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.

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.tsx
index 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') return
e.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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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 NO
diff --git a/src/renderer/components/settings/shortcutRecording.test.ts b/src/renderer/components/settings/shortcutRecording.test.ts
index 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.ts
index 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 whatever
diff --git a/src/renderer/lib/boardKeyNav.test.ts b/src/renderer/lib/boardKeyNav.test.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.css
index 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.ts
index 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.ts
index 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') 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
diff --git a/src/shared/shortcut.test.ts b/src/shared/shortcut.test.ts
index 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(
true
diff --git a/src/shared/shortcut.ts b/src/shared/shortcut.ts
index 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 {