Commit 38c93a2abdabb59b5a24c402d17397d1fd1493b8 | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-02-15 12:00:53-08:00
committer	Julius Marminge <jmarminge@gmail.com> 2026-02-15 15:51:05-08:00
log	38c93a2abdabb59b5a24c402d17397d1fd1493b8
tree	1aa1177cb1ecae3a5a29161e09f97cdf64796540
parent	ef4ce2e1ec3a6e08ccc392b802462519cbb706bc

Resolve keybinding precedence across commands

- Evaluate shortcut matches by resolving the last matching key+when rule, regardless of command
- Add cross-command precedence tests and switch assertions to `vitest` `assert`
- Clarify precedence behavior in `KEYBINDINGS.md`

3 files changed, 105 insertions(+), 37 deletions(-)

KEYBINDINGS.md
apps
- web
  - src
    keybindings.test.ts
    keybindings.ts

KEYBINDINGS.md+2-1

...	@@ -97,4 +97,5 @@ If you define any rules for a command, the default rule for that command is remo	...	@@ -97,4 +97,5 @@ If you define any rules for a command, the default rule for that command is remo
97	## Precedence	97	## Precedence
98		98
99	- Rules are evaluated in array order.	99	- Rules are evaluated in array order.
100	- Later matching rules win over earlier matching rules for the same command.	100	- For a key event, the server/client resolves the last rule where both `key` matches and `when` evaluates to `true`.
		101	- That means precedence is across commands, not only within the same command.

apps/web/src/keybindings.test.ts+92-33

 @@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { assert, describe, it } from "vitest";
 import type { KeybindingsConfig } from "@t3tools/contracts";
 import {
 @@ -34,43 +34,47 @@ const DEFAULT_BINDINGS: KeybindingsConfig = [
 describe("isTerminalToggleShortcut", () => {
   it("matches Cmd+J on macOS", () => {
-    expect(isTerminalToggleShortcut(event({ metaKey: true }), DEFAULT_BINDINGS, { platform: "MacIntel" })).toBe(true);
+    assert.isTrue(
+      isTerminalToggleShortcut(event({ metaKey: true }), DEFAULT_BINDINGS, { platform: "MacIntel" }),
+    );
   });
   it("matches Ctrl+J on non-macOS", () => {
-    expect(isTerminalToggleShortcut(event({ ctrlKey: true }), DEFAULT_BINDINGS, { platform: "Win32" })).toBe(true);
+    assert.isTrue(
+      isTerminalToggleShortcut(event({ ctrlKey: true }), DEFAULT_BINDINGS, { platform: "Win32" }),
+    );
   });
 });
 describe("split/new terminal shortcuts", () => {
   it("requires terminalFocus for default split/new bindings", () => {
-    expect(
+    assert.isFalse(
       isTerminalSplitShortcut(event({ key: "d", metaKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
         context: { terminalFocus: false },
       }),
-    ).toBe(false);
+    );
-    expect(
+    assert.isFalse(
       isTerminalNewShortcut(event({ key: "d", ctrlKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "Linux",
         context: { terminalFocus: false },
       }),
-    ).toBe(false);
+    );
   });
   it("matches split/new when terminalFocus is true", () => {
-    expect(
+    assert.isTrue(
       isTerminalSplitShortcut(event({ key: "d", metaKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
         context: { terminalFocus: true },
       }),
-    ).toBe(true);
+    );
-    expect(
+    assert.isTrue(
       isTerminalNewShortcut(event({ key: "d", ctrlKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "Linux",
         context: { terminalFocus: true },
       }),
-    ).toBe(true);
+    );
   });
   it("supports when expressions", () => {
 @@ -87,24 +91,24 @@ describe("split/new terminal shortcuts", () => {
       },
       { key: "mod+j", command: "terminal.toggle" },
     ];
-    expect(
+    assert.isTrue(
       isTerminalSplitShortcut(event({ key: "\\", ctrlKey: true }), keybindings, {
         platform: "Win32",
         context: { terminalOpen: true, terminalFocus: false },
       }),
-    ).toBe(true);
+    );
-    expect(
+    assert.isFalse(
       isTerminalSplitShortcut(event({ key: "\\", ctrlKey: true }), keybindings, {
         platform: "Win32",
         context: { terminalOpen: false, terminalFocus: false },
       }),
-    ).toBe(false);
+    );
-    expect(
+    assert.isTrue(
       isTerminalNewShortcut(event({ key: "n", ctrlKey: true, shiftKey: true }), keybindings, {
         platform: "Win32",
         context: { terminalOpen: true, terminalFocus: false },
       }),
-    ).toBe(true);
+    );
   });
 });
 @@ -114,12 +118,13 @@ describe("shortcutLabelForCommand", () => {
       { key: "mod+\\", command: "terminal.split", when: "terminalFocus" },
       { key: "mod+shift+\\", command: "terminal.split", when: "!terminalFocus" },
     ];
-    expect(shortcutLabelForCommand(bindings, "terminal.split", "Linux")).toBe("Ctrl+Shift+\\");
+    assert.strictEqual(shortcutLabelForCommand(bindings, "terminal.split", "Linux"), "Ctrl+Shift+\\");
   });
   it("returns labels for non-terminal commands", () => {
-    expect(shortcutLabelForCommand(DEFAULT_BINDINGS, "chat.new", "MacIntel")).toBe("⇧⌘O");
+    assert.strictEqual(shortcutLabelForCommand(DEFAULT_BINDINGS, "chat.new", "MacIntel"), "⇧⌘O");
-    expect(shortcutLabelForCommand(DEFAULT_BINDINGS, "editor.openFavorite", "Linux")).toBe(
+    assert.strictEqual(
+      shortcutLabelForCommand(DEFAULT_BINDINGS, "editor.openFavorite", "Linux"),
       "Ctrl+O",
     );
   });
 @@ -127,49 +132,103 @@ describe("shortcutLabelForCommand", () => {
 describe("chat/editor shortcuts", () => {
   it("matches chat.new shortcut", () => {
-    expect(
+    assert.isTrue(
       isChatNewShortcut(event({ key: "o", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
       }),
-    ).toBe(true);
+    );
-    expect(
+    assert.isTrue(
       isChatNewShortcut(event({ key: "o", ctrlKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "Linux",
       }),
-    ).toBe(true);
+    );
   });
   it("matches editor.openFavorite shortcut", () => {
-    expect(
+    assert.isTrue(
       isOpenFavoriteEditorShortcut(event({ key: "o", metaKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
       }),
-    ).toBe(true);
+    );
-    expect(
+    assert.isTrue(
       isOpenFavoriteEditorShortcut(event({ key: "o", ctrlKey: true }), DEFAULT_BINDINGS, {
         platform: "Linux",
       }),
-    ).toBe(true);
+    );
+  });
+});
+describe("cross-command precedence", () => {
+  it("uses when + order so a later focused rule overrides a global rule", () => {
+    const keybindings: KeybindingsConfig = [
+      { key: "mod+n", command: "chat.new" },
+      { key: "mod+n", command: "terminal.new", when: "terminalFocus" },
+    ];
+    assert.isTrue(
+      isTerminalNewShortcut(event({ key: "n", metaKey: true }), keybindings, {
+        platform: "MacIntel",
+        context: { terminalFocus: true },
+      }),
+    );
+    assert.isFalse(
+      isChatNewShortcut(event({ key: "n", metaKey: true }), keybindings, {
+        platform: "MacIntel",
+        context: { terminalFocus: true },
+      }),
+    );
+    assert.isFalse(
+      isTerminalNewShortcut(event({ key: "n", metaKey: true }), keybindings, {
+        platform: "MacIntel",
+        context: { terminalFocus: false },
+      }),
+    );
+    assert.isTrue(
+      isChatNewShortcut(event({ key: "n", metaKey: true }), keybindings, {
+        platform: "MacIntel",
+        context: { terminalFocus: false },
+      }),
+    );
+  });
+  it("still lets a later global rule win when both rules match", () => {
+    const keybindings: KeybindingsConfig = [
+      { key: "mod+n", command: "terminal.new", when: "terminalFocus" },
+      { key: "mod+n", command: "chat.new" },
+    ];
+    assert.isFalse(
+      isTerminalNewShortcut(event({ key: "n", ctrlKey: true }), keybindings, {
+        platform: "Linux",
+        context: { terminalFocus: true },
+      }),
+    );
+    assert.isTrue(
+      isChatNewShortcut(event({ key: "n", ctrlKey: true }), keybindings, {
+        platform: "Linux",
+        context: { terminalFocus: true },
+      }),
+    );
   });
 });
 describe("formatShortcutLabel", () => {
   it("formats labels for macOS", () => {
-    expect(formatShortcutLabel("mod+shift+d", "MacIntel")).toBe("⇧⌘D");
+    assert.strictEqual(formatShortcutLabel("mod+shift+d", "MacIntel"), "⇧⌘D");
   });
   it("formats labels for non-macOS", () => {
-    expect(formatShortcutLabel("mod+shift+d", "Linux")).toBe("Ctrl+Shift+D");
+    assert.strictEqual(formatShortcutLabel("mod+shift+d", "Linux"), "Ctrl+Shift+D");
   });
 });
 describe("isTerminalClearShortcut", () => {
   it("matches Ctrl+L on all platforms", () => {
-    expect(isTerminalClearShortcut(event({ key: "l", ctrlKey: true }), "Linux")).toBe(true);
+    assert.isTrue(isTerminalClearShortcut(event({ key: "l", ctrlKey: true }), "Linux"));
-    expect(isTerminalClearShortcut(event({ key: "l", ctrlKey: true }), "MacIntel")).toBe(true);
+    assert.isTrue(isTerminalClearShortcut(event({ key: "l", ctrlKey: true }), "MacIntel"));
   });
   it("matches Cmd+K on macOS", () => {
-    expect(isTerminalClearShortcut(event({ key: "k", metaKey: true }), "MacIntel")).toBe(true);
+    assert.isTrue(isTerminalClearShortcut(event({ key: "k", metaKey: true }), "MacIntel"));
   });
 });

apps/web/src/keybindings.ts+11-3

 @@ -305,17 +305,25 @@ function matchesCommandShortcut(
   command: KeybindingCommand,
   options?: ShortcutMatchOptions,
 ): boolean {
+  return resolveShortcutCommand(event, keybindings, options) === command;
+}
+function resolveShortcutCommand(
+  event: ShortcutEventLike,
+  keybindings: ResolvedKeybindings,
+  options?: ShortcutMatchOptions,
+): KeybindingCommand | null {
   const platform = resolvePlatform(options);
   const context = resolveContext(options);
   for (let index = keybindings.length - 1; index >= 0; index -= 1) {
     const binding = keybindings[index];
-    if (!binding || binding.command !== command) continue;
+    if (!binding) continue;
     if (!matchesWhenExpression(binding.when, context)) continue;
     if (!matchesShortcutValue(event, binding.key, platform)) continue;
-    return true;
+    return binding.command;
   }
-  return false;
+  return null;
 }
 function formatShortcutKeyLabel(key: string): string {