@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/__tests__/terminal-handoff-controller.test.ts

@@ -0,0 +1,173 @@
+/**
+ * TERM-002: unit tests for the TUI terminal-handoff controller LOGIC.
+ *
+ * The real Ink suspend/resume + child-process TTY handoff can only be validated on a live terminal
+ * (manual / User Execution evidence). These tests pin the controller's observable contract: TTY +
+ * mounted-App gating, and the suspend → clear → fn → resume order (including resume-on-throw).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { TerminalHandoffController } from '../terminal-handoff-controller.js';
+
+const origStdin = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+const origStdout = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
+
+function setTty(stdin: boolean, stdout: boolean): void {
+  Object.defineProperty(process.stdin, 'isTTY', { value: stdin, configurable: true });
+  Object.defineProperty(process.stdout, 'isTTY', { value: stdout, configurable: true });
+}
+
+afterEach(() => {
+  if (origStdin) Object.defineProperty(process.stdin, 'isTTY', origStdin);
+  if (origStdout) Object.defineProperty(process.stdout, 'isTTY', origStdout);
+});
+
+describe('TerminalHandoffController', () => {
+  it('canHandoffTerminal requires a TTY on both streams AND registered App hooks', () => {
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    expect(c.canHandoffTerminal).toBe(false); // no hooks yet
+
+    const unregister = c.registerSuspendHooks({ suspend: async () => {}, resume: () => {} });
+    expect(c.canHandoffTerminal).toBe(true);
+
+    setTty(false, true);
+    expect(c.canHandoffTerminal).toBe(false); // stdin not a TTY
+
+    setTty(true, true);
+    unregister();
+    expect(c.canHandoffTerminal).toBe(false); // App unmounted
+  });
+
+  it('runs suspend → clear → fn → resume in order', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => {
+        order.push('suspend');
+      },
+      resume: () => order.push('resume'),
+    });
+    c.setInkInstance({ clear: () => order.push('clear') });
+
+    const result = await c.runWithTerminal(async () => {
+      order.push('child');
+      return 7;
+    });
+
+    expect(result).toBe(7);
+    expect(order).toEqual(['suspend', 'clear', 'child', 'resume']);
+  });
+
+  it('resumes even when the child fn throws', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => void order.push('suspend'),
+      resume: () => order.push('resume'),
+    });
+
+    await expect(
+      c.runWithTerminal(async () => {
+        throw new Error('child failed');
+      }),
+    ).rejects.toThrow('child failed');
+    expect(order).toEqual(['suspend', 'resume']);
+  });
+
+  it('rejects (does not run fn) when no interactive TTY is available', async () => {
+    const c = new TerminalHandoffController();
+    setTty(false, false);
+    c.registerSuspendHooks({ suspend: async () => {}, resume: () => {} });
+    const fn = vi.fn();
+    await expect(c.runWithTerminal(fn as never)).rejects.toThrow(/unavailable/);
+    expect(fn).not.toHaveBeenCalled();
+  });
+});
+
+/** SCREEN-1992 TC-06: the negotiated terminal modes bracket the handoff. */
+describe('TerminalHandoffController terminal-mode hooks', () => {
+  it('runs preSuspend after suspend and postResume after resume, even when the child throws', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => {
+        order.push('suspend');
+      },
+      resume: () => order.push('resume'),
+    });
+    c.setInkInstance({ clear: () => order.push('clear') });
+    c.setTerminalModeHooks({
+      preSuspend: () => {
+        order.push('mode-off');
+      },
+      postResume: () => {
+        order.push('mode-on');
+      },
+    });
+
+    await expect(
+      c.runWithTerminal(async () => {
+        order.push('child');
+        throw new Error('child failed');
+      }),
+    ).rejects.toThrow('child failed');
+    expect(order).toEqual(['suspend', 'mode-off', 'clear', 'child', 'resume', 'mode-on']);
+
+    c.setTerminalModeHooks(undefined);
+    order.length = 0;
+    await c.runWithTerminal(async () => order.push('child'));
+    expect(order).toEqual(['suspend', 'clear', 'child', 'resume']);
+  });
+
+  /**
+   * SCREEN-2670: `preSuspend` may be async — it drains the parked screen-reader output — and the
+   * screen is cleared only after it settles. Without the await, `clear` and the child would run
+   * while the drain was still pending, and parked frames would land on top of the child's output.
+   */
+  it('awaits an async preSuspend before clearing the screen and starting the child', async () => {
+    const order: string[] = [];
+    const c = new TerminalHandoffController();
+    setTty(true, true);
+    c.registerSuspendHooks({
+      suspend: async () => {
+        order.push('suspend');
+      },
+      resume: () => order.push('resume'),
+    });
+    c.setInkInstance({ clear: () => order.push('clear') });
+    let finishDrain: () => void = () => {};
+    const drained = new Promise<void>((resolve) => {
+      finishDrain = resolve;
+    });
+    c.setTerminalModeHooks({
+      preSuspend: async () => {
+        order.push('drain-start');
+        await drained;
+        order.push('drain-end');
+      },
+      postResume: () => {
+        order.push('mode-on');
+      },
+    });
+
+    const run = c.runWithTerminal(async () => order.push('child'));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    // The drain has not settled: nothing past it may have run yet.
+    expect(order).toEqual(['suspend', 'drain-start']);
+    finishDrain();
+    await run;
+    expect(order).toEqual([
+      'suspend',
+      'drain-start',
+      'drain-end',
+      'clear',
+      'child',
+      'resume',
+      'mode-on',
+    ]);
+  });
+});

package/src/__tests__/terminal-handoff-pty-e2e.test.ts

@@ -0,0 +1,77 @@
+/**
+ * TEST-007 / TERM-002: real-terminal handoff, end-to-end through a PTY.
+ *
+ * Drives `fixtures/terminal-handoff-driver.tsx` (a real Ink app using the real
+ * `TerminalHandoffController` + `useTerminalHandoffSuspension`) inside a pseudo-terminal. This is the
+ * automated replacement for the former manual-only smoke: it proves on a real TTY that
+ *
+ *  1. the handoff is available (`canHandoffTerminal === true` under a PTY),
+ *  2. Ink releases raw mode so the inherited child receives the driver's keystrokes, and
+ *  3. `runWithTerminal` RETURNS after the child exits and the TUI resumes (regression guard for the
+ *     event-loop-starvation hang fixed in the controller — without the stdin release the child's
+ *     exit is never observed and the TUI hangs forever).
+ */
+import { mkdtempSync, readFileSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createPtyEnv } from './pty/isolated-home.js';
+import { spawnPtyFixture } from './pty/spawn-pty.js';
+
+import type { IPtyRunSession } from './pty/spawn-pty.js';
+
+const FIXTURE = fileURLToPath(new URL('./fixtures/terminal-handoff-driver.tsx', import.meta.url));
+const PACKAGE_DIR = fileURLToPath(new URL('../..', import.meta.url));
+const TEST_TIMEOUT_MS = 30_000;
+
+const tempDirs: string[] = [];
+const sessions: IPtyRunSession[] = [];
+
+afterEach(() => {
+  for (const session of sessions.splice(0)) session.dispose();
+  for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe('terminal handoff PTY E2E', () => {
+  it(
+    'hands the real terminal to a child, receives its input, and resumes the TUI',
+    async () => {
+      const dir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-handoff-pty-')));
+      tempDirs.push(dir);
+      const outputPath = join(dir, 'result.json');
+
+      const session = spawnPtyFixture(FIXTURE, {
+        argv: [outputPath],
+        cwd: PACKAGE_DIR,
+        // HARNESS-025: isolated HOME — the child must not read the developer's `~`.
+        env: createPtyEnv(),
+      });
+      sessions.push(session);
+
+      await session.waitFor('READY canHandoff=true', 10_000);
+      await session.waitFor('HANDOFF_STARTED', 10_000);
+      // Let the child reach its read() before sending the line.
+      await new Promise((resolve) => setTimeout(resolve, 300));
+      await session.sendKeys('hello-from-pty', 10);
+      session.write('\r');
+
+      // The crux: the handoff must RETURN and the TUI must resume (no hang).
+      await session.waitFor('RESUMED exit=0', 10_000);
+      expect(await session.expectExit(5_000)).toBe(0);
+
+      const snapshot = session.snapshot();
+      expect(snapshot).toContain('CHILD_GOT:[hello-from-pty]');
+
+      const result = JSON.parse(readFileSync(outputPath, 'utf8')) as {
+        canHandoff: boolean;
+        exitCode: number;
+        returned: boolean;
+      };
+      expect(result).toEqual({ canHandoff: true, exitCode: 0, returned: true });
+    },
+    TEST_TIMEOUT_MS,
+  );
+});

package/src/__tests__/text-prompt-flow.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import {
+  applyTextPromptInput,
+  createTextPromptFlowState,
+  getTextPromptInputAction,
+  type ITextPromptFlowState,
+} from '../flows/text-prompt-flow.js';
+
+describe('text prompt flow', () => {
+  it('Given typed text When submit is applied Then it emits trimmed submit value', () => {
+    const typed = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'insert', value: '  hello  ' },
+      { allowEmpty: false },
+    ).state;
+
+    const result = applyTextPromptInput(typed, { type: 'submit' }, { allowEmpty: false });
+
+    expect(result.effect).toEqual({ type: 'submit', value: 'hello' });
+    expect(result.state.resolved).toBe(true);
+  });
+
+  it('Given empty required text When submit is applied Then validation error stays in state', () => {
+    const result = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'submit' },
+      { allowEmpty: false, validate: (value) => (value.length === 0 ? 'Required' : undefined) },
+    );
+
+    expect(result.effect).toEqual({ type: 'none' });
+    expect(result.state.error).toBe('Required');
+    expect(result.state.resolved).toBe(false);
+  });
+
+  it('Given defaultable empty text When submit is applied Then empty submit is allowed', () => {
+    const result = applyTextPromptInput(
+      createTextPromptFlowState(),
+      { type: 'submit' },
+      { allowEmpty: true },
+    );
+
+    expect(result.effect).toEqual({ type: 'submit', value: '' });
+  });
+
+  it('Given text with an error When delete or insert is applied Then the error is cleared', () => {
+    const state: ITextPromptFlowState = { value: 'ab', error: 'Invalid', resolved: false };
+
+    const deleted = applyTextPromptInput(state, { type: 'delete' }, { allowEmpty: false });
+    const inserted = applyTextPromptInput(
+      state,
+      { type: 'insert', value: 'c' },
+      { allowEmpty: false },
+    );
+
+    expect(deleted.state).toMatchObject({ value: 'a', error: undefined });
+    expect(inserted.state).toMatchObject({ value: 'abc', error: undefined });
+  });
+
+  it('Given prompt is already resolved When input is applied Then no second effect is emitted', () => {
+    const state: ITextPromptFlowState = { value: 'done', resolved: true };
+
+    const result = applyTextPromptInput(state, { type: 'submit' }, { allowEmpty: false });
+
+    expect(result.effect).toEqual({ type: 'none' });
+    expect(result.state).toBe(state);
+  });
+
+  it('Given raw Ink key info When mapped Then terminal details become prompt actions', () => {
+    expect(getTextPromptInputAction('', { escape: true })).toEqual({ type: 'cancel' });
+    expect(getTextPromptInputAction('', { return: true })).toEqual({ type: 'submit' });
+    expect(getTextPromptInputAction('', { backspace: true })).toEqual({ type: 'delete' });
+    expect(getTextPromptInputAction('x', { ctrl: false, meta: false })).toEqual({
+      type: 'insert',
+      value: 'x',
+    });
+  });
+});

package/src/__tests__/theme-picker.test.tsx

@@ -0,0 +1,345 @@
+/**
+ * SCREEN-2002 TC-10 — the theme picker.
+ *
+ * Preview-on-move is the behaviour worth pinning: the highlighted row IS the live region's theme
+ * while the picker is open, so moving the highlight must call `preview` and LEAVING must not
+ * persist it. Selecting does not write — it submits `/theme <id>` through the normal command path,
+ * which is what keeps the host the only writer of the settings document.
+ */
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ScreenReaderProvider } from '../screen-reader-context.js';
+
+const gateMock = vi.hoisted(() => ({ value: true }));
+// Spread the real module and override ONE export: a hand-listed factory silently drops whatever
+// the module gains later, and the failure lands as "not a function" in an unrelated file.
+vi.mock('../terminal-capabilities.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../terminal-capabilities.js')>()),
+  isInteractiveColorTerminal: (): boolean => gateMock.value,
+}));
+
+afterEach(() => {
+  gateMock.value = true;
+});
+import { DARK_THEME, LIGHT_THEME, listBuiltInThemes } from '../theme/built-in-themes.js';
+import ThemePicker from '../ThemePicker.js';
+
+import type { IAppThemePickerViewModel } from '../hooks/useAppThemeState.js';
+
+const ARROW_DOWN = '\x1b[B';
+const ARROW_UP = '\x1b[A';
+const ENTER = '\r';
+const ESCAPE = '\x1b';
+
+function picker(overrides: Partial<IAppThemePickerViewModel> = {}): IAppThemePickerViewModel {
+  return {
+    visible: true,
+    themes: listBuiltInThemes(),
+    skipped: [],
+    activeThemeId: 'dark',
+    syntaxHighlighting: true,
+    reducedMotion: false,
+    preview: vi.fn(),
+    select: vi.fn(),
+    cancel: vi.fn(),
+    ...overrides,
+  };
+}
+
+async function tick(ms = 20): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe('the theme picker (SCREEN-2002 TC-10)', () => {
+  it('lists every theme with its appearance and source, and marks the active one', () => {
+    const frame = render(<ThemePicker picker={picker()} />).lastFrame() ?? '';
+
+    expect(frame).toContain(`${DARK_THEME.name} — dark, built-in (current)`);
+    expect(frame).toContain(`${LIGHT_THEME.name} — light, built-in`);
+    expect(frame).not.toContain(`${LIGHT_THEME.name} — light, built-in (current)`);
+  });
+
+  it('starts focused on the ACTIVE theme, not on the first row', async () => {
+    const view = picker({ activeThemeId: 'dark-daltonized' });
+    const { stdin } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    stdin.write(ARROW_DOWN);
+    await tick();
+
+    // From `dark-daltonized` (index 2), down lands on `light-daltonized` — not on `light`.
+    expect(view.preview).toHaveBeenCalledWith('light-daltonized');
+  });
+
+  it('previews on move, and does not select or cancel while moving', async () => {
+    const view = picker();
+    const { stdin } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    stdin.write(ARROW_DOWN);
+    await tick();
+
+    expect(view.preview).toHaveBeenCalledWith('light');
+    expect(view.select).not.toHaveBeenCalled();
+    expect(view.cancel).not.toHaveBeenCalled();
+  });
+
+  it('wraps at both ends rather than stopping', async () => {
+    const view = picker();
+    const { stdin } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    stdin.write(ARROW_UP);
+    await tick();
+
+    expect(view.preview).toHaveBeenCalledWith('light-daltonized');
+  });
+
+  it('selects the focused row, and selects the PREVIEWED one after moving', async () => {
+    const view = picker();
+    const { stdin } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    stdin.write(ARROW_DOWN);
+    await tick();
+    stdin.write(ENTER);
+    await tick();
+
+    expect(view.select).toHaveBeenCalledWith('light', {
+      syntaxHighlighting: true,
+      reducedMotion: false,
+    });
+    expect(view.select).toHaveBeenCalledTimes(1);
+  });
+
+  it('cancels on escape WITHOUT selecting — the persisted theme is what remains', async () => {
+    const view = picker();
+    const { stdin } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    stdin.write(ARROW_DOWN);
+    await tick();
+    stdin.write(ESCAPE);
+    await tick();
+
+    expect(view.cancel).toHaveBeenCalledTimes(1);
+    expect(view.select).not.toHaveBeenCalled();
+  });
+
+  it('toggles syntax and motion locally, and submits them WITH the theme as one patch', async () => {
+    const view = picker();
+    const { stdin, lastFrame } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    expect(lastFrame() ?? '').toContain('syntax on · motion on');
+    stdin.write('s');
+    await tick();
+    stdin.write('m');
+    await tick();
+    expect(lastFrame() ?? '').toContain('syntax off · motion off');
+    // Nothing is written until select — a toggle is pending, like the previewed theme.
+    expect(view.select).not.toHaveBeenCalled();
+
+    stdin.write(ENTER);
+    await tick();
+
+    expect(view.select).toHaveBeenCalledWith('dark', {
+      syntaxHighlighting: false,
+      reducedMotion: true,
+    });
+  });
+
+  it('abandons pending toggles on escape, exactly as it abandons the preview', async () => {
+    const view = picker();
+    const { stdin } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    stdin.write('s');
+    await tick();
+    stdin.write(ESCAPE);
+    await tick();
+
+    expect(view.cancel).toHaveBeenCalledTimes(1);
+    expect(view.select).not.toHaveBeenCalled();
+  });
+
+  it('seeds the toggles from what is PERSISTED, not from the defaults', async () => {
+    const view = picker({ syntaxHighlighting: false, reducedMotion: true });
+    const { lastFrame } = render(<ThemePicker picker={view} />);
+    await tick();
+
+    expect(lastFrame() ?? '').toContain('syntax off · motion off');
+  });
+
+  it('admits a motion pin, so the row cannot read `motion on` on a visibly still run', () => {
+    const frame =
+      render(
+        <ThemePicker
+          picker={picker({
+            reducedMotion: false,
+            reducedMotionPin: { tier: 'flag', reducedMotion: true },
+          })}
+        />,
+      ).lastFrame() ?? '';
+
+    // The saved choice and what THIS RUN does are different facts and are shown as two. A tier
+    // alone cannot say which way it went — `--no-reduced-motion` is an override that pins the
+    // opposite value — so rendering the saved value beside the tier is how the row ends up reading
+    // `motion on (pinned by flag)` on a visibly still run.
+    expect(frame).toContain('motion on (this run: motion off, pinned by flag)');
+  });
+
+  it('shows the opposite pin the same way, so the two runs are told apart', () => {
+    const frame =
+      render(
+        <ThemePicker
+          picker={picker({
+            reducedMotion: true,
+            reducedMotionPin: { tier: 'environment', reducedMotion: false },
+          })}
+        />,
+      ).lastFrame() ?? '';
+
+    expect(frame).toContain('motion off (this run: motion on, pinned by environment)');
+  });
+
+  it('says previews cannot show when colour is off, rather than looking broken', () => {
+    gateMock.value = false;
+
+    const frame = render(<ThemePicker picker={picker()} />).lastFrame() ?? '';
+
+    expect(frame).toContain('Colour is off for this terminal');
+  });
+
+  it('renders the empty state rather than an empty box', () => {
+    const frame = render(<ThemePicker picker={picker({ themes: [] })} />).lastFrame() ?? '';
+
+    expect(frame).toContain('No themes installed');
+  });
+});
+
+describe('the theme picker in screen-reader mode (SCREEN-2002 TC-10)', () => {
+  function renderInMode(view: IAppThemePickerViewModel): ReturnType<typeof render> {
+    return render(
+      <ScreenReaderProvider enabled>
+        <ThemePicker picker={view} />
+      </ScreenReaderProvider>,
+    );
+  }
+
+  it('numbers the rows and prompts for a typed answer instead of drawing a highlight', () => {
+    const frame = renderInMode(picker()).lastFrame() ?? '';
+
+    expect(frame).toContain('1.');
+    expect(frame).toContain('4.');
+    // No box-drawing chrome in the mode.
+    expect(frame).not.toMatch(/[─-╿]/u);
+  });
+
+  it('applies on SELECT and never previews per keystroke — there is no highlight to hear', async () => {
+    const view = picker();
+    const { stdin } = renderInMode(view);
+    await tick();
+
+    stdin.write('2');
+    await tick();
+    stdin.write(ENTER);
+    await tick();
+
+    expect(view.select).toHaveBeenCalledWith('light', {
+      syntaxHighlighting: true,
+      reducedMotion: false,
+    });
+    expect(view.preview).not.toHaveBeenCalled();
+  });
+
+  it('cancels on the mode s own cancel path', async () => {
+    const view = picker();
+    const { stdin } = renderInMode(view);
+    await tick();
+
+    stdin.write(ESCAPE);
+    await tick();
+
+    expect(view.cancel).toHaveBeenCalledTimes(1);
+    expect(view.select).not.toHaveBeenCalled();
+  });
+});
+
+describe('the theme picker over files it refused (SCREEN-2002 TC-11)', () => {
+  const skipped = [
+    { id: 'custom:broken', fileName: 'broken.json', reason: '$.overrides.colors.text.accent: bad' },
+  ];
+
+  it('shows a refused file as a row that carries its reason and cannot be chosen', async () => {
+    const view = picker({ skipped });
+    const { lastFrame, stdin } = render(<ThemePicker picker={view} />);
+    const frame = lastFrame() ?? '';
+
+    expect(frame).toContain('broken.json');
+    expect(frame).toContain('$.overrides.colors.text.accent: bad');
+
+    // Walking past the end of the applicable rows wraps to the first one; it never lands on a file
+    // the run has already refused, because selecting it could only fail.
+    await tick();
+    for (let index = 0; index <= listBuiltInThemes().length; index += 1) {
+      stdin.write(ARROW_DOWN);
+      await tick();
+    }
+    stdin.write(ENTER);
+    await tick();
+
+    expect(view.select).toHaveBeenCalledTimes(1);
+    const [selectedId] = (view.select as ReturnType<typeof vi.fn>).mock.calls[0] ?? [];
+    expect(listBuiltInThemes().map((theme) => theme.id)).toContain(selectedId);
+  });
+
+  it('says nothing about skipped files when there are none', () => {
+    expect(render(<ThemePicker picker={picker()} />).lastFrame() ?? '').not.toContain('Skipped');
+  });
+
+  it('numbers only the applicable rows in screen-reader mode', async () => {
+    const view = picker({ skipped });
+    const { lastFrame, stdin } = render(
+      <ScreenReaderProvider enabled>
+        <ThemePicker picker={view} />
+      </ScreenReaderProvider>,
+    );
+    const frame = lastFrame() ?? '';
+
+    expect(frame).toContain('broken.json');
+    expect(frame).not.toMatch(/5\.\s*Skipped/u);
+
+    await tick();
+    stdin.write('5');
+    await tick();
+    stdin.write(ENTER);
+    await tick();
+
+    expect(view.select).not.toHaveBeenCalled();
+  });
+});
+
+describe('the toggles row names a route the mode can take (SCREEN-2002 TC-11)', () => {
+  it('names the commands in screen-reader mode, where `s` and `m` are not bound', () => {
+    const frame =
+      render(
+        <ScreenReaderProvider enabled>
+          <ThemePicker picker={picker()} />
+        </ScreenReaderProvider>,
+      ).lastFrame() ?? '';
+
+    expect(frame).toContain('syntax on · motion on');
+    expect(frame).toContain('/theme syntax on|off');
+    expect(frame).toContain('/theme motion on|off');
+  });
+
+  it('does NOT name them in sighted mode, where the keys are bound and hinted', () => {
+    const frame = render(<ThemePicker picker={picker()} />).lastFrame() ?? '';
+
+    expect(frame).toContain('syntax on · motion on');
+    expect(frame).not.toContain('/theme syntax');
+  });
+});

package/src/__tests__/transport-boundary.test.ts

@@ -0,0 +1,11 @@
+import * as tui from '../index.js';
+
+import { describe, expect, it } from 'vitest';
+
+describe('TUI presentation boundary (ARCH-011)', () => {
+  it('exports presentation hosts without claiming borrowed-session transport conformance', () => {
+    expect(tui).not.toHaveProperty('TuiTransport');
+    expect(tui).toHaveProperty('renderApp');
+    expect(tui).toHaveProperty('createDefaultTuiCliAdapter');
+  });
+});