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

package/src/screen-reader-stdout.ts

@@ -0,0 +1,328 @@
+/**
+ * SCREEN-2670 — the pre-write park: an owned write path between Ink and the terminal.
+ *
+ * A diff-based screen reader computes what to speak from successive terminal snapshots. In
+ * screen-reader mode Ink runs UNTHROTTLED (`ink.js:193`), so commits land back to back and a reader
+ * that samples between two of them sees a torn or already-overwritten region. The park separates
+ * commits IN TIME so a snapshot can fall between them. It does not move the cursor: every frame Ink
+ * writes already begins with `eraseLines`, which ends in `cursorLeft`, so column zero is where the
+ * frame starts anyway (CLI-062 invariant I3 — no cursor sequence is written here).
+ *
+ * THE UNIT IS A COMMIT, NOT A CHUNK. One commit in the mode is up to four `write()` calls in one
+ * synchronous run (`ink.js:371-412`): synchronized-output begin, `erase + staticOutput`, the frame,
+ * synchronized-output end. Parking each would pay the interval three times and leave the erased
+ * region on screen between the erase and the frame — the torn state the park exists to prevent. So
+ * the chunks of one synchronous run form ONE batch (closed on `process.nextTick`), parked once in
+ * front and released contiguously.
+ *
+ * WHAT IS NEVER PARKED:
+ * - the first batch of a session (there is no earlier commit to separate it from);
+ * - a batch with no printable content — Ink's empty-string barrier (`ink.js:588`, `:647`), an OSC
+ *   133 mark, a bare control sequence — which still queues BEHIND anything pending so order holds;
+ * - a batch stamped with the echo flag: the composer's own key handler arms it for text-mutating
+ *   keys only, it is read when the batch OPENS and carried on it (so a keystroke queued behind a
+ *   parked reply keeps its exemption), and it expires on `setImmediate` whether or not a batch took
+ *   it, so a keystroke that commits nothing cannot un-park a later transcript batch.
+ *
+ * NOTHING IS EVER DROPPED. Ink keeps its own erase bookkeeping (`lastOutputHeight`) from the frame
+ * it believes it wrote, and writes each `<Static>` item exactly once — so a batch that never reaches
+ * the terminal corrupts the next erase and loses a transcript line for good. When a newer printable
+ * batch closes while an older one is still parked, the OLDER one is released at once, contiguously
+ * and without its park, so at most one batch ever waits and memory stays bounded on a fast stream;
+ * the park then applies to the newest commit only.
+ */
+
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+
+import type { IScreenReaderPacingPort } from './screen-reader-pacing-context.js';
+
+/** Ink's own fallbacks when the stream reports no size. */
+const DEFAULT_COLUMNS = 80;
+const DEFAULT_ROWS = 24;
+
+type TWriteCallback = (error?: Error | null) => void;
+
+/**
+ * What Ink 7.1.1 touches on the stream it is given (`ink.js`, `log-update.js`): the write, the
+ * dimensions, the TTY flag, the resize listener pair, and the writable-state probes.
+ */
+export type TParkedStdoutSource = Pick<
+  NodeJS.WriteStream,
+  | 'write'
+  | 'columns'
+  | 'rows'
+  | 'isTTY'
+  | 'destroyed'
+  | 'writable'
+  | 'writableEnded'
+  | 'writableLength'
+  | 'writableNeedDrain'
+  | 'on'
+  | 'off'
+>;
+
+export interface ICreateParkedStdoutOptions {
+  stdout: TParkedStdoutSource;
+  /** Milliseconds between the previous printable release and the next parked one. */
+  preparkMs: number;
+  /** Injected clock for tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+
+interface IChunk {
+  text: string;
+  callback: TWriteCallback | undefined;
+}
+
+interface IBatch {
+  chunks: IChunk[];
+  /** Read at formation, never at release. */
+  echo: boolean;
+  printable: boolean;
+  /** Ink's `write('', cb)` — the exit barrier, which must reach the stream in order. */
+  barrier: boolean;
+}
+
+export interface IParkedStdout {
+  /** The stream to hand Ink as `stdout`. One stable object: Ink keys its instance map by it. */
+  asInkStdout(): NodeJS.WriteStream;
+  /** The composer's key handler arms this for a text-mutating key. Expires on `setImmediate`. */
+  armEchoRelease(): void;
+  /** Write through the same ordered path — for the OSC 133 marks, which are positional. */
+  write(chunk: string | Uint8Array, callback?: TWriteCallback): boolean;
+  /**
+   * Release everything queued NOW, in order and without waiting out a park, and keep parking what
+   * comes later — for a terminal handoff, so nothing lands on top of the child's output.
+   */
+  drain(): Promise<void>;
+  /** Release everything still queued, in order and without further parking; resolves when written. */
+  flush(): Promise<void>;
+}
+
+/** The members Ink reads from `options.stdout`, narrowed as `TInkStdinSurface` narrows stdin. */
+type TInkStdoutSurface = TParkedStdoutSource;
+
+function toText(chunk: string | Uint8Array): string {
+  return typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+}
+
+/** Printable = something a reader could speak: visible text after every escape is stripped. */
+function isPrintable(text: string): boolean {
+  return sanitizeTerminalText(text).trim().length > 0;
+}
+
+class ParkedStdout implements TInkStdoutSurface {
+  private readonly source: TParkedStdoutSource;
+  private readonly preparkMs: number;
+  private readonly now: () => number;
+  private open: IBatch | undefined;
+  private readonly queue: IBatch[] = [];
+  private timer: NodeJS.Timeout | undefined;
+  private lastPrintableReleaseAt: number | undefined;
+  private echoArmed = false;
+  private echoExpiryScheduled = false;
+  private flushing = false;
+  private drainWaiters: Array<() => void> = [];
+
+  constructor(options: ICreateParkedStdoutOptions) {
+    this.source = options.stdout;
+    this.preparkMs = options.preparkMs;
+    this.now = options.now ?? Date.now;
+    this.on = ((...args: Parameters<NodeJS.WriteStream['on']>) =>
+      this.source.on(...args)) as NodeJS.WriteStream['on'];
+    this.off = ((...args: Parameters<NodeJS.WriteStream['off']>) =>
+      this.source.off(...args)) as NodeJS.WriteStream['off'];
+  }
+
+  // ── the surface Ink reads ──────────────────────────────────────────────────────────────────
+
+  get columns(): number {
+    return this.source.columns ?? DEFAULT_COLUMNS;
+  }
+
+  get rows(): number {
+    return this.source.rows ?? DEFAULT_ROWS;
+  }
+
+  get isTTY(): boolean {
+    return this.source.isTTY ?? false;
+  }
+
+  get destroyed(): boolean {
+    return this.source.destroyed ?? false;
+  }
+
+  get writable(): boolean {
+    return this.source.writable ?? true;
+  }
+
+  get writableEnded(): boolean {
+    return this.source.writableEnded ?? false;
+  }
+
+  get writableLength(): number {
+    return this.source.writableLength ?? 0;
+  }
+
+  get writableNeedDrain(): boolean {
+    return this.source.writableNeedDrain ?? false;
+  }
+
+  // Ink registers and removes its `resize` listener through these and discards the return value.
+  readonly on: NodeJS.WriteStream['on'];
+  readonly off: NodeJS.WriteStream['off'];
+
+  /**
+   * The write is deferred, so the boolean is the source's CURRENT backpressure state — what the
+   * same call would have returned a moment ago. Ink does not read it; a caller that does is told
+   * the truth about the stream it is ultimately writing to.
+   */
+  write(
+    chunk: string | Uint8Array,
+    encodingOrCallback?: BufferEncoding | TWriteCallback,
+    maybeCallback?: TWriteCallback,
+  ): boolean {
+    const callback = typeof encodingOrCallback === 'function' ? encodingOrCallback : maybeCallback;
+    const text = toText(chunk);
+    let batch = this.open;
+    if (batch === undefined) {
+      const opened: IBatch = {
+        chunks: [],
+        echo: this.echoArmed,
+        printable: false,
+        barrier: false,
+      };
+      batch = opened;
+      this.open = opened;
+      // One synchronous run = one batch. nextTick drains before the check phase, so a batch opened
+      // in the turn that armed the echo flag always closes before the flag's setImmediate expiry.
+      process.nextTick(() => this.close(opened));
+    }
+    batch.chunks.push({ text, callback });
+    if (text.length === 0) batch.barrier = true;
+    else if (!batch.printable && isPrintable(text)) batch.printable = true;
+    return !this.writableNeedDrain;
+  }
+
+  // ── the owned-writer surface ──────────────────────────────────────────────────────────────
+
+  asInkStdout(): NodeJS.WriteStream {
+    const surface: TInkStdoutSurface = this;
+    return surface as NodeJS.WriteStream;
+  }
+
+  armEchoRelease(): void {
+    this.echoArmed = true;
+    if (this.echoExpiryScheduled) return;
+    this.echoExpiryScheduled = true;
+    setImmediate(() => {
+      this.echoArmed = false;
+      this.echoExpiryScheduled = false;
+    });
+  }
+
+  drain(): Promise<void> {
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    for (const waiting of this.queue.splice(0)) this.release(waiting);
+    return this.settled();
+  }
+
+  flush(): Promise<void> {
+    this.flushing = true;
+    return this.drain();
+  }
+
+  /** Resolves once no batch is open or queued. */
+  private settled(): Promise<void> {
+    if (this.open === undefined && this.queue.length === 0) return Promise.resolve();
+    return new Promise<void>((resolve) => {
+      this.drainWaiters.push(resolve);
+    });
+  }
+
+  // ── batching and release ──────────────────────────────────────────────────────────────────
+
+  private close(batch: IBatch): void {
+    if (this.open !== batch) return;
+    this.open = undefined;
+    // A newer printable commit closing behind a parked one: release the older one NOW rather than
+    // drop it — Ink's erase bookkeeping and its once-only Static writes both assume it landed.
+    if (this.isParked(batch)) {
+      if (this.timer !== undefined) {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+      }
+      for (const waiting of this.queue.splice(0)) this.release(waiting);
+    }
+    this.queue.push(batch);
+    this.pump();
+  }
+
+  /** The first printable release of a session is never parked: nothing precedes it to separate. */
+  private isParked(batch: IBatch): boolean {
+    return (
+      this.preparkMs > 0 &&
+      this.lastPrintableReleaseAt !== undefined &&
+      batch.printable &&
+      !batch.echo &&
+      !this.flushing
+    );
+  }
+
+  private pump(): void {
+    // Always recompute from the head: a superseded head leaves a stale timer behind, and the batch
+    // now at the head may be a control-only one that must not wait on it.
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+    while (this.queue.length > 0) {
+      const head = this.queue[0] as IBatch;
+      if (this.isParked(head)) {
+        const due = (this.lastPrintableReleaseAt ?? 0) + this.preparkMs;
+        const wait = due - this.now();
+        if (wait > 0) {
+          // Kept referenced: this timer guards queued output and Ink's exit barrier, whose callback
+          // resolves `waitUntilExit()`; the process must not exit with a frame still parked.
+          this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.pump();
+          }, wait);
+          return;
+        }
+      }
+      this.queue.shift();
+      this.release(head);
+    }
+    if (this.open === undefined) {
+      const waiters = this.drainWaiters;
+      this.drainWaiters = [];
+      for (const resolve of waiters) resolve();
+    }
+  }
+
+  private release(batch: IBatch): void {
+    for (const chunk of batch.chunks) {
+      this.source.write(chunk.text, chunk.callback);
+    }
+    if (batch.printable) this.lastPrintableReleaseAt = this.now();
+  }
+}
+
+/** Build the owned write path. Constructed only when the mode is on and `preparkMs > 0`. */
+export function createParkedStdout(options: ICreateParkedStdoutOptions): IParkedStdout {
+  return new ParkedStdout(options);
+}
+
+/** The port the render tree publishes: arming and the positional write, bound to one proxy. */
+export function toPacingPort(parked: IParkedStdout): IScreenReaderPacingPort {
+  return {
+    armEchoRelease: () => parked.armEchoRelease(),
+    write: (text) => {
+      parked.write(text);
+    },
+  };
+}

package/src/shutdown-signal.ts

@@ -0,0 +1,34 @@
+/**
+ * Interrupt-signal policy for the interactive TUI (CLI-075 / RUNTIME-33).
+ *
+ * The first Ctrl+C or termination signal runs the graceful shutdown (persist session, cancel
+ * background work, drain queues). A second interrupt arriving while a shutdown is already in flight
+ * is a force-quit: the user is telling us the graceful path is wedged, so we exit immediately rather
+ * than no-op. Exit code 130 = 128 + SIGINT(2), the conventional "terminated by Ctrl+C" code.
+ */
+
+/** Conventional "terminated by SIGINT" exit code (128 + 2). */
+export const FORCE_QUIT_EXIT_CODE = 130;
+
+export interface IHandleInterruptParams {
+  /** Whether a graceful shutdown is already in progress. */
+  isShuttingDown: boolean;
+  /** Runs the graceful shutdown (only on the first interrupt). */
+  graceful: () => void;
+  /** Force-quits the process (defaults to `process.exit`); injectable for tests. */
+  forceExit?: (code: number) => void;
+}
+
+/**
+ * Route an interrupt (Ctrl+C / SIGINT / SIGTERM) to either the graceful path or a force-quit.
+ * Keeping this pure and side-effect-injectable makes the second-signal contract unit-testable
+ * without spawning a process.
+ */
+export function handleInterrupt(params: IHandleInterruptParams): void {
+  const forceExit = params.forceExit ?? ((code: number): void => process.exit(code));
+  if (params.isShuttingDown) {
+    forceExit(FORCE_QUIT_EXIT_CODE);
+    return;
+  }
+  params.graceful();
+}

package/src/status-activity.ts

@@ -0,0 +1,70 @@
+/**
+ * SCREEN-2002: this module is pure, so it names a colour TOKEN, not a colour. `StatusBar` resolves
+ * the token against the live theme — a pure function that returned a chalk name could not follow one.
+ */
+export type TStatusActivityKind = 'tools' | 'thinking' | 'background' | 'queued' | 'idle';
+
+export interface IStatusActivityInput {
+  isThinking: boolean;
+  activeToolCount: number;
+  activeBackgroundTaskCount: number;
+  hasPendingPrompt: boolean;
+}
+
+/** The `IThemeColors['text']` key a status activity is rendered in. */
+export type TStatusActivityTone = 'accent' | 'warning' | 'muted';
+
+export interface IStatusActivity {
+  kind: TStatusActivityKind;
+  label: string;
+  tone: TStatusActivityTone;
+  segments: string[];
+  text: string;
+}
+
+const NO_ACTIVE_ITEMS = 0;
+
+export function formatStatusActivity(input: IStatusActivityInput): IStatusActivity {
+  const base = getPrimaryActivity(input);
+  const segments = input.hasPendingPrompt && base.kind !== 'queued' ? ['queued'] : [];
+  const text = [base.label, ...segments].join(' · ');
+  return { ...base, segments, text };
+}
+
+function getPrimaryActivity(
+  input: IStatusActivityInput,
+): Omit<IStatusActivity, 'segments' | 'text'> {
+  if (input.activeToolCount > NO_ACTIVE_ITEMS) {
+    return {
+      kind: 'tools',
+      label: `Tools (${input.activeToolCount})`,
+      tone: 'accent',
+    };
+  }
+  if (input.isThinking) {
+    return {
+      kind: 'thinking',
+      label: 'Thinking',
+      tone: 'warning',
+    };
+  }
+  if (input.activeBackgroundTaskCount > NO_ACTIVE_ITEMS) {
+    return {
+      kind: 'background',
+      label: `Background (${input.activeBackgroundTaskCount})`,
+      tone: 'accent',
+    };
+  }
+  if (input.hasPendingPrompt) {
+    return {
+      kind: 'queued',
+      label: 'Queued',
+      tone: 'warning',
+    };
+  }
+  return {
+    kind: 'idle',
+    label: 'Idle',
+    tone: 'muted',
+  };
+}

package/src/status-glyph.ts

@@ -0,0 +1,78 @@
+/**
+ * Single source of truth for status symbol + color across the TUI.
+ *
+ * Before SCREEN-005 the same conceptual status (e.g. "running") was rendered
+ * three different ways — icons (⟳/✓/✗) in the streaming indicator, markers
+ * (□/■) in the background-task panel, and color-only in the workspace detail
+ * pane. This module gives every component one semantic status vocabulary and
+ * one glyph map, so a "running" task looks the same everywhere and every status
+ * pairs a SYMBOL with a color (never color alone — required for no-color
+ * terminals and colorblind users).
+ */
+
+import type { IThemeColors } from './theme/index.js';
+import type {
+  TExecutionAttention,
+  TExecutionWorkspaceStatus,
+} from '@robota-sdk/agent-interface-execution';
+import type { IToolState } from '@robota-sdk/agent-interface-session';
+
+export type TUiStatusKind =
+  'running' | 'success' | 'error' | 'denied' | 'waiting' | 'cancelled' | 'idle';
+
+/**
+ * Canonical status → SYMBOL map. Used by every status-rendering component.
+ *
+ * SCREEN-2002 split the colour out: a symbol is the same in every theme, a colour is not, and a
+ * module-level constant cannot follow a theme resolved at render time. The symbol stays here (this
+ * module remains the SSOT for status kinds and their glyphs); the colour comes from the live theme
+ * through {@link statusGlyphColor}, which every call site reaches with `usePalette()`, so the pairing
+ * survives — no caller gets one without the other.
+ */
+export const STATUS_SYMBOL: Record<TUiStatusKind, string> = {
+  running: '⟳',
+  success: '✓',
+  error: '✗',
+  denied: '⊘',
+  waiting: '◴',
+  cancelled: '⊗',
+  idle: '·',
+};
+
+/** The live theme's colour for a status kind. Always rendered beside {@link STATUS_SYMBOL}. */
+export function statusGlyphColor(colors: IThemeColors, kind: TUiStatusKind): string {
+  return colors.status[kind];
+}
+
+/** Map a tool-execution state to a semantic status kind. */
+export function toolStateStatusKind(tool: IToolState): TUiStatusKind {
+  if (tool.isRunning) return 'running';
+  if (tool.result === 'error') return 'error';
+  if (tool.result === 'denied') return 'denied';
+  return 'success';
+}
+
+const ACTIVE_WORKSPACE_STATUSES: readonly TExecutionWorkspaceStatus[] = [
+  'active',
+  'queued',
+  'running',
+  'sleeping',
+];
+
+/**
+ * Map an execution-workspace entry's status (+ optional attention) to a semantic
+ * status kind. `attention` takes precedence so an entry flagged failed/permission
+ * classifies correctly even when its raw status hasn't caught up — this mirrors the
+ * precedence the workspace color logic uses, so colour + glyph come from one rule.
+ */
+export function workspaceStatusKind(
+  status: TExecutionWorkspaceStatus,
+  attention?: TExecutionAttention,
+): TUiStatusKind {
+  if (attention === 'failed' || status === 'failed') return 'error';
+  if (attention === 'permission' || status === 'waiting_permission') return 'waiting';
+  if (status === 'completed') return 'success';
+  if (status === 'cancelled') return 'cancelled';
+  if (ACTIVE_WORKSPACE_STATUSES.includes(status)) return 'running';
+  return 'idle';
+}

package/src/terminal-capabilities-context.tsx

@@ -0,0 +1,27 @@
+import React, { createContext, useContext } from 'react';
+
+/** Host-selected overrides; absent values leave terminal detection in charge. */
+export interface ITerminalCapabilityOverrides {
+  readonly imeCursorPositioning?: boolean | undefined;
+  readonly turnMarks?: boolean | undefined;
+}
+
+const TerminalCapabilitiesContext = createContext<ITerminalCapabilityOverrides>({});
+
+export function TerminalCapabilitiesProvider({
+  overrides,
+  children,
+}: {
+  overrides: ITerminalCapabilityOverrides | undefined;
+  children: React.ReactNode;
+}): React.ReactElement {
+  return (
+    <TerminalCapabilitiesContext.Provider value={overrides ?? {}}>
+      {children}
+    </TerminalCapabilitiesContext.Provider>
+  );
+}
+
+export function useTerminalCapabilityOverrides(): ITerminalCapabilityOverrides {
+  return useContext(TerminalCapabilitiesContext);
+}

package/src/terminal-capabilities.ts

@@ -0,0 +1,77 @@
+/**
+ * Single source of truth for "should this process emit color + motion to the
+ * terminal?" — used by both the markdown renderer (color) and WaveText (motion),
+ * so the two never disagree (SCREEN-008).
+ *
+ * Precedence:
+ *  - `NO_COLOR` present (any value, including empty) → off (per the NO_COLOR convention).
+ *  - `FORCE_COLOR=0` → off; `FORCE_COLOR=<non-empty, non-0>` → on.
+ *  - otherwise → on only when stdout is an interactive TTY.
+ */
+export function isInteractiveColorTerminal(): boolean {
+  if ('NO_COLOR' in process.env) return false;
+  const force = process.env.FORCE_COLOR;
+  if (force === '0') return false;
+  if (force !== undefined && force !== '') return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+/**
+ * CLI-062 — may this process position the REAL terminal cursor for IME composition?
+ *
+ * Precedence:
+ *  - Host override true → on (explicit opt-in for Terminal.app); false → off.
+ *  - `TERM_PROGRAM=Apple_Terminal` → off by default (invariant I5): the historical Korean-IME
+ *    SIGSEGV is an Apple-side `attributedSubstringFromRange:` bug; its trigger geometry is gone
+ *    (measured y + post-<Static> tiny frame), but Terminal.app stays opt-in until the manual
+ *    matrix passes on real hardware. The CLI-052 startup warning remains in place.
+ *  - otherwise → on only when stdout is an interactive TTY (ink writes no cursor sequences at
+ *    all on a non-TTY, so this is defense in depth).
+ */
+export function supportsImeCursorPositioning(
+  options: { override?: boolean | undefined } = {},
+): boolean {
+  if (options.override === true) return true;
+  if (options.override === false) return false;
+  if (process.env.TERM_PROGRAM === 'Apple_Terminal') return false; // I5
+  return Boolean(process.stdout.isTTY);
+}
+
+/**
+ * CLI-2004 — may this process write OSC 133 shell-integration marks at agent-turn boundaries?
+ *
+ * The marks are otherwise harmless: every emulator surveyed discards an unknown OSC sequence, so
+ * this gate carries DOCUMENTED negatives, not a capability probe. Robota's support table (the TUI
+ * package's docs/SPEC.md) is the user-facing half of the same list.
+ *
+ * Precedence:
+ *  - Host override true → on (opt back in on a terminal listed below); false → off.
+ *  - `TERM_PROGRAM=WezTerm` → off: WezTerm treats OSC 133 as shell-owned and a non-shell emitter
+ *    corrupts its own prompt tracking, so the marks are withheld rather than emitted uselessly.
+ *  - otherwise → on only when stdout is an interactive TTY. Nothing consumes the marks in a pipe,
+ *    and they would land in a captured transcript as noise.
+ */
+export function supportsTurnMarks(options: { override?: boolean | undefined } = {}): boolean {
+  if (options.override === true) return true;
+  if (options.override === false) return false;
+  if (process.env.TERM_PROGRAM === 'WezTerm') return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+/**
+ * SCREEN-1992 — may this process ask the terminal to report focus changes (DECSET 1004)?
+ *
+ * The mode is harmless where unimplemented (the request is discarded and no `CSI I`/`CSI O` ever
+ * arrives), so the gate is the interactive-TTY check plus an override the product shell injects from
+ * its own environment — this package reads no product-named literal for it.
+ *
+ * Precedence:
+ *  - `override === true` → on; `override === false` → off (kill switch).
+ *  - otherwise → on only when BOTH stdin and stdout are interactive TTYs: the sequences arrive on
+ *    stdin, and nothing sends them in a pipe.
+ */
+export function supportsFocusReporting(options: { override?: boolean | undefined } = {}): boolean {
+  if (options.override === true) return true;
+  if (options.override === false) return false;
+  return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+}

package/src/terminal-focus-reporting.ts

@@ -0,0 +1,50 @@
+/**
+ * SCREEN-1992 — DECSET/DECRST 1004: ask the terminal to report focus changes (`CSI I` / `CSI O`).
+ *
+ * Written OUTSIDE Ink, following the `terminal-marks.ts` carve-out: the two sequences are constants,
+ * so nothing needs sanitizing, and no component may emit an escape sequence. A terminal that does not
+ * implement the mode discards the request; `supportsFocusReporting()` (terminal-capabilities.ts)
+ * carries the gate, and `negotiated` is what the stdin filter and the attention tracker consult.
+ */
+const FOCUS_REPORTING_ENABLE = '\x1b[?1004h';
+const FOCUS_REPORTING_DISABLE = '\x1b[?1004l';
+
+export interface IFocusReportingWriterOptions {
+  /** The capability gate, read at enable time. */
+  supported: () => boolean;
+  /** Injected sink; defaults to the process's own stdout. */
+  write?: (text: string) => void;
+}
+
+export interface IFocusReportingWriter {
+  /** True between a successful `enable()` and the next `disable()`. */
+  readonly negotiated: boolean;
+  enable(): void;
+  disable(): void;
+}
+
+export function createFocusReportingWriter(
+  options: IFocusReportingWriterOptions,
+): IFocusReportingWriter {
+  const write =
+    options.write ??
+    ((text: string): void => {
+      process.stdout.write(text);
+    });
+  let negotiated = false;
+  return {
+    get negotiated(): boolean {
+      return negotiated;
+    },
+    enable(): void {
+      if (negotiated || !options.supported()) return;
+      negotiated = true;
+      write(FOCUS_REPORTING_ENABLE);
+    },
+    disable(): void {
+      if (!negotiated) return;
+      negotiated = false;
+      write(FOCUS_REPORTING_DISABLE);
+    },
+  };
+}