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.

42.5 KB
Raw Blame
import { describe, it, expect } from 'vitest'
import {
  COMMAND_DEFINITIONS,
  COMMANDS_BY_ID,
  isCommandId,
  normalizeBindingForCommand,
  getEffectiveBindings,
  bindingIdentity,
  conflictBuckets,
  findKeybindingConflicts,
  sanitizeKeybindingOverrides,
  resolveCommandForKeyEvent,
  normalizeTerminalShortcutPolicy,
  MAIN_INTERCEPTED_COMMAND_IDS,
  findMainInterceptShadowing
} from './keybindings'
import type { CommandId } from './keybindings'
import { AGENT_CONFIG, BUILTIN_AGENT_IDS } from './agents/config'
import { parseShortcut } from './shortcut'
import type { ShortcutKeyEvent } from './shortcut'

describe('registry invariants', () => {
  it('has unique ids and a map that covers them all', () => {
    const ids = COMMAND_DEFINITIONS.map((d) => d.id)
    expect(new Set(ids).size).toBe(ids.length)
    expect(COMMANDS_BY_ID.size).toBe(ids.length)
    for (const d of COMMAND_DEFINITIONS) expect(COMMANDS_BY_ID.get(d.id)).toBe(d)
  })

  it('every default binding parses, and keyed defaults carry a key', () => {
    for (const d of COMMAND_DEFINITIONS) {
      for (const s of [...d.defaultBindings.darwin, ...d.defaultBindings.other]) {
        const p = parseShortcut(s)
        if (d.allowHoldChord) continue
        expect(p.key, `${d.id}: ${s}`).not.toBeNull()
      }
    }
  })

  it('pins the defaults that PR 2 will wire (behavior contract)', () => {
    expect(COMMANDS_BY_ID.get('app.commandPalette')?.defaultBindings.darwin).toEqual(['Cmd+K'])
    expect(COMMANDS_BY_ID.get('node.close')?.defaultBindings.other).toEqual(['Cmd+W'])
    expect(COMMANDS_BY_ID.get('canvas.redo')?.defaultBindings.other).toEqual(['Cmd+Shift+Z', 'Cmd+Y'])
    expect(COMMANDS_BY_ID.get('terminal.copySelection')?.defaultBindings.other).toEqual([
      'Cmd+Shift+C', 'Ctrl+Insert'
    ])
    expect(COMMANDS_BY_ID.get('canvas.deleteSelection')?.defaultBindings.other).toEqual(['Delete', 'Backspace'])
    expect(COMMANDS_BY_ID.get('speech.dictation')?.defaultBindings.darwin).toEqual(['Cmd+Alt'])
    expect(COMMANDS_BY_ID.get('canvas.fitAll')?.defaultBindings.darwin).toEqual([])
  })

  it('reopen-last-closed defaults to Cmd+Shift+T and works in a terminal', () => {
    const def = COMMANDS_BY_ID.get('app.reopenLastClosed')
    expect(def?.defaultBindings.darwin).toEqual(['Cmd+Shift+T'])
    expect(def?.defaultBindings.other).toEqual(['Cmd+Shift+T'])
    expect(def?.allowInTerminal).toBe(true)
  })

  it('pins the WHOLE table — every row PR 2 will dispatch on, in source order', () => {
    // Source order is contractual (first match wins in the resolver), so the array order is
    // asserted too. A dropped flag — allowInTerminal above all — reds this test.
    const table = COMMAND_DEFINITIONS.map((d) => ({
      id: d.id,
      title: d.title,
      group: d.group,
      scope: d.scope,
      darwin: d.defaultBindings.darwin,
      other: d.defaultBindings.other,
      allowWhileTyping: d.allowWhileTyping,
      allowInTerminal: d.allowInTerminal,
      allowBareKey: d.allowBareKey,
      allowHoldChord: d.allowHoldChord
    }))
    expect(table).toEqual([
      { id: 'app.commandPalette', title: 'Command palette', group: 'General', scope: 'app',
        darwin: ['Cmd+K'], other: ['Cmd+K'], allowInTerminal: true },
      { id: 'app.settings', title: 'Open settings', group: 'General', scope: 'app',
        darwin: ['Cmd+Comma'], other: ['Cmd+Comma'], allowInTerminal: true },
      { id: 'app.shortcutsPanel', title: 'Keyboard shortcuts panel', group: 'General', scope: 'app',
        darwin: ['Cmd+Slash'], other: ['Cmd+Slash'], allowInTerminal: true },
      { id: 'view.kanbanToggle', title: 'Toggle kanban board', group: 'General', scope: 'app',
        darwin: ['Cmd+Shift+B'], other: ['Cmd+Shift+B'], allowInTerminal: true },
      { id: 'view.globalKanbanToggle', title: 'Toggle global kanban (Omni)', group: 'General', scope: 'app',
        darwin: [], other: [], allowInTerminal: true },
      { id: 'view.focusMode', title: 'Toggle focus mode', group: 'General', scope: 'canvas',
        darwin: ['Cmd+Shift+F'], other: ['Cmd+Shift+F'], allowInTerminal: true },
      { id: 'panel.explorer', title: 'Toggle explorer panel', group: 'General', scope: 'app',
        darwin: ['Cmd+Shift+E'], other: ['Cmd+Shift+E'], allowInTerminal: true },
      { id: 'panel.sourceControl', title: 'Toggle source control panel', group: 'General',
        scope: 'app', darwin: ['Cmd+Shift+G'], other: ['Cmd+Shift+G'], allowInTerminal: true },
      { id: 'panel.sessions', title: 'Pin sessions sidebar', group: 'General', scope: 'app',
        darwin: ['Cmd+Shift+L'], other: ['Cmd+Shift+L'], allowInTerminal: true },
      { id: 'app.reopenLastClosed', title: 'Reopen last closed', group: 'General', scope: 'app',
        darwin: ['Cmd+Shift+T'], other: ['Cmd+Shift+T'], allowInTerminal: true },
      { id: 'project.next', title: 'Next project tab', group: 'General', scope: 'app',
        darwin: ['Ctrl+Tab'], other: ['Ctrl+Tab'], allowInTerminal: true, allowWhileTyping: true },
      { id: 'project.prev', title: 'Previous project tab', group: 'General', scope: 'app',
        darwin: ['Ctrl+Shift+Tab'], other: ['Ctrl+Shift+Tab'], allowInTerminal: true,
        allowWhileTyping: true },
      { id: 'canvas.undo', title: 'Undo', group: 'Canvas', scope: 'canvas',
        darwin: ['Cmd+Z'], other: ['Cmd+Z'] },
      { id: 'canvas.redo', title: 'Redo', group: 'Canvas', scope: 'canvas',
        darwin: ['Cmd+Shift+Z'], other: ['Cmd+Shift+Z', 'Cmd+Y'] },
      { id: 'canvas.goBack', title: 'Go back', group: 'Canvas', scope: 'canvas',
        darwin: ['Cmd+['], other: ['Cmd+['] },
      { id: 'canvas.goForward', title: 'Go forward', group: 'Canvas', scope: 'canvas',
        darwin: ['Cmd+]'], other: ['Cmd+]'] },
      { id: 'canvas.deleteSelection', title: 'Delete selection', group: 'Canvas', scope: 'canvas',
        darwin: ['Delete', 'Backspace'], other: ['Delete', 'Backspace'], allowBareKey: true },
      { id: 'canvas.fitAll', title: 'Fit all nodes in view', group: 'Canvas', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'canvas.tidy', title: 'Tidy canvas', group: 'Canvas', scope: 'canvas',
        darwin: ['Cmd+Shift+A'], other: ['Cmd+Shift+A'] },
      { id: 'canvas.tidyLineage', title: 'Arrange by lineage', group: 'Canvas', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'canvas.groupSelection', title: 'Group selection', group: 'Canvas', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'canvas.toggleLock', title: 'Toggle canvas lock', group: 'Canvas', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newTerminal', title: 'New terminal node', group: 'Nodes', scope: 'canvas',
        darwin: ['Cmd+T'], other: ['Cmd+T'] },
      { id: 'node.newAgent', title: 'New agent node', group: 'Nodes', scope: 'canvas',
        darwin: ['Cmd+Shift+C'], other: ['Cmd+Shift+C'] },
      // The per-agent + per-node-kind creates: pool only, no default chord on either platform.
      { id: 'node.newAgent.claude', title: 'New Claude Code node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newAgent.codex', title: 'New Codex node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newAgent.gemini', title: 'New Gemini node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newAgent.opencode', title: 'New opencode node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newAgent.grok', title: 'New Grok node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newAgent.copilot', title: 'New GitHub Copilot node', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [] },
      { id: 'node.newAgent.antigravity', title: 'New Antigravity node', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [] },
      { id: 'node.newAgent.cursor', title: 'New Cursor node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newSticky', title: 'New sticky note', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newBrowser', title: 'New browser node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newWebView', title: 'New web view node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newDino', title: 'New dino node', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newWhiteboard', title: 'New whiteboard', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.newFile', title: 'New file…', group: 'Nodes', scope: 'canvas',
        darwin: [], other: [] },
      { id: 'node.focusLeft', title: 'Focus node to the left', group: 'Nodes', scope: 'canvas',
        darwin: ['Cmd+ArrowLeft'], other: ['Ctrl+Shift+ArrowLeft'], allowInTerminal: true },
      { id: 'node.focusRight', title: 'Focus node to the right', group: 'Nodes', scope: 'canvas',
        darwin: ['Cmd+ArrowRight'], other: ['Ctrl+Shift+ArrowRight'], allowInTerminal: true },
      { id: 'node.focusUp', title: 'Focus node above', group: 'Nodes', scope: 'canvas',
        darwin: ['Cmd+ArrowUp'], other: ['Ctrl+Shift+ArrowUp'], allowInTerminal: true },
      { id: 'node.focusDown', title: 'Focus node below', group: 'Nodes', scope: 'canvas',
        darwin: ['Cmd+ArrowDown'], other: ['Ctrl+Shift+ArrowDown'], allowInTerminal: true },
      // Pool only: no default chord on either platform.
      { id: 'node.nextNeedingYou', title: 'Go to next agent needing you', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.maximize', title: 'Maximize / restore node', group: 'Nodes', scope: 'canvas',
        darwin: ['Cmd+Shift+Enter'], other: ['Cmd+Shift+Enter'], allowInTerminal: true },
      { id: 'node.zoneLeft', title: 'Snap node to left half', group: 'Nodes', scope: 'canvas',
        darwin: ['Ctrl+Alt+ArrowLeft'], other: [], allowInTerminal: true },
      { id: 'node.zoneRight', title: 'Snap node to right half', group: 'Nodes', scope: 'canvas',
        darwin: ['Ctrl+Alt+ArrowRight'], other: [], allowInTerminal: true },
      { id: 'node.zoneUp', title: 'Snap node to top half', group: 'Nodes', scope: 'canvas',
        darwin: ['Ctrl+Alt+ArrowUp'], other: [], allowInTerminal: true },
      { id: 'node.zoneDown', title: 'Snap node to bottom half', group: 'Nodes', scope: 'canvas',
        darwin: ['Ctrl+Alt+ArrowDown'], other: [], allowInTerminal: true },
      { id: 'node.zoneLeftThird', title: 'Snap node to left third', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.zoneCenterThird', title: 'Snap node to center third', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.zoneRightThird', title: 'Snap node to right third', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.zoneTopLeft', title: 'Snap node to top left quarter', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.zoneTopRight', title: 'Snap node to top right quarter', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.zoneBottomLeft', title: 'Snap node to bottom left quarter', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.zoneBottomRight', title: 'Snap node to bottom right quarter', group: 'Nodes',
        scope: 'canvas', darwin: [], other: [], allowInTerminal: true },
      { id: 'node.close', title: 'Close node / window', group: 'Nodes', scope: 'app',
        darwin: ['Cmd+W'], other: ['Cmd+W'], allowInTerminal: true, allowWhileTyping: true },
      { id: 'node.toggleMarkdown', title: 'Toggle markdown view', group: 'Nodes', scope: 'app',
        darwin: ['Cmd+M'], other: ['Cmd+M'], allowInTerminal: true, allowWhileTyping: true },
      { id: 'board.openCard', title: 'Open focused card', group: 'Board', scope: 'board',
        darwin: ['Space'], other: ['Space'] },
      { id: 'board.nextCard', title: 'Next card', group: 'Board', scope: 'board',
        darwin: ['J', 'ArrowDown'], other: ['J', 'ArrowDown'] },
      { id: 'board.prevCard', title: 'Previous card', group: 'Board', scope: 'board',
        darwin: ['K', 'ArrowUp'], other: ['K', 'ArrowUp'] },
      { id: 'board.columnLeft', title: 'Card in the column to the left', group: 'Board',
        scope: 'board', darwin: ['ArrowLeft'], other: ['ArrowLeft'] },
      { id: 'board.columnRight', title: 'Card in the column to the right', group: 'Board',
        scope: 'board', darwin: ['ArrowRight'], other: ['ArrowRight'] },
      { id: 'terminal.find', title: 'Find in terminal', group: 'Terminal', scope: 'terminal',
        darwin: ['Cmd+F'], other: ['Cmd+F'] },
      { id: 'terminal.copySelection', title: 'Copy terminal selection', group: 'Terminal',
        scope: 'terminal', darwin: ['Cmd+C'], other: ['Cmd+Shift+C', 'Ctrl+Insert'] },
      { id: 'scm.commit', title: 'Commit', group: 'Source Control', scope: 'scm',
        darwin: ['Cmd+Enter'], other: ['Cmd+Enter'], allowWhileTyping: true },
      { id: 'speech.dictation', title: 'Dictate', group: 'Speech', scope: 'app',
        darwin: ['Cmd+Alt'], other: ['Cmd+Alt'],
        allowHoldChord: true, allowInTerminal: true, allowWhileTyping: true }
    ])
  })

  it('isCommandId accepts known ids and rejects unknowns', () => {
    expect(isCommandId('node.newTerminal')).toBe(true)
    expect(isCommandId('node.selfDestruct')).toBe(false)
  })

  // Parity with the agent registry, both directions. The union is spelled statically (so the
  // CommandId type stays literal), which means nothing but this test notices when builtin agent
  // #7 lands: it reds here until `node.newAgent.<id>` exists, and it reds again if a command
  // outlives the agent it creates.
  it('has one create command per builtin agent, titled from AGENT_CONFIG', () => {
    const perAgent = COMMAND_DEFINITIONS.map((d) => d.id).filter((id) =>
      id.startsWith('node.newAgent.')
    )
    expect([...perAgent].sort()).toEqual(
      BUILTIN_AGENT_IDS.map((a) => `node.newAgent.${a}`).sort()
    )
    for (const agentId of BUILTIN_AGENT_IDS) {
      const d = COMMANDS_BY_ID.get(`node.newAgent.${agentId}` as CommandId)
      expect(d?.title).toBe(`New ${AGENT_CONFIG[agentId].label} node`)
      expect(d?.group).toBe('Nodes')
      expect(d?.scope).toBe('canvas')
    }
  })

  // Every command this PR added ships with NO default chord — the pool grows, the out-of-box
  // key map does not. A default sneaking in here would shadow an existing binding or steal a
  // key from the terminal for a user who never asked for the command.
  it('ships "New whiteboard" unbound on both platforms', () => {
    const d = COMMANDS_BY_ID.get('node.newWhiteboard')
    expect(d?.defaultBindings).toEqual({ darwin: [], other: [] })
  })

  it('ships the new create commands unbound on both platforms', () => {
    const added: readonly string[] = [
      ...BUILTIN_AGENT_IDS.map((a) => `node.newAgent.${a}`),
      'node.newSticky',
      'node.newBrowser',
      'node.newWebView',
      'node.newDino',
      'node.newFile'
    ]
    expect(added).toHaveLength(13)
    for (const id of added) {
      const d = COMMANDS_BY_ID.get(id as CommandId)
      expect(d, id).toBeDefined()
      expect(d!.defaultBindings.darwin, id).toEqual([])
      expect(d!.defaultBindings.other, id).toEqual([])
      expect(getEffectiveBindings(id as CommandId, {}, true), id).toEqual([])
      expect(getEffectiveBindings(id as CommandId, {}, false), id).toEqual([])
    }
  })
})

const def = (id: string) => {
  const d = COMMANDS_BY_ID.get(id as never)
  if (!d) throw new Error(`missing ${id}`)
  return d
}

describe('normalizeBindingForCommand', () => {
  it('canonicalizes token order and casing', () => {
    const r = normalizeBindingForCommand(def('node.newTerminal'), 'shift+t+cmd', true)
    expect(r).toEqual({ ok: true, value: 'Cmd+Shift+T' })
  })
  it('rejects a chord with no modifier for a normal command', () => {
    const r = normalizeBindingForCommand(def('node.newTerminal'), 'T', true)
    expect(r.ok).toBe(false)
  })
  it('rejects shift-only chords (stealing typed text)', () => {
    expect(normalizeBindingForCommand(def('node.newTerminal'), 'Shift+T', true).ok).toBe(false)
  })
  it('allows safe bare keys only with allowBareKey', () => {
    expect(normalizeBindingForCommand(def('canvas.deleteSelection'), 'Delete', true)).toEqual({
      ok: true, value: 'Delete'
    })
    expect(normalizeBindingForCommand(def('canvas.deleteSelection'), 'X', true).ok).toBe(false)
    expect(normalizeBindingForCommand(def('node.newTerminal'), 'Delete', true).ok).toBe(false)
  })
  it('allows hold chords only with allowHoldChord', () => {
    expect(normalizeBindingForCommand(def('speech.dictation'), 'Cmd+Alt', true)).toEqual({
      ok: true, value: 'Cmd+Alt'
    })
    expect(normalizeBindingForCommand(def('node.newTerminal'), 'Cmd+Alt', true).ok).toBe(false)
  })
  it('rejects Cmd combined with literal Ctrl on non-mac', () => {
    expect(normalizeBindingForCommand(def('node.newTerminal'), 'Cmd+Ctrl+T', false).ok).toBe(false)
    expect(normalizeBindingForCommand(def('node.newTerminal'), 'Cmd+Ctrl+T', true).ok).toBe(true)
  })
  it('rejects garbage', () => {
    expect(normalizeBindingForCommand(def('node.newTerminal'), '', true).ok).toBe(false)
    expect(normalizeBindingForCommand(def('node.newTerminal'), '+++', true).ok).toBe(false)
  })
  it('every default in the registry survives its own validation', () => {
    for (const d of COMMAND_DEFINITIONS) {
      for (const isMac of [true, false]) {
        for (const s of d.defaultBindings[isMac ? 'darwin' : 'other']) {
          const r = normalizeBindingForCommand(d, s, isMac)
          expect(r, `${d.id}: ${s} (isMac=${isMac})`).toEqual({ ok: true, value: s })
        }
      }
    }
  })
})

describe('getEffectiveBindings', () => {
  it('returns platform defaults with no override', () => {
    expect(getEffectiveBindings('terminal.copySelection', {}, true)).toEqual(['Cmd+C'])
    expect(getEffectiveBindings('terminal.copySelection', {}, false)).toEqual([
      'Cmd+Shift+C', 'Ctrl+Insert'
    ])
  })
  it('an override replaces defaults; [] disables', () => {
    const o = { 'node.newTerminal': ['Cmd+Shift+T'], 'canvas.undo': [] as string[] }
    expect(getEffectiveBindings('node.newTerminal', o, true)).toEqual(['Cmd+Shift+T'])
    expect(getEffectiveBindings('canvas.undo', o, true)).toEqual([])
  })
})

describe('bindingIdentity', () => {
  it('resolves Cmd and literal Ctrl to the same identity on non-mac', () => {
    expect(bindingIdentity('Cmd+K', false)).toBe(bindingIdentity('Ctrl+K', false))
  })
  it('keeps them distinct on mac', () => {
    expect(bindingIdentity('Cmd+K', true)).not.toBe(bindingIdentity('Ctrl+K', true))
  })
  it('collapses alias key spellings onto one identity', () => {
    expect(bindingIdentity('Cmd+Esc', true)).toBe(bindingIdentity('Cmd+Escape', true))
    expect(bindingIdentity('Cmd+Return', true)).toBe(bindingIdentity('Cmd+Enter', true))
  })
  it('still separates a modifier from a bare key, and a hold chord from a keyed one', () => {
    expect(bindingIdentity('Cmd+Delete', true)).not.toBe(bindingIdentity('Delete', true))
    expect(bindingIdentity('Cmd+Alt', true)).not.toBe(bindingIdentity('Cmd+Alt+D', true))
  })
})

describe('conflictBuckets', () => {
  // The whole mapping, asserted over the REGISTRY rather than a hand-picked example per bucket.
  // A bucket is a dispatch CONTEXT: the chords that can resolve at the same moment. 'canvas'
  // resolves only with the board closed and 'board' only with it open, while 'app' resolves in
  // both — so an app command sits in both view buckets and a canvas command never meets a board
  // one. 'terminal' and 'scm' are their own; `speech.dictation` is the one command whose bucket
  // comes from its id instead of its scope.
  it('maps every command to the contexts its scope dispatches in, dictation excepted', () => {
    const expected = {
      app: ['canvas-view', 'board-view'],
      canvas: ['canvas-view'],
      board: ['board-view'],
      terminal: ['terminal'],
      scm: ['scm']
    } as const
    for (const def of COMMAND_DEFINITIONS) {
      if (def.id === 'speech.dictation') continue
      expect(conflictBuckets(def)).toEqual(expected[def.scope])
    }
    expect(conflictBuckets(COMMANDS_BY_ID.get('speech.dictation')!)).toEqual(['dictation'])
  })

  it('agrees with the dispatcher: two scopes share a bucket exactly when both can resolve at once', () => {
    // Asked of the REAL resolver, never restated: a command can resolve in a context when, bound
    // alone to a chord nothing else holds, a keydown of that chord resolves to it there.
    const chord = 'Cmd+Alt+Shift+F12'
    const press = { metaKey: true, ctrlKey: false, altKey: true, shiftKey: true, key: 'F12' }
    const resolvesIn = (def: (typeof COMMAND_DEFINITIONS)[number], kanbanOpen: boolean): boolean =>
      resolveCommandForKeyEvent(
        press,
        { typing: false, terminal: false, kanbanOpen, terminalFirst: false },
        { [def.id]: [chord] },
        true
      ) === def.id
    const views = COMMAND_DEFINITIONS.filter((def) =>
      def.id !== 'speech.dictation' && (def.scope === 'app' || def.scope === 'canvas' || def.scope === 'board'))
    for (const a of views) {
      for (const b of views) {
        const share = conflictBuckets(a).some((bucket) => conflictBuckets(b).includes(bucket))
        const together = [true, false].some((open) => resolvesIn(a, open) && resolvesIn(b, open))
        expect(share, `${a.id} × ${b.id}`).toBe(together)
      }
    }
  })
})

describe('findKeybindingConflicts', () => {
  it('reports nothing for pure defaults', () => {
    expect(findKeybindingConflicts({}, true)).toEqual([])
    expect(findKeybindingConflicts({}, false)).toEqual([])
  })
  it('the shipped default table is conflict-free even under full scrutiny', () => {
    expect(findKeybindingConflicts({}, true, { includeDefaults: true })).toEqual([])
    expect(findKeybindingConflicts({}, false, { includeDefaults: true })).toEqual([])
  })
  it('flags an override colliding with a default in the same bucket', () => {
    const conflicts = findKeybindingConflicts({ 'canvas.fitAll': ['Cmd+K'] }, true)
    expect(conflicts).toEqual([
      { binding: 'Cmd+K', commandIds: ['app.commandPalette', 'canvas.fitAll'] }
    ])
  })
  it('reports the canonical spelling, not the override as written', () => {
    expect(findKeybindingConflicts({ 'canvas.fitAll': ['cmd+k'] }, true)).toEqual([
      { binding: 'Cmd+K', commandIds: ['app.commandPalette', 'canvas.fitAll'] }
    ])
    // canvas.fitAll precedes node.newTerminal in the registry, so the override is the
    // entry-creating spelling here — the assertion above cannot see the canonicalization.
    expect(findKeybindingConflicts({ 'canvas.fitAll': ['cmd+t'] }, true)).toEqual([
      { binding: 'Cmd+T', commandIds: ['canvas.fitAll', 'node.newTerminal'] }
    ])
  })
  it('flags a cross-spelling collision on non-mac (Ctrl+K vs Cmd+K)', () => {
    const conflicts = findKeybindingConflicts({ 'canvas.fitAll': ['Ctrl+K'] }, false)
    expect(conflicts.map((c) => c.commandIds)).toEqual([['app.commandPalette', 'canvas.fitAll']])
  })
  it('does not flag collisions across buckets', () => {
    // terminal.find is Cmd+F in the terminal bucket; an app-bucket Cmd+F is legal.
    expect(findKeybindingConflicts({ 'canvas.fitAll': ['Cmd+F'] }, true)).toEqual([])
  })
  it('the scm bucket is its own keyspace, not part of a view bucket', () => {
    // scm.commit holds Cmd+Enter; a canvas (canvas-view bucket) override on the same chord is legal,
    // because Commit dispatches from the focused composer. Reds if conflictBuckets folds 'scm'
    // into a view bucket.
    expect(findKeybindingConflicts({ 'canvas.fitAll': ['Cmd+Enter'] }, true)).toEqual([])
  })
  it('a canvas override may share a chord with a board command — they never dispatch together', () => {
    // board.nextCard holds bare ArrowDown and only resolves while a board is up; canvas commands
    // are inert then. A bare-arrow canvas override used to be stripped at load for this "conflict".
    expect(findKeybindingConflicts({ 'canvas.deleteSelection': ['ArrowDown'] }, true)).toEqual([])
    expect(sanitizeKeybindingOverrides({ 'canvas.deleteSelection': ['ArrowDown'] }, true))
      .toEqual({ overrides: { 'canvas.deleteSelection': ['ArrowDown'] }, warnings: [] })
    // …and the other direction: a board override on a canvas command's chord.
    expect(findKeybindingConflicts({ 'board.openCard': ['Cmd+Shift+F'] }, true)).toEqual([])
  })
  it('a board override still conflicts with an app command, which dispatches on the board too', () => {
    expect(findKeybindingConflicts({ 'board.openCard': ['Cmd+K'] }, true)).toEqual([
      { binding: 'Cmd+K', commandIds: ['app.commandPalette', 'board.openCard'] }
    ])
  })
  it('reports a collision between two app commands once, not once per view', () => {
    expect(findKeybindingConflicts({ 'app.settings': ['Cmd+K'] }, true)).toEqual([
      { binding: 'Cmd+K', commandIds: ['app.commandPalette', 'app.settings'] }
    ])
  })
  it('two disabled commands never conflict', () => {
    expect(
      findKeybindingConflicts({ 'canvas.fitAll': [], 'canvas.groupSelection': [] }, true)
    ).toEqual([])
  })
})

describe('sanitizeKeybindingOverrides', () => {
  it('passes through a clean override map', () => {
    const r = sanitizeKeybindingOverrides({ 'node.newTerminal': ['Cmd+Shift+Y'] }, true)
    expect(r).toEqual({ overrides: { 'node.newTerminal': ['Cmd+Shift+Y'] }, warnings: [] })
  })
  it('canonicalizes spellings', () => {
    const r = sanitizeKeybindingOverrides({ 'node.newTerminal': ['shift+cmd+y'] }, true)
    expect(r.overrides).toEqual({ 'node.newTerminal': ['Cmd+Shift+Y'] })
  })
  it('drops unknown ids with a warning, keeps the rest', () => {
    const r = sanitizeKeybindingOverrides(
      { 'node.selfDestruct': ['Cmd+X'], 'canvas.undo': [] }, true
    )
    expect(r.overrides).toEqual({ 'canvas.undo': [] })
    expect(r.warnings.some((w) => w.includes('node.selfDestruct'))).toBe(true)
  })
  it('drops an invalid binding string but keeps valid siblings', () => {
    const r = sanitizeKeybindingOverrides({ 'node.newTerminal': ['Cmd+Shift+Y', 'T'] }, true)
    expect(r.overrides).toEqual({ 'node.newTerminal': ['Cmd+Shift+Y'] })
    expect(r.warnings.length).toBe(1)
  })
  it('a non-empty list that is entirely invalid falls back to defaults, not disabled', () => {
    const r = sanitizeKeybindingOverrides({ 'node.newTerminal': ['T', '+++'] }, true)
    expect(r.overrides).toEqual({})
    expect(r.warnings.length).toBeGreaterThan(0)
  })
  it('an explicit empty array still means disabled', () => {
    expect(sanitizeKeybindingOverrides({ 'canvas.undo': [] }, true).overrides).toEqual({
      'canvas.undo': []
    })
  })
  it('strips BOTH sides of a conflicting override pair, naming the titles', () => {
    const r = sanitizeKeybindingOverrides(
      { 'canvas.fitAll': ['Cmd+P'], 'canvas.groupSelection': ['Cmd+P'] }, true
    )
    expect(r.overrides).toEqual({})
    expect(r.warnings.some((w) =>
      w.includes('Fit all nodes in view') && w.includes('Group selection')
    )).toBe(true)
  })
  it('an override conflicting with a DEFAULT strips only the override', () => {
    const r = sanitizeKeybindingOverrides({ 'canvas.fitAll': ['Cmd+K'] }, true)
    expect(r.overrides).toEqual({})
    expect(r.warnings.some((w) => w.includes('Command palette'))).toBe(true)
  })
  it('keeps stripping when a REVERTED default uncovers a second conflict', () => {
    // Pass 1: Cmd+P collides between the two overrides, so both are dropped — which reverts
    // app.commandPalette to its Cmd+K default, and THAT now collides with canvas.fitAll's
    // override. Pass 2 strips it. A single-shot strip would leave canvas.fitAll on Cmd+K,
    // ambiguous against the palette.
    const r = sanitizeKeybindingOverrides(
      {
        'app.commandPalette': ['Cmd+P'],
        'canvas.groupSelection': ['Cmd+P'],
        'canvas.fitAll': ['Cmd+K']
      },
      true
    )
    expect(r.overrides).toEqual({})
    expect(r.warnings.length).toBeGreaterThanOrEqual(2)
  })
  it('non-object / non-array shapes degrade to empty with a warning', () => {
    expect(sanitizeKeybindingOverrides('nope', true).overrides).toEqual({})
    expect(sanitizeKeybindingOverrides({ 'canvas.undo': 'Cmd+Z' }, true).overrides).toEqual({})
  })
  it('is a fixpoint: sanitizing its own output adds nothing', () => {
    const once = sanitizeKeybindingOverrides(
      { 'canvas.fitAll': ['Cmd+P'], 'node.newTerminal': ['Cmd+Shift+T'] }, true
    )
    const twice = sanitizeKeybindingOverrides(once.overrides, true)
    expect(twice).toEqual({ overrides: once.overrides, warnings: [] })
  })
})

const ev = (over: Partial<ShortcutKeyEvent>): ShortcutKeyEvent => ({
  metaKey: false, ctrlKey: false, shiftKey: false, altKey: false, key: '', ...over
})
const ctx = (
  over: Partial<{
    typing: boolean; terminal: boolean; kanbanOpen: boolean; terminalFirst: boolean
  }> = {}
) => ({
  typing: false, terminal: false, kanbanOpen: false, terminalFirst: false, ...over
})

describe('resolveCommandForKeyEvent', () => {
  it('resolves Ctrl+Tab / Ctrl+Shift+Tab to the project-tab cycle from any focus, on both platforms', () => {
    for (const isMac of [true, false]) {
      for (const c of [ctx(), ctx({ terminal: true }), ctx({ typing: true }), ctx({ kanbanOpen: true })]) {
        expect(resolveCommandForKeyEvent(ev({ ctrlKey: true, key: 'Tab' }), c, {}, isMac))
          .toBe('project.next')
        expect(resolveCommandForKeyEvent(ev({ ctrlKey: true, shiftKey: true, key: 'Tab' }), c, {}, isMac))
          .toBe('project.prev')
      }
    }
    // A bare Tab stays focus traversal, and terminal-first hands the chord back to the pane.
    expect(resolveCommandForKeyEvent(ev({ key: 'Tab' }), ctx(), {}, true)).toBeNull()
    expect(resolveCommandForKeyEvent(
      ev({ ctrlKey: true, key: 'Tab' }), ctx({ terminal: true, terminalFirst: true }), {}, true
    )).toBeNull()
  })

  it('matches a default app chord', () => {
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'k' }), ctx(), {}, true))
      .toBe('app.commandPalette')
  })
  it('matches the bracket chords from the KEY the DOM reports', () => {
    // The registry spells these `Cmd+[` / `Cmd+]` because the resolver compares against
    // `e.key`. Spelled as the `e.code` values (`BracketLeft`/`BracketRight`) they would
    // normalize to 'BRACKETLEFT' and match no keydown at all — a silently dead chord.
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: '[' }), ctx(), {}, true))
      .toBe('canvas.goBack')
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: ']' }), ctx(), {}, true))
      .toBe('canvas.goForward')
  })
  it('typing blocks commands without allowWhileTyping, allows the flagged ones', () => {
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, key: 't' }), ctx({ typing: true }), {}, true
    )).toBeNull()
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, key: 'w' }), ctx({ typing: true }), {}, true
    )).toBe('node.close')
  })
  it('terminal focus blocks canvas commands but passes allowInTerminal + terminal scope', () => {
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, key: 't' }), ctx({ terminal: true }), {}, true
    )).toBeNull()
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, key: 'k' }), ctx({ terminal: true }), {}, true
    )).toBe('app.commandPalette')
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, key: 'f' }), ctx({ terminal: true }), {}, true
    )).toBe('terminal.find')
  })
  it('kanban open makes canvas-scope commands inert, app scope still fires', () => {
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, key: 'z' }), ctx({ kanbanOpen: true }), {}, true
    )).toBeNull()
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, shiftKey: true, key: 'b' }), ctx({ kanbanOpen: true }), {}, true
    )).toBe('view.kanbanToggle')
  })
  it('terminal.find does NOT fire outside terminal focus (scope-gated)', () => {
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'f' }), ctx(), {}, true)).toBeNull()
  })
  it('respects overrides and disabled commands', () => {
    const o = { 'app.commandPalette': [] as string[], 'canvas.fitAll': ['Cmd+K'] }
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'k' }), ctx(), o, true))
      .toBe('canvas.fitAll')
  })
  it('never resolves a hold chord', () => {
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, altKey: true, key: 'Alt' }), ctx(), {}, true
    )).toBeNull()
  })
  it('never resolves scm-scope commands — they dispatch from their own composer', () => {
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'Enter' }), ctx(), {}, true))
      .toBeNull()
  })
  it('never resolves speech.dictation — even a hand-edited KEYED override', () => {
    // The registry row is display-only; dictation dispatches from its own listeners reading
    // settings.speech.shortcut, so nothing here would ever handle it. Without the resolver skip
    // this override RESOLVES, finds no handler, and the chord is spent — the trailing gestures
    // (zoom / projectJump / copy) never see it, so a `Cmd+0` override kills zoom-to-100%.
    // Passed straight in, bypassing sanitize: this is exactly the hand-edited settings.json case.
    const o = { 'speech.dictation': ['Cmd+0'] }
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: '0' }), ctx(), o, true)).toBeNull()
  })
  it('terminal focus admits terminal scope over a canvas command sharing the chord', () => {
    // Cmd+F sits on terminal.find; a canvas-scope override claims the same chord. The
    // terminal-focus gate drops canvas.fitAll before its bindings are ever read — this
    // witnesses the gate, NOT registry order (that is the tie test below).
    const o = { 'canvas.fitAll': ['Cmd+F'] }
    expect(resolveCommandForKeyEvent(
      ev({ metaKey: true, key: 'f' }), ctx({ terminal: true }), o, true
    )).toBe('terminal.find')
  })
  it('resolves the non-mac-only alternate default (Ctrl+Y → redo)', () => {
    expect(resolveCommandForKeyEvent(ev({ ctrlKey: true, key: 'y' }), ctx(), {}, false))
      .toBe('canvas.redo')
  })
  it('non-mac Ctrl+Shift+C is copy in a terminal and New agent outside one', () => {
    // By design, the two buckets double-book this chord: node.newAgent (global) and
    // terminal.copySelection (terminal) both default to it off-mac, and the focus gates — not
    // the conflict detector — are what keep them apart at dispatch time.
    const e = ev({ ctrlKey: true, shiftKey: true, key: 'C' })
    expect(resolveCommandForKeyEvent(e, ctx({ terminal: true }), {}, false))
      .toBe('terminal.copySelection')
    expect(resolveCommandForKeyEvent(e, ctx(), {}, false)).toBe('node.newAgent')
  })
  it('a bare key resolves, and typing still blocks it', () => {
    expect(resolveCommandForKeyEvent(ev({ key: 'Delete' }), ctx(), {}, true))
      .toBe('canvas.deleteSelection')
    expect(resolveCommandForKeyEvent(ev({ key: 'Delete' }), ctx({ typing: true }), {}, true))
      .toBeNull()
  })
  it('first matching definition in registry source order wins a tie', () => {
    // Deliberately unsanitized colliding override — the resolver must order the tie deterministically.
    const o = { 'canvas.redo': ['Cmd+Z'] }
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'z' }), ctx(), o, true)).toBe('canvas.undo')
  })
})

describe('findMainInterceptShadowing', () => {
  it('flags a main-intercepted remap that shadows another bucket', () => {
    expect(findMainInterceptShadowing('node.close', 'Cmd+F', {}, true)).toEqual(['terminal.find'])
    expect(findMainInterceptShadowing('node.close', 'Cmd+Enter', {}, true)).toEqual(['scm.commit'])
  })
  it('same-bucket collisions are the sanitizer/conflict path, still reported here', () => {
    expect(findMainInterceptShadowing('node.toggleMarkdown', 'Cmd+K', {}, true)).toEqual([
      'app.commandPalette'
    ])
  })
  it('empty for a clean chord, for non-intercepted commands, and never self-reports', () => {
    expect(findMainInterceptShadowing('node.close', 'Cmd+Alt+F9', {}, true)).toEqual([])
    expect(findMainInterceptShadowing('canvas.undo', 'Cmd+F', {}, true)).toEqual([])
    expect(findMainInterceptShadowing('node.close', 'Cmd+W', {}, true)).toEqual([])
  })
  it('respects overrides and cross-spelling identities', () => {
    const o = { 'terminal.find': ['Cmd+Alt+F9'] }
    expect(findMainInterceptShadowing('node.close', 'Cmd+F', o, true)).toEqual([])
    expect(findMainInterceptShadowing('node.close', 'Ctrl+K', {}, false)).toEqual([
      'app.commandPalette'
    ])
  })
  it('names exactly the two main-intercepted commands', () => {
    expect(MAIN_INTERCEPTED_COMMAND_IDS).toEqual(['node.close', 'node.toggleMarkdown'])
  })
})

describe('normalizeTerminalShortcutPolicy', () => {
  it('defaults everything but the literal terminal-first to app-first', () => {
    expect(normalizeTerminalShortcutPolicy('terminal-first')).toBe('terminal-first')
    expect(normalizeTerminalShortcutPolicy('app-first')).toBe('app-first')
    expect(normalizeTerminalShortcutPolicy(undefined)).toBe('app-first')
    expect(normalizeTerminalShortcutPolicy('shell-first')).toBe('app-first')
  })
})

describe('resolver under terminal-first', () => {
  const term = (terminalFirst: boolean) => ({
    typing: false, terminal: true, kanbanOpen: false, terminalFirst
  })
  it('app-first keeps today: allowInTerminal app commands fire over a terminal', () => {
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'k' }), term(false), {}, true))
      .toBe('app.commandPalette')
  })
  it('terminal-first blocks allowInTerminal app commands', () => {
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'k' }), term(true), {}, true))
      .toBeNull()
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, shiftKey: true, key: 'b' }), term(true), {}, true))
      .toBeNull()
  })
  it('terminal-first keeps terminal-scope commands alive', () => {
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'f' }), term(true), {}, true))
      .toBe('terminal.find')
  })
  it('terminalFirst is inert outside terminal focus', () => {
    const app = { typing: false, terminal: false, kanbanOpen: false, terminalFirst: true }
    expect(resolveCommandForKeyEvent(ev({ metaKey: true, key: 'k' }), app, {}, true))
      .toBe('app.commandPalette')
  })
})

describe('dictation conflict bucket', () => {
  it("a dictation override sharing another command's chord is NOT a conflict", () => {
    expect(findKeybindingConflicts({ 'speech.dictation': ['Cmd+K'] }, true)).toEqual([])
  })
  it('sanitize keeps a colliding dictation override — the migration survival case', () => {
    const r = sanitizeKeybindingOverrides({ 'speech.dictation': ['Cmd+K'] }, true)
    expect(r).toEqual({ overrides: { 'speech.dictation': ['Cmd+K'] }, warnings: [] })
  })
  it("sanitize keeps BOTH sides when a user override shares dictation's chord", () => {
    const r = sanitizeKeybindingOverrides(
      { 'speech.dictation': ['Cmd+J'], 'app.commandPalette': ['Cmd+J'] },
      true
    )
    expect(r.overrides).toEqual({
      'speech.dictation': ['Cmd+J'],
      'app.commandPalette': ['Cmd+J']
    })
    expect(r.warnings).toEqual([])
  })
  // Dictation is now OUTSIDE `includeDefaults`' reach: a future default colliding with its
  // `Cmd+Alt` would not be caught here.
  it('the shipped defaults stay conflict-free under full scrutiny (unchanged invariant)', () => {
    expect(findKeybindingConflicts({}, true, { includeDefaults: true })).toEqual([])
    expect(findKeybindingConflicts({}, false, { includeDefaults: true })).toEqual([])
  })
})


// The kanban board's keyboard (Space / J / K / arrows). Bare keys are only safe because of WHERE
// these fire: while a board is up, and never while typing or in a terminal — the refusals below
// are what make a bare letter a command rather than a character stolen from the user.
describe('board commands', () => {
  it('permit bare keys, letters and Space included — for board scope only', () => {
    expect(normalizeBindingForCommand(def('board.nextCard'), 'j', true)).toEqual({ ok: true, value: 'J' })
    expect(normalizeBindingForCommand(def('board.openCard'), 'Space', false)).toEqual({ ok: true, value: 'Space' })
    expect(normalizeBindingForCommand(def('board.prevCard'), 'Shift+K', true)).toEqual({ ok: true, value: 'Shift+K' })
    // Everyone else keeps the rule: a bare letter would be stolen from whatever the user types.
    expect(normalizeBindingForCommand(def('node.newTerminal'), 'J', true).ok).toBe(false)
    expect(normalizeBindingForCommand(def('canvas.deleteSelection'), 'J', true).ok).toBe(false)
  })

  it('resolve only while a board is open', () => {
    expect(resolveCommandForKeyEvent(ev({ key: 'j' }), ctx({ kanbanOpen: true }), {}, true)).toBe('board.nextCard')
    expect(resolveCommandForKeyEvent(ev({ key: 'ArrowDown' }), ctx({ kanbanOpen: true }), {}, false)).toBe('board.nextCard')
    expect(resolveCommandForKeyEvent(ev({ key: 'k' }), ctx({ kanbanOpen: true }), {}, true)).toBe('board.prevCard')
    expect(resolveCommandForKeyEvent(ev({ key: ' ' }), ctx({ kanbanOpen: true }), {}, true)).toBe('board.openCard')
    expect(resolveCommandForKeyEvent(ev({ key: 'ArrowLeft' }), ctx({ kanbanOpen: true }), {}, true)).toBe('board.columnLeft')
    expect(resolveCommandForKeyEvent(ev({ key: 'j' }), ctx(), {}, true)).toBeNull()
    expect(resolveCommandForKeyEvent(ev({ key: ' ' }), ctx(), {}, true)).toBeNull()
  })

  it('are refused inside a text surface (the comment box, a rename field, the chat composer)', () => {
    for (const key of ['j', 'k', ' ', 'ArrowDown', 'ArrowRight']) {
      expect(resolveCommandForKeyEvent(ev({ key }), ctx({ kanbanOpen: true, typing: true }), {}, true)).toBeNull()
    }
  })

  it('are refused while a terminal has focus — the card modal\'s terminal owns its keys', () => {
    for (const terminalFirst of [false, true]) {
      for (const key of ['j', 'k', ' ', 'ArrowUp']) {
        expect(
          resolveCommandForKeyEvent(ev({ key }), ctx({ kanbanOpen: true, terminal: true, terminalFirst }), {}, true)
        ).toBeNull()
      }
    }
  })

  it('a held modifier is a different chord (Cmd+J is not J)', () => {
    expect(resolveCommandForKeyEvent(ev({ key: 'j', metaKey: true }), ctx({ kanbanOpen: true }), {}, true)).toBeNull()
  })

  it('follow a remap and a disable', () => {
    const o = { 'board.nextCard': ['N'], 'board.openCard': [] as string[] }
    expect(resolveCommandForKeyEvent(ev({ key: 'n' }), ctx({ kanbanOpen: true }), o, true)).toBe('board.nextCard')
    expect(resolveCommandForKeyEvent(ev({ key: 'j' }), ctx({ kanbanOpen: true }), o, true)).toBeNull()
    expect(resolveCommandForKeyEvent(ev({ key: ' ' }), ctx({ kanbanOpen: true }), o, true)).toBeNull()
  })
})