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

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/agent-test-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);
+    }
+  });
+});

package/src/keybindings/__tests__/node-keybindings-source.test.ts

@@ -0,0 +1,118 @@
+import { mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  createNodeKeybindingsSource,
+} from '../node-keybindings-source.js';
+
+const roots: string[] = [];
+
+async function temporaryRoot(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'agent-test-keybindings-'));
+  roots.push(root);
+  return root;
+}
+
+async function eventually(assertion: () => void, timeout = 2_000): Promise<void> {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    try {
+      assertion();
+      return;
+    } catch {
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+  }
+  assertion();
+}
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe('Node keybindings source', () => {
+  it('omits the schema when the host has no documentation URL', async () => {
+    const root = await temporaryRoot();
+    const source = createNodeKeybindingsSource({ filePath: join(root, 'keys.json') });
+    expect(JSON.parse(await readFile(await source.ensureFile(), 'utf8'))).toEqual({ version: 1, bindings: {} });
+    source.dispose();
+  });
+
+  it('uses only the host-selected file and schema when creating the sparse document', async () => {
+    const root = await temporaryRoot();
+    const filePath = join(root, 'host-config', 'keys.json');
+    const schemaUrl = 'https://example.invalid/schemas/keys.json';
+    const source = createNodeKeybindingsSource({ filePath, schemaUrl });
+    const firstPath = await source.ensureFile();
+    expect(firstPath).toBe(filePath);
+    expect(JSON.parse(await readFile(firstPath, 'utf8'))).toEqual({
+      $schema: schemaUrl,
+      version: 1,
+      bindings: {},
+    });
+
+    await writeFile(firstPath, '{"owned":true}\n', 'utf8');
+    expect(await source.ensureFile()).toBe(firstPath);
+    expect(await readFile(firstPath, 'utf8')).toBe('{"owned":true}\n');
+    source.dispose();
+  });
+
+  it('loads atomic replacements, retains last-valid bindings on invalid input, and disposes', async () => {
+    const root = await temporaryRoot();
+    const path = join(root, 'custom', 'keybindings.json');
+    const log = vi.fn();
+    const source = createNodeKeybindingsSource({
+      filePath: path,
+      schemaUrl: 'https://example.invalid/keys.json',
+      onDiagnostic: log,
+    });
+    await source.start();
+    expect(await source.ensureFile()).toBe(path);
+    const snapshots = [source.getSnapshot()];
+    const unsubscribe = source.subscribe((snapshot) => snapshots.push(snapshot));
+
+    const replacement = join(root, 'custom', 'keybindings.next.json');
+    await writeFile(
+      replacement,
+      JSON.stringify({ version: 1, bindings: { 'chat-input': { submit: 'ctrl+k' } } }),
+      'utf8',
+    );
+    await rename(replacement, path);
+    await eventually(() => {
+      expect(source.getSnapshot().bindings['chat-input'].submit).toEqual(['ctrl+k']);
+    });
+    const valid = source.getSnapshot();
+
+    await writeFile(replacement, '{"version":1,"bindings":{"missing":{}}}', 'utf8');
+    await rename(replacement, path);
+    await eventually(() => {
+      expect(source.getSnapshot().diagnostic?.path).toBe('$.bindings.missing');
+    });
+    expect(source.getSnapshot().bindings).toBe(valid.bindings);
+    expect(source.getSnapshot().generation).toBeGreaterThan(valid.generation);
+    expect(log).toHaveBeenCalledWith(expect.objectContaining({ file: path }));
+
+    unsubscribe();
+    source.dispose();
+    const count = snapshots.length;
+    await writeFile(path, JSON.stringify({ version: 1, bindings: {} }), 'utf8');
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    expect(snapshots).toHaveLength(count);
+  });
+
+  it('shares one start, and a failed start leaves no half-started source', async () => {
+    const root = await temporaryRoot();
+    const source = createNodeKeybindingsSource({
+      filePath: join(root, 'custom', 'keybindings.json'),
+      schemaUrl: 'https://example.invalid/keys.json',
+    });
+    await Promise.all([source.start(), source.start()]);
+    expect(source.isStarted()).toBe(true);
+    source.dispose();
+    expect(source.isStarted()).toBe(false);
+    await expect(source.start()).rejects.toThrow(/disposed/i);
+  });
+});

package/src/keybindings/keybinding-catalogue.ts

@@ -0,0 +1,171 @@
+export const KEYBINDING_ACTIONS = {
+  app: ['open-workspace-switcher'],
+  thinking: ['abort'],
+  'background-detail': ['return-to-main'],
+  recovery: ['retry'],
+  'chat-input': [
+    'submit',
+    'history-previous',
+    'history-next',
+    'history-search',
+    'cursor-left',
+    'cursor-right',
+    'delete-backward',
+    'delete-word',
+    'delete-line',
+  ],
+  'text-input': [
+    'submit',
+    'cursor-left',
+    'cursor-right',
+    'cursor-up',
+    'cursor-down',
+    'delete-backward',
+    'delete-word',
+    'delete-line',
+  ],
+  'autocomplete-menu': ['previous', 'next', 'close', 'accept', 'execute'],
+  'queued-prompt': ['cancel'],
+  'confirm-prompt': ['previous', 'next', 'confirm', 'choose-yes', 'choose-no'],
+  'permission-prompt': [
+    'previous',
+    'next',
+    'confirm',
+    'allow-once',
+    'allow-session',
+    'allow-project',
+    'deny',
+  ],
+  'text-prompt': ['submit', 'cancel', 'delete-backward'],
+  'list-picker': ['previous', 'next', 'select', 'cancel'],
+  'menu-select': ['previous', 'next', 'select', 'back'],
+  'multi-select': ['previous', 'next', 'toggle', 'confirm', 'cancel'],
+  'workspace-switcher': ['previous', 'next', 'select', 'close', 'attach'],
+  'background-list': ['previous', 'next', 'open', 'close'],
+  'transport-settings': ['previous', 'next', 'toggle', 'close'],
+  /** SCREEN-1993: the reverse prompt-history search overlay. */
+  'history-search': ['previous', 'next', 'cycle-scope', 'insert', 'execute', 'cancel'],
+  /**
+   * SCREEN-2002: the theme picker. Navigation PREVIEWS; only `select` applies. Printable keys are
+   * fine here because the picker takes no text.
+   */
+  'theme-picker': ['previous', 'next', 'select', 'toggle-syntax', 'toggle-motion', 'cancel'],
+} as const;
+
+export type TKeybindingContext = keyof typeof KEYBINDING_ACTIONS;
+export type TKeybindingAction<TContext extends TKeybindingContext = TKeybindingContext> =
+  (typeof KEYBINDING_ACTIONS)[TContext][number];
+
+type TDefaultKeybindings = {
+  readonly [TContext in TKeybindingContext]: Readonly<
+    Record<TKeybindingAction<TContext>, readonly string[]>
+  >;
+};
+
+export const DEFAULT_KEYBINDINGS = {
+  app: { 'open-workspace-switcher': ['ctrl+b'] },
+  thinking: { abort: ['escape'] },
+  'background-detail': { 'return-to-main': ['escape'] },
+  recovery: { retry: ['enter'] },
+  'chat-input': {
+    submit: ['enter'],
+    'history-previous': ['up'],
+    'history-next': ['down'],
+    'history-search': ['ctrl+r'],
+    'cursor-left': ['left'],
+    'cursor-right': ['right'],
+    'delete-backward': ['backspace', 'delete'],
+    'delete-word': ['ctrl+w'],
+    'delete-line': ['ctrl+u'],
+  },
+  'text-input': {
+    submit: ['enter'],
+    'cursor-left': ['left'],
+    'cursor-right': ['right'],
+    'cursor-up': ['up'],
+    'cursor-down': ['down'],
+    'delete-backward': ['backspace', 'delete'],
+    'delete-word': ['ctrl+w'],
+    'delete-line': ['ctrl+u'],
+  },
+  'autocomplete-menu': {
+    previous: ['up'],
+    next: ['down'],
+    close: ['escape'],
+    accept: ['tab'],
+    execute: ['enter'],
+  },
+  'queued-prompt': { cancel: ['backspace', 'delete'] },
+  'confirm-prompt': {
+    previous: ['left', 'up'],
+    next: ['right', 'down'],
+    confirm: ['enter'],
+    'choose-yes': ['y'],
+    'choose-no': ['n'],
+  },
+  'permission-prompt': {
+    previous: ['left', 'up'],
+    next: ['right', 'down'],
+    confirm: ['enter'],
+    'allow-once': ['y'],
+    'allow-session': ['s', 'a'],
+    'allow-project': ['p'],
+    deny: ['n', 'd'],
+  },
+  'text-prompt': {
+    submit: ['enter'],
+    cancel: ['escape'],
+    'delete-backward': ['backspace', 'delete'],
+  },
+  'list-picker': { previous: ['up'], next: ['down'], select: ['enter'], cancel: ['escape'] },
+  'menu-select': { previous: ['up'], next: ['down'], select: ['enter'], back: ['escape'] },
+  'multi-select': {
+    previous: ['up'],
+    next: ['down'],
+    toggle: ['space'],
+    confirm: ['enter'],
+    cancel: ['escape'],
+  },
+  'workspace-switcher': {
+    previous: ['up'],
+    next: ['down'],
+    select: ['enter'],
+    close: ['ctrl+b', 'escape'],
+    attach: ['a'],
+  },
+  'background-list': {
+    previous: ['up'],
+    next: ['down'],
+    open: ['enter'],
+    close: ['escape'],
+  },
+  'transport-settings': {
+    previous: ['up'],
+    next: ['down'],
+    toggle: ['space'],
+    close: ['enter', 'escape'],
+  },
+  'history-search': {
+    previous: ['up'],
+    next: ['down', 'ctrl+r'],
+    'cycle-scope': ['ctrl+s'],
+    insert: ['enter', 'tab'],
+    execute: ['ctrl+e'],
+    cancel: ['escape'],
+  },
+  'theme-picker': {
+    previous: ['up'],
+    next: ['down'],
+    select: ['enter'],
+    'toggle-syntax': ['s'],
+    'toggle-motion': ['m'],
+    cancel: ['escape'],
+  },
+} as const satisfies TDefaultKeybindings;
+
+export const TEXT_ENTRY_CONTEXTS: ReadonlySet<TKeybindingContext> = new Set([
+  'chat-input',
+  'text-input',
+  'text-prompt',
+  'history-search',
+]);