Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(keybindings): board and canvas commands no longer share a conflict bucket
review91b6c97b895b
diff --git a/CLAUDE.md b/CLAUDE.mdindex 7a11ead8b..394425bea 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -4794,7 +4794,14 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord meawhile a board is up and carry neither `allowWhileTyping` nor `allowInTerminal` — that pair ofrefusals 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()` (thefirst 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 meawarning reads that list and cannot derive it — main is not importable from the renderer. Notewhat the pin cannot cover: a HARDCODED intercept (the `Digit0` branch) has no command id, so itswallows 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 keyedlistener 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 (legacydiff --git a/src/core/settings-store.ts b/src/core/settings-store.tsindex 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.tsxindex 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.tsxindex 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'sdiff --git a/src/shared/keybindings.test.ts b/src/shared/keybindings.test.tsindex 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 constfor (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.tsindex 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) continueconst 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}