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

package/src/keybindings/keybinding-registry.ts

@@ -0,0 +1,303 @@
+import { isJsonRecord } from '../json-value.js';
+import {
+  DEFAULT_KEYBINDINGS,
+  KEYBINDING_ACTIONS,
+  TEXT_ENTRY_CONTEXTS,
+  type TKeybindingAction,
+  type TKeybindingContext,
+} from './keybinding-catalogue.js';
+import {
+  displayBinding,
+  keybindingDeliverySignature,
+  keyStrokesFromInput,
+  normalizeBinding,
+  type IKeyInput,
+} from './keybinding-syntax.js';
+
+import type { TJsonValue } from '../json-value.js';
+
+export { DEFAULT_KEYBINDINGS } from './keybinding-catalogue.js';
+export type { IKeyInput } from './keybinding-syntax.js';
+export type { TKeybindingAction, TKeybindingContext } from './keybinding-catalogue.js';
+
+export interface IKeybindingWarning {
+  readonly code: 'multiplexer-conflict' | 'modifier-delivery';
+  readonly path: string;
+  readonly message: string;
+}
+
+export interface IKeybindingDiagnostic {
+  readonly file: string;
+  readonly path: string;
+  readonly message: string;
+}
+
+export interface IKeybindingSnapshot {
+  readonly generation: number;
+  readonly sourcePath: string;
+  readonly bindings: Readonly<
+    Record<TKeybindingContext, Readonly<Record<string, readonly string[]>>>
+  >;
+  readonly warnings: readonly IKeybindingWarning[];
+  readonly diagnostic?: IKeybindingDiagnostic;
+}
+
+export type TParseKeybindingsResult =
+  | { readonly ok: true; readonly snapshot: IKeybindingSnapshot }
+  | { readonly ok: false; readonly diagnostic: IKeybindingDiagnostic };
+
+const CHORD_TIMEOUT_MS = 1_000;
+
+function diagnostic(file: string, path: string, message: string): TParseKeybindingsResult {
+  return { ok: false, diagnostic: { file, path, message } };
+}
+
+function cloneDefaults(): Record<TKeybindingContext, Record<string, string[]>> {
+  return Object.fromEntries(
+    Object.entries(DEFAULT_KEYBINDINGS).map(([context, actions]) => [
+      context,
+      Object.fromEntries(
+        Object.entries(actions).map(([action, bindings]) => [action, [...bindings]]),
+      ),
+    ]),
+  ) as Record<TKeybindingContext, Record<string, string[]>>;
+}
+
+function bindingValues(value: TJsonValue): readonly string[] | null | undefined {
+  if (value === null) return null;
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string')) {
+    return value;
+  }
+  return undefined;
+}
+
+function validateContextBindings(
+  context: TKeybindingContext,
+  bindings: Record<string, string[]>,
+  file: string,
+): TParseKeybindingsResult | undefined {
+  const owners = new Map<string, string>();
+  const prefixes = new Map<string, string>();
+  for (const [action, values] of Object.entries(bindings)) {
+    for (const binding of values) {
+      const deliveryBinding = keybindingDeliverySignature(binding);
+      const owner = owners.get(deliveryBinding);
+      const actionPath = `$.bindings.${context}.${action}`;
+      if (owner !== undefined && owner !== action) {
+        return diagnostic(file, actionPath, `Binding duplicates action ${owner}.`);
+      }
+      const strokes = deliveryBinding.split(' ');
+      if (strokes.length > 1 && TEXT_ENTRY_CONTEXTS.has(context) && isPrintable(strokes[0] ?? '')) {
+        return diagnostic(
+          file,
+          actionPath,
+          'Printable text cannot begin a chord in a text context.',
+        );
+      }
+      owners.set(deliveryBinding, action);
+      if (strokes.length > 1) prefixes.set(strokes[0] ?? '', action);
+    }
+  }
+  for (const [binding, action] of owners) {
+    const prefixOwner = prefixes.get(binding);
+    if (prefixOwner !== undefined) {
+      return diagnostic(
+        file,
+        `$.bindings.${context}.${prefixOwner}`,
+        `Chord prefix collides with action ${action}.`,
+      );
+    }
+  }
+  return undefined;
+}
+
+function isPrintable(stroke: string): boolean {
+  return !stroke.includes('+') && [...stroke].length === 1;
+}
+
+function warningFor(binding: string, path: string): IKeybindingWarning[] {
+  const warnings: IKeybindingWarning[] = [];
+  if (binding.split(' ').includes('ctrl+b')) {
+    warnings.push({
+      code: 'multiplexer-conflict',
+      path,
+      message: 'Ctrl+B may be captured by a terminal multiplexer.',
+    });
+  }
+  if (/ctrl\+shift\+[a-z]/u.test(binding)) {
+    warnings.push({
+      code: 'modifier-delivery',
+      path,
+      message: 'This terminal may not distinguish Ctrl+Shift from Ctrl.',
+    });
+  }
+  return warnings;
+}
+
+export function parseKeybindingsDocument(text: string, file: string): TParseKeybindingsResult {
+  let value: TJsonValue;
+  try {
+    value = JSON.parse(text) as TJsonValue;
+  } catch (cause) {
+    return diagnostic(file, '$', cause instanceof Error ? cause.message : 'Invalid JSON.');
+  }
+  if (!isJsonRecord(value)) return diagnostic(file, '$', 'Expected an object.');
+  if (value.version !== 1) return diagnostic(file, '$.version', 'Expected version 1.');
+  if (!isJsonRecord(value.bindings)) return diagnostic(file, '$.bindings', 'Expected an object.');
+
+  const effective = cloneDefaults();
+  const warnings: IKeybindingWarning[] = [];
+  for (const [rawContext, rawActions] of Object.entries(value.bindings)) {
+    if (!(rawContext in KEYBINDING_ACTIONS)) {
+      return diagnostic(file, `$.bindings.${rawContext}`, 'Unknown keybinding context.');
+    }
+    const context = rawContext as TKeybindingContext;
+    if (!isJsonRecord(rawActions)) {
+      return diagnostic(file, `$.bindings.${context}`, 'Expected an action object.');
+    }
+    for (const [action, rawBindings] of Object.entries(rawActions)) {
+      if (!(KEYBINDING_ACTIONS[context] as readonly string[]).includes(action)) {
+        return diagnostic(file, `$.bindings.${context}.${action}`, 'Unknown action.');
+      }
+      const values = bindingValues(rawBindings);
+      const actionPath = `$.bindings.${context}.${action}`;
+      if (values === undefined) {
+        return diagnostic(file, actionPath, 'Expected a binding, binding list, or null.');
+      }
+      if (values === null) {
+        effective[context][action] = [];
+        continue;
+      }
+      const normalized: string[] = [];
+      for (const rawBinding of values) {
+        const binding = normalizeBinding(rawBinding);
+        if (binding === undefined) return diagnostic(file, actionPath, 'Invalid binding syntax.');
+        if (binding.split(' ').includes('ctrl+c')) {
+          return diagnostic(file, actionPath, 'Ctrl+C is reserved for two-stage shutdown.');
+        }
+        normalized.push(binding);
+        warnings.push(...warningFor(binding, actionPath));
+      }
+      effective[context][action] = normalized;
+    }
+  }
+  for (const context of Object.keys(effective) as TKeybindingContext[]) {
+    const invalid = validateContextBindings(context, effective[context], file);
+    if (invalid !== undefined) return invalid;
+  }
+  const bindings = Object.freeze(
+    Object.fromEntries(
+      Object.entries(effective).map(([context, actions]) => [
+        context,
+        Object.freeze(
+          Object.fromEntries(
+            Object.entries(actions).map(([action, bindings]) => [action, Object.freeze(bindings)]),
+          ),
+        ),
+      ]),
+    ),
+  ) as IKeybindingSnapshot['bindings'];
+  return {
+    ok: true,
+    snapshot: Object.freeze({
+      generation: 0,
+      sourcePath: file,
+      bindings,
+      warnings: Object.freeze(warnings),
+    }),
+  };
+}
+
+export interface IChordState {
+  readonly context?: TKeybindingContext;
+  readonly generation?: number;
+  readonly strokes: readonly string[];
+  readonly deadline?: number;
+}
+
+export function createEmptyChordState(): IChordState {
+  return { strokes: [] };
+}
+
+function actionBindings(
+  snapshot: IKeybindingSnapshot,
+  context: TKeybindingContext,
+): [TKeybindingAction, readonly string[]][] {
+  return Object.entries(snapshot.bindings[context]) as [TKeybindingAction, readonly string[]][];
+}
+
+export function resolveKeybindingInput(options: {
+  readonly snapshot: IKeybindingSnapshot;
+  readonly state: IChordState;
+  readonly context: TKeybindingContext;
+  readonly input: string;
+  readonly key: IKeyInput;
+  readonly now: number;
+}): {
+  readonly state: IChordState;
+  readonly actions: readonly TKeybindingAction[];
+  readonly consumed: boolean;
+} {
+  const strokes = keyStrokesFromInput(options.input, options.key);
+  if (strokes.length === 0) {
+    return { state: createEmptyChordState(), actions: [], consumed: false };
+  }
+  const stateValid =
+    options.state.context === options.context &&
+    options.state.generation === options.snapshot.generation &&
+    (options.state.deadline === undefined || options.now <= options.state.deadline) &&
+    !options.key.escape;
+  const prior = stateValid ? options.state.strokes : [];
+  const entries = actionBindings(options.snapshot, options.context);
+  for (const stroke of strokes) {
+    const sequence = [...prior, stroke].join(' ');
+    const exact = entries
+      .filter(([, bindings]) => bindings.includes(sequence))
+      .map(([action]) => action);
+    if (exact.length > 0) {
+      return { state: createEmptyChordState(), actions: exact, consumed: true };
+    }
+    if (
+      entries.some(([, bindings]) => bindings.some((binding) => binding.startsWith(`${sequence} `)))
+    ) {
+      return {
+        state: {
+          context: options.context,
+          generation: options.snapshot.generation,
+          strokes: [...prior, stroke],
+          deadline: options.now + CHORD_TIMEOUT_MS,
+        },
+        actions: [],
+        consumed: true,
+      };
+    }
+  }
+  if (prior.length > 0) {
+    return resolveKeybindingInput({ ...options, state: createEmptyChordState() });
+  }
+  return { state: createEmptyChordState(), actions: [], consumed: false };
+}
+
+export function keybindingHints<TContext extends TKeybindingContext>(
+  snapshot: IKeybindingSnapshot,
+  context: TContext,
+  actions: readonly (readonly [
+    TKeybindingAction<TContext> | readonly TKeybindingAction<TContext>[],
+    string,
+  ])[],
+): { keys: string; label: string }[] {
+  return actions.flatMap(([actionOrActions, label]) => {
+    const grouped = Array.isArray(actionOrActions);
+    const actionList = grouped ? actionOrActions : [actionOrActions];
+    const bindings = actionList.flatMap((action) => {
+      const values = snapshot.bindings[context][action] ?? [];
+      return grouped ? values.slice(0, 1) : values;
+    });
+    const displayed = bindings.map(displayBinding);
+    const keys = displayed.every((binding) => /^[↑↓←→]$/u.test(binding))
+      ? displayed.join('')
+      : displayed.join('/');
+    return bindings.length === 0 ? [] : [{ keys, label }];
+  });
+}

package/src/keybindings/keybinding-syntax.ts

@@ -0,0 +1,155 @@
+export interface IKeyInput {
+  readonly ctrl?: boolean;
+  readonly shift?: boolean;
+  readonly meta?: boolean;
+  readonly return?: boolean;
+  readonly escape?: boolean;
+  readonly tab?: boolean;
+  readonly upArrow?: boolean;
+  readonly downArrow?: boolean;
+  readonly leftArrow?: boolean;
+  readonly rightArrow?: boolean;
+  readonly backspace?: boolean;
+  readonly delete?: boolean;
+}
+
+const MODIFIER_ALIASES: Readonly<Record<string, 'ctrl' | 'alt' | 'meta' | 'shift'>> = {
+  ctrl: 'ctrl',
+  control: 'ctrl',
+  alt: 'alt',
+  option: 'alt',
+  meta: 'meta',
+  cmd: 'meta',
+  command: 'meta',
+  shift: 'shift',
+};
+const MODIFIER_ORDER = ['ctrl', 'alt', 'meta', 'shift'] as const;
+const KEY_ALIASES: Readonly<Record<string, string>> = {
+  return: 'enter',
+  enter: 'enter',
+  esc: 'escape',
+  escape: 'escape',
+  tab: 'tab',
+  space: 'space',
+  spacebar: 'space',
+  up: 'up',
+  down: 'down',
+  left: 'left',
+  right: 'right',
+  backspace: 'backspace',
+  delete: 'delete',
+};
+
+export function normalizeBinding(raw: string): string | undefined {
+  const strokes = raw.trim().split(/\s+/u);
+  if (strokes.length < 1 || strokes.length > 2) return undefined;
+  const normalized = strokes.map(normalizeStroke);
+  return normalized.every((stroke): stroke is string => stroke !== undefined)
+    ? normalized.join(' ')
+    : undefined;
+}
+
+function normalizeStroke(raw: string): string | undefined {
+  if (!raw || raw.includes(' ')) return undefined;
+  const parts = raw.split('+');
+  if (parts.some((part) => part.length === 0)) return undefined;
+  const rawKey = parts.at(-1);
+  if (rawKey === undefined) return undefined;
+  const modifiers = new Set<'ctrl' | 'alt' | 'meta' | 'shift'>();
+  for (const rawModifier of parts.slice(0, -1)) {
+    const modifier = MODIFIER_ALIASES[rawModifier.toLowerCase()];
+    if (modifier === undefined || modifiers.has(modifier)) return undefined;
+    modifiers.add(modifier);
+  }
+  let key = KEY_ALIASES[rawKey.toLowerCase()];
+  if (key === undefined) {
+    if ([...rawKey].length !== 1 || /\s/u.test(rawKey)) return undefined;
+    key = rawKey.toLowerCase();
+    if (parts.length === 1 && rawKey !== key) modifiers.add('shift');
+  }
+  return [...MODIFIER_ORDER.filter((modifier) => modifiers.has(modifier)), key].join('+');
+}
+
+function keyStrokeFromInput(input: string, key: IKeyInput): string | undefined {
+  // Ink preserves LF as a one-character input string instead of setting `key.return`. In terminal
+  // raw mode that byte is Ctrl+J; normalize it before printable-text handling can treat it as paste.
+  if (/^[\r\n]*\n[\r\n]*$/u.test(input)) return 'ctrl+j';
+  const special = key.return
+    ? 'enter'
+    : key.escape
+      ? 'escape'
+      : key.tab
+        ? 'tab'
+        : key.upArrow
+          ? 'up'
+          : key.downArrow
+            ? 'down'
+            : key.leftArrow
+              ? 'left'
+              : key.rightArrow
+                ? 'right'
+                : key.backspace
+                  ? 'backspace'
+                  : key.delete
+                    ? 'delete'
+                    : input === ' '
+                      ? 'space'
+                      : [...input].length === 1
+                        ? input.toLowerCase()
+                        : undefined;
+  if (special === undefined) return undefined;
+  const modifiers = [
+    ...(key.ctrl ? ['ctrl'] : []),
+    ...(key.meta ? ['meta'] : []),
+    ...(key.shift ? ['shift'] : []),
+  ];
+  return [...modifiers, special].join('+');
+}
+
+/**
+ * Terminal protocols collapse several control characters onto named keys. Keep the configured
+ * spelling for hints, but offer every spelling that the same received byte can represent.
+ */
+export function keyStrokesFromInput(input: string, key: IKeyInput): readonly string[] {
+  const primary = keyStrokeFromInput(input, key);
+  if (primary === undefined) return [];
+  if (primary === 'enter') return ['enter', 'ctrl+m'];
+  if (primary === 'tab') return ['tab', 'ctrl+i'];
+  if (primary === 'escape') return ['escape', 'ctrl+['];
+  return [primary];
+}
+
+export function keybindingDeliverySignature(binding: string): string {
+  return binding
+    .split(' ')
+    .map((stroke) => {
+      if (stroke === 'ctrl+m') return 'enter';
+      if (stroke === 'ctrl+i') return 'tab';
+      if (stroke === 'ctrl+[') return 'escape';
+      return stroke;
+    })
+    .join(' ');
+}
+
+export function displayBinding(binding: string): string {
+  const displayStroke = (stroke: string): string =>
+    stroke
+      .split('+')
+      .map(
+        (part) =>
+          ({
+            ctrl: 'Ctrl',
+            alt: 'Alt',
+            meta: 'Meta',
+            shift: 'Shift',
+            escape: 'Esc',
+            up: '↑',
+            down: '↓',
+            left: '←',
+            right: '→',
+          })[part] ??
+          (part.length === 1 ? part.toUpperCase() : `${part[0]?.toUpperCase()}${part.slice(1)}`),
+      )
+      .join('+');
+  return binding.split(' ').map(displayStroke).join(' ');
+}

package/src/keybindings/keybindings-context.tsx

@@ -0,0 +1,124 @@
+import { useInput } from 'ink';
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
+
+import {
+  createEmptyChordState,
+  keybindingHints,
+  parseKeybindingsDocument,
+  resolveKeybindingInput,
+  type IChordState,
+  type IKeybindingSnapshot,
+  type IKeyInput,
+  type TKeybindingAction,
+  type TKeybindingContext,
+} from './keybinding-registry.js';
+
+import type { IKeybindingsSource } from './node-keybindings-source.js';
+
+const parsedDefault = parseKeybindingsDocument('{"version":1,"bindings":{}}', '<defaults>');
+if (!parsedDefault.ok) throw new Error(parsedDefault.diagnostic.message);
+const DEFAULT_SNAPSHOT = parsedDefault.snapshot;
+
+const KeybindingsContext = createContext<IKeybindingSnapshot>(DEFAULT_SNAPSHOT);
+
+export function KeybindingsProvider({
+  source,
+  children,
+}: {
+  source?: IKeybindingsSource;
+  children: React.ReactNode;
+}): React.ReactElement {
+  const [snapshot, setSnapshot] = useState(() => source?.getSnapshot() ?? DEFAULT_SNAPSHOT);
+  useEffect(() => {
+    if (source === undefined) return;
+    setSnapshot(source.getSnapshot());
+    return source.subscribe(setSnapshot);
+  }, [source]);
+  return <KeybindingsContext.Provider value={snapshot}>{children}</KeybindingsContext.Provider>;
+}
+
+export function useKeybindings(): IKeybindingSnapshot {
+  return useContext(KeybindingsContext);
+}
+
+export function useKeybindingHints<TContext extends TKeybindingContext>(
+  context: TContext,
+  actions: readonly (readonly [
+    TKeybindingAction<TContext> | readonly TKeybindingAction<TContext>[],
+    string,
+  ])[],
+): { keys: string; label: string }[] {
+  return keybindingHints(useKeybindings(), context, actions);
+}
+
+export function useKeybindingActions<
+  TContext extends TKeybindingContext,
+  TFallback extends TKeybindingContext = TContext,
+>(
+  context: TContext,
+  handler: (
+    actions: readonly (TKeybindingAction<TContext> | TKeybindingAction<TFallback>)[],
+    input: string,
+    key: IKeyInput,
+    consumed: boolean,
+    resolvedContext: TContext | TFallback,
+  ) => void,
+  options: {
+    readonly isActive?: boolean;
+    /**
+     * A key `context` does not bind is resolved again here, so a surface layered over an editor (the
+     * autocomplete menu over the chat input) leaves every key it does not use to the editor's bindings.
+     */
+    readonly fallbackContext?: TFallback;
+  } = {},
+): void {
+  const snapshot = useKeybindings();
+  const stateRef = useRef<IChordState>(createEmptyChordState());
+  const fallbackStateRef = useRef<IChordState>(createEmptyChordState());
+  const { fallbackContext } = options;
+  useEffect(() => {
+    stateRef.current = createEmptyChordState();
+    fallbackStateRef.current = createEmptyChordState();
+  }, [context, fallbackContext, snapshot.generation]);
+  useInput(
+    (input, key) => {
+      const result = resolveKeybindingInput({
+        snapshot,
+        state: stateRef.current,
+        context,
+        input,
+        key,
+        now: Date.now(),
+      });
+      stateRef.current = result.state;
+      if (fallbackContext === undefined || result.consumed) {
+        fallbackStateRef.current = createEmptyChordState();
+        handler(
+          result.actions as readonly TKeybindingAction<TContext>[],
+          input,
+          key,
+          result.consumed,
+          context,
+        );
+        return;
+      }
+      const fallback = resolveKeybindingInput({
+        snapshot,
+        state: fallbackStateRef.current,
+        context: fallbackContext,
+        input,
+        key,
+        now: Date.now(),
+      });
+      fallbackStateRef.current = fallback.state;
+      handler(
+        fallback.actions as readonly TKeybindingAction<TFallback>[],
+        input,
+        key,
+        fallback.consumed,
+        fallbackContext,
+      );
+    },
+    { isActive: options.isActive ?? true },
+  );
+}