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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(kanban): keyboard — J/K and arrows walk the board, Space opens a card
review424b0d23b683
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 79538197b..cc6bdfc72 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -200,6 +200,7 @@ import { containerOrigin, snapPointInRootSpace } from '../lib/gridSnap'import { zoomFromPct } from '../lib/zoomPresets'import { CANVAS_MAX_ZOOM, CANVAS_MIN_ZOOM } from './zoom-limits'import { isSpaceRelease, spacePanKeydown } from '../lib/spacePan'+import { runBoardKey } from '../lib/boardKeys'import { readCanvasLocked, writeCanvasLocked } from '../lib/canvasLock'import {FLOW_NODE_CLASS,@@ -1157,7 +1158,8 @@ export function Canvas() {*/useEffect(() => {const onKeyDown = (e: KeyboardEvent): void => {- if (spacePanKeydown(e, document.activeElement) !== 'engage') return+ const covered = isGlobalKanbanOpen() || isKanbanOpen(useProjects.getState().activeProjectId)+ if (spacePanKeydown(e, document.activeElement, covered) !== 'engage') returne.preventDefault()setSpacePan(true)}@@ -8333,6 +8335,13 @@ export function Canvas() {'canvas.goForward': () => { goForward(); return true },'canvas.fitAll': () => { fitAll(); return true },'canvas.tidy': () => { arrangeAllNodes(); return true },+ // The kanban board's keys — the mounted board decides (and declines when the focused control+ // owns the key, or when no per-project board is up: Omni registers none). lib/boardKeys.+ 'board.openCard': () => runBoardKey('open'),+ 'board.nextCard': () => runBoardKey('next'),+ 'board.prevCard': () => runBoardKey('prev'),+ 'board.columnLeft': () => runBoardKey('left'),+ 'board.columnRight': () => runBoardKey('right'),'canvas.deleteSelection': deleteSelectionCommand,'node.newTerminal': () => { addTerminal(); return true },'node.newAgent': () => {diff --git a/src/renderer/components/ShortcutsPanel.test.tsx b/src/renderer/components/ShortcutsPanel.test.tsxindex bf61d237c..1fe745b0d 100644--- a/src/renderer/components/ShortcutsPanel.test.tsx+++ b/src/renderer/components/ShortcutsPanel.test.tsx@@ -54,7 +54,8 @@ function bindEverything(isMac: boolean): (id: CommandId) => readonly string[] {const pool = [...'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split(''),...'0123456789'.split(''),- ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`)+ ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`),+ 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'PageUp', 'PageDown']expect(pool.length).toBeGreaterThanOrEqual(COMMAND_DEFINITIONS.length)const map = new Map<CommandId, string[]>()diff --git a/src/renderer/components/kanban/KanbanView.keyboard.test.tsx b/src/renderer/components/kanban/KanbanView.keyboard.test.tsxnew file mode 100644index 000000000..b9b4f3cd5--- /dev/null+++ b/src/renderer/components/kanban/KanbanView.keyboard.test.tsx@@ -0,0 +1,212 @@+// @vitest-environment jsdom+//+// The board's keyboard: J/K (and arrows) walk the cards in board order, Space opens the focused+// card, and inside the card modal J/K step to the neighbouring card. Every action DECLINES — falls+// through to the platform — when the focused control uses the key itself or a dialog sits on top.+// (The typing / terminal refusals are the registry's, pinned in shared/keybindings.test.ts.)+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { act, useEffect } from 'react'+import { createRoot, type Root } from 'react-dom/client'+import { KanbanView, type KanbanSession } from './KanbanView'+import type { ProjectKanban } from '@shared/types'+import { runBoardKey } from '../../lib/boardKeys'+import { popDialog, pushDialog, resetDialogStack } from '../dialog-stack'++vi.mock('../../session/session', () => ({+ useSession: () => ({ source: 'local', api: window.nodeTerminal })+}))++// The real modal is exercised by CardModal.test; here it only has to be a dialog on the stack that+// names its card and can close.+vi.mock('./CardModal', () => ({+ CardModal: ({ session, onClose }: { session: { id: string }; onClose: () => void }) => {+ useEffect(() => {+ pushDialog('card-modal')+ return () => popDialog('card-modal')+ }, [])+ return (+ <div className="kanban-modal" data-node-id={session.id}>+ <button className="modal-close" onClick={onClose}>close</button>+ <select className="modal-select"><option>low</option><option>high</option></select>+ </div>+ )+ }+}))++let root: Root+let host: HTMLElement+const card = (id: string): KanbanSession =>+ ({ id, title: `Card ${id}`, color: '#fff', kind: 'sticky', text: '', spawn: {} }) as unknown as KanbanSession++// Ungrouped: u1. To Do: a1 a2. Done: b1.+const board = (): ProjectKanban => ({+ columns: [+ { id: 'a', title: 'To Do', color: '#0a84ff' },+ { id: 'b', title: 'Done', color: '#32d74b' }+ ],+ assignments: [+ { nodeId: 'a1', columnId: 'a' },+ { nodeId: 'a2', columnId: 'a' },+ { nodeId: 'b1', columnId: 'b' }+ ]+})++beforeEach(() => {+ vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)+ vi.stubGlobal(+ 'ResizeObserver',+ class {+ observe(): void {}+ unobserve(): void {}+ disconnect(): void {}+ }+ )+ ;(window as unknown as { nodeTerminal: unknown }).nodeTerminal = {+ boardLog: { list: async () => [], onChanged: () => () => {} },+ settings: { save: async () => {} }+ }+ resetDialogStack()+ host = document.createElement('div')+ document.body.appendChild(host)+ root = createRoot(host)+ const noop = (): void => {}+ act(() =>+ root.render(+ <KanbanView+ board={board()}+ sessions={['u1', 'a1', 'a2', 'b1'].map(card)}+ onChange={noop}+ onOpenNode={noop}+ onCreateNode={noop}+ onRenameNode={noop}+ onEditSticky={noop}+ onDeleteNode={noop}+ onModalNodeChange={noop}+ onBrowserNav={noop}+ onSetIcon={noop}+ />+ )+ )+})+afterEach(() => {+ act(() => root.unmount())+ host.remove()+ document.body.innerHTML = ''+ resetDialogStack()+ vi.unstubAllGlobals()+})++const focused = (): string | null =>+ (document.activeElement as HTMLElement | null)?.getAttribute('data-kanban-card') ?? null+const modalCard = (): string | null =>+ document.querySelector('.kanban-modal')?.getAttribute('data-node-id') ?? null+const press = (action: Parameters<typeof runBoardKey>[0]): boolean => {+ let claimed = false+ act(() => {+ claimed = runBoardKey(action)+ })+ return claimed+}+const cardEl = (id: string): HTMLElement =>+ document.querySelector<HTMLElement>(`[data-kanban-card="${id}"]`)!++describe('KanbanView — board keyboard', () => {+ it('J from nowhere focuses the first card; J/K then walk board order (column by column)', () => {+ expect(press('next')).toBe(true)+ expect(focused()).toBe('u1')+ press('next')+ expect(focused()).toBe('a1')+ press('next')+ press('next')+ expect(focused()).toBe('b1')+ expect(press('next')).toBe(false) // the end: nothing to move to, the key falls through+ press('prev')+ expect(focused()).toBe('a2')+ })++ it('K from nowhere focuses the LAST card', () => {+ press('prev')+ expect(focused()).toBe('b1')+ })++ it('left/right jump to the same row of the neighbouring column', () => {+ act(() => cardEl('a2').focus())+ press('right')+ expect(focused()).toBe('b1')+ press('left')+ expect(focused()).toBe('a1')+ press('left')+ expect(focused()).toBe('u1')+ expect(press('left')).toBe(false)+ })++ it('left/right with no card focused decline (the arrow keeps its native meaning)', () => {+ expect(press('right')).toBe(false)+ })++ it('Space opens the focused card', () => {+ act(() => cardEl('a1').focus())+ expect(press('open')).toBe(true)+ expect(modalCard()).toBe('a1')+ })++ it('Space with no card to open declines', () => {+ expect(press('open')).toBe(false)+ expect(modalCard()).toBeNull()+ })++ it('Space on a focused BUTTON is the button’s — the board declines', () => {+ const btn = document.querySelector<HTMLButtonElement>('.kanban-add-col')!+ act(() => btn.focus())+ expect(press('open')).toBe(false)+ expect(modalCard()).toBeNull()+ })++ it('inside the card modal, J/K step to the neighbouring card', () => {+ act(() => cardEl('a1').focus())+ press('open')+ expect(press('next')).toBe(true)+ expect(modalCard()).toBe('a2')+ press('prev')+ press('prev')+ expect(modalCard()).toBe('u1')+ expect(press('prev')).toBe(false)+ // Space and the column jumps are not the modal's: its focused controls keep them.+ expect(press('open')).toBe(false)+ expect(press('right')).toBe(false)+ })++ it('inside the modal, a focused <select> keeps its arrows and letters — no card step', () => {+ act(() => cardEl('a1').focus())+ press('open')+ act(() => document.querySelector<HTMLSelectElement>('.modal-select')!.focus())+ expect(press('next')).toBe(false)+ expect(modalCard()).toBe('a1')+ })++ it('declines while another dialog sits on top of the modal (it owns the keyboard)', () => {+ act(() => cardEl('a1').focus())+ press('open')+ pushDialog('icon-picker')+ expect(press('next')).toBe(false)+ expect(modalCard()).toBe('a1')+ popDialog('icon-picker')+ })++ it('declines on the board while any dialog is open', () => {+ pushDialog('confirm')+ expect(press('next')).toBe(false)+ popDialog('confirm')+ })++ it('closing the modal puts focus back on the card it showed, so J/K continue from there', () => {+ act(() => cardEl('a1').focus())+ press('open')+ press('next')+ act(() => {+ document.querySelector<HTMLButtonElement>('.modal-close')!.click()+ })+ expect(modalCard()).toBeNull()+ expect(focused()).toBe('a2')+ })+})diff --git a/src/renderer/components/kanban/KanbanView.tsx b/src/renderer/components/kanban/KanbanView.tsxindex 996ac57ae..3baf7843a 100644--- a/src/renderer/components/kanban/KanbanView.tsx+++ b/src/renderer/components/kanban/KanbanView.tsx@@ -20,6 +20,9 @@ import {nextColumnColor, pruneAssignments, recolorColumn, renameColumn, setColumnCategory, unassigned} from '../../lib/kanban'import { markCanvasCovered } from '../../lib/canvasCovered'+import { registerBoardKeys, type BoardKeyAction } from '../../lib/boardKeys'+import { columnStep, keyOwnedByControl, stepCard } from '../../lib/boardKeyNav'+import { openDialogCount } from '../dialog-stack'import { labelSwatch } from '../../lib/kanbanLabelColors'import { CardModal } from './CardModal'import { KanbanColumn, type KanbanLane } from './KanbanColumn'@@ -133,6 +136,25 @@ const isProviderDrag = (drag: CardDrag): drag is Extract<CardDrag, { sourceId: 'const NO_LABELS: KanbanLabel[] = []const NO_CARDS: KanbanSession[] = []+/** The card the board's keys act FROM: the focused card, else the one under the pointer. */+function currentBoardCard(active: Element | null): string | null {+ const focused = active?.closest?.('[data-kanban-card]')?.getAttribute('data-kanban-card')+ if (focused) return focused+ const hovered = [...document.querySelectorAll('[data-kanban-card]')].filter((el) => el.matches(':hover'))+ return hovered.at(-1)?.getAttribute('data-kanban-card') ?? null+}++/** Focus a card and bring it into view. Compared by attribute, never interpolated into a selector:+ * node ids come from a git-shared file. */+function focusBoardCard(id: string): void {+ const el = [...document.querySelectorAll<HTMLElement>('[data-kanban-card]')].find(+ (c) => c.getAttribute('data-kanban-card') === id+ )+ if (!el) return+ el.focus({ preventScroll: true })+ el.scrollIntoView?.({ block: 'nearest', inline: 'nearest' })+}+/** Full-page session board OVER the canvas. The canvas stays mounted underneath (its* agent-status listeners must keep running, and display:none would 0×0-resize every* terminal into a tmux SIGWINCH) — this is an opaque overlay, nothing more.@@ -438,6 +460,60 @@ export const KanbanView = memo(function KanbanView({[board.columns, showClosed])+ // ── Keyboard (board.* registry commands, dispatched by Canvas through lib/boardKeys) ──────────+ // Board order = the session cards on screen, column by column (Ungrouped first), top to bottom —+ // exactly what the columns render, filters and hidden closed columns included. GitHub cards are+ // not in it: they open a different summary and are the provider's, not the board's.+ const navColumns = useMemo<string[][]>(() => {+ if (!sourceVisible(source, 'sessions')) return []+ return [+ columnCards.ungrouped.map((c) => c.id),+ ...shownColumns.map((col) => (columnCards.byColumn.get(col.id) ?? NO_CARDS).map((c) => c.id))+ ]+ }, [columnCards, shownColumns, source])+ const boardKeyRef = useRef<(action: BoardKeyAction) => boolean>(() => false)+ boardKeyRef.current = (action) => {+ const active = document.activeElement+ if (keyOwnedByControl(active, action)) return false+ if (cardMenu) return false+ const order = navColumns.flat()+ if (modalNodeId) {+ // Only while the card modal is the ONE dialog: anything stacked on it owns the keyboard.+ if (openDialogCount() !== 1) return false+ if (action !== 'next' && action !== 'prev') return false+ const target = stepCard(order, modalNodeId, action === 'next' ? 1 : -1)+ if (!target) return false+ setModalNodeId(target)+ return true+ }+ if (openDialogCount() > 0) return false+ const current = currentBoardCard(active)+ if (action === 'open') {+ if (!current) return false+ setModalNodeId(current)+ return true+ }+ const target =+ action === 'next' || action === 'prev'+ ? current+ ? stepCard(order, current, action === 'next' ? 1 : -1)+ : (action === 'next' ? order[0] : order.at(-1)) ?? null+ : current+ ? columnStep(navColumns, current, action === 'right' ? 1 : -1)+ : null+ if (!target) return false+ focusBoardCard(target)+ return true+ }+ useEffect(() => registerBoardKeys((action) => boardKeyRef.current(action)), [])+ // Closing the modal hands focus back to the card it last showed, so J/K carry on from there.+ const lastModalRef = useRef<string | null>(null)+ useEffect(() => {+ const was = lastModalRef.current+ lastModalRef.current = modalNodeId+ if (was && !modalNodeId) focusBoardCard(was)+ }, [modalNodeId])+// Stable column/card plumbing — every handler the memoized columns receive is identity-stable// across renders (the column binds its own id; cards bind theirs).const handleCardDragStart = useCallback((id: string) => {diff --git a/src/renderer/components/kanban/SessionCard.tsx b/src/renderer/components/kanban/SessionCard.tsxindex 25a2df124..54717d02d 100644--- a/src/renderer/components/kanban/SessionCard.tsx+++ b/src/renderer/components/kanban/SessionCard.tsx@@ -71,6 +71,10 @@ export const SessionCard = memo(function SessionCard({dropSide ? ` kanban-card--drop-${dropSide}` : ''}`}draggable+ // Focusable, and named for the board's keyboard (J/K/arrows walk these, Space opens one —+ // KanbanView's board-key handler finds the current card through this attribute).+ tabIndex={0}+ data-kanban-card={session.id}onDragStart={(e) => {e.dataTransfer.effectAllowed = 'move'setDragging(true)diff --git a/src/renderer/components/settings/ShortcutRecorderButton.tsx b/src/renderer/components/settings/ShortcutRecorderButton.tsxindex 5b070c2a5..d496da562 100644--- a/src/renderer/components/settings/ShortcutRecorderButton.tsx+++ b/src/renderer/components/settings/ShortcutRecorderButton.tsx@@ -76,7 +76,13 @@ export function ShortcutRecorderButton({// Did THIS instance arm the (global) main-process bit? See `release`.const armedRef = useRef(false)const def = COMMANDS_BY_ID.get(commandId)!- const opts = { isMac, allowHold: def.allowHoldChord === true }+ const opts = {+ isMac,+ allowHold: def.allowHoldChord === true,+ // Bare keys only where the registry lets the command have one; normalizeBindingForCommand+ // (below) still refuses a bare key a command's flags do not permit (e.g. Delete's SAFE set).+ allowBare: def.scope === 'board' || def.allowBareKey === true+ }// Refs only ⇒ stable with no deps, so the mount-time cleanup below cannot capture stale state,// and idempotent ⇒ running it twice, or on an unmount that was never armed, does nothing.diff --git a/src/renderer/components/settings/sections/ShortcutsSection.test.tsx b/src/renderer/components/settings/sections/ShortcutsSection.test.tsxindex 9306f3238..3fd8d5793 100644--- a/src/renderer/components/settings/sections/ShortcutsSection.test.tsx+++ b/src/renderer/components/settings/sections/ShortcutsSection.test.tsx@@ -181,11 +181,11 @@ describe('ShortcutsSection rows', () => {it('renders every group as its own divided block, rows packed inside it', () => {render()- expect(host.querySelectorAll('h3')).toHaveLength(6)+ expect(host.querySelectorAll('h3')).toHaveLength(7)expect(ids()).toHaveLength(COMMAND_DEFINITIONS.length)// The rows now live INSIDE their group's wrapper, so the shell's `divide-y` separates// GROUPS: the policy row + the filter rail + one block per group.- expect(body().children).toHaveLength(2 + 6)+ expect(body().children).toHaveLength(2 + 7)})// `settings.keybindings` is hand-editable JSON and `mergeSettings` passes it through with NOdiff --git a/src/renderer/components/settings/shortcutRecording.test.ts b/src/renderer/components/settings/shortcutRecording.test.tsindex c1a57a4b6..fc16edbf8 100644--- a/src/renderer/components/settings/shortcutRecording.test.ts+++ b/src/renderer/components/settings/shortcutRecording.test.ts@@ -60,6 +60,21 @@ describe('recordingKeydown', () => {expect(r.kind).toBe('pending')if (r.kind === 'pending') expect(r.state.mods).toBeNull()})+ // Board keys (J/K/Space/arrows) and the bare-key commands (Delete) are bare by default; a+ // recorder that could only capture Cmd+… could never set one back to a single key.+ it('a bare key commits as itself when the command allows bare keys', () => {+ const BARE = { isMac: true, allowHold: false, allowBare: true }+ expect(recordingKeydown({ mods: null }, e({ key: 'j' }), BARE)).toEqual({ kind: 'commit', combo: 'J' })+ expect(recordingKeydown({ mods: null }, e({ key: ' ' }), BARE)).toEqual({ kind: 'commit', combo: 'SPACE' })+ expect(recordingKeydown({ mods: null }, e({ key: 'ArrowDown' }), BARE)).toEqual({ kind: 'commit', combo: 'ARROWDOWN' })+ // Escape still cancels — it is the recorder's own exit, never a capture.+ expect(recordingKeydown({ mods: null }, e({ key: 'Escape' }), BARE)).toEqual({ kind: 'cancel' })+ // A modified press still captures the whole chord.+ expect(recordingKeydown({ mods: null }, e({ metaKey: true, key: 'j' }), BARE)).toEqual({ kind: 'commit', combo: 'Cmd+J' })+ })+ it('a bare key stays refused for every other command', () => {+ expect(recordingKeydown({ mods: null }, e({ key: 'j' }), KEYED).kind).toBe('pending')+ })it('modifier-only keydown without allowHold just previews the requirement', () => {const r = recordingKeydown({ mods: null }, e({ metaKey: true, key: 'Meta' }), KEYED)expect(r.kind).toBe('pending')diff --git a/src/renderer/components/settings/shortcutRecording.ts b/src/renderer/components/settings/shortcutRecording.tsindex d1a454fd3..5c0298add 100644--- a/src/renderer/components/settings/shortcutRecording.ts+++ b/src/renderer/components/settings/shortcutRecording.ts@@ -46,6 +46,7 @@*/import {buildModifierChord,+ captureBareKey,captureToShortcut,formatShortcut,isModifierEventKey,@@ -74,6 +75,9 @@ export interface RecordingOptions {/** The command's `allowHoldChord`. When false, a modifier-only gesture can never commit — it* only previews the requirement, and the user must go on to press a real key. */allowHold: boolean+ /** The command may be bound to a bare key (a board key, a bare-key canvas command): an+ * unmodified press commits as itself. Optional so every existing caller keeps its behavior. */+ allowBare?: boolean}/** Non-mac Meta (Super/Win): unspellable in this grammar, in both the keyed and hold paths. */@@ -119,6 +123,10 @@ export function recordingKeydown(}}+ if (opts.allowBare) {+ const bare = captureBareKey(e)+ if (bare) return { kind: 'commit', combo: bare }+ }const combo = captureToShortcut(e, isMac)if (combo) return { kind: 'commit', combo }// Refused: either the primary modifier is missing, or (off-mac) Super is held. Keep whateverdiff --git a/src/renderer/lib/boardKeyNav.test.ts b/src/renderer/lib/boardKeyNav.test.tsnew file mode 100644index 000000000..59c37e4ea--- /dev/null+++ b/src/renderer/lib/boardKeyNav.test.ts@@ -0,0 +1,93 @@+import { describe, expect, it, vi } from 'vitest'+import { columnStep, keyOwnedByControl, stepCard } from './boardKeyNav'+import { registerBoardKeys, runBoardKey } from './boardKeys'++const COLS = [['u1'], [], ['a1', 'a2', 'a3'], ['b1']]+const ORDER = COLS.flat()++describe('stepCard — board order is column by column, top to bottom', () => {+ it('moves to the neighbour', () => {+ expect(stepCard(ORDER, 'u1', 1)).toBe('a1')+ expect(stepCard(ORDER, 'a3', 1)).toBe('b1')+ expect(stepCard(ORDER, 'a1', -1)).toBe('u1')+ })++ it('stops at the ends (null = nothing to move to)', () => {+ expect(stepCard(ORDER, 'b1', 1)).toBeNull()+ expect(stepCard(ORDER, 'u1', -1)).toBeNull()+ })++ it('a card that is no longer on the board has no neighbour', () => {+ expect(stepCard(ORDER, 'gone', 1)).toBeNull()+ })+})++describe('columnStep', () => {+ it('jumps to the same row of the nearest NON-EMPTY column, clamped to its length', () => {+ expect(columnStep(COLS, 'a3', 1)).toBe('b1')+ expect(columnStep(COLS, 'a2', -1)).toBe('u1') // skips the empty column+ expect(columnStep(COLS, 'u1', 1)).toBe('a1')+ })++ it('is null at the edge of the board', () => {+ expect(columnStep(COLS, 'b1', 1)).toBeNull()+ expect(columnStep(COLS, 'u1', -1)).toBeNull()+ expect(columnStep(COLS, 'gone', 1)).toBeNull()+ })+})++const el = (tagName: string, attrs: Record<string, string> = {}): Element =>+ ({+ tagName,+ getAttribute: (k: string) => attrs[k] ?? null,+ closest: (sel: string) => (sel === '[data-kanban-card]' && attrs['data-kanban-card'] ? el(tagName, attrs) : null)+ }) as unknown as Element++describe('keyOwnedByControl — the board never takes a key the focused control uses', () => {+ it('a focused button keeps Space (native activation) but not J/K/arrows', () => {+ expect(keyOwnedByControl(el('BUTTON'), 'open')).toBe(true)+ expect(keyOwnedByControl(el('BUTTON'), 'next')).toBe(false)+ expect(keyOwnedByControl(el('A'), 'open')).toBe(true)+ })++ it('a <select> owns every key (arrows change it, letters type-ahead)', () => {+ for (const a of ['open', 'next', 'prev', 'left', 'right'] as const) {+ expect(keyOwnedByControl(el('SELECT'), a)).toBe(true)+ }+ })++ it('an ARIA composite widget owns every key', () => {+ expect(keyOwnedByControl(el('DIV', { role: 'listbox' }), 'next')).toBe(true)+ expect(keyOwnedByControl(el('DIV', { role: 'slider' }), 'left')).toBe(true)+ })++ it('a card, the body, or nothing owns no key', () => {+ expect(keyOwnedByControl(el('DIV', { 'data-kanban-card': 'a1' }), 'open')).toBe(false)+ expect(keyOwnedByControl(el('BODY'), 'open')).toBe(false)+ expect(keyOwnedByControl(null, 'next')).toBe(false)+ })+})++describe('boardKeys — the seam between the window dispatcher and the mounted board', () => {+ it('declines (falls through to the platform) when no board is registered', () => {+ expect(runBoardKey('next')).toBe(false)+ })++ it('hands the action to the registered board and returns its claim', () => {+ const handler = vi.fn(() => true)+ const off = registerBoardKeys(handler)+ expect(runBoardKey('open')).toBe(true)+ expect(handler).toHaveBeenCalledWith('open')+ off()+ expect(runBoardKey('open')).toBe(false)+ })++ it('an OLD registration’s cleanup never clears a newer one', () => {+ const first = registerBoardKeys(() => true)+ const second = vi.fn(() => true)+ registerBoardKeys(second)+ first()+ expect(runBoardKey('next')).toBe(true)+ expect(second).toHaveBeenCalled()+ })+})diff --git a/src/renderer/lib/boardKeyNav.ts b/src/renderer/lib/boardKeyNav.tsnew file mode 100644index 000000000..5b714b4d6--- /dev/null+++ b/src/renderer/lib/boardKeyNav.ts@@ -0,0 +1,59 @@+/**+ * Pure keyboard navigation over the kanban board: the order a J/K/arrow press walks, and which+ * focused controls own a key the board must therefore leave alone.+ */+import type { BoardKeyAction } from './boardKeys'++/** The neighbour of `current` in board order (`dir` 1 = next, -1 = previous), or null at an end+ * or when `current` is not on the board. */+export function stepCard(order: readonly string[], current: string, dir: 1 | -1): string | null {+ const i = order.indexOf(current)+ if (i === -1) return null+ return order[i + dir] ?? null+}++/** The card in the nearest NON-EMPTY column to the left/right of `current`, on the same row+ * (clamped to that column's length). Null at the board's edge. */+export function columnStep(+ columns: ReadonlyArray<readonly string[]>,+ current: string,+ dir: 1 | -1+): string | null {+ const col = columns.findIndex((c) => c.includes(current))+ if (col === -1) return null+ const row = columns[col].indexOf(current)+ for (let c = col + dir; c >= 0 && c < columns.length; c += dir) {+ const cards = columns[c]+ if (cards.length) return cards[Math.min(row, cards.length - 1)]+ }+ return null+}++/** ARIA composite widgets use arrows AND letters (type-ahead) for their own navigation. */+const COMPOSITE_ROLES = new Set([+ 'listbox', 'option', 'menu', 'menubar', 'menuitem', 'menuitemcheckbox', 'menuitemradio',+ 'slider', 'spinbutton', 'tab', 'tablist', 'radio', 'radiogroup', 'combobox', 'grid', 'gridcell',+ 'tree', 'treeitem', 'treegrid'+])+/** Controls that a Space press ACTIVATES natively. */+const SPACE_ACTIVATED = new Set(['BUTTON', 'A', 'SUMMARY', 'INPUT'])++/**+ * Does the focused element use this key itself? Then the board declines and the key reaches it.+ * (Text surfaces never get here: the registry refuses every board command while typing.)+ * - a `<select>` owns everything: arrows change its value, letters type-ahead;+ * - an ARIA composite widget owns everything, for the same reasons;+ * - a button, link, summary or checkbox owns Space — the key that presses it.+ * A card itself owns nothing: it is what the board's keys are for.+ */+export function keyOwnedByControl(el: Element | null, action: BoardKeyAction): boolean {+ if (!el) return false+ if (el.closest?.('[data-kanban-card]')) return false+ if (el.tagName === 'SELECT') return true+ const role = el.getAttribute?.('role')+ if (role && COMPOSITE_ROLES.has(role)) return true+ if (action === 'open') {+ return SPACE_ACTIVATED.has(el.tagName) || role === 'button' || role === 'checkbox' || role === 'switch'+ }+ return false+}diff --git a/src/renderer/lib/boardKeys.ts b/src/renderer/lib/boardKeys.tsnew file mode 100644index 000000000..d32ef8061--- /dev/null+++ b/src/renderer/lib/boardKeys.ts@@ -0,0 +1,28 @@+/**+ * The seam between the window keydown dispatcher (Canvas — the ONE registry dispatcher) and the+ * board that is on screen. Canvas owns the `board.*` handlers because it owns the dispatcher; the+ * board owns the cards. Module state rather than React context because the handler runs inside a+ * window keydown listener and must answer "claimed?" synchronously.+ *+ * With no board registered (the Omni view, or no board at all) every action DECLINES, so the key+ * falls through to the platform exactly as an unbound one would.+ */+export type BoardKeyAction = 'open' | 'next' | 'prev' | 'left' | 'right'++type Handler = (action: BoardKeyAction) => boolean++let current: Handler | null = null++/** Register the mounted board's handler; returns an unregister that only clears ITS registration+ * (a remount's new handler must survive the old one's cleanup, whatever order React runs them). */+export function registerBoardKeys(handler: Handler): () => void {+ current = handler+ return () => {+ if (current === handler) current = null+ }+}++/** Run a board action; true = the board claimed the key. */+export function runBoardKey(action: BoardKeyAction): boolean {+ return current ? current(action) : false+}diff --git a/src/renderer/lib/globalKeybindings.test.ts b/src/renderer/lib/globalKeybindings.test.tsindex 3079e50d3..79478e272 100644--- a/src/renderer/lib/globalKeybindings.test.ts+++ b/src/renderer/lib/globalKeybindings.test.ts@@ -193,3 +193,32 @@ describe('dispatchGlobalKeydown', () => {expect(captured).toEqual([])})})++// The board's bare keys ride the same one dispatcher. What makes a bare `j` safe is the resolver's+// refusals, so they are pinned here at the level a real keydown goes through.+describe('dispatchGlobalKeydown — board keys', () => {+ const textarea = (): ContextElement => ({ tagName: 'TEXTAREA', classList: { contains: () => false } })++ it('a bare j on an open board reaches board.nextCard and is claimed', () => {+ const next = vi.fn(() => true)+ const e = ev({ key: 'j' })+ expect(dispatchGlobalKeydown(e, deps({ kanbanOpen: () => true, handlers: { 'board.nextCard': next } }))).toBe(true)+ expect(next).toHaveBeenCalled()+ expect(e.defaultPrevented).toBe(true)+ })++ it('never on the canvas, never in the comment box, never in the modal terminal', () => {+ const next = vi.fn(() => true)+ const handlers = { 'board.nextCard': next }+ expect(dispatchGlobalKeydown(ev({ key: 'j' }), deps({ handlers }))).toBe(false)+ expect(dispatchGlobalKeydown(ev({ key: 'j' }), deps({ kanbanOpen: () => true, activeElement: textarea, handlers }))).toBe(false)+ expect(dispatchGlobalKeydown(ev({ key: 'j' }), deps({ kanbanOpen: () => true, activeElement: xtermEl, handlers }))).toBe(false)+ expect(next).not.toHaveBeenCalled()+ })++ it('a board that declines (nothing to move to) leaves the key to the platform', () => {+ const e = ev({ key: ' ' })+ expect(dispatchGlobalKeydown(e, deps({ kanbanOpen: () => true, handlers: { 'board.openCard': () => false } }))).toBe(false)+ expect(e.defaultPrevented).toBe(false)+ })+})diff --git a/src/renderer/lib/spacePan.test.ts b/src/renderer/lib/spacePan.test.tsindex 1f69e5258..2d22d4701 100644--- a/src/renderer/lib/spacePan.test.ts+++ b/src/renderer/lib/spacePan.test.ts@@ -18,6 +18,16 @@ describe('spacePanKeydown', () => {expect(spacePanKeydown({ key: ' ' }, el('BUTTON'))).toBe('engage')})+ // The kanban board covers the canvas while it is up (the canvas stays MOUNTED underneath), so a+ // pan there moves nothing anyone can see — and the capture-phase preventDefault used to swallow+ // every space on the board: a focused board button could not be pressed with it, and the board's+ // own Space ("open the focused card") never received it.+ it('never engages while the canvas is covered by a board', () => {+ expect(spacePanKeydown({ key: ' ' }, null, true)).toBe('ignore')+ expect(spacePanKeydown({ key: ' ' }, el('BUTTON'), true)).toBe('ignore')+ expect(spacePanKeydown({ key: ' ' }, null, false)).toBe('engage')+ })+it('NEVER takes a space that is being typed', () => {for (const target of [el('TEXTAREA'), el('INPUT'), el('DIV', true)]) {expect(spacePanKeydown({ key: ' ' }, target)).toBe('ignore')@@ -86,4 +96,9 @@ describe("React Flow's built-in space-pan (#930)", () => {const source = readFileSync('src/renderer/canvas/Canvas.tsx', 'utf8')expect(source).toContain('panActivationKeyCode={null}')})++ it('the canvas hands the covered-by-a-board fact to the decision (wiring pin)', () => {+ const source = readFileSync('src/renderer/canvas/Canvas.tsx', 'utf8')+ expect(source).toContain('spacePanKeydown(e, document.activeElement, covered)')+ })})diff --git a/src/renderer/lib/spacePan.ts b/src/renderer/lib/spacePan.tsindex 200c48614..309fb02a8 100644--- a/src/renderer/lib/spacePan.ts+++ b/src/renderer/lib/spacePan.ts@@ -49,9 +49,17 @@ export interface SpaceKeyEvent {* - the auto-REPEAT of a held key, so engaging happens once per press rather than sixty times a* second;* - anything typed into a terminal, a note or a field, which is the case that matters most: a- * space swallowed there is a wrong character in the user's text, not a missing pan.+ * space swallowed there is a wrong character in the user's text, not a missing pan;+ * - any space at all while a board covers the canvas (see `canvasCovered`).*/-export function spacePanKeydown(e: SpaceKeyEvent, active: Element | null): SpacePanAction {+export function spacePanKeydown(+ e: SpaceKeyEvent,+ active: Element | null,+ /** A board view covers the canvas (it stays mounted underneath): there is nothing to pan, and+ * the space belongs to the board — its focused buttons and its "open the card" key. */+ canvasCovered = false+): SpacePanAction {+ if (canvasCovered) return 'ignore'if (e.key !== ' ' && e.key !== 'Spacebar') return 'ignore'if (e.repeat) return 'ignore'if (e.ctrlKey || e.metaKey || e.altKey) return 'ignore'diff --git a/src/renderer/styles.css b/src/renderer/styles.cssindex be21bf22e..7198d7d0c 100644--- a/src/renderer/styles.css+++ b/src/renderer/styles.css@@ -11997,6 +11997,15 @@ button.group-node__setup:disabled {color: var(--accent);}+/* A card the board's keyboard is on (J/K/arrows move it, Space opens it). */+.kanban-card:focus {+ outline: none;+}+.kanban-card:focus-visible {+ outline: 2px solid var(--accent);+ outline-offset: 1px;+}+/* ── Board status chips (header) — transient filters on live agent state ── */.kanban-status-chips {display: inline-flex;diff --git a/src/shared/keybindings.test.ts b/src/shared/keybindings.test.tsindex ca8281251..5e96d5448 100644--- a/src/shared/keybindings.test.ts+++ b/src/shared/keybindings.test.ts@@ -159,6 +159,16 @@ describe('registry invariants', () => {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',@@ -312,8 +322,10 @@ describe('conflictBucket', () => {it('maps every command to its scope bucket, dictation excepted', () => {for (const def of COMMAND_DEFINITIONS) {if (def.id === 'speech.dictation') continue+ // 'board' joins the global keyspace for the same reason 'canvas' does: both dispatch from+ // the window listener, each merely inert while the other view is up.expect(conflictBucket(def)).toBe(- def.scope === 'app' || def.scope === 'canvas' ? 'global' : def.scope+ def.scope === 'app' || def.scope === 'canvas' || def.scope === 'board' ? 'global' : def.scope)}expect(conflictBucket(COMMANDS_BY_ID.get('speech.dictation')!)).toBe('dictation')@@ -640,3 +652,55 @@ describe('dictation conflict bucket', () => {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()+ })+})diff --git a/src/shared/keybindings.ts b/src/shared/keybindings.tsindex 9dd4d3afa..405e7c687 100644--- a/src/shared/keybindings.ts+++ b/src/shared/keybindings.ts@@ -16,8 +16,17 @@ import {} from './shortcut'import type { ShortcutKeyEvent } from './shortcut'-export type CommandScope = 'app' | 'canvas' | 'terminal' | 'scm'-export type CommandGroup = 'General' | 'Canvas' | 'Nodes' | 'Terminal' | 'Source Control' | 'Speech'+/** `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@@ -85,6 +94,11 @@ export type CommandId =| 'node.zoneDown'| 'node.close'| 'node.toggleMarkdown'+ | 'board.openCard'+ | 'board.nextCard'+ | 'board.prevCard'+ | 'board.columnLeft'+ | 'board.columnRight'| 'terminal.find'| 'terminal.copySelection'| 'scm.commit'@@ -237,6 +251,24 @@ export const COMMAND_DEFINITIONS: readonly CommandDefinition[] = [{ 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') },@@ -296,7 +328,10 @@ export function normalizeBindingForCommand(return { ok: true, value: serializeShortcut(p) }}const hasStrongModifier = p.cmd || p.ctrl || p.alt- if (!hasStrongModifier) {+ // 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.' }@@ -341,9 +376,10 @@ export function bindingIdentity(binding: string, isMac: boolean): string {].join('')}-/** Commands sharing a bucket compete for the same keys. 'app' and 'canvas' share one global- * keyspace (both dispatch from the window listener; canvas commands are merely inert while- * the board is open); terminal and scm are their own focused surfaces.+/** Commands sharing a bucket compete for the same keys. 'app', 'canvas' and 'board' share one+ * global keyspace (all dispatch from the window listener; canvas commands are merely inert while+ * the board is open, board commands while it is closed); 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 ===@@ -373,7 +409,7 @@ export function conflictBucket(def: Pick<CommandDefinition, 'id' | 'scope'>): 'global' | 'terminal' | 'scm' | 'dictation' {if (def.id === 'speech.dictation') return 'dictation'- return def.scope === 'app' || def.scope === 'canvas' ? 'global' : def.scope+ return def.scope === 'app' || def.scope === 'canvas' || def.scope === 'board' ? 'global' : def.scope}export interface KeybindingConflict {@@ -599,6 +635,7 @@ export function resolveCommandForKeyEvent(}if (!ctx.terminal && def.scope === 'terminal') continueif (ctx.kanbanOpen && def.scope === 'canvas') continue+ if (!ctx.kanbanOpen && def.scope === 'board') continuefor (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-nulldiff --git a/src/shared/shortcut.test.ts b/src/shared/shortcut.test.tsindex c7aba6afa..009ce3992 100644--- a/src/shared/shortcut.test.ts+++ b/src/shared/shortcut.test.ts@@ -181,6 +181,19 @@ describe('shortcutKeyParts', () => {describe('matchesShortcut', () => {const base = { metaKey: false, ctrlKey: false, shiftKey: false, altKey: false, key: 'd' }+ // The DOM reports the space bar as `e.key === ' '`, while the canonical token is `Space`. Without+ // mapping one onto the other, no `Space` binding could ever fire.+ it('matches the space bar against a Space binding', () => {+ expect(matchesShortcut({ ...base, key: ' ' }, 'Space', true)).toBe(true)+ expect(matchesShortcut({ ...base, key: ' ', metaKey: true }, 'Cmd+Space', true)).toBe(true)+ expect(matchesShortcut({ ...base, key: 'a' }, 'Space', true)).toBe(false)+ })++ it('captures the space bar as the canonical Space token', () => {+ expect(captureToShortcut({ ...base, key: ' ', metaKey: true }, true)).toBe('Cmd+SPACE')+ expect(parseShortcut(captureToShortcut({ ...base, key: ' ', metaKey: true }, true)!).key).toBe('SPACE')+ })+it('matches on mac with metaKey as the primary modifier', () => {expect(matchesShortcut({ ...base, metaKey: true, shiftKey: true }, 'Cmd+Shift+D', true)).toBe(truediff --git a/src/shared/shortcut.ts b/src/shared/shortcut.tsindex 5cf82bcc6..476259119 100644--- a/src/shared/shortcut.ts+++ b/src/shared/shortcut.ts@@ -57,8 +57,11 @@ const KEY_ALIASES: Record<string, string> = { COMMA: ',', SLASH: '/', PERIOD: '.const MODIFIER_KEYS = new Set(['META', 'CONTROL', 'CTRL', 'SHIFT', 'ALT', 'ALTGRAPH', 'OS'])/** `"d"` / `"D"` / `"Escape"` / `"F5"` -> the uppercased canonical key token; a punctuation alias- * (`"Comma"`) -> the character `e.key` actually reports (`","`). */+ * (`"Comma"`) -> the character `e.key` actually reports (`","`); the space bar (`" "`) -> `SPACE`. */function normalizeKey(key: string): string {+ // The DOM reports the space bar as a literal ' '; the canonical token is `SPACE` (a `Space`+ // binding could never match otherwise, and a captured space serialized as a trailing blank).+ if (key === ' ') return 'SPACE'const upper = key.toUpperCase()return KEY_ALIASES[upper] ?? upper}@@ -287,6 +290,18 @@ export function captureToShortcut(e: ShortcutKeyEvent, isMac: boolean): string |return parts.join('+')}+/**+ * A captured keydown with NO modifier held, as its canonical key token (`"j"` -> `"J"`, `" "` ->+ * `"SPACE"`), or null when a modifier is held or the key is itself a modifier. Only for commands+ * whose flags permit a bare binding (the board's keys, the bare-key canvas commands); the caller+ * still validates the result through `normalizeBindingForCommand`.+ */+export function captureBareKey(e: ShortcutKeyEvent): string | null {+ if (e.metaKey || e.ctrlKey || e.altKey || e.shiftKey) return null+ const key = normalizeKey(e.key)+ return MODIFIER_KEYS.has(key) ? null : key+}+/** The modifier state observed while capturing a would-be hold-to-talk chord (see* `buildModifierChord`). */export interface ChordModifiers {