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

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, 'state', '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,
+    'state',
+    '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(), 'agent-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,
+  );
+});

package/src/__tests__/pty/screen-2670-prepark.ptytest.ts

@@ -0,0 +1,228 @@
+/**
+ * SCREEN-2670 TC-09 — the pre-write park on the BUILT CLI binary, in a real PTY.
+ *
+ * A screen reader sees bytes and time, nothing else, so the claim is checked where both exist: the
+ * raw PTY stream is sampled every few milliseconds and each growth is stamped. A COMMIT the park
+ * released arrives as one growth (its chunks are written contiguously); the interval shows up as
+ * the gap between consecutive printable growths. The same fixture runs three ways — park 250 ms,
+ * park 0, mode off — so the interval is attributed to the park and not to the replay.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm build` first).
+ */
+
+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 type { IPtySession } from './pty-driver.js';
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const REPLAY_FIXTURE = join(FIXTURES, 'replay-conversation.jsonl');
+
+const WAIT_MS = 30_000;
+const CASE_TIMEOUT_MS = 120_000;
+/** The park under test — large against the frame cadence, small against the case budget. */
+const PARK_MS = 250;
+/** Sampling period; the gap resolution is twice this. */
+const SAMPLE_MS = 5;
+/** OS and PTY jitter allowance on the asserted interval. */
+const SLACK_MS = 60;
+/** Growths closer than this are one burst: a PTY read can split one contiguous write. */
+const COALESCE_MS = 30;
+
+/** Startup frames settle for this long before the keystroke is measured against a quiet stream. */
+const STARTUP_SETTLE_MS = 750;
+/* eslint-disable no-control-regex -- matching the escapes IS the point here */
+const OSC_133 = /\x1b\]133;[ABCD]\x07/g;
+const ESCAPES = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07|\x1b[()][A-Z0-9]|\x1b[=>]/g;
+/* eslint-enable no-control-regex */
+
+interface IGrowth {
+  at: number;
+  bytes: string;
+}
+
+/**
+ * Sample the raw stream from `since` (an offset taken BEFORE the action — the driver's key pacing
+ * means output can land before this loop starts) until `until` matches or the budget ends; return
+ * every growth stamped.
+ */
+interface IMark {
+  /** Index into the RAW stream (growth detection). */
+  raw: number;
+  /** The driver's mark into the STRIPPED transcript (pattern matching) — the two are not the same. */
+  stripped: number;
+}
+
+function markNow(session: IPtySession): IMark {
+  return { raw: session.raw().length, stripped: session.outputOffset() };
+}
+
+async function sampleUntil(
+  session: IPtySession,
+  since: IMark,
+  until: RegExp,
+  budgetMs: number,
+): Promise<IGrowth[]> {
+  const growths: IGrowth[] = [];
+  let seen = since.raw;
+  const deadline = Date.now() + budgetMs;
+  while (Date.now() < deadline) {
+    const raw = session.raw();
+    if (raw.length > seen) {
+      growths.push({ at: Date.now(), bytes: raw.slice(seen) });
+      seen = raw.length;
+    }
+    if (until.test(session.snapshotSince(since.stripped))) break;
+    await new Promise((resolve) => setTimeout(resolve, SAMPLE_MS));
+  }
+  return growths;
+}
+
+const visible = (bytes: string): string => bytes.replace(ESCAPES, '');
+
+/** Merge growths that landed within `COALESCE_MS` of each other — one contiguous write, one burst. */
+function bursts(growths: IGrowth[]): IGrowth[] {
+  const merged: IGrowth[] = [];
+  for (const growth of growths) {
+    const last = merged.at(-1);
+    if (last !== undefined && growth.at - last.at < COALESCE_MS) last.bytes += growth.bytes;
+    else merged.push({ ...growth });
+  }
+  return merged;
+}
+
+/**
+ * The marks travel through the owned path and keep their place. A replayed reply resolves inside
+ * one commit, so the turn's own B/C/D/A marks are not observable here (their ordering against a
+ * parked batch is pinned by the unit test); what this stream does carry is the mount-time
+ * prompt-start, which must precede the answer rather than surface inside the parked gap after it.
+ */
+function expectMarksOrderedWithTheTurn(raw: string): void {
+  const marks = [...raw.matchAll(OSC_133)].map((match) => ({
+    code: match[0],
+    at: match.index ?? 0,
+  }));
+  const answerAt = raw.indexOf('REPLAYED_ANSWER_42');
+  const promptStarts = marks.filter((mark) => mark.code.includes('133;A'));
+  expect(promptStarts.length).toBeGreaterThanOrEqual(1);
+  expect(promptStarts[0]?.at).toBeLessThan(answerAt);
+}
+
+/**
+ * One paced-free line: the echo commit (exempt) and the turn commit (parked) are provoked within
+ * milliseconds of each other, so the interval between them is the park and nothing else. The reply
+ * itself is replayed as a single chunk, so the turn is ONE commit — which is also what proves the
+ * chunks of a commit stay contiguous: the answer arrives inside one synchronized-output window.
+ */
+interface ITurnTiming {
+  typedAt: number;
+  echoAt: number;
+  answerAt: number;
+  answerBytes: string;
+}
+
+async function typeAndSubmit(session: IPtySession): Promise<ITurnTiming> {
+  const mark = markNow(session);
+  const sampling = sampleUntil(session, mark, /REPLAYED_ANSWER_42[\s\S]*Type a message/, WAIT_MS);
+  // Characters are paced (a single chunk would be read as a paste); the echo latency is measured
+  // from the LAST key, so the driver's per-key pacing is not charged to the park. Enter follows the
+  // last echo immediately, so the turn's commit is provoked within milliseconds of an exempt one.
+  await session.sendKeys('hell');
+  const typedAt = Date.now();
+  await session.sendKeys('o');
+  session.writeRaw('\r');
+  const growths = bursts(await sampling);
+  const echo = growths.find((g) => visible(g.bytes).includes('hello'));
+  const answer = growths.find((g) => visible(g.bytes).includes('REPLAYED_ANSWER_42'));
+  expect(echo, 'the echo of the typed line').toBeDefined();
+  expect(answer, 'the replayed answer').toBeDefined();
+  return {
+    typedAt,
+    echoAt: (echo as IGrowth).at,
+    answerAt: (answer as IGrowth).at,
+    answerBytes: (answer as IGrowth).bytes,
+  };
+}
+
+function spawnScenario(projectDir: string, mode: 'park' | 'zero' | 'off'): IPtySession {
+  const screenReader = mode === 'off' ? [] : ['--screen-reader'];
+  const prepark = mode === 'zero' ? '0' : String(PARK_MS);
+  return spawnTui({
+    projectDir,
+    homeDir: join(projectDir, 'home'),
+    args: ['--session-log', REPLAY_FIXTURE, ...screenReader, '--name', 'prepark-scenario'],
+    env: { PRODUCT_SCREEN_READER_STARTUP_QUIET_MS: '0', PRODUCT_SCREEN_READER_PREPARK_MS: prepark },
+  });
+}
+
+async function settled(session: IPtySession): Promise<void> {
+  await session.waitFor(/Type a message or \/help/, WAIT_MS);
+  await new Promise((resolve) => setTimeout(resolve, STARTUP_SETTLE_MS));
+}
+
+describe('SCREEN-2670 the pre-write park through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-prepark-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-09: the echo is not delayed, the turn commit waits the interval after it, its chunks are contiguous, and the marks stay in order',
+    async () => {
+      session = spawnScenario(projectDir, 'park');
+      await settled(session);
+
+      const timing = await typeAndSubmit(session);
+      // The keystroke's commit is exempt: its echo lands well inside the interval.
+      expect(timing.echoAt - timing.typedAt).toBeLessThan(PARK_MS - SLACK_MS);
+      // The turn's commit is parked: at least the interval after the previous printable release.
+      // Assumption: with a single-chunk replay the answer commit is the LAST printable commit of the
+      // turn's burst; only the last waiting batch is parked, so a later commit inside the interval
+      // would make this measure turn latency instead.
+      expect(timing.answerAt - timing.echoAt).toBeGreaterThanOrEqual(PARK_MS - SLACK_MS);
+      // And it arrived whole: the synchronized-output window opened and closed in one growth.
+      expect(timing.answerBytes).toContain('\x1b[?2026h');
+      expect(timing.answerBytes).toContain('\x1b[?2026l');
+      expectMarksOrderedWithTheTurn(session.raw());
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'TC-09: with the interval 0 no delay is injected',
+    async () => {
+      session = spawnScenario(projectDir, 'zero');
+      await settled(session);
+      const timing = await typeAndSubmit(session);
+      expect(timing.answerAt - timing.echoAt).toBeLessThan(PARK_MS - SLACK_MS);
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'TC-09: with the mode off the park is absent — no interval, bordered UI as before',
+    async () => {
+      session = spawnScenario(projectDir, 'off');
+      await settled(session);
+      const timing = await typeAndSubmit(session);
+      expect(timing.answerAt - timing.echoAt).toBeLessThan(PARK_MS - SLACK_MS);
+      expect(session.snapshot()).toMatch(/[│─╭╮╰╯┌┐└┘]/u);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});