feat(tui): route shell shortcuts through opentui keymap

Author: TheGreatAxios

bun.lock

@@ -1,39 +1,25 @@
 # Keymap evaluation
 
-Decision record for a global keymap on the imperative `@opentui/core` 0.6.4 surface. This record changes no code.
+Decision record for application key bindings on `@opentui/core` 0.6.6. The engine is `@opentui/keymap`.
 
 ## Recommendation
 
-**Decline** a global keymap. Do not adopt one later under another name, and file no follow-up. The library does not ship an application keymap, and the shell behaviors that would have to move into one are not widget bindings.
+**Adopt** `@opentui/keymap` for application commands. Do not move widget-local editing, the scroll lease, or the kill ring into it.
 
-## What 0.6.4 actually provides
+`createDefaultOpenTuiKeymap(renderer)` installs the default parser, the event matcher, and the enabled and metadata fields. The shell registers one layer: `commands` (`name`, `run`) and `bindings` (`key`, `cmd`). Each `run` calls the existing handler in `src/tui/shell/keys.ts`. The help overlay reads those rows from the same catalog as the registration (`keymapShortcuts()` plus `promptLocalShortcuts()`).
 
-Bindings are per widget. `TextareaRenderable` takes `keyBindings` of `TextareaAction` (caret, selection, kill-to-line, undo, submit, and the rest of the editor action set). `SelectRenderable` takes `keyBindings` of `SelectAction`: `move-up`, `move-down`, `move-up-fast`, `move-down-fast`, `select-current`. The same shape exists on `TabSelect` and the terminal console; `Input` reuses the textarea actions. Each widget merges its defaults with the caller's list and looks up one event.
+## What stays a command body
 
-`mergeKeyBindings(defaults, custom)` in `lib/keybinding.internal.d.ts` is that merge: two `KeyBinding<Action>[]` lists become one list for one widget. It does not route across the shell, it does not know which surface holds focus, and it does not encode policy that spans widgets. There is no keymap engine package on this core. The repo depends on `@opentui/core` only.
+Widget `keyBindings` cannot express policy that spans the shell:
 
-## What stays
+- **Scroll lease.** One surface holds the lease. The wheel must not move the transcript while a modal is open. Arrow keys never scroll the transcript.
+- **Kill ring.** Ctrl+K/U/W and Alt+D kill, Ctrl+Y yanks, Alt+Y yank-pops. Those stay Textarea-local in `prompt-kill-ring.ts`. The keymap does not bind them.
+- **Ctrl+C.** Pause, stop sub-agents, and quit stay `handleCtrlC`. The keymap command calls that handler; it does not reimplement the arming window. A decision gate still declines before the arming handler runs.
 
-- `src/tui/shell/keys.ts` is the shell dispatcher: paste guard, overlay keys, prompt wheel forwarding, kill/yank orchestration, and Ctrl+C arming. It is not a binding table.
-- `src/tui/keybindings.ts` is the shortcut catalog the help overlay reads. `keybindings.test.ts` drives each row through a live shell. The catalog describes chords; it does not implement them.
-
-Neither file is a stand-in for `mergeKeyBindings`. Replacing them with widget tables would drop behavior the tables cannot express.
-
-## Deleted if a global keymap were adopted
-
-It is not adopted. If it were, the deletion this record refuses is:
-
-- `src/tui/shell/keys.ts` would be deleted or reduced to widget binding tables.
-- `src/tui/keybindings.ts` would be deleted in favor of `mergeKeyBindings` defaults.
-
-Those files stay. Reducing them would drop three policies that are not widget bindings:
-
-- **Scroll lease.** One surface holds the lease. The wheel must not move the transcript while a modal is open on top of it. Prompt wheel events are forwarded to the transcript only because the prompt itself does not scroll. Arrow keys never scroll anything: in the prompt they are caret motion or history recall, and in an overlay list they move the selection. Page keys move only the surface that holds the lease.
-- **Kill ring.** The prompt kill ring (kill chords and yank / yank-pop) is shell state. Textarea delete actions discard or edit a buffer; they are not that ring.
-- **Ctrl+C.** The first press pauses a busy run or clears an idle prompt. A later press inside the arming window quits, and live sub-agents insert a stop press before quit. That is session policy, not a textarea `submit` or select `select-current` binding.
+Paste, overlay accept, and prompt newline chords stay where they were. Enter, Up, and Down stay in `keys.ts` because the same chord sends, steers, recalls history, or moves the caret. Ctrl+X is the held-item drop and is a keymap command.
 
 ## Checks
 
-- [x] Decline a global keymap. `mergeKeyBindings` and per-widget `keyBindings` are the only real key APIs, and they are not an application map.
-- [ ] Adopt a global keymap and delete `shell/keys.ts` and `keybindings.ts`. Cannot check. No keymap engine exists on this core, and the adopt path would drop the scroll lease, the kill ring, and Ctrl+C policy. Leave this unchecked.
-- [x] File no follow-up. This record does not adopt a path that needs one.
+- [x] Use `@opentui/keymap` for application commands. Help rows for those chords come from the keymap catalog.
+- [x] Leave the scroll lease, the kill ring, and Ctrl+C policy as command bodies. Widget bindings cannot express them.
+- [ ] Delete `shell/keys.ts` and `keybindings.ts`. Cannot check. The dispatcher and the prompt-local catalog stay.

docs/TUI-keymap-eval.md

@@ -106,7 +106,8 @@
     "@intx/types": "workspace:*",
     "@intx/workflow-host": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@opentui/core": "0.6.4",
+    "@opentui/core": "0.6.6",
+    "@opentui/keymap": "0.6.6",
     "arktype": "catalog:",
     "isomorphic-git": "catalog:",
     "@corbits/code-agent-designer": "workspace:*",
@@ -125,13 +126,13 @@
     "typescript-language-server": "^4.3.4"
   },
   "optionalDependencies": {
-    "@opentui/core-darwin-arm64": "0.6.4",
-    "@opentui/core-darwin-x64": "0.6.4",
-    "@opentui/core-linux-arm64": "0.6.4",
-    "@opentui/core-linux-arm64-musl": "0.6.4",
-    "@opentui/core-linux-x64": "0.6.4",
-    "@opentui/core-linux-x64-musl": "0.6.4",
-    "@opentui/core-win32-arm64": "0.6.4",
-    "@opentui/core-win32-x64": "0.6.4"
+    "@opentui/core-darwin-arm64": "0.6.6",
+    "@opentui/core-darwin-x64": "0.6.6",
+    "@opentui/core-linux-arm64": "0.6.6",
+    "@opentui/core-linux-arm64-musl": "0.6.6",
+    "@opentui/core-linux-x64": "0.6.6",
+    "@opentui/core-linux-x64-musl": "0.6.6",
+    "@opentui/core-win32-arm64": "0.6.6",
+    "@opentui/core-win32-x64": "0.6.6"
   }
 }

package.json

@@ -1,14 +1,18 @@
 /**
  * OpenTUI shell keybinding catalog (pure data) — the help overlay's source
- * of truth. Every row must be a chord that really works: a handler in
- * `src/tui/shell.ts`, or a default prompt binding from @opentui/core. Do
- * not hand-transcribe from docs; `keybindings.test.ts` drives every row's
- * chord through a live shell and asserts its effect.
+ * of truth. Rows with `command` are application chords registered on
+ * `@opentui/keymap`. Rows without one stay prompt-local: textarea defaults,
+ * the kill ring, or a chord whose meaning depends on context keys.ts still
+ * owns. `keybindings.test.ts` drives every row through a live shell.
  */
 
 export interface ShellShortcut {
   readonly keys: string;
   readonly description: string;
+  /** `@opentui/keymap` command name. Absent for prompt-local chords. */
+  readonly command?: string;
+  /** Binding strings for `command`. Absent for prompt-local chords. */
+  readonly bindings?: readonly string[];
 }
 
 export const SHELL_SHORTCUTS: readonly ShellShortcut[] = [
@@ -21,58 +25,84 @@ export const SHELL_SHORTCUTS: readonly ShellShortcut[] = [
     keys: "Alt+Enter",
     description:
       "queue a follow-up delivered only when the run goes idle; does nothing unless a run is busy",
+    command: "shell.queue",
+    bindings: ["alt+return"],
   },
   {
     keys: "Up / Down / Enter / Ctrl+X",
     description:
       "on held items above the prompt: select, send now, drop (Esc backs out)",
+    // Up, Down, and Enter also move the caret, recall history, or send.
+    // Only Ctrl+X is unambiguous; the others stay in keys.ts.
+    command: "shell.held.drop",
+    bindings: ["ctrl+x"],
   },
   {
     keys: "Ctrl+C",
     description:
       "pause a busy run and hold the queue, or clear the prompt and attachments when idle; Ctrl+C again to exit — with live sub-agents, a 2nd press stops them, a 3rd quits",
+    command: "shell.interrupt",
+    bindings: ["ctrl+c"],
   },
   {
     keys: "Ctrl+G",
     description:
       "pop the most recently queued or steered message back into the prompt for editing",
+    command: "shell.cancel",
+    bindings: ["ctrl+g"],
   },
   {
     keys: "Alt+C",
     description:
       "copy mode: pick a message, tool output, or diff; press again to close it",
+    command: "shell.copy",
+    bindings: ["alt+c"],
   },
   {
     keys: "Alt+M",
     description:
       "toggle DEC mouse capture (on by default: wheel scroll, click-to-expand, drag-to-copy); off restores native terminal drag-select",
+    command: "shell.mouse",
+    bindings: ["alt+m"],
   },
   {
     keys: "Alt+E",
     description:
       "expand or collapse every collapsible row (tool call, diff, skill, reasoning)",
+    command: "shell.expand",
+    bindings: ["alt+e"],
   },
   {
     keys: "Alt+T",
     description:
       "show or hide the task list above the prompt (hidden by default)",
+    command: "shell.tasks",
+    bindings: ["alt+t"],
   },
   {
     keys: "Alt+O",
     description:
       "observe a live subagent session; a system row says so when there is none",
+    command: "shell.observe",
+    bindings: ["alt+o"],
   },
   {
     keys: "Tab",
     description: "move focus between the prompt and the transcript",
+    command: "shell.focus",
+    bindings: ["tab"],
   },
   {
     keys: "Shift+Tab",
     description: "cycle reasoning effort for the current model",
+    command: "shell.effort",
+    bindings: ["shift+tab"],
   },
   {
     keys: "Esc",
     description: "close the open overlay, or leave subagent observe",
+    command: "shell.dismiss",
+    bindings: ["escape"],
   },
   {
     keys: "Ctrl+B / Ctrl+F",
@@ -128,10 +158,34 @@ export const SHELL_SHORTCUTS: readonly ShellShortcut[] = [
   },
 ] as const;
 
-/** Help rows from the shell's own catalog, so they cannot drift from it. */
+/** Application chords the keymap registers. */
+export function keymapShortcuts(): readonly ShellShortcut[] {
+  return SHELL_SHORTCUTS.filter((row) => row.command !== undefined);
+}
+
+/**
+ * Prompt-local rows: textarea defaults, the kill ring, paste, and chords
+ * whose meaning depends on context the keymap does not own.
+ */
+export function promptLocalShortcuts(): readonly ShellShortcut[] {
+  return SHELL_SHORTCUTS.filter((row) => row.command === undefined);
+}
+
+function formatShortcut(row: ShellShortcut): string {
+  return `${row.keys} — ${row.description}`;
+}
+
+/**
+ * Help rows from the keymap catalog plus prompt-local rows, in catalog
+ * order, so the overlay cannot drift from either list.
+ */
 export function helpItems(): readonly string[] {
+  const owned = new Set<string>([
+    ...keymapShortcuts().map((row) => row.keys),
+    ...promptLocalShortcuts().map((row) => row.keys),
+  ]);
   return [
-    ...SHELL_SHORTCUTS.map((s) => `${s.keys} — ${s.description}`),
+    ...SHELL_SHORTCUTS.filter((row) => owned.has(row.keys)).map(formatShortcut),
     "Close help",
   ];
 }

src/tui/keybindings.ts

@@ -83,6 +83,7 @@ import {
   createShellKeyHandlers,
   routePromptWheelToTranscript,
 } from "./keys.js";
+import { attachShellKeymap } from "./keymap.js";
 
 const DEFAULT_TITLE = "corbits";
 
@@ -364,6 +365,7 @@ export function createAppShell(
   }
 
   let disposed = false;
+  let detachKeymap: (() => void) | undefined;
   let session = createSessionQueue(run);
   const seedPending = Math.max(0, Math.floor(options?.pendingQueue ?? 0));
   for (let i = 0; i < seedPending; i++) {
@@ -518,6 +520,8 @@ export function createAppShell(
       shell.disposed = true;
       // Quit paths that skip idle Ctrl+C still drop Corbits-created files.
       clearPendingAttachments(shell);
+      detachKeymap?.();
+      detachKeymap = undefined;
       if (wireKeys) {
         renderer.keyInput.off("keypress", onKey);
         renderer.keyInput.off("paste", onPaste);
@@ -628,13 +632,14 @@ export function createAppShell(
   if (onObserveRequestOpt) {
     setPaletteOnObserveRequest(shell, onObserveRequestOpt);
   }
-  const { onKey, onPaste } = createShellKeyHandlers(shell, {
+  const { onKey, onPaste, keymap } = createShellKeyHandlers(shell, {
     isDisposed: () => disposed,
   });
   if (wireKeys) {
     renderer.keyInput.on("keypress", onKey);
     renderer.keyInput.on("paste", onPaste);
     prompt.onSubmit = onEnter;
+    detachKeymap = attachShellKeymap(renderer as CliRenderer, keymap);
   }
 
   applyLayout(shell, layout);