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.

fix(keybindings): board and canvas commands no longer share a conflict bucket

review91b6c97b895b
diff --git a/CLAUDE.md b/CLAUDE.md
index 7a11ead8b..394425bea 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4794,7 +4794,14 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
while a board is up and carry neither `allowWhileTyping` nor `allowInTerminal` — that pair of
refusals is what makes a bare key a command rather than a character stolen from the user, so a
`board` row must never gain either flag, and no other scope may be given bare letters
- (`normalizeBindingForCommand`). `board` shares the `global` conflict bucket with app/canvas.
+ (`normalizeBindingForCommand`).
+ - **A conflict bucket is a DISPATCH CONTEXT, not a scope** (`conflictBuckets`): `canvas` resolves
+ only with the board closed, `board` only with it open, `app` in both — so an app command sits in
+ `canvas-view` AND `board-view`, and a canvas command never conflicts with a board one. One
+ shared keyspace for all three reported a collision dispatch cannot produce, and the load-time
+ sanitizer then STRIPPED the user's legitimate override (a bare-arrow canvas command against the
+ board's arrow keys). A test walks every pair of view commands through the real
+ `resolveCommandForKeyEvent`, so a new scope or a dispatch change that forgets the buckets reds.
- **Never read `settings.speech.shortcut`.** The dictation chord is `dictationBinding()` (the
first effective `speech.dictation` binding); the legacy field is a **downgrade mirror only**,
written by `setKeybindingOverride` so an older build still finds the user's chord.
@@ -4806,8 +4813,8 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
warning reads that list and cannot derive it — main is not importable from the renderer. Note
what the pin cannot cover: a HARDCODED intercept (the `Digit0` branch) has no command id, so it
swallows its chord app-wide with the recorder reporting no conflict.
- - **Dictation has its own conflict bucket** (`conflictBucket` — `speech.dictation` is never in
- `global`), because it never competes at dispatch: the resolver skips it and its own keyed
+ - **Dictation has its own conflict bucket** (`conflictBuckets` — `speech.dictation` is never in
+ a view bucket), because it never competes at dispatch: the resolver skips it and its own keyed
listener claims the chord FIRST **in plain app focus or the ⌘M composer box** (`isChatComposerTarget`),
which is precedence, not ambiguity.
Overlap policy is deliberately asymmetric — the LOAD path PERMITS a shared chord (legacy
diff --git a/src/core/settings-store.ts b/src/core/settings-store.ts
index f8a2cc61b..7aea5bf79 100644
--- a/src/core/settings-store.ts
+++ b/src/core/settings-store.ts
@@ -28,7 +28,7 @@ function mergeSettings(saved: Partial<Settings> | null | undefined): Settings {
// A shortcut EQUAL to the default seeds nothing: the override would only restate what the
// registry already says, and would then pin that chord against any future default change.
// **The seeded value survives the read path.** `speech.dictation` has its OWN conflict bucket
- // (`conflictBucket` in shared/keybindings.ts), so it can never be a participant in a
+ // (`conflictBuckets` in shared/keybindings.ts), so it can never be a participant in a
// cross-command collision, and the READ path's sanitizer (`sanitizeKeybindingOverrides`) has
// nothing to strip — neither the seed nor the user's own override on the same chord. (It used
// not to: both were deleted on load, and dictation silently fell back to the registry default.)
diff --git a/src/renderer/components/settings/sections/ShortcutsSection.test.tsx b/src/renderer/components/settings/sections/ShortcutsSection.test.tsx
index 3fd8d5793..16031b9f8 100644
--- a/src/renderer/components/settings/sections/ShortcutsSection.test.tsx
+++ b/src/renderer/components/settings/sections/ShortcutsSection.test.tsx
@@ -550,7 +550,7 @@ describe('commitCandidate', () => {
// Dictation is its own conflict bucket (Task 1), so NEITHER of the three gates above can see an
// overlap with it — the detector is silent by design and the load path deliberately permits one.
- // These two gates are what makes `conflictBucket`'s "the Settings UI REFUSES to create one" true.
+ // These two gates are what makes `conflictBuckets`'s "the Settings UI REFUSES to create one" true.
//
// They are SCOPED, and the four tests below are the discriminating matrix: the keyed gesture is
// offered only in plain app focus (`globalKeybindings.ts` — `!ctx.typing && !ctx.terminal &&
@@ -581,7 +581,7 @@ describe('commitCandidate', () => {
expect(kb()['terminal.find']).toEqual(['Cmd+Alt+D'])
})
- it('refuses a keyed Dictate chord that a global-bucket command already holds', () => {
+ it('refuses a keyed Dictate chord that a view-bucket command already holds', () => {
const r = commitCandidate('speech.dictation', 'Cmd+K', 'replace')
expect(r.ok).toBe(false)
if (!r.ok) expect(r.error).toContain('Command palette')
diff --git a/src/renderer/components/settings/sections/ShortcutsSection.tsx b/src/renderer/components/settings/sections/ShortcutsSection.tsx
index 57f27f3c2..3ac2a913f 100644
--- a/src/renderer/components/settings/sections/ShortcutsSection.tsx
+++ b/src/renderer/components/settings/sections/ShortcutsSection.tsx
@@ -20,7 +20,7 @@
* 2. `findKeybindingConflicts` over the candidate map — a same-bucket collision.
* 3. `findMainInterceptShadowing` — a CROSS-bucket hit the conflict check cannot see.
* 4. REVERSE shadowing — the same collision seen from the non-intercepted side.
- * 5. The two DICTATION overlap gates — the one overlap `conflictBucket` deliberately does not
+ * 5. The two DICTATION overlap gates — the one overlap `conflictBuckets` deliberately does not
* report, refused here in both directions, but only for `app`/`canvas`-scope commands: the
* keyed gesture has a focus gate, so a terminal- or scm-scope command never competes with it
* (see the block itself for why).
@@ -226,7 +226,7 @@ export function commitCandidate(
}
// DICTATION OVERLAP, both directions. `speech.dictation` is its own conflict bucket (see
- // `conflictBucket` in @shared/keybindings), so gate (2) above is silent about it BY DESIGN —
+ // `conflictBuckets` in @shared/keybindings), so gate (2) above is silent about it BY DESIGN —
// dictation never competes at dispatch, it PRE-EMPTS: the resolver skips it and its own keyed
// listener claims the chord first while the canvas has focus. That is precedence, not ambiguity,
// which is why the LOAD path permits an overlap (legacy files contain them, and dropping a user's
diff --git a/src/shared/keybindings.test.ts b/src/shared/keybindings.test.ts
index 5e96d5448..4a402f308 100644
--- a/src/shared/keybindings.test.ts
+++ b/src/shared/keybindings.test.ts
@@ -6,7 +6,7 @@ import {
normalizeBindingForCommand,
getEffectiveBindings,
bindingIdentity,
- conflictBucket,
+ conflictBuckets,
findKeybindingConflicts,
sanitizeKeybindingOverrides,
resolveCommandForKeyEvent,
@@ -311,24 +311,49 @@ describe('bindingIdentity', () => {
})
})
-describe('conflictBucket', () => {
- // The whole mapping, asserted over the REGISTRY rather than a hand-picked example per bucket:
- // 'app' and 'canvas' share the global keyspace, 'terminal' and 'scm' are their own, and
- // `speech.dictation` is the one command whose bucket comes from its id instead of its scope.
- // Kills two mutants a per-bucket sample can miss: a scope-mapping typo (folding 'scm' — or a
- // scope added later — into 'global', or dropping 'canvas' out of it), and the removal of the
- // dictation branch, which would send Dictate back into 'global' and re-report the collision
- // the bucket exists to stop.
- it('maps every command to its scope bucket, dictation excepted', () => {
+describe('conflictBuckets', () => {
+ // The whole mapping, asserted over the REGISTRY rather than a hand-picked example per bucket.
+ // A bucket is a dispatch CONTEXT: the chords that can resolve at the same moment. 'canvas'
+ // resolves only with the board closed and 'board' only with it open, while 'app' resolves in
+ // both — so an app command sits in both view buckets and a canvas command never meets a board
+ // one. 'terminal' and 'scm' are their own; `speech.dictation` is the one command whose bucket
+ // comes from its id instead of its scope.
+ it('maps every command to the contexts its scope dispatches in, dictation excepted', () => {
+ const expected = {
+ app: ['canvas-view', 'board-view'],
+ canvas: ['canvas-view'],
+ board: ['board-view'],
+ terminal: ['terminal'],
+ scm: ['scm']
+ } as const
for (const def of COMMAND_DEFINITIONS) {
if (def.id === 'speech.dictation') continue
- // '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' || def.scope === 'board' ? 'global' : def.scope
- )
+ expect(conflictBuckets(def)).toEqual(expected[def.scope])
+ }
+ expect(conflictBuckets(COMMANDS_BY_ID.get('speech.dictation')!)).toEqual(['dictation'])
+ })
+
+ it('agrees with the dispatcher: two scopes share a bucket exactly when both can resolve at once', () => {
+ // Asked of the REAL resolver, never restated: a command can resolve in a context when, bound
+ // alone to a chord nothing else holds, a keydown of that chord resolves to it there.
+ const chord = 'Cmd+Alt+Shift+F12'
+ const press = { metaKey: true, ctrlKey: false, altKey: true, shiftKey: true, key: 'F12' }
+ const resolvesIn = (def: (typeof COMMAND_DEFINITIONS)[number], kanbanOpen: boolean): boolean =>
+ resolveCommandForKeyEvent(
+ press,
+ { typing: false, terminal: false, kanbanOpen, terminalFirst: false },
+ { [def.id]: [chord] },
+ true
+ ) === def.id
+ const views = COMMAND_DEFINITIONS.filter((def) =>
+ def.id !== 'speech.dictation' && (def.scope === 'app' || def.scope === 'canvas' || def.scope === 'board'))
+ for (const a of views) {
+ for (const b of views) {
+ const share = conflictBuckets(a).some((bucket) => conflictBuckets(b).includes(bucket))
+ const together = [true, false].some((open) => resolvesIn(a, open) && resolvesIn(b, open))
+ expect(share, `${a.id} × ${b.id}`).toBe(together)
+ }
}
- expect(conflictBucket(COMMANDS_BY_ID.get('speech.dictation')!)).toBe('dictation')
})
})
@@ -365,12 +390,31 @@ describe('findKeybindingConflicts', () => {
// terminal.find is Cmd+F in the terminal bucket; an app-bucket Cmd+F is legal.
expect(findKeybindingConflicts({ 'canvas.fitAll': ['Cmd+F'] }, true)).toEqual([])
})
- it('the scm bucket is its own keyspace, not part of global', () => {
- // scm.commit holds Cmd+Enter; a canvas (global-bucket) override on the same chord is legal,
- // because Commit dispatches from the focused composer. Reds if conflictBucket folds 'scm'
- // into 'global'.
+ it('the scm bucket is its own keyspace, not part of a view bucket', () => {
+ // scm.commit holds Cmd+Enter; a canvas (canvas-view bucket) override on the same chord is legal,
+ // because Commit dispatches from the focused composer. Reds if conflictBuckets folds 'scm'
+ // into a view bucket.
expect(findKeybindingConflicts({ 'canvas.fitAll': ['Cmd+Enter'] }, true)).toEqual([])
})
+ it('a canvas override may share a chord with a board command — they never dispatch together', () => {
+ // board.nextCard holds bare ArrowDown and only resolves while a board is up; canvas commands
+ // are inert then. A bare-arrow canvas override used to be stripped at load for this "conflict".
+ expect(findKeybindingConflicts({ 'canvas.deleteSelection': ['ArrowDown'] }, true)).toEqual([])
+ expect(sanitizeKeybindingOverrides({ 'canvas.deleteSelection': ['ArrowDown'] }, true))
+ .toEqual({ overrides: { 'canvas.deleteSelection': ['ArrowDown'] }, warnings: [] })
+ // …and the other direction: a board override on a canvas command's chord.
+ expect(findKeybindingConflicts({ 'board.openCard': ['Cmd+Shift+F'] }, true)).toEqual([])
+ })
+ it('a board override still conflicts with an app command, which dispatches on the board too', () => {
+ expect(findKeybindingConflicts({ 'board.openCard': ['Cmd+K'] }, true)).toEqual([
+ { binding: 'Cmd+K', commandIds: ['app.commandPalette', 'board.openCard'] }
+ ])
+ })
+ it('reports a collision between two app commands once, not once per view', () => {
+ expect(findKeybindingConflicts({ 'app.settings': ['Cmd+K'] }, true)).toEqual([
+ { binding: 'Cmd+K', commandIds: ['app.commandPalette', 'app.settings'] }
+ ])
+ })
it('two disabled commands never conflict', () => {
expect(
findKeybindingConflicts({ 'canvas.fitAll': [], 'canvas.groupSelection': [] }, true)
diff --git a/src/shared/keybindings.ts b/src/shared/keybindings.ts
index 405e7c687..9c19b8c44 100644
--- a/src/shared/keybindings.ts
+++ b/src/shared/keybindings.ts
@@ -376,10 +376,15 @@ export function bindingIdentity(binding: string, isMac: boolean): string {
].join('')
}
-/** 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.
+/** A bucket is a dispatch CONTEXT: commands sharing one can resolve at the same moment, so they
+ * compete for the same keys. All three view scopes dispatch from the window listener, but not at
+ * the same moments: 'canvas' resolves only while the board is CLOSED and 'board' only while it is
+ * OPEN, while 'app' resolves in both (`resolveCommandForKeyEvent`). So an app command sits in both
+ * view buckets, a canvas command in 'canvas-view' and a board command in 'board-view' — a canvas
+ * and a board command never compete. Folding the three into one global keyspace reported a
+ * collision dispatch cannot produce, and `sanitizeKeybindingOverrides` then stripped a legitimate
+ * override at load (a bare-arrow canvas command against the board's J/K/arrow keys). Terminal and
+ * scm are their own focused surfaces.
*
* **`speech.dictation` is its own fourth bucket, and the reason is dispatch, not scope.** It
* never competes for a chord: the resolver SKIPS it outright (see the `def.id ===
@@ -405,11 +410,16 @@ export function bindingIdentity(binding: string, isMac: boolean): string {
* before the page exists, so such a hand-edit survives sanitization as a permanently dead chord.
* The UI can never create it (`commitCandidate`'s reverse-shadow gate refuses it one step earlier
* than the dictation gates). */
-export 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' || def.scope === 'board' ? 'global' : def.scope
+export type ConflictBucket = 'canvas-view' | 'board-view' | 'terminal' | 'scm' | 'dictation'
+
+export function conflictBuckets(def: Pick<CommandDefinition, 'id' | 'scope'>): readonly ConflictBucket[] {
+ if (def.id === 'speech.dictation') return ['dictation']
+ switch (def.scope) {
+ case 'app': return ['canvas-view', 'board-view']
+ case 'canvas': return ['canvas-view']
+ case 'board': return ['board-view']
+ default: return [def.scope]
+ }
}
export interface KeybindingConflict {
@@ -431,22 +441,30 @@ export function findKeybindingConflicts(
const byBucketAndIdentity = new Map<string, { binding: string; ids: Set<CommandId> }>()
for (const def of COMMAND_DEFINITIONS) {
for (const binding of getEffectiveBindings(def.id, overrides, isMac)) {
- const key = `${conflictBucket(def)} ${bindingIdentity(binding, isMac)}`
- const entry = byBucketAndIdentity.get(key) ?? {
- // Canonicalized, so a hand-edited `cmd+k` override is reported as `Cmd+K`.
- binding: serializeShortcut(parseShortcut(binding)),
- ids: new Set<CommandId>()
+ for (const bucket of conflictBuckets(def)) {
+ const key = `${bucket} ${bindingIdentity(binding, isMac)}`
+ const entry = byBucketAndIdentity.get(key) ?? {
+ // Canonicalized, so a hand-edited `cmd+k` override is reported as `Cmd+K`.
+ binding: serializeShortcut(parseShortcut(binding)),
+ ids: new Set<CommandId>()
+ }
+ entry.ids.add(def.id)
+ byBucketAndIdentity.set(key, entry)
}
- entry.ids.add(def.id)
- byBucketAndIdentity.set(key, entry)
}
}
const conflicts: KeybindingConflict[] = []
+ // Two app commands on one chord meet in BOTH view buckets; that is one conflict, not two.
+ const reported = new Set<string>()
for (const { binding, ids } of byBucketAndIdentity.values()) {
if (ids.size < 2) continue
const commandIds = [...ids].sort()
const touchesOverride = commandIds.some((id) => overrides[id] !== undefined)
- if (opts.includeDefaults || touchesOverride) conflicts.push({ binding, commandIds })
+ if (!opts.includeDefaults && !touchesOverride) continue
+ const key = `${binding} ${commandIds.join(' ')}`
+ if (reported.has(key)) continue
+ reported.add(key)
+ conflicts.push({ binding, commandIds })
}
return conflicts
}