fix: refine interactive Miku terminal

Author: sionic-khope

AGENTS.md

@@ -0,0 +1,26 @@
+# MikuCode Engineering Rules
+
+## Required checks before every push
+
+Run the CI-equivalent commands and do not push a failing result. First ensure
+the active developer directory is a full Xcode installation; this workstation's
+default Command Line Tools directory cannot compile XCTest targets:
+
+```sh
+export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
+swift build -Xswiftc -warnings-as-errors
+swift test -Xswiftc -warnings-as-errors
+```
+
+The GitHub workflow currently selects Xcode 16.4. Treat Swift concurrency
+diagnostics from that toolchain as release-blocking: shared AppKit objects must
+be isolated to `@MainActor` or created on demand, never stored in unisolated
+static mutable state.
+
+For changes to the companion or terminal presentation, also launch
+`swift run MikuCodeApp` and manually verify idle movement, hover focus, open,
+terminal input, and close-to-idle. After a push, inspect the matching GitHub
+Actions run before reporting CI as healthy.
+
+Keep the app as one panel and one local PTY terminal. Do not add a preview
+desktop window, external-terminal launch path, or permanent demo controls.

DESIGN.md

@@ -11,24 +11,27 @@ space.
 | --- | --- | --- |
 | `idle` | Transparent panel; a smooth 2D virtual-streamer Miku walks slowly along the lower-right wallpaper area and reveals a terminal bubble on hover | Stopped |
 | `opening` | Same panel transitions to the active composition | Stopped |
-| `terminal` | Screen-sized, borderless, normal-level panel with a large speech-bubble PTY terminal and Miku right rail | Running and directly focused |
+| `terminal` | Screen-sized, borderless, normal-level panel with a large speech-bubble PTY terminal, compact MikuCode header, and Miku right rail | Running and directly focused |
 | `closing` | Active composition leaves the same panel | Stopped, drained, and persisted |
 
 Repeated or out-of-order events are no-ops. Command-W and panel-close requests
 use the close transition and return to `idle`.
 
 ## Composition
 
-- The active terminal occupies 74% of display width and 84% of display height;
+- The active terminal occupies 77% of display width and 84% of display height;
   the Miku rail is right-aligned and occupies the remaining region.
 - The idle panel is fully transparent, shadowless, and passes pointer events
-  through outside its documented 200 × 340 point lower-right Miku region.
+  through outside its documented 220 × 360 point lower-right Miku region.
 - Hover shifts Miku's focus toward the user and reveals a small speech-bubble
   terminal affordance. Her artwork switches to a direct, attentive gaze.
   Clicking either Miku herself or that bubble begins the terminal transition.
-- The terminal is the only visible active control. It has no title bar,
-  traffic lights, toolbar, status chips, text fields, paging/search controls,
-  or permanent Clear, Interrupt, or Send buttons.
+- In terminal state, the bubble header contains `miku-code` and one close
+  control. Clicking it or expanded Miku closes the terminal and returns to idle.
+- The terminal header is an agent-workspace cue, not a toolbar: it contains the
+  app name, the actual PTY state, and one close control. There are no traffic
+  lights, provider selectors, text fields, paging/search controls, or permanent
+  Clear, Interrupt, or Send buttons.
 - Terminal output remains selectable through AppKit accessibility text even
   when Metal renders the visible glyphs.
 
@@ -48,10 +51,12 @@ on terminal exit.
 ## Visual tokens
 
 The visual system uses a 4-point spacing base. Idle is transparent; active
-surfaces use a blue-black two-stop bubble, a translucent rim, a restrained
-teal shadow, and white terminal text. The app icon is a separate
+surfaces use a graphite two-stop bubble, a translucent rim, a restrained teal
+shadow, and white terminal text. The header uses compact rounded app type with
+monospaced `agent terminal` and PTY state labels, making the surface read as a
+coding-agent workspace rather than a generic terminal emulator. The app icon is a separate
 terminal-and-Miku asset; the desktop companion contains only the 2D Miku
 character. Idle artwork crossfades between left and right walking frames while
-moving horizontally; hover and terminal states use the focus frame. ANSI colors
+moving horizontally above a subtle teal ground shadow; hover and terminal states use the focus frame. ANSI colors
 are confined to terminal output. Reduce Motion removes companion float and
 state transitions while preserving state changes.

README.md

@@ -8,9 +8,12 @@ fills the display with a speech-bubble terminal and Miku on the right.
 ## Behavior
 
 - The PTY output view is selectable and receives keyboard input directly.
-- Hovering Miku shifts her attention toward the user and reveals the only idle
-  control: a small terminal speech bubble. Selecting that bubble opens the
-  full terminal in the same panel.
+- Miku walks slowly across her idle area. Hovering shifts her attention toward
+  the user and reveals a small terminal speech bubble; selecting either Miku
+  or that bubble opens the full terminal in the same panel.
+- The expanded terminal uses the default MikuCode theme with a compact
+  `miku-code` header and close button. Selecting the expanded Miku or the
+  close button returns to idle.
 - Printable keys, control sequences, paste, resize, paging, find, clear, and
   interrupt use terminal keyboard or native text-view actions; there are no
   permanent toolbars, text fields, buttons, status chips, or demo controls.

Sources/MikuCodeApp/AppPresentation.swift

@@ -145,7 +145,7 @@ enum PresentationLayout {
         let width = max(1, size.width)
         let height = max(1, size.height)
         let activeInset = min(32, max(16, width * 0.03))
-        let terminalSize = CGSize(width: width * 0.74, height: height * 0.84)
+        let terminalSize = CGSize(width: width * 0.77, height: height * 0.84)
         let terminalFrame = CGRect(
             x: activeInset,
             y: (height - terminalSize.height) / 2,
@@ -161,7 +161,7 @@ enum PresentationLayout {
             width: max(1, mikuMaxX - mikuMinX),
             height: mikuHeight
         )
-        let idleSize = CGSize(width: 200, height: 340)
+        let idleSize = CGSize(width: 220, height: 360)
         let idleEntryFrame = CGRect(
             x: width - MikuVisualTokens.space6 - idleSize.width,
             y: height - MikuVisualTokens.space6 - idleSize.height,
@@ -187,13 +187,18 @@ enum MikuVisualTokens {
     static let openingDuration = 0.24
     static let closingDuration = 0.18
     static let idleFloatDuration = 1.8
+    static let idleWalkDuration = 4.6
+    static let idleTurnDuration = 0.38
     static let pressDuration = 0.12
 
-    static let activeVeil = Color.black.opacity(0.18)
-    static let bubbleTop = Color(red: 0.035, green: 0.070, blue: 0.105).opacity(0.94)
-    static let bubbleBottom = Color(red: 0.010, green: 0.022, blue: 0.034).opacity(0.97)
-    static let bubbleRim = Color.white.opacity(0.14)
-    static let terminalText = Color.white.opacity(0.84)
+    static let activeVeil = Color.black.opacity(0.22)
+    static let bubbleTop = Color(red: 0.060, green: 0.067, blue: 0.075).opacity(0.98)
+    static let bubbleBottom = Color(red: 0.025, green: 0.030, blue: 0.035).opacity(0.99)
+    static let bubbleRim = Color.white.opacity(0.11)
+    static let terminalText = Color.white.opacity(0.88)
+    static let agentMeta = Color.white.opacity(0.46)
+    static let agentHeader = Color.white.opacity(0.035)
+    static let agentControl = Color.white.opacity(0.075)
     static let mikuTeal = Color(red: 0.224, green: 0.851, blue: 0.812)
     static let mikuTealDeep = Color(red: 0.067, green: 0.498, blue: 0.514)
     static let mikuNeutral = Color.white.opacity(0.82)

Sources/MikuCodeApp/MikuCodeApp.swift

@@ -44,6 +44,7 @@ final class MikuApplicationDelegate: NSObject, NSApplicationDelegate {
     }
 }
 
+@MainActor
 struct MikuRootView: View {
     @ObservedObject var presentation: AppPresentationStore
     @ObservedObject var terminalSession: TerminalSessionModel
@@ -100,6 +101,7 @@ struct MikuRootView: View {
             TerminalPanel(
                 session: terminalSession,
                 focusRequestID: presentation.focusRequestID,
+                onClose: onClose,
                 rendererPolicy: terminalRendererPolicy
             )
             .frame(
@@ -110,10 +112,14 @@ struct MikuRootView: View {
                 x: metrics.terminalFrame.midX,
                 y: metrics.terminalFrame.midY
             )
-            MikuCompanion(scale: .active)
+            Button(action: onClose) {
+                MikuCompanion(scale: .active)
+            }
+            .buttonStyle(.plain)
                 .frame(width: metrics.mikuFrame.width, height: metrics.mikuFrame.height)
                 .position(x: metrics.mikuFrame.midX, y: metrics.mikuFrame.midY)
-                .accessibilityHidden(true)
+                .accessibilityLabel("Close terminal")
+                .accessibilityHint("Return MikuCode to the desktop")
         }
         .accessibilityElement(children: .contain)
         .accessibilityLabel("MikuCode terminal")

Sources/MikuCodeApp/MikuCompanion.swift

@@ -1,6 +1,8 @@
 import AppKit
+import Combine
 import SwiftUI
 
+@MainActor
 struct MikuEntryButton: View {
     @State private var isHovering = false
     let action: () -> Void
@@ -51,6 +53,7 @@ struct MikuEntryButton: View {
     }
 }
 
+@MainActor
 struct MikuCompanion: View {
     enum Scale {
         case idle
@@ -69,22 +72,45 @@ struct MikuCompanion: View {
     }
 
     var body: some View {
-        Image(nsImage: currentArtwork)
-            .resizable()
-            .interpolation(.high)
-            .scaledToFit()
-            .scaleEffect(looksAtUser ? 1.035 : 1)
-            .saturation(looksAtUser ? 1.08 : 0.98)
-            .brightness(looksAtUser ? 0.025 : 0)
-            .offset(x: walkingOffset, y: floatingOffset)
-            .shadow(
-                color: MikuVisualTokens.mikuTeal.opacity(scale == .idle ? 0.14 : 0.10),
-                radius: scale == .idle ? 12 : 18
-            )
-            .animation(.easeInOut(duration: 0.22), value: looksAtUser)
-            .animation(.easeInOut(duration: 0.22), value: isWalkingRight)
-            .onAppear { updateMotion() }
-            .onChange(of: reduceMotion) { _, _ in updateMotion() }
+        ZStack(alignment: .bottom) {
+            if scale == .idle {
+                Ellipse()
+                    .fill(MikuVisualTokens.mikuTeal.opacity(0.20))
+                    .frame(width: 108, height: 14)
+                    .blur(radius: 7)
+                    .offset(y: -14)
+                    .accessibilityHidden(true)
+            }
+            Image(nsImage: currentArtwork)
+                .resizable()
+                .interpolation(.high)
+                .scaledToFit()
+                .scaleEffect(scale == .idle ? 1.06 : 1)
+                .scaleEffect(looksAtUser ? 1.035 : 1)
+                .saturation(looksAtUser ? 1.08 : 0.98)
+                .brightness(looksAtUser ? 0.025 : 0)
+                .offset(x: walkingOffset, y: floatingOffset)
+                .shadow(
+                    color: MikuVisualTokens.mikuTeal.opacity(scale == .idle ? 0.14 : 0.10),
+                    radius: scale == .idle ? 12 : 18
+                )
+                .animation(.easeInOut(duration: 0.22), value: looksAtUser)
+                .animation(.easeInOut(duration: 0.22), value: isWalkingRight)
+                .onAppear { updateMotion() }
+                .onChange(of: reduceMotion) { _, _ in updateMotion() }
+                .onReceive(
+                    Timer.publish(
+                        every: MikuVisualTokens.idleWalkDuration,
+                        on: .main,
+                        in: .common
+                    ).autoconnect()
+                ) { _ in
+                    guard scale == .idle, !looksAtUser, !reduceMotion else { return }
+                    withAnimation(.easeInOut(duration: MikuVisualTokens.idleTurnDuration)) {
+                        isWalkingRight.toggle()
+                    }
+                }
+        }
     }
 
     private var currentArtwork: NSImage {
@@ -96,7 +122,7 @@ struct MikuCompanion: View {
 
     private var walkingOffset: CGFloat {
         guard scale == .idle, !looksAtUser, !reduceMotion else { return 0 }
-        return isWalkingRight ? 16 : -16
+        return isWalkingRight ? 30 : -30
     }
 
     private var floatingOffset: CGFloat {
@@ -111,8 +137,7 @@ struct MikuCompanion: View {
             return
         }
         withAnimation(
-            .easeInOut(duration: 4.8)
-                .repeatForever(autoreverses: true)
+            .easeInOut(duration: MikuVisualTokens.idleTurnDuration)
         ) {
             isWalkingRight = true
         }
@@ -125,6 +150,7 @@ struct MikuCompanion: View {
     }
 }
 
+@MainActor
 enum MikuArtwork {
     static let appIcon = image(named: "MikuCodeIcon")
     static let walkLeft = image(named: "MikuWalkLeft")

Sources/MikuCodeApp/MikuPanelCoordinator.swift

@@ -53,6 +53,8 @@ final class MikuPanelCoordinator: NSObject, NSWindowDelegate {
     func completeOpening() {
         guard presentation.finishOpening() else { return }
         configurePanel(for: .terminal)
+        guard ordersFront else { return }
+        panel.makeKeyAndOrderFront(nil)
     }
 
     func requestClose() {

Sources/MikuCodeApp/TerminalOutputTextView.swift

@@ -48,6 +48,11 @@ final class TerminalOutputTextView: NSTextView {
         setSelectedRange(NSRange(location: safeLocation, length: safeLength))
     }
 
+    override func mouseDown(with event: NSEvent) {
+        window?.makeFirstResponder(self)
+        super.mouseDown(with: event)
+    }
+
     override func keyDown(with event: NSEvent) {
         if event.keyCode == 116 {
             onPageUp?()