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

package/src/__tests__/pty/screen-006-no-color.ptytest.ts

@@ -0,0 +1,138 @@
+/**
+ * SCREEN-006 User Execution Test Scenarios — color/motion degradation and palette-token colors on
+ * the BUILT robota binary in a real PTY (run by `test:pty`; requires `pnpm build:deps` first).
+ *
+ * Scenario 1 (NO_COLOR legibility): `NO_COLOR=1` through a replayed conversation → the raw pty
+ *   transcript contains ZERO SGR color sequences (30-38/40-48/90-97/100-107 params, incl. 38;5 /
+ *   48;5 extended forms). Because NO color code may appear at all, this also proves the repeated
+ *   waiting-state frames show zero WaveText color churn (motion is static: the
+ *   `isInteractiveColorTerminal()` gate creates no interval under NO_COLOR).
+ * Scenario 2 (normal-run consistency): color on → the persisted tool summary renders the
+ *   `STATUS_SYMBOL.success` glyph in the resolved theme's status color (green, ESC[32m — sourced
+ *   from `colors.status` through `statusGlyphColor`), the assistant label renders the accent token
+ *   (cyan, ESC[36m), and the markdown diff block carries the theme's diff SGR pairs (38;5;120 on
+ *   48;5;22 for added lines under the default `dark` theme).
+ *   Reachability note (recorded limit): a permission DENY short-circuits before tool-start, so the
+ *   framework emits no tool-summary entry for it — the denied (`yellowBright`) unification is
+ *   therefore pinned at component level (`message-list-rendering.test.tsx`), while this scenario
+ *   evidences the same glyph→status-colour sourcing end-to-end via the success kind.
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+import { DARK_THEME } from '../../theme/built-in-themes.js';
+import { background, foreground } from '../../theme/index.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const REPLAY_FIXTURE = join(FIXTURES, 'replay-conversation.jsonl');
+const COLORS_FIXTURE = join(FIXTURES, 'screen-006-colors.jsonl');
+
+/** SGR params that set a color (foreground/background, basic/bright/extended). */
+const COLOR_PARAM = /^(?:3[0-8]|39|4[0-8]|49|9[0-7]|10[0-7])$/;
+
+/** Every SGR color param present in a raw pty transcript (e.g. ['33', '38;5;210'→'38']). */
+function sgrColorParams(raw: string): string[] {
+  const params: string[] = [];
+  // eslint-disable-next-line no-control-regex -- scanning raw SGR escape bytes by design
+  for (const match of raw.matchAll(/\x1b\[([0-9;]*)m/g)) {
+    // In an extended sequence (38;5;n / 48;5;n) the payload params are not themselves
+    // color-setters, but the leading 38/48 is — flagging it is sufficient and exact.
+    for (const param of (match[1] === '' ? '0' : match[1]).split(';')) {
+      if (COLOR_PARAM.test(param)) {
+        params.push(param);
+        break; // one flagged param per sequence is enough evidence
+      }
+    }
+  }
+  return params;
+}
+
+describe('SCREEN-006 color/motion through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-screen006-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('S1: NO_COLOR=1 → legible output, zero SGR color sequences, no animation', async () => {
+    session = spawnTui({
+      projectDir,
+      homeDir: join(projectDir, 'home'),
+      args: ['--session-log', REPLAY_FIXTURE],
+      env: { NO_COLOR: '1' },
+    });
+
+    await session.waitFor(/Type a message or \/help/);
+    await session.sendKeys('hello');
+    await session.pressEnter();
+
+    // The replayed turn completes and the output stays legible (content + labels present).
+    await session.waitFor(/REPLAYED_ANSWER_42/, 20_000);
+    await session.waitFor(/Type a message or \/help/, 20_000);
+
+    const stripped = session.snapshot();
+    expect(stripped).toContain('You:');
+    expect(stripped).toContain('REPLAYED_ANSWER_42');
+
+    // Zero SGR color sequences in the ENTIRE raw transcript — which also proves the
+    // waiting-state (WaveText) frames carried zero color churn under NO_COLOR.
+    expect(sgrColorParams(session.raw())).toEqual([]);
+  }, 60_000);
+
+  it('S2: color on → tool summary uses the themes status color, labels use accent, diff uses the themes pairs', async () => {
+    session = spawnTui({
+      projectDir,
+      homeDir: join(projectDir, 'home'),
+      args: ['--session-log', COLORS_FIXTURE],
+    });
+
+    await session.waitFor(/Type a message or \/help/);
+    await session.sendKeys('go');
+    await session.pressEnter();
+
+    // The replayed Shell call needs approval in default permission mode → allow it.
+    await session.waitFor(/Permission Required/, 20_000);
+    await session.sendKeys('y');
+
+    // The turn continues: the second replayed response carries the markdown diff block,
+    // and the persisted tool summary lands at turn end.
+    await session.waitFor(/SCREEN006_DIFF_DONE/, 20_000);
+    await session.waitFor(/✓ Shell/, 10_000);
+
+    const stripped = session.snapshot();
+    const raw = session.raw();
+
+    // Persisted tool summary: SSOT glyph + the theme's status colour (success → green, ESC[32m)
+    // rendered by the unified MessageList path (STATUS_SYMBOL + statusGlyphColor).
+    expect(stripped).toContain('✓ Shell');
+    // eslint-disable-next-line no-control-regex -- asserting on raw SGR escape bytes by design
+    expect(raw).toMatch(/\x1b\[32m[^\x1b]*✓ Shell/);
+
+    // Assistant label renders the accent token (cyan → ESC[36m ... "Robota:").
+    // eslint-disable-next-line no-control-regex -- asserting on raw SGR escape bytes by design
+    expect(raw).toMatch(/\x1b\[36m(?:\x1b\[[0-9;]*m)*Robota:/);
+
+    // Markdown diff block carries the resolved theme's SGR pair (added line: light green on a dark
+    // green background) — SCREEN-2002 moved the values into the theme, the bytes are unchanged.
+    const addedBackground = background(DARK_THEME.markdown.diffAddedBackground)('x').split('x')[0];
+    const addedForeground = foreground(DARK_THEME.markdown.diffAdded)('x').split('x')[0];
+    expect(raw).toContain(`${addedBackground}${addedForeground}`);
+    expect(stripped).toContain('+ added line');
+  }, 60_000);
+});

package/src/__tests__/pty/screen-010-scrollback.ptytest.ts

@@ -0,0 +1,123 @@
+/**
+ * SCREEN-010 TC-05: chat-window scrollback layout, on the real binary.
+ *
+ * Runs in the PTY vitest project against the BUILT robota CLI. Automates the former "manual" smoke
+ * (per the never-ask-the-user-to-test rule): generates committed output larger than a small viewport
+ * and asserts the committed history is emitted to the terminal's native scrollback while the input
+ * prompt + status bar stay pinned at the bottom. Once committed content is in scrollback and the input
+ * is pinned, native terminal scroll-back is the terminal's own behavior (not the app's), so this is
+ * the automatable essence of TC-05.
+ *
+ * CLI-2004 TC-22 adds the same proof under `--screen-reader`. Ink's `alternateScreen` defaults to
+ * false and nothing in the tree sets it — this is the GUARD on that, not new behaviour: the
+ * alternate screen has no scrollback, and reviewing earlier output is the whole reason a reader can
+ * use this TUI at all. The flagless case above cannot serve as the guard, because it asserts on the
+ * boot banner and on `Idle`, both of which the mode suppresses.
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+/**
+ * The heading of the COMMITTED `/help` output, and the reason it is this precise.
+ *
+ * `Available commands` without the colon is also `/help`'s own DESCRIPTION, which the slash
+ * autocomplete renders while the command is still being typed — four times over, before Enter is
+ * handled at all. Waiting on that returns immediately and leaves the snapshot below racing the
+ * commit; the case then asserts "the prompt is below the committed output" against a frame in which
+ * nothing has been committed yet. It passed only because the commit usually won that race, and a
+ * loaded runner is where it does not. The colon appears only in the committed block.
+ */
+const COMMITTED_HELP_HEADING = /Available commands:/;
+
+/** Wait budgets: one `waitFor`, and a whole case, on a loaded CI runner. */
+const PROMPT_WAIT_MS = 30_000;
+const COMMANDS_WAIT_MS = 20_000;
+const CASE_TIMEOUT_MS = 60_000;
+
+describe('SCREEN-010 chat-window scrollback layout (real binary)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-scrollback-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-05: committed history fills scrollback beyond the viewport while the input stays pinned',
+    async () => {
+      // Small viewport so the committed /help output exceeds it and scrolls into scrollback.
+      session = spawnTui({ projectDir, homeDir: join(projectDir, 'home'), rows: 16 });
+
+      await session.waitFor(/Type a message or \/help/);
+      await session.waitFor(/Idle/);
+
+      // /help commits a long command list (> 16 rows) to history → Ink <Static> → scrollback.
+      await session.sendKeys('/help');
+      await session.pressEnter();
+      await session.waitFor(COMMITTED_HELP_HEADING, COMMANDS_WAIT_MS);
+
+      const snap = session.snapshot();
+
+      // Committed content is present (emitted to scrollback), and the banner committed at boot remains.
+      const committedIdx = snap.search(COMMITTED_HELP_HEADING);
+      expect(committedIdx).toBeGreaterThanOrEqual(0);
+      expect((snap.match(/v\d+\.\d+\.\d+/g) ?? []).length).toBeGreaterThanOrEqual(1);
+
+      // The input prompt re-renders at the BOTTOM (live region): its last occurrence is below the
+      // committed command-list output — i.e. the input is pinned while committed history sits above it.
+      const lastPromptIdx = snap.lastIndexOf('Type a message');
+      expect(lastPromptIdx).toBeGreaterThan(committedIdx);
+
+      // The status bar is also pinned in the live region.
+      expect(snap.lastIndexOf('Idle')).toBeGreaterThan(committedIdx);
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'CLI-2004 TC-22: --screen-reader never switches to the alternate screen and keeps history in scrollback',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        rows: 16,
+        args: ['--screen-reader'],
+        env: { ROBOTA_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, PROMPT_WAIT_MS);
+
+      await session.sendKeys('/help');
+      await session.pressEnter();
+      await session.waitFor(/Available commands|\/exit/i, COMMANDS_WAIT_MS);
+
+      // No alternate-screen switch at ANY point in the run — the mode must not buy a tidy frame at
+      // the price of the terminal's own scrollback.
+      expect(session.raw()).not.toContain('\x1b[?1049h');
+
+      const snap = session.snapshot();
+      const committedIdx = snap.search(/Available commands|\/exit/i);
+      expect(committedIdx).toBeGreaterThanOrEqual(0);
+
+      // The input stays pinned below the committed history — asserted without the banner or `Idle`,
+      // which the mode suppresses.
+      expect(snap.lastIndexOf('Type a message')).toBeGreaterThan(committedIdx);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

package/src/__tests__/pty/screen-1993-scrollback.ptytest.ts

@@ -0,0 +1,124 @@
+/**
+ * SCREEN-1993 TC-10: the transcript decision's evidence, on the real binary.
+ *
+ * The item asked for a way to "search prompt history and conversation transcripts"; the spec ships
+ * prompt-history search and REJECTS an in-app transcript viewer because the terminal's own scrollback
+ * already holds the whole transcript (`<Static>` commits every message, and nothing ever switches to
+ * the alternate screen, which has no scrollback). That reason is only as good as its proof: resume a
+ * persisted session of more than 100 messages in a small viewport and assert every message text is
+ * in the captured output without a single key pressed — and that `ESC [ ? 1049 h` never appears.
+ */
+
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const SESSION_ID = 'screen-1993-transcript';
+const TURNS = 60; // 120 messages: 60 user prompts and 60 assistant replies
+const PROMPT_WAIT_MS = 30_000;
+const FIXTURE_YEAR = 2026;
+const CASE_TIMEOUT_MS = 90_000;
+
+function messageText(index: number, role: 'user' | 'assistant'): string {
+  return role === 'user'
+    ? `transcript prompt ${index} of ${TURNS}`
+    : `transcript reply ${index} of ${TURNS}`;
+}
+
+/** A persisted session in the store's versioned envelope: `messages` for the model, `history` for the UI. */
+function seedSession(homeDir: string, cwd: string): void {
+  const at = (index: number): string =>
+    new Date(Date.UTC(FIXTURE_YEAR, 0, 1, 0, 0, index)).toISOString();
+  const messages = [];
+  const history = [];
+  for (let index = 1; index <= TURNS; index += 1) {
+    for (const role of ['user', 'assistant'] as const) {
+      const content = messageText(index, role);
+      messages.push({
+        id: `m-${role}-${index}`,
+        timestamp: at(index),
+        state: 'complete',
+        role,
+        content,
+      });
+      history.push({
+        id: `${role}-${index}`,
+        timestamp: at(index),
+        category: 'chat',
+        type: role,
+        data: { role, content },
+      });
+    }
+  }
+  const sessionsDir = join(homeDir, '.robota', 'sessions');
+  mkdirSync(sessionsDir, { recursive: true });
+  writeFileSync(
+    join(sessionsDir, `${SESSION_ID}.json`),
+    JSON.stringify({
+      schemaVersion: 1,
+      record: {
+        id: SESSION_ID,
+        name: 'transcript-fixture',
+        cwd,
+        createdAt: at(0),
+        updatedAt: at(TURNS),
+        messages,
+        history,
+      },
+    }),
+    'utf8',
+  );
+}
+
+describe('SCREEN-1993 TC-10: the resumed transcript lives in native scrollback', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-1993-scrollback-')));
+    writeTuiProviderSettings(projectDir);
+    seedSession(join(projectDir, 'home'), projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'every one of 120 restored messages is in the terminal output with no key pressed, and no alternate screen',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        rows: 16,
+        args: ['--resume', SESSION_ID, '--name', 'transcript-fixture'],
+      });
+      await session.waitFor(/Type a message or \/help/, PROMPT_WAIT_MS);
+      await session.waitFor(new RegExp(messageText(TURNS, 'assistant')), PROMPT_WAIT_MS);
+
+      const snapshot = session.snapshot();
+      const missing: string[] = [];
+      for (let index = 1; index <= TURNS; index += 1) {
+        for (const role of ['user', 'assistant'] as const) {
+          if (!snapshot.includes(messageText(index, role))) missing.push(messageText(index, role));
+        }
+      }
+      expect(missing).toEqual([]);
+      // The transcript is above the live region: the input is pinned below the last message.
+      expect(snapshot.lastIndexOf('Type a message')).toBeGreaterThan(
+        snapshot.indexOf(messageText(TURNS, 'assistant')),
+      );
+      // The alternate screen has no scrollback; the TUI never enters it.
+      expect(session.raw()).not.toContain('\x1b[?1049h');
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

package/src/__tests__/pty/screen-2002-themes.ptytest.ts

@@ -0,0 +1,292 @@
+/**
+ * SCREEN-2002 TC-13 — themes, user theme files and plugin theme files, through the BUILT binary in
+ * a real PTY (run by `test:pty`; requires `pnpm build:deps` first).
+ *
+ * What only this level can show: that the theme a user chooses reaches the terminal's actual bytes
+ * without a restart, that a theme FILE they wrote is discovered from their home directory and a
+ * plugin's from its own, and that a file the run refused is visible to them — at startup and in the
+ * picker — rather than silently missing from the list.
+ *
+ * The transcript is Ink `<Static>` and is not repainted, so a theme change moves the LIVE region;
+ * assertions take an offset mark first and read only what arrived after it.
+ */
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const THEME_FIXTURE = join(FIXTURES, 'screen-2002-themes.jsonl');
+
+const PROMPT = /Type a message or \/help/;
+const SNIPPET_DONE = /SCREEN2002_SNIPPET_DONE/;
+const ACCENT = '#56b4e9';
+
+/** Named because a bare number in a call is a lint warning, and because each one means something. */
+const BOOT_MS = 30_000;
+const STEP_MS = 20_000;
+const TURN_MS = 40_000;
+const CASE_MS = 150_000;
+/** More than the single reset a plain frame carries. */
+const MINIMUM_SGR_VARIETY = 1;
+
+/** Every SGR sequence in a slice of the raw transcript, as a set — the frame's colour vocabulary. */
+function sgrVocabulary(raw: string): Set<string> {
+  const found = new Set<string>();
+  // eslint-disable-next-line no-control-regex -- scanning raw SGR escape bytes by design
+  for (const match of raw.matchAll(/\x1b\[([0-9;]*)m/g)) found.add(match[1] ?? '');
+  return found;
+}
+
+/** The raw bytes of the rendered line that holds the snippet, if the frame carried it. */
+function snippetLine(raw: string): string {
+  return raw.split(/\r?\n/u).find((line) => line.includes('answer') && line.includes('42')) ?? '';
+}
+
+function seedThemeFiles(homeDir: string): void {
+  const themes = join(homeDir, '.robota', 'themes');
+  mkdirSync(themes, { recursive: true });
+  writeFileSync(
+    join(themes, 'mine.json'),
+    JSON.stringify({
+      name: 'Mine',
+      base: 'dark',
+      // Tokens the IDLE frame actually paints with. Overriding `text.accent` alone proves nothing
+      // here: the accent labels live in the transcript, which is `<Static>` and is never repainted,
+      // so a run with nothing submitted would show the same bytes either way.
+      overrides: {
+        colors: {
+          text: { accent: ACCENT, muted: ACCENT },
+          border: { focused: ACCENT, muted: ACCENT },
+          status: { idle: ACCENT },
+        },
+      },
+    }),
+  );
+  writeFileSync(
+    join(themes, 'broken.json'),
+    JSON.stringify({ overrides: { colors: { text: { accent: 'not-a-colour' } } } }),
+  );
+
+  const pluginVersionDir = join(
+    homeDir,
+    '.robota',
+    'plugins',
+    'cache',
+    'fixtures',
+    'theme-fixture',
+    '1.0.0',
+  );
+  mkdirSync(join(pluginVersionDir, '.claude-plugin'), { recursive: true });
+  writeFileSync(
+    join(pluginVersionDir, '.claude-plugin', 'plugin.json'),
+    JSON.stringify({
+      name: 'theme-fixture',
+      version: '1.0.0',
+      description: 'a themes-only fixture plugin',
+      features: {},
+    }),
+  );
+  mkdirSync(join(pluginVersionDir, 'themes'), { recursive: true });
+  writeFileSync(
+    join(pluginVersionDir, 'themes', 'plugged.json'),
+    JSON.stringify({ name: 'Plugged', base: 'light' }),
+  );
+}
+
+describe('SCREEN-2002 themes through the real binary', () => {
+  let projectDir: string;
+  let homeDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'robota-screen2002-pty-')));
+    writeTuiProviderSettings(projectDir);
+    homeDir = join(projectDir, 'home');
+    seedThemeFiles(homeDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'S1: lists user and plugin themes, refuses a broken file out loud, and switches without a restart',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir,
+        args: ['--session-log', THEME_FIXTURE],
+        env: { FORCE_COLOR: '3' },
+      });
+
+      // The refused file says so ONCE, at startup, with the path that refused it.
+      await session.waitFor(
+        /Skipped theme "broken\.json": \$\.overrides\.colors\.text\.accent/,
+        BOOT_MS,
+      );
+      await session.waitFor(PROMPT, BOOT_MS);
+
+      // `/theme list` sees the built-ins AND both files, each with where it came from.
+      const listMark = session.outputOffset();
+      await session.sendKeys('/theme list');
+      await session.pressEnter();
+      await session.waitForSince(listMark, /Available themes:/, STEP_MS);
+      const listed = session.snapshotSince(listMark);
+      expect(listed).toContain('dark — Dark');
+      expect(listed).toContain('custom:mine — Mine (dark, user)');
+      expect(listed).toContain('custom:theme-fixture:plugged — Plugged (light, plugin)');
+
+      // Applying the user's own theme puts ITS accent colour on the wire, with no restart.
+      const applyMark = session.outputOffset();
+      // A RAW mark of its own: `outputOffset()` indexes the ANSI-STRIPPED transcript, so slicing
+      // `raw()` with it lands at an unrelated byte.
+      const applyRawMark = session.raw().length;
+      await session.sendKeys('/theme custom:mine');
+      await session.pressEnter();
+      await session.waitForSince(applyMark, /Applied: theme Mine/, STEP_MS);
+      await session.waitForSince(applyMark, PROMPT, STEP_MS);
+      // `#56b4e9` as this terminal encodes it. The PTY is `xterm-256color` with no `COLORTERM`, so
+      // the depth is 256 and the hex downsamples to index 117 — asserting truecolor here would be
+      // asserting the harness's terminal rather than the theme.
+      expect(session.raw().slice(applyRawMark)).toContain('38;5;117');
+    },
+    CASE_MS,
+  );
+
+  it(
+    'S2: the picker previews on move, restores on escape, and shows the refused file as a row',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir,
+        args: ['--session-log', THEME_FIXTURE],
+        env: { FORCE_COLOR: '3' },
+      });
+      await session.waitFor(PROMPT, BOOT_MS);
+
+      const openMark = session.outputOffset();
+      const openRawMark = session.raw().length;
+      await session.sendKeys('/theme');
+      await session.pressEnter();
+      await session.waitForSince(openMark, /Theme/, STEP_MS);
+      // The refused file is a row that carries its reason — the startup line has long since scrolled.
+      await session.waitForSince(openMark, /Skipped "broken\.json"/, STEP_MS);
+
+      // Moving the highlight repaints the live region in the previewed theme: new SGR appears that
+      // the frame did not carry before the move. The arrow goes through `writeRaw` — `sendKeys`
+      // paces per character, so the leading Escape would arrive alone and CANCEL the picker.
+      const before = sgrVocabulary(session.raw().slice(openRawMark));
+      const moveMark = session.outputOffset();
+      const moveRawMark = session.raw().length;
+      session.writeRaw('\x1b[B');
+      await session.waitForSince(moveMark, /> Light — light, built-in/, STEP_MS);
+      const after = sgrVocabulary(session.raw().slice(moveRawMark));
+      expect([...after].some((sequence) => !before.has(sequence))).toBe(true);
+
+      // Escape leaves the persisted theme in place. Not only "nothing was applied": the colours the
+      // PREVIEW introduced are gone from the frame, which is what "restores" has to mean when the
+      // preview was visible rather than merely recorded.
+      const previewed = [...after].filter((sequence) => !before.has(sequence));
+      expect(previewed.length).toBeGreaterThan(0);
+      const escapeMark = session.outputOffset();
+      const escapeRawMark = session.raw().length;
+      session.pressEscape();
+      await session.waitForSince(escapeMark, PROMPT, STEP_MS);
+      const restored = sgrVocabulary(session.raw().slice(escapeRawMark));
+      // The symmetric guard: a post-escape slice carrying no SGR at all would satisfy the filter
+      // below without measuring anything, which is the fail-toward-green shape S3 also had.
+      expect(restored.size).toBeGreaterThan(0);
+      expect(previewed.filter((sequence) => restored.has(sequence))).toEqual([]);
+      expect(session.snapshotSince(escapeMark)).not.toContain('Applied: theme');
+    },
+    CASE_MS,
+  );
+
+  it(
+    'S3: syntax highlighting is switched off for later renders and the scrollback keeps its own',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir,
+        args: ['--session-log', THEME_FIXTURE],
+        env: { FORCE_COLOR: '3' },
+      });
+      await session.waitFor(PROMPT, BOOT_MS);
+
+      const firstMark = session.outputOffset();
+      const firstRawMark = session.raw().length;
+      await session.sendKeys('show me a snippet');
+      await session.pressEnter();
+      await session.waitForSince(firstMark, SNIPPET_DONE, TURN_MS);
+      const highlighted = session.raw().slice(firstRawMark);
+      // The TEXT is read from the stripped transcript: a highlighted block carries SGR BETWEEN its
+      // tokens, so the source line is not contiguous in the raw bytes — which is the point.
+      expect(session.snapshotSince(firstMark)).toContain('const answer = 42;');
+      // cli-highlight coloured the keyword: the block carries SGR the plain text would not.
+      expect(sgrVocabulary(highlighted).size).toBeGreaterThan(MINIMUM_SGR_VARIETY);
+
+      const offMark = session.outputOffset();
+      await session.sendKeys('/theme syntax off');
+      await session.pressEnter();
+      await session.waitForSince(offMark, /syntax highlighting off/, STEP_MS);
+
+      const secondMark = session.outputOffset();
+      const secondRawMark = session.raw().length;
+      await session.sendKeys('show me a snippet');
+      await session.pressEnter();
+      await session.waitForSince(secondMark, SNIPPET_DONE, TURN_MS);
+
+      // The same source, rendered again. Asserting only that the TEXT is there would pass whether
+      // or not `/theme syntax off` reached a render site — which is the defect this package has
+      // already shipped once — so the assertion is on the line's own SGR: the second render of the
+      // same line carries strictly fewer distinct sequences than the highlighted first.
+      const plain = session.raw().slice(secondRawMark);
+      expect(session.snapshotSince(secondMark)).toContain('const answer = 42;');
+      // Both lines must actually be there. Without this the comparison is asymmetric toward green:
+      // a missing second line measures zero sequences and every assertion below passes.
+      expect(snippetLine(highlighted)).not.toBe('');
+      expect(snippetLine(plain)).not.toBe('');
+      const highlightedLine = sgrVocabulary(snippetLine(highlighted));
+      const plainLine = sgrVocabulary(snippetLine(plain));
+      expect(highlightedLine.size).toBeGreaterThan(plainLine.size);
+      expect([...highlightedLine].some((sequence) => !plainLine.has(sequence))).toBe(true);
+    },
+    CASE_MS,
+  );
+
+  it(
+    'S4: --reduced-motion is reported as pinned for the run, and colour stays on',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir,
+        args: ['--session-log', THEME_FIXTURE, '--reduced-motion'],
+        env: { FORCE_COLOR: '3' },
+      });
+      await session.waitFor(PROMPT, BOOT_MS);
+
+      const mark = session.outputOffset();
+      const rawMark = session.raw().length;
+      await session.sendKeys('/theme list');
+      await session.pressEnter();
+      await session.waitForSince(mark, /Available themes:/, STEP_MS);
+      const listed = session.snapshotSince(mark);
+      // The pin is reported, not silently obeyed.
+      // What THIS RUN does, and what is saved — two facts, never one in place of the other. This
+      // line is the defect TC-13 found: it read `reduced motion: off (… pinned by flag)`.
+      expect(listed).toContain('reduced motion: on for this run (pinned by flag; saved off)');
+      // Colour is untouched by the motion decision.
+      expect(sgrVocabulary(session.raw().slice(rawMark)).size).toBeGreaterThan(MINIMUM_SGR_VARIETY);
+    },
+    CASE_MS,
+  );
+});