@crouton-kit/crouter 0.3.68 → 0.3.78

package/dist/core/runtime/tmux.js

@@ -8,8 +8,7 @@
 // root) or switch-client + select-window (across roots). done/dead nodes close
 // their window; reviving opens a fresh one.
 import { spawnSync } from 'node:child_process';
-import { readConfig } from '../config.js';
-import { defaultCanvasNavConfig } from '../../types.js';
+import { resolveUserKeybindings, } from '../keybindings/index.js';
 import { bundledPiCommandForShell } from './pi-cli.js';
 import { surfaceTmuxStyleArgs } from './surface-bg.js';
 // ---------------------------------------------------------------------------
@@ -72,13 +71,22 @@ function ensureBracketedPaste() {
     // broken `Enbp=E[?2004h` (no ESC) and silently disables bracketed paste.
     tmux(['set-option', '-sga', 'terminal-overrides', '*:Enbp=\\E[?2004h:Dsbp=\\E[?2004l']);
 }
+/** Server-level tmux prerequisites for crtr's viewer surfaces, applied once a
+ *  server exists (callers invoke via ensureSession). Currently: bracketed paste
+ *  capability (above) and `focus-events on`, which forwards terminal focus
+ *  in/out (DECSET 1004) to the program in each pane — the attach viewer uses it
+ *  to hollow out the editor cursor in blurred panes. */
+function ensureServerOptions() {
+    ensureBracketedPaste();
+    tmux(['set-option', '-s', 'focus-events', 'on']);
+}
 /** Create a detached session rooted at `cwd` if it doesn't exist. The session
  *  name is a root's tmux home; every node under that root is a window in it. */
 export function ensureSession(name, cwd) {
     if (!sessionExists(name)) {
         tmux(['new-session', '-d', '-s', name, '-c', cwd]);
     }
-    ensureBracketedPaste();
+    ensureServerOptions();
 }
 function envFlags(env) {
     const out = [];
@@ -400,135 +408,233 @@ export function sendKeysEnter(pane, text) {
     return tmux(['send-keys', '-t', pane, text, 'Enter']).ok;
 }
 // ---------------------------------------------------------------------------
-// Prefix menu — Alt+C opens a which-key-style tmux display-menu of crouter
-// actions. Installed on the running server at root boot; idempotent (a re-bind
-// overwrites the previous one). Menu entries are data-driven: tmux renders the
-// action tree, and every `crtr` / `popup` action routes through `crtr canvas
-// chord` so node-relative vars resolve in one safe place.
+// Crouter-owned tmux bindings
 // ---------------------------------------------------------------------------
+const TMUX_BINDING_MANIFEST = '@crtr_keybindings_manifest';
+const ROOT_TABLE = 'root';
+const MENU_ACTIONS = {
+    'crtr.tmux.menu.promote': { description: 'promote to orchestrator', action: { kind: 'keys', keys: '/promote' } },
+    'crtr.tmux.menu.resume': { description: 'resume node', action: { kind: 'keys', keys: '/resume-node' } },
+    'crtr.tmux.menu.demote': { description: 'demote to terminal', action: { kind: 'command', run: 'node lifecycle demote --pane {pane}' } },
+    'crtr.tmux.menu.detach': { description: 'detach to background', action: { kind: 'command', run: 'node lifecycle demote --pane {pane} --detach' } },
+    'crtr.tmux.menu.close-subtree': { description: 'close agent + subtree', action: { kind: 'command', run: 'node lifecycle close --pane {pane}' } },
+    'crtr.tmux.menu.context': { description: 'browse context dirs', action: { kind: 'keys', keys: '/context' } },
+    'crtr.tmux.menu.graph': { description: 'graph view', action: { kind: 'keys', keys: '/graph' } },
+    'crtr.tmux.menu.focus-manager': { description: 'focus manager', action: { kind: 'command', run: 'node focus {manager}' } },
+    'crtr.tmux.menu.open': undefined,
+    'crtr.tmux.menu.issues': undefined,
+    'crtr.tmux.menu.issue.idea': undefined,
+    'crtr.tmux.menu.issue.bug': undefined,
+    'crtr.tmux.node.next': undefined,
+    'crtr.tmux.node.previous': undefined,
+    'crtr.tmux.view.next': undefined,
+    'crtr.tmux.view.previous': undefined,
+};
 function escapeTmuxFormats(value) {
     return value.replace(/#/g, '##');
 }
-function runShellCmd(shellCmd) {
-    return `run-shell ${shellQuote(shellCmd)}`;
-}
-function tmuxCmd(args) {
+function tmuxCommand(args) {
     return args.map(shellQuote).join(' ');
 }
-function chordShellCmd(run) {
-    return runShellCmd(`crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))} >/dev/null 2>&1`);
-}
-function popupCmd(run) {
-    return `display-popup -E -w 60% -h 50% -d "#{pane_current_path}" ${shellQuote(`crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))} --interactive`)}`;
-}
-function keysCmd(keys) {
-    return `send-keys -t '#{pane_id}' ${shellQuote(escapeTmuxFormats(keys))} Enter`;
+function chordCommand(run, interactive = false) {
+    const command = `crtr canvas chord --pane '#{pane_id}' --run ${shellQuote(escapeTmuxFormats(run))}${interactive ? ' --interactive' : ''}`;
+    return interactive
+        ? `display-popup -E -w 60% -h 50% -d "#{pane_current_path}" ${shellQuote(command)}`
+        : `run-shell ${shellQuote(`${command} >/dev/null 2>&1`)}`;
+}
+function renderMenuAction(action) {
+    switch (action.kind) {
+        case 'keys': return `send-keys -t '#{pane_id}' ${shellQuote(escapeTmuxFormats(action.keys))} Enter`;
+        case 'command': return chordCommand(action.run);
+        case 'popup': return chordCommand(action.run, true);
+        case 'submenu': return tmuxCommand(buildMenuArgs(action.title, action.items));
+    }
 }
 function buildMenuArgs(title, items) {
     const safeTitle = escapeTmuxFormats(title);
+    const widestItem = items.reduce((width, item) => Math.max(width, escapeTmuxFormats(item.description).length), 0);
     const args = ['display-menu', '-T', `#[align=centre]${safeTitle}`, ...surfaceTmuxStyleArgs()];
-    const boxW = Math.max(safeTitle.length, ...items.map((i) => escapeTmuxFormats(i.desc).length)) + 6;
-    const nudgeX = 1;
-    const nudgeY = 3;
-    args.push('-x', `#{e|-:#{pane_right},${boxW + nudgeX}}`, '-y', `#{e|+:#{pane_top},${nudgeY}}`);
+    args.push('-x', `#{e|-:#{pane_right},${Math.max(safeTitle.length, widestItem) + 7}}`, '-y', '#{e|+:#{pane_top},3}');
     for (const item of items) {
-        args.push(escapeTmuxFormats(item.desc), escapeTmuxFormats(item.key), renderAction(item.action, item.desc));
+        args.push(escapeTmuxFormats(item.description), item.selector, renderMenuAction(item.action));
     }
     args.push('-esc / q to close', '', '');
     return args;
 }
-function renderAction(action, label) {
-    const kind = action.kind ?? 'crtr';
-    switch (kind) {
-        case 'keys':
-            return keysCmd(action.keys);
-        case 'popup':
-            return popupCmd(action.run);
-        case 'menu':
-            return tmuxCmd(buildMenuArgs(label, action.items));
-        case 'crtr':
-            return chordShellCmd(action.run);
-        default:
-            throw new Error(`unknown canvas action kind: ${kind}`);
+const TMUX_NAMED_KEYS = {
+    enter: 'Enter', escape: 'Escape', tab: 'Tab', backspace: 'BSpace', delete: 'DC',
+    space: 'Space', up: 'Up', down: 'Down', left: 'Left', right: 'Right',
+    pageup: 'PPage', pagedown: 'NPage', home: 'Home', end: 'End',
+};
+function tmuxKey(stroke) {
+    const parts = stroke.split('+');
+    let key = parts.pop();
+    const modifiers = new Set(parts);
+    if (modifiers.has('shift') && key.length === 1 && /[a-z]/.test(key)) {
+        key = key.toUpperCase();
+        modifiers.delete('shift');
+    }
+    key = TMUX_NAMED_KEYS[key] ?? key;
+    const prefix = [
+        modifiers.has('ctrl') ? 'C-' : '',
+        modifiers.has('alt') ? 'M-' : '',
+        modifiers.has('shift') ? 'S-' : '',
+    ].join('');
+    return `${prefix}${key}`;
+}
+function menuSelector(stroke) {
+    const parts = stroke.split('+');
+    const key = parts.at(-1);
+    return parts.includes('shift') && /[a-z]/.test(key) ? key.toUpperCase() : key === 'space' ? ' ' : key;
+}
+function menuItems(bindings) {
+    const issueItems = [];
+    for (const [id, description, type] of [
+        ['crtr.tmux.menu.issue.idea', 'idea', 'idea'],
+        ['crtr.tmux.menu.issue.bug', 'bug', 'bug'],
+    ]) {
+        for (const gesture of bindings.gestures(id)) {
+            issueItems.push({ description, selector: menuSelector(gesture), action: { kind: 'popup', run: `canvas issue new --type ${type}` } });
+        }
     }
+    const items = [];
+    for (const id of [
+        'crtr.tmux.menu.promote', 'crtr.tmux.menu.resume', 'crtr.tmux.menu.demote',
+        'crtr.tmux.menu.detach', 'crtr.tmux.menu.close-subtree', 'crtr.tmux.menu.context',
+        'crtr.tmux.menu.graph', 'crtr.tmux.menu.focus-manager', 'crtr.tmux.menu.issues',
+    ]) {
+        const entry = id === 'crtr.tmux.menu.issues'
+            ? { description: 'new issue / todo', action: { kind: 'submenu', title: 'new issue / todo', items: issueItems } }
+            : MENU_ACTIONS[id];
+        if (id === 'crtr.tmux.menu.issues' && issueItems.length === 0)
+            continue;
+        for (const gesture of bindings.gestures(id)) {
+            items.push({ description: entry.description, selector: menuSelector(gesture), action: entry.action });
+        }
+    }
+    return items;
+}
+function bindingAt(table, key) {
+    const result = tmux(['list-keys', '-T', table]);
+    if (!result.ok)
+        return null;
+    return result.stdout.split('\n').find((line) => {
+        const match = line.match(/^bind-key\s+(?:-r\s+)?-T\s+\S+\s+(\S+)\s+/);
+        return match?.[1] === key;
+    }) ?? null;
 }
-/** Bind Alt+C to the crouter action menu. Best-effort; false if tmux fails. */
-export function installMenuBinding() {
-    let prefixBinds;
+function sequenceTable(prefix) {
+    return `crtr-${Buffer.from(prefix).toString('hex')}`;
+}
+function readManifest() {
+    const option = tmux(['show-options', '-s', '-q', TMUX_BINDING_MANIFEST]);
+    if (!option.ok)
+        return null;
+    if (option.stdout === '')
+        return { pairs: [], existed: false };
+    const result = tmux(['show-options', '-s', '-qv', TMUX_BINDING_MANIFEST]);
+    if (!result.ok)
+        return null;
     try {
-        prefixBinds = readConfig('user').canvasNav.prefixBinds;
+        const value = JSON.parse(result.stdout);
+        if (!Array.isArray(value) || value.some((pair) => typeof pair !== 'object' || pair === null || typeof pair.table !== 'string' || typeof pair.key !== 'string'))
+            return null;
+        return { pairs: value, existed: true };
     }
     catch {
-        prefixBinds = defaultCanvasNavConfig().prefixBinds;
+        return null;
     }
-    const items = [];
-    for (const [key, bind] of Object.entries(prefixBinds)) {
-        if (key.length !== 1)
-            continue;
-        const desc = bind.desc ?? `chord ${key}`;
-        items.push({ key, desc, action: bind });
+}
+const LEGACY_ROOT_BINDINGS = [
+    { key: 'M-c', markers: ['display-menu', 'promote to orchestrator', 'crtr canvas chord', 'new issue / todo'] },
+    { key: 'M-]', markers: ['run-shell', 'crtr node cycle --dir next', "--pane '#{pane_id}'"] },
+    { key: 'M-[', markers: ['run-shell', 'crtr node cycle --dir prev', "--pane '#{pane_id}'"] },
+    { key: 'M-v', markers: ['switch-client', '-T crtr-view'] },
+];
+function adoptLegacyBindings() {
+    for (const legacy of LEGACY_ROOT_BINDINGS) {
+        const existing = bindingAt(ROOT_TABLE, legacy.key);
+        if (existing !== null && legacy.markers.every((marker) => existing.includes(marker))) {
+            tmux(['unbind-key', '-T', ROOT_TABLE, legacy.key]);
+        }
     }
-    return tmux(['bind-key', '-n', 'M-c', ...buildMenuArgs(' crtr ', items)]).ok;
 }
-// ---------------------------------------------------------------------------
-// Nav bindings — Alt+] / Alt+[ DFS-walk the canvas one window at a time. Each
-// key shells out to `crtr node cycle`, passing the active pane so the walk is
-// relative to the agent in front of you; cycle then swaps the next/prev node
-// into that pane (like `node focus`). Output is discarded so the keypress never
-// pops a results view. Installed at root boot alongside the Alt+C menu.
-// ---------------------------------------------------------------------------
-/** Bind Alt+] (forward) and Alt+[ (back) to the DFS canvas walk. Best-effort;
- *  false if either bind fails. NOTE: Alt+[ is only delivered cleanly when the
- *  terminal/tmux disambiguate it from a raw CSI introducer (`extended-keys on`).
- */
-export function installNavBindings() {
-    const next = tmux([
-        'bind-key', '-n', 'M-]', 'run-shell',
-        `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    const prev = tmux([
-        'bind-key', '-n', 'M-[', 'run-shell',
-        `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    return next && prev;
+function actionCommand(id) {
+    switch (id) {
+        case 'crtr.tmux.node.next': return ['run-shell', `crtr node cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.node.previous': return ['run-shell', `crtr node cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.view.next': return ['run-shell', `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`];
+        case 'crtr.tmux.view.previous': return ['run-shell', `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`];
+        default: throw new Error(`no tmux command for ${id}`);
+    }
 }
-// ---------------------------------------------------------------------------
-// View-nav bindings — Alt+V then ] / [ cycle the view hosted in a MONITOR pane
-// to the next/prev available view, in place. A VIEW-PREFIXED CHORD, not a bare
-// Alt pair: Alt+V switches into a private one-shot `crtr-view` key table, then
-// ] (next) / [ (prev) fire the cycle — mirroring node cycle's bracket DIRECTION
-// grammar (Alt+] next / Alt+[ prev) while NAMESPACING the brackets so they can
-// never shadow root bindings. This is collision-proof: only ONE root key (M-v)
-// is claimed, and bare Alt pairs are a minefield in real configs (e.g. Alt+,/. 
-// and Alt+]/.[ commonly bound to window/pane nav). The bracket lives in the
-// private table, so it also sidesteps the M-[ vs CSI-introducer ambiguity that
-// dogs installNavBindings' Alt+[. Each key shells surface-view cycle, passing the
-// active pane; cycle reads the pane's @crtr_view tag and respawns it on the
-// next/prev view. Output discarded so the keypress never pops a results view.
-// Installed at root boot alongside the node nav + Alt+C menu.
-//
-// NOTE: `M-v` is a GLOBAL root binding — it intercepts Alt+V in every pane/app
-// (e.g. swallowed from the pi editor), the same tradeoff crtr already takes for
-// M-c / M-] / M-[. Intended: crtr owns a small set of Alt chords server-wide.
-// ---------------------------------------------------------------------------
-/** Bind Alt+V → (], [) to the view-monitor cycle. `M-v` enters the private
- *  `crtr-view` key table (switch-client -T), then ] cycles next / [ cycles prev.
- *  Best-effort; false if any of the three binds fail. Deliberately distinct from
- *  installNavBindings' bare Alt+]/Alt+[ (node cycle): the two cycles coexist on
- *  the same server — brackets alone walk the node graph, Alt+V-then-bracket flips
- *  view monitors. The bracket keys are bound in the private table, so they NEVER
- *  shadow the user's root ]/[ and carry no CSI-introducer ambiguity. */
-export function installViewNavBindings() {
-    const enter = tmux([
-        'bind-key', '-n', 'M-v', 'switch-client', '-T', 'crtr-view',
-    ]).ok;
-    const next = tmux([
-        'bind-key', '-T', 'crtr-view', ']', 'run-shell',
-        `crtr surface view cycle --dir next --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    const prev = tmux([
-        'bind-key', '-T', 'crtr-view', '[', 'run-shell',
-        `crtr surface view cycle --dir prev --pane '#{pane_id}' >/dev/null 2>&1`,
-    ]).ok;
-    return enter && next && prev;
+/** Reconcile the tmux server with one immutable crouter binding snapshot. */
+export function installTmuxBindings(bindings = resolveUserKeybindings()) {
+    const diagnostics = [];
+    const installed = [];
+    const manifest = readManifest();
+    if (manifest === null) {
+        diagnostics.push({ code: 'tmux-error', message: `tmux is unavailable or ${TMUX_BINDING_MANIFEST} is malformed` });
+        return { ok: false, installed, diagnostics };
+    }
+    if (!manifest.existed)
+        adoptLegacyBindings();
+    for (const pair of manifest.pairs) {
+        const result = tmux(['unbind-key', '-T', pair.table, pair.key]);
+        if (!result.ok && bindingAt(pair.table, pair.key) !== null) {
+            diagnostics.push({ code: 'tmux-error', message: `could not remove crouter binding ${pair.table}:${pair.key}: ${result.stderr}` });
+        }
+    }
+    if (diagnostics.some((diagnostic) => diagnostic.code === 'tmux-error')) {
+        return { ok: false, installed, diagnostics };
+    }
+    const install = (table, key, command, id, gesture) => {
+        if (bindingAt(table, key) !== null) {
+            diagnostics.push({ code: 'occupied', bindingId: id, gesture, message: `${table}:${key} is already bound by tmux; ${id} was not installed` });
+            return false;
+        }
+        const result = tmux(['bind-key', '-T', table, key, ...command]);
+        if (!result.ok) {
+            diagnostics.push({ code: 'tmux-error', bindingId: id, gesture, message: `could not install ${id}: ${result.stderr}` });
+            return false;
+        }
+        installed.push({ table, key });
+        return true;
+    };
+    const menuCommand = buildMenuArgs(' crtr ', menuItems(bindings));
+    for (const gesture of bindings.gestures('crtr.tmux.menu.open')) {
+        install(ROOT_TABLE, tmuxKey(gesture), menuCommand, 'crtr.tmux.menu.open', gesture);
+    }
+    for (const id of ['crtr.tmux.node.next', 'crtr.tmux.node.previous']) {
+        for (const gesture of bindings.gestures(id))
+            install(ROOT_TABLE, tmuxKey(gesture), actionCommand(id), id, gesture);
+    }
+    const sequences = new Map();
+    for (const id of ['crtr.tmux.view.next', 'crtr.tmux.view.previous']) {
+        for (const gesture of bindings.gestures(id)) {
+            const [first, second] = gesture.split(' > ');
+            const prefix = tmuxKey(first);
+            const entries = sequences.get(prefix) ?? [];
+            entries.push({ id, gesture, second: tmuxKey(second) });
+            sequences.set(prefix, entries);
+        }
+    }
+    for (const [prefix, entries] of sequences) {
+        if (bindingAt(ROOT_TABLE, prefix) !== null) {
+            for (const entry of entries)
+                diagnostics.push({ code: 'occupied', bindingId: entry.id, gesture: entry.gesture, message: `${ROOT_TABLE}:${prefix} is already bound by tmux; ${entry.id} was not installed` });
+            continue;
+        }
+        const table = sequenceTable(prefix);
+        let children = 0;
+        for (const entry of entries)
+            if (install(table, entry.second, actionCommand(entry.id), entry.id, entry.gesture))
+                children++;
+        if (children > 0)
+            install(ROOT_TABLE, prefix, ['switch-client', '-T', table], entries[0].id, entries[0].gesture);
+    }
+    const save = tmux(['set-option', '-s', TMUX_BINDING_MANIFEST, JSON.stringify(installed)]);
+    if (!save.ok)
+        diagnostics.push({ code: 'tmux-error', message: `could not save crouter tmux ownership manifest: ${save.stderr}` });
+    return { ok: diagnostics.every((diagnostic) => diagnostic.code !== 'tmux-error'), installed, diagnostics };
 }

package/dist/core/tui/__tests__/host-keybindings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/tui/__tests__/host-keybindings.test.js

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { resolveKeybindings } from '../../keybindings/index.js';
+import { matchViewBinding, matchesViewHostBinding, parseViewKeypress, resolveViewKeyHints } from '../host.js';
+function key(input = '', patch = {}) {
+    return {
+        upArrow: false,
+        downArrow: false,
+        leftArrow: false,
+        rightArrow: false,
+        return: false,
+        escape: false,
+        ctrl: false,
+        meta: false,
+        tab: false,
+        shiftTab: false,
+        backspace: false,
+        ...patch,
+    };
+}
+test('catalog view bindings use defaults, remaps, and effective hint labels', () => {
+    const keymap = [
+        { bindingId: 'crtr.view.canvas.down', intent: 'down', hint: { label: 'move' } },
+    ];
+    const defaults = resolveKeybindings();
+    assert.deepEqual(matchViewBinding(keymap, defaults, 'j', key('j'), { row: 0 }), { intent: 'down', payload: undefined });
+    assert.deepEqual(resolveViewKeyHints(keymap, defaults, { row: 0 }), [{ keys: 'J / Down', label: 'move' }]);
+    const remapped = resolveKeybindings({ 'crtr.view.canvas.down': ['x'] });
+    assert.equal(matchViewBinding(keymap, remapped, 'j', key('j'), { row: 0 }), null);
+    assert.deepEqual(matchViewBinding(keymap, remapped, 'x', key('x'), { row: 0 }), { intent: 'down', payload: undefined });
+    assert.deepEqual(resolveViewKeyHints(keymap, remapped, { row: 0 }), [{ keys: 'X', label: 'move' }]);
+});
+test('custom view literals retain their matching and presenter-authored hints', () => {
+    const keymap = [
+        { keys: ['z'], intent: 'custom', hint: { keys: 'z', label: 'custom' } },
+    ];
+    const bindings = resolveKeybindings();
+    assert.deepEqual(matchViewBinding(keymap, bindings, 'z', key('z'), undefined), { intent: 'custom', payload: undefined });
+    assert.equal(matchViewBinding(keymap, bindings, 'x', key('x'), undefined), null);
+    assert.deepEqual(resolveViewKeyHints(keymap, bindings, undefined), [{ keys: 'z', label: 'custom' }]);
+});
+test('Alt+<letter> does not falsely match a bare custom literal', () => {
+    const keymap = [{ keys: ['q'], intent: 'quit' }];
+    const bindings = resolveKeybindings();
+    const altQ = parseViewKeypress(Buffer.from('\x1bq'));
+    assert.equal(matchViewBinding(keymap, bindings, altQ.input, altQ.key, undefined, altQ.raw), null);
+    const q = parseViewKeypress(Buffer.from('q'));
+    assert.deepEqual(matchViewBinding(keymap, bindings, q.input, q.key, undefined, q.raw), { intent: 'quit', payload: undefined });
+});
+test('host force quit and capture deletion follow catalog IDs through raw terminal decoding', () => {
+    const defaults = resolveKeybindings();
+    const ctrlC = parseViewKeypress(Buffer.from('\x03'));
+    const del = parseViewKeypress(Buffer.from('\x7f'), defaults);
+    const bs = parseViewKeypress(Buffer.from('\b'), defaults);
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.force-quit', ctrlC.raw));
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', del.raw));
+    // 0x08 stays Backspace under default config so ^H-erase terminals still delete.
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', bs.raw));
+    const remapped = resolveKeybindings({
+        'crtr.view.host.force-quit': ['alt+x'],
+        'crtr.view.host.editor.backspace': ['ctrl+h'],
+    });
+    const altX = parseViewKeypress(Buffer.from('\x1bx'), remapped);
+    const ctrlH = parseViewKeypress(Buffer.from('\b'), remapped);
+    const delRemap = parseViewKeypress(Buffer.from('\x7f'), remapped);
+    assert.equal(matchesViewHostBinding(remapped, 'crtr.view.host.force-quit', ctrlC.raw), false);
+    assert.ok(matchesViewHostBinding(remapped, 'crtr.view.host.force-quit', altX.raw));
+    // With deletion remapped to Ctrl-H, the 0x08 byte deletes and DEL no longer does.
+    assert.equal(matchesViewHostBinding(remapped, 'crtr.view.host.editor.backspace', delRemap.raw), false);
+    assert.ok(matchesViewHostBinding(remapped, 'crtr.view.host.editor.backspace', ctrlH.raw));
+});
+test('Alt+Backspace deletes like Backspace under default config', () => {
+    const defaults = resolveKeybindings();
+    const altDel = parseViewKeypress(Buffer.from('\x1b\x7f'), defaults);
+    const altBs = parseViewKeypress(Buffer.from('\x1b\b'), defaults);
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', altDel.raw));
+    assert.ok(matchesViewHostBinding(defaults, 'crtr.view.host.editor.backspace', altBs.raw));
+});
+test('raw terminal decoding covers modified arrows and enter/return equivalence', () => {
+    const keymap = [{ bindingId: 'crtr.view.settings.edit-or-submit', intent: 'submit' }];
+    const bindings = resolveKeybindings();
+    const cr = parseViewKeypress(Buffer.from('\r'));
+    const lf = parseViewKeypress(Buffer.from('\n'));
+    assert.deepEqual(matchViewBinding(keymap, bindings, cr.input, cr.key, undefined, cr.raw), { intent: 'submit', payload: undefined });
+    assert.deepEqual(matchViewBinding(keymap, bindings, lf.input, lf.key, undefined, lf.raw), { intent: 'submit', payload: undefined });
+    const ctrlUp = parseViewKeypress(Buffer.from('\x1b[1;5A'));
+    assert.equal(ctrlUp.raw.upArrow, true);
+    assert.equal(ctrlUp.raw.ctrl, true);
+    const up = parseViewKeypress(Buffer.from('\x1b[A'));
+    assert.equal(up.raw.upArrow, true);
+    assert.equal(up.raw.ctrl, false);
+});
+test('a disabled binding neither matches nor renders a hint', () => {
+    const keymap = [
+        { bindingId: 'crtr.view.canvas.refresh', intent: 'refresh', hint: { label: 'refresh' } },
+    ];
+    const bindings = resolveKeybindings({ 'crtr.view.canvas.refresh': [] });
+    const g = parseViewKeypress(Buffer.from('g'));
+    assert.equal(matchViewBinding(keymap, bindings, g.input, g.key, undefined, g.raw), null);
+    assert.deepEqual(resolveViewKeyHints(keymap, bindings, undefined), []);
+});
+test('capture hints are host-owned, mode-gated, and keep custom KeyHint keys verbatim', () => {
+    const gated = [
+        { capture: 'setDraft', when: (state) => state.compose, hint: { label: 'compose' } },
+    ];
+    assert.deepEqual(resolveViewKeyHints(gated, resolveKeybindings(), { compose: true }), [{ keys: 'type', label: 'compose' }]);
+    assert.deepEqual(resolveViewKeyHints(gated, resolveKeybindings(), { compose: false }), []);
+    const custom = [
+        { capture: 'setDraft', when: () => true, hint: { keys: 'edit', label: 'compose' } },
+    ];
+    assert.deepEqual(resolveViewKeyHints(custom, resolveKeybindings(), undefined), [{ keys: 'edit', label: 'compose' }]);
+});

package/dist/core/tui/host.d.ts

@@ -1,5 +1,7 @@
+import { type Key } from './terminal.js';
 import { type Draw, type Rect, type Size } from './draw.js';
-import type { ViewCore, TuiPresenter, TextPresenter, KeyHint, BannerLevel } from '../view/contract.js';
+import type { ViewCore, TuiPresenter, TextPresenter, KeyBinding, KeyHint, BannerLevel } from '../view/contract.js';
+import { type BindingId, type BindingResolution, type RawTerminalInput } from '../keybindings/index.js';
 export interface RunViewOptions {
     /** CLI flags forwarded verbatim to the view via host.options. */
     options?: Record<string, string>;
@@ -32,6 +34,33 @@ export interface ChromeManifest {
  *  on the row above it when set. */
 declare function drawChrome(draw: Draw, size: Size, manifest: ChromeManifest, c: Chrome, now?: number): Rect;
 export { drawChrome };
+/** Tokens a keystroke can match a keymap binding's `keys` against. Arrows →
+ *  up/down/left/right, return → return|enter, escape → escape|esc, a printable
+ *  char → the char itself (+ 'space' for ' '), ctrl+x → ctrl+x|c-x. */
+export interface ViewKeypress {
+    readonly input: string;
+    readonly key: Key;
+    readonly raw: RawTerminalInput;
+}
+/** Extend the shared legacy parser with the terminal gestures the catalog can
+ * express. The raw shape goes only to the catalog matcher; custom literals keep
+ * their established Key-based matching. When `bindings` is supplied the ambiguous
+ * 0x08 byte resolves to Ctrl-H only if an effective binding claims it. */
+export declare function parseViewKeypress(data: Buffer, bindings?: BindingResolution<BindingId>): ViewKeypress;
+/** Resolve footer hints for the CURRENT state: only bindings whose `when(state)`
+ * passes contribute, so mode-gated affordances (compose/react send/cancel/pick)
+ * appear exactly while active. Catalog bindings render the effective key label
+ * (omitted entirely when disabled); custom-view literal hints stay verbatim. */
+export declare function resolveViewKeyHints<S>(keymap: KeyBinding<S>[], bindings: BindingResolution<BindingId>, state: S): KeyHint[];
+/** The first non-capture binding whose key matches and whose `when` (if any)
+ * passes — catalog IDs use the terminal matcher; custom literals retain their
+ * presenter-authored matching. */
+export declare function matchViewBinding<S>(keymap: KeyBinding<S>[], bindings: BindingResolution<BindingId>, input: string, key: Key, state: S, raw?: RawTerminalInput): {
+    intent: string;
+    payload: unknown;
+} | null;
+/** Match a host-owned generic-view action through the same catalog snapshot. */
+export declare function matchesViewHostBinding(bindings: BindingResolution<BindingId>, id: 'crtr.view.host.force-quit' | 'crtr.view.host.editor.backspace', raw: RawTerminalInput): boolean;
 /** Host a dual-target ViewCore + TuiPresenter in the alt screen until it quits
  *  (or Ctrl-C). `text` is the optional text presenter for the piped path. */
 export declare function runCoreView<S>(core: ViewCore<S>, tui: TuiPresenter<S>, text: TextPresenter<S> | null, opts?: RunViewOptions): Promise<void>;