Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

39.0 KB
Raw Blame
/**
 * The keybinding registry + engine, shared by main, renderer, and the Server Edition bridge.
 * Registry, validation, effective-binding resolution, conflict detection, override
 * sanitization, and the pure event→command resolver all live in this one module so the
 * dispatchers, Settings UI, and ShortcutsPanel cannot drift apart. Builds on shortcut.ts —
 * canonical binding strings are shortcut.ts strings (`Cmd` = abstract primary modifier,
 * `Ctrl` = literal Control, modifier-only chords = hold-to-talk).
 */
import { AGENT_CONFIG } from './agents/config'
import {
  parseShortcut,
  serializeShortcut,
  resolvedModifiers,
  matchesShortcut,
  isHoldChord
} from './shortcut'
import type { ShortcutKeyEvent } from './shortcut'

/** `board` = fires only while a kanban board is up (the inverse of `canvas`), and never while
 *  typing or in a terminal — which is what lets its defaults be bare keys (J/K/Space/arrows). */
export type CommandScope = 'app' | 'canvas' | 'board' | 'terminal' | 'scm'
export type CommandGroup =
  | 'General'
  | 'Canvas'
  | 'Nodes'
  | 'Board'
  | 'Terminal'
  | 'Source Control'
  | 'Speech'

export interface CommandDefinition {
  id: CommandId
  /** English row label for ShortcutsPanel and the Settings section. */
  title: string
  group: CommandGroup
  scope: CommandScope
  /** Canonical shortcut.ts strings. `other` covers linux + win32 — widen to three buckets
   *  only when a real default needs to differ between them. Empty array = unassigned. */
  defaultBindings: { darwin: readonly string[]; other: readonly string[] }
  /** May fire while a real input/textarea/contentEditable is focused (xterm excluded). */
  allowWhileTyping?: boolean
  /** May fire while an xterm has focus. Scope 'terminal' implies it. */
  allowInTerminal?: boolean
  /** Permits modifier-less bindings, restricted to SAFE_BARE_KEYS. */
  allowBareKey?: boolean
  /** Permits modifier-only hold chords (hold-to-talk). */
  allowHoldChord?: boolean
}

export type CommandId =
  | 'app.commandPalette'
  | 'app.settings'
  | 'app.shortcutsPanel'
  | 'view.kanbanToggle'
  | 'view.globalKanbanToggle'
  | 'view.focusMode'
  | 'panel.explorer'
  | 'panel.sourceControl'
  | 'panel.sessions'
  | 'app.reopenLastClosed'
  | 'project.next'
  | 'project.prev'
  | 'canvas.undo'
  | 'canvas.redo'
  | 'canvas.goBack'
  | 'canvas.goForward'
  | 'canvas.deleteSelection'
  | 'canvas.fitAll'
  | 'canvas.tidy'
  | 'canvas.tidyLineage'
  | 'canvas.toggleLock'
  | 'canvas.groupSelection'
  | 'node.newTerminal'
  | 'node.newAgent'
  // Per-builtin-agent creates. The seven ids are spelled STATICALLY (never derived from
  // BUILTIN_AGENT_IDS) so this union stays literal — `isCommandId`, the overrides map and the
  // handler table all depend on that.
  | 'node.newAgent.claude'
  | 'node.newAgent.codex'
  | 'node.newAgent.gemini'
  | 'node.newAgent.opencode'
  | 'node.newAgent.grok'
  | 'node.newAgent.copilot'
  | 'node.newAgent.antigravity'
  | 'node.newAgent.cursor'
  | 'node.newSticky'
  | 'node.newBrowser'
  | 'node.newWebView'
  | 'node.newDino'
  | 'node.newWhiteboard'
  | 'node.newFile'
  | 'node.focusLeft'
  | 'node.focusRight'
  | 'node.focusUp'
  | 'node.focusDown'
  | 'node.nextNeedingYou'
  | 'node.maximize'
  | 'node.zoneLeft'
  | 'node.zoneRight'
  | 'node.zoneUp'
  | 'node.zoneDown'
  | 'node.zoneLeftThird'
  | 'node.zoneCenterThird'
  | 'node.zoneRightThird'
  | 'node.zoneTopLeft'
  | 'node.zoneTopRight'
  | 'node.zoneBottomLeft'
  | 'node.zoneBottomRight'
  | 'node.close'
  | 'node.toggleMarkdown'
  | 'board.openCard'
  | 'board.nextCard'
  | 'board.prevCard'
  | 'board.columnLeft'
  | 'board.columnRight'
  | 'terminal.find'
  | 'terminal.copySelection'
  | 'scm.commit'
  | 'speech.dictation'

/** Same defaults on every platform. */
const both = (...bindings: string[]): { darwin: string[]; other: string[] } => ({
  darwin: bindings,
  other: [...bindings]
})

export const COMMAND_DEFINITIONS: readonly CommandDefinition[] = [
  // General — the Canvas.tsx:4491 block today; fires while an xterm has focus, and (bug,
  // fixed in the dispatch PR) also while typing. allowWhileTyping is deliberately absent.
  { id: 'app.commandPalette', title: 'Command palette', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+K'), allowInTerminal: true },
  { id: 'app.settings', title: 'Open settings', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+Comma'), allowInTerminal: true },
  { id: 'app.shortcutsPanel', title: 'Keyboard shortcuts panel', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+Slash'), allowInTerminal: true },
  { id: 'view.kanbanToggle', title: 'Toggle kanban board', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+Shift+B'), allowInTerminal: true },
  { id: 'view.globalKanbanToggle', title: 'Toggle global kanban (Omni)', group: 'General', scope: 'app',
    defaultBindings: both(), allowInTerminal: true },
  // Focus mode fills the window with one node — most naturally invoked from INSIDE the terminal
  // being enlarged, hence allowInTerminal. Scope stays 'canvas': over the kanban board or while
  // typing in an input there is no node geometry for the toggle to act on (the pre-registry
  // hardcoded chord fired in both places; the registry gating is the fix, not a regression).
  { id: 'view.focusMode', title: 'Toggle focus mode', group: 'General', scope: 'canvas',
    defaultBindings: both('Cmd+Shift+F'), allowInTerminal: true },
  { id: 'panel.explorer', title: 'Toggle explorer panel', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+Shift+E'), allowInTerminal: true },
  { id: 'panel.sourceControl', title: 'Toggle source control panel', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+Shift+G'), allowInTerminal: true },
  { id: 'panel.sessions', title: 'Pin sessions sidebar', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+Shift+L'), allowInTerminal: true },
  { id: 'app.reopenLastClosed', title: 'Reopen last closed', group: 'General', scope: 'app',
    defaultBindings: both('Cmd+Shift+T'), allowInTerminal: true },
  // Chrome's tab-cycling chords, on the project tab strip. `Ctrl` is the LITERAL Control key on
  // every platform (mac included — ⌘Tab is the OS app switcher), which is also what Chrome uses.
  // allowWhileTyping + allowInTerminal: like the browser's, it switches from wherever focus is —
  // Ctrl+Tab types nothing in an input and xterm has no use for it. A browser reserves both
  // chords for its own tabs and never delivers them to the page, so in the Server Edition these
  // only fire once rebound.
  { id: 'project.next', title: 'Next project tab', group: 'General', scope: 'app',
    defaultBindings: both('Ctrl+Tab'), allowInTerminal: true, allowWhileTyping: true },
  { id: 'project.prev', title: 'Previous project tab', group: 'General', scope: 'app',
    defaultBindings: both('Ctrl+Shift+Tab'), allowInTerminal: true, allowWhileTyping: true },

  // Canvas — inert while the kanban board is open (scope 'canvas'), blocked while typing.
  { id: 'canvas.undo', title: 'Undo', group: 'Canvas', scope: 'canvas',
    defaultBindings: both('Cmd+Z') },
  { id: 'canvas.redo', title: 'Redo', group: 'Canvas', scope: 'canvas',
    defaultBindings: { darwin: ['Cmd+Shift+Z'], other: ['Cmd+Shift+Z', 'Cmd+Y'] } },
  // Camera history (breadcrumb trail), not node-array history: `[` / `]` are the literal keys
  // `e.key` reports, which is what the resolver compares against — `BracketLeft`/`BracketRight`
  // are `KeyboardEvent.code` values and would never match (shortcut.ts's KEY_ALIASES covers only
  // Comma/Slash/Period, so brackets have no word-form spelling here). Off-mac the binding is
  // Ctrl+[, which terminals read as ESC — safe here because scope 'canvas' without
  // allowWhileTyping means the resolver refuses it whenever a terminal or input has focus.
  { id: 'canvas.goBack', title: 'Go back', group: 'Canvas', scope: 'canvas',
    defaultBindings: both('Cmd+[') },
  { id: 'canvas.goForward', title: 'Go forward', group: 'Canvas', scope: 'canvas',
    defaultBindings: both('Cmd+]') },
  { id: 'canvas.deleteSelection', title: 'Delete selection', group: 'Canvas', scope: 'canvas',
    // Mirrors the current platform-blind handler; the typing guard keeps Backspace safe.
    defaultBindings: both('Delete', 'Backspace'),
    allowBareKey: true },
  { id: 'canvas.fitAll', title: 'Fit all nodes in view', group: 'Canvas', scope: 'canvas',
    defaultBindings: both() },
  { id: 'canvas.tidy', title: 'Tidy canvas', group: 'Canvas', scope: 'canvas',
    // arrangeAllNodes self-guards (kanban open, <2 top-level nodes), same as the ⌘K/menu entries.
    defaultBindings: both('Cmd+Shift+A') },
  { id: 'canvas.tidyLineage', title: 'Arrange by lineage', group: 'Canvas', scope: 'canvas',
    // Ships unbound: it is the second tidy, and Cmd+Shift+A is already the first. Self-guards
    // exactly like arrangeAllNodes (kanban open, <2 top-level nodes, no usable rope).
    defaultBindings: both() },
  { id: 'canvas.groupSelection', title: 'Group selection', group: 'Canvas', scope: 'canvas',
    defaultBindings: both() },
  { id: 'canvas.toggleLock', title: 'Toggle canvas lock', group: 'Canvas', scope: 'canvas',
    // Ships unbound (issue #1130): the obvious chord, Cmd+Shift+L, is the sessions sidebar's.
    // Not allowInTerminal — a focused terminal keeps the chord, like every canvas command.
    defaultBindings: both() },

  // Nodes
  { id: 'node.newTerminal', title: 'New terminal node', group: 'Nodes', scope: 'canvas',
    defaultBindings: both('Cmd+T') },
  { id: 'node.newAgent', title: 'New agent node', group: 'Nodes', scope: 'canvas',
    // Non-mac note: Ctrl+Shift+C is a common terminal-copy convention; kept for parity
    // with current behavior, revisit with telemetry.
    defaultBindings: both('Cmd+Shift+C') },
  // Every command below ships UNBOUND on purpose: they expand the remappable POOL, and a chord
  // nobody asked for would either shadow an existing default or steal a key from the terminal.
  // The user assigns them in Settings → Keyboard Shortcuts; titles come from AGENT_CONFIG so a
  // relabelled agent cannot drift from its row.
  { id: 'node.newAgent.claude', title: `New ${AGENT_CONFIG.claude.label} node`, group: 'Nodes',
    scope: 'canvas', defaultBindings: both() },
  { id: 'node.newAgent.codex', title: `New ${AGENT_CONFIG.codex.label} node`, group: 'Nodes',
    scope: 'canvas', defaultBindings: both() },
  { id: 'node.newAgent.gemini', title: `New ${AGENT_CONFIG.gemini.label} node`, group: 'Nodes',
    scope: 'canvas', defaultBindings: both() },
  { id: 'node.newAgent.opencode', title: `New ${AGENT_CONFIG.opencode.label} node`, group: 'Nodes',
    scope: 'canvas', defaultBindings: both() },
  { id: 'node.newAgent.grok', title: `New ${AGENT_CONFIG.grok.label} node`, group: 'Nodes',
    scope: 'canvas', defaultBindings: both() },
  { id: 'node.newAgent.copilot', title: `New ${AGENT_CONFIG.copilot.label} node`, group: 'Nodes',
    scope: 'canvas', defaultBindings: both() },
  { id: 'node.newAgent.antigravity', title: `New ${AGENT_CONFIG.antigravity.label} node`,
    group: 'Nodes', scope: 'canvas', defaultBindings: both() },
  { id: 'node.newAgent.cursor', title: `New ${AGENT_CONFIG.cursor.label} node`, group: 'Nodes',
    scope: 'canvas', defaultBindings: both() },
  { id: 'node.newSticky', title: 'New sticky note', group: 'Nodes', scope: 'canvas',
    defaultBindings: both() },
  { id: 'node.newBrowser', title: 'New browser node', group: 'Nodes', scope: 'canvas',
    defaultBindings: both() },
  { id: 'node.newWebView', title: 'New web view node', group: 'Nodes', scope: 'canvas',
    defaultBindings: both() },
  { id: 'node.newDino', title: 'New dino node', group: 'Nodes', scope: 'canvas',
    defaultBindings: both() },
  { id: 'node.newWhiteboard', title: 'New whiteboard', group: 'Nodes', scope: 'canvas',
    defaultBindings: both() },
  { id: 'node.newFile', title: 'New file…', group: 'Nodes', scope: 'canvas',
    defaultBindings: both() },

  // Directional focus, the multiplexer gesture (Ghostty goto_split, tmux select-pane -L). Two
  // flags carry the whole point: scope 'canvas' because there is no geometry to walk on the
  // board, and allowInTerminal because the hand that wants to move is already typing in a
  // terminal — without it the gesture only works from the one place you don't need it.
  //
  // The non-mac default is NOT Ctrl+Arrow (what `both('Cmd+ArrowLeft')` would resolve to):
  // Ctrl+Arrow is readline's word-jump, and allowInTerminal would steal it from every shell on
  // Linux and Windows. Ctrl+Alt+Arrow is out for a different reason — the speech.dictation
  // default is the modifier-only chord 'Cmd+Alt', which on those platforms is Ctrl+Alt held, so
  // the hold listener would start recording on the way to an arrow. Ctrl+Shift+Arrow is what is
  // left that no shell and no other command already owns.
  { id: 'node.focusLeft', title: 'Focus node to the left', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Cmd+ArrowLeft'], other: ['Ctrl+Shift+ArrowLeft'] },
    allowInTerminal: true },
  { id: 'node.focusRight', title: 'Focus node to the right', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Cmd+ArrowRight'], other: ['Ctrl+Shift+ArrowRight'] },
    allowInTerminal: true },
  { id: 'node.focusUp', title: 'Focus node above', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Cmd+ArrowUp'], other: ['Ctrl+Shift+ArrowUp'] },
    allowInTerminal: true },
  { id: 'node.focusDown', title: 'Focus node below', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Cmd+ArrowDown'], other: ['Ctrl+Shift+ArrowDown'] },
    allowInTerminal: true },
  // Travel to the agent that has waited longest for you (waiting/blocked), across projects; each
  // press steps to the next one, without going through the sidebar. Ships UNBOUND — every obvious chord already has an owner, and a default
  // would steal it from a user who never asked. Scope 'canvas' + allowInTerminal for the
  // node.focus* reason: the hand that wants to move is in a terminal, and over the kanban board
  // there is no canvas to land on. The queue is built on demand per press (lib/nextNeedingYou).
  { id: 'node.nextNeedingYou', title: 'Go to next agent needing you', group: 'Nodes',
    scope: 'canvas', defaultBindings: both(), allowInTerminal: true },
  // The header maximize toggle's chord (issue #399): fill the viewport with the node under the
  // keyboard (else the single selected node), or restore it. allowInTerminal for focus-mode's
  // reason — the hand that wants more rows is already typing in the terminal being enlarged.
  // ⌘⇧Enter is iTerm2's maximize-pane chord — the same gesture terminal users already know —
  // and collides with nothing here (scm.commit's ⌘Enter is a different chord, scm scope).
  { id: 'node.maximize', title: 'Maximize / restore node', group: 'Nodes', scope: 'canvas',
    defaultBindings: both('Cmd+Shift+Enter'), allowInTerminal: true },
  // Zone snap (issue #394 v1): send the node under the keyboard (else the single selected one)
  // into a half of the visible canvas — the Rectangle/Magnet ⌃⌥arrow idiom, which is why the mac
  // default is Ctrl+Alt (literal Control, not Cmd). Off-mac the halves ship UNBOUND: Ctrl+Alt+Arrow
  // would trip the speech.dictation hold chord there ('Cmd+Alt' resolves to Ctrl+Alt held — the
  // exact trap the node.focus* comment documents), and Ctrl+Shift+Arrow is those focus commands.
  { id: 'node.zoneLeft', title: 'Snap node to left half', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Ctrl+Alt+ArrowLeft'], other: [] }, allowInTerminal: true },
  { id: 'node.zoneRight', title: 'Snap node to right half', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Ctrl+Alt+ArrowRight'], other: [] }, allowInTerminal: true },
  { id: 'node.zoneUp', title: 'Snap node to top half', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Ctrl+Alt+ArrowUp'], other: [] }, allowInTerminal: true },
  { id: 'node.zoneDown', title: 'Snap node to bottom half', group: 'Nodes', scope: 'canvas',
    defaultBindings: { darwin: ['Ctrl+Alt+ArrowDown'], other: [] }, allowInTerminal: true },
  // Thirds and quarters (issue #1169): the rest of the zone list, same rules as the halves, but
  // shipped UNBOUND on every platform. There is no free chord family left for seven more zones
  // (Ctrl+Alt+Arrow is the halves', Ctrl+Shift+Arrow and Cmd+Arrow are focus), and a default here
  // would steal a key from somebody's shell via allowInTerminal. The user binds the ones they use.
  { id: 'node.zoneLeftThird', title: 'Snap node to left third', group: 'Nodes', scope: 'canvas',
    defaultBindings: both(), allowInTerminal: true },
  { id: 'node.zoneCenterThird', title: 'Snap node to center third', group: 'Nodes', scope: 'canvas',
    defaultBindings: both(), allowInTerminal: true },
  { id: 'node.zoneRightThird', title: 'Snap node to right third', group: 'Nodes', scope: 'canvas',
    defaultBindings: both(), allowInTerminal: true },
  { id: 'node.zoneTopLeft', title: 'Snap node to top left quarter', group: 'Nodes', scope: 'canvas',
    defaultBindings: both(), allowInTerminal: true },
  { id: 'node.zoneTopRight', title: 'Snap node to top right quarter', group: 'Nodes', scope: 'canvas',
    defaultBindings: both(), allowInTerminal: true },
  { id: 'node.zoneBottomLeft', title: 'Snap node to bottom left quarter', group: 'Nodes', scope: 'canvas',
    defaultBindings: both(), allowInTerminal: true },
  { id: 'node.zoneBottomRight', title: 'Snap node to bottom right quarter', group: 'Nodes', scope: 'canvas',
    defaultBindings: both(), allowInTerminal: true },
  // Main-process intercepted today (unconditional): keep firing everywhere.
  { id: 'node.close', title: 'Close node / window', group: 'Nodes', scope: 'app',
    defaultBindings: both('Cmd+W'), allowInTerminal: true, allowWhileTyping: true },
  { id: 'node.toggleMarkdown', title: 'Toggle markdown view', group: 'Nodes', scope: 'app',
    defaultBindings: both('Cmd+M'), allowInTerminal: true, allowWhileTyping: true },

  // Board — the kanban board's keyboard. Scope 'board' resolves only while a board is up, and none
  // of these carries allowWhileTyping or allowInTerminal: the comment box, a rename field and the
  // card modal's terminal keep every key they are typed into. That refusal is the whole reason a
  // bare letter is acceptable here (see `normalizeBindingForCommand`). Inside the card modal
  // next/previous step the modal to the neighbouring card. The handler DECLINES (falling through
  // to the platform) whenever the focused control owns the key — Space on a focused button, any
  // key in a <select> — see KanbanView's board-key handler.
  { id: 'board.openCard', title: 'Open focused card', group: 'Board', scope: 'board',
    defaultBindings: both('Space') },
  { id: 'board.nextCard', title: 'Next card', group: 'Board', scope: 'board',
    defaultBindings: both('J', 'ArrowDown') },
  { id: 'board.prevCard', title: 'Previous card', group: 'Board', scope: 'board',
    defaultBindings: both('K', 'ArrowUp') },
  { id: 'board.columnLeft', title: 'Card in the column to the left', group: 'Board', scope: 'board',
    defaultBindings: both('ArrowLeft') },
  { id: 'board.columnRight', title: 'Card in the column to the right', group: 'Board', scope: 'board',
    defaultBindings: both('ArrowRight') },

  // Terminal
  { id: 'terminal.find', title: 'Find in terminal', group: 'Terminal', scope: 'terminal',
    defaultBindings: both('Cmd+F') },
  { id: 'terminal.copySelection', title: 'Copy terminal selection', group: 'Terminal',
    scope: 'terminal',
    // Plain Ctrl+C stays SIGINT off-mac; Cmd+Shift+C resolves to Ctrl+Shift+C there.
    defaultBindings: { darwin: ['Cmd+C'], other: ['Cmd+Shift+C', 'Ctrl+Insert'] } },

  // Source control (local handler; registry supplies label + remap)
  { id: 'scm.commit', title: 'Commit', group: 'Source Control', scope: 'scm',
    defaultBindings: both('Cmd+Enter'), allowWhileTyping: true },

  // Speech — the migrated dictation chord; hold-to-talk by default.
  { id: 'speech.dictation', title: 'Dictate', group: 'Speech', scope: 'app',
    defaultBindings: both('Cmd+Alt'),
    allowHoldChord: true, allowInTerminal: true, allowWhileTyping: true }
]

export const COMMANDS_BY_ID: ReadonlyMap<CommandId, CommandDefinition> = new Map(
  COMMAND_DEFINITIONS.map((d) => [d.id, d])
)

export function isCommandId(v: string): v is CommandId {
  return COMMANDS_BY_ID.has(v as CommandId)
}

/** Modifier-less keys that are safe to bind bare — they don't type a character. */
export const SAFE_BARE_KEYS: ReadonlySet<string> = new Set([
  'DELETE', 'BACKSPACE', 'ESCAPE', 'ENTER', 'TAB',
  'ARROWUP', 'ARROWDOWN', 'ARROWLEFT', 'ARROWRIGHT', 'PAGEUP', 'PAGEDOWN',
  'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12'
])

export type NormalizedBinding = { ok: true; value: string } | { ok: false; error: string }

/** Parse + validate one binding string against a command's flags; returns the canonical
 *  serialized form on success. The single validation path for defaults (pinned by a registry
 *  test), Settings-recorder captures, and hand-edited settings.json overrides. */
export function normalizeBindingForCommand(
  def: CommandDefinition,
  raw: string,
  isMac: boolean
): NormalizedBinding {
  const p = parseShortcut(raw)
  const hasAnyToken = p.cmd || p.ctrl || p.alt || p.shift || p.key !== null
  if (!hasAnyToken) return { ok: false, error: 'Use a shortcut like Cmd+K or Cmd+Shift+P.' }
  if (!isMac && p.cmd && p.ctrl) {
    return { ok: false, error: 'Cmd already means Ctrl on this platform; use one of them.' }
  }
  if (p.key === null) {
    if (!def.allowHoldChord) {
      return { ok: false, error: 'This command needs a key, not a modifier-only chord.' }
    }
    if (!p.cmd && !p.ctrl && !p.alt) {
      return { ok: false, error: 'A hold chord needs at least one non-shift modifier.' }
    }
    return { ok: true, value: serializeShortcut(p) }
  }
  const hasStrongModifier = p.cmd || p.ctrl || p.alt
  // A board command never fires while typing or in a terminal (the resolver refuses both for its
  // scope, and no board row may opt out of that), so a bare letter or Space there cannot steal a
  // character from anyone — it is a board key, not text.
  if (!hasStrongModifier && def.scope !== 'board') {
    if (p.shift) return { ok: false, error: 'Shift-only shortcuts would steal typed text.' }
    if (!def.allowBareKey || !SAFE_BARE_KEYS.has(p.key)) {
      return { ok: false, error: 'Include a modifier key.' }
    }
  }
  return { ok: true, value: serializeShortcut(p) }
}

/** User overrides, as stored in settings.json under `keybindings`. Absent id = defaults;
 *  `[]` = disabled. */
export type KeybindingOverrides = Partial<Record<CommandId, readonly string[]>>

export function getEffectiveBindings(
  id: CommandId,
  overrides: KeybindingOverrides,
  isMac: boolean
): readonly string[] {
  const override = overrides[id]
  if (override !== undefined) return override
  const def = COMMANDS_BY_ID.get(id)
  if (!def) return []
  return isMac ? def.defaultBindings.darwin : def.defaultBindings.other
}

/** Platform-resolved identity: two spellings that press the same physical modifiers + key get
 *  the same identity (`Cmd+K` === `Ctrl+K` on non-mac, but not on mac). The key segment runs
 *  through `serializeShortcut` so ALIAS spellings collapse too (`Cmd+Esc` === `Cmd+Escape`,
 *  `Cmd+Return` === `Cmd+Enter`) — without that a hand-edited `Cmd+Return` override would sit
 *  invisibly on top of the `Cmd+Enter` default. */
export function bindingIdentity(binding: string, isMac: boolean): string {
  const p = parseShortcut(binding)
  const m = resolvedModifiers(p, isMac)
  return [
    m.meta ? 'M' : '',
    m.ctrl ? 'C' : '',
    m.alt ? 'A' : '',
    m.shift ? 'S' : '',
    ':',
    p.key === null
      ? '(hold)'
      : serializeShortcut({ cmd: false, ctrl: false, alt: false, shift: false, key: p.key })
  ].join('')
}

/** A bucket is a dispatch CONTEXT: commands sharing one can resolve at the same moment, so they
 *  compete for the same keys. All three view scopes dispatch from the window listener, but not at
 *  the same moments: 'canvas' resolves only while the board is CLOSED and 'board' only while it is
 *  OPEN, while 'app' resolves in both (`resolveCommandForKeyEvent`). So an app command sits in both
 *  view buckets, a canvas command in 'canvas-view' and a board command in 'board-view' — a canvas
 *  and a board command never compete. Folding the three into one global keyspace reported a
 *  collision dispatch cannot produce, and `sanitizeKeybindingOverrides` then stripped a legitimate
 *  override at load (a bare-arrow canvas command against the board's J/K/arrow keys). Terminal and
 *  scm are their own focused surfaces.
 *
 *  **`speech.dictation` is its own fourth bucket, and the reason is dispatch, not scope.** It
 *  never competes for a chord: the resolver SKIPS it outright (see the `def.id ===
 *  'speech.dictation'` guard in `resolveCommandForKeyEvent`), and its keyed gesture runs from a
 *  dedicated listener that claims the chord FIRST in plain app focus. So a chord shared with
 *  another command is a matter of PRECEDENCE — dictation wins where it listens, the other command
 *  wins everywhere else (terminal focus, say) — never ambiguity, which is the only thing the
 *  conflict detector exists to find. Folding it into 'global' therefore reported a collision that
 *  dispatch cannot produce.
 *
 *  What the bucket BUYS is survival on the read path: `sanitizeKeybindingOverrides` deletes every
 *  overridden participant of a reported conflict, so a migrated legacy chord that happened to match
 *  another command's binding (the `speech.shortcut` → `speech.dictation` seed in
 *  `core/settings-store.ts`) was seeded on load and stripped moments later, taking the user's own
 *  colliding override with it. With its own bucket the seed survives.
 *
 *  **Overlap policy is deliberately asymmetric.** The LOAD path PERMITS a shared chord — legacy
 *  settings.json files already contain them and silently dropping a user's chord is the failure
 *  this closes. The Settings UI REFUSES to create one (`commitCandidate`'s two dictation gates),
 *  because a user picking a chord interactively should be told about the precedence rather than
 *  discover it later. One case the permissive load path cannot rescue: a keyed dictation override
 *  on a MAIN-INTERCEPTED chord (⌘W / ⌘M) wins NOWHERE — main steals those in `before-input-event`
 *  before the page exists, so such a hand-edit survives sanitization as a permanently dead chord.
 *  The UI can never create it (`commitCandidate`'s reverse-shadow gate refuses it one step earlier
 *  than the dictation gates). */
export type ConflictBucket = 'canvas-view' | 'board-view' | 'terminal' | 'scm' | 'dictation'

export function conflictBuckets(def: Pick<CommandDefinition, 'id' | 'scope'>): readonly ConflictBucket[] {
  if (def.id === 'speech.dictation') return ['dictation']
  switch (def.scope) {
    case 'app': return ['canvas-view', 'board-view']
    case 'canvas': return ['canvas-view']
    case 'board': return ['board-view']
    default: return [def.scope]
  }
}

export interface KeybindingConflict {
  /** Canonical string of one colliding spelling (the first seen). */
  binding: string
  /** Sorted ids of every command holding the identity. */
  commandIds: CommandId[]
}

/** Collisions between effective bindings within a bucket. By default only collisions touching
 *  at least one overridden command are reported (shipped defaults are asserted conflict-free
 *  by a registry test using `includeDefaults: true` — user-facing surfaces never nag about
 *  stock bindings). */
export function findKeybindingConflicts(
  overrides: KeybindingOverrides,
  isMac: boolean,
  opts: { includeDefaults?: boolean } = {}
): KeybindingConflict[] {
  const byBucketAndIdentity = new Map<string, { binding: string; ids: Set<CommandId> }>()
  for (const def of COMMAND_DEFINITIONS) {
    for (const binding of getEffectiveBindings(def.id, overrides, isMac)) {
      for (const bucket of conflictBuckets(def)) {
        const key = `${bucket} ${bindingIdentity(binding, isMac)}`
        const entry = byBucketAndIdentity.get(key) ?? {
          // Canonicalized, so a hand-edited `cmd+k` override is reported as `Cmd+K`.
          binding: serializeShortcut(parseShortcut(binding)),
          ids: new Set<CommandId>()
        }
        entry.ids.add(def.id)
        byBucketAndIdentity.set(key, entry)
      }
    }
  }
  const conflicts: KeybindingConflict[] = []
  // Two app commands on one chord meet in BOTH view buckets; that is one conflict, not two.
  const reported = new Set<string>()
  for (const { binding, ids } of byBucketAndIdentity.values()) {
    if (ids.size < 2) continue
    const commandIds = [...ids].sort()
    const touchesOverride = commandIds.some((id) => overrides[id] !== undefined)
    if (!opts.includeDefaults && !touchesOverride) continue
    const key = `${binding} ${commandIds.join(' ')}`
    if (reported.has(key)) continue
    reported.add(key)
    conflicts.push({ binding, commandIds })
  }
  return conflicts
}

/** Commands the MAIN process intercepts via before-input-event. A remap of one of these is
 *  swallowed app-wide before any renderer surface sees the key, so the Settings UI must check
 *  its candidate against EVERY command — the per-bucket conflict detector cannot see this. */
export const MAIN_INTERCEPTED_COMMAND_IDS: readonly CommandId[] = [
  'node.close',
  'node.toggleMarkdown'
]

/** Cross-bucket shadowing check for a candidate binding of a main-intercepted command:
 *  every OTHER command whose effective bindings share the candidate's platform identity.
 *  Empty for non-intercepted commands (their collisions are the ordinary bucket check). */
export function findMainInterceptShadowing(
  id: CommandId,
  candidate: string,
  overrides: KeybindingOverrides,
  isMac: boolean
): CommandId[] {
  if (!MAIN_INTERCEPTED_COMMAND_IDS.includes(id)) return []
  const target = bindingIdentity(candidate, isMac)
  const hits: CommandId[] = []
  for (const def of COMMAND_DEFINITIONS) {
    if (def.id === id) continue
    for (const binding of getEffectiveBindings(def.id, overrides, isMac)) {
      if (bindingIdentity(binding, isMac) === target) {
        hits.push(def.id)
        break
      }
    }
  }
  return hits
}

/** Validate a raw `settings.keybindings` value (hand-editable JSON) into a safe override map.
 *  Loops until conflict-free so one bad edit cannot leave ambiguous dispatch. This is the
 *  SETTINGS-LOAD path: it applies what survives and warns about what it dropped. It is not the
 *  pre-save gate — its warnings are unstructured strings, which cannot tell a UI which field to
 *  block on. The Settings UI blocks pre-save in `ShortcutsSection.commitCandidate`, which runs
 *  `normalizeBindingForCommand` (inside its recorder) and `findKeybindingConflicts` directly, per
 *  candidate binding: same detector, different surfacing (design.md D3). */
export function sanitizeKeybindingOverrides(
  raw: unknown,
  isMac: boolean
): { overrides: KeybindingOverrides; warnings: string[] } {
  const warnings: string[] = []
  const overrides: Partial<Record<CommandId, string[]>> = {}
  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
    if (raw !== undefined && raw !== null) warnings.push('keybindings must be an object; ignored.')
    return { overrides, warnings }
  }
  for (const [id, value] of Object.entries(raw)) {
    if (!isCommandId(id)) {
      warnings.push(`Unknown command "${id}" ignored.`)
      continue
    }
    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
      warnings.push(`Bindings for "${id}" must be an array of strings; ignored.`)
      continue
    }
    const def = COMMANDS_BY_ID.get(id)!
    const normalized: string[] = []
    for (const s of value as string[]) {
      const r = normalizeBindingForCommand(def, s, isMac)
      if (r.ok) {
        if (!normalized.includes(r.value)) normalized.push(r.value)
      } else {
        warnings.push(`Binding "${s}" for "${id}" ignored: ${r.error}`)
      }
    }
    // A list that HAD entries and lost every one of them falls back to defaults rather than
    // being stored as `[]`: `[]` means "disabled", so a typo in a hand-edited settings.json
    // would silently turn a working shortcut off. An explicit `[]` in the input still disables.
    if (value.length > 0 && normalized.length === 0) {
      warnings.push(`All bindings for "${id}" were invalid; falling back to defaults.`)
      continue
    }
    overrides[id] = normalized
  }
  // Strip overridden participants of any remaining conflict until none are left. Bounded:
  // each pass removes at least one override or exits.
  // NEVER pass `includeDefaults: true` here. Termination rests on the touchesOverride reporting
  // gate: every reported conflict has at least one OVERRIDE to delete, so a pass always shrinks
  // the map. A default-vs-default conflict has no deletable participant, so it would be reported
  // forever and the loop would spin.
  for (;;) {
    const conflicts = findKeybindingConflicts(overrides, isMac)
    if (conflicts.length === 0) break
    for (const conflict of conflicts) {
      const titles = conflict.commandIds
        .map((cid) => COMMANDS_BY_ID.get(cid)?.title ?? cid)
        .join(', ')
      warnings.push(`Conflicting shortcut ${conflict.binding} between: ${titles}. Overrides dropped.`)
      for (const cid of conflict.commandIds) {
        if (overrides[cid] !== undefined) delete overrides[cid]
      }
    }
  }
  return { overrides, warnings }
}

/** Who wins while an xterm has focus. 'app-first' (default): allowInTerminal app commands still
 *  fire (today's behavior). 'terminal-first': ONLY scope:'terminal' commands fire; everything
 *  else — allowInTerminal app commands, the main-intercepted ⌘W/⌘M, the registry-less gestures —
 *  reaches the PTY. NOTE: the naive reading "terminal-first = the existing allowInTerminal gate"
 *  is vacuous here — that gate IS app-first; this flag tightens past it. */
export type TerminalShortcutPolicy = 'app-first' | 'terminal-first'

/** Unknown/legacy values read as app-first (the safe, current-behavior direction). */
export function normalizeTerminalShortcutPolicy(v: unknown): TerminalShortcutPolicy {
  return v === 'terminal-first' ? 'terminal-first' : 'app-first'
}

/**
 * PURE. Does the user's `terminalShortcutPolicy` mean this window must stop claiming chords right
 * now? The composition `index.ts` hands to `installKeydownIntercepts`' 5th parameter, exported so
 * it can be pressed instead of living untested inside a closure in a 5000-line file. It lives in
 * `shared` because it has TWO consumers: the desktop intercept (`main/keydown-intercept.ts`, which
 * re-exports it) and the Server Edition's browser-side ⌘M listener
 * (`renderer/bridge/markdown-toggle-key.ts`, which feeds it focus read straight from the DOM).
 *
 * **Both halves are refusals and both matter.** `app-first` is the shipped default, so it must be
 * false whatever the mirror reports — that is the byte-identical guarantee of this feature: a user
 * who never touched the setting sees exactly the pre-feature intercepts, even though their
 * renderer is reporting terminal focus all day. And in MAIN, `terminalFocused` is a MIRROR of the
 * renderer's `document.activeElement`, which is why `false` is its reset value everywhere main
 * keeps it: a page that died mid-report, a window that never had one, a reload — all resolve to
 * "intercepts on", never to "intercepts off with nothing alive to turn them back on". That
 * fail-safe reasoning is about main's mirror only: the browser consumer has no mirror and passes
 * LIVE DOM focus (`isTerminalTarget(document.activeElement)`) read on the very keystroke.
 *
 * Why the policy is read here rather than the intercepts simply being uninstalled under
 * `terminal-first`: the policy is a live setting and the focus changes per keystroke, so there is
 * nothing static to install against — and an app-first user's window must not be a different
 * window from a terminal-first user's.
 */
export function policyStandsDown(
  policy: TerminalShortcutPolicy,
  terminalFocused: boolean
): boolean {
  return policy === 'terminal-first' && terminalFocused
}

/** `typing` and `terminal` are expected to be DISJOINT — xterm's hidden textarea is a terminal,
 *  not a typing surface, so a caller classifying focus must not report both. If one does anyway,
 *  `typing` wins (it is checked first) and every terminal-scope command becomes unreachable. */
export interface KeyDispatchContext {
  /** A real input/textarea/contentEditable has focus (xterm's hidden textarea excluded). */
  typing: boolean
  /** An xterm has focus. */
  terminal: boolean
  /** The kanban board is open for the active project. */
  kanbanOpen: boolean
  /** terminal-first policy is active: while `terminal` is true, only scope:'terminal' commands
   *  may resolve (allowInTerminal is an app-first concept). Inert when `terminal` is false. */
  terminalFirst: boolean
}

/** Pure dispatch core: the first registry command (source order) whose effective bindings
 *  match `e` and whose flags permit the context. Keyed chords only — hold chords are the
 *  dedicated hold listener's job (`chordHeld`). Callers preventDefault only when the
 *  returned command's handler actually claims the chord. */
export function resolveCommandForKeyEvent(
  e: ShortcutKeyEvent,
  ctx: KeyDispatchContext,
  overrides: KeybindingOverrides,
  isMac: boolean
): CommandId | null {
  for (const def of COMMAND_DEFINITIONS) {
    // scm commands dispatch from their own focused composer (local onKeyDown), never from
    // the window listener — resolving them here would fire Commit with no composer focused.
    if (def.scope === 'scm') continue
    // speech.dictation dispatches from its own dedicated listeners (the keyed gesture and the
    // hold-mode effect, both reading `dictationBinding()` — the registry override; the legacy
    // settings.speech.shortcut field is only its downgrade mirror), never from here — its
    // row here is display-only, for ShortcutsPanel and the Settings section. A hand-edited KEYED
    // override would otherwise RESOLVE, find no handler, and spend the chord: the dispatcher's
    // claim protocol stops a resolved command from reaching the trailing gestures, so
    // `{"speech.dictation": ["Cmd+0"]}` would silently kill zoom-to-100%.
    if (def.id === 'speech.dictation') continue
    if (ctx.typing && !def.allowWhileTyping) continue
    if (ctx.terminal) {
      if (def.scope !== 'terminal' && (ctx.terminalFirst || !def.allowInTerminal)) continue
    }
    if (!ctx.terminal && def.scope === 'terminal') continue
    if (ctx.kanbanOpen && def.scope === 'canvas') continue
    if (!ctx.kanbanOpen && def.scope === 'board') continue
    for (const binding of getEffectiveBindings(def.id, overrides, isMac)) {
      // Hold chords belong to the dedicated hold listener, and this skip STATES that contract
      // rather than relying on it being unreachable: `matchesShortcut` also refuses a key-null
      // chord today (`parsed.key !== null`), so removing this line changes nothing — until the
      // day it does.
      if (isHoldChord(binding)) continue
      if (matchesShortcut(e, binding, isMac)) return def.id
    }
  }
  return null
}