Skip to content

DESIGN.md

Latest commit

 

History

History
90 lines (78 loc) · 5.44 KB

DESIGN.md

File metadata and controls

90 lines (78 loc) · 5.44 KB
Raw

MikuCode Design

MikuCode is one persistent AppKit panel with two presentation states: a clear, clickable idle overlay and a focused terminal surface. The panel is never replaced, and the app never creates a second window or a system fullscreen space.

The distributable surface is MikuCode.app, launched directly from Finder or the Dock. Development swift run output is not part of the product UI.

State contract

State Surface PTY
idle Transparent panel; a centered front-facing chibi Miku stays still, changes to attentive eye contact on hover, and reveals a terminal bubble Stopped
opening Same panel transitions to the active composition Stopped
terminal Screen-sized, borderless, normal-level panel with a large dark sky-blue speech-bubble coding-agent workspace, compact MikuCode header, and Miku right rail The coordinator-owned local PTY runs whether its embedded view is shown or hidden
closing Active composition leaves the same panel The local PTY stops, drains, and persists

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 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 220 × 360 point lower-right Miku region.
  • Idle Miku normally sits at the desktop layer so ordinary windows can cover her. Selecting MikuCode in the Dock temporarily promotes that companion above open windows; it returns to the desktop layer when the app loses focus.
  • Hover crossfades Miku's idle art into an attentive front-facing gaze and reveals a small speech-bubble terminal affordance. The companion never walks, slides, or bobs in idle; only the intentional gaze state changes. Clicking either Miku herself or that bubble begins the terminal transition.
  • In terminal state, the bubble opens as a coding-agent workspace: a compact MikuCode logo mark gives way to prompt history, a provider/approval composer, and a terminal toggle. Codex and Claude support Plan, Accept, and Auto; the workspace only records a request after its token-matched PTY delivery. The terminal toggle reveals that same local PTY inside the bubble—never a second window. Hovering expanded Miku reveals a close marker. Clicking either close target stops the terminal and returns the same running app to its small idle companion at the floating layer; it only returns behind other apps after the app itself loses focus, and never quits MikuCode.
  • The workspace header is an agent-workspace cue, not a toolbar: it contains the logo mark, local-shell status, an embedded-terminal toggle, and one close control. The composer is a measured bottom dock: provider and approval chips remain distinct from a full-width prompt field and labelled send action at all supported bubble sizes. Codex uses a cool gray signal, Claude orange, and Plan/Accept/Auto each retain distinct semantic colors. Command-F opens the only transient terminal text field: a compact in-bubble finder. Command-G and Shift-Command-G navigate its case-insensitive matches across output pages; Escape restores terminal focus and removes the finder.
  • The speech-bubble tail owns a reserved header inset; terminal and close controls never sit beneath it, and the focused-Miku close target begins after a fixed gap beyond the workspace frame. No interactive target is allowed to overlap another.
  • The speech bubble resizes directly from its edges and corners. Its frame stays inside a 24-point display inset and preserves a minimum right-side Miku rail; native directional cursors expose the otherwise unobtrusive resize targets.
  • Terminal output remains selectable through AppKit accessibility text even when Metal renders the visible glyphs.

Input and lifecycle

The app activates and makes its own panel key before requesting first-responder focus for the terminal output view. Printable keys, control keys, navigation, paste, and terminal keyboard actions write only to the owned PTY master. No external app launch, global keyboard dispatch, synthetic key posting, or global event monitor is used.

PTY output is read without blocking, input is bounded and drained through a write source, resize is sent through TIOCSWINSZ, and shutdown sends SIGHUP with a bounded SIGKILL fallback. The coordinator-owned PTY and its bounded snapshot persist on close and restore on the next launch.

Visual tokens

The visual system uses a 4-point spacing base. Idle is transparent; active surfaces use flat dark sky-blue tones, a translucent cyan rim with a slow opacity pulse, a restrained teal shadow, and white terminal text. The header uses modern SF app type with small monospaced agent 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 stays centered and still above a subtle teal ground shadow. Its only idle motion is an intentional crossfade to an attentive gaze on hover; opening, active terminal, and closing states use the focus frame as the deliberate zoom transition. ANSI colors are confined to terminal output. Reduce Motion removes companion float and state transitions while preserving state changes.