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

package/src/terminal-handoff-controller.ts

@@ -0,0 +1,98 @@
+/**
+ * TERM-002: TUI implementation of the `ITerminalHandoff` transport contract.
+ *
+ * Manual suspend/resume (NOT Ink 7.1.0 `suspendTerminal`): while a child process owns the real
+ * terminal, the App renders nothing so Ink unmounts its input hooks and releases raw mode; the Ink
+ * frame is cleared; the caller's `fn` runs the child with inherited stdio; then the App re-renders.
+ *
+ * The framework (`InteractiveSession`) owns the orchestration (exclusivity, fast-fail) — this class
+ * only performs the actual screen release/reclaim. It spawns nothing itself (platform-neutral).
+ */
+import type { ITerminalHandoff } from '@robota-sdk/agent-interface-session';
+
+/** How the App suspends/resumes its rendering, registered into the controller on mount. */
+export interface ITuiSuspendHooks {
+  /** Render nothing (release Ink input/raw mode); resolves once that has committed. */
+  suspend(): Promise<void>;
+  /** Resume rendering and force a redraw. */
+  resume(): void;
+}
+
+/**
+ * SCREEN-1992: terminal modes the TUI negotiated (focus reporting) are released before a child owns
+ * the terminal and re-negotiated once it is reclaimed, so the child never receives `CSI I`/`CSI O`
+ * and a child that reset the mode does not leave the TUI blind afterwards.
+ */
+export interface ITerminalModeHooks {
+  /** May be async: SCREEN-2670 drains the parked screen-reader output before the child gets the TTY. */
+  preSuspend(): void | Promise<void>;
+  postResume(): void;
+}
+
+/** Minimal slice of the Ink render instance the controller needs. */
+export interface IInkClearable {
+  clear(): void;
+}
+
+export class TerminalHandoffController implements ITerminalHandoff {
+  private hooks?: ITuiSuspendHooks;
+  private instance?: IInkClearable;
+  private modeHooks?: ITerminalModeHooks;
+
+  /**
+   * The App registers how to suspend/resume Ink. Returns an unregister function for cleanup on
+   * unmount. Only a mounted App provides these hooks, which gates `canHandoffTerminal`.
+   */
+  registerSuspendHooks(hooks: ITuiSuspendHooks): () => void {
+    this.hooks = hooks;
+    return () => {
+      if (this.hooks === hooks) this.hooks = undefined;
+    };
+  }
+
+  /** render.tsx registers the terminal-mode bracket (SCREEN-1992) before `render()`. */
+  setTerminalModeHooks(hooks: ITerminalModeHooks | undefined): void {
+    this.modeHooks = hooks;
+  }
+
+  /** render.tsx supplies the Ink instance (for `clear()`) after `render()` returns. */
+  setInkInstance(instance: IInkClearable): void {
+    this.instance = instance;
+  }
+
+  get canHandoffTerminal(): boolean {
+    return (
+      process.stdin.isTTY === true && process.stdout.isTTY === true && this.hooks !== undefined
+    );
+  }
+
+  async runWithTerminal<T>(fn: () => Promise<T>): Promise<T> {
+    const hooks = this.hooks;
+    if (!this.canHandoffTerminal || hooks === undefined) {
+      throw new Error(
+        'TUI terminal handoff unavailable: no interactive TTY, or the App is not mounted.',
+      );
+    }
+    await hooks.suspend();
+    await this.modeHooks?.preSuspend();
+    this.instance?.clear();
+    // Releasing Ink's React input hooks (empty render) is not enough: the parent process still holds
+    // a raw-mode TTY read on stdin, which (a) steals input from the inherited child and (b) starves
+    // the parent event loop so the child's exit is never observed — the handoff would hang forever.
+    // Explicitly hand stdin to the child by dropping raw mode and pausing the parent's reader; Ink
+    // re-grabs stdin (raw mode + resume) when its input hooks re-mount on resume.
+    const stdin = process.stdin;
+    if (stdin.isTTY && typeof stdin.setRawMode === 'function') stdin.setRawMode(false);
+    stdin.pause();
+    try {
+      return await fn();
+    } finally {
+      // Always reclaim the screen, even when the child failed. Re-rendering re-mounts the input
+      // hooks, which is what restores raw mode and resumes the parent's stdin reader.
+      if (stdin.isTTY && typeof stdin.setRawMode === 'function') stdin.setRawMode(true);
+      stdin.resume();
+      hooks.resume();
+      this.modeHooks?.postResume();
+    }
+  }
+}

package/src/terminal-marks.ts

@@ -0,0 +1,63 @@
+/**
+ * CLI-2004 — OSC 133 shell-integration marks at agent-turn boundaries.
+ *
+ * `OSC 133 ; A` marks prompt start, `; B` prompt end, `; C` pre-execution and `; D` execution
+ * finished. Terminals that implement the protocol turn those into jump-to-previous-prompt
+ * navigation, which is how a reader reviews a long session without scrolling line by line.
+ *
+ * Written OUTSIDE Ink, following the `use-terminal-title.ts` carve-out: `sanitize-terminal-text.ts`
+ * strips OSC from untrusted text and the `tui-safe-text-boundary` scan permits only `SafeText` to
+ * import Ink's `Text`, so an escape sequence this package writes deliberately cannot go through a
+ * component. Unlike the title writer there is no interpolated payload here at all — the four
+ * sequences are constants — so nothing needs sanitizing.
+ *
+ * A terminal that does not implement OSC 133 discards the unknown sequence silently, so emission is
+ * safe wherever it is on; `supportsTurnMarks()` (terminal-capabilities.ts) carries the documented
+ * negatives rather than a capability probe.
+ */
+
+/** The four boundary marks, in the order one turn emits them. */
+export type TTurnMark = 'promptStart' | 'promptEnd' | 'turnStart' | 'turnEnd';
+
+const MARK_CODES: Readonly<Record<TTurnMark, string>> = {
+  promptStart: 'A',
+  promptEnd: 'B',
+  turnStart: 'C',
+  turnEnd: 'D',
+};
+
+/** The exact byte sequence for one mark. */
+export function turnMarkSequence(mark: TTurnMark): string {
+  return `\x1b]133;${MARK_CODES[mark]}\x07`;
+}
+
+export interface ITurnMarkWriterOptions {
+  /** Screen-reader mode. Off ⇒ nothing is ever written. */
+  enabled: boolean;
+  /** Documented per-terminal support gate. */
+  supported: () => boolean;
+  /** Injected sink; defaults to the process's own stdout. */
+  write?: (text: string) => void;
+}
+
+export interface ITurnMarkWriter {
+  emit(mark: TTurnMark): void;
+}
+
+/**
+ * Build the mark writer. Both gates are read at emit time, not construction time, so a test can flip
+ * the support gate between emissions without rebuilding the writer.
+ */
+export function createTurnMarkWriter(options: ITurnMarkWriterOptions): ITurnMarkWriter {
+  const write =
+    options.write ??
+    ((text: string): void => {
+      process.stdout.write(text);
+    });
+  return {
+    emit(mark: TTurnMark): void {
+      if (!options.enabled || !options.supported()) return;
+      write(turnMarkSequence(mark));
+    },
+  };
+}

package/src/theme/__tests__/built-in-themes.test.ts

@@ -0,0 +1,117 @@
+/**
+ * SCREEN-2002 TC-01/TC-05 — the built-in themes as data, and the pairing the palette floor guards.
+ *
+ * Succeeds the SCREEN-006 `tui-palette.test.ts`: the same mechanics (every leaf is a colour in the
+ * grammar, the wave ramp is four stops, status covers the seven kinds), now over four themes instead
+ * of one map, plus the pairing `status-glyph` used to hold as a constant — a symbol for every kind a
+ * theme colours, so a status is never colour alone.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_APPEARANCE_SETTINGS } from '@robota-sdk/agent-framework';
+
+import { BUILT_IN_THEMES, DARK_THEME, DEFAULT_THEME_ID } from '../built-in-themes.js';
+import { isThemeColor } from '../theme-styles.js';
+import { STATUS_SYMBOL, statusGlyphColor, type TUiStatusKind } from '../../status-glyph.js';
+
+import type { ITuiTheme } from '../theme-contracts.js';
+
+const KINDS: readonly TUiStatusKind[] = [
+  'running',
+  'success',
+  'error',
+  'denied',
+  'waiting',
+  'cancelled',
+  'idle',
+];
+
+const HEX_PATTERN = /^#[0-9a-fA-F]{6}$/u;
+
+function leaves(theme: ITuiTheme): [string, string][] {
+  const entries: [string, string][] = [];
+  for (const [group, values] of Object.entries(theme.colors)) {
+    for (const [token, value] of Object.entries(values)) {
+      entries.push([`colors.${group}.${token}`, value as string]);
+    }
+  }
+  for (const [token, value] of Object.entries(theme.markdown))
+    entries.push([`markdown.${token}`, value]);
+  for (const [token, value] of Object.entries(theme.syntax))
+    entries.push([`syntax.${token}`, value]);
+  theme.motion.wave.forEach((value, index) => entries.push([`motion.wave[${index}]`, value]));
+  return entries;
+}
+
+describe('built-in themes (SCREEN-2002 TC-01)', () => {
+  it.each(BUILT_IN_THEMES.map((theme) => [theme.id, theme] as const))(
+    '%s: every leaf is a colour in Ink’s grammar',
+    (_id, theme) => {
+      const invalid = leaves(theme).filter(([, value]) => !isThemeColor(value));
+      expect(invalid).toEqual([]);
+    },
+  );
+
+  it.each(BUILT_IN_THEMES.map((theme) => [theme.id, theme] as const))(
+    '%s: the wave ramp is four stops and status covers the seven kinds',
+    (_id, theme) => {
+      expect(theme.motion.wave).toHaveLength(4);
+      expect(Object.keys(theme.colors.status).sort()).toEqual([...KINDS].sort());
+    },
+  );
+
+  it('ships one dark and one light variant of each family, with unique ids', () => {
+    const ids = BUILT_IN_THEMES.map((theme) => theme.id);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(ids).toEqual(['dark', 'light', 'dark-daltonized', 'light-daltonized']);
+    expect(BUILT_IN_THEMES.filter((theme) => theme.appearance === 'light')).toHaveLength(2);
+    expect(BUILT_IN_THEMES.every((theme) => theme.source === 'built-in')).toBe(true);
+  });
+
+  it('specifies the daltonized pair in hex so the CVD guard can simulate it', () => {
+    for (const theme of BUILT_IN_THEMES.filter((candidate) =>
+      candidate.id.endsWith('daltonized'),
+    )) {
+      const named = leaves(theme).filter(([, value]) => !HEX_PATTERN.test(value));
+      expect(named).toEqual([]);
+    }
+  });
+});
+
+describe('status is never colour alone (SCREEN-2002 TC-05)', () => {
+  it.each(KINDS)('%s has a symbol and a colour in every theme', (kind) => {
+    expect(STATUS_SYMBOL[kind].length).toBeGreaterThan(0);
+    for (const theme of BUILT_IN_THEMES) {
+      expect(isThemeColor(statusGlyphColor(theme.colors, kind))).toBe(true);
+    }
+  });
+
+  it('keeps the dark theme’s status colours identical to the values the package shipped', () => {
+    expect(DARK_THEME.colors.status).toEqual({
+      running: 'yellow',
+      success: 'green',
+      error: 'red',
+      denied: 'yellowBright',
+      waiting: 'yellow',
+      cancelled: 'yellow',
+      idle: 'gray',
+    });
+  });
+});
+
+/**
+ * SCREEN-2002: the settings document's default theme id and this package's default built-in are two
+ * declarations of one fact, in two packages, because the dependency runs one way — `agent-framework`
+ * cannot read the catalogue. A silent divergence would not crash: it would resolve to "theme
+ * `<id>` is not installed" on every startup for a user who set nothing, which is the failure mode
+ * hardest to attribute. So it is pinned here, where both are importable.
+ */
+describe('the default theme id has one meaning across packages', () => {
+  it('matches the appearance settings default', () => {
+    expect(DEFAULT_THEME_ID).toBe(DEFAULT_APPEARANCE_SETTINGS.theme);
+  });
+
+  it('names a theme the catalogue actually holds', () => {
+    expect(BUILT_IN_THEMES.map((theme) => theme.id)).toContain(DEFAULT_APPEARANCE_SETTINGS.theme);
+  });
+});

package/src/theme/__tests__/color-vision.test.ts

@@ -0,0 +1,82 @@
+/**
+ * SCREEN-2002 TC-04 — the daltonized built-ins are guarded, not asserted.
+ *
+ * The claim "a colour-blind user can tell these apart" is measurable, so it is measured: every pair
+ * of status colours and the diff pair are simulated for protanopia and deuteranopia and required to
+ * stay apart in Lab. The guard's own failure modes are exercised too — a red/green pair must FAIL it,
+ * and a value it cannot simulate must FAIL rather than skip, because a guard that quietly passes what
+ * it did not check is worse than none.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { DARK_DALTONIZED_THEME, DARK_THEME, LIGHT_DALTONIZED_THEME } from '../built-in-themes.js';
+import { simulate, simulatedDistance, type TColorVision } from '../color-vision.js';
+
+import type { ITuiTheme } from '../theme-contracts.js';
+
+/**
+ * The floor, in CIE76 units, measured rather than assumed: the shipped daltonized pairs sit at 56–88
+ * under both simulations, and the green/red pair the default theme uses for the same distinction
+ * measures 41.7 under protanopia. 50 therefore separates the two with margin on each side. It is an
+ * empirical floor for THIS projection, not a published perceptual constant, and is recorded as such.
+ */
+const MIN_DISTANCE = 50;
+
+const VISIONS: readonly TColorVision[] = ['protanopia', 'deuteranopia'];
+const DALTONIZED = [DARK_DALTONIZED_THEME, LIGHT_DALTONIZED_THEME];
+
+/**
+ * The pairs whose DIFFERENCE IN COLOUR carries meaning — "this went well" against "this did not",
+ * in the three places the product draws that distinction. Other status colours (running, waiting,
+ * cancelled, denied) are told apart by their glyph and their word, which is the rule this package
+ * has kept since SCREEN-005; requiring them to differ in colour too would be guarding a claim the
+ * product does not make.
+ */
+function meaningfulPairs(theme: ITuiTheme): [string, string, string][] {
+  return [
+    ['status.success vs status.error', theme.colors.status.success, theme.colors.status.error],
+    ['diff added vs removed', theme.markdown.diffAdded, theme.markdown.diffRemoved],
+    ['syntax addition vs deletion', theme.syntax.addition, theme.syntax.deletion],
+  ];
+}
+
+describe('daltonized built-ins survive simulated colour-vision deficiency (SCREEN-2002 TC-04)', () => {
+  it.each(
+    DALTONIZED.flatMap((theme) => VISIONS.map((vision) => [theme.id, vision, theme] as const)),
+  )('%s under %s: every meaningful pair stays apart', (_id, vision, theme) => {
+    const tooClose = meaningfulPairs(theme)
+      .map(([label, first, second]) => ({
+        label,
+        distance: simulatedDistance(first, second, vision),
+      }))
+      // A pair the guard could not simulate is a failure, not a skip — and a NON-FINITE distance is
+      // the same hole wearing a number: `NaN < MIN_DISTANCE` is false, so one bad coefficient would
+      // turn this guard green for every pair at once.
+      .filter((pair) => !Number.isFinite(pair.distance) || (pair.distance ?? 0) < MIN_DISTANCE);
+    expect(tooClose).toEqual([]);
+  });
+
+  it('discriminates: the green/red pair the default theme uses falls below the floor', () => {
+    // The default theme names its colours, and a name resolves in the terminal — so the guard cannot
+    // measure it at all, which is itself the refusal it makes. Measured as the hexes a terminal
+    // typically renders those names as, the pair falls under the floor for protanopia.
+    expect(
+      simulatedDistance(
+        DARK_THEME.colors.status.success,
+        DARK_THEME.colors.status.error,
+        'protanopia',
+      ),
+    ).toBeUndefined();
+    const asHex = simulatedDistance('#00a000', '#d00000', 'protanopia');
+    expect(asHex).toBeDefined();
+    expect(asHex ?? 0).toBeLessThan(MIN_DISTANCE);
+  });
+
+  it('refuses a value it cannot simulate rather than passing it', () => {
+    expect(simulate('cyan', 'protanopia')).toBeUndefined();
+    expect(simulate('ansi256(9)', 'protanopia')).toBeUndefined();
+    expect(simulate('#abc', 'protanopia')).toBeDefined();
+    expect(simulate('ansi256(22)', 'protanopia')).toBeDefined();
+    expect(simulate('rgb(10, 20, 30)', 'deuteranopia')).toBeDefined();
+  });
+});

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

@@ -0,0 +1,146 @@
+/**
+ * SCREEN-2002 TC-05/TC-06 — the resolved theme reaches components, and motion has one owner.
+ *
+ * The reduced-motion input is the accessibility setting this item exists for, so it is asserted
+ * against the component that consumes it rather than against the hook in isolation: `WaveText` must
+ * stop scheduling entirely, not merely look still.
+ */
+import chalk from 'chalk';
+import { Text } from 'ink';
+import { render } from 'ink-testing-library';
+import React from 'react';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { AppBanner } from '../../app-banner.js';
+import WaveText from '../../WaveText.js';
+import { DARK_THEME, LIGHT_THEME } from '../built-in-themes.js';
+// Through the BARREL, deliberately: the module's export surface is what every consumer outside
+// `src/theme/` reaches, and an export dropped from it is a runtime `undefined` rather than a type
+// error at the call site. Importing from `theme-context.js` here would leave that surface unguarded.
+import { useSyntaxHighlighting } from '../index.js';
+import { ThemeProvider } from '../theme-context.js';
+import { foreground } from '../theme-styles.js';
+
+const gateMock = vi.hoisted(() => ({ value: true }));
+vi.mock('../../terminal-capabilities.js', () => ({
+  isInteractiveColorTerminal: (): boolean => gateMock.value,
+  supportsImeCursorPositioning: (): boolean => false,
+  supportsFocusReporting: (): boolean => false,
+}));
+
+const WAVE_INTERVAL_MS = 400;
+
+afterEach(() => {
+  gateMock.value = true;
+  vi.useRealTimers();
+});
+
+describe('reduced motion (SCREEN-2002 TC-06)', () => {
+  const originalLevel = chalk.level;
+  const TRUECOLOR = 3;
+  beforeAll(() => {
+    chalk.level = TRUECOLOR;
+  });
+  afterAll(() => {
+    chalk.level = originalLevel;
+  });
+
+  it('stops the animation without stopping colour, and schedules no interval at all', () => {
+    vi.useFakeTimers();
+    const { lastFrame, unmount } = render(
+      <ThemeProvider reducedMotion>
+        <WaveText text="Waiting" />
+      </ThemeProvider>,
+    );
+    const first = lastFrame() ?? '';
+    // The whole point: no timer is armed, so nothing repaints.
+    expect(vi.getTimerCount()).toBe(0);
+    vi.advanceTimersByTime(WAVE_INTERVAL_MS * 5);
+    const later = lastFrame() ?? '';
+    unmount();
+    expect(later).toBe(first);
+    // Colour is untouched — reduced motion is orthogonal to the colour gate. The frame is the
+    // canonical MUTED token, not an uncoloured one and not a stopped ramp stop.
+    expect(first).toContain('Waiting');
+    expect(first).toContain(openCode(DARK_THEME.colors.text.muted));
+    for (const stop of DARK_THEME.motion.wave) {
+      expect(first).not.toContain(openCode(stop));
+    }
+  });
+
+  it('animates when reduced motion is off', () => {
+    vi.useFakeTimers();
+    const { unmount } = render(
+      <ThemeProvider>
+        <WaveText text="Waiting" />
+      </ThemeProvider>,
+    );
+    expect(vi.getTimerCount()).toBeGreaterThan(0);
+    unmount();
+  });
+
+  it('stays still when the colour gate is off, whatever the setting', () => {
+    gateMock.value = false;
+    vi.useFakeTimers();
+    const { unmount } = render(
+      <ThemeProvider>
+        <WaveText text="Waiting" />
+      </ThemeProvider>,
+    );
+    expect(vi.getTimerCount()).toBe(0);
+    unmount();
+  });
+});
+
+describe('a provided theme reaches components (SCREEN-2002 TC-05)', () => {
+  // These assertions are about the emitted SGR, so the level is forced for them.
+  const originalLevel = chalk.level;
+  const TRUECOLOR = 3;
+  beforeAll(() => {
+    chalk.level = TRUECOLOR;
+  });
+  afterAll(() => {
+    chalk.level = originalLevel;
+  });
+
+  it('renders the provided theme’s colours, not the default built-in’s', () => {
+    const themed = render(
+      <ThemeProvider theme={LIGHT_THEME}>
+        <AppBanner version="1.2.3" />
+      </ThemeProvider>,
+    ).lastFrame();
+    const unthemed = render(<AppBanner version="1.2.3" />).lastFrame();
+    expect(themed).not.toBe(unthemed);
+    expect(themed ?? '').toContain(openCode(LIGHT_THEME.colors.text.accent));
+  });
+});
+
+function openCode(color: string): string {
+  const [open] = foreground(color)('x').split('x');
+  return open ?? '';
+}
+
+/**
+ * SCREEN-2002: `/theme syntax off` persisted a setting that reached nothing until this travelled
+ * with the theme — the command reported success for a no-op. So the assertion is that the value
+ * ARRIVES at a consumer, not merely that the provider accepts it.
+ */
+describe('syntax highlighting travels with the theme (SCREEN-2002 TC-03)', () => {
+  function Probe(): React.ReactElement {
+    return <Text>{`syntax:${String(useSyntaxHighlighting())}`}</Text>;
+  }
+
+  it('defaults to on outside a provider, so today s rendering is unchanged', () => {
+    expect(render(<Probe />).lastFrame()).toContain('syntax:true');
+  });
+
+  it('carries false to a consumer when the appearance says off', () => {
+    const frame = render(
+      <ThemeProvider syntaxHighlighting={false}>
+        <Probe />
+      </ThemeProvider>,
+    ).lastFrame();
+
+    expect(frame).toContain('syntax:false');
+  });
+});