From 71a868be17bb8c19e90501c564b92dceab25c3ec Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Sat, 9 May 2026 17:02:15 -0700
Subject: [PATCH 01/12] Initial unimplemented mobile UI spec.

---
 docs/specs/mobile-ui.md | 503 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 503 insertions(+)
 create mode 100644 docs/specs/mobile-ui.md

diff --git a/docs/specs/mobile-ui.md b/docs/specs/mobile-ui.md
new file mode 100644
index 0000000..91c4a84
--- /dev/null
+++ b/docs/specs/mobile-ui.md
@@ -0,0 +1,503 @@
+# Mobile Terminal Website Prototype Spec
+
+## 1. Overview
+
+This document specifies a greenfield prototype for a mobile-first terminal UI.
+
+The prototype tests one core idea:
+
+```text
+Native phone keyboard for text + simple terminal controls for missing keys.
+```
+
+The app should feel like a lightweight mobile terminal playground. It does not need remote sessions, SSH, user accounts, or production infrastructure. The first version should use a local playground PTY, fake shell, in-browser terminal demo, or command simulator that is realistic enough to test the mobile UI.
+
+The main interface has a terminal viewport and a bottom navigation row:
+
+```text
+Recent | Type | Draft | Keys
+```
+
+Only the most important sections need complete behavior in v0:
+
+* **Type**: implemented.
+* **Keys**: implemented.
+* **Recent**: opens a TODO pane.
+* **Draft**: opens a TODO pane.
+
+## 2. Prototype goals
+
+### 2.1 Primary goals
+
+* Test mobile terminal text entry using the native phone keyboard.
+* Test whether simple on-screen terminal controls make missing keys usable on a phone.
+* Keep the terminal viewport usable when the mobile keyboard is visible.
+* Provide enough terminal behavior to evaluate typing, Enter, Backspace, arrows, Escape, Tab, and Ctrl+C.
+* Keep the implementation small and easy to iterate on.
+
+### 2.2 Non-goals
+
+The prototype does not need:
+
+* Remote shell support.
+* SSH support.
+* WebSocket transport.
+* User accounts.
+* Session persistence.
+* Multiple terminal sessions.
+* Command history storage.
+* Snippet management.
+* A real draft/scratchpad workflow.
+* Terminal mouse mode.
+* Advanced gestures.
+* Production security hardening.
+* Full accessibility implementation.
+
+## 3. Core layout
+
+## 3.1 Default portrait layout
+
+```text
+┌─────────────────────────┐
+│ Terminal playground      │
+│                         │
+│                         │
+├─────────────────────────┤
+│ Active pane              │
+├─────────────────────────┤
+│ Recent | Type | Draft | Keys
+└─────────────────────────┘
+```
+
+The active pane changes when the user taps a bottom navigation item.
+
+## 3.2 Type mode layout
+
+Type is the default active section.
+
+```text
+┌─────────────────────────┐
+│ Terminal playground      │
+│                         │
+├─────────────────────────┤
+│ Esc Tab Ctrl+C ← ↓ ↑ →   │
+├─────────────────────────┤
+│ Recent | Type | Draft | Keys
+├─────────────────────────┤
+│ native phone keyboard    │
+└─────────────────────────┘
+```
+
+When the native keyboard is open, the terminal viewport should resize to remain visible.
+
+## 3.3 Keys mode layout
+
+Keys mode shows the same important controls in a larger layout.
+
+```text
+┌─────────────────────────┐
+│ Terminal playground      │
+│                         │
+├─────────────────────────┤
+│ Esc     Tab     Ctrl+C   │
+│ ←       ↓       ↑       →│
+├─────────────────────────┤
+│ Recent | Type | Draft | Keys
+└─────────────────────────┘
+```
+
+Keys mode is useful when the user needs more reliable taps for arrow keys and Ctrl+C.
+
+## 3.4 TODO pane layout
+
+Recent and Draft should open simple placeholder panes.
+
+```text
+┌─────────────────────────┐
+│ Terminal playground      │
+│                         │
+├─────────────────────────┤
+│ TODO: Recent             │
+├─────────────────────────┤
+│ Recent | Type | Draft | Keys
+└─────────────────────────┘
+```
+
+```text
+┌─────────────────────────┐
+│ Terminal playground      │
+│                         │
+├─────────────────────────┤
+│ TODO: Draft              │
+├─────────────────────────┤
+│ Recent | Type | Draft | Keys
+└─────────────────────────┘
+```
+
+The TODO panes should make the app structure visible without implementing those workflows.
+
+## 4. Bottom navigation
+
+The bottom navigation row is always present unless the native keyboard or viewport constraints make that impossible.
+
+```text
+Recent | Type | Draft | Keys
+```
+
+### 4.1 Navigation behavior
+
+| Item   | v0 behavior                                |
+| ------ | ------------------------------------------ |
+| Recent | Opens TODO pane                            |
+| Type   | Opens Type pane and focuses terminal input |
+| Draft  | Opens TODO pane                            |
+| Keys   | Opens large Keys pane                      |
+
+### 4.2 Active state
+
+The active item should be visually obvious.
+
+Recommended active states:
+
+* Highlight the selected label.
+* Use a top border or pill background.
+* Keep the active pane directly above the nav row.
+
+### 4.3 Default state
+
+The app should start in **Type** mode.
+
+## 5. Terminal playground
+
+The terminal area is the main testing surface.
+
+### 5.1 Requirements
+
+The terminal playground should:
+
+* Display terminal-like output.
+* Accept typed input from the native mobile keyboard.
+* Show a cursor.
+* Support Enter.
+* Support Backspace.
+* Respond visibly to arrow keys.
+* Respond visibly to Escape, Tab, and Ctrl+C.
+* Scroll when output exceeds the visible area.
+* Resize when the mobile keyboard appears or disappears.
+
+### 5.2 Implementation options
+
+Use the simplest implementation that gives a realistic enough interaction test.
+
+Acceptable options:
+
+* xterm.js connected to a local playground process.
+* xterm.js with an in-browser command simulator.
+* A custom terminal-like component if true terminal emulation is not needed yet.
+
+Prefer xterm.js if the prototype should test realistic cursor movement, ANSI behavior, and terminal rendering.
+
+### 5.3 Minimal fake shell behavior
+
+A fake shell is acceptable for v0.
+
+Minimum useful behavior:
+
+* Echo typed characters.
+* Maintain a command line buffer.
+* Enter submits the current command.
+* Backspace edits the current command.
+* Arrow keys produce visible behavior.
+* Ctrl+C clears or interrupts the current command.
+* Escape and Tab produce visible behavior.
+
+Example commands:
+
+```text
+help
+clear
+echo hello
+```
+
+The shell only needs enough behavior to test the mobile controls.
+
+## 6. Type pane
+
+Type is the primary implemented pane.
+
+### 6.1 Purpose
+
+Type mode lets the user enter normal text through the native phone keyboard while keeping a compact terminal control row available.
+
+### 6.2 Layout
+
+```text
+Esc Tab Ctrl+C ← ↓ ↑ →
+```
+
+### 6.3 Behavior
+
+When the user opens Type mode:
+
+* Focus the terminal input.
+* Open the native phone keyboard where browser policy allows.
+* Show the compact terminal control row.
+* Keep the terminal viewport visible above the controls and keyboard.
+
+### 6.4 Hidden input
+
+Use a hidden or visually minimal input configured for terminal-style typing:
+
+```html
+<textarea
+  autocapitalize="off"
+  autocomplete="off"
+  autocorrect="off"
+  spellcheck="false"
+  inputmode="text"
+  enterkeyhint="enter"
+></textarea>
+```
+
+### 6.5 Text input behavior
+
+Required behavior:
+
+* Normal characters are sent to the terminal playground.
+* Enter sends terminal Enter.
+* Backspace works.
+* Autocorrect and autocapitalization are disabled where possible.
+* Input should support mobile keyboard behavior and IME composition.
+* The app should not depend only on `keydown` for text input.
+
+## 7. Keys pane
+
+Keys is the second implemented pane.
+
+### 7.1 Purpose
+
+Keys mode provides larger tap targets for the terminal controls that are most important on mobile.
+
+### 7.2 Layout
+
+```text
+┌───────────────────────┐
+│ Esc   Tab   Ctrl+C     │
+│ ←     ↓     ↑     →    │
+└───────────────────────┘
+```
+
+### 7.3 Controls
+
+| Button | Behavior         |
+| ------ | ---------------- |
+| Esc    | Send Escape      |
+| Tab    | Send Tab         |
+| Ctrl+C | Send interrupt   |
+| ←      | Send left arrow  |
+| ↓      | Send down arrow  |
+| ↑      | Send up arrow    |
+| →      | Send right arrow |
+
+### 7.4 Interaction rules
+
+* Tapping a key sends exactly one action.
+* The same key mappings should be used in Type mode and Keys mode.
+* Keys mode should not add extra controls in v0.
+* Long-press repeat is not required for v0.
+* Modifier-lock behavior is not required for v0.
+
+## 8. Recent TODO pane
+
+### 8.1 Purpose
+
+Recent is visible in the navigation so the overall app structure can be tested, but it does not implement command history in v0.
+
+### 8.2 Layout
+
+```text
+TODO: Recent commands
+
+This pane will eventually show recently used commands.
+```
+
+### 8.3 Behavior
+
+* Tapping Recent opens the TODO pane.
+* The terminal remains visible above the pane.
+* No command list is required.
+* No storage is required.
+
+## 9. Draft TODO pane
+
+### 9.1 Purpose
+
+Draft is visible in the navigation so the overall app structure can be tested, but it does not implement scratchpad or dual-pane editing in v0.
+
+### 9.2 Layout
+
+```text
+TODO: Draft
+
+This pane will eventually support composing text before sending it to the terminal.
+```
+
+### 9.3 Behavior
+
+* Tapping Draft opens the TODO pane.
+* The terminal remains visible above the pane.
+* No editable scratchpad is required.
+* No copy/paste workflow is required.
+
+## 10. Key sequence mapping
+
+Use these mappings for both Type mode and Keys mode.
+
+| UI action   | Sequence       |
+| ----------- | -------------- |
+| Ctrl+C      | `\x03`         |
+| Esc         | `\x1B`         |
+| Tab         | `\x09`         |
+| Enter       | `\r`           |
+| Backspace   | Usually `\x7F` |
+| Arrow Up    | `\x1B[A`       |
+| Arrow Down  | `\x1B[B`       |
+| Arrow Right | `\x1B[C`       |
+| Arrow Left  | `\x1B[D`       |
+
+If the playground terminal uses a higher-level input API instead of raw terminal sequences, map these actions to the equivalent local action.
+
+## 11. Keyboard visibility and layout
+
+Keyboard handling should be simple and pragmatic.
+
+The prototype should resize the terminal area when the phone keyboard appears. Use the simplest reliable approach available:
+
+1. Use `window.visualViewport` resize events if available.
+2. Fall back to normal viewport sizing.
+3. Avoid complex keyboard detection logic unless the layout is broken.
+
+Minimal approach:
+
+```js
+function updateLayoutForKeyboard() {
+  const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
+  document.documentElement.style.setProperty(
+    "--visible-height",
+    `${viewportHeight}px`
+  );
+}
+
+window.visualViewport?.addEventListener("resize", updateLayoutForKeyboard);
+window.visualViewport?.addEventListener("scroll", updateLayoutForKeyboard);
+window.addEventListener("resize", updateLayoutForKeyboard);
+updateLayoutForKeyboard();
+```
+
+The prototype does not need to perfectly detect whether the keyboard is present. It only needs to keep the terminal, active pane, and nav row usable.
+
+## 12. Touch interactions
+
+Keep touch behavior minimal.
+
+Required interactions:
+
+* Tap terminal to focus typing.
+* Tap Type to focus typing.
+* Tap control buttons.
+* Tap bottom navigation items.
+* Scroll terminal output.
+
+Not required for v0:
+
+* Swipe navigation.
+* Long-press arrow repeat.
+* Trackpad mode.
+* Two-finger gestures.
+* Terminal mouse mode.
+* Custom text selection behavior.
+
+## 13. Copy and paste
+
+Keep copy and paste minimal.
+
+Prototype behavior:
+
+* Let users paste through the native browser/OS paste flow where possible.
+* Let terminal output selection rely on default browser behavior where possible.
+* No custom clipboard manager is required.
+* No multi-line paste review is required.
+
+## 14. Recommended v0 scope
+
+Build exactly this:
+
+* One terminal playground screen.
+* Bottom navigation row:
+
+```text
+Recent | Type | Draft | Keys
+```
+
+* Type pane with compact controls:
+
+```text
+Esc Tab Ctrl+C ← ↓ ↑ →
+```
+
+* Keys pane with larger controls:
+
+```text
+Esc   Tab   Ctrl+C
+←     ↓     ↑     →
+```
+
+* Recent TODO pane.
+* Draft TODO pane.
+* Native mobile keyboard input.
+* Basic viewport resizing when the keyboard opens.
+* Simple local playground terminal behavior.
+
+## 15. Prototype success criteria
+
+The prototype should answer these questions:
+
+1. Is the terminal viewport usable when the mobile keyboard is open?
+2. Is the compact Type control row easy to reach?
+3. Is the larger Keys pane necessary or useful?
+4. Are arrow keys usable enough for command history and cursor movement?
+5. Is Ctrl+C discoverable and easy to trigger?
+6. Does the native keyboard feel acceptable for terminal text entry?
+7. Does the four-item navigation row make sense, even with Recent and Draft as placeholders?
+8. Is the UI too cramped in portrait orientation?
+
+## 16. Future work
+
+Potential later additions:
+
+* Real recent commands.
+* Draft scratchpad.
+* Dual-pane copy/paste.
+* Pinned snippets.
+* Ctrl+D and Ctrl+Z.
+* Alt and modifier behavior.
+* Home, End, PgUp, PgDn.
+* Long-press key repeat.
+* Gesture navigation.
+* Terminal mouse mode.
+* Remote backend PTY.
+* SSH sessions.
+* User accounts.
+* Session persistence.
+* Multi-session support.
+* Production security model.
+
+## 17. Product principle
+
+The v0 prototype should stay focused:
+
+```text
+Type and Keys are real.
+Recent and Draft establish the shape of the app.
+Everything else waits.
+```

From 38962576ac6f873afb6b09fde7b2776ad4bfc658 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Sat, 9 May 2026 17:05:11 -0700
Subject: [PATCH 02/12] Rename Roam marketing to Tether

---
 website/src/pages/Home.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/src/pages/Home.tsx b/website/src/pages/Home.tsx
index f21c882..84471f2 100644
--- a/website/src/pages/Home.tsx
+++ b/website/src/pages/Home.tsx
@@ -321,7 +321,7 @@ function NotifySignupForm() {
           type="submit"
           className="min-h-12 inline-flex items-center justify-center rounded-md border border-[var(--color-caramel)] bg-[var(--color-caramel)]/15 px-6 py-3 text-base font-display text-[var(--color-caramel)] transition hover:bg-[var(--color-caramel)]/25 sm:w-auto"
         >
-          Notify me when Roam ships
+          Notify me when Tether ships
         </button>
       </div>
       {message && (
@@ -965,7 +965,7 @@ function Home() {
               Walk away. Keep going.
             </h2>
             <p className="mb-4 text-lg leading-relaxed opacity-70">
-              Coming next: <span className="text-[var(--color-caramel)]">Roam</span>. Pair a
+              Coming next: <span className="text-[var(--color-caramel)]">Tether</span>. Pair a
               terminal session to your phone over WebRTC and take a stroll, the MouseTerm alert
               system will buzz you if there's anything to do. A hosted auto-pairing service comes
               later — just leave and keep working, no "I'm walking away" dance.

From 0f676da840e2cb8c4c545e8573d8e5360a0bdf6f Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Sat, 9 May 2026 18:15:08 -0700
Subject: [PATCH 03/12] Add Tether mobile prototype page

---
 docs/specs/layout.md                         |   8 +-
 lib/src/components/MobileTerminalUi.tsx      | 355 +++++++++++++++++++
 lib/src/components/Wall.tsx                  |  14 +-
 lib/src/stories/MobileTerminalUi.stories.tsx | 111 ++++++
 website/src/App.tsx                          |   4 +
 website/src/index.css                        |  16 +
 website/src/pages/Tether.tsx                 | 209 +++++++++++
 7 files changed, 709 insertions(+), 8 deletions(-)
 create mode 100644 lib/src/components/MobileTerminalUi.tsx
 create mode 100644 lib/src/stories/MobileTerminalUi.stories.tsx
 create mode 100644 website/src/pages/Tether.tsx

diff --git a/docs/specs/layout.md b/docs/specs/layout.md
index f9c0697..8e75670 100644
--- a/docs/specs/layout.md
+++ b/docs/specs/layout.md
@@ -18,7 +18,7 @@ Transitioning between Pane and Door does not alter the Session in any way. Minim
 There are two areas:
 
 - **Content** — tiling layout containing Panes, powered by dockview
-- **Baseboard** — always-visible bottom strip containing Doors and shortcut hints
+- **Baseboard** — bottom strip containing Doors and shortcut hints. It is visible in the main shell; tightly constrained embedders may suppress it with `Wall showBaseboard={false}` when they do not expose door/minimize workflows.
 
 The user can navigate between all elements using the mouse, or by entering `command` mode and using the keyboard.
 
@@ -32,7 +32,7 @@ Wall
 │       │   │       ├── TerminalPanel → TerminalPane → xterm.js
 │       │   │       └── TerminalPaneHeader (tab component, drag handle)
 │       │   └── WorkspaceSelectionOverlay (fixed positioned, pointer-events: none)
-│       ├── Baseboard (always-visible bottom strip, shortcut hints when empty)
+│       ├── Baseboard (bottom strip, shortcut hints when empty; optional for constrained embedders)
 │       │   └── Door components (one per minimized session)
 │       └── KillConfirmOverlay (conditional)
 ```
@@ -104,7 +104,9 @@ The header adapts to available width via ResizeObserver in three tiers:
 
 ## Baseboard
 
-Below the content area is the baseboard (`h-7`, 28px). It is always visible and has no top divider. The dockview area ends 2px above it, leaving a narrow theme-colored gap that keeps rounded pane corners distinct from the baseboard. Its horizontal padding matches the Dockview wrapper's 6px inset, so doors align with the panes above. When empty, it shows keyboard shortcut hints when there are no doors and the container is wider than 350px (currently: `LCmd → RCmd to enter command mode`).
+Below the content area is the baseboard (`h-7`, 28px). It is visible by default and has no top divider. The dockview area ends 2px above it, leaving a narrow theme-colored gap that keeps rounded pane corners distinct from the baseboard. Its horizontal padding matches the Dockview wrapper's 6px inset, so doors align with the panes above. When empty, it shows keyboard shortcut hints when there are no doors and the container is wider than 350px (currently: `LCmd → RCmd to enter command mode`).
+
+`Wall` accepts `showBaseboard={false}` for constrained embedders such as the website mobile Tether prototype, where a separate bottom navigation owns the area below the terminal and door workflows are outside the prototype scope. The main app shell keeps the default `showBaseboard=true`.
 
 When a session is minimized, it becomes a **door** on the baseboard. The door displays the same derived terminal label as the pane header, a TODO badge (if set), and an alert bell icon with activity dot. It uses the bottom edge of the window as its bottom border, with left, top, and right borders using the shared terminal top radius from `lib/src/components/design.tsx` — resembling a mouse hole and matching pane rounding. Door dimensions: `min-w-[68px] max-w-[220px] h-6`.
 
diff --git a/lib/src/components/MobileTerminalUi.tsx b/lib/src/components/MobileTerminalUi.tsx
new file mode 100644
index 0000000..4f238f1
--- /dev/null
+++ b/lib/src/components/MobileTerminalUi.tsx
@@ -0,0 +1,355 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent,
+  type ReactNode,
+} from 'react';
+import { clsx } from 'clsx';
+
+export type MobileTerminalSection = 'recent' | 'type' | 'draft' | 'keys';
+
+export const MOBILE_TERMINAL_KEY_SEQUENCES = {
+  ctrlC: '\x03',
+  esc: '\x1b',
+  tab: '\x09',
+  enter: '\r',
+  backspace: '\x7f',
+  up: '\x1b[A',
+  down: '\x1b[B',
+  right: '\x1b[C',
+  left: '\x1b[D',
+} as const;
+
+interface TerminalKey {
+  id: keyof typeof MOBILE_TERMINAL_KEY_SEQUENCES;
+  label: string;
+  title: string;
+}
+
+const TERMINAL_KEYS: TerminalKey[] = [
+  { id: 'esc', label: 'Esc', title: 'Escape' },
+  { id: 'tab', label: 'Tab', title: 'Tab' },
+  { id: 'ctrlC', label: 'Ctrl+C', title: 'Interrupt' },
+  { id: 'left', label: '\u2190', title: 'Left arrow' },
+  { id: 'down', label: '\u2193', title: 'Down arrow' },
+  { id: 'up', label: '\u2191', title: 'Up arrow' },
+  { id: 'right', label: '\u2192', title: 'Right arrow' },
+];
+
+const NAV_ITEMS: { id: MobileTerminalSection; label: string }[] = [
+  { id: 'recent', label: 'Recent' },
+  { id: 'type', label: 'Type' },
+  { id: 'draft', label: 'Draft' },
+  { id: 'keys', label: 'Keys' },
+];
+
+type MobileTerminalStyle = CSSProperties & {
+  '--mobile-terminal-visible-height'?: string;
+};
+
+export interface MobileTerminalUiProps {
+  terminal: ReactNode;
+  activeSection?: MobileTerminalSection;
+  defaultSection?: MobileTerminalSection;
+  onSectionChange?: (section: MobileTerminalSection) => void;
+  onSendInput?: (data: string) => void;
+  onFocusInput?: () => void;
+  interactive?: boolean;
+  fillViewport?: boolean;
+  className?: string;
+  terminalClassName?: string;
+  style?: CSSProperties;
+}
+
+function useVisualViewportHeight(enabled: boolean): number | null {
+  const [height, setHeight] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    const update = () => {
+      setHeight(window.visualViewport?.height ?? window.innerHeight);
+    };
+
+    update();
+    window.visualViewport?.addEventListener('resize', update);
+    window.visualViewport?.addEventListener('scroll', update);
+    window.addEventListener('resize', update);
+
+    return () => {
+      window.visualViewport?.removeEventListener('resize', update);
+      window.visualViewport?.removeEventListener('scroll', update);
+      window.removeEventListener('resize', update);
+    };
+  }, [enabled]);
+
+  return height;
+}
+
+function keyDownSequence(event: KeyboardEvent<HTMLTextAreaElement>): string | null {
+  if (event.ctrlKey && event.key.toLowerCase() === 'c') {
+    return MOBILE_TERMINAL_KEY_SEQUENCES.ctrlC;
+  }
+
+  switch (event.key) {
+    case 'Enter':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.enter;
+    case 'Backspace':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.backspace;
+    case 'Escape':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.esc;
+    case 'Tab':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.tab;
+    case 'ArrowUp':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.up;
+    case 'ArrowDown':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.down;
+    case 'ArrowRight':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.right;
+    case 'ArrowLeft':
+      return MOBILE_TERMINAL_KEY_SEQUENCES.left;
+    default:
+      return null;
+  }
+}
+
+function KeyButton({
+  item,
+  size,
+  disabled,
+  onPress,
+}: {
+  item: TerminalKey;
+  size: 'compact' | 'large';
+  disabled: boolean;
+  onPress: (id: keyof typeof MOBILE_TERMINAL_KEY_SEQUENCES) => void;
+}) {
+  return (
+    <button
+      type="button"
+      title={item.title}
+      disabled={disabled}
+      onPointerDown={(event) => event.preventDefault()}
+      onClick={() => onPress(item.id)}
+      className={clsx(
+        'flex min-w-0 items-center justify-center rounded border border-border bg-surface-raised font-mono text-foreground transition-colors',
+        'hover:bg-header-inactive-bg focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-focus-ring',
+        'disabled:pointer-events-none disabled:opacity-60',
+        size === 'compact'
+          ? 'min-h-10 px-1 text-xs'
+          : 'min-h-14 px-3 text-base',
+      )}
+    >
+      <span className="truncate">{item.label}</span>
+    </button>
+  );
+}
+
+function TodoPane({ section }: { section: Exclude<MobileTerminalSection, 'type' | 'keys'> }) {
+  return (
+    <div className="grid min-h-24 content-start gap-2 border-t border-border bg-app-bg px-4 py-3 text-foreground">
+      {section === 'recent' ? (
+        <>
+          <h2 className="font-mono text-sm font-semibold">TODO: Recent commands</h2>
+          <p className="text-sm text-muted">This pane will eventually show recently used commands.</p>
+        </>
+      ) : (
+        <>
+          <h2 className="font-mono text-sm font-semibold">TODO: Draft</h2>
+          <p className="text-sm text-muted">This pane will eventually support composing text before sending it to the terminal.</p>
+        </>
+      )}
+    </div>
+  );
+}
+
+export function MobileTerminalUi({
+  terminal,
+  activeSection,
+  defaultSection = 'type',
+  onSectionChange,
+  onSendInput,
+  onFocusInput,
+  interactive = true,
+  fillViewport = false,
+  className,
+  terminalClassName,
+  style,
+}: MobileTerminalUiProps) {
+  const [internalSection, setInternalSection] = useState<MobileTerminalSection>(defaultSection);
+  const section = activeSection ?? internalSection;
+  const inputRef = useRef<HTMLTextAreaElement | null>(null);
+  const composingRef = useRef(false);
+  const [inputValue, setInputValue] = useState('');
+  const viewportHeight = useVisualViewportHeight(fillViewport);
+
+  const sendInput = useCallback((data: string) => {
+    if (!interactive || data.length === 0) return;
+    onSendInput?.(data);
+  }, [interactive, onSendInput]);
+
+  const focusInput = useCallback(() => {
+    if (!interactive) return;
+    onFocusInput?.();
+    inputRef.current?.focus({ preventScroll: true });
+  }, [interactive, onFocusInput]);
+
+  const setSection = useCallback((nextSection: MobileTerminalSection) => {
+    if (activeSection === undefined) setInternalSection(nextSection);
+    onSectionChange?.(nextSection);
+    if (nextSection === 'type') {
+      window.requestAnimationFrame(focusInput);
+    }
+  }, [activeSection, focusInput, onSectionChange]);
+
+  const flushInputValue = useCallback((value: string) => {
+    if (value) sendInput(value);
+    setInputValue('');
+  }, [sendInput]);
+
+  useEffect(() => {
+    if (section !== 'type' || !interactive) return;
+    const frame = window.requestAnimationFrame(focusInput);
+    const delayedFocus = window.setTimeout(focusInput, 120);
+    const settledFocus = window.setTimeout(focusInput, 500);
+    return () => {
+      window.cancelAnimationFrame(frame);
+      window.clearTimeout(delayedFocus);
+      window.clearTimeout(settledFocus);
+    };
+  }, [focusInput, interactive, section]);
+
+  const rootStyle: MobileTerminalStyle = { ...style };
+  if (fillViewport && viewportHeight !== null) {
+    rootStyle['--mobile-terminal-visible-height'] = `${viewportHeight}px`;
+  }
+
+  return (
+    <div
+      data-mobile-terminal-ui
+      className={clsx(
+        'relative flex min-h-0 flex-col overflow-hidden bg-app-bg text-app-fg',
+        fillViewport ? 'h-[var(--mobile-terminal-visible-height,100dvh)]' : 'h-full',
+        className,
+      )}
+      style={rootStyle}
+    >
+      <div
+        className={clsx('min-h-0 flex-1 overflow-hidden bg-terminal-bg', terminalClassName)}
+        onPointerDown={focusInput}
+        onPointerUp={focusInput}
+      >
+        <div className="flex h-full min-h-0 flex-col">{terminal}</div>
+      </div>
+
+      {section === 'type' ? (
+        <div className="grid shrink-0 grid-cols-7 gap-1 border-t border-border bg-app-bg px-2 py-2">
+          {TERMINAL_KEYS.map((item) => (
+            <KeyButton
+              key={item.id}
+              item={item}
+              size="compact"
+              disabled={!interactive}
+              onPress={(id) => {
+                sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id]);
+                focusInput();
+              }}
+            />
+          ))}
+        </div>
+      ) : null}
+
+      {section === 'keys' ? (
+        <div className="grid shrink-0 gap-2 border-t border-border bg-app-bg px-3 py-3">
+          <div className="grid grid-cols-3 gap-2">
+            {TERMINAL_KEYS.slice(0, 3).map((item) => (
+              <KeyButton
+                key={item.id}
+                item={item}
+                size="large"
+                disabled={!interactive}
+                onPress={(id) => sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id])}
+              />
+            ))}
+          </div>
+          <div className="grid grid-cols-4 gap-2">
+            {TERMINAL_KEYS.slice(3).map((item) => (
+              <KeyButton
+                key={item.id}
+                item={item}
+                size="large"
+                disabled={!interactive}
+                onPress={(id) => sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id])}
+              />
+            ))}
+          </div>
+        </div>
+      ) : null}
+
+      {section === 'recent' || section === 'draft' ? <TodoPane section={section} /> : null}
+
+      <nav className="grid h-12 shrink-0 grid-cols-4 border-t border-border bg-app-bg font-mono text-sm">
+        {NAV_ITEMS.map((item) => {
+          const selected = item.id === section;
+          return (
+            <button
+              key={item.id}
+              type="button"
+              disabled={!interactive}
+              aria-current={selected ? 'page' : undefined}
+              onClick={() => setSection(item.id)}
+              className={clsx(
+                'min-w-0 border-t-2 px-1 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-focus-ring',
+                'disabled:pointer-events-none',
+                selected
+                  ? 'border-focus-ring bg-header-active-bg text-header-active-fg'
+                  : 'border-transparent text-muted hover:bg-header-inactive-bg hover:text-foreground',
+              )}
+            >
+              <span className="truncate">{item.label}</span>
+            </button>
+          );
+        })}
+      </nav>
+
+      <textarea
+        ref={inputRef}
+        aria-label="Terminal input"
+        value={inputValue}
+        disabled={!interactive}
+        autoCapitalize="off"
+        autoComplete="off"
+        autoCorrect="off"
+        spellCheck={false}
+        inputMode="text"
+        enterKeyHint="enter"
+        onKeyDown={(event) => {
+          const sequence = keyDownSequence(event);
+          if (!sequence) return;
+          event.preventDefault();
+          sendInput(sequence);
+          setInputValue('');
+        }}
+        onCompositionStart={() => {
+          composingRef.current = true;
+        }}
+        onCompositionEnd={(event) => {
+          composingRef.current = false;
+          flushInputValue(event.currentTarget.value);
+        }}
+        onChange={(event) => {
+          const value = event.currentTarget.value;
+          if (composingRef.current) {
+            setInputValue(value);
+          } else {
+            flushInputValue(value);
+          }
+        }}
+        className="absolute left-0 top-0 h-px w-px resize-none overflow-hidden border-0 bg-transparent p-0 opacity-0 outline-none"
+      />
+    </div>
+  );
+}
diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 7f236e8..6944837 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -100,6 +100,7 @@ export function Wall({
   onApiReady,
   onEvent,
   baseboardNotice,
+  showBaseboard = true,
 }: {
   initialPaneIds?: string[];
   initialMode?: WallMode;
@@ -108,6 +109,7 @@ export function Wall({
   onApiReady?: (api: DockviewApi) => void;
   onEvent?: (event: WallEvent) => void;
   baseboardNotice?: ReactNode;
+  showBaseboard?: boolean;
 } = {}) {
   const apiRef = useRef<DockviewApi | null>(null);
   const [dockviewApi, setDockviewApi] = useState<DockviewApi | null>(null);
@@ -591,9 +593,9 @@ export function Wall({
           <FreshlySpawnedContext.Provider value={freshlySpawnedRef.current}>
           <DialogKeyboardContext.Provider value={setDialogKeyboardActive}>
           <div className="flex-1 min-h-0 flex flex-col bg-app-bg text-app-fg font-sans overflow-hidden">
-            {/* Dockview — 2px bottom inset keeps rounded panes distinct from the baseboard. */}
-            <div className="flex-1 min-h-0 relative px-1.5 pt-1.5 pb-0.5">
-              <div ref={dockviewContainerRef} className="absolute inset-x-1.5 top-1.5 bottom-0.5">
+            {/* Dockview — 2px bottom inset keeps rounded panes distinct from the baseboard when present. */}
+            <div className={`flex-1 min-h-0 relative px-1.5 pt-1.5 ${showBaseboard ? 'pb-0.5' : 'pb-1.5'}`}>
+              <div ref={dockviewContainerRef} className={`absolute inset-x-1.5 top-1.5 ${showBaseboard ? 'bottom-0.5' : 'bottom-1.5'}`}>
                 <DockviewReact
                   components={components}
                   tabComponents={tabComponents}
@@ -605,8 +607,10 @@ export function Wall({
               </div>
             </div>
 
-            {/* Baseboard — always visible */}
-            <Baseboard items={doors} onReattach={handleReattach} notice={baseboardNotice} />
+            {/* Baseboard — always visible in the main shell; embedders may suppress it for constrained mobile prototypes. */}
+            {showBaseboard ? (
+              <Baseboard items={doors} onReattach={handleReattach} notice={baseboardNotice} />
+            ) : null}
 
             {/* Kill confirmation overlay — centered over the pane being killed */}
             {confirmKill && (
diff --git a/lib/src/stories/MobileTerminalUi.stories.tsx b/lib/src/stories/MobileTerminalUi.stories.tsx
new file mode 100644
index 0000000..30010bf
--- /dev/null
+++ b/lib/src/stories/MobileTerminalUi.stories.tsx
@@ -0,0 +1,111 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useMemo, useState } from 'react';
+import {
+  MOBILE_TERMINAL_KEY_SEQUENCES,
+  MobileTerminalUi,
+  type MobileTerminalUiProps,
+} from '../components/MobileTerminalUi';
+
+const meta: Meta<typeof MobileTerminalUi> = {
+  title: 'App/MobileTerminalUi',
+  component: MobileTerminalUi,
+  parameters: {
+    layout: 'centered',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MobileTerminalUi>;
+
+const SEQUENCE_LABELS = new Map<string, string>([
+  [MOBILE_TERMINAL_KEY_SEQUENCES.ctrlC, 'CTRL_C'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.esc, 'ESC'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.tab, 'TAB'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.enter, 'ENTER'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.backspace, 'BACKSPACE'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.up, 'ARROW_UP'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.down, 'ARROW_DOWN'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.right, 'ARROW_RIGHT'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.left, 'ARROW_LEFT'],
+]);
+
+function describeInput(data: string): string {
+  return SEQUENCE_LABELS.get(data) ?? JSON.stringify(data);
+}
+
+function MockTerminal({ inputLog }: { inputLog: string[] }) {
+  const renderedLog = useMemo(() => inputLog.slice(-6), [inputLog]);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col overflow-hidden bg-terminal-bg p-3 font-mono text-sm text-terminal-fg">
+      <div className="text-success">ascii-splash</div>
+      <div className="text-muted">pattern=oceanbeach quality=medium fps=30</div>
+      <div className="mt-3 grid flex-1 content-center gap-1 text-center text-xs leading-tight text-foreground">
+        <div>{'~~~~~      *      ~~~~~'}</div>
+        <div>{'  ~~~~   /|\\   ~~~~  '}</div>
+        <div>{'~~~~   /_|_\\   ~~~~  '}</div>
+        <div>{'  ~~~~   / \\   ~~~~  '}</div>
+      </div>
+      <div className="mt-auto border-t border-border pt-2 text-xs text-muted">
+        {renderedLog.length === 0 ? (
+          <div>$ _</div>
+        ) : (
+          renderedLog.map((entry, index) => <div key={`${entry}-${index}`}>$ {entry}</div>)
+        )}
+      </div>
+    </div>
+  );
+}
+
+function StoryFrame(args: MobileTerminalUiProps) {
+  const [inputLog, setInputLog] = useState<string[]>([]);
+
+  return (
+    <div className="h-[812px] w-[390px] overflow-hidden border border-border bg-app-bg shadow-2xl">
+      <MobileTerminalUi
+        {...args}
+        terminal={<MockTerminal inputLog={inputLog} />}
+        onSendInput={(data) => {
+          args.onSendInput?.(data);
+          setInputLog((entries) => [...entries, describeInput(data)]);
+        }}
+      />
+    </div>
+  );
+}
+
+export const TypePane: Story = {
+  args: {
+    defaultSection: 'type',
+  },
+  render: (args) => <StoryFrame {...args} />,
+};
+
+export const KeysPane: Story = {
+  args: {
+    defaultSection: 'keys',
+  },
+  render: (args) => <StoryFrame {...args} />,
+};
+
+export const RecentTodoPane: Story = {
+  args: {
+    defaultSection: 'recent',
+  },
+  render: (args) => <StoryFrame {...args} />,
+};
+
+export const DraftTodoPane: Story = {
+  args: {
+    defaultSection: 'draft',
+  },
+  render: (args) => <StoryFrame {...args} />,
+};
+
+export const NonInteractivePhoneMockup: Story = {
+  args: {
+    defaultSection: 'type',
+    interactive: false,
+  },
+  render: (args) => <StoryFrame {...args} />,
+};
diff --git a/website/src/App.tsx b/website/src/App.tsx
index c24edf0..97eaa9b 100644
--- a/website/src/App.tsx
+++ b/website/src/App.tsx
@@ -9,6 +9,10 @@ export const routes: RouteRecord[] = [
     path: "/playground",
     lazy: () => import("./pages/Playground"),
   },
+  {
+    path: "/tether",
+    lazy: () => import("./pages/Tether"),
+  },
   {
     path: "/changelog",
     lazy: () => import("./pages/Changelog"),
diff --git a/website/src/index.css b/website/src/index.css
index 15eb968..16134f9 100644
--- a/website/src/index.css
+++ b/website/src/index.css
@@ -36,6 +36,22 @@ html body {
   height: auto;
 }
 
+html body.tether-marketing-body {
+  overflow: auto;
+}
+
+body.tether-marketing-body #root {
+  height: auto;
+}
+
+html body.tether-terminal-body {
+  overflow: hidden;
+}
+
+body.tether-terminal-body #root {
+  height: 100vh;
+}
+
 [data-theme-picker-current="true"] {
   background-image: linear-gradient(currentColor, currentColor);
   background-position: 0 100%;
diff --git a/website/src/pages/Tether.tsx b/website/src/pages/Tether.tsx
new file mode 100644
index 0000000..a3b7462
--- /dev/null
+++ b/website/src/pages/Tether.tsx
@@ -0,0 +1,209 @@
+import { useCallback, useEffect, useRef, useState, type ComponentType } from "react";
+import SiteHeader, { STATIC_PAGE_HEADER_STYLE } from "../components/SiteHeader";
+import { MobileTerminalUi } from "mouseterm-lib/components/MobileTerminalUi";
+import { restoreActiveTheme } from "mouseterm-lib/lib/themes";
+
+export { Tether as Component };
+
+type FakePtyAdapter = import("mouseterm-lib/lib/platform/fake-adapter").FakePtyAdapter;
+type AsciiSplashRunner = import("../lib/ascii-splash-runner").AsciiSplashRunner;
+
+const TETHER_PANE = "tether-ascii-splash";
+const TETHER_THEME_ID = "vscode.theme-kimbie-dark.kimbie-dark";
+
+interface WallModule {
+  Wall: ComponentType<any>;
+}
+
+interface DockviewApiLike {
+  getPanel(id: string): { api: { setTitle(title: string): void; setActive(): void } } | undefined;
+}
+
+function useIsMobileViewport() {
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const media = window.matchMedia("(max-width: 767px)");
+    const update = () => setIsMobile(media.matches);
+    update();
+    media.addEventListener("change", update);
+    return () => media.removeEventListener("change", update);
+  }, []);
+
+  return isMobile;
+}
+
+function useTetherTheme() {
+  const restoredRef = useRef(false);
+  if (!restoredRef.current) {
+    restoreActiveTheme(TETHER_THEME_ID);
+    restoredRef.current = true;
+  }
+}
+
+function TetherTerminalExperience({
+  interactive,
+  fillViewport = false,
+}: {
+  interactive: boolean;
+  fillViewport?: boolean;
+}) {
+  useTetherTheme();
+  const [WallModule, setWallModule] = useState<WallModule | null>(null);
+  const adapterRef = useRef<FakePtyAdapter | null>(null);
+  const runnerRef = useRef<AsciiSplashRunner | null>(null);
+  const restartingRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function loadWall() {
+      const platform = await import("mouseterm-lib/lib/platform");
+      const registry = await import("mouseterm-lib/lib/terminal-registry");
+      const wall = await import("mouseterm-lib/components/Wall");
+      const asciiSplash = await import("../lib/ascii-splash-runner");
+      await import("mouseterm-lib/index.css");
+      if (cancelled) return;
+
+      const adapter = platform.initPlatform("fake");
+      registry.disposeAllSessions();
+      adapter.reset();
+      registry.initAlertStateReceiver();
+      adapterRef.current = adapter;
+      adapter.clearDefaultScenario();
+      adapter.setScenario(TETHER_PANE, { name: "none", chunks: [] });
+
+      const startRunner = () => {
+        if (cancelled || runnerRef.current || !adapter.hasPty(TETHER_PANE)) return;
+        const runner = new asciiSplash.AsciiSplashRunner({
+          adapter,
+          terminalId: TETHER_PANE,
+          args: [],
+          onExit: () => {
+            runnerRef.current = null;
+            if (cancelled) return;
+            restartingRef.current = window.setTimeout(() => {
+              restartingRef.current = null;
+              startRunner();
+            }, 120);
+          },
+        });
+        runnerRef.current = runner;
+        runner.start();
+      };
+
+      adapter.setInputHandler(TETHER_PANE, (data) => {
+        runnerRef.current?.handleInput(data);
+      });
+
+      const unsubscribeSpawn = adapter.onPtySpawn(({ id }) => {
+        if (id === TETHER_PANE) startRunner();
+      });
+      if (adapter.hasPty(TETHER_PANE)) startRunner();
+
+      setWallModule({ Wall: wall.Wall });
+
+      return () => {
+        unsubscribeSpawn();
+      };
+    }
+
+    let disposeSpawn: (() => void) | undefined;
+    loadWall().then((dispose) => {
+      if (cancelled) {
+        dispose?.();
+      } else {
+        disposeSpawn = dispose;
+      }
+    });
+
+    return () => {
+      cancelled = true;
+      disposeSpawn?.();
+      if (restartingRef.current !== null) {
+        window.clearTimeout(restartingRef.current);
+        restartingRef.current = null;
+      }
+      runnerRef.current?.dispose();
+      runnerRef.current = null;
+      adapterRef.current?.clearInputHandler(TETHER_PANE);
+    };
+  }, []);
+
+  const handleApiReady = useCallback((api: DockviewApiLike) => {
+    const panel = api.getPanel(TETHER_PANE);
+    if (!panel) return;
+    panel.api.setTitle("ascii-splash");
+    panel.api.setActive();
+  }, []);
+
+  return (
+    <MobileTerminalUi
+      terminal={
+        WallModule ? (
+          <WallModule.Wall
+            initialPaneIds={[TETHER_PANE]}
+            initialMode="passthrough"
+            onApiReady={handleApiReady}
+            showBaseboard={false}
+          />
+        ) : null
+      }
+      interactive={interactive}
+      fillViewport={fillViewport}
+      onSendInput={(data) => adapterRef.current?.writePty(TETHER_PANE, data)}
+    />
+  );
+}
+
+function MobileTetherPage() {
+  return (
+    <main className="fixed inset-0 bg-black">
+      <TetherTerminalExperience interactive fillViewport />
+    </main>
+  );
+}
+
+function DesktopTetherPage() {
+  return (
+    <div className="min-h-screen bg-[var(--color-bg)] text-[var(--color-text)]">
+      <SiteHeader activePath="/tether" style={STATIC_PAGE_HEADER_STYLE} />
+      <main className="mx-auto grid min-h-screen max-w-6xl items-center gap-10 px-4 pb-10 pt-24 md:grid-cols-[minmax(0,1fr)_minmax(320px,390px)] md:px-8 md:pt-28">
+        <section className="max-w-2xl">
+          <h1 className="mb-6 font-display text-[clamp(2.5rem,6vw,5.5rem)] leading-none text-[var(--color-text)]">
+            Coming soon: MouseTerm Tether
+          </h1>
+          <p className="mb-5 max-w-xl text-xl leading-relaxed opacity-75 md:text-2xl">
+            Take your terminal from wherever it was (VS Code or standalone desktop) to wherever you are going
+          </p>
+          <p className="font-display text-lg text-[var(--color-caramel)]">
+            Come back on mobile to try out the UI
+          </p>
+        </section>
+
+        <section aria-label="MouseTerm Tether phone preview" className="mx-auto w-full max-w-[390px]">
+          <div className="rounded-[2.4rem] border border-white/15 bg-neutral-950 p-3 shadow-[0_24px_90px_rgba(0,0,0,0.55)]">
+            <div className="mx-auto mb-2 h-1.5 w-24 rounded-full bg-white/20" />
+            <div className="aspect-[390/812] overflow-hidden rounded-[1.8rem] border border-white/10 bg-black">
+              <div className="h-full pointer-events-none" aria-hidden="true">
+                <TetherTerminalExperience interactive={false} />
+              </div>
+            </div>
+          </div>
+        </section>
+      </main>
+    </div>
+  );
+}
+
+function Tether() {
+  const isMobile = useIsMobileViewport();
+
+  useEffect(() => {
+    const className = isMobile ? "tether-terminal-body" : "tether-marketing-body";
+    document.body.classList.add(className);
+    return () => document.body.classList.remove(className);
+  }, [isMobile]);
+
+  return isMobile ? <MobileTetherPage /> : <DesktopTetherPage />;
+}

From bb0e7c6fd878f05b12cc98feb755a45097de89d7 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Sat, 9 May 2026 18:16:01 -0700
Subject: [PATCH 04/12] Disable interaction in Tether desktop preview

---
 website/src/pages/Tether.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/website/src/pages/Tether.tsx b/website/src/pages/Tether.tsx
index a3b7462..84a573b 100644
--- a/website/src/pages/Tether.tsx
+++ b/website/src/pages/Tether.tsx
@@ -185,7 +185,7 @@ function DesktopTetherPage() {
           <div className="rounded-[2.4rem] border border-white/15 bg-neutral-950 p-3 shadow-[0_24px_90px_rgba(0,0,0,0.55)]">
             <div className="mx-auto mb-2 h-1.5 w-24 rounded-full bg-white/20" />
             <div className="aspect-[390/812] overflow-hidden rounded-[1.8rem] border border-white/10 bg-black">
-              <div className="h-full pointer-events-none" aria-hidden="true">
+              <div className="h-full pointer-events-none" aria-hidden="true" inert>
                 <TetherTerminalExperience interactive={false} />
               </div>
             </div>

From 195b581682f74398f4f95e65c14a397b475d007b Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Sat, 9 May 2026 21:41:57 -0700
Subject: [PATCH 05/12] Move Tether marketing onto the /tether page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lift the "Walk away. Keep going." hero, descriptive paragraphs, and
NotifySignupForm out of Home.tsx's #notify section and onto
DesktopTetherPage. Add a ShareUrlButton inline with a new "Come back
right now on mobile … to try it out! (WIP)" callout that uses the Web
Share API (clipboard fallback) so desktop visitors can fling the URL
to their phone.

Also bundles previously-staged tether prototype work: ThemePicker on
the mobile and desktop tether pages, with matching mobile-ui and theme
spec updates.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/specs/mobile-ui.md      |   5 ++
 docs/specs/theme.md          |  11 ++-
 website/src/pages/Home.tsx   | 103 +------------------------
 website/src/pages/Tether.tsx | 145 +++++++++++++++++++++++++++++++++--
 4 files changed, 150 insertions(+), 114 deletions(-)

diff --git a/docs/specs/mobile-ui.md b/docs/specs/mobile-ui.md
index 91c4a84..622c25f 100644
--- a/docs/specs/mobile-ui.md
+++ b/docs/specs/mobile-ui.md
@@ -18,6 +18,10 @@ The main interface has a terminal viewport and a bottom navigation row:
 Recent | Type | Draft | Keys
 ```
 
+The website `/tether` prototype also exposes a small floating theme switcher
+above the terminal. It uses the shared MouseTerm `ThemePicker` and must not
+replace or reorder the four-item bottom navigation.
+
 Only the most important sections need complete behavior in v0:
 
 * **Type**: implemented.
@@ -433,6 +437,7 @@ Prototype behavior:
 Build exactly this:
 
 * One terminal playground screen.
+* Floating theme switcher using the shared MouseTerm theme picker.
 * Bottom navigation row:
 
 ```text
diff --git a/docs/specs/theme.md b/docs/specs/theme.md
index 5eec0ac..b8dccca 100644
--- a/docs/specs/theme.md
+++ b/docs/specs/theme.md
@@ -152,10 +152,13 @@ terminal colors. It captures the current DOM-visible theme state and shows:
 - dynamic door/focus-ring picks from the same `pickDoorPair()` and
   `pickFocusRing()` helpers used by Wall's `computeDynamicPalette()`.
 
-Standalone and playground expose the debugger as `Debug current theme` in the
-`ThemePicker` menu. VSCode opens it through the `mouseterm.debugTheme` command
-and the `mouseterm:openThemeDebugger` extension-to-webview message. The
-debugger's copied report is a shareable text dump of the same snapshot.
+Standalone, playground, and the website `/tether` prototype expose the debugger
+as `Debug current theme` in the `ThemePicker` menu. `/tether` uses the same
+picker in the desktop page header and as a floating control above the mobile
+terminal prototype, both with the Kimbie Dark default theme fallback. VSCode
+opens it through the `mouseterm.debugTheme` command and the
+`mouseterm:openThemeDebugger` extension-to-webview message. The debugger's
+copied report is a shareable text dump of the same snapshot.
 
 ## Maintainer checklist
 
diff --git a/website/src/pages/Home.tsx b/website/src/pages/Home.tsx
index 84471f2..19abfd8 100644
--- a/website/src/pages/Home.tsx
+++ b/website/src/pages/Home.tsx
@@ -1,7 +1,6 @@
 import {
   AppleLogoIcon,
   CheckCircleIcon,
-  CircleNotchIcon,
   CubeIcon,
   DesktopIcon,
   DotsThreeOutlineIcon,
@@ -10,7 +9,7 @@ import {
   TerminalIcon,
   WindowsLogoIcon,
 } from "@phosphor-icons/react";
-import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type FormEvent, type MouseEventHandler, type ReactNode } from "react";
+import { useEffect, useLayoutEffect, useRef, useState, type CSSProperties, type MouseEventHandler, type ReactNode } from "react";
 import SiteHeader from "../components/SiteHeader";
 import posterUrl from "../assets/video-climb-blink-and-stare.webp";
 import videoUrl from "../assets/video-climb-blink-and-stare.mp4";
@@ -19,7 +18,6 @@ import copyPasteVideoUrl from "../assets/video-copy-paste.mp4";
 import tmuxVideoUrl from "../assets/video-tmux.mp4";
 import visualStudioIconUrl from "../assets/visual-studio-icon.svg";
 import tinyIconUrl from "../assets/icon-tiny-dark.png";
-import phoneMockupUrl from "../assets/phone-mockup.webp";
 import standaloneLatest from "@standalone-latest";
 import { prefersReducedMotion } from "mouseterm-lib/lib/ui-geometry";
 
@@ -260,79 +258,6 @@ function DownloadGroupHeader({
   );
 }
 
-const EMAIL_REGEX =
-  /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
-
-function NotifySignupForm() {
-  const [email, setEmail] = useState("");
-  const [message, setMessage] = useState("");
-  const [redirecting, setRedirecting] = useState(false);
-
-  const redirectUrl = `https://nedshed.dev/subscribe?email=${encodeURIComponent(email)}`;
-
-  function handleSubmit(e: FormEvent<HTMLFormElement>) {
-    e.preventDefault();
-    if (!EMAIL_REGEX.test(email)) {
-      setMessage("Please enter a valid email");
-      return;
-    }
-    setRedirecting(true);
-    window.setTimeout(() => {
-      window.location.href = redirectUrl;
-    }, 3000);
-  }
-
-  if (redirecting) {
-    return (
-      <div className="flex items-center gap-3 text-lg leading-relaxed text-[var(--color-caramel)]">
-        <CircleNotchIcon className="shrink-0 animate-spin" size={28} weight="bold" />
-        <p>
-          Just one more click! Hit <span className="text-[var(--color-text)]/70">subscribe</span> after{" "}
-          <a
-            href={redirectUrl}
-            className="underline underline-offset-2 hover:opacity-80"
-          >
-            the redirect
-          </a>
-          ...
-        </p>
-      </div>
-    );
-  }
-
-  return (
-    <form onSubmit={handleSubmit} className="flex flex-col gap-2">
-      <label htmlFor="notify-email" className="font-display text-sm opacity-50">
-        Email
-      </label>
-      <div className="flex flex-col gap-3 sm:flex-row sm:items-stretch">
-        <input
-          id="notify-email"
-          type="email"
-          name="email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          placeholder="you@example.com"
-          required
-          autoComplete="email"
-          className="min-h-12 w-full rounded-md border border-[var(--color-text)]/50 bg-[var(--color-bg)] px-4 py-3 text-base text-[var(--color-text)]/70 placeholder:opacity-50 focus:border-[var(--color-caramel)] focus:outline-none sm:flex-1"
-        />
-        <button
-          type="submit"
-          className="min-h-12 inline-flex items-center justify-center rounded-md border border-[var(--color-caramel)] bg-[var(--color-caramel)]/15 px-6 py-3 text-base font-display text-[var(--color-caramel)] transition hover:bg-[var(--color-caramel)]/25 sm:w-auto"
-        >
-          Notify me when Tether ships
-        </button>
-      </div>
-      {message && (
-        <p className="text-sm text-red-400" role="alert">
-          {message}
-        </p>
-      )}
-    </form>
-  );
-}
-
 function Home() {
   const videoRef = useRef<HTMLVideoElement>(null);
   const posterRef = useRef<HTMLImageElement>(null);
@@ -954,32 +879,6 @@ function Home() {
           </div>
         </section>
 
-        <section id="notify" className={`mx-auto max-w-5xl px-4 md:px-6 ${SECTION_PY} grid md:grid-cols-[2fr_3fr] gap-8 md:gap-12 items-start`}>
-          <img
-            src={phoneMockupUrl}
-            alt="MouseTerm Playground running on a phone"
-            className="order-2 md:order-1 block w-full max-w-[280px] mx-auto md:max-w-none"
-          />
-          <div className="order-1 md:order-2">
-            <h2 className="font-display text-[clamp(1.5rem,2.5vw+0.5rem,2.25rem)] text-[var(--color-text)] mb-6">
-              Walk away. Keep going.
-            </h2>
-            <p className="mb-4 text-lg leading-relaxed opacity-70">
-              Coming next: <span className="text-[var(--color-caramel)]">Tether</span>. Pair a
-              terminal session to your phone over WebRTC and take a stroll, the MouseTerm alert
-              system will buzz you if there's anything to do. A hosted auto-pairing service comes
-              later — just leave and keep working, no "I'm walking away" dance.
-            </p>
-            <p className="mb-4 text-lg leading-relaxed opacity-70">
-              Open source and free to self-host, or pay us a little bit and you can use ours. We'll discount for early adopters, so don't miss out!
-            </p>
-            <NotifySignupForm />
-            <p className="mt-3 text-base leading-snug opacity-50">
-              This signs you up for my personal devlog <a href="https://nedshed.dev" className="text-[var(--color-caramel)] underline-offset-2 hover:underline">nedshed.dev</a> on Substack. The next post will be the launch post, you can unsubscribe any time.
-            </p>
-          </div>
-        </section>
-
         <footer className="border-t border-[var(--color-text)]/20 py-10">
           <div className="mx-auto max-w-5xl px-4 md:px-6 flex flex-wrap items-center justify-center gap-x-6 gap-y-2 text-base text-center opacity-50">
             <a href="/dependencies" className="underline hover:opacity-100">Dependencies</a>
diff --git a/website/src/pages/Tether.tsx b/website/src/pages/Tether.tsx
index 84a573b..d8f7c77 100644
--- a/website/src/pages/Tether.tsx
+++ b/website/src/pages/Tether.tsx
@@ -1,6 +1,8 @@
-import { useCallback, useEffect, useRef, useState, type ComponentType } from "react";
+import { useCallback, useEffect, useRef, useState, type ComponentType, type FormEvent } from "react";
+import { CircleNotchIcon, ShareIcon } from "@phosphor-icons/react";
 import SiteHeader, { STATIC_PAGE_HEADER_STYLE } from "../components/SiteHeader";
 import { MobileTerminalUi } from "mouseterm-lib/components/MobileTerminalUi";
+import { ThemePicker } from "mouseterm-lib/components/ThemePicker";
 import { restoreActiveTheme } from "mouseterm-lib/lib/themes";
 
 export { Tether as Component };
@@ -160,24 +162,151 @@ function MobileTetherPage() {
   return (
     <main className="fixed inset-0 bg-black">
       <TetherTerminalExperience interactive fillViewport />
+      <div className="absolute right-2 top-10 z-30 rounded border border-[var(--vscode-panel-border)] bg-[var(--vscode-editorWidget-background)]/95 px-1.5 py-1 text-[var(--vscode-editor-foreground)] shadow-lg">
+        <ThemePicker variant="standalone-appbar" defaultThemeId={TETHER_THEME_ID} />
+      </div>
     </main>
   );
 }
 
+const EMAIL_REGEX =
+  /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+
+function NotifySignupForm() {
+  const [email, setEmail] = useState("");
+  const [message, setMessage] = useState("");
+  const [redirecting, setRedirecting] = useState(false);
+
+  const redirectUrl = `https://nedshed.dev/subscribe?email=${encodeURIComponent(email)}`;
+
+  function handleSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    if (!EMAIL_REGEX.test(email)) {
+      setMessage("Please enter a valid email");
+      return;
+    }
+    setRedirecting(true);
+    window.setTimeout(() => {
+      window.location.href = redirectUrl;
+    }, 3000);
+  }
+
+  if (redirecting) {
+    return (
+      <div className="flex items-center gap-3 text-lg leading-relaxed text-[var(--color-caramel)]">
+        <CircleNotchIcon className="shrink-0 animate-spin" size={28} weight="bold" />
+        <p>
+          Just one more click! Hit <span className="text-[var(--color-text)]/70">subscribe</span> after{" "}
+          <a
+            href={redirectUrl}
+            className="underline underline-offset-2 hover:opacity-80"
+          >
+            the redirect
+          </a>
+          ...
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="flex flex-col gap-2">
+      <label htmlFor="notify-email" className="font-display text-sm opacity-50">
+        Email
+      </label>
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-stretch">
+        <input
+          id="notify-email"
+          type="email"
+          name="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="you@example.com"
+          required
+          autoComplete="email"
+          className="min-h-12 w-full rounded-md border border-[var(--color-text)]/50 bg-[var(--color-bg)] px-4 py-3 text-base text-[var(--color-text)]/70 placeholder:opacity-50 focus:border-[var(--color-caramel)] focus:outline-none sm:flex-1"
+        />
+        <button
+          type="submit"
+          className="min-h-12 inline-flex items-center justify-center rounded-md border border-[var(--color-caramel)] bg-[var(--color-caramel)]/15 px-6 py-3 text-base font-display text-[var(--color-caramel)] transition hover:bg-[var(--color-caramel)]/25 sm:w-auto"
+        >
+          Notify me when Tether ships
+        </button>
+      </div>
+      {message && (
+        <p className="text-sm text-red-400" role="alert">
+          {message}
+        </p>
+      )}
+    </form>
+  );
+}
+
+function ShareUrlButton() {
+  const [copied, setCopied] = useState(false);
+
+  async function handleShare() {
+    const url = window.location.href;
+    if (navigator.share) {
+      try {
+        await navigator.share({ url, title: "MouseTerm Tether" });
+        return;
+      } catch (err) {
+        if ((err as DOMException)?.name === "AbortError") return;
+      }
+    }
+    try {
+      await navigator.clipboard.writeText(url);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 2000);
+    } catch {
+      window.prompt("Copy this URL to your phone:", url);
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleShare}
+      aria-label="Share this page URL"
+      className="inline-flex items-center gap-1 align-[-0.2em] rounded text-[var(--color-text)]/90 transition duration-150 hover:scale-120 hover:text-[var(--color-text)]"
+    >
+      <ShareIcon size={22} weight="bold" />
+      {copied && <span className="text-sm">copied!</span>}
+    </button>
+  );
+}
+
 function DesktopTetherPage() {
   return (
     <div className="min-h-screen bg-[var(--color-bg)] text-[var(--color-text)]">
-      <SiteHeader activePath="/tether" style={STATIC_PAGE_HEADER_STYLE} />
+      <SiteHeader
+        activePath="/tether"
+        style={STATIC_PAGE_HEADER_STYLE}
+        controls={<ThemePicker variant="standalone-appbar" defaultThemeId={TETHER_THEME_ID} />}
+      />
       <main className="mx-auto grid min-h-screen max-w-6xl items-center gap-10 px-4 pb-10 pt-24 md:grid-cols-[minmax(0,1fr)_minmax(320px,390px)] md:px-8 md:pt-28">
         <section className="max-w-2xl">
-          <h1 className="mb-6 font-display text-[clamp(2.5rem,6vw,5.5rem)] leading-none text-[var(--color-text)]">
-            Coming soon: MouseTerm Tether
+          <h1 className="font-display text-[clamp(1.5rem,2.5vw+0.5rem,2.25rem)] text-[var(--color-text)] mb-4">
+            Walk away. Keep going.
           </h1>
-          <p className="mb-5 max-w-xl text-xl leading-relaxed opacity-75 md:text-2xl">
-            Take your terminal from wherever it was (VS Code or standalone desktop) to wherever you are going
+          <p className="mb-6 font-display text-lg text-[var(--color-caramel)]">
+            Come back right now on mobile{" "}
+            <ShareUrlButton />{" "}
+            to try it out! (WIP)
+          </p>
+          <p className="mb-4 text-lg leading-relaxed opacity-70">
+            Coming next: <span className="text-[var(--color-caramel)]">Tether</span>. Pair a
+            terminal session to your phone over WebRTC and take a stroll, the MouseTerm alert
+            system will buzz you if there's anything to do. A hosted auto-pairing service comes
+            later — just leave and keep working, no "I'm walking away" dance.
+          </p>
+          <p className="mb-4 text-lg leading-relaxed opacity-70">
+            Open source and free to self-host, or pay us a little bit and you can use ours. We'll discount for early adopters, so don't miss out!
           </p>
-          <p className="font-display text-lg text-[var(--color-caramel)]">
-            Come back on mobile to try out the UI
+          <NotifySignupForm />
+          <p className="mt-3 text-base leading-snug opacity-50">
+            This signs you up for my personal devlog <a href="https://nedshed.dev" className="text-[var(--color-caramel)] underline-offset-2 hover:underline">nedshed.dev</a> on Substack. The next post will be the launch post, you can unsubscribe any time.
           </p>
         </section>
 

From c14cdf5ddb696ec233bf0f6b6417fec01227dcbb Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Sat, 9 May 2026 21:44:42 -0700
Subject: [PATCH 06/12] Extract NotifySignupForm into its own component

Move the form and its EMAIL_REGEX out of Tether.tsx and into
website/src/components/NotifySignupForm.tsx so it can be reused
without duplicating the redirect/spinner state machine.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 website/src/components/NotifySignupForm.tsx | 75 +++++++++++++++++++
 website/src/pages/Tether.tsx                | 81 +--------------------
 2 files changed, 79 insertions(+), 77 deletions(-)
 create mode 100644 website/src/components/NotifySignupForm.tsx

diff --git a/website/src/components/NotifySignupForm.tsx b/website/src/components/NotifySignupForm.tsx
new file mode 100644
index 0000000..b5254d5
--- /dev/null
+++ b/website/src/components/NotifySignupForm.tsx
@@ -0,0 +1,75 @@
+import { useState, type FormEvent } from "react";
+import { CircleNotchIcon } from "@phosphor-icons/react";
+
+const EMAIL_REGEX =
+  /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+
+export function NotifySignupForm() {
+  const [email, setEmail] = useState("");
+  const [message, setMessage] = useState("");
+  const [redirecting, setRedirecting] = useState(false);
+
+  const redirectUrl = `https://nedshed.dev/subscribe?email=${encodeURIComponent(email)}`;
+
+  function handleSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    if (!EMAIL_REGEX.test(email)) {
+      setMessage("Please enter a valid email");
+      return;
+    }
+    setRedirecting(true);
+    window.setTimeout(() => {
+      window.location.href = redirectUrl;
+    }, 3000);
+  }
+
+  if (redirecting) {
+    return (
+      <div className="flex items-center gap-3 text-lg leading-relaxed text-[var(--color-caramel)]">
+        <CircleNotchIcon className="shrink-0 animate-spin" size={28} weight="bold" />
+        <p>
+          Just one more click! Hit <span className="text-[var(--color-text)]/70">subscribe</span> after{" "}
+          <a
+            href={redirectUrl}
+            className="underline underline-offset-2 hover:opacity-80"
+          >
+            the redirect
+          </a>
+          ...
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="flex flex-col gap-2">
+      <label htmlFor="notify-email" className="font-display text-sm opacity-50">
+        Email
+      </label>
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-stretch">
+        <input
+          id="notify-email"
+          type="email"
+          name="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="you@example.com"
+          required
+          autoComplete="email"
+          className="min-h-12 w-full rounded-md border border-[var(--color-text)]/50 bg-[var(--color-bg)] px-4 py-3 text-base text-[var(--color-text)]/70 placeholder:opacity-50 focus:border-[var(--color-caramel)] focus:outline-none sm:flex-1"
+        />
+        <button
+          type="submit"
+          className="min-h-12 inline-flex items-center justify-center rounded-md border border-[var(--color-caramel)] bg-[var(--color-caramel)]/15 px-6 py-3 text-base font-display text-[var(--color-caramel)] transition hover:bg-[var(--color-caramel)]/25 sm:w-auto"
+        >
+          Notify me when Tether ships
+        </button>
+      </div>
+      {message && (
+        <p className="text-sm text-red-400" role="alert">
+          {message}
+        </p>
+      )}
+    </form>
+  );
+}
diff --git a/website/src/pages/Tether.tsx b/website/src/pages/Tether.tsx
index d8f7c77..c8e690e 100644
--- a/website/src/pages/Tether.tsx
+++ b/website/src/pages/Tether.tsx
@@ -1,6 +1,7 @@
-import { useCallback, useEffect, useRef, useState, type ComponentType, type FormEvent } from "react";
-import { CircleNotchIcon, ShareIcon } from "@phosphor-icons/react";
+import { useCallback, useEffect, useRef, useState, type ComponentType } from "react";
+import { ShareIcon } from "@phosphor-icons/react";
 import SiteHeader, { STATIC_PAGE_HEADER_STYLE } from "../components/SiteHeader";
+import { NotifySignupForm } from "../components/NotifySignupForm";
 import { MobileTerminalUi } from "mouseterm-lib/components/MobileTerminalUi";
 import { ThemePicker } from "mouseterm-lib/components/ThemePicker";
 import { restoreActiveTheme } from "mouseterm-lib/lib/themes";
@@ -169,79 +170,6 @@ function MobileTetherPage() {
   );
 }
 
-const EMAIL_REGEX =
-  /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
-
-function NotifySignupForm() {
-  const [email, setEmail] = useState("");
-  const [message, setMessage] = useState("");
-  const [redirecting, setRedirecting] = useState(false);
-
-  const redirectUrl = `https://nedshed.dev/subscribe?email=${encodeURIComponent(email)}`;
-
-  function handleSubmit(e: FormEvent<HTMLFormElement>) {
-    e.preventDefault();
-    if (!EMAIL_REGEX.test(email)) {
-      setMessage("Please enter a valid email");
-      return;
-    }
-    setRedirecting(true);
-    window.setTimeout(() => {
-      window.location.href = redirectUrl;
-    }, 3000);
-  }
-
-  if (redirecting) {
-    return (
-      <div className="flex items-center gap-3 text-lg leading-relaxed text-[var(--color-caramel)]">
-        <CircleNotchIcon className="shrink-0 animate-spin" size={28} weight="bold" />
-        <p>
-          Just one more click! Hit <span className="text-[var(--color-text)]/70">subscribe</span> after{" "}
-          <a
-            href={redirectUrl}
-            className="underline underline-offset-2 hover:opacity-80"
-          >
-            the redirect
-          </a>
-          ...
-        </p>
-      </div>
-    );
-  }
-
-  return (
-    <form onSubmit={handleSubmit} className="flex flex-col gap-2">
-      <label htmlFor="notify-email" className="font-display text-sm opacity-50">
-        Email
-      </label>
-      <div className="flex flex-col gap-3 sm:flex-row sm:items-stretch">
-        <input
-          id="notify-email"
-          type="email"
-          name="email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          placeholder="you@example.com"
-          required
-          autoComplete="email"
-          className="min-h-12 w-full rounded-md border border-[var(--color-text)]/50 bg-[var(--color-bg)] px-4 py-3 text-base text-[var(--color-text)]/70 placeholder:opacity-50 focus:border-[var(--color-caramel)] focus:outline-none sm:flex-1"
-        />
-        <button
-          type="submit"
-          className="min-h-12 inline-flex items-center justify-center rounded-md border border-[var(--color-caramel)] bg-[var(--color-caramel)]/15 px-6 py-3 text-base font-display text-[var(--color-caramel)] transition hover:bg-[var(--color-caramel)]/25 sm:w-auto"
-        >
-          Notify me when Tether ships
-        </button>
-      </div>
-      {message && (
-        <p className="text-sm text-red-400" role="alert">
-          {message}
-        </p>
-      )}
-    </form>
-  );
-}
-
 function ShareUrlButton() {
   const [copied, setCopied] = useState(false);
 
@@ -296,8 +224,7 @@ function DesktopTetherPage() {
             to try it out! (WIP)
           </p>
           <p className="mb-4 text-lg leading-relaxed opacity-70">
-            Coming next: <span className="text-[var(--color-caramel)]">Tether</span>. Pair a
-            terminal session to your phone over WebRTC and take a stroll, the MouseTerm alert
+            Pair a terminal session to your phone over WebRTC and take a stroll, the MouseTerm alert
             system will buzz you if there's anything to do. A hosted auto-pairing service comes
             later — just leave and keep working, no "I'm walking away" dance.
           </p>

From 072d4a6bf5ffce581442bb91fa280be447b4c867 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Sat, 9 May 2026 21:46:00 -0700
Subject: [PATCH 07/12] Move devlog disclaimer into NotifySignupForm

The "signs you up for nedshed.dev" disclaimer is part of the form's
contract, so let it travel with the component instead of being
duplicated by every caller.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 website/src/components/NotifySignupForm.tsx | 68 ++++++++++++---------
 website/src/pages/Tether.tsx                |  3 -
 2 files changed, 40 insertions(+), 31 deletions(-)

diff --git a/website/src/components/NotifySignupForm.tsx b/website/src/components/NotifySignupForm.tsx
index b5254d5..bb49d4d 100644
--- a/website/src/components/NotifySignupForm.tsx
+++ b/website/src/components/NotifySignupForm.tsx
@@ -42,34 +42,46 @@ export function NotifySignupForm() {
   }
 
   return (
-    <form onSubmit={handleSubmit} className="flex flex-col gap-2">
-      <label htmlFor="notify-email" className="font-display text-sm opacity-50">
-        Email
-      </label>
-      <div className="flex flex-col gap-3 sm:flex-row sm:items-stretch">
-        <input
-          id="notify-email"
-          type="email"
-          name="email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          placeholder="you@example.com"
-          required
-          autoComplete="email"
-          className="min-h-12 w-full rounded-md border border-[var(--color-text)]/50 bg-[var(--color-bg)] px-4 py-3 text-base text-[var(--color-text)]/70 placeholder:opacity-50 focus:border-[var(--color-caramel)] focus:outline-none sm:flex-1"
-        />
-        <button
-          type="submit"
-          className="min-h-12 inline-flex items-center justify-center rounded-md border border-[var(--color-caramel)] bg-[var(--color-caramel)]/15 px-6 py-3 text-base font-display text-[var(--color-caramel)] transition hover:bg-[var(--color-caramel)]/25 sm:w-auto"
+    <>
+      <form onSubmit={handleSubmit} className="flex flex-col gap-2">
+        <label htmlFor="notify-email" className="font-display text-sm opacity-50">
+          Email
+        </label>
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-stretch">
+          <input
+            id="notify-email"
+            type="email"
+            name="email"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+            placeholder="you@example.com"
+            required
+            autoComplete="email"
+            className="min-h-12 w-full rounded-md border border-[var(--color-text)]/50 bg-[var(--color-bg)] px-4 py-3 text-base text-[var(--color-text)]/70 placeholder:opacity-50 focus:border-[var(--color-caramel)] focus:outline-none sm:flex-1"
+          />
+          <button
+            type="submit"
+            className="min-h-12 inline-flex items-center justify-center rounded-md border border-[var(--color-caramel)] bg-[var(--color-caramel)]/15 px-6 py-3 text-base font-display text-[var(--color-caramel)] transition hover:bg-[var(--color-caramel)]/25 sm:w-auto"
+          >
+            Notify me when Tether ships
+          </button>
+        </div>
+        {message && (
+          <p className="text-sm text-red-400" role="alert">
+            {message}
+          </p>
+        )}
+      </form>
+      <p className="mt-3 text-base leading-snug opacity-50">
+        This signs you up for my personal devlog{" "}
+        <a
+          href="https://nedshed.dev"
+          className="text-[var(--color-caramel)] underline-offset-2 hover:underline"
         >
-          Notify me when Tether ships
-        </button>
-      </div>
-      {message && (
-        <p className="text-sm text-red-400" role="alert">
-          {message}
-        </p>
-      )}
-    </form>
+          nedshed.dev
+        </a>{" "}
+        on Substack. The next post will be the launch post, you can unsubscribe any time.
+      </p>
+    </>
   );
 }
diff --git a/website/src/pages/Tether.tsx b/website/src/pages/Tether.tsx
index c8e690e..4073704 100644
--- a/website/src/pages/Tether.tsx
+++ b/website/src/pages/Tether.tsx
@@ -232,9 +232,6 @@ function DesktopTetherPage() {
             Open source and free to self-host, or pay us a little bit and you can use ours. We'll discount for early adopters, so don't miss out!
           </p>
           <NotifySignupForm />
-          <p className="mt-3 text-base leading-snug opacity-50">
-            This signs you up for my personal devlog <a href="https://nedshed.dev" className="text-[var(--color-caramel)] underline-offset-2 hover:underline">nedshed.dev</a> on Substack. The next post will be the launch post, you can unsubscribe any time.
-          </p>
         </section>
 
         <section aria-label="MouseTerm Tether phone preview" className="mx-auto w-full max-w-[390px]">

From 6f1c7d189c9832a56f55ad1bcd2e76a209dc4dca Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 11 May 2026 16:50:18 -0700
Subject: [PATCH 08/12] Revise tether mobile controls

---
 docs/specs/mobile-ui.md                      | 509 ++++++-------------
 lib/src/components/MobileTerminalUi.tsx      | 451 +++++++++++-----
 lib/src/stories/MobileTerminalUi.stories.tsx |   9 +
 website/src/pages/Tether.tsx                 | 174 +++++--
 4 files changed, 607 insertions(+), 536 deletions(-)

diff --git a/docs/specs/mobile-ui.md b/docs/specs/mobile-ui.md
index 622c25f..a4199ef 100644
--- a/docs/specs/mobile-ui.md
+++ b/docs/specs/mobile-ui.md
@@ -2,253 +2,150 @@
 
 ## 1. Overview
 
-This document specifies a greenfield prototype for a mobile-first terminal UI.
+This document specifies the `/tether` mobile terminal prototype.
 
 The prototype tests one core idea:
 
 ```text
-Native phone keyboard for text + simple terminal controls for missing keys.
+Stable terminal viewport + explicit touch mode + explicit keyboard mode.
 ```
 
-The app should feel like a lightweight mobile terminal playground. It does not need remote sessions, SSH, user accounts, or production infrastructure. The first version should use a local playground PTY, fake shell, in-browser terminal demo, or command simulator that is realistic enough to test the mobile UI.
+The app should feel like a lightweight mobile terminal playground. It does not
+need remote sessions, SSH, user accounts, or production infrastructure.
 
-The main interface has a terminal viewport and a bottom navigation row:
+The website `/tether` prototype exposes a small floating theme switcher above
+the terminal. It uses the shared MouseTerm `ThemePicker`.
 
-```text
-Recent | Type | Draft | Keys
-```
-
-The website `/tether` prototype also exposes a small floating theme switcher
-above the terminal. It uses the shared MouseTerm `ThemePicker` and must not
-replace or reorder the four-item bottom navigation.
-
-Only the most important sections need complete behavior in v0:
+`/tether` uses the same fake playground terminal stack as `/playground`:
+`PlaygroundShellRegistry` attaches a `TutorialShell` to every spawned pane, the
+same fake commands dispatch to browser-side runners, and the first pane simply
+auto-runs `ascii-splash` as its initial command.
 
-* **Type**: implemented.
-* **Keys**: implemented.
-* **Recent**: opens a TODO pane.
-* **Draft**: opens a TODO pane.
+## 2. Prototype Goals
 
-## 2. Prototype goals
+Primary goals:
 
-### 2.1 Primary goals
-
-* Test mobile terminal text entry using the native phone keyboard.
-* Test whether simple on-screen terminal controls make missing keys usable on a phone.
-* Keep the terminal viewport usable when the mobile keyboard is visible.
-* Provide enough terminal behavior to evaluate typing, Enter, Backspace, arrows, Escape, Tab, and Ctrl+C.
+* Keep the terminal viewport stable when the native phone keyboard opens or closes.
+* Let the user explicitly choose what terminal touches mean.
+* Let the user explicitly choose what appears in the stable keyboard reserve area.
+* Test normal mobile text entry using the native phone keyboard.
+* Provide enough terminal behavior to evaluate typing, Enter, Backspace, arrows, Escape, Tab, and app interruption.
 * Keep the implementation small and easy to iterate on.
 
-### 2.2 Non-goals
-
-The prototype does not need:
+Non-goals:
 
 * Remote shell support.
 * SSH support.
 * WebSocket transport.
 * User accounts.
 * Session persistence.
-* Multiple terminal sessions.
 * Command history storage.
-* Snippet management.
 * A real draft/scratchpad workflow.
-* Terminal mouse mode.
 * Advanced gestures.
 * Production security hardening.
 * Full accessibility implementation.
 
-## 3. Core layout
+## 3. Core Layout
 
-## 3.1 Default portrait layout
+The mobile UI is split into fixed and flexible regions:
 
 ```text
 ┌─────────────────────────┐
-│ Terminal playground      │
-│                         │
-│                         │
+│ Pane title               │ fixed/small
 ├─────────────────────────┤
-│ Active pane              │
+│ Pane content             │ flexible terminal area
 ├─────────────────────────┤
-│ Recent | Type | Draft | Keys
-└─────────────────────────┘
-```
-
-The active pane changes when the user taps a bottom navigation item.
-
-## 3.2 Type mode layout
-
-Type is the default active section.
-
-```text
-┌─────────────────────────┐
-│ Terminal playground      │
-│                         │
-├─────────────────────────┤
-│ Esc Tab Ctrl+C ← ↓ ↑ →   │
+│ Touch mode selector      │ thin, always visible
 ├─────────────────────────┤
-│ Recent | Type | Draft | Keys
+│ Keyboard mode selector   │ thin, always visible
 ├─────────────────────────┤
-│ native phone keyboard    │
+│ Keyboard reserve area    │ stable height
+│                         │
+│ Shows app keyboard UI    │ when OS keyboard hidden
+│ Occupied by OS keyboard  │ when OS keyboard visible
 └─────────────────────────┘
 ```
 
-When the native keyboard is open, the terminal viewport should resize to remain visible.
-
-## 3.3 Keys mode layout
+The pane title and pane content come from the embedded `Wall` terminal pane. The
+mobile wrapper owns the two selectors and the fixed-height keyboard reserve.
 
-Keys mode shows the same important controls in a larger layout.
-
-```text
-┌─────────────────────────┐
-│ Terminal playground      │
-│                         │
-├─────────────────────────┤
-│ Esc     Tab     Ctrl+C   │
-│ ←       ↓       ↑       →│
-├─────────────────────────┤
-│ Recent | Type | Draft | Keys
-└─────────────────────────┘
-```
+The root height must not be recalculated from `window.visualViewport` on every
+keyboard resize. The reserve area is intentionally stable so the terminal region
+does not bounce while the OS keyboard animates.
 
-Keys mode is useful when the user needs more reliable taps for arrow keys and Ctrl+C.
+## 4. Touch Mode Selector
 
-## 3.4 TODO pane layout
+The touch selector controls what happens when the user touches the pane content
+area. It is thin and always visible between the terminal content and the
+keyboard mode selector.
 
-Recent and Draft should open simple placeholder panes.
+Touch modes:
 
-```text
-┌─────────────────────────┐
-│ Terminal playground      │
-│                         │
-├─────────────────────────┤
-│ TODO: Recent             │
-├─────────────────────────┤
-│ Recent | Type | Draft | Keys
-└─────────────────────────┘
-```
+| Mode | Icon | Availability | Behavior |
+| --- | --- | --- | --- |
+| Gestures | `HandPointingIcon` | Always available | Touch drags generate arrow keys. Drag left sends left, drag right sends right, drag up sends up, and drag down sends down. |
+| Text selection | `CursorTextIcon` | Always available | Touches are reserved for terminal text selection and copy/paste. If the TUI is capturing mouse events, MouseTerm activates mouse override for the active pane. |
+| Cursor | `CursorClickIcon` | Only when the active TUI is capturing mouse events | Touches are passed through as terminal mouse/cursor input. |
 
-```text
-┌─────────────────────────┐
-│ Terminal playground      │
-│                         │
-├─────────────────────────┤
-│ TODO: Draft              │
-├─────────────────────────┤
-│ Recent | Type | Draft | Keys
-└─────────────────────────┘
-```
+Default touch mode is **Gestures**.
 
-The TODO panes should make the app structure visible without implementing those workflows.
+If Cursor mode is active and the active pane stops capturing mouse events, the
+selector must fall back to Gestures.
 
-## 4. Bottom navigation
+## 5. Keyboard Mode Selector
 
-The bottom navigation row is always present unless the native keyboard or viewport constraints make that impossible.
+The keyboard mode selector controls what appears in the keyboard reserve area.
+It is thin, always visible, and has four items:
 
 ```text
 Recent | Type | Draft | Keys
 ```
 
-### 4.1 Navigation behavior
-
-| Item   | v0 behavior                                |
-| ------ | ------------------------------------------ |
-| Recent | Opens TODO pane                            |
-| Type   | Opens Type pane and focuses terminal input |
-| Draft  | Opens TODO pane                            |
-| Keys   | Opens large Keys pane                      |
-
-### 4.2 Active state
-
-The active item should be visually obvious.
-
-Recommended active states:
-
-* Highlight the selected label.
-* Use a top border or pill background.
-* Keep the active pane directly above the nav row.
-
-### 4.3 Default state
-
-The app should start in **Type** mode.
+Keyboard modes:
 
-## 5. Terminal playground
+| Mode | Reserve area content |
+| --- | --- |
+| Recent | The entire reserve area displays `Recent - WIP`. |
+| Type | The reserve area focuses the hidden terminal input. Every typed key is echoed into the terminal as it happens. |
+| Draft | The entire reserve area displays `Draft - WIP`. |
+| Keys | The entire reserve area displays terminal key buttons. |
 
-The terminal area is the main testing surface.
+Default keyboard mode is **Type**.
 
-### 5.1 Requirements
+Switching to Type should focus the hidden input and open the native keyboard
+where browser policy allows. Switching away from Type should blur the hidden
+input so the app keyboard UI is visible again.
 
-The terminal playground should:
+Tapping the **Type** selector must focus the hidden input synchronously during
+the tap/click handler. Do not defer this focus to `requestAnimationFrame` or a
+timer, because mobile browsers may then treat it as no longer user-initiated and
+refuse to open the native keyboard.
 
-* Display terminal-like output.
-* Accept typed input from the native mobile keyboard.
-* Show a cursor.
-* Support Enter.
-* Support Backspace.
-* Respond visibly to arrow keys.
-* Respond visibly to Escape, Tab, and Ctrl+C.
-* Scroll when output exceeds the visible area.
-* Resize when the mobile keyboard appears or disappears.
+## 6. Keys Mode
 
-### 5.2 Implementation options
-
-Use the simplest implementation that gives a realistic enough interaction test.
-
-Acceptable options:
-
-* xterm.js connected to a local playground process.
-* xterm.js with an in-browser command simulator.
-* A custom terminal-like component if true terminal emulation is not needed yet.
-
-Prefer xterm.js if the prototype should test realistic cursor movement, ANSI behavior, and terminal rendering.
-
-### 5.3 Minimal fake shell behavior
-
-A fake shell is acceptable for v0.
-
-Minimum useful behavior:
-
-* Echo typed characters.
-* Maintain a command line buffer.
-* Enter submits the current command.
-* Backspace edits the current command.
-* Arrow keys produce visible behavior.
-* Ctrl+C clears or interrupts the current command.
-* Escape and Tab produce visible behavior.
-
-Example commands:
+Keys mode displays exactly these buttons:
 
 ```text
-help
-clear
-echo hello
+Esc   Tab   Space   Enter
+←     ↓     ↑       →
 ```
 
-The shell only needs enough behavior to test the mobile controls.
-
-## 6. Type pane
+Mappings:
 
-Type is the primary implemented pane.
+| Button | Sequence |
+| --- | --- |
+| Esc | `\x1B` |
+| Tab | `\x09` |
+| Space | ` ` |
+| Enter | `\r` |
+| ← | `\x1B[D` |
+| ↓ | `\x1B[B` |
+| ↑ | `\x1B[A` |
+| → | `\x1B[C` |
 
-### 6.1 Purpose
+Tapping a key sends exactly one action. Long-press repeat is not required for v0.
 
-Type mode lets the user enter normal text through the native phone keyboard while keeping a compact terminal control row available.
-
-### 6.2 Layout
-
-```text
-Esc Tab Ctrl+C ← ↓ ↑ →
-```
-
-### 6.3 Behavior
-
-When the user opens Type mode:
-
-* Focus the terminal input.
-* Open the native phone keyboard where browser policy allows.
-* Show the compact terminal control row.
-* Keep the terminal viewport visible above the controls and keyboard.
-
-### 6.4 Hidden input
+## 7. Type Mode Input
 
 Use a hidden or visually minimal input configured for terminal-style typing:
 
@@ -263,220 +160,144 @@ Use a hidden or visually minimal input configured for terminal-style typing:
 ></textarea>
 ```
 
-### 6.5 Text input behavior
-
 Required behavior:
 
-* Normal characters are sent to the terminal playground.
+* Normal characters are sent to the active terminal immediately.
 * Enter sends terminal Enter.
 * Backspace works.
+* Physical `Ctrl+C` sends `\x03`.
 * Autocorrect and autocapitalization are disabled where possible.
-* Input should support mobile keyboard behavior and IME composition.
-* The app should not depend only on `keydown` for text input.
-
-## 7. Keys pane
+* Input supports mobile keyboard behavior and IME composition.
+* The app does not depend only on `keydown` for text input.
 
-Keys is the second implemented pane.
-
-### 7.1 Purpose
-
-Keys mode provides larger tap targets for the terminal controls that are most important on mobile.
-
-### 7.2 Layout
-
-```text
-┌───────────────────────┐
-│ Esc   Tab   Ctrl+C     │
-│ ←     ↓     ↑     →    │
-└───────────────────────┘
-```
-
-### 7.3 Controls
-
-| Button | Behavior         |
-| ------ | ---------------- |
-| Esc    | Send Escape      |
-| Tab    | Send Tab         |
-| Ctrl+C | Send interrupt   |
-| ←      | Send left arrow  |
-| ↓      | Send down arrow  |
-| ↑      | Send up arrow    |
-| →      | Send right arrow |
-
-### 7.4 Interaction rules
-
-* Tapping a key sends exactly one action.
-* The same key mappings should be used in Type mode and Keys mode.
-* Keys mode should not add extra controls in v0.
-* Long-press repeat is not required for v0.
-* Modifier-lock behavior is not required for v0.
-
-## 8. Recent TODO pane
-
-### 8.1 Purpose
-
-Recent is visible in the navigation so the overall app structure can be tested, but it does not implement command history in v0.
-
-### 8.2 Layout
-
-```text
-TODO: Recent commands
+## 8. Terminal Playground Behavior
 
-This pane will eventually show recently used commands.
-```
-
-### 8.3 Behavior
-
-* Tapping Recent opens the TODO pane.
-* The terminal remains visible above the pane.
-* No command list is required.
-* No storage is required.
-
-## 9. Draft TODO pane
+A fake shell is acceptable for v0.
 
-### 9.1 Purpose
+Minimum useful behavior:
 
-Draft is visible in the navigation so the overall app structure can be tested, but it does not implement scratchpad or dual-pane editing in v0.
+* Echo typed characters.
+* Maintain a command line buffer.
+* Enter submits the current command.
+* Backspace edits the current command.
+* Arrow keys produce visible behavior.
+* Escape and Tab produce visible behavior.
+* When a fake full-screen app such as `ascii-splash`, `splash`, `changelog`, or
+  `tut` is running, `Ctrl+C` sends `\x03` to that app; if the app exits, the
+  terminal returns to the fake shell prompt instead of restarting the app.
+* New panes created from the wall get the same fake shell behavior and prompt as
+  regular `/playground` panes.
 
-### 9.2 Layout
+Example commands:
 
 ```text
-TODO: Draft
-
-This pane will eventually support composing text before sending it to the terminal.
+help
+clear
+echo hello
+ascii-splash
+changelog
+tut
 ```
 
-### 9.3 Behavior
-
-* Tapping Draft opens the TODO pane.
-* The terminal remains visible above the pane.
-* No editable scratchpad is required.
-* No copy/paste workflow is required.
-
-## 10. Key sequence mapping
-
-Use these mappings for both Type mode and Keys mode.
-
-| UI action   | Sequence       |
-| ----------- | -------------- |
-| Ctrl+C      | `\x03`         |
-| Esc         | `\x1B`         |
-| Tab         | `\x09`         |
-| Enter       | `\r`           |
-| Backspace   | Usually `\x7F` |
-| Arrow Up    | `\x1B[A`       |
-| Arrow Down  | `\x1B[B`       |
-| Arrow Right | `\x1B[C`       |
-| Arrow Left  | `\x1B[D`       |
-
-If the playground terminal uses a higher-level input API instead of raw terminal sequences, map these actions to the equivalent local action.
-
-## 11. Keyboard visibility and layout
-
-Keyboard handling should be simple and pragmatic.
-
-The prototype should resize the terminal area when the phone keyboard appears. Use the simplest reliable approach available:
-
-1. Use `window.visualViewport` resize events if available.
-2. Fall back to normal viewport sizing.
-3. Avoid complex keyboard detection logic unless the layout is broken.
-
-Minimal approach:
+The shell only needs enough behavior to test the mobile controls.
 
-```js
-function updateLayoutForKeyboard() {
-  const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
-  document.documentElement.style.setProperty(
-    "--visible-height",
-    `${viewportHeight}px`
-  );
-}
+## 9. Keyboard Reserve
 
-window.visualViewport?.addEventListener("resize", updateLayoutForKeyboard);
-window.visualViewport?.addEventListener("scroll", updateLayoutForKeyboard);
-window.addEventListener("resize", updateLayoutForKeyboard);
-updateLayoutForKeyboard();
-```
+The keyboard reserve area has a stable height. It should not be recomputed from
+`visualViewport` while the native keyboard animates.
 
-The prototype does not need to perfectly detect whether the keyboard is present. It only needs to keep the terminal, active pane, and nav row usable.
+When the OS keyboard is hidden, the reserve area shows the selected app keyboard
+UI (`Recent - WIP`, Type focus target, `Draft - WIP`, or Keys buttons).
 
-## 12. Touch interactions
+When the OS keyboard is visible, the OS keyboard may cover or occupy that same
+physical area. This is preferred over resizing the whole app around the keyboard.
 
-Keep touch behavior minimal.
+## 10. Touch Interactions
 
 Required interactions:
 
-* Tap terminal to focus typing.
-* Tap Type to focus typing.
-* Tap control buttons.
-* Tap bottom navigation items.
-* Scroll terminal output.
+* Tap keyboard mode selector items.
+* Tap touch mode selector items.
+* Tap Type reserve area to focus typing.
+* Type through the native keyboard.
+* Tap key buttons in Keys mode.
+* Drag in Gestures mode to send arrow keys.
+* Use Text selection mode for terminal selection and copy/paste.
+* Use Cursor mode for terminal mouse/cursor input when a TUI requests mouse reporting.
+
+Pane-content touches must never open the native keyboard. The pane content area
+may focus the terminal internally for key routing or mouse handling, but the
+mobile wrapper must configure text inputs created by the terminal surface as
+non-keyboard targets (`inputmode="none"`, readonly, not tab-reachable) and
+immediately blur them when the touch starts there. Since `Wall` may defer xterm
+focus to `requestAnimationFrame`, the wrapper must also repeat that blur shortly
+after the touch. The only mobile UI surfaces that should open the native
+keyboard are the Type selector and the Type reserve area.
 
 Not required for v0:
 
-* Swipe navigation.
-* Long-press arrow repeat.
+* Long-press key repeat.
+* Multi-touch gestures.
 * Trackpad mode.
-* Two-finger gestures.
-* Terminal mouse mode.
-* Custom text selection behavior.
+* A full command history UI.
+* A real draft editor.
 
-## 13. Copy and paste
+## 11. Copy And Paste
 
 Keep copy and paste minimal.
 
 Prototype behavior:
 
+* Text selection mode should allow the existing terminal selection and copy/paste flows to work.
 * Let users paste through the native browser/OS paste flow where possible.
-* Let terminal output selection rely on default browser behavior where possible.
-* No custom clipboard manager is required.
+* No custom mobile clipboard manager is required.
 * No multi-line paste review is required.
 
-## 14. Recommended v0 scope
+## 12. Recommended v0 Scope
 
 Build exactly this:
 
 * One terminal playground screen.
 * Floating theme switcher using the shared MouseTerm theme picker.
-* Bottom navigation row:
+* Touch mode selector:
 
 ```text
-Recent | Type | Draft | Keys
+Gestures | Text selection | Cursor
 ```
 
-* Type pane with compact controls:
+* Keyboard mode selector:
 
 ```text
-Esc Tab Ctrl+C ← ↓ ↑ →
+Recent | Type | Draft | Keys
 ```
 
-* Keys pane with larger controls:
+* Stable keyboard reserve area.
+* Recent reserve content: `Recent - WIP`.
+* Draft reserve content: `Draft - WIP`.
+* Type mode native mobile keyboard input.
+* Keys buttons:
 
 ```text
-Esc   Tab   Ctrl+C
-←     ↓     ↑     →
+Esc   Tab   Space   Enter
+←     ↓     ↑       →
 ```
 
-* Recent TODO pane.
-* Draft TODO pane.
-* Native mobile keyboard input.
-* Basic viewport resizing when the keyboard opens.
 * Simple local playground terminal behavior.
 
-## 15. Prototype success criteria
+## 13. Prototype Success Criteria
 
 The prototype should answer these questions:
 
-1. Is the terminal viewport usable when the mobile keyboard is open?
-2. Is the compact Type control row easy to reach?
-3. Is the larger Keys pane necessary or useful?
-4. Are arrow keys usable enough for command history and cursor movement?
-5. Is Ctrl+C discoverable and easy to trigger?
-6. Does the native keyboard feel acceptable for terminal text entry?
-7. Does the four-item navigation row make sense, even with Recent and Draft as placeholders?
+1. Does the terminal viewport feel stable when the mobile keyboard opens and closes?
+2. Is the touch mode selector understandable and reachable?
+3. Are gesture arrows usable enough for command history and cursor movement?
+4. Is text selection discoverable and reliable on mobile?
+5. Is Cursor mode useful when a TUI captures mouse events?
+6. Does native keyboard Type mode feel acceptable for terminal text entry?
+7. Does the stable keyboard reserve feel better than resizing the whole UI?
 8. Is the UI too cramped in portrait orientation?
 
-## 16. Future work
+## 14. Future Work
 
 Potential later additions:
 
@@ -484,12 +305,10 @@ Potential later additions:
 * Draft scratchpad.
 * Dual-pane copy/paste.
 * Pinned snippets.
-* Ctrl+D and Ctrl+Z.
+* Ctrl+C, Ctrl+D, and Ctrl+Z app-key buttons.
 * Alt and modifier behavior.
 * Home, End, PgUp, PgDn.
 * Long-press key repeat.
-* Gesture navigation.
-* Terminal mouse mode.
 * Remote backend PTY.
 * SSH sessions.
 * User accounts.
@@ -497,12 +316,12 @@ Potential later additions:
 * Multi-session support.
 * Production security model.
 
-## 17. Product principle
+## 15. Product Principle
 
 The v0 prototype should stay focused:
 
 ```text
-Type and Keys are real.
-Recent and Draft establish the shape of the app.
+Touch modes make pane touches explicit.
+Keyboard modes make the reserve area explicit.
 Everything else waits.
 ```
diff --git a/lib/src/components/MobileTerminalUi.tsx b/lib/src/components/MobileTerminalUi.tsx
index 4f238f1..f07d244 100644
--- a/lib/src/components/MobileTerminalUi.tsx
+++ b/lib/src/components/MobileTerminalUi.tsx
@@ -4,17 +4,27 @@ import {
   useRef,
   useState,
   type CSSProperties,
+  type ComponentType,
   type KeyboardEvent,
+  type PointerEvent,
   type ReactNode,
 } from 'react';
+import {
+  CursorClickIcon,
+  CursorTextIcon,
+  HandPointingIcon,
+} from '@phosphor-icons/react';
 import { clsx } from 'clsx';
 
-export type MobileTerminalSection = 'recent' | 'type' | 'draft' | 'keys';
+export type MobileTerminalKeyboardMode = 'recent' | 'type' | 'draft' | 'keys';
+export type MobileTerminalSection = MobileTerminalKeyboardMode;
+export type MobileTerminalTouchMode = 'gestures' | 'selection' | 'cursor';
 
 export const MOBILE_TERMINAL_KEY_SEQUENCES = {
   ctrlC: '\x03',
   esc: '\x1b',
   tab: '\x09',
+  space: ' ',
   enter: '\r',
   backspace: '\x7f',
   up: '\x1b[A',
@@ -32,29 +42,44 @@ interface TerminalKey {
 const TERMINAL_KEYS: TerminalKey[] = [
   { id: 'esc', label: 'Esc', title: 'Escape' },
   { id: 'tab', label: 'Tab', title: 'Tab' },
-  { id: 'ctrlC', label: 'Ctrl+C', title: 'Interrupt' },
+  { id: 'space', label: 'Space', title: 'Space' },
+  { id: 'enter', label: 'Enter', title: 'Enter' },
   { id: 'left', label: '\u2190', title: 'Left arrow' },
   { id: 'down', label: '\u2193', title: 'Down arrow' },
   { id: 'up', label: '\u2191', title: 'Up arrow' },
   { id: 'right', label: '\u2192', title: 'Right arrow' },
 ];
 
-const NAV_ITEMS: { id: MobileTerminalSection; label: string }[] = [
+const KEYBOARD_MODES: { id: MobileTerminalKeyboardMode; label: string }[] = [
   { id: 'recent', label: 'Recent' },
   { id: 'type', label: 'Type' },
   { id: 'draft', label: 'Draft' },
   { id: 'keys', label: 'Keys' },
 ];
 
-type MobileTerminalStyle = CSSProperties & {
-  '--mobile-terminal-visible-height'?: string;
-};
+const TOUCH_MODES: Array<{
+  id: MobileTerminalTouchMode;
+  label: string;
+  title: string;
+  Icon: ComponentType<{ size?: number; weight?: 'regular' | 'bold' | 'duotone' | 'fill' }>;
+}> = [
+  { id: 'gestures', label: 'Gestures', title: 'Gestures', Icon: HandPointingIcon },
+  { id: 'selection', label: 'Text selection', title: 'Text selection', Icon: CursorTextIcon },
+  { id: 'cursor', label: 'Cursor', title: 'Cursor', Icon: CursorClickIcon },
+];
 
 export interface MobileTerminalUiProps {
   terminal: ReactNode;
-  activeSection?: MobileTerminalSection;
-  defaultSection?: MobileTerminalSection;
-  onSectionChange?: (section: MobileTerminalSection) => void;
+  activeSection?: MobileTerminalKeyboardMode;
+  defaultSection?: MobileTerminalKeyboardMode;
+  onSectionChange?: (section: MobileTerminalKeyboardMode) => void;
+  activeKeyboardMode?: MobileTerminalKeyboardMode;
+  defaultKeyboardMode?: MobileTerminalKeyboardMode;
+  onKeyboardModeChange?: (mode: MobileTerminalKeyboardMode) => void;
+  activeTouchMode?: MobileTerminalTouchMode;
+  defaultTouchMode?: MobileTerminalTouchMode;
+  onTouchModeChange?: (mode: MobileTerminalTouchMode) => void;
+  cursorTouchAvailable?: boolean;
   onSendInput?: (data: string) => void;
   onFocusInput?: () => void;
   interactive?: boolean;
@@ -64,31 +89,6 @@ export interface MobileTerminalUiProps {
   style?: CSSProperties;
 }
 
-function useVisualViewportHeight(enabled: boolean): number | null {
-  const [height, setHeight] = useState<number | null>(null);
-
-  useEffect(() => {
-    if (!enabled || typeof window === 'undefined') return;
-
-    const update = () => {
-      setHeight(window.visualViewport?.height ?? window.innerHeight);
-    };
-
-    update();
-    window.visualViewport?.addEventListener('resize', update);
-    window.visualViewport?.addEventListener('scroll', update);
-    window.addEventListener('resize', update);
-
-    return () => {
-      window.visualViewport?.removeEventListener('resize', update);
-      window.visualViewport?.removeEventListener('scroll', update);
-      window.removeEventListener('resize', update);
-    };
-  }, [enabled]);
-
-  return height;
-}
-
 function keyDownSequence(event: KeyboardEvent<HTMLTextAreaElement>): string | null {
   if (event.ctrlKey && event.key.toLowerCase() === 'c') {
     return MOBILE_TERMINAL_KEY_SEQUENCES.ctrlC;
@@ -118,12 +118,10 @@ function keyDownSequence(event: KeyboardEvent<HTMLTextAreaElement>): string | nu
 
 function KeyButton({
   item,
-  size,
   disabled,
   onPress,
 }: {
   item: TerminalKey;
-  size: 'compact' | 'large';
   disabled: boolean;
   onPress: (id: keyof typeof MOBILE_TERMINAL_KEY_SEQUENCES) => void;
 }) {
@@ -138,9 +136,7 @@ function KeyButton({
         'flex min-w-0 items-center justify-center rounded border border-border bg-surface-raised font-mono text-foreground transition-colors',
         'hover:bg-header-inactive-bg focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-focus-ring',
         'disabled:pointer-events-none disabled:opacity-60',
-        size === 'compact'
-          ? 'min-h-10 px-1 text-xs'
-          : 'min-h-14 px-3 text-base',
+        'min-h-14 px-2 text-sm',
       )}
     >
       <span className="truncate">{item.label}</span>
@@ -148,20 +144,85 @@ function KeyButton({
   );
 }
 
-function TodoPane({ section }: { section: Exclude<MobileTerminalSection, 'type' | 'keys'> }) {
+function KeyboardModeButton({
+  id,
+  label,
+  selected,
+  disabled,
+  onSelect,
+}: {
+  id: MobileTerminalKeyboardMode;
+  label: string;
+  selected: boolean;
+  disabled: boolean;
+  onSelect: (mode: MobileTerminalKeyboardMode) => void;
+}) {
   return (
-    <div className="grid min-h-24 content-start gap-2 border-t border-border bg-app-bg px-4 py-3 text-foreground">
-      {section === 'recent' ? (
-        <>
-          <h2 className="font-mono text-sm font-semibold">TODO: Recent commands</h2>
-          <p className="text-sm text-muted">This pane will eventually show recently used commands.</p>
-        </>
-      ) : (
-        <>
-          <h2 className="font-mono text-sm font-semibold">TODO: Draft</h2>
-          <p className="text-sm text-muted">This pane will eventually support composing text before sending it to the terminal.</p>
-        </>
+    <button
+      key={id}
+      type="button"
+      disabled={disabled}
+      aria-current={selected ? 'page' : undefined}
+      onClick={() => onSelect(id)}
+      className={clsx(
+        'min-w-0 border-t-2 px-1 font-mono text-sm transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-focus-ring',
+        'disabled:pointer-events-none disabled:opacity-60',
+        selected
+          ? 'border-focus-ring bg-header-active-bg text-header-active-fg'
+          : 'border-transparent text-muted hover:bg-header-inactive-bg hover:text-foreground',
       )}
+    >
+      <span className="truncate">{label}</span>
+    </button>
+  );
+}
+
+function TouchModeSelector({
+  mode,
+  cursorAvailable,
+  disabled,
+  onSelect,
+}: {
+  mode: MobileTerminalTouchMode;
+  cursorAvailable: boolean;
+  disabled: boolean;
+  onSelect: (mode: MobileTerminalTouchMode) => void;
+}) {
+  return (
+    <div className="grid h-10 shrink-0 grid-cols-3 border-t border-border bg-app-bg">
+      {TOUCH_MODES.map((item) => {
+        const selected = item.id === mode;
+        const itemDisabled = disabled || (item.id === 'cursor' && !cursorAvailable);
+        const Icon = item.Icon;
+        return (
+          <button
+            key={item.id}
+            type="button"
+            title={item.title}
+            aria-label={item.label}
+            aria-pressed={selected}
+            disabled={itemDisabled}
+            onClick={() => onSelect(item.id)}
+            className={clsx(
+              'grid min-w-0 place-items-center border-t-2 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-focus-ring',
+              'disabled:pointer-events-none disabled:opacity-35',
+              selected
+                ? 'border-focus-ring bg-header-active-bg text-header-active-fg'
+                : 'border-transparent text-muted hover:bg-header-inactive-bg hover:text-foreground',
+            )}
+          >
+            <Icon size={18} weight={selected ? 'bold' : 'regular'} />
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+function WorkInProgressPane({ label }: { label: 'Recent' | 'Draft' }) {
+  return (
+    <div className="grid h-full place-items-center px-4 text-center font-mono text-sm text-muted">
+      {label} - WIP
     </div>
   );
 }
@@ -171,6 +232,13 @@ export function MobileTerminalUi({
   activeSection,
   defaultSection = 'type',
   onSectionChange,
+  activeKeyboardMode,
+  defaultKeyboardMode,
+  onKeyboardModeChange,
+  activeTouchMode,
+  defaultTouchMode = 'gestures',
+  onTouchModeChange,
+  cursorTouchAvailable = false,
   onSendInput,
   onFocusInput,
   interactive = true,
@@ -179,12 +247,16 @@ export function MobileTerminalUi({
   terminalClassName,
   style,
 }: MobileTerminalUiProps) {
-  const [internalSection, setInternalSection] = useState<MobileTerminalSection>(defaultSection);
-  const section = activeSection ?? internalSection;
+  const resolvedDefaultKeyboardMode = defaultKeyboardMode ?? defaultSection;
+  const [internalKeyboardMode, setInternalKeyboardMode] = useState<MobileTerminalKeyboardMode>(resolvedDefaultKeyboardMode);
+  const [internalTouchMode, setInternalTouchMode] = useState<MobileTerminalTouchMode>(defaultTouchMode);
+  const keyboardMode = activeKeyboardMode ?? activeSection ?? internalKeyboardMode;
+  const touchMode = activeTouchMode ?? internalTouchMode;
+  const terminalHostRef = useRef<HTMLDivElement | null>(null);
   const inputRef = useRef<HTMLTextAreaElement | null>(null);
   const composingRef = useRef(false);
+  const gestureStartRef = useRef<{ pointerId: number; x: number; y: number } | null>(null);
   const [inputValue, setInputValue] = useState('');
-  const viewportHeight = useVisualViewportHeight(fillViewport);
 
   const sendInput = useCallback((data: string) => {
     if (!interactive || data.length === 0) return;
@@ -197,13 +269,62 @@ export function MobileTerminalUi({
     inputRef.current?.focus({ preventScroll: true });
   }, [interactive, onFocusInput]);
 
-  const setSection = useCallback((nextSection: MobileTerminalSection) => {
-    if (activeSection === undefined) setInternalSection(nextSection);
-    onSectionChange?.(nextSection);
-    if (nextSection === 'type') {
-      window.requestAnimationFrame(focusInput);
+  const blurInput = useCallback(() => {
+    inputRef.current?.blur();
+  }, []);
+
+  const configurePaneTextInputs = useCallback(() => {
+    const host = terminalHostRef.current;
+    if (!host) return;
+    for (const input of host.querySelectorAll<HTMLInputElement | HTMLTextAreaElement>('input, textarea')) {
+      if (input.inputMode !== 'none') input.inputMode = 'none';
+      if (input.autocomplete !== 'off') input.autocomplete = 'off';
+      if (!input.readOnly) input.readOnly = true;
+      if (input.tabIndex !== -1) input.tabIndex = -1;
     }
-  }, [activeSection, focusInput, onSectionChange]);
+  }, []);
+
+  const blurPaneTextInputs = useCallback(() => {
+    if (typeof document === 'undefined') return;
+    const blurActivePaneInput = () => {
+      configurePaneTextInputs();
+      inputRef.current?.blur();
+      const active = document.activeElement;
+      if (!(active instanceof HTMLElement)) return;
+      if (!terminalHostRef.current?.contains(active)) return;
+      if (
+        active instanceof HTMLInputElement
+        || active instanceof HTMLTextAreaElement
+        || active.isContentEditable
+      ) {
+        active.blur();
+      }
+    };
+    blurActivePaneInput();
+    window.setTimeout(blurActivePaneInput, 0);
+    window.setTimeout(blurActivePaneInput, 50);
+    window.setTimeout(blurActivePaneInput, 200);
+    window.requestAnimationFrame(blurActivePaneInput);
+  }, [configurePaneTextInputs]);
+
+  const setKeyboardMode = useCallback((nextMode: MobileTerminalKeyboardMode) => {
+    if (activeKeyboardMode === undefined && activeSection === undefined) {
+      setInternalKeyboardMode(nextMode);
+    }
+    onKeyboardModeChange?.(nextMode);
+    onSectionChange?.(nextMode);
+    if (nextMode === 'type') {
+      focusInput();
+    } else {
+      blurInput();
+    }
+  }, [activeKeyboardMode, activeSection, blurInput, focusInput, onKeyboardModeChange, onSectionChange]);
+
+  const setTouchMode = useCallback((nextMode: MobileTerminalTouchMode) => {
+    if (nextMode === 'cursor' && !cursorTouchAvailable) return;
+    if (activeTouchMode === undefined) setInternalTouchMode(nextMode);
+    onTouchModeChange?.(nextMode);
+  }, [activeTouchMode, cursorTouchAvailable, onTouchModeChange]);
 
   const flushInputValue = useCallback((value: string) => {
     if (value) sendInput(value);
@@ -211,7 +332,7 @@ export function MobileTerminalUi({
   }, [sendInput]);
 
   useEffect(() => {
-    if (section !== 'type' || !interactive) return;
+    if (keyboardMode !== 'type' || !interactive) return;
     const frame = window.requestAnimationFrame(focusInput);
     const delayedFocus = window.setTimeout(focusInput, 120);
     const settledFocus = window.setTimeout(focusInput, 500);
@@ -220,101 +341,153 @@ export function MobileTerminalUi({
       window.clearTimeout(delayedFocus);
       window.clearTimeout(settledFocus);
     };
-  }, [focusInput, interactive, section]);
+  }, [focusInput, interactive, keyboardMode]);
 
-  const rootStyle: MobileTerminalStyle = { ...style };
-  if (fillViewport && viewportHeight !== null) {
-    rootStyle['--mobile-terminal-visible-height'] = `${viewportHeight}px`;
-  }
+  useEffect(() => {
+    if (touchMode === 'cursor' && !cursorTouchAvailable) {
+      setTouchMode('gestures');
+    }
+  }, [cursorTouchAvailable, setTouchMode, touchMode]);
+
+  useEffect(() => {
+    const host = terminalHostRef.current;
+    if (!host) return;
+    configurePaneTextInputs();
+    const observer = new MutationObserver(configurePaneTextInputs);
+    observer.observe(host, {
+      childList: true,
+      subtree: true,
+    });
+    return () => observer.disconnect();
+  }, [configurePaneTextInputs, terminal]);
+
+  const handlePanePointerDownCapture = useCallback((event: PointerEvent<HTMLDivElement>) => {
+    blurPaneTextInputs();
+    if (!interactive || touchMode !== 'gestures') return;
+    if (event.pointerType === 'mouse') return;
+    event.preventDefault();
+    event.stopPropagation();
+    event.currentTarget.setPointerCapture(event.pointerId);
+    gestureStartRef.current = { pointerId: event.pointerId, x: event.clientX, y: event.clientY };
+  }, [interactive, touchMode]);
+
+  const handlePanePointerUpCapture = useCallback((event: PointerEvent<HTMLDivElement>) => {
+    const start = gestureStartRef.current;
+    if (!start || start.pointerId !== event.pointerId) return;
+    gestureStartRef.current = null;
+    event.preventDefault();
+    event.stopPropagation();
+
+    const dx = event.clientX - start.x;
+    const dy = event.clientY - start.y;
+    if (Math.max(Math.abs(dx), Math.abs(dy)) < 24) return;
+    if (Math.abs(dx) > Math.abs(dy)) {
+      sendInput(dx < 0 ? MOBILE_TERMINAL_KEY_SEQUENCES.left : MOBILE_TERMINAL_KEY_SEQUENCES.right);
+    } else {
+      sendInput(dy < 0 ? MOBILE_TERMINAL_KEY_SEQUENCES.up : MOBILE_TERMINAL_KEY_SEQUENCES.down);
+    }
+  }, [sendInput]);
+
+  const handlePaneFocusStartCapture = useCallback(() => {
+    blurPaneTextInputs();
+  }, [blurPaneTextInputs]);
+
+  const handlePanePointerCancelCapture = useCallback((event: PointerEvent<HTMLDivElement>) => {
+    if (gestureStartRef.current?.pointerId === event.pointerId) {
+      gestureStartRef.current = null;
+    }
+  }, []);
 
   return (
     <div
       data-mobile-terminal-ui
       className={clsx(
         'relative flex min-h-0 flex-col overflow-hidden bg-app-bg text-app-fg',
-        fillViewport ? 'h-[var(--mobile-terminal-visible-height,100dvh)]' : 'h-full',
+        fillViewport ? 'h-screen' : 'h-full',
         className,
       )}
-      style={rootStyle}
+      style={style}
     >
       <div
-        className={clsx('min-h-0 flex-1 overflow-hidden bg-terminal-bg', terminalClassName)}
-        onPointerDown={focusInput}
-        onPointerUp={focusInput}
+        ref={terminalHostRef}
+        className={clsx(
+          'min-h-0 flex-1 overflow-hidden bg-terminal-bg',
+          touchMode === 'gestures' ? 'touch-none' : 'touch-auto',
+          terminalClassName,
+        )}
+        onPointerDownCapture={handlePanePointerDownCapture}
+        onPointerUpCapture={handlePanePointerUpCapture}
+        onPointerCancelCapture={handlePanePointerCancelCapture}
+        onMouseDownCapture={handlePaneFocusStartCapture}
+        onTouchStartCapture={handlePaneFocusStartCapture}
       >
         <div className="flex h-full min-h-0 flex-col">{terminal}</div>
       </div>
 
-      {section === 'type' ? (
-        <div className="grid shrink-0 grid-cols-7 gap-1 border-t border-border bg-app-bg px-2 py-2">
-          {TERMINAL_KEYS.map((item) => (
-            <KeyButton
-              key={item.id}
-              item={item}
-              size="compact"
-              disabled={!interactive}
-              onPress={(id) => {
-                sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id]);
-                focusInput();
-              }}
-            />
-          ))}
-        </div>
-      ) : null}
-
-      {section === 'keys' ? (
-        <div className="grid shrink-0 gap-2 border-t border-border bg-app-bg px-3 py-3">
-          <div className="grid grid-cols-3 gap-2">
-            {TERMINAL_KEYS.slice(0, 3).map((item) => (
-              <KeyButton
-                key={item.id}
-                item={item}
-                size="large"
-                disabled={!interactive}
-                onPress={(id) => sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id])}
-              />
-            ))}
-          </div>
-          <div className="grid grid-cols-4 gap-2">
-            {TERMINAL_KEYS.slice(3).map((item) => (
-              <KeyButton
-                key={item.id}
-                item={item}
-                size="large"
-                disabled={!interactive}
-                onPress={(id) => sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id])}
-              />
-            ))}
-          </div>
-        </div>
-      ) : null}
-
-      {section === 'recent' || section === 'draft' ? <TodoPane section={section} /> : null}
-
-      <nav className="grid h-12 shrink-0 grid-cols-4 border-t border-border bg-app-bg font-mono text-sm">
-        {NAV_ITEMS.map((item) => {
-          const selected = item.id === section;
-          return (
-            <button
-              key={item.id}
-              type="button"
-              disabled={!interactive}
-              aria-current={selected ? 'page' : undefined}
-              onClick={() => setSection(item.id)}
-              className={clsx(
-                'min-w-0 border-t-2 px-1 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-focus-ring',
-                'disabled:pointer-events-none',
-                selected
-                  ? 'border-focus-ring bg-header-active-bg text-header-active-fg'
-                  : 'border-transparent text-muted hover:bg-header-inactive-bg hover:text-foreground',
-              )}
-            >
-              <span className="truncate">{item.label}</span>
-            </button>
-          );
-        })}
+      <TouchModeSelector
+        mode={touchMode}
+        cursorAvailable={cursorTouchAvailable}
+        disabled={!interactive}
+        onSelect={setTouchMode}
+      />
+
+      <nav className="grid h-10 shrink-0 grid-cols-4 border-t border-border bg-app-bg">
+        {KEYBOARD_MODES.map((item) => (
+          <KeyboardModeButton
+            key={item.id}
+            id={item.id}
+            label={item.label}
+            selected={item.id === keyboardMode}
+            disabled={!interactive}
+            onSelect={setKeyboardMode}
+          />
+        ))}
       </nav>
 
+      <div className="h-64 shrink-0 border-t border-border bg-app-bg">
+        {keyboardMode === 'recent' ? <WorkInProgressPane label="Recent" /> : null}
+        {keyboardMode === 'draft' ? <WorkInProgressPane label="Draft" /> : null}
+        {keyboardMode === 'type' ? (
+          <button
+            type="button"
+            disabled={!interactive}
+            aria-label="Focus terminal input"
+            onClick={focusInput}
+            className={clsx(
+              'grid h-full w-full place-items-center bg-app-bg text-terminal-fg transition-colors',
+              'focus-visible:outline focus-visible:outline-1 focus-visible:outline-inset focus-visible:outline-focus-ring',
+              'disabled:pointer-events-none disabled:opacity-60',
+            )}
+          >
+            <span aria-hidden="true" className="font-mono text-3xl leading-none text-focus-ring">▌</span>
+          </button>
+        ) : null}
+        {keyboardMode === 'keys' ? (
+          <div className="grid h-full grid-rows-2 gap-2 p-3">
+            <div className="grid grid-cols-4 gap-2">
+              {TERMINAL_KEYS.slice(0, 4).map((item) => (
+                <KeyButton
+                  key={item.id}
+                  item={item}
+                  disabled={!interactive}
+                  onPress={(id) => sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id])}
+                />
+              ))}
+            </div>
+            <div className="grid grid-cols-4 gap-2">
+              {TERMINAL_KEYS.slice(4).map((item) => (
+                <KeyButton
+                  key={item.id}
+                  item={item}
+                  disabled={!interactive}
+                  onPress={(id) => sendInput(MOBILE_TERMINAL_KEY_SEQUENCES[id])}
+                />
+              ))}
+            </div>
+          </div>
+        ) : null}
+      </div>
+
       <textarea
         ref={inputRef}
         aria-label="Terminal input"
diff --git a/lib/src/stories/MobileTerminalUi.stories.tsx b/lib/src/stories/MobileTerminalUi.stories.tsx
index 30010bf..e0f459a 100644
--- a/lib/src/stories/MobileTerminalUi.stories.tsx
+++ b/lib/src/stories/MobileTerminalUi.stories.tsx
@@ -21,6 +21,7 @@ const SEQUENCE_LABELS = new Map<string, string>([
   [MOBILE_TERMINAL_KEY_SEQUENCES.ctrlC, 'CTRL_C'],
   [MOBILE_TERMINAL_KEY_SEQUENCES.esc, 'ESC'],
   [MOBILE_TERMINAL_KEY_SEQUENCES.tab, 'TAB'],
+  [MOBILE_TERMINAL_KEY_SEQUENCES.space, 'SPACE'],
   [MOBILE_TERMINAL_KEY_SEQUENCES.enter, 'ENTER'],
   [MOBILE_TERMINAL_KEY_SEQUENCES.backspace, 'BACKSPACE'],
   [MOBILE_TERMINAL_KEY_SEQUENCES.up, 'ARROW_UP'],
@@ -109,3 +110,11 @@ export const NonInteractivePhoneMockup: Story = {
   },
   render: (args) => <StoryFrame {...args} />,
 };
+
+export const CursorTouchAvailable: Story = {
+  args: {
+    defaultSection: 'keys',
+    cursorTouchAvailable: true,
+  },
+  render: (args) => <StoryFrame {...args} />,
+};
diff --git a/website/src/pages/Tether.tsx b/website/src/pages/Tether.tsx
index 4073704..2669010 100644
--- a/website/src/pages/Tether.tsx
+++ b/website/src/pages/Tether.tsx
@@ -1,15 +1,23 @@
-import { useCallback, useEffect, useRef, useState, type ComponentType } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore, type ComponentType } from "react";
 import { ShareIcon } from "@phosphor-icons/react";
 import SiteHeader, { STATIC_PAGE_HEADER_STYLE } from "../components/SiteHeader";
 import { NotifySignupForm } from "../components/NotifySignupForm";
-import { MobileTerminalUi } from "mouseterm-lib/components/MobileTerminalUi";
+import { MobileTerminalUi, type MobileTerminalTouchMode } from "mouseterm-lib/components/MobileTerminalUi";
 import { ThemePicker } from "mouseterm-lib/components/ThemePicker";
 import { restoreActiveTheme } from "mouseterm-lib/lib/themes";
+import {
+  getMouseSelectionSnapshot,
+  setOverride as setMouseOverride,
+  subscribeToMouseSelection,
+} from "mouseterm-lib/lib/mouse-selection";
+import { PlaygroundShellRegistry } from "../lib/playground-shells";
+import { TutorialState } from "../lib/tutorial-state";
+import { BUSY_DEMO_DURATION_MS, BUSY_DEMO_INTERVAL_MS, TutRunner } from "../lib/tut-runner";
+import { ChangelogRunner } from "../lib/changelog-runner";
 
 export { Tether as Component };
 
 type FakePtyAdapter = import("mouseterm-lib/lib/platform/fake-adapter").FakePtyAdapter;
-type AsciiSplashRunner = import("../lib/ascii-splash-runner").AsciiSplashRunner;
 
 const TETHER_PANE = "tether-ascii-splash";
 const TETHER_THEME_ID = "vscode.theme-kimbie-dark.kimbie-dark";
@@ -19,9 +27,14 @@ interface WallModule {
 }
 
 interface DockviewApiLike {
+  activePanel?: { id?: string } | null;
   getPanel(id: string): { api: { setTitle(title: string): void; setActive(): void } } | undefined;
+  onDidAddPanel(listener: (panel: { id?: string } | undefined) => void): { dispose: () => void };
+  onDidActivePanelChange(listener: (panel: { id?: string } | undefined) => void): { dispose: () => void };
 }
 
+type DockviewDisposable = { dispose: () => void };
+
 function useIsMobileViewport() {
   const [isMobile, setIsMobile] = useState(false);
 
@@ -54,8 +67,30 @@ function TetherTerminalExperience({
   useTetherTheme();
   const [WallModule, setWallModule] = useState<WallModule | null>(null);
   const adapterRef = useRef<FakePtyAdapter | null>(null);
-  const runnerRef = useRef<AsciiSplashRunner | null>(null);
-  const restartingRef = useRef<number | null>(null);
+  const shellRegistryRef = useRef<PlaygroundShellRegistry | null>(null);
+  const dockviewDisposablesRef = useRef<DockviewDisposable[]>([]);
+  const autoStartedRef = useRef<Set<string>>(new Set());
+  const spawnUnsubRef = useRef<(() => void) | null>(null);
+  const busyDemoDisposeRef = useRef<(() => void) | null>(null);
+  const [activePaneId, setActivePaneId] = useState(TETHER_PANE);
+  const [touchMode, setTouchMode] = useState<MobileTerminalTouchMode>("gestures");
+  const mouseStates = useSyncExternalStore(
+    subscribeToMouseSelection,
+    getMouseSelectionSnapshot,
+    getMouseSelectionSnapshot,
+  );
+  const activeMouseState = mouseStates.get(activePaneId);
+  const cursorTouchAvailable = activeMouseState?.mouseReporting !== undefined
+    && activeMouseState.mouseReporting !== "none";
+
+  const tryAutoStart = useCallback((id: string) => {
+    if (id !== TETHER_PANE) return;
+    if (autoStartedRef.current.has(id)) return;
+    const shellRegistry = shellRegistryRef.current;
+    if (!shellRegistry) return;
+    autoStartedRef.current.add(id);
+    shellRegistry.ensureShell(id).runCommand("ascii-splash");
+  }, []);
 
   useEffect(() => {
     let cancelled = false;
@@ -64,6 +99,7 @@ function TetherTerminalExperience({
       const platform = await import("mouseterm-lib/lib/platform");
       const registry = await import("mouseterm-lib/lib/terminal-registry");
       const wall = await import("mouseterm-lib/components/Wall");
+      const scenarios = await import("mouseterm-lib/lib/platform/fake-scenarios");
       const asciiSplash = await import("../lib/ascii-splash-runner");
       await import("mouseterm-lib/index.css");
       if (cancelled) return;
@@ -73,67 +109,98 @@ function TetherTerminalExperience({
       adapter.reset();
       registry.initAlertStateReceiver();
       adapterRef.current = adapter;
-      adapter.clearDefaultScenario();
+      adapter.setDefaultScenario(scenarios.SCENARIO_SHELL_PROMPT);
       adapter.setScenario(TETHER_PANE, { name: "none", chunks: [] });
 
-      const startRunner = () => {
-        if (cancelled || runnerRef.current || !adapter.hasPty(TETHER_PANE)) return;
-        const runner = new asciiSplash.AsciiSplashRunner({
-          adapter,
-          terminalId: TETHER_PANE,
-          args: [],
-          onExit: () => {
-            runnerRef.current = null;
-            if (cancelled) return;
-            restartingRef.current = window.setTimeout(() => {
-              restartingRef.current = null;
-              startRunner();
-            }, 120);
-          },
-        });
-        runnerRef.current = runner;
-        runner.start();
-      };
-
-      adapter.setInputHandler(TETHER_PANE, (data) => {
-        runnerRef.current?.handleInput(data);
-      });
+      const tutorialState = new TutorialState();
+      const shellRegistry = new PlaygroundShellRegistry(
+        adapter,
+        (terminalId, name, args, onExit) => {
+          if (name === "tut") {
+            return new TutRunner({
+              adapter,
+              terminalId,
+              state: tutorialState,
+              onExit,
+              onTriggerBusyDemo: () => {
+                busyDemoDisposeRef.current?.();
+                busyDemoDisposeRef.current = adapter.pumpActivity(
+                  terminalId,
+                  BUSY_DEMO_DURATION_MS,
+                  BUSY_DEMO_INTERVAL_MS,
+                );
+              },
+              onTogglePlaceToPaste: () => {},
+            });
+          }
+          if (name === "ascii-splash" || name === "splash") {
+            return new asciiSplash.AsciiSplashRunner({
+              adapter,
+              terminalId,
+              args,
+              onExit,
+            });
+          }
+          if (name === "changelog") {
+            return new ChangelogRunner({ adapter, terminalId, onExit });
+          }
+          return null;
+        },
+      );
+      shellRegistryRef.current = shellRegistry;
+      shellRegistry.ensureShell(TETHER_PANE);
 
-      const unsubscribeSpawn = adapter.onPtySpawn(({ id }) => {
-        if (id === TETHER_PANE) startRunner();
+      spawnUnsubRef.current = adapter.onPtySpawn(({ id }) => {
+        shellRegistry.ensureShell(id);
+        tryAutoStart(id);
       });
-      if (adapter.hasPty(TETHER_PANE)) startRunner();
+      if (adapter.hasPty(TETHER_PANE)) tryAutoStart(TETHER_PANE);
 
       setWallModule({ Wall: wall.Wall });
-
-      return () => {
-        unsubscribeSpawn();
-      };
     }
 
-    let disposeSpawn: (() => void) | undefined;
-    loadWall().then((dispose) => {
-      if (cancelled) {
-        dispose?.();
-      } else {
-        disposeSpawn = dispose;
-      }
-    });
+    loadWall();
 
     return () => {
       cancelled = true;
-      disposeSpawn?.();
-      if (restartingRef.current !== null) {
-        window.clearTimeout(restartingRef.current);
-        restartingRef.current = null;
+      for (const disposable of dockviewDisposablesRef.current) {
+        disposable.dispose();
       }
-      runnerRef.current?.dispose();
-      runnerRef.current = null;
-      adapterRef.current?.clearInputHandler(TETHER_PANE);
+      dockviewDisposablesRef.current = [];
+      spawnUnsubRef.current?.();
+      spawnUnsubRef.current = null;
+      busyDemoDisposeRef.current?.();
+      busyDemoDisposeRef.current = null;
+      shellRegistryRef.current?.disposeAll();
+      shellRegistryRef.current = null;
+      autoStartedRef.current.clear();
+      adapterRef.current = null;
     };
-  }, []);
+  }, [tryAutoStart]);
+
+  useEffect(() => {
+    const reporting = activeMouseState?.mouseReporting ?? "none";
+    if (touchMode === "selection" && reporting !== "none") {
+      setMouseOverride(activePaneId, "permanent");
+    } else {
+      setMouseOverride(activePaneId, "off");
+    }
+  }, [activeMouseState?.mouseReporting, activePaneId, touchMode]);
 
   const handleApiReady = useCallback((api: DockviewApiLike) => {
+    const addDisposable = api.onDidAddPanel((panel) => {
+      if (panel?.id) shellRegistryRef.current?.ensureShell(panel.id);
+    });
+    dockviewDisposablesRef.current.push(addDisposable);
+
+    const activeDisposable = api.onDidActivePanelChange((panel) => {
+      if (panel?.id) setActivePaneId(panel.id);
+    });
+    dockviewDisposablesRef.current.push(activeDisposable);
+
+    setActivePaneId(api.activePanel?.id ?? TETHER_PANE);
+    shellRegistryRef.current?.ensureShell(TETHER_PANE);
+
     const panel = api.getPanel(TETHER_PANE);
     if (!panel) return;
     panel.api.setTitle("ascii-splash");
@@ -154,7 +221,10 @@ function TetherTerminalExperience({
       }
       interactive={interactive}
       fillViewport={fillViewport}
-      onSendInput={(data) => adapterRef.current?.writePty(TETHER_PANE, data)}
+      activeTouchMode={touchMode}
+      onTouchModeChange={setTouchMode}
+      cursorTouchAvailable={cursorTouchAvailable}
+      onSendInput={(data) => adapterRef.current?.writePty(activePaneId, data)}
     />
   );
 }

From 5b4156bada9ec5f7b74ea8f0b55f65136bb4a3eb Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 11 May 2026 17:53:40 -0700
Subject: [PATCH 09/12] Improve tether mobile selectors

---
 docs/specs/mobile-ui.md                 |  32 +++---
 lib/src/components/MobileTerminalUi.tsx | 130 ++++++++++++++++--------
 2 files changed, 106 insertions(+), 56 deletions(-)

diff --git a/docs/specs/mobile-ui.md b/docs/specs/mobile-ui.md
index a4199ef..5b92e0e 100644
--- a/docs/specs/mobile-ui.md
+++ b/docs/specs/mobile-ui.md
@@ -55,9 +55,9 @@ The mobile UI is split into fixed and flexible regions:
 ├─────────────────────────┤
 │ Pane content             │ flexible terminal area
 ├─────────────────────────┤
-│ Touch mode selector      │ thin, always visible
+│ Touch mode selector      │ labeled, always visible
 ├─────────────────────────┤
-│ Keyboard mode selector   │ thin, always visible
+│ Keyboard mode selector   │ labeled, always visible
 ├─────────────────────────┤
 │ Keyboard reserve area    │ stable height
 │                         │
@@ -76,16 +76,20 @@ does not bounce while the OS keyboard animates.
 ## 4. Touch Mode Selector
 
 The touch selector controls what happens when the user touches the pane content
-area. It is thin and always visible between the terminal content and the
-keyboard mode selector.
+area. It is always visible between the terminal content and the keyboard mode
+selector.
+
+The selector must be self-labeling. It should use a compact left-side `Touch`
+label plus segmented buttons that include both an icon and a short mode label.
+Icon-only touch controls are too hard to discover in this prototype.
 
 Touch modes:
 
-| Mode | Icon | Availability | Behavior |
-| --- | --- | --- | --- |
-| Gestures | `HandPointingIcon` | Always available | Touch drags generate arrow keys. Drag left sends left, drag right sends right, drag up sends up, and drag down sends down. |
-| Text selection | `CursorTextIcon` | Always available | Touches are reserved for terminal text selection and copy/paste. If the TUI is capturing mouse events, MouseTerm activates mouse override for the active pane. |
-| Cursor | `CursorClickIcon` | Only when the active TUI is capturing mouse events | Touches are passed through as terminal mouse/cursor input. |
+| Mode | Button label | Icon | Availability | Behavior |
+| --- | --- | --- | --- | --- |
+| Gestures | `Gestures` | `HandPointingIcon` | Always available | Touch drags generate arrow keys. Drag left sends left, drag right sends right, drag up sends up, and drag down sends down. |
+| Text selection | `Select` | `CursorTextIcon` | Always available | Touches are reserved for terminal text selection and copy/paste. If the TUI is capturing mouse events, MouseTerm activates mouse override for the active pane. |
+| Cursor | `Cursor` | `CursorClickIcon` | Only when the active TUI is capturing mouse events | Touches are passed through as terminal mouse/cursor input. |
 
 Default touch mode is **Gestures**.
 
@@ -95,12 +99,16 @@ selector must fall back to Gestures.
 ## 5. Keyboard Mode Selector
 
 The keyboard mode selector controls what appears in the keyboard reserve area.
-It is thin, always visible, and has four items:
+It is always visible and has four items:
 
 ```text
 Recent | Type | Draft | Keys
 ```
 
+The selector must be self-labeling. It should use a compact left-side `Input`
+label plus segmented text buttons. The label describes the reserve area's
+purpose without adding a longer instruction line.
+
 Keyboard modes:
 
 | Mode | Reserve area content |
@@ -262,13 +270,13 @@ Build exactly this:
 * Touch mode selector:
 
 ```text
-Gestures | Text selection | Cursor
+Touch  Gestures | Select | Cursor
 ```
 
 * Keyboard mode selector:
 
 ```text
-Recent | Type | Draft | Keys
+Input  Recent | Type | Draft | Keys
 ```
 
 * Stable keyboard reserve area.
diff --git a/lib/src/components/MobileTerminalUi.tsx b/lib/src/components/MobileTerminalUi.tsx
index f07d244..407999b 100644
--- a/lib/src/components/MobileTerminalUi.tsx
+++ b/lib/src/components/MobileTerminalUi.tsx
@@ -60,12 +60,13 @@ const KEYBOARD_MODES: { id: MobileTerminalKeyboardMode; label: string }[] = [
 const TOUCH_MODES: Array<{
   id: MobileTerminalTouchMode;
   label: string;
+  shortLabel: string;
   title: string;
   Icon: ComponentType<{ size?: number; weight?: 'regular' | 'bold' | 'duotone' | 'fill' }>;
 }> = [
-  { id: 'gestures', label: 'Gestures', title: 'Gestures', Icon: HandPointingIcon },
-  { id: 'selection', label: 'Text selection', title: 'Text selection', Icon: CursorTextIcon },
-  { id: 'cursor', label: 'Cursor', title: 'Cursor', Icon: CursorClickIcon },
+  { id: 'gestures', label: 'Gestures', shortLabel: 'Gestures', title: 'Gestures: drags send arrow keys', Icon: HandPointingIcon },
+  { id: 'selection', label: 'Text selection', shortLabel: 'Select', title: 'Text selection: touches select terminal text', Icon: CursorTextIcon },
+  { id: 'cursor', label: 'Cursor', shortLabel: 'Cursor', title: 'Cursor: touches send terminal mouse events', Icon: CursorClickIcon },
 ];
 
 export interface MobileTerminalUiProps {
@@ -162,14 +163,15 @@ function KeyboardModeButton({
       key={id}
       type="button"
       disabled={disabled}
+      aria-label={`${label} keyboard mode`}
       aria-current={selected ? 'page' : undefined}
       onClick={() => onSelect(id)}
       className={clsx(
-        'min-w-0 border-t-2 px-1 font-mono text-sm transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-focus-ring',
+        'min-w-0 rounded px-1.5 py-1 font-mono text-xs leading-none transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-1 focus-visible:outline-focus-ring',
         'disabled:pointer-events-none disabled:opacity-60',
         selected
-          ? 'border-focus-ring bg-header-active-bg text-header-active-fg'
-          : 'border-transparent text-muted hover:bg-header-inactive-bg hover:text-foreground',
+          ? 'bg-header-active-bg text-header-active-fg shadow-[inset_0_0_0_1px_var(--color-focus-ring)]'
+          : 'text-muted hover:bg-header-inactive-bg hover:text-foreground',
       )}
     >
       <span className="truncate">{label}</span>
@@ -177,6 +179,14 @@ function KeyboardModeButton({
   );
 }
 
+function SelectorLabel({ children }: { children: ReactNode }) {
+  return (
+    <div className="w-[4.5rem] shrink-0 pl-2 pr-1 font-mono text-[11px] leading-none text-muted">
+      {children}
+    </div>
+  );
+}
+
 function TouchModeSelector({
   mode,
   cursorAvailable,
@@ -189,33 +199,72 @@ function TouchModeSelector({
   onSelect: (mode: MobileTerminalTouchMode) => void;
 }) {
   return (
-    <div className="grid h-10 shrink-0 grid-cols-3 border-t border-border bg-app-bg">
-      {TOUCH_MODES.map((item) => {
-        const selected = item.id === mode;
-        const itemDisabled = disabled || (item.id === 'cursor' && !cursorAvailable);
-        const Icon = item.Icon;
-        return (
-          <button
+    <section
+      aria-label="Touch mode"
+      className="flex h-12 shrink-0 items-center border-t border-border bg-app-bg"
+    >
+      <SelectorLabel>Touch</SelectorLabel>
+      <div className="mr-2 grid min-w-0 flex-1 grid-cols-3 gap-1 rounded bg-surface-raised p-1 shadow-[inset_0_0_0_1px_var(--color-border)]">
+        {TOUCH_MODES.map((item) => {
+          const selected = item.id === mode;
+          const itemDisabled = disabled || (item.id === 'cursor' && !cursorAvailable);
+          const Icon = item.Icon;
+          return (
+            <button
+              key={item.id}
+              type="button"
+              title={item.title}
+              aria-label={item.label}
+              aria-pressed={selected}
+              disabled={itemDisabled}
+              onClick={() => onSelect(item.id)}
+              className={clsx(
+                'flex min-w-0 items-center justify-center gap-1 rounded px-1.5 py-1 font-mono text-xs leading-none transition-colors',
+                'focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-1 focus-visible:outline-focus-ring',
+                'disabled:pointer-events-none disabled:opacity-35',
+                selected
+                  ? 'bg-header-active-bg text-header-active-fg shadow-[inset_0_0_0_1px_var(--color-focus-ring)]'
+                  : 'text-muted hover:bg-header-inactive-bg hover:text-foreground',
+              )}
+            >
+              <Icon size={15} weight={selected ? 'bold' : 'regular'} />
+              <span className="truncate">{item.shortLabel}</span>
+            </button>
+          );
+        })}
+      </div>
+    </section>
+  );
+}
+
+function KeyboardModeSelector({
+  mode,
+  disabled,
+  onSelect,
+}: {
+  mode: MobileTerminalKeyboardMode;
+  disabled: boolean;
+  onSelect: (mode: MobileTerminalKeyboardMode) => void;
+}) {
+  return (
+    <section
+      aria-label="Keyboard mode"
+      className="flex h-12 shrink-0 items-center border-t border-border bg-app-bg"
+    >
+      <SelectorLabel>Input</SelectorLabel>
+      <nav className="mr-2 grid min-w-0 flex-1 grid-cols-4 gap-1 rounded bg-surface-raised p-1 shadow-[inset_0_0_0_1px_var(--color-border)]">
+        {KEYBOARD_MODES.map((item) => (
+          <KeyboardModeButton
             key={item.id}
-            type="button"
-            title={item.title}
-            aria-label={item.label}
-            aria-pressed={selected}
-            disabled={itemDisabled}
-            onClick={() => onSelect(item.id)}
-            className={clsx(
-              'grid min-w-0 place-items-center border-t-2 transition-colors focus-visible:outline focus-visible:outline-1 focus-visible:outline-focus-ring',
-              'disabled:pointer-events-none disabled:opacity-35',
-              selected
-                ? 'border-focus-ring bg-header-active-bg text-header-active-fg'
-                : 'border-transparent text-muted hover:bg-header-inactive-bg hover:text-foreground',
-            )}
-          >
-            <Icon size={18} weight={selected ? 'bold' : 'regular'} />
-          </button>
-        );
-      })}
-    </div>
+            id={item.id}
+            label={item.label}
+            selected={item.id === mode}
+            disabled={disabled}
+            onSelect={onSelect}
+          />
+        ))}
+      </nav>
+    </section>
   );
 }
 
@@ -431,18 +480,11 @@ export function MobileTerminalUi({
         onSelect={setTouchMode}
       />
 
-      <nav className="grid h-10 shrink-0 grid-cols-4 border-t border-border bg-app-bg">
-        {KEYBOARD_MODES.map((item) => (
-          <KeyboardModeButton
-            key={item.id}
-            id={item.id}
-            label={item.label}
-            selected={item.id === keyboardMode}
-            disabled={!interactive}
-            onSelect={setKeyboardMode}
-          />
-        ))}
-      </nav>
+      <KeyboardModeSelector
+        mode={keyboardMode}
+        disabled={!interactive}
+        onSelect={setKeyboardMode}
+      />
 
       <div className="h-64 shrink-0 border-t border-border bg-app-bg">
         {keyboardMode === 'recent' ? <WorkInProgressPane label="Recent" /> : null}

From 682df3733e83d6c04df7ad9e9dccb0e9d412fcb8 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 11 May 2026 17:54:10 -0700
Subject: [PATCH 10/12] Impeccable v2 -> v3 transition

---
 .impeccable.md => PRODUCT.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename .impeccable.md => PRODUCT.md (100%)

diff --git a/.impeccable.md b/PRODUCT.md
similarity index 100%
rename from .impeccable.md
rename to PRODUCT.md

From 4a3f6dd23d54cb0046f0dd830ef6f57b9319d6c0 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 11 May 2026 21:04:58 -0700
Subject: [PATCH 11/12] Add DESIGN.md and PRODUCT.md register field

Documents the host-theme-driven design system (six-section Stitch
format) and adds the impeccable v3 register field to PRODUCT.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .impeccable/design.json | 281 ++++++++++++++++++++++++++++++++++++++++
 DESIGN.md               | 269 ++++++++++++++++++++++++++++++++++++++
 PRODUCT.md              |   4 +
 3 files changed, 554 insertions(+)
 create mode 100644 .impeccable/design.json
 create mode 100644 DESIGN.md

diff --git a/.impeccable/design.json b/.impeccable/design.json
new file mode 100644
index 0000000..57df9e3
--- /dev/null
+++ b/.impeccable/design.json
@@ -0,0 +1,281 @@
+{
+  "schemaVersion": 2,
+  "generatedAt": "2026-05-11T00:00:00Z",
+  "title": "Design System: MouseTerm",
+  "extensions": {
+    "colorMeta": {
+      "app-bg": {
+        "role": "neutral",
+        "displayName": "App Background (Host Sidebar)",
+        "canonical": "var(--vscode-sideBar-background)",
+        "tonalRamp": ["#0d0905", "#150e07", "#1a1309", "#221a0f", "#2b2114", "#3a2c1a", "#5e452e", "#8a6843"]
+      },
+      "app-fg": {
+        "role": "neutral",
+        "displayName": "App Foreground (Host Sidebar Text)",
+        "canonical": "var(--vscode-sideBar-foreground)",
+        "tonalRamp": ["#3a2c1a", "#5e452e", "#8a6843", "#a98968", "#c7a07d", "#d3af86", "#e3c5a3", "#efdac4"]
+      },
+      "surface-raised": {
+        "role": "neutral",
+        "displayName": "Raised Surface (Popovers, Dialogs)",
+        "canonical": "var(--vscode-editorWidget-background)",
+        "tonalRamp": ["#15100a", "#1d150c", "#241a10", "#2b2114", "#33271a", "#3e3020", "#5e452e", "#8a6843"]
+      },
+      "foreground": {
+        "role": "neutral",
+        "displayName": "Primary Foreground",
+        "canonical": "var(--vscode-editor-foreground)",
+        "tonalRamp": ["#3a2c1a", "#5e452e", "#8a6843", "#a98968", "#c7a07d", "#d3af86", "#e3c5a3", "#efdac4"]
+      },
+      "muted": {
+        "role": "neutral",
+        "displayName": "Muted Foreground (Shortcuts, Hints)",
+        "canonical": "var(--vscode-descriptionForeground)",
+        "tonalRamp": ["#3a2c1a", "#5e452e", "#776046", "#8a6843", "#9a7a52", "#a98968", "#c7a07d", "#d3af86"]
+      },
+      "border": {
+        "role": "neutral",
+        "displayName": "Panel Border (Hairline on Raised Surfaces)",
+        "canonical": "var(--vscode-panel-border)",
+        "tonalRamp": ["#221a0f", "#2b2114", "#3a2c1a", "#4a3823", "#5e452e", "#6f5538", "#8a6843", "#a98968"]
+      },
+      "header-active-bg": {
+        "role": "primary",
+        "displayName": "Focused Header (the closest thing to an accent)",
+        "canonical": "var(--vscode-list-activeSelectionBackground)",
+        "tonalRamp": ["#2e2410", "#3e3018", "#523f20", "#665128", "#7e602f", "#9a7638", "#b58c45", "#cda35a"]
+      },
+      "header-active-fg": {
+        "role": "primary",
+        "displayName": "Focused Header Text",
+        "canonical": "var(--vscode-list-activeSelectionForeground)",
+        "tonalRamp": ["#8a6843", "#a98968", "#c7a07d", "#d3af86", "#e3c5a3", "#efdac4", "#f5e8d6", "#ffffff"]
+      },
+      "header-inactive-bg": {
+        "role": "secondary",
+        "displayName": "Unfocused Header",
+        "canonical": "var(--vscode-list-inactiveSelectionBackground)",
+        "tonalRamp": ["#221a0f", "#2b2114", "#3a2c1a", "#4a3823", "#5e452e", "#6f5538", "#8a6843", "#a98968"]
+      },
+      "header-inactive-fg": {
+        "role": "secondary",
+        "displayName": "Unfocused Header Text",
+        "canonical": "var(--vscode-list-inactiveSelectionForeground)",
+        "tonalRamp": ["#5e452e", "#8a6843", "#a98968", "#c7a07d", "#d3af86", "#e3c5a3", "#efdac4", "#f5e8d6"]
+      },
+      "door-bg": {
+        "role": "tertiary",
+        "displayName": "Door (runtime-picked for OKLab separation)",
+        "canonical": "var(--color-door-bg)",
+        "tonalRamp": ["#221a0f", "#2b2114", "#3a2c1a", "#4a3823", "#5e452e", "#6f5538", "#8a6843", "#a98968"]
+      },
+      "door-fg": {
+        "role": "tertiary",
+        "displayName": "Door Text",
+        "canonical": "var(--color-door-fg)",
+        "tonalRamp": ["#5e452e", "#8a6843", "#a98968", "#c7a07d", "#d3af86", "#e3c5a3", "#efdac4", "#f5e8d6"]
+      },
+      "focus-ring": {
+        "role": "tertiary",
+        "displayName": "Focus Ring (runtime-picked for chroma)",
+        "canonical": "var(--color-focus-ring)",
+        "tonalRamp": ["#5e452e", "#8a6843", "#a98968", "#c7a07d", "#d3af86", "#e3c5a3", "#f9d181", "#fee9b3"]
+      },
+      "terminal-bg": {
+        "role": "neutral",
+        "displayName": "Terminal Background (orthogonal to chrome)",
+        "canonical": "var(--vscode-terminal-background)",
+        "tonalRamp": ["#0d0905", "#150e07", "#1a1309", "#221a0f", "#2b2114", "#3a2c1a", "#4a3823", "#5e452e"]
+      },
+      "terminal-fg": {
+        "role": "neutral",
+        "displayName": "Terminal Foreground",
+        "canonical": "var(--vscode-terminal-foreground)",
+        "tonalRamp": ["#5e452e", "#8a6843", "#a98968", "#c7a07d", "#d3af86", "#e3c5a3", "#efdac4", "#f5e8d6"]
+      },
+      "input-bg": {
+        "role": "neutral",
+        "displayName": "Input Background",
+        "canonical": "var(--vscode-input-background)",
+        "tonalRamp": ["#15100a", "#1d150c", "#241a10", "#2b2114", "#33271a", "#3e3020", "#5e452e", "#8a6843"]
+      },
+      "input-border": {
+        "role": "neutral",
+        "displayName": "Input Border",
+        "canonical": "var(--vscode-input-border)",
+        "tonalRamp": ["#221a0f", "#2b2114", "#3a2c1a", "#4a3823", "#5e452e", "#6f5538", "#8a6843", "#a98968"]
+      },
+      "error": {
+        "role": "primary",
+        "displayName": "Error / Destructive (terminal ANSI red)",
+        "canonical": "var(--vscode-terminal-ansiRed)",
+        "tonalRamp": ["#3d1e10", "#5a2c17", "#75381e", "#984828", "#cc6633", "#d97f4f", "#e29a72", "#ecbfa1"]
+      },
+      "success": {
+        "role": "primary",
+        "displayName": "Success / Affirm (terminal ANSI green)",
+        "canonical": "var(--vscode-terminal-ansiGreen)",
+        "tonalRamp": ["#293119", "#3d4824", "#52602f", "#6a7a3a", "#889b4a", "#9eaf60", "#b5c280", "#cdd6a4"]
+      },
+      "alarm": {
+        "role": "primary",
+        "displayName": "Alarm / Bell (terminal ANSI yellow, runtime-rotated per surface)",
+        "canonical": "var(--vscode-terminal-ansiYellow)",
+        "tonalRamp": ["#4a3818", "#6e5424", "#917030", "#b58c45", "#d3a85c", "#f9d181", "#fbdda3", "#fee9b3"]
+      },
+      "window-close-hover": {
+        "role": "primary",
+        "displayName": "Window Close Hover (native OS red, the only literal)",
+        "canonical": "#b92a1b",
+        "tonalRamp": ["#3d0e09", "#5a160d", "#751c12", "#982618", "#b92a1b", "#cf493a", "#dd6e60", "#e89889"]
+      }
+    },
+    "typographyMeta": {
+      "body": {
+        "displayName": "Body (the workhorse step)",
+        "purpose": "Pane headers, doors, button labels, popup contents. Almost everything sits here."
+      },
+      "label": {
+        "displayName": "Label (tiny, wide tracking)",
+        "purpose": "TODO pills, kill-confirm hints, anything that has to be readable at 10px."
+      },
+      "shortcut": {
+        "displayName": "Shortcut [bracketed]",
+        "purpose": "Keybinding hints, always rendered through <Shortcut> or renderShortcuts()."
+      }
+    },
+    "shadows": [
+      { "name": "popover", "value": "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)", "purpose": "Tooltips, selection popup, header tooltips. Surface is in the air, not heavy." },
+      { "name": "dialog",  "value": "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)", "purpose": "Kill-confirm sheet, TODO alert dialog. Floats above chrome." },
+      { "name": "modal",   "value": "0 25px 50px -12px rgb(0 0 0 / 0.25)", "purpose": "Theme picker dropdown, theme debugger, theme store. Top-of-app surface." },
+      { "name": "inset-focus-ring", "value": "inset 0 0 0 1px var(--color-focus-ring)", "purpose": "Mobile segmented-control selected state. Inset because a border would shift layout on toggle." },
+      { "name": "inset-border", "value": "inset 0 0 0 1px var(--color-border)", "purpose": "Mobile segmented-control container. Same layout-stability reason." }
+    ],
+    "motion": [
+      { "name": "ease-quart-out",      "value": "cubic-bezier(0.22, 1, 0.36, 1)",  "purpose": "Default for pane spawn/kill and any layout-adjacent transition. Exponential ease-out, no bounce." },
+      { "name": "spring-overshoot",    "value": "cubic-bezier(0.34, 1.56, 0.64, 1)", "purpose": "Reserved for celebratory state-resolution: TODO check pop-in, kill-confirm letter flash, copy-confirm scale. Used only at 220–500ms; never on layout." },
+      { "name": "ease-in-out-bell",    "value": "ease-in-out", "purpose": "Bell ring continuous animation (800ms, infinite, alternating ±45deg rotation)." },
+      { "name": "ease-out-shake",      "value": "ease-out",    "purpose": "Kill-overlay shake-x (400ms, x-axis only)." },
+      { "name": "duration-pane",       "value": "440ms", "purpose": "Pane spawn and kill choreography." },
+      { "name": "duration-flourish",   "value": "500ms", "purpose": "TODO pill dismiss sequence." },
+      { "name": "duration-confirm",    "value": "220ms", "purpose": "Kill-overlay confirm letter flash." },
+      { "name": "duration-copy-flash", "value": "260ms", "purpose": "Selection popup copy-confirm scale flash." },
+      { "name": "duration-bell-ring",  "value": "800ms", "purpose": "One full ring cycle." },
+      { "name": "duration-shake",      "value": "400ms", "purpose": "Kill-cancel shake-x." }
+    ],
+    "breakpoints": [
+      { "name": "md", "value": "768px" }
+    ]
+  },
+  "components": [
+    {
+      "name": "Door",
+      "kind": "custom",
+      "refersTo": "door",
+      "description": "Pane-header indicator on the baseboard. Top corners rounded, square bottom; the signature component of the system.",
+      "html": "<button class=\"ds-door\" type=\"button\" title=\"build\"><span class=\"ds-door__title\">build</span><span class=\"ds-door__badges\"><span class=\"ds-todo-pill\">TODO</span><svg class=\"ds-door__bell\" viewBox=\"0 0 256 256\" width=\"11\" height=\"11\" aria-hidden=\"true\"><path fill=\"currentColor\" d=\"M221.8 175.94C216.25 166.38 208 139.33 208 104a80 80 0 1 0-160 0c0 35.34-8.26 62.38-13.81 71.94A16 16 0 0 0 48 200h40.81a40 40 0 0 0 78.38 0H208a16 16 0 0 0 13.8-24.06ZM128 216a24 24 0 0 1-22.62-16h45.24A24 24 0 0 1 128 216Z\"/></svg></span></button>",
+      "css": ".ds-door { display: flex; align-items: center; gap: 8px; height: 24px; min-width: 68px; max-width: 220px; padding: 0 10px; overflow: hidden; border: none; border-radius: 8px 8px 0 0; background: var(--color-door-bg, #5e452e); color: var(--color-door-fg, #d3af86); font-family: var(--vscode-editor-font-family, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.75rem; line-height: 1rem; font-weight: 500; cursor: pointer; } .ds-door__title { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; text-align: left; } .ds-door__badges { display: flex; align-items: center; gap: 6px; flex-shrink: 0; } .ds-door__bell { color: var(--vscode-terminal-ansiYellow, #f9d181); }"
+    },
+    {
+      "name": "Pane Header (Active)",
+      "kind": "nav",
+      "refersTo": "header-active-bg",
+      "description": "Focused pane header tab. The bg swap between this and the inactive variant is the entire focus affordance.",
+      "html": "<div class=\"ds-pane-header ds-pane-header--active\"><span class=\"ds-pane-header__title\">~/src/lib · pnpm dev</span><div class=\"ds-pane-header__actions\"><button class=\"ds-header-btn\" aria-label=\"Toggle alert\"><svg viewBox=\"0 0 256 256\" width=\"14\" height=\"14\" aria-hidden=\"true\"><path fill=\"currentColor\" d=\"M221.8 175.94C216.25 166.38 208 139.33 208 104a80 80 0 1 0-160 0c0 35.34-8.26 62.38-13.81 71.94A16 16 0 0 0 48 200h40.81a40 40 0 0 0 78.38 0H208a16 16 0 0 0 13.8-24.06Z\"/></svg></button><button class=\"ds-header-btn\" aria-label=\"Kill\"><svg viewBox=\"0 0 256 256\" width=\"14\" height=\"14\" aria-hidden=\"true\"><path fill=\"currentColor\" d=\"M205.66 194.34a8 8 0 0 1-11.32 11.32L128 139.31l-66.34 66.35a8 8 0 0 1-11.32-11.32L116.69 128 50.34 61.66a8 8 0 0 1 11.32-11.32L128 116.69l66.34-66.35a8 8 0 0 1 11.32 11.32L139.31 128Z\"/></svg></button></div></div>",
+      "css": ".ds-pane-header { display: flex; align-items: center; gap: 8px; height: 30px; padding: 0 10px; border-radius: 8px 8px 0 0; font-family: var(--vscode-editor-font-family, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.75rem; font-weight: 500; } .ds-pane-header--active { background: var(--vscode-list-activeSelectionBackground, #7e602f); color: var(--vscode-list-activeSelectionForeground, #ffffff); } .ds-pane-header__title { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; } .ds-pane-header__actions { display: flex; gap: 2px; flex-shrink: 0; } .ds-header-btn { display: flex; align-items: center; justify-content: center; width: 20px; height: 20px; padding: 0; border: none; border-radius: 4px; background: transparent; color: inherit; cursor: pointer; transition: background 120ms cubic-bezier(0.22, 1, 0.36, 1); } .ds-header-btn:hover { background: color-mix(in srgb, currentColor 10%, transparent); } .ds-header-btn:focus-visible { outline: 1px solid var(--color-focus-ring, #f9d181); outline-offset: 1px; }"
+    },
+    {
+      "name": "Pane Header (Inactive)",
+      "kind": "nav",
+      "refersTo": "header-inactive-bg",
+      "description": "Unfocused pane header. Identical geometry to active; only the background and foreground differ.",
+      "html": "<div class=\"ds-pane-header ds-pane-header--inactive\"><span class=\"ds-pane-header__title\">~/src/web · vite preview</span></div>",
+      "css": ".ds-pane-header--inactive { background: var(--vscode-list-inactiveSelectionBackground, #5e452e); color: var(--vscode-list-inactiveSelectionForeground, #d3af86); }"
+    },
+    {
+      "name": "Window Close Button",
+      "kind": "button",
+      "refersTo": "chrome-button-window-close",
+      "description": "Windows/Linux native-style window close. The one place a literal hex (#b92a1b) is allowed in the system, because the platform convention is a hard red.",
+      "html": "<button class=\"ds-win-close\" aria-label=\"Close\"><svg viewBox=\"0 0 256 256\" width=\"12\" height=\"12\" aria-hidden=\"true\"><path fill=\"currentColor\" d=\"M205.66 194.34a8 8 0 0 1-11.32 11.32L128 139.31l-66.34 66.35a8 8 0 0 1-11.32-11.32L116.69 128 50.34 61.66a8 8 0 0 1 11.32-11.32L128 116.69l66.34-66.35a8 8 0 0 1 11.32 11.32L139.31 128Z\"/></svg></button>",
+      "css": ".ds-win-close { display: flex; align-items: center; justify-content: center; width: 44px; height: 20px; padding: 0; border: none; background: transparent; color: inherit; cursor: pointer; transition: background 120ms cubic-bezier(0.22, 1, 0.36, 1); } .ds-win-close:hover { background: #b92a1b; color: #ffffff; }"
+    },
+    {
+      "name": "Tooltip / Popup Button Row",
+      "kind": "card",
+      "refersTo": "popup-button-row",
+      "description": "The raised-surface primitive. Used as a tooltip body, a selection popup, and an illegal-rename warning. Always carries the popover shadow.",
+      "html": "<div class=\"ds-popup\" role=\"tooltip\"><span class=\"ds-popup__line\">Kill pane</span><span class=\"ds-popup__line\"><span class=\"ds-shortcut\">[⌘W]</span></span></div>",
+      "css": ".ds-popup { display: inline-flex; flex-direction: column; gap: 2px; padding: 6px 8px; background: var(--vscode-editorWidget-background, #2b2114); color: var(--vscode-editor-foreground, #d3af86); border: 1px solid var(--vscode-panel-border, #5e452e); border-radius: 4px; box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1); font-family: var(--vscode-editor-font-family, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.75rem; line-height: 1rem; font-weight: 500; white-space: nowrap; } .ds-popup__line { display: block; } .ds-shortcut { color: var(--vscode-descriptionForeground, #a98968); }"
+    },
+    {
+      "name": "Kill Confirm Dialog",
+      "kind": "card",
+      "refersTo": "kill-confirm-dialog",
+      "description": "The kill-confirmation sheet that appears centered over a focused pane. Uses surface-raised + dialog shadow + the spring-overshoot curve when the user confirms.",
+      "html": "<div class=\"ds-kill\" role=\"dialog\" aria-label=\"Confirm kill\"><div class=\"ds-kill__title\">Kill <span class=\"ds-kill__name\">pnpm dev</span>?</div><div class=\"ds-kill__hint\"><span class=\"ds-shortcut\">[y]</span> confirm <span class=\"ds-shortcut\">[n]</span> cancel</div></div>",
+      "css": ".ds-kill { display: inline-flex; flex-direction: column; gap: 6px; padding: 16px 24px; background: var(--vscode-editorWidget-background, #2b2114); color: var(--vscode-editor-foreground, #d3af86); border: 1px solid var(--vscode-panel-border, #5e452e); border-radius: 8px; box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1); font-family: var(--vscode-editor-font-family, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.75rem; text-align: center; } .ds-kill__title { font-weight: 500; } .ds-kill__name { color: var(--vscode-terminal-ansiRed, #cc6633); font-weight: 600; } .ds-kill__hint { color: var(--vscode-descriptionForeground, #a98968); font-size: 0.625rem; }"
+    },
+    {
+      "name": "TODO Pill",
+      "kind": "chip",
+      "refersTo": "todo-pill",
+      "description": "Tiny inline label inside pane headers and doors. The wider tracking (0.08em) is mandatory at this 10px size; without it the letters smear.",
+      "html": "<span class=\"ds-todo-pill\">TODO</span>",
+      "css": ".ds-todo-pill { display: inline-block; padding: 0 2px; font-family: var(--vscode-editor-font-family, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.625rem; line-height: 1rem; font-weight: 600; letter-spacing: 0.08em; color: var(--vscode-editor-foreground, #d3af86); }"
+    },
+    {
+      "name": "Theme Picker Trigger",
+      "kind": "button",
+      "refersTo": "header-action-button-labeled",
+      "description": "The labeled chrome button used to open the theme picker. Inherits header fg; hovers with a 10% wash of currentColor so it works under any theme.",
+      "html": "<button class=\"ds-trigger\" aria-label=\"Theme\"><span>Kimbie Dark</span><svg viewBox=\"0 0 256 256\" width=\"10\" height=\"10\" aria-hidden=\"true\"><path fill=\"currentColor\" d=\"M213.66 101.66l-80 80a8 8 0 0 1-11.32 0l-80-80a8 8 0 0 1 11.32-11.32L128 164.69l74.34-74.35a8 8 0 0 1 11.32 11.32Z\"/></svg></button>",
+      "css": ".ds-trigger { display: inline-flex; align-items: center; gap: 4px; height: 20px; padding: 0 6px; border: none; border-radius: 4px; background: transparent; color: inherit; font-family: var(--vscode-editor-font-family, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.625rem; font-weight: 500; cursor: pointer; transition: background 120ms cubic-bezier(0.22, 1, 0.36, 1); } .ds-trigger:hover { background: color-mix(in srgb, currentColor 10%, transparent); } .ds-trigger:focus-visible { outline: 1px solid var(--color-focus-ring, #f9d181); outline-offset: 1px; }"
+    }
+  ],
+  "narrative": {
+    "northStar": "The Native Tenant",
+    "overview": "MouseTerm is a tenant in someone else's house. The house is VSCode. The user picked the furniture (their theme), the lighting (their mode), the typography (their editor font). MouseTerm moves in, multiplies what the user can do with their terminals, and leaves the decor alone. The system is intentionally minimal and bg-only. Chrome recedes; terminals are the content. Hierarchy is conveyed through background shifts between header-active-bg and header-inactive-bg, not through borders, shadows, or accent stripes. Status is conveyed through shape and position and through the active terminal palette's own ANSI red/green/yellow, not through a separate design-system palette.",
+    "keyCharacteristics": [
+      "Host-theme-driven palette: every color is a var(--vscode-*) passthrough.",
+      "Bg-only chrome: no decorative borders, no resting shadows, no accent stripes.",
+      "Monospace everywhere: sans and mono resolve to the same VSCode editor font.",
+      "Tight type scale: text-xs (10px) and text-sm (12px) override Tailwind defaults; almost everything sits on these two steps.",
+      "Status through palette already in the room: alerts use the user's ANSI red / green / yellow, not a brand color.",
+      "Motion: short, exponential ease-out for layout transitions; sparing spring-overshoot reserved for celebratory state-resolution."
+    ],
+    "rules": [
+      { "name": "The Host-Theme-Only Rule", "body": "Never write a hex value or oklch() literal into theme.css or a component. Never use var(..., fallback) chains. Every color must resolve through --vscode-* or one of the body-published runtime picks. The one allowed exception is #b92a1b for native window-close hover.", "section": "colors" },
+      { "name": "The Bg-Only Chrome Rule", "body": "Pane headers, doors, and the baseboard convey hierarchy through background shifts only. Do not add borders or shadows to 'make the hierarchy work.'", "section": "colors" },
+      { "name": "The Active Header Doubles as Accent Rule", "body": "Animated emphasis (copy-confirm flash, active-pane selection ring) tints with header-active-bg/25. The accent is not separate from the focus signal; they are the same color, used at different opacities.", "section": "colors" },
+      { "name": "The Two-Step Rule", "body": "Almost everything sits on text-xs or text-sm. If a new surface wants text-base or larger, the surface is probably wrong.", "section": "typography" },
+      { "name": "The Bracket-Shortcut Rule", "body": "Keybindings always render as [k] in muted color via <Shortcut> or renderShortcuts(...). Never put Ctrl+K or ⌘K in chrome text.", "section": "typography" },
+      { "name": "The Flat-At-Rest Rule", "body": "Surfaces in the resting layout (panes, doors, baseboard, terminal content) carry no shadow. Shadow appears only when a surface enters the air.", "section": "elevation" },
+      { "name": "The Inset-Over-Border Rule", "body": "When a surface needs a 1px stroke that may toggle on state change, prefer shadow-[inset_0_0_0_1px_…] over border. The shadow does not affect layout; the border does.", "section": "elevation" }
+    ],
+    "dos": [
+      "Do route every color through a --vscode-* variable or a body-published runtime pick (--color-door-*, --color-focus-ring, --color-alarm-vs-*). The frontmatter is the contract.",
+      "Do keep chrome on text-xs (10px) and text-sm (12px). The Tailwind defaults are overridden for a reason; do not write text-base into chrome to 'make it readable.'",
+      "Do use hover:bg-current/10 for neutral hover feedback inside theme-tinted chrome. It is the one hover treatment that always works.",
+      "Do convey active-vs-inactive pane state through the header-active-bg / header-inactive-bg background swap. That is the entire focus affordance.",
+      "Do render keybindings as [k] via <Shortcut> / renderShortcuts. Always muted, always bracketed.",
+      "Do gate every keyframe animation behind @media (prefers-reduced-motion: reduce).",
+      "Do use shadow-[inset_0_0_0_1px_var(--color-…)] instead of border when a stroke may toggle on state change.",
+      "Do treat doors as the navigation primitive. Doors own rounded-t-lg; terminal bodies own rounded-b-lg; together they form one rectangle.",
+      "Do use the spring-overshoot curve cubic-bezier(0.34, 1.56, 0.64, 1) only for state-resolution moments (TODO check, kill confirm, copy flash), and keep durations short (220-500ms)."
+    ],
+    "donts": [
+      "Don't write a hex color anywhere except #b92a1b for the windowClose hover. No exceptions. No oklch() literals either; even those bypass the host theme.",
+      "Don't add var(--vscode-*, #fallback) fallback chains in theme.css. The runtime host plus the resolver are responsible for providing the variable; a fallback hides a real bug.",
+      "Don't add borders or shadows to pane headers or doors to 'make the hierarchy work.' The hierarchy is header-active-bg vs. header-inactive-bg.",
+      "Don't introduce a text-muted color inside an active or inactive pane header. Header-internal text inherits the header foreground; muting inside it breaks the focus signal.",
+      "Don't use rounded SaaS cards, gradient accents, gradient text, or glassmorphism. PRODUCT.md names these directly.",
+      "Don't use hacker-aesthetic green-on-black, terminal-cliché Matrix tints, or any color that signals 'this is a programmer tool.' The user's theme decides what color this tool is.",
+      "Don't animate layout properties (width, height, top, left, padding). Pane transitions use clip-path and opacity deliberately so layout measurements stay valid mid-animation.",
+      "Don't add an emoji, mascot, or illustration to chrome. PRODUCT.md is explicit.",
+      "Don't wrap things in containers. Most surfaces don't need one; the host's sidebar already is the container.",
+      "Don't introduce a new pass-through --mt-* token or a one-off color for tabs, badges, accents, or button hovers. If a new rendered surface truly needs a token that isn't in the hierarchy, update theme.css and design.tsx together, document the addition in docs/specs/theme.md, and update CONSUMED_VSCODE_KEYS in bundle-themes.mjs."
+    ]
+  }
+}
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..b22e51f
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,269 @@
+---
+name: MouseTerm
+description: A mouse-friendly multitasking terminal that feels native inside VSCode.
+colors:
+  app-bg: "var(--vscode-sideBar-background)"
+  app-fg: "var(--vscode-sideBar-foreground)"
+  surface-raised: "var(--vscode-editorWidget-background)"
+  foreground: "var(--vscode-editor-foreground)"
+  muted: "var(--vscode-descriptionForeground)"
+  border: "var(--vscode-panel-border)"
+  header-active-bg: "var(--vscode-list-activeSelectionBackground)"
+  header-active-fg: "var(--vscode-list-activeSelectionForeground)"
+  header-inactive-bg: "var(--vscode-list-inactiveSelectionBackground)"
+  header-inactive-fg: "var(--vscode-list-inactiveSelectionForeground)"
+  door-bg: "var(--color-door-bg)"
+  door-fg: "var(--color-door-fg)"
+  focus-ring: "var(--color-focus-ring)"
+  terminal-bg: "var(--vscode-terminal-background)"
+  terminal-fg: "var(--vscode-terminal-foreground)"
+  input-bg: "var(--vscode-input-background)"
+  input-border: "var(--vscode-input-border)"
+  error: "var(--vscode-terminal-ansiRed)"
+  success: "var(--vscode-terminal-ansiGreen)"
+  alarm: "var(--vscode-terminal-ansiYellow)"
+  window-close-hover: "#b92a1b"
+typography:
+  body:
+    fontFamily: "var(--vscode-editor-font-family)"
+    fontSize: "0.75rem"
+    lineHeight: "1rem"
+    fontWeight: 500
+  label:
+    fontFamily: "var(--vscode-editor-font-family)"
+    fontSize: "0.625rem"
+    lineHeight: "1rem"
+    fontWeight: 600
+    letterSpacing: "0.08em"
+  shortcut:
+    fontFamily: "var(--vscode-editor-font-family)"
+    fontSize: "0.75rem"
+    fontWeight: 500
+rounded:
+  sm: "4px"
+  lg: "8px"
+spacing:
+  xs: "2px"
+  sm: "6px"
+  md: "10px"
+  lg: "16px"
+components:
+  door:
+    backgroundColor: "{colors.door-bg}"
+    textColor: "{colors.door-fg}"
+    rounded: "{rounded.lg}"
+    height: "24px"
+    padding: "0 10px"
+    typography: "{typography.body}"
+  header-action-button-icon:
+    rounded: "{rounded.sm}"
+    height: "20px"
+    width: "20px"
+  header-action-button-labeled:
+    rounded: "{rounded.sm}"
+    height: "20px"
+    padding: "0 6px"
+    typography: "{typography.body}"
+  popup-button-row:
+    backgroundColor: "{colors.surface-raised}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.sm}"
+    typography: "{typography.body}"
+  chrome-button-window:
+    width: "44px"
+    height: "20px"
+  chrome-button-window-close:
+    width: "44px"
+    height: "20px"
+  todo-pill:
+    typography: "{typography.label}"
+    textColor: "{colors.foreground}"
+  kill-confirm-dialog:
+    backgroundColor: "{colors.surface-raised}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.lg}"
+    padding: "16px 24px"
+---
+
+# Design System: MouseTerm
+
+## 1. Overview
+
+**Creative North Star: "The Native Tenant"**
+
+MouseTerm is a tenant in someone else's house. The house is VSCode. The user picked the furniture (their theme), the lighting (their mode), the typography (their editor font). MouseTerm moves in, multiplies what the user can do with their terminals, and leaves the decor alone. The interface should be indistinguishable from a built-in panel: not because it imitates VSCode, but because it inherits from VSCode. Every color, every font, every surface is a passthrough of the host's tokens.
+
+The system is intentionally minimal and bg-only. Chrome recedes; terminals are the content. Hierarchy is conveyed through background shifts between `header-active-bg` and `header-inactive-bg`, not through borders, shadows, or accent stripes. Status is conveyed through shape and position (a bell icon, a door's alert state) and through the active terminal palette's own ANSI red/green/yellow, not through a separate design-system palette.
+
+The system explicitly rejects: rounded SaaS cards, gradient accents, hacker-aesthetic green-on-black, "Slack-style" Electron chrome bloat, decorative animations, and any token that hardcodes a color. If a user installs a high-contrast theme, the chrome can look flatter than usual: that is accepted, not "fixed" with overrides.
+
+**Key Characteristics:**
+- Host-theme-driven palette: every color is a `var(--vscode-*)` passthrough.
+- Bg-only chrome: no decorative borders, no resting shadows, no accent stripes.
+- Monospace everywhere: sans and mono resolve to the same VSCode editor font.
+- Tight type scale: `text-xs` (10px) and `text-sm` (12px) override Tailwind defaults; almost everything sits on these two steps.
+- Status through palette already in the room: alerts use the user's ANSI red / green / yellow, not a brand color.
+- Motion: short, exponential ease-out for layout transitions; sparing spring-overshoot reserved for celebratory state-resolution.
+
+## 2. Colors
+
+The palette has no fixed values. Every semantic token resolves to a `--vscode-*` variable at runtime. Inside VSCode, those variables are injected by the host. Outside VSCode (standalone, website playground), `applyTheme()` materializes the same variable shape on `document.body` from a bundled MouseTerm theme.
+
+### Primary
+This system has no "primary" accent in the brand sense. The closest analogue is the **focused-header pair**:
+- **Header Active Background** (`var(--vscode-list-activeSelectionBackground)`): the bg of the focused pane's header tab. This is the only consistent visual cue for "this pane has focus." Used at full opacity for the header bg, and at `/25` opacity for the active terminal selection ring and copy-confirm flash background.
+- **Header Active Foreground** (`var(--vscode-list-activeSelectionForeground)`): text on the focused header. Inherited by buttons inside the focused header.
+
+### Secondary
+- **Header Inactive Background** (`var(--vscode-list-inactiveSelectionBackground)`): unfocused pane headers and the candidate bg for doors. The bg-bg delta between this and `header-active-bg` is the entire focus affordance.
+- **Header Inactive Foreground** (`var(--vscode-list-inactiveSelectionForeground)`): text on unfocused headers. Inherits the nearest `sideBar.foreground`, not the active-selection white.
+
+### Tertiary
+- **Door Background / Foreground** (`var(--color-door-bg)` / `var(--color-door-fg)`): runtime-chosen at body level by `computeDynamicPalette()`. Picks whichever of (inactive-header bg/fg) or (terminal bg/fg) has stronger OKLab perceptual separation from the app bg, so doors stay readable regardless of how close the user's chosen header and terminal palettes happen to be.
+- **Focus Ring** (`var(--color-focus-ring)`): runtime-chosen. Prefers a chromatic `focusBorder`, then a chromatic active-header background, then the highest-contrast fallback. Used for the marching-ants command-mode ring and the terminal text-selection border.
+
+### Neutral
+- **App Background** (`var(--vscode-sideBar-background)`): the chrome host. Baseboard, dockview gutters, gaps around panes. Reads as "the editor's sidebar," because it literally is.
+- **App Foreground** (`var(--vscode-sideBar-foreground)`): default text on app chrome.
+- **Surface Raised** (`var(--vscode-editorWidget-background)`): popovers, tooltips, dialogs, kill-confirm sheet, theme picker dropdown. Roughly one step above app-bg in the host's vocabulary.
+- **Foreground** (`var(--vscode-editor-foreground)`): primary text in raised surfaces (popups, dialogs).
+- **Muted** (`var(--vscode-descriptionForeground)`): secondary text, shortcut hints inside `[brackets]`, theme picker chip captions.
+- **Border** (`var(--vscode-panel-border)`): hairline border on raised surfaces (popups, dialogs, theme picker). The only place borders carry weight.
+
+### Status
+- **Terminal Background / Foreground** (`var(--vscode-terminal-background)` / `var(--vscode-terminal-foreground)`): the terminal content surface and xterm default text. Orthogonal to the chrome.
+- **Error** (`var(--vscode-terminal-ansiRed)`): destructive actions and kill-confirm letter flash.
+- **Success** (`var(--vscode-terminal-ansiGreen)`): TODO check, theme-store install confirm.
+- **Alarm** (`var(--vscode-terminal-ansiYellow)` initial; runtime-rotated): bell-ringing alert tint. Per-surface OKLCH hue-rotation by `use-dynamic-palette.ts` from the bg the bell sits on, so the alert pops off any header.
+
+### Fixed Exception
+- **Window Close Hover** (`#b92a1b`): the only literal color in the whole system. Native OS close-button hover on Windows/Linux chrome buttons; matches the platform convention across themes.
+
+### Named Rules
+**The Host-Theme-Only Rule.** Never write a hex value or `oklch()` literal into `theme.css` or a component. Never use `var(..., fallback)` chains. Every color must resolve through `--vscode-*` or one of the body-published runtime picks (`--color-door-*`, `--color-focus-ring`, `--color-alarm-vs-*`). The one allowed exception is `#b92a1b` for native window-close hover.
+
+**The Bg-Only Chrome Rule.** Pane headers, doors, and the baseboard convey hierarchy through background shifts only. Do not add borders or shadows to "make the hierarchy work." If a high-contrast theme makes a header look flat against the app bg, that is the user's theme speaking; do not override.
+
+**The Active Header Doubles as Accent Rule.** Animated emphasis (copy-confirm flash, active-pane selection ring) tints with `header-active-bg/25`. The accent is not separate from the focus signal; they are the same color, used at different opacities.
+
+## 3. Typography
+
+**Display Font:** none (no display tier).
+**Body Font:** `var(--vscode-editor-font-family)`.
+**Label/Mono Font:** same as body. Sans and mono resolve to the same VSCode editor font.
+
+**Character:** monospace, the user's own editor face. The system has no opinion about Cascadia vs. SF Mono vs. JetBrains Mono vs. Fira Code; whatever is set in the editor is what MouseTerm uses, including ligature settings. This is the typographic equivalent of the host-theme rule.
+
+### Hierarchy
+- **Body** (weight 500, `text-sm` = 0.75rem / 12px, line-height 1rem): pane headers, doors, popup contents, button labels. The single most-used step.
+- **Label** (weight 600, `text-xs` = 0.625rem / 10px, line-height 1rem, `tracking-[0.08em]`): TODO pills, kill-confirm hint, shortcut prompts. The wider tracking is non-negotiable at this size; without it the pill characters smear together.
+- **Shortcut** (weight 500, `text-sm`, muted color): keybinding text inside `[brackets]`. Always rendered with the `Shortcut` component or `renderShortcuts()`, never inline.
+
+The Tailwind defaults for `text-xs` (12px) and `text-sm` (14px) are overridden in `theme.css` to 10px and 12px respectively. The override is intentional: the chrome needs to recede, and the default Tailwind sizes are too loud against terminal output.
+
+### Named Rules
+**The Two-Step Rule.** Almost everything sits on `text-xs` or `text-sm`. If a new surface wants `text-base` or larger, the surface is probably wrong. Make it smaller or rethink the affordance.
+
+**The Bracket-Shortcut Rule.** Keybindings always render as `[k]` in muted color via `<Shortcut>` or `renderShortcuts(...)`. Never put `Ctrl+K` or `⌘K` in chrome text. The bracket convention is the entire visual hint system for "this is a key."
+
+## 4. Elevation
+
+Flat by default. Pane headers, doors, the baseboard, and terminal panes carry zero shadow at rest. Hierarchy is delegated to background shifts (active vs. inactive header) and to position (doors sit on the baseboard, the baseboard sits below panes).
+
+Shadows appear only on **raised surfaces that float above content**: popovers, tooltips, dialogs. They are ambient, not structural; they say "I am temporary and on top," not "I have weight."
+
+### Shadow Vocabulary
+- **Popover** (`box-shadow: var(--tw-shadow-md)`): tooltips (`PopupButtonRow`), selection popup, illegal-rename warning, terminal-pane header tooltips.
+- **Dialog** (`box-shadow: var(--tw-shadow-lg)`): kill-confirm sheet, TODO alert dialog.
+- **Modal** (`box-shadow: var(--tw-shadow-2xl)`): theme picker dropdown (when expanded), theme debugger, theme store dialog.
+- **Inset hairline** (`box-shadow: inset 0 0 0 1px var(--color-focus-ring)` / `var(--color-border)`): mobile UI segmented controls. Used instead of `border` when the surface needs a 1px stroke that does not shift layout on state change.
+
+### Named Rules
+**The Flat-At-Rest Rule.** Surfaces in the resting layout (panes, doors, baseboard, terminal content) carry no shadow. Shadow appears only when a surface enters the air (popover, tooltip, dialog, modal).
+
+**The Inset-Over-Border Rule.** When a surface needs a 1px stroke that may toggle on state change (active vs. inactive), prefer `shadow-[inset_0_0_0_1px_…]` over `border`. The shadow does not affect layout; the border does.
+
+## 5. Components
+
+### Doors
+Doors are the pane-header indicators on the baseboard. The most signature component in the system.
+- **Shape:** top corners only — `rounded-t-lg` (8px). The bottom is square so the door visually anchors to the baseboard. The pane body owns the bottom corners (`rounded-b-lg`); together they form one continuous rounded rectangle when expanded.
+- **Surface:** `bg-door-bg` + `text-door-fg`. These resolve at runtime via `computeDynamicPalette()` and may match either the inactive-header palette or the terminal palette, whichever has stronger separation from `app-bg`.
+- **Dimensions:** `h-6` (24px), `min-w-[68px]`, `max-w-[220px]`, horizontal padding `px-2.5` (10px), `gap-2` between title and badges.
+- **Type:** `text-sm font-medium font-mono`.
+- **Content:** truncated title; optional TODO pill (`text-xs font-semibold tracking-[0.08em]`, success-tinted when flourishing); optional bell icon (`size={11}`, `weight="fill"`), `text-alarm-vs-door` when ringing.
+- **Hover/Focus:** no decorative hover. The whole door is a button; the focus state is conveyed by the parent pane's selection ring, not by a per-door treatment.
+
+### Buttons
+
+#### Header Action Button
+The icon-and-tooltip button used inside pane headers (kill, alert toggle, todo, etc.).
+- **Shape:** `rounded` (4px) when icon-only, also `rounded` for labeled variants.
+- **Color:** `text-inherit` — inherits the header's foreground, so it tints with the active/inactive header palette.
+- **Hover:** `hover:bg-current/10` — a 10%-opacity wash of the current text color. Theme-agnostic, works light or dark.
+- **Tooltip:** rendered through a portal as a `PopupButtonRow` 8px below the button, with `text-sm` primary line and an optional muted detail line. Keybindings inside the tooltip auto-render as `[bracketed]` shortcuts.
+
+#### Chrome Button (window controls)
+The Windows/Linux native-style window control row in the standalone app bar.
+- **Variants:** `icon` (h-5 min-w-5, hover bg-current/10), `labeled` (h-5 min-w-5 px-1.5 text-xs), `window` (w-11, hover bg-current/10), `windowClose` (w-11, hover bg `#b92a1b` text-white).
+- **The exception:** `windowClose` is the only place a literal hex color is permitted, because the platform convention is a hard red regardless of theme.
+
+### Cards / Containers
+
+The system uses **raised surfaces**, not "cards." There are no nested cards. There is no resting card grid.
+- **Raised surface** (`PopupButtonRow`, tooltips, popups): `bg-surface-raised`, `border border-border`, `rounded` (4px), `shadow-md`, `font-mono text-sm`.
+- **Dialog** (`KillConfirm`, `TodoAlertDialog`): `bg-surface-raised`, `border border-border`, `rounded-lg` (8px), `shadow-lg`, generous padding (`px-6 py-4` for kill-confirm).
+- **Modal** (`ThemePicker` dropdown, `ThemeDebugger`, `ThemeStoreDialog`): `bg-surface-raised`, `border`, `rounded`, `shadow-2xl`, fixed-position with viewport-clamped sizing.
+
+### Inputs
+- Used by `ThemePicker`. Style: `bg-input-bg`, `border border-input-border`, `rounded`, `font-mono`, `text-sm`.
+- **Focus:** native browser focus outline; this is acceptable because the entire input lives inside a raised surface that already has `shadow-2xl` and a border.
+
+### Navigation
+
+The system has no traditional top-nav. Two surfaces play navigational roles:
+- **Baseboard** (bottom of the app): horizontal strip of doors representing minimized panes plus chrome action buttons. Doors are the primary navigation affordance to a minimized terminal. Button style: `h-5 rounded px-1.5 text-sm font-medium font-mono text-muted` with `hover:bg-surface-raised hover:text-foreground transition-colors`.
+- **Pane Header (TerminalPaneHeader)**: the tab-replacing strip at the top of each pane. Tab-bar styling is stripped from dockview entirely (`--dv-tabs-and-actions-container-*` overrides); the React header IS the tab.
+
+### Signature Components
+
+#### TODO Pill
+A tiny inline label that appears in pane headers and inside doors when a terminal has a TODO state.
+- `text-xs font-semibold tracking-[0.08em]` — the tracking is mandatory at this size.
+- Grid-stacked `<letters>` and `<check>` so width stays stable when the dismiss flourish runs.
+- **Flourish (500ms):** letters fade 0–30%, check springs in 0–40% with `cubic-bezier(0.34, 1.56, 0.64, 1)` (overshoot 1.15x, settle to 1.0x at 55%), whole pill dissolves 55–100%. Reduced-motion replaces the entire sequence with opacity:0 at zero duration.
+
+#### Pane Spawn / Kill Choreography
+The most distinctive motion in the system. Implemented as `clip-path` reveals, not transforms, so `getBoundingClientRect` stays accurate during the animation (the selection overlay measures real bounds).
+- **Spawn:** 440ms `cubic-bezier(0.22, 1, 0.36, 1)` clip-path reveal from left / top / top-left, depending on which side of the layout the new pane appeared on.
+- **Kill (edge/middle):** 440ms `pane-fade-out`. The neighbor's spawn-grow carries the directional cue; the dying pane just fades.
+- **Kill (last-pane):** 440ms `pane-fade-and-shrink-to-br`, paired with `ring-shrink-to-br` so the focus ring stays glued to the pane as it disappears.
+- **Reduced-motion:** all of the above are nulled.
+
+#### Marching Ants (Command Mode)
+The selection ring around the focused pane in command mode is an SVG with `stroke-dasharray` and an infinite `marching-ants` keyframe that increments `stroke-dashoffset` by `var(--march-offset)`. Color: `var(--color-focus-ring)`. This is the system's only ongoing animation; it is meant to be the visual signature of "you are now in command mode."
+
+## 6. Do's and Don'ts
+
+### Do:
+- **Do** route every color through a `--vscode-*` variable or a body-published runtime pick (`--color-door-*`, `--color-focus-ring`, `--color-alarm-vs-*`). The frontmatter is the contract.
+- **Do** keep chrome on `text-xs` (10px) and `text-sm` (12px). The Tailwind defaults are overridden for a reason; do not write `text-base` into chrome to "make it readable."
+- **Do** use `hover:bg-current/10` for neutral hover feedback inside theme-tinted chrome. It is the one hover treatment that always works.
+- **Do** convey active-vs-inactive pane state through the `header-active-bg` / `header-inactive-bg` background swap. That is the entire focus affordance.
+- **Do** render keybindings as `[k]` via `<Shortcut>` / `renderShortcuts`. Always muted, always bracketed.
+- **Do** gate every keyframe animation behind `@media (prefers-reduced-motion: reduce)`. The pattern is in `theme.css` already; reuse it.
+- **Do** use `shadow-[inset_0_0_0_1px_var(--color-…)]` instead of `border` when a stroke may toggle on state change. Border shifts layout; inset shadow does not.
+- **Do** treat doors as the navigation primitive. Doors own `rounded-t-lg`; terminal bodies own `rounded-b-lg`; together they form one rectangle.
+- **Do** use the spring-overshoot curve `cubic-bezier(0.34, 1.56, 0.64, 1)` only for state-resolution moments (TODO check, kill confirm, copy flash), and keep durations short (220–500ms).
+
+### Don't:
+- **Don't** write a hex color anywhere except `#b92a1b` for the windowClose hover. No exceptions. No `oklch()` literals either; even those bypass the host theme.
+- **Don't** add `var(--vscode-*, #fallback)` fallback chains in `theme.css`. The runtime host plus the resolver are responsible for providing the variable; a fallback hides a real bug.
+- **Don't** add borders or shadows to pane headers or doors to "make the hierarchy work." The hierarchy is `header-active-bg` vs. `header-inactive-bg`. If a high-contrast theme makes that look flat, accept it.
+- **Don't** introduce a `text-muted` color inside an active or inactive pane header. Header-internal text inherits the header foreground; muting inside it breaks the focus signal.
+- **Don't** use rounded SaaS cards, gradient accents, gradient text, or glassmorphism. PRODUCT.md names these directly: "Generic SaaS (rounded cards, gradients, startup illustrations)," "Electron bloat (Slack — heavy, slow-feeling, too much chrome)."
+- **Don't** use hacker-aesthetic green-on-black, terminal-cliché Matrix tints, or any color that signals "this is a programmer tool." The user's theme decides what color this tool is.
+- **Don't** animate layout properties (`width`, `height`, `top`, `left`, `padding`). Pane transitions use `clip-path` and `opacity` deliberately so layout measurements stay valid mid-animation.
+- **Don't** add an emoji, mascot, or illustration to chrome. PRODUCT.md is explicit: "Overly playful (too many animations, emojis, mascots)."
+- **Don't** wrap things in containers. Most surfaces don't need one; the host's sidebar already is the container.
+- **Don't** introduce a new pass-through `--mt-*` token or a one-off color for tabs, badges, accents, or button hovers. If a new rendered surface truly needs a token that isn't in the hierarchy above, update `theme.css` and `design.tsx` together, document the addition in `docs/specs/theme.md`, and update `CONSUMED_VSCODE_KEYS` in `bundle-themes.mjs`.
diff --git a/PRODUCT.md b/PRODUCT.md
index 624b8d0..ad907a8 100644
--- a/PRODUCT.md
+++ b/PRODUCT.md
@@ -1,3 +1,7 @@
+## Register
+
+product
+
 ## Design Context
 
 ### Users

From 64ff4e86ab32c564b6da0aa379b24094f0bcdff8 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 13 May 2026 01:29:57 -0700
Subject: [PATCH 12/12] Code review cleanups on tether branch

- Use text-xs instead of text-[11px] in MobileTerminalUi selector label
- Use clsx instead of template-string concat for conditional classes in Wall
- Tighten WallModule.Wall type in Tether.tsx (drop ComponentType<any>)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 lib/src/components/MobileTerminalUi.tsx | 2 +-
 lib/src/components/Wall.tsx             | 5 +++--
 website/src/pages/Tether.tsx            | 4 ++--
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/lib/src/components/MobileTerminalUi.tsx b/lib/src/components/MobileTerminalUi.tsx
index 407999b..a04f1c6 100644
--- a/lib/src/components/MobileTerminalUi.tsx
+++ b/lib/src/components/MobileTerminalUi.tsx
@@ -181,7 +181,7 @@ function KeyboardModeButton({
 
 function SelectorLabel({ children }: { children: ReactNode }) {
   return (
-    <div className="w-[4.5rem] shrink-0 pl-2 pr-1 font-mono text-[11px] leading-none text-muted">
+    <div className="w-[4.5rem] shrink-0 pl-2 pr-1 font-mono text-xs leading-none text-muted">
       {children}
     </div>
   );
diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 6944837..6b8f921 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -1,4 +1,5 @@
 import { useRef, useState, useEffect, useCallback, useMemo, type ReactNode } from 'react';
+import { clsx } from 'clsx';
 import {
   DockviewReact,
   themeAbyss,
@@ -594,8 +595,8 @@ export function Wall({
           <DialogKeyboardContext.Provider value={setDialogKeyboardActive}>
           <div className="flex-1 min-h-0 flex flex-col bg-app-bg text-app-fg font-sans overflow-hidden">
             {/* Dockview — 2px bottom inset keeps rounded panes distinct from the baseboard when present. */}
-            <div className={`flex-1 min-h-0 relative px-1.5 pt-1.5 ${showBaseboard ? 'pb-0.5' : 'pb-1.5'}`}>
-              <div ref={dockviewContainerRef} className={`absolute inset-x-1.5 top-1.5 ${showBaseboard ? 'bottom-0.5' : 'bottom-1.5'}`}>
+            <div className={clsx('flex-1 min-h-0 relative px-1.5 pt-1.5', showBaseboard ? 'pb-0.5' : 'pb-1.5')}>
+              <div ref={dockviewContainerRef} className={clsx('absolute inset-x-1.5 top-1.5', showBaseboard ? 'bottom-0.5' : 'bottom-1.5')}>
                 <DockviewReact
                   components={components}
                   tabComponents={tabComponents}
diff --git a/website/src/pages/Tether.tsx b/website/src/pages/Tether.tsx
index 2669010..45f1897 100644
--- a/website/src/pages/Tether.tsx
+++ b/website/src/pages/Tether.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useState, useSyncExternalStore, type ComponentType } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { ShareIcon } from "@phosphor-icons/react";
 import SiteHeader, { STATIC_PAGE_HEADER_STYLE } from "../components/SiteHeader";
 import { NotifySignupForm } from "../components/NotifySignupForm";
@@ -23,7 +23,7 @@ const TETHER_PANE = "tether-ascii-splash";
 const TETHER_THEME_ID = "vscode.theme-kimbie-dark.kimbie-dark";
 
 interface WallModule {
-  Wall: ComponentType<any>;
+  Wall: typeof import("mouseterm-lib/components/Wall")["Wall"];
 }
 
 interface DockviewApiLike {