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(shortcuts): derive the ⌘/ panel from the keybinding registry

enes4d7e5b6afa53
diff --git a/CLAUDE.md b/CLAUDE.md
index 7e3596bd7..480d2df0f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2058,6 +2058,31 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
(including a source-level wiring pin, since the menu leg lives against a real Menu in index.ts),
and `keybindingOverrides.test.ts` pins the renderer-to-xterm hand-off through
`terminalKeyAction`.
+ - **ShortcutsPanel is DERIVED from the registry, never a hand-written list.**
+ `buildShortcutSections` iterates `COMMAND_DEFINITIONS` — one section per `CommandGroup` in
+ registry source order, the label from `def.title`, and EVERY one of the command's EFFECTIVE
+ chords — and a command with no effective binding (ships unbound, or the user disabled it) is
+ OMITTED rather than shown chord-less. All chords, not just the first: off-mac
+ `terminal.copySelection` holds Ctrl+Shift+C AND Ctrl+Insert, and in the **Server Edition**
+ Chromium reserves Ctrl+Shift+C for the inspector un-preventably — so a first-chord-only row
+ advertised the one that cannot work there. The panel it replaced enumerated 24 ids by hand against a
+ 45-command registry, so ⌘⇧T (reopen last closed), ⌘⇧↵ (maximize node), the ⌃⌥arrow zone snaps
+ and Copy terminal selection were live chords it never mentioned, and no ships-unbound command
+ could ever appear even after the user assigned one. `ShortcutsPanel.test.tsx` is the watchdog:
+ it binds every registry command and asserts a row per `def.title`, so a new command that fails
+ to surface reds it. Same stale-doc rule as the canvas-control skill body (#269) — derive the
+ text, don't retype it.
+ Rows the registry does NOT own (mouse gestures, the two `zoomShortcut.ts` chords, the ⌘1-9
+ project jump, tmux/xterm terminal behaviors) are literal, and still read from settings where
+ the behavior does: the hover dwell prints `panHoverDelay` and the drag rows follow
+ `canvasDragMode`, because the old fixed text claimed 0.6 s and a right-drag pan React Flow
+ (`panOnDrag={[1]}`, middle button only) has never done.
+ **One honest exception to "the chord shown is the chord that fires":** `terminal.copySelection`
+ is a registry row whose matcher is still the hardcoded `isCopyShortcut`
+ (`terminalKeyAction` keeps the copy chords and Shift+Enter "whatever the registry says"). Its
+ registry defaults match that matcher on both platforms, so the row is accurate as shipped; a
+ REMAP of it would not be, on this panel or in Settings. Wiring `isCopyShortcut` to the registry
+ is the fix.
- **`terminalFocused` is a MIRROR, and its fail-safe direction is `false` = not focused =
intercepts ON.** `renderer/lib/terminalFocusMirror.ts` reports focus changes to main and is
change-deduped (it never re-asserts), so a page that died mid-report, a reload, or a window that
@@ -2414,6 +2439,7 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
pan-hover delay, double-click focus, accent, tmux on/scrollback, commit agent,
`seenShortcuts`.
- **Shortcuts** (`ShortcutsPanel.tsx`, ? / ⌘/): shown once on first launch (`seenShortcuts`).
+ **Derived from the registry, never hand-listed** — see the Keybindings invariant below.
- **Welcome** (`WelcomeScreen.tsx`): shown when no projects exist.
- **Window chrome**: macOS integrated title bar (`titleBarStyle: 'hiddenInset'`); the tab
bar (`TabBar.tsx`) is the drag region with the `nodeterm` logo + a rounded pill of project
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f0d2e3c49..0c3f1fa5f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -186,6 +186,14 @@ its accelerator) — and Reload (⌘R / ⌘⇧R) is the named exception that alw
because it is the crash-recovery lever. Browsers own a different set. And any chord that reaches the canvas needs the two refusals every canvas shortcut
here has: not while the kanban board covers it, not while the user is typing.
+**A new chord needs no edit to the shortcuts panel — and must not get one.** `ShortcutsPanel`
+derives its whole inventory from `COMMAND_DEFINITIONS` (section per `CommandGroup`, label from
+`def.title`, chord from the EFFECTIVE binding), so adding a registry command is all it takes to
+make it show up; a command with no effective binding is omitted rather than listed chord-less.
+`ShortcutsPanel.test.tsx` is the watchdog and reds if a command fails to surface. The panel it
+replaced hand-listed 24 ids against a 45-command registry and had drifted four live chords behind
+— if you find yourself typing a command id into that file, that is the bug reappearing.
+
**Comments explain WHY, and name the failure they prevent.** The codebase is deliberately dense with
reasoning. A comment that restates the code is noise; one that says "do not simplify this back,
here is what broke" is the point.
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index c4e6268eb..eeb6fb07c 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -12565,7 +12565,18 @@ export function Canvas() {
/>
)}
- {shortcutsOpen && <ShortcutsPanel onClose={() => setShortcutsOpen(false)} />}
+ {shortcutsOpen && (
+ <ShortcutsPanel
+ onClose={() => setShortcutsOpen(false)}
+ // The panel lists what is BOUND; the whole remappable pool (and every command that
+ // ships without a chord) lives in Settings → Keyboard Shortcuts.
+ onCustomize={() => {
+ setShortcutsOpen(false)
+ setSettingsSection('shortcuts')
+ setSettingsOpen(true)
+ }}
+ />
+ )}
{mobileLaunchOpen && (
<MobileLaunchCard
onClose={() => {
diff --git a/src/renderer/components/ShortcutsPanel.test.tsx b/src/renderer/components/ShortcutsPanel.test.tsx
new file mode 100644
index 000000000..cf99327de
--- /dev/null
+++ b/src/renderer/components/ShortcutsPanel.test.tsx
@@ -0,0 +1,261 @@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+ COMMAND_DEFINITIONS,
+ getEffectiveBindings,
+ normalizeBindingForCommand,
+ sanitizeKeybindingOverrides,
+ type CommandId
+} from '@shared/keybindings'
+import { DEFAULT_SETTINGS } from '@shared/types'
+import { useSettings } from '../state/settings'
+import { buildShortcutSections, ShortcutsPanel, type ShortcutSectionsOptions } from './ShortcutsPanel'
+
+vi.mock('../bridge/runtime', () => ({ isBrowserRuntime: () => false }))
+
+const BASE: Omit<ShortcutSectionsOptions, 'bindingsFor'> = {
+ isMac: true,
+ browser: false,
+ panHoverDelay: DEFAULT_SETTINGS.panHoverDelay,
+ dragMode: 'select',
+ doubleClickFocus: true,
+ wheelZoom: false
+}
+
+const build = (
+ bindingsFor: (id: CommandId) => readonly string[],
+ over: Partial<ShortcutSectionsOptions> = {}
+) => buildShortcutSections({ ...BASE, ...over, bindingsFor })
+
+const labelsOf = (sections: ReturnType<typeof buildShortcutSections>): string[] =>
+ sections.flatMap((s) => s.rows.map((r) => r.label))
+
+/** The row's FIRST chord — the shape most assertions care about. */
+const rowFor = (
+ sections: ReturnType<typeof buildShortcutSections>,
+ label: string
+): string[] | undefined =>
+ sections.flatMap((s) => s.rows).find((r) => r.label === label)?.chords[0]
+
+/** EVERY chord on the row. */
+const chordsFor = (
+ sections: ReturnType<typeof buildShortcutSections>,
+ label: string
+): string[][] | undefined =>
+ sections.flatMap((s) => s.rows).find((r) => r.label === label)?.chords
+
+/** Every command bound to its OWN distinct chord, so nothing is dropped as unbound and no two
+ * rows collide. Keys are drawn from a pool wide enough for the whole registry, and each chord
+ * is validated the way settings.json would be — a pool that ran out, or a chord a command's own
+ * flags refuse, must fail loudly here rather than silently shrink the expected row set. */
+function bindEverything(isMac: boolean): (id: CommandId) => readonly string[] {
+ const pool = [
+ ...'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split(''),
+ ...'0123456789'.split(''),
+ ...Array.from({ length: 12 }, (_, i) => `F${i + 1}`)
+ ]
+ expect(pool.length).toBeGreaterThanOrEqual(COMMAND_DEFINITIONS.length)
+ const map = new Map<CommandId, string[]>()
+ COMMAND_DEFINITIONS.forEach((def, i) => {
+ const chord = `Cmd+Alt+Shift+${pool[i]}`
+ const r = normalizeBindingForCommand(def, chord, isMac)
+ expect(r.ok, `${def.id} refused ${chord}`).toBe(true)
+ map.set(def.id, [r.ok ? r.value : chord])
+ })
+ return (id) => map.get(id) ?? []
+}
+
+describe('buildShortcutSections — registry parity (watchdog)', () => {
+ // THE guard: the panel derives its inventory from COMMAND_DEFINITIONS, so a command added to
+ // the registry shows up here without an edit to ShortcutsPanel.tsx. A hand-written list — the
+ // shape this file replaced, which had drifted 21 commands behind — reds this test.
+ it('renders a row for EVERY registry command when all are bound', () => {
+ const labels = labelsOf(build(bindEverything(true)))
+ for (const def of COMMAND_DEFINITIONS) {
+ // speech.dictation is the one row whose label is decorated by chord shape; a keyed chord
+ // (which bindEverything hands it) keeps the bare title.
+ expect(labels, `missing registry command: ${def.id}`).toContain(def.title)
+ }
+ })
+
+ it('puts each command under its own registry group, in registry order', () => {
+ const sections = build(bindEverything(true))
+ for (const def of COMMAND_DEFINITIONS) {
+ const section = sections.find((s) => s.rows.some((r) => r.label === def.title))
+ expect(section?.title, `${def.id} landed in the wrong section`).toBe(def.group)
+ }
+ const groups = sections.map((s) => s.title)
+ const expected: string[] = []
+ for (const d of COMMAND_DEFINITIONS) if (!expected.includes(d.group)) expected.push(d.group)
+ expect(groups.slice(0, expected.length)).toEqual(expected)
+ })
+
+ it('shows every command that ships with a default chord on this platform', () => {
+ for (const isMac of [true, false]) {
+ const labels = labelsOf(
+ build((id) => getEffectiveBindings(id, {}, isMac), { isMac })
+ )
+ for (const def of COMMAND_DEFINITIONS) {
+ const bound = (isMac ? def.defaultBindings.darwin : def.defaultBindings.other).length > 0
+ if (!bound) continue
+ // speech.dictation's default IS a hold chord, so its row carries the "(hold)" suffix —
+ // the one command whose label is decorated by the shape of the chord it resolved to.
+ const shown = labels.some((l) => l === def.title || l === `${def.title} (hold)`)
+ expect(shown, `${def.id} (isMac=${isMac}) missing from the panel`).toBe(true)
+ }
+ }
+ })
+})
+
+describe('buildShortcutSections — bindings', () => {
+ it('omits a command with no effective binding', () => {
+ const labels = labelsOf(build((id) => getEffectiveBindings(id, {}, true)))
+ // Ships unbound on purpose (it expands the remappable pool), so it advertises no key.
+ expect(labels).not.toContain('New sticky note')
+ })
+
+ it('omits a command the user DISABLED, and follows one they remapped', () => {
+ const { overrides } = sanitizeKeybindingOverrides(
+ { 'app.commandPalette': [], 'canvas.tidy': ['Cmd+Alt+Shift+F9'] },
+ true
+ )
+ const sections = build((id) => getEffectiveBindings(id, overrides, true))
+ expect(labelsOf(sections)).not.toContain('Command palette')
+ expect(rowFor(sections, 'Tidy canvas')).toEqual(['⌘', '⌥', '⇧', 'F9'])
+ })
+
+ it('shows EVERY effective chord of a multi-binding command', () => {
+ const sections = build((id) => getEffectiveBindings(id, {}, false), { isMac: false })
+ expect(chordsFor(sections, 'Redo')).toEqual([
+ ['Ctrl', 'Shift', 'Z'],
+ ['Ctrl', 'Y']
+ ])
+ // The one that matters: off-mac Chromium reserves Ctrl+Shift+C for the inspector and a page
+ // cannot preventDefault it, so in the Server Edition Ctrl+Insert is the ONLY chord that
+ // copies. Printing the first chord alone advertised the broken one.
+ expect(chordsFor(sections, 'Copy terminal selection')).toEqual([
+ ['Ctrl', 'Shift', 'C'],
+ ['Ctrl', 'Insert']
+ ])
+ // Same reason on the canvas: Delete and Backspace both delete.
+ expect(chordsFor(sections, 'Delete selection')).toEqual([['Delete'], ['Backspace']])
+ })
+
+ it('spells the dictation row by the CHORD SHAPE, never settings.speech.shortcut', () => {
+ const hold = build((id) => getEffectiveBindings(id, {}, true))
+ expect(labelsOf(hold)).toContain('Dictate (hold)')
+ const keyed = build((id) =>
+ getEffectiveBindings(id, { 'speech.dictation': ['Cmd+Alt+Shift+D'] }, true)
+ )
+ expect(labelsOf(keyed)).toContain('Dictate')
+ expect(labelsOf(keyed)).not.toContain('Dictate (hold)')
+ // Disabled: `isHoldChord('')` is TRUE, so a missing `chord !== ''` check would print a
+ // "(hold)" row for a shortcut the user turned off.
+ const off = build((id) => getEffectiveBindings(id, { 'speech.dictation': [] }, true))
+ expect(labelsOf(off).filter((l) => l.startsWith('Dictate'))).toEqual([])
+ })
+})
+
+describe('buildShortcutSections — platform and non-command rows', () => {
+ it('renders mac glyphs on mac and Ctrl/Shift words elsewhere', () => {
+ const mac = build((id) => getEffectiveBindings(id, {}, true), { isMac: true })
+ expect(rowFor(mac, 'Command palette')).toEqual(['⌘', 'K'])
+ const other = build((id) => getEffectiveBindings(id, {}, false), { isMac: false })
+ expect(rowFor(other, 'Command palette')).toEqual(['Ctrl', 'K'])
+ })
+
+ it('drops the ⌘1-9 project jump in the Server Edition (the browser owns it)', () => {
+ const desktop = build(() => [], { browser: false })
+ expect(labelsOf(desktop)).toContain('Jump to project')
+ const browser = build(() => [], { browser: true })
+ expect(labelsOf(browser)).not.toContain('Jump to project')
+ })
+
+ it('swaps the drag rows with settings.canvasDragMode', () => {
+ const select = build(() => [], { dragMode: 'select' })
+ expect(rowFor(select, 'Box-select (touch to select)')).toEqual(['Left-drag'])
+ expect(rowFor(select, 'Pan the canvas')).toEqual(['Middle-drag'])
+ const pan = build(() => [], { dragMode: 'pan' })
+ expect(rowFor(pan, 'Pan the canvas')).toEqual(['Left-drag'])
+ expect(rowFor(pan, 'Box-select (touch to select)')).toEqual(['⇧', 'drag'])
+ })
+
+ it('prints the live hover dwell, not a baked-in 0.6s', () => {
+ expect(rowFor(build(() => [], { panHoverDelay: 250 }), 'Enter the terminal (type / select)'))
+ .toEqual(['Hover 0.3s'])
+ expect(rowFor(build(() => [], { panHoverDelay: 600 }), 'Enter the terminal (type / select)'))
+ .toEqual(['Hover 0.6s'])
+ })
+
+ it('names the force-select modifier per platform (Option on mac, Shift elsewhere)', () => {
+ const label = 'Select in the emulator (apps that grab the mouse)'
+ expect(rowFor(build(() => [], { isMac: true }), label)).toEqual(['⌥', 'drag'])
+ expect(rowFor(build(() => [], { isMac: false }), label)).toEqual(['Shift', 'drag'])
+ })
+
+ it('gives every row in a section a distinct label (they key the rendered list)', () => {
+ for (const s of build(bindEverything(true), { wheelZoom: true, dragMode: 'pan' })) {
+ const labels = s.rows.map((r) => r.label)
+ expect(new Set(labels).size, `duplicate label in ${s.title}`).toBe(labels.length)
+ }
+ })
+})
+
+describe('ShortcutsPanel (DOM)', () => {
+ ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+ let root: Root | null = null
+
+ afterEach(() => {
+ act(() => root?.unmount())
+ root = null
+ document.body.innerHTML = ''
+ useSettings.setState({ settings: { ...DEFAULT_SETTINGS } })
+ })
+
+ const render = (props: Partial<Parameters<typeof ShortcutsPanel>[0]> = {}): void => {
+ const host = document.createElement('div')
+ document.body.appendChild(host)
+ root = createRoot(host)
+ act(() => root!.render(<ShortcutsPanel onClose={() => {}} {...props} />))
+ }
+
+ const rowLabels = (): string[] =>
+ [...document.querySelectorAll('.shortcut-label')].map((n) => n.textContent ?? '')
+
+ it('reads the live override map through the settings store', () => {
+ useSettings.setState({
+ settings: { ...DEFAULT_SETTINGS, keybindings: { 'canvas.tidy': [] } as never }
+ })
+ render()
+ expect(rowLabels()).toContain('Command palette')
+ expect(rowLabels()).not.toContain('Tidy canvas')
+ })
+
+ it('separates a row\'s alternative chords rather than printing one run of badges', () => {
+ render()
+ const row = [...document.querySelectorAll('.shortcut-row')].find(
+ (n) => n.querySelector('.shortcut-label')?.textContent === 'Delete selection'
+ )
+ expect(row).toBeTruthy()
+ expect(row!.querySelectorAll('.shortcut-or').length).toBe(1)
+ expect([...row!.querySelectorAll('.kbd')].map((n) => n.textContent)).toEqual([
+ 'Delete',
+ 'Backspace'
+ ])
+ })
+
+ it('offers the Settings route only when the host wires it', () => {
+ render()
+ expect(document.querySelector('.shortcuts__customize')).toBeNull()
+ act(() => root!.unmount())
+ document.body.innerHTML = ''
+ const onCustomize = vi.fn()
+ render({ onCustomize })
+ const btn = document.querySelector('.shortcuts__customize') as HTMLButtonElement
+ expect(btn).not.toBeNull()
+ act(() => btn.click())
+ expect(onCustomize).toHaveBeenCalledOnce()
+ })
+})
diff --git a/src/renderer/components/ShortcutsPanel.tsx b/src/renderer/components/ShortcutsPanel.tsx
index a2b708782..0fab4ead6 100644
--- a/src/renderer/components/ShortcutsPanel.tsx
+++ b/src/renderer/components/ShortcutsPanel.tsx
@@ -1,134 +1,212 @@
-import { useEffect } from 'react'
+/**
+ * The ⌘/ keyboard-shortcuts reference, DERIVED FROM THE REGISTRY.
+ *
+ * Every command row is produced by iterating `COMMAND_DEFINITIONS` — one section per
+ * `CommandGroup` in registry source order, one row per command, the label from `def.title` and
+ * EVERY one of the command's EFFECTIVE chords (`effectiveBindings` — the user's override when
+ * there is one). Nothing here enumerates command ids by hand, so a command added to the
+ * registry appears in this panel on the same commit, and one that is renamed cannot keep an old
+ * label here. That is the whole point: the previous version listed 24 ids by hand against a
+ * 45-command registry, so ⌘⇧T (reopen last closed), ⌘⇧↵ (maximize node), the ⌃⌥arrow zone snaps
+ * and Copy terminal selection were all live chords the panel never mentioned, and every
+ * ships-unbound command stayed invisible even after the user assigned it a chord.
+ * `ShortcutsPanel.test.tsx` is the watchdog (a new registry command that fails to show up reds it).
+ *
+ * **Unbound and user-disabled commands are omitted**, not listed as "none": the panel answers
+ * "which keys do things", and a row with no chord answers nothing. Settings → Keyboard Shortcuts
+ * is the surface that shows the whole pool, which is what the footer link points at.
+ *
+ * **Rows that are NOT registry commands** live in `extraRows` / `behaviorRows`: mouse gestures,
+ * the two zoom chords (`lib/zoomShortcut.ts`), the ⌘1-9 project jump (`lib/projectJump.ts`) and
+ * the terminal's own behaviors. They are literal because the registry does not know them — but
+ * they are still DERIVED from settings wherever the behavior is: the hover dwell prints
+ * `settings.panHoverDelay`, and the drag rows follow `settings.canvasDragMode`, because the panel
+ * used to claim a fixed 0.6 s and a right-drag pan that React Flow (`panOnDrag={[1]}` — middle
+ * button only) has never done.
+ *
+ * **One honest exception to "the chord you see is the chord that fires":** `terminal.copySelection`
+ * is a registry row whose matcher is still the hardcoded `isCopyShortcut` in
+ * `terminal/terminal-config.ts` ("the copy chords and Shift+Enter keep their existing owners
+ * whatever the registry says" — `terminalKeyAction`). Its registry DEFAULTS match that matcher on
+ * both platforms, so the row is accurate as shipped; a remap of it would not be. Settings already
+ * offers the same row on the same terms, so the panel does not second-guess it — wiring
+ * `isCopyShortcut` to the registry is the fix, and it is not this change.
+ */
+import { Fragment, useEffect } from 'react'
import { createPortal } from 'react-dom'
import { isHoldChord, shortcutKeyParts } from '@shared/shortcut'
-import type { CommandId } from '@shared/keybindings'
+import {
+ COMMAND_DEFINITIONS,
+ type CommandGroup,
+ type CommandId
+} from '@shared/keybindings'
+import { isMacPlatform, keyLabel } from '@shared/platform-utils'
import { isBrowserRuntime } from '../bridge/runtime'
-import { commandKeys, dictationBinding } from '../lib/keybindingOverrides'
+import { effectiveBindings } from '../lib/keybindingOverrides'
import { useSettings } from '../state/settings'
-const isMac = /Mac/i.test(navigator.platform || navigator.userAgent)
-import { keyLabel } from '@shared/platform-utils'
-
export interface ShortcutsPanelProps {
onClose: () => void
+ /** Route into Settings → Keyboard Shortcuts. Optional so the panel renders standalone. */
+ onCustomize?: () => void
}
-interface Row {
- keys: string[]
+export interface ShortcutRow {
+ /** One entry per EFFECTIVE chord, each already split into display badges. A command may hold
+ * several and the extras are not interchangeable: `canvas.deleteSelection` ships Delete AND
+ * Backspace, and `terminal.copySelection` ships Ctrl+Shift+C AND Ctrl+Insert off-mac — where
+ * Chromium reserves Ctrl+Shift+C for the inspector and a page cannot take it back, so in the
+ * Server Edition Ctrl+Insert is the ONLY one that copies. Printing just the first chord
+ * advertised the broken one there. */
+ chords: string[][]
label: string
}
-/** Registry rows derive their keys from the effective binding, so a remap in settings.json
- * shows up here without touching this file — and a command the user unbound (or that ships
- * unassigned) drops off the panel instead of advertising a chord that no longer fires.
- * That promise holds because every row's KEYBOARD path also reads the registry, which is
- * what makes the panel and the key agree — `terminal.find` included, whose match in
- * TerminalNode now reads `effectiveBindings('terminal.find')` instead of a hardcoded
- * Cmd/Ctrl+F. Gesture/mouse rows stay literal: they are not commands and the registry knows
- * nothing about them. "Dictate" is a registry row too now — its chord comes from
- * `dictationBinding()` (the first effective `speech.dictation` binding), with the legacy
- * `settings.speech.shortcut` field kept only as a downgrade mirror — so it follows a remap and
- * DROPS off the panel when the user unbinds it, exactly like every `cmd()` row above. It keeps
- * its own builder because it is the one row whose LABEL depends on the chord's shape: a
- * modifier-only chord is hold-to-talk, which "Dictate (hold)" spells out. */
-function buildSections(dictationChord: string): { title: string; rows: Row[] }[] {
- const cmd = (id: CommandId, label: string): Row[] => {
- const keys = commandKeys(id)
- return keys.length ? [{ keys, label }] : []
+export interface ShortcutSection {
+ title: string
+ rows: ShortcutRow[]
+}
+
+export interface ShortcutSectionsOptions {
+ isMac: boolean
+ /** Server Edition (browser tab): a couple of chords are the browser's and can never fire. */
+ browser: boolean
+ /** `settings.panHoverDelay`, ms. */
+ panHoverDelay: number
+ /** `settings.canvasDragMode` — decides which button box-selects and which pans. */
+ dragMode: 'select' | 'pan'
+ /** `settings.doubleClickFocus`. */
+ doubleClickFocus: boolean
+ /** `settings.wheelZoom` — a plain wheel zooms too. */
+ wheelZoom: boolean
+ /** Canonical effective binding strings for a command; `[]` when unbound or disabled. */
+ bindingsFor: (id: CommandId) => readonly string[]
+}
+
+/** The section order IS the registry's group order (first appearance), so a new `CommandGroup`
+ * gets its own section without an edit here. */
+function groupOrder(): CommandGroup[] {
+ const seen: CommandGroup[] = []
+ for (const def of COMMAND_DEFINITIONS) if (!seen.includes(def.group)) seen.push(def.group)
+ return seen
+}
+
+/** The one row whose LABEL depends on the chord's SHAPE: a modifier-only dictation chord is
+ * hold-to-talk, which the title alone does not say. `isHoldChord('')` is TRUE, so the empty
+ * chord (dictation disabled) is checked first — but such a row is dropped before it gets here. */
+function rowLabel(id: CommandId, title: string, chord: string): string {
+ if (id === 'speech.dictation' && chord !== '' && isHoldChord(chord)) return `${title} (hold)`
+ return title
+}
+
+/** A literal (non-command) row: one chord, spelled out. */
+const row = (keys: string[], label: string): ShortcutRow => ({ chords: [keys], label })
+
+/** Gesture / non-command rows appended under a registry group. */
+function extraRows(group: CommandGroup, o: ShortcutSectionsOptions): ShortcutRow[] {
+ if (group === 'General') {
+ // Desktop only: browsers own Cmd/Ctrl+1-9 for tab switching and a page cannot take it back
+ // (lib/projectJump.ts rule 1), so listing it in the Server Edition would promise a shortcut
+ // that never fires.
+ return o.browser ? [] : [row(['⌘', '1-9'], 'Jump to project')]
+ }
+ if (group === 'Canvas') {
+ return [
+ row(['Right-click'], 'Actions menu (empty space or node)'),
+ // React Flow's `selectionOnDrag` / `panOnDrag` follow settings.canvasDragMode, so these
+ // two rows swap with it rather than describing only the default.
+ ...(o.dragMode === 'pan'
+ ? [
+ row(['Left-drag'], 'Pan the canvas'),
+ row(['⇧', 'drag'], 'Box-select (touch to select)')
+ ]
+ : [
+ row(['Left-drag'], 'Box-select (touch to select)'),
+ row(['Middle-drag'], 'Pan the canvas')
+ ]),
+ row(['Space', 'drag'], 'Pan the canvas (any drag mode)'),
+ row(['⇧', 'click'], 'Add a node to the selection'),
+ ...(o.doubleClickFocus
+ ? [row(['Double-click'], 'Center & focus a node')]
+ : []),
+ row(['⌘', 'wheel'], 'Zoom in / out'),
+ ...(o.wheelZoom ? [row(['Wheel'], 'Zoom in / out (plain wheel)')] : []),
+ // Advertised on BOTH surfaces, unlike "Jump to project" above. ⌘1-9 is dropped there
+ // because the browser RESERVES it (tab switching, un-preventable) for something unrelated;
+ // ⌘0 is neither — it is not in the reserved set, so the page gets the keydown, and even
+ // where a browser insists on handling it too it means the same thing we do ("actual size").
+ // Shift+1 is nobody else's key on any surface. Both live in lib/zoomShortcut.ts, which is
+ // matched on `e.code` and therefore is not a registry binding.
+ row(['⌘', '0'], 'Zoom to 100%'),
+ row(['⇧', '1'], 'Fit view')
+ ]
}
- const dictate = (): Row[] =>
- dictationChord === ''
- ? []
- : [
- {
- keys: shortcutKeyParts(dictationChord, isMac),
- label: isHoldChord(dictationChord) ? 'Dictate (hold)' : 'Dictate'
- }
- ]
+ return []
+}
+
+/** Terminal facts the registry knows nothing about: tmux owns the mouse, xterm owns two remaps,
+ * and the hover guard owns the first ~half second. Each verified against the code that
+ * implements it (see CLAUDE.md "tmux owns the mouse" and terminal/terminal-config.ts). */
+function behaviorRows(o: ShortcutSectionsOptions): ShortcutRow[] {
+ const seconds = Math.round(o.panHoverDelay / 100) / 10
+ const forceSelect = o.isMac ? '⌥' : 'Shift'
return [
- {
- title: 'General',
- rows: [
- ...cmd('app.commandPalette', 'Command palette'),
- ...cmd('app.settings', 'Settings'),
- ...cmd('app.shortcutsPanel', 'This shortcuts panel'),
- ...cmd('panel.explorer', 'Explorer'),
- // `panel.sourceControl` used to be listed here AND in the Source Control section below —
- // one command, two rows, both showing the same chord. The section row ("Open Source
- // Control") is the one that belongs, so the General duplicate is gone.
- ...cmd('view.kanbanToggle', 'Kanban board'),
- ...cmd('panel.sessions', 'Pin the sessions sidebar'),
- // Desktop only: browsers own Cmd/Ctrl+1-9 for tab switching and a page cannot take it
- // back, so listing it in the Server Edition would promise a shortcut that never fires.
- ...(isBrowserRuntime() ? [] : [{ keys: ['⌘', '1-9'], label: 'Jump to project' }]),
- ...dictate(),
- ...cmd('canvas.undo', 'Undo'),
- ...cmd('canvas.redo', 'Redo'),
- ...cmd('canvas.goBack', 'Go back'),
- ...cmd('canvas.goForward', 'Go forward')
- ]
- },
- {
- title: 'Canvas',
- rows: [
- ...cmd('node.newTerminal', 'New terminal'),
- ...cmd('node.newAgent', 'New Claude Code'),
- ...cmd('node.close', 'Close selected node'),
- ...cmd('canvas.deleteSelection', 'Delete selection'),
- // One row per direction rather than a single collapsed "⌘ ← → ↑ ↓": each is its own
- // command, so a user who remapped or unbound only ⌘↑ must see exactly that.
- ...cmd('node.focusLeft', 'Focus the node to the left'),
- ...cmd('node.focusRight', 'Focus the node to the right'),
- ...cmd('node.focusUp', 'Focus the node above'),
- ...cmd('node.focusDown', 'Focus the node below'),
- { keys: ['Right-click'], label: 'Actions menu (empty space or node)' },
- { keys: ['Left-drag'], label: 'Box-select (touch to select)' },
- { keys: ['Middle / Right-drag'], label: 'Pan the canvas' },
- { keys: ['Double-click'], label: 'Center & focus a node' },
- ...cmd('view.focusMode', 'Focus mode (selected node fills the window)'),
- { keys: ['⌘', 'wheel'], label: 'Zoom in / out' },
- // Advertised on BOTH surfaces, unlike "Jump to project" above. ⌘1-9 is dropped there
- // because the browser RESERVES it (tab switching, un-preventable) for something unrelated;
- // ⌘0 is neither — it is not in the reserved set, so the page gets the keydown, and even
- // where a browser insists on handling it too it means the same thing we do ("actual size")
- // instead of fighting us. Shift+1 is nobody else's key on any surface.
- { keys: ['⌘', '0'], label: 'Zoom to 100%' },
- { keys: ['⇧', '1'], label: 'Fit view' },
- ...cmd('canvas.tidy', 'Tidy canvas')
- ]
- },
- {
- title: 'Terminal',
- rows: [
- { keys: ['Hover ~0.6s'], label: 'Enter the terminal (type/select)' },
- { keys: ['Quick drag'], label: 'Move the terminal (before it focuses)' },
- ...cmd('node.toggleMarkdown', 'Toggle markdown view'),
- ...cmd('terminal.find', 'Find in terminal'),
- { keys: ['⌘', 'C'], label: 'Copy selection (markdown view)' },
- { keys: ['✦'], label: 'Name the terminal with AI' }
- ]
- },
- {
- title: 'Source Control',
- rows: [
- ...cmd('panel.sourceControl', 'Open Source Control'),
- ...cmd('scm.commit', 'Commit the staged changes')
- ]
- }
+ row([`Hover ${seconds}s`], 'Enter the terminal (type / select)'),
+ row(['Quick drag'], 'Move the terminal (before it focuses)'),
+ row(['Wheel'], "Scroll tmux's own history"),
+ row(['Drag'], 'Select — copies to the system clipboard'),
+ row([forceSelect, 'drag'], 'Select in the emulator (apps that grab the mouse)'),
+ row(['⇧', 'Enter'], 'Insert a newline instead of submitting'),
+ row(['⌘', 'click'], 'Open a link, file or folder from the output'),
+ row(['✦'], 'Name the terminal with AI')
]
}
+/** Registry rows + the literal rows, as the panel renders them. Pure: every input is a value,
+ * so the parity test can drive it without a settings store or a DOM. */
+export function buildShortcutSections(o: ShortcutSectionsOptions): ShortcutSection[] {
+ const sections: ShortcutSection[] = []
+ for (const group of groupOrder()) {
+ const rows: ShortcutRow[] = []
+ for (const def of COMMAND_DEFINITIONS) {
+ if (def.group !== group) continue
+ const chords = o.bindingsFor(def.id)
+ const chord = chords[0]
+ if (!chord) continue // unbound, or the user disabled it — no key to advertise
+ rows.push({
+ chords: chords.map((c) => shortcutKeyParts(c, o.isMac)),
+ label: rowLabel(def.id, def.title, chord)
+ })
+ }
+ rows.push(...extraRows(group, o))
+ if (rows.length) sections.push({ title: group, rows })
+ }
+ sections.push({ title: 'Terminal behavior', rows: behaviorRows(o) })
+ return sections
+}
+
/** Keyboard shortcuts reference; shown on first launch and via ⌘/ or the ? button. */
-export function ShortcutsPanel({ onClose }: ShortcutsPanelProps) {
- // A string selector, so an unrelated settings write cannot re-render the panel.
- const dictationChord = useSettings(() => dictationBinding())
- // Every OTHER row reads the registry through a plain `commandKeys()` call, which is not a
- // subscription — so a panel left open while a chord is remapped (Settings in another window,
- // or an outside edit to settings.json the store watcher picks up) kept showing the old key
- // unless the remap happened to be dictation's. Subscribing to the overrides object itself is
- // what makes the whole panel re-render; the value is unused on purpose.
+export function ShortcutsPanel({ onClose, onCustomize }: ShortcutsPanelProps) {
+ // Subscribing to the overrides object is what makes a remap land in an ALREADY-OPEN panel
+ // (Settings in another window, or an outside edit to settings.json the store watcher picks up):
+ // `effectiveBindings` is a plain read, not a subscription, so without this the rows would keep
+ // the chords they were built with. The value is unused on purpose.
useSettings((s) => s.settings.keybindings)
- const SECTIONS = buildSections(dictationChord)
+ // Narrow primitive selectors: an unrelated settings write must not re-render the panel.
+ const panHoverDelay = useSettings((s) => s.settings.panHoverDelay)
+ const dragMode = useSettings((s) => s.settings.canvasDragMode)
+ const doubleClickFocus = useSettings((s) => s.settings.doubleClickFocus)
+ const wheelZoom = useSettings((s) => s.settings.wheelZoom)
+ const isMac = isMacPlatform()
+ const sections = buildShortcutSections({
+ isMac,
+ browser: isBrowserRuntime(),
+ panHoverDelay,
+ dragMode: dragMode === 'pan' ? 'pan' : 'select',
+ doubleClickFocus,
+ wheelZoom,
+ bindingsFor: effectiveBindings
+ })
useEffect(() => {
const onKey = (e: KeyboardEvent) => {
@@ -148,17 +226,22 @@ export function ShortcutsPanel({ onClose }: ShortcutsPanelProps) {
</button>
</div>
<div className="shortcuts__body">
- {SECTIONS.map((s) => (
+ {sections.map((s) => (
<section key={s.title}>
<h3>{s.title}</h3>
- {s.rows.map((r) => (
- <div key={r.label} className="shortcut-row">
+ {s.rows.map((r, i) => (
+ <div key={`${r.label}-${i}`} className="shortcut-row">
<span className="shortcut-label">{r.label}</span>
<span className="shortcut-keys">
- {r.keys.map((k, i) => (
- <kbd key={i} className="kbd">
- {keyLabel(k)}
- </kbd>
+ {r.chords.map((chord, ci) => (
+ <Fragment key={ci}>
+ {ci > 0 && <span className="shortcut-or">or</span>}
+ {chord.map((k, i) => (
+ <kbd key={i} className="kbd">
+ {keyLabel(k, isMac)}
+ </kbd>
+ ))}
+ </Fragment>
))}
</span>
</div>
@@ -166,6 +249,14 @@ export function ShortcutsPanel({ onClose }: ShortcutsPanelProps) {
</section>
))}
</div>
+ {onCustomize && (
+ <div className="shortcuts__foot">
+ <span>Unassigned commands and remapping live in Settings.</span>
+ <button className="shortcuts__customize" onClick={onCustomize}>
+ Customize…
+ </button>
+ </div>
+ )}
</div>
</div>,
document.body
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 5bf018ffb..8c9cf8715 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -5454,6 +5454,43 @@ body,
flex-shrink: 0;
}
+/* Separator between two chords that BOTH fire the same command (Delete / Backspace,
+ Ctrl+Shift+C / Ctrl+Insert) — they are alternatives, not a sequence. */
+.shortcut-or {
+ align-self: center;
+ font-size: 10px;
+ color: var(--muted);
+ padding: 0 1px;
+}
+
+/* Footer route into Settings → Keyboard Shortcuts: the panel shows what is BOUND, that section
+ shows the whole remappable pool (and the commands that ship without a chord). */
+.shortcuts__foot {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+ padding: 10px 18px;
+ border-top: 1px solid var(--border);
+ font-size: 12px;
+ color: var(--muted);
+}
+
+.shortcuts__customize {
+ flex-shrink: 0;
+ border: 1px solid var(--border);
+ border-radius: 7px;
+ background: transparent;
+ color: var(--text);
+ padding: 4px 10px;
+ font-size: 12px;
+ cursor: pointer;
+}
+
+.shortcuts__customize:hover {
+ background: rgba(var(--tint-rgb), 0.08);
+}
+
/* ---- Command palette ---- */
.palette-overlay {
position: fixed;