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

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,129 @@
+/**
+ * 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 { 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 };
+  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,
+    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,56 @@
+export { renderApp } from './render.js';
+export { renderSupervisedSessionView } from './SupervisedSessionView.js';
+export type { ISupervisedViewRow, ISupervisedSessionViewProps } from './SupervisedSessionView.js';
+export { TuiInteractionChannel } from './TuiInteractionChannel.js';
+export type { ITuiInteractionChannelOptions } from './TuiInteractionChannel.js';
+export type { 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>;
+}

package/src/keybindings/__tests__/keybinding-registry.test.ts

@@ -0,0 +1,228 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'vitest';
+
+import { KEYBINDING_ACTIONS } from '../keybinding-catalogue.js';
+import {
+  createEmptyChordState,
+  DEFAULT_KEYBINDINGS,
+  keybindingHints,
+  parseKeybindingsDocument,
+  resolveKeybindingInput,
+} from '../keybinding-registry.js';
+
+const SOURCE = '/tmp/robota-keybindings.json';
+
+function parse(document: unknown) {
+  return parseKeybindingsDocument(JSON.stringify(document), SOURCE);
+}
+
+describe('contextual keybinding registry', () => {
+  it('normalizes aliases and uppercase, reuses bindings by context, and applies null unbinding', () => {
+    const result = parse({
+      version: 1,
+      bindings: {
+        'chat-input': { submit: 'control+j', 'history-previous': null },
+        'autocomplete-menu': { accept: 'ctrl+j' },
+        'workspace-switcher': { attach: 'A' },
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.snapshot.bindings['chat-input'].submit).toEqual(['ctrl+j']);
+    expect(result.snapshot.bindings['chat-input']['history-previous']).toEqual([]);
+    expect(result.snapshot.bindings['autocomplete-menu'].accept).toEqual(['ctrl+j']);
+    expect(result.snapshot.bindings['workspace-switcher'].attach).toEqual(['shift+a']);
+    expect(result.snapshot.bindings['chat-input']['cursor-left']).toEqual(
+      DEFAULT_KEYBINDINGS['chat-input']['cursor-left'],
+    );
+    expect(Object.isFrozen(result.snapshot)).toBe(true);
+  });
+
+  it.each([
+    [{ version: 1, bindings: { missing: { submit: 'enter' } } }, '$.bindings.missing'],
+    [
+      { version: 1, bindings: { 'chat-input': { missing: 'enter' } } },
+      '$.bindings.chat-input.missing',
+    ],
+    [
+      { version: 1, bindings: { 'chat-input': { submit: 'ctrl+c' } } },
+      '$.bindings.chat-input.submit',
+    ],
+    // SCREEN-1993: Ctrl+C stays reserved in the search overlay too.
+    [
+      { version: 1, bindings: { 'history-search': { execute: 'ctrl+c' } } },
+      '$.bindings.history-search.execute',
+    ],
+    [
+      {
+        version: 1,
+        bindings: { 'chat-input': { submit: 'ctrl+j', 'history-previous': 'control+j' } },
+      },
+      '$.bindings.chat-input.history-previous',
+    ],
+    [
+      {
+        version: 1,
+        bindings: { 'chat-input': { submit: 'ctrl+m', 'history-previous': 'enter' } },
+      },
+      '$.bindings.chat-input.history-previous',
+    ],
+    [
+      {
+        version: 1,
+        bindings: { 'chat-input': { submit: 'ctrl+x', 'history-previous': 'ctrl+x ctrl+p' } },
+      },
+      '$.bindings.chat-input.history-previous',
+    ],
+    [{ version: 1, bindings: { 'chat-input': { submit: 'g g' } } }, '$.bindings.chat-input.submit'],
+  ])('rejects an invalid replacement atomically with an exact path', (document, path) => {
+    const result = parse(document);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.diagnostic.path).toBe(path);
+    expect(result.diagnostic.file).toBe(SOURCE);
+  });
+
+  it('keeps multiplexer and undeliverable modifier conflicts as warnings', () => {
+    const result = parse({
+      version: 1,
+      bindings: {
+        app: { 'open-workspace-switcher': 'ctrl+b' },
+        'workspace-switcher': { attach: 'ctrl+shift+a' },
+      },
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.snapshot.warnings.map((warning) => warning.code)).toEqual([
+      'multiplexer-conflict',
+      'modifier-delivery',
+    ]);
+  });
+
+  it('resolves bounded chords and re-evaluates one mismatching stroke', () => {
+    const parsed = parse({
+      version: 1,
+      bindings: {
+        'workspace-switcher': { attach: 'g g', close: 'escape' },
+      },
+    });
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+
+    const first = resolveKeybindingInput({
+      snapshot: parsed.snapshot,
+      state: createEmptyChordState(),
+      context: 'workspace-switcher',
+      input: 'g',
+      key: {},
+      now: 100,
+    });
+    expect(first).toMatchObject({ actions: [], consumed: true });
+
+    const mismatch = resolveKeybindingInput({
+      snapshot: parsed.snapshot,
+      state: first.state,
+      context: 'workspace-switcher',
+      input: '',
+      key: { escape: true },
+      now: 200,
+    });
+    expect(mismatch.actions).toEqual(['close']);
+    expect(mismatch.state.strokes).toEqual([]);
+  });
+
+  it('resolves terminal control-code aliases without changing the configured label', () => {
+    const parsed = parse({
+      version: 1,
+      bindings: { 'chat-input': { submit: 'ctrl+m' } },
+    });
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+
+    const result = resolveKeybindingInput({
+      snapshot: parsed.snapshot,
+      state: createEmptyChordState(),
+      context: 'chat-input',
+      input: '',
+      key: { return: true },
+      now: 0,
+    });
+
+    expect(result).toMatchObject({ actions: ['submit'], consumed: true });
+    expect(keybindingHints(parsed.snapshot, 'chat-input', [['submit', 'Submit']])).toEqual([
+      { keys: 'Ctrl+M', label: 'Submit' },
+    ]);
+  });
+
+  it('resets pending chords on timeout, context change, and snapshot replacement', () => {
+    const parsed = parse({
+      version: 1,
+      bindings: { 'workspace-switcher': { attach: 'g g' } },
+    });
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    const pending = resolveKeybindingInput({
+      snapshot: parsed.snapshot,
+      state: createEmptyChordState(),
+      context: 'workspace-switcher',
+      input: 'g',
+      key: {},
+      now: 0,
+    }).state;
+
+    for (const input of [
+      { context: 'workspace-switcher' as const, now: 1_001, generation: 0, strokes: ['g'] },
+      { context: 'list-picker' as const, now: 100, generation: 0, strokes: [] },
+      { context: 'workspace-switcher' as const, now: 100, generation: 1, strokes: ['g'] },
+    ]) {
+      const snapshot = { ...parsed.snapshot, generation: input.generation };
+      const result = resolveKeybindingInput({
+        snapshot,
+        state: pending,
+        context: input.context,
+        input: 'g',
+        key: {},
+        now: input.now,
+      });
+      expect(result.actions).toEqual([]);
+      expect(result.state.strokes).toEqual(input.strokes);
+    }
+  });
+
+  it('derives user-facing hints only from effective active bindings', () => {
+    const parsed = parse({
+      version: 1,
+      bindings: { 'chat-input': { submit: 'ctrl+j', 'history-previous': null } },
+    });
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(
+      keybindingHints(parsed.snapshot, 'chat-input', [
+        ['history-previous', 'Previous'],
+        ['submit', 'Submit'],
+      ]),
+    ).toEqual([{ keys: 'Ctrl+J', label: 'Submit' }]);
+  });
+
+  it('keeps the published JSON Schema aligned with every runtime context and action', () => {
+    const schemaPath = new URL(
+      '../../../../../apps/docs/public/schemas/keybindings.schema.json',
+      import.meta.url,
+    );
+    const schema = JSON.parse(readFileSync(schemaPath, 'utf8')) as {
+      $id: string;
+      properties: { bindings: { properties: Record<string, { $ref: string }> } };
+      $defs: Record<string, { properties?: Record<string, unknown> }>;
+    };
+
+    expect(schema.$id).toBe('https://docs.robota.io/schemas/keybindings.schema.json');
+    expect(Object.keys(schema.properties.bindings.properties)).toEqual(
+      Object.keys(KEYBINDING_ACTIONS),
+    );
+    for (const [context, actions] of Object.entries(KEYBINDING_ACTIONS)) {
+      expect(Object.keys(schema.$defs[context]?.properties ?? {})).toEqual(actions);
+    }
+  });
+});