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

package/src/hooks/useSideEffects.ts

@@ -0,0 +1,144 @@
+/**
+ * CMD-004 Phase 2 Stage C — the TUI as a pure renderer.
+ *
+ * The session layer (the host) executes every command host action via `ICommandHostAdapters`
+ * BEFORE the command result returns (language change, settings reset, exit/restart, rename,
+ * statusline patch, remote control — see `interactive-session-host-actions.ts`). This hook only:
+ *
+ * 1. renders the four UI screens from the requester-routed `ui_intent` session event
+ *    (`show-plugin-manager` / `show-settings` / `show-session-picker` / `show-agent-switcher`) —
+ *    the surface that issued the command renders the intent; intents stamped with another
+ *    surface's driver id (or unattributed) are ignored;
+ * 2. reflects the broadcast `session_renamed` event into the rendered title (the host performed
+ *    the rename — the TUI never mutates the session);
+ * 3. refreshes the statusline display after a slash-command result arrives by RE-READING the
+ *    persisted settings (refresh-on-result — the host applied any patch via the settings adapter).
+ */
+
+import { OWNER_DRIVER_ID } from '@robota-sdk/agent-interface-session';
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+
+import type { IUseSideEffectsOptions, IUseSideEffectsResult } from './side-effects-types.js';
+import type { ITuiSessionUiEventPort } from '../tui-app-channel-port.js';
+import type { ISessionRenamedEvent, IUiIntentEvent } from '@robota-sdk/agent-interface-session';
+
+interface IUiEventHandlers {
+  setSessionName: (name: string) => void;
+  refreshStatusLineSettings: () => void;
+  /** SCREEN-2002: re-read the persisted appearance after a slash command may have patched it. */
+  refreshAppearanceSettings: () => void;
+  openAgentSwitcher?: (() => void) | undefined;
+}
+
+interface IScreenSetters {
+  setShowPluginTUI: (show: boolean) => void;
+  setShowTransportTUI: (show: boolean) => void;
+  setShowSessionPicker: (show: boolean) => void;
+  setShowThemePicker: (show: boolean) => void;
+}
+
+/** Subscribe to `ui_intent` (requester-routed) + `session_renamed` (broadcast); returns cleanup. */
+function subscribeToSessionUiEvents(
+  uiEventPort: ITuiSessionUiEventPort,
+  screens: IScreenSetters,
+  handlersRef: { current: IUiEventHandlers },
+): () => void {
+  const onUiIntent = (event: IUiIntentEvent): void => {
+    // Requester-routed: this surface is the local operator (OWNER_DRIVER_ID). Intents issued by
+    // other surfaces — or unattributed ones — are theirs to render, not ours.
+    if (event.requesterDriverId !== OWNER_DRIVER_ID) return;
+    switch (event.intent.type) {
+      case 'show-plugin-manager':
+        screens.setShowPluginTUI(true);
+        return;
+      case 'show-settings':
+        screens.setShowTransportTUI(true);
+        return;
+      case 'show-session-picker':
+        screens.setShowSessionPicker(true);
+        return;
+      case 'show-agent-switcher':
+        handlersRef.current.openAgentSwitcher?.();
+        return;
+      case 'show-theme-picker':
+        screens.setShowThemePicker(true);
+        return;
+    }
+  };
+  const onSessionRenamed = (event: ISessionRenamedEvent): void => {
+    handlersRef.current.setSessionName(event.name);
+  };
+  uiEventPort.on('ui_intent', onUiIntent);
+  uiEventPort.on('session_renamed', onSessionRenamed);
+  return () => {
+    uiEventPort.off('ui_intent', onUiIntent);
+    uiEventPort.off('session_renamed', onSessionRenamed);
+  };
+}
+
+/**
+ * Latest-callback refs so the session subscription binds exactly once per session: App recreates
+ * some callbacks every render, and re-subscribing on each identity change would churn listeners.
+ */
+function useLatestHandlers(handlers: IUiEventHandlers): { current: IUiEventHandlers } {
+  const ref = useRef(handlers);
+  ref.current = handlers;
+  return ref;
+}
+
+export function useSideEffects({
+  uiEventPort,
+  baseHandleSubmit,
+  setSessionName,
+  refreshStatusLineSettings,
+  refreshAppearanceSettings,
+  showSessionPickerOnStart,
+  openAgentSwitcher,
+}: IUseSideEffectsOptions): IUseSideEffectsResult {
+  const [showPluginTUI, setShowPluginTUI] = useState(false);
+  const [showSessionPicker, setShowSessionPicker] = useState(showSessionPickerOnStart ?? false);
+  const [showTransportTUI, setShowTransportTUI] = useState(false);
+  const [showThemePicker, setShowThemePicker] = useState(false);
+
+  const handlersRef = useLatestHandlers({
+    setSessionName,
+    refreshStatusLineSettings,
+    refreshAppearanceSettings,
+    openAgentSwitcher,
+  });
+
+  useLayoutEffect(
+    () =>
+      subscribeToSessionUiEvents(
+        uiEventPort,
+        { setShowPluginTUI, setShowTransportTUI, setShowSessionPicker, setShowThemePicker },
+        handlersRef,
+      ),
+    [uiEventPort],
+  );
+
+  const handleSubmit = useCallback(
+    async (input: string): Promise<void> => {
+      await baseHandleSubmit(input);
+      // Refresh-on-result: a slash command's result has arrived; the host may have patched the
+      // persisted statusline settings — re-read them for the status bar.
+      if (input.trimStart().startsWith('/')) {
+        handlersRef.current.refreshStatusLineSettings();
+        handlersRef.current.refreshAppearanceSettings();
+      }
+    },
+    [baseHandleSubmit],
+  );
+
+  return {
+    handleSubmit,
+    showPluginTUI,
+    showSessionPicker,
+    showTransportTUI,
+    showThemePicker,
+    setShowPluginTUI,
+    setShowSessionPicker,
+    setShowTransportTUI,
+    setShowThemePicker,
+  };
+}

package/src/hooks/useStatusLineSettings.ts

@@ -0,0 +1,50 @@
+import { DEFAULT_STATUS_LINE_COMMAND_SETTINGS } from '@robota-sdk/agent-framework';
+import { useCallback, useState } from 'react';
+
+import { useTuiCliAdapter } from '../tui-cli-adapter-context.js';
+
+import type { ITuiCliAdapter } from '../tui-cli-adapter.js';
+import type { TUniversalValue } from '@robota-sdk/agent-core';
+import type { IStatusLineCommandSettings } from '@robota-sdk/agent-interface-command';
+
+function readStatusLineSettings(
+  settings: Record<string, TUniversalValue>,
+): IStatusLineCommandSettings {
+  const defaults = { ...DEFAULT_STATUS_LINE_COMMAND_SETTINGS };
+  const raw = settings.statusline;
+  if (!isRecord(raw)) {
+    return defaults;
+  }
+  return {
+    enabled: typeof raw.enabled === 'boolean' ? raw.enabled : defaults.enabled,
+    gitBranch: typeof raw.gitBranch === 'boolean' ? raw.gitBranch : defaults.gitBranch,
+  };
+}
+
+function isRecord(value: TUniversalValue): value is Record<string, TUniversalValue> {
+  return (
+    value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)
+  );
+}
+
+function readFromAdapter(cliAdapter: ITuiCliAdapter): IStatusLineCommandSettings {
+  return readStatusLineSettings(cliAdapter.readSettings(cliAdapter.getUserSettingsPath()));
+}
+
+/**
+ * Statusline settings as persisted on disk, plus a from-disk `refresh()`.
+ *
+ * CMD-004 Phase 2 Stage C: the HOST applies `statusline-settings-patch` via the settings adapter
+ * (the TUI no longer writes settings), so the renderer refreshes by RE-READING the persisted
+ * document when a command result arrives (refresh-on-result).
+ */
+export function useStatusLineSettings(): [IStatusLineCommandSettings, () => void] {
+  const cliAdapter = useTuiCliAdapter();
+  const [settings, setSettings] = useState<IStatusLineCommandSettings>(() =>
+    readFromAdapter(cliAdapter),
+  );
+  const refresh = useCallback((): void => {
+    setSettings(readFromAdapter(cliAdapter));
+  }, [cliAdapter]);
+  return [settings, refresh];
+}

package/src/hooks/useTerminalHandoffSuspension.ts

@@ -0,0 +1,30 @@
+/**
+ * TERM-002: React glue for the terminal-handoff controller.
+ *
+ * Registers the App's suspend/resume into the controller. On suspend the App renders nothing (see
+ * App.tsx) so Ink unmounts its input hooks and releases raw mode, handing the real terminal to the
+ * child process; on resume the App re-renders.
+ */
+import { useEffect, useState } from 'react';
+
+import type { TerminalHandoffController } from '../terminal-handoff-controller.js';
+
+/** Time for React/Ink to commit the empty render (unmount input, release raw mode) before handoff. */
+const SUSPEND_COMMIT_DELAY_MS = 50;
+
+export function useTerminalHandoffSuspension(
+  controller: TerminalHandoffController | undefined,
+): boolean {
+  const [suspended, setSuspended] = useState(false);
+  useEffect(() => {
+    if (!controller) return;
+    return controller.registerSuspendHooks({
+      suspend: async () => {
+        setSuspended(true);
+        await new Promise<void>((resolve) => setTimeout(resolve, SUSPEND_COMMIT_DELAY_MS));
+      },
+      resume: () => setSuspended(false),
+    });
+  }, [controller]);
+  return suspended;
+}

package/src/hooks/useTuiChannel.ts

@@ -0,0 +1,141 @@
+/**
+ * useTuiChannel — React hook that subscribes to the bounded TUI channel port.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+
+import type {
+  ITuiAppChannelPort,
+  ITuiCommandQueryPort,
+  ITuiRuntimeStatusSnapshot,
+  ITuiSessionUiEventPort,
+} from '../tui-app-channel-port.js';
+import type { ITuiSessionEventNotice } from '../tui-session-events.js';
+import type { IPendingPermissionRequest } from '../types.js';
+import type {
+  IActionRequest,
+  IHistoryEntry,
+  TActionResponse,
+  TPermissionMode,
+  TSessionEndReason,
+} from '@robota-sdk/agent-core';
+import type {
+  IExecutionDetailPage,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type { ISessionListingEntry, IToolState } from '@robota-sdk/agent-interface-session';
+
+export interface ITuiChannelState {
+  uiEventPort: ITuiSessionUiEventPort;
+  commandQueryPort: ITuiCommandQueryPort;
+  history: readonly IHistoryEntry[];
+  addEntry: (entry: IHistoryEntry) => void;
+  streamingText: string;
+  activeTools: readonly IToolState[];
+  isThinking: boolean;
+  isAborting: boolean;
+  /** ERR-001 G2: humanized message of the last failed turn (null once the next turn starts). */
+  lastErrorMessage: string | null;
+  /** ERR-001 G3: no provider activity for a while during a turn — connection may be stalled. */
+  isStalled: boolean;
+  sessionEventNotices: readonly ITuiSessionEventNotice[];
+  isShuttingDown: boolean;
+  pendingPrompt: string | null;
+  /** REMOTE-014 E5: total queued turns across all drivers (owner + co-drivers); >1 means a co-driver is queued. */
+  pendingCount: number;
+  executionWorkspaceSnapshot: IExecutionWorkspaceSnapshot | null;
+  selectedExecutionEntryId?: string;
+  permissionRequest: IPendingPermissionRequest | null;
+  /** CMD-004: the unified action awaiting a user answer, or null. */
+  pendingUserAction: IActionRequest | null;
+  contextState: { percentage: number; usedTokens: number; maxTokens: number };
+  /** The host's sessions for the picker, when the channel's host keeps them. */
+  hostSessions: readonly ISessionListingEntry[] | undefined;
+  /** Changes when the transcript starts over for another session under this channel. */
+  transcriptGeneration: number;
+  /** This terminal only observes the session. */
+  readOnly: boolean;
+  /** This terminal is attached to a session a host runs; leaving only detaches it. */
+  attached: boolean;
+  handleSubmit: (input: string) => Promise<void>;
+  handleAbort: () => void;
+  handleCancelQueue: () => void;
+  handleStopWaitingLoop: () => Promise<void>;
+  handleShutdown: (reason?: TSessionEndReason) => Promise<void>;
+  sendAgentJob: (taskId: string, input: string) => Promise<void>;
+  resolveUserAction: (request: IActionRequest, response: TActionResponse) => void;
+  getRuntimeStatusSnapshot: (fallback: TPermissionMode) => ITuiRuntimeStatusSnapshot;
+  selectExecutionWorkspaceEntry: (entryId: string) => void;
+  readExecutionWorkspaceDetail: (entryId: string) => Promise<IExecutionDetailPage>;
+}
+
+interface IHistoryReadableSession {
+  getFullHistory(): IHistoryEntry[];
+}
+
+interface IHistorySyncManager {
+  syncHistory(entries: IHistoryEntry[]): void;
+}
+
+export function applyCompactEventToManager(
+  interactiveSession: IHistoryReadableSession,
+  manager: IHistorySyncManager,
+): void {
+  manager.syncHistory(interactiveSession.getFullHistory());
+}
+
+export function useTuiChannel(channel: ITuiAppChannelPort): ITuiChannelState {
+  const [, forceRender] = useState(0);
+
+  useEffect(() => channel.subscribe(() => forceRender((n) => n + 1)), [channel]);
+  const snapshot = channel.getSnapshot();
+
+  // SCREEN-014 fix: these are consumed in `useEffect` dependency arrays in App. `channel` is stable
+  // (created once), so memoize them — a fresh closure each render made the detail-loading effect
+  // re-run every render and `setState`-loop ("Maximum update depth exceeded") whenever a background
+  // entry was selected.
+  const selectExecutionWorkspaceEntry = useCallback(
+    (id: string) => channel.selectExecutionWorkspaceEntry(id),
+    [channel],
+  );
+  const readExecutionWorkspaceDetail = useCallback(
+    (id: string) => channel.readExecutionWorkspaceDetail(id),
+    [channel],
+  );
+
+  return {
+    uiEventPort: channel.getSessionUiEventPort(),
+    commandQueryPort: channel.getCommandQueryPort(),
+    history: snapshot.history,
+    addEntry: (entry) => channel.addEntry(entry),
+    streamingText: snapshot.streamingText,
+    activeTools: snapshot.activeTools,
+    isThinking: snapshot.isThinking,
+    isAborting: snapshot.isAborting,
+    lastErrorMessage: snapshot.lastErrorMessage,
+    isStalled: snapshot.isStalled,
+    sessionEventNotices: snapshot.sessionEventNotices,
+    isShuttingDown: snapshot.isShuttingDown,
+    pendingPrompt: snapshot.pendingPrompt,
+    pendingCount: snapshot.pendingCount,
+    executionWorkspaceSnapshot: snapshot.executionWorkspaceSnapshot,
+    selectedExecutionEntryId: snapshot.selectedExecutionEntryId,
+    permissionRequest: snapshot.permissionRequest,
+    pendingUserAction: snapshot.pendingUserAction,
+    contextState: snapshot.contextState,
+    hostSessions: snapshot.hostSessions,
+    transcriptGeneration: snapshot.transcriptGeneration ?? 0,
+    readOnly: snapshot.readOnly === true,
+    attached: snapshot.attached === true,
+    handleSubmit: (input) => channel.handleInput(input),
+    handleAbort: () => channel.abort(),
+    handleCancelQueue: () => channel.cancelQueue(),
+    handleStopWaitingLoop: () => channel.stopWaitingSelfPacedLoop(),
+    handleShutdown: (reason) => channel.shutdown({ reason }),
+    sendAgentJob: (taskId, input) => channel.sendAgentJob(taskId, input),
+    resolveUserAction: (request, response) => channel.resolveUserAction(request, response),
+    getRuntimeStatusSnapshot: (fallback) => channel.getRuntimeStatusSnapshot(fallback),
+    selectExecutionWorkspaceEntry,
+    readExecutionWorkspaceDetail,
+  };
+}

package/src/humanize-tool-name.ts

@@ -0,0 +1,51 @@
+/**
+ * SCREEN-012: turn a provider-safe projected tool id into the natural command name for display.
+ *
+ * Slash commands invoked by the model are projected to provider-safe tool ids prefixed with
+ * the host-selected prefix (or the neutral default), optionally suffixed with a `_<8 hex>` hash when
+ * the name would otherwise exceed the provider length limit (see model-command-tool-projection.ts).
+ * For display we recover the command name: strip the prefix and a trailing projection hash. Tool
+ * names that are not command projections (e.g. `Shell`, `Read`) are returned unchanged.
+ *
+ * ## SEC-019: this is where a tool label is made safe, not at each render site
+ *
+ * A tool name and its first argument come from the model, from an MCP server's manifest, or from a
+ * plugin — all untrusted — and they are put on the terminal as text. Sanitizing at the render sites
+ * was tried and failed within one review round: `MessageList` has two branches that show a tool name
+ * and only one of them got the call, so a name carrying OSC 52 still reached `<Text>` whenever the
+ * tool's content happened to parse as a structured summary. Three more sites had the same gap
+ * (`StreamingIndicator`, and the label `tool-summary-status` composes for the history view).
+ *
+ * The defect is not that a call was forgotten. It is that "make this displayable" and "make this
+ * safe to display" were two separate steps, so every new render site had to remember the second one.
+ * They are one step here, and a fifth caller is covered because it cannot obtain the display text
+ * without going through the function that sanitizes it.
+ */
+import { MODEL_COMMAND_TOOL_PREFIX } from '@robota-sdk/agent-framework';
+
+import { sanitizeTerminalText } from './sanitize-terminal-text.js';
+
+/** A trailing `_<8 lowercase hex>` projection hash appended to over-long command tool names. */
+const PROJECTION_HASH_SUFFIX = /_[0-9a-f]{8}$/;
+
+export function humanizeToolName(
+  toolName: string,
+  prefix: string = MODEL_COMMAND_TOOL_PREFIX,
+): string {
+  if (!toolName.startsWith(prefix)) return sanitizeTerminalText(toolName);
+  const body = toolName.slice(prefix.length);
+  const withoutHash = body.replace(PROJECTION_HASH_SUFFIX, '');
+  return sanitizeTerminalText(withoutHash.length > 0 ? withoutHash : toolName);
+}
+
+/**
+ * The first argument of a tool call, as display text.
+ *
+ * A separate function rather than a bare `sanitizeTerminalText` at the two sites that show it: the
+ * argument is the other half of a tool label, it is equally untrusted — a path, a shell command, a
+ * URL the model chose — and pairing it with {@link humanizeToolName} is what makes the boundary
+ * findable. A render site that reaches for one naturally reaches for the other.
+ */
+export function humanizeToolArgument(firstArg: string | undefined): string {
+  return firstArg === undefined ? '' : sanitizeTerminalText(firstArg);
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+export { renderApp, renderAttachedApp } from './render.js';
+export { renderSupervisedSessionView } from './SupervisedSessionView.js';
+export type {
+  IAttachedSessionConnection,
+  TAttachedSessionEnd,
+} from './attached-session-connection.js';
+export type {
+  ISupervisedAttachRequest,
+  ISupervisedViewRow,
+  ISupervisedSessionViewProps,
+  ISupervisedStartTrustQuestion,
+  TSupervisedStartTrustChoice,
+  TSupervisedViewExit,
+} from './SupervisedSessionView.js';
+export { TuiInteractionChannel } from './TuiInteractionChannel.js';
+export type { ITuiInteractionChannelOptions } from './TuiInteractionChannel.js';
+export type {
+  ITuiClientCommand,
+  ITuiClientCommands,
+  TTuiClientCommandHost,
+} from './wire-tui-client-commands.js';
+export type { IRenderAttachedAppOptions, IRenderOptions } from './render.js';
+export type { ITerminalCapabilityOverrides } from './terminal-capabilities-context.js';
+export type { TScreenReaderChannel } from './screen-reader-announcement.js';
+export type { IScreenReaderPacingOverrides } from './screen-reader-pacing.js';
+export type { ITuiCliAdapter } from './tui-cli-adapter.js';
+export type { IDefaultTuiCliAdapterOptions } from './create-default-tui-cli-adapter.js';
+export { createDefaultTuiCliAdapter } from './create-default-tui-cli-adapter.js';
+export { createNodeKeybindingsSource } from './keybindings/node-keybindings-source.js';
+// SCREEN-2002: the product shell assembles one registry and hands it to both `/theme` and
+// `renderApp`. The theme DATA stays unexported — a caller asks the registry, never a built-in.
+export { createThemeCataloguePort, createThemeRegistry } from './theme/theme-registry.js';
+// The product shell composes the registry, so it must be able to enumerate the built-ins, parse the
+// files that join them, and build its OWN diagnostics through the same escaping policy. The
+// accessor comes from the module that USES it rather than from the data module, which the
+// anti-drift floor forbids naming outside `src/theme/`.
+export { listBuiltInThemes } from './theme/theme-registry.js';
+export {
+  escapeThemeText,
+  parseThemeDocument,
+  quoteThemeText,
+  sanitizeThemeProse,
+} from './theme/theme-document.js';
+export type {
+  IThemeCataloguePortOptions,
+  IThemeRegistry,
+  IThemeResolution,
+  IThemeSkip,
+} from './theme/theme-registry.js';
+export type { IThemeDocumentInput, TThemeDocumentResult } from './theme/theme-document.js';
+// `createThemeRegistry` takes themes, so a caller must be able to name one.
+export type { ITuiTheme, TThemeSource } from './theme/theme-contracts.js';
+export type {
+  IKeybindingsFilePort,
+  IKeybindingsSource,
+  INodeKeybindingsSourceOptions,
+} from './keybindings/node-keybindings-source.js';
+export type {
+  IKeybindingDiagnostic,
+  IKeybindingSnapshot,
+  IKeybindingWarning,
+  TKeybindingAction,
+  TKeybindingContext,
+} from './keybindings/keybinding-registry.js';
+export type {
+  TOnMissingArgsAction,
+  ITuiPickerItem,
+  ITuiCommandInteraction,
+  ITuiPickerInteraction,
+  ITuiConfirmInteraction,
+  TAnyTuiCommandInteraction,
+} from './command-interaction.js';

package/src/input-area-rules.tsx

@@ -0,0 +1,71 @@
+/**
+ * The input area's horizontal rules, and the deletion announcement that replaces them.
+ *
+ * Extracted from `InputArea.tsx` (CLI-2004). The rules are hand-drawn `<Text>` lines rather than a
+ * Yoga-synthesized `Box` border because a synthesized border drops glyphs during rapid re-render at
+ * full terminal height (SCREEN-003) — which is exactly why they are not covered by the `borderStyle`
+ * suppression the mode applies elsewhere and need their own branch.
+ */
+
+import React from 'react';
+
+import { Text } from './SafeText.js';
+import { usePalette } from './theme/index.js';
+import { buildInputTopBorder } from './utils/input-top-border.js';
+
+/** The announcement's exact shape, so the input and its test cannot disagree about it. */
+export function formatDeletionAnnouncement(deleted: string): string {
+  return `[deleted: ${deleted}]`;
+}
+
+/** Top rule, carrying the optional right-aligned session title. Nothing in screen-reader mode. */
+export function InputTopRule({
+  screenReader,
+  innerWidth,
+  borderColor,
+  sessionName,
+}: {
+  screenReader: boolean;
+  innerWidth: number;
+  borderColor: string;
+  sessionName?: string;
+}): React.ReactElement | null {
+  const palette = usePalette();
+  if (screenReader) return null;
+  const topBorder = buildInputTopBorder(innerWidth, sessionName);
+  return (
+    <Text color={borderColor}>
+      {topBorder.left}
+      {topBorder.label ? (
+        <Text backgroundColor={borderColor} color={palette.text.onAccent} bold>
+          {topBorder.label}
+        </Text>
+      ) : null}
+      {topBorder.right}
+    </Text>
+  );
+}
+
+/** Bottom rule (mirrors the top). Nothing in screen-reader mode. */
+export function InputBottomRule({
+  screenReader,
+  innerWidth,
+  borderColor,
+}: {
+  screenReader: boolean;
+  innerWidth: number;
+  borderColor: string;
+}): React.ReactElement | null {
+  if (screenReader) return null;
+  return <Text color={borderColor}>{'─'.repeat(innerWidth)}</Text>;
+}
+
+/** `[deleted: <text>]`, rendered once for the most recent word/line delete. */
+export function DeletionAnnouncement({
+  deleted,
+}: {
+  deleted: string | null;
+}): React.ReactElement | null {
+  if (deleted === null) return null;
+  return <Text>{formatDeletionAnnouncement(deleted)}</Text>;
+}

package/src/json-value.ts

@@ -0,0 +1,18 @@
+/**
+ * The shape of a parsed JSON document, and the one guard that narrows it.
+ *
+ * Two user-owned files are read as JSON in this package — the keybindings document and, since
+ * SCREEN-2002, a theme document — and both walk an arbitrary tree looking for the keys they know.
+ * A second copy of this type would be a second answer to "what can a parsed file hold", which is
+ * how two readers of the same kind of file start disagreeing about what a null or an array means.
+ */
+export type TJsonValue = string | number | boolean | null | TJsonValue[] | IJsonRecord;
+
+export interface IJsonRecord {
+  [key: string]: TJsonValue;
+}
+
+/** An object, not an array and not `null` — the distinction `typeof` alone does not make. */
+export function isJsonRecord(value: TJsonValue): value is IJsonRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/key-hint-footer.tsx

@@ -0,0 +1,54 @@
+/**
+ * Key-hint footer SSOT (SCREEN-005).
+ *
+ * Single source of truth for prompt-footer key hints and the selection-row indicator across the
+ * package's Ink prompt/selection components. Every footer call site declares its hints as
+ * `IKeyHint[]` and renders them through `formatKeyHints` / `KeyHintFooter`, so exactly one grammar
+ * exists (no per-component footer dialects) and a drift cannot re-appear silently — the
+ * `key-hint-consistency` test asserts every declared hint set round-trips through this module.
+ *
+ * This module ships MECHANICS only: the separator, the pair grammar, the indicator constants.
+ * Verb vocabulary (Navigate/Select/Confirm/…) is supplied by callers — the package stays a
+ * content-neutral library ingredient. No config surface: per-call-site suppression is passing an
+ * empty hint list.
+ *
+ * Affordance contract (see docs/SPEC.md "Interaction affordance contract"): the footer lists
+ * exactly the keys that do something — a prompt that suppresses Esc in its flow omits Esc here.
+ */
+
+import React from 'react';
+
+import { Text } from './SafeText.js';
+
+/** One key hint: the key(s) and the verb label, e.g. `{ keys: '↑↓', label: 'Navigate' }`. */
+export interface IKeyHint {
+  keys: string;
+  label: string;
+}
+
+/** Separator between key-hint pairs. Changing the footer separator is a one-constant edit. */
+export const KEY_HINT_SEPARATOR = ' · ';
+
+/** Selection cursor rendered in front of the focused row. */
+export const SELECTION_INDICATOR = '> ';
+
+/** Same-width blank rendered in front of non-focused rows so columns stay aligned. */
+export const SELECTION_INDICATOR_NONE = '  ';
+
+/** Pure formatter: joins `keys label` pairs with {@link KEY_HINT_SEPARATOR}. Empty list → ''. */
+export function formatKeyHints(hints: readonly IKeyHint[]): string {
+  return hints.map((hint) => `${hint.keys} ${hint.label}`).join(KEY_HINT_SEPARATOR);
+}
+
+/**
+ * Dim one-line footer: leading pad + formatted hints. Renders nothing for an empty hint list
+ * (per-call-site suppression without a config surface).
+ */
+export function KeyHintFooter({
+  hints,
+}: {
+  hints: readonly IKeyHint[];
+}): React.ReactElement | null {
+  if (hints.length === 0) return null;
+  return <Text dimColor> {formatKeyHints(hints)}</Text>;
+}