gloomberb 0.14.0 → 0.14.1

package/src/app/keybindings/chord.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+import {
+  formatKeyChord,
+  isTypingChord,
+  keyChordFromEvent,
+  matchesKeyChord,
+  parseKeyChord,
+  serializeKeyChord,
+} from "./chord";
+
+describe("parseKeyChord", () => {
+  test("reads the accelerator grammar case-insensitively and round-trips", () => {
+    expect(parseKeyChord("CmdOrCtrl+Shift+F")).toEqual({ key: "f", ctrl: false, cmd: false, primary: true, alt: false, shift: true });
+    expect(parseKeyChord("ctrl+p")).toEqual({ key: "p", ctrl: true, cmd: false, primary: false, alt: false, shift: false });
+    expect(parseKeyChord("`")).toEqual({ key: "`", ctrl: false, cmd: false, primary: false, alt: false, shift: false });
+    expect(parseKeyChord("Alt+1")).toMatchObject({ key: "1", alt: true });
+    expect(parseKeyChord("F5")).toMatchObject({ key: "f5" });
+    expect(parseKeyChord("Ctrl++")).toMatchObject({ key: "+", ctrl: true });
+    expect(parseKeyChord("CmdOrCtrl+,")).toMatchObject({ key: ",", primary: true });
+    expect(parseKeyChord("Option+Backtick")).toMatchObject({ key: "`", alt: true });
+    expect(parseKeyChord("CmdOrCtrl+Digit")).toMatchObject({ key: "digit", primary: true });
+    for (const text of ["CmdOrCtrl+Shift+F", "Ctrl+P", "`", "Alt+1", "F5", "Shift+Tab", "CmdOrCtrl+Digit", "Escape"]) {
+      expect(serializeKeyChord(parseKeyChord(text)!)).toBe(text);
+    }
+  });
+
+  test("an uppercase letter is the letter, not Shift", () => {
+    expect(parseKeyChord("Ctrl+K")).toMatchObject({ key: "k", shift: false });
+    expect(parseKeyChord("Shift+R")).toMatchObject({ key: "r", shift: true });
+  });
+
+  test("rejects text that names no key or mixes explicit and primary modifiers", () => {
+    expect(parseKeyChord("")).toBeNull();
+    expect(parseKeyChord("Ctrl+")).toBeNull();
+    expect(parseKeyChord("Ctrl+Shift")).toBeNull();
+    expect(parseKeyChord("Hyper+K")).toBeNull();
+    expect(parseKeyChord("Ctrl+CmdOrCtrl+K")).toBeNull();
+    expect(parseKeyChord("Ctrl+Bogus")).toBeNull();
+  });
+});
+
+describe("formatKeyChord", () => {
+  test("names the primary modifier for the host", () => {
+    const chord = parseKeyChord("CmdOrCtrl+Shift+F")!;
+    expect(formatKeyChord(chord, { primaryModifier: "ctrl" })).toBe("Ctrl+Shift+F");
+    expect(formatKeyChord(chord, { primaryModifier: "cmd" })).toBe("Cmd+Shift+F");
+    expect(formatKeyChord(parseKeyChord("Escape")!, { primaryModifier: "ctrl" })).toBe("Esc");
+    expect(formatKeyChord(parseKeyChord("CmdOrCtrl+Digit")!, { primaryModifier: "cmd" })).toBe("Cmd+1-9");
+  });
+});
+
+describe("matchesKeyChord", () => {
+  const base = { ctrl: false, shift: false, alt: false, meta: false, super: false };
+
+  test("primary accepts Control, Command and the kitty super modifier", () => {
+    const chord = parseKeyChord("CmdOrCtrl+K")!;
+    expect(matchesKeyChord(chord, { ...base, name: "k", ctrl: true })).toBe(true);
+    expect(matchesKeyChord(chord, { ...base, name: "k", meta: true })).toBe(true);
+    expect(matchesKeyChord(chord, { ...base, name: "k", super: true })).toBe(true);
+    expect(matchesKeyChord(chord, { ...base, name: "k" })).toBe(false);
+    expect(matchesKeyChord(chord, { ...base, name: "k", ctrl: true, alt: true })).toBe(false);
+  });
+
+  test("explicit Control does not accept Command", () => {
+    const chord = parseKeyChord("Ctrl+P")!;
+    expect(matchesKeyChord(chord, { ...base, name: "p", ctrl: true })).toBe(true);
+    expect(matchesKeyChord(chord, { ...base, name: "p", meta: true })).toBe(false);
+  });
+
+  test("letters honour Shift, including an uppercase name from the terminal", () => {
+    const shifted = parseKeyChord("Shift+R")!;
+    const plain = parseKeyChord("R")!;
+    expect(matchesKeyChord(shifted, { ...base, name: "R" })).toBe(true);
+    expect(matchesKeyChord(shifted, { ...base, name: "r", shift: true })).toBe(true);
+    expect(matchesKeyChord(shifted, { ...base, name: "r" })).toBe(false);
+    expect(matchesKeyChord(plain, { ...base, name: "r" })).toBe(true);
+    expect(matchesKeyChord(plain, { ...base, name: "R" })).toBe(false);
+    expect(matchesKeyChord(plain, { ...base, name: "r", ctrl: true })).toBe(false);
+  });
+
+  test("punctuation ignores Shift and accepts the US-layout slash for question mark", () => {
+    const help = parseKeyChord("?")!;
+    expect(matchesKeyChord(help, { ...base, name: "?", shift: true })).toBe(true);
+    expect(matchesKeyChord(help, { ...base, name: "?" })).toBe(true);
+    expect(matchesKeyChord(help, { ...base, name: "/", shift: true })).toBe(true);
+    expect(matchesKeyChord(help, { ...base, name: "/", shift: true, alt: true })).toBe(false);
+    expect(matchesKeyChord(parseKeyChord("`")!, { ...base, name: "`" })).toBe(true);
+  });
+
+  test("named keys and the digit family", () => {
+    expect(matchesKeyChord(parseKeyChord("Shift+Tab")!, { ...base, name: "tab", shift: true })).toBe(true);
+    expect(matchesKeyChord(parseKeyChord("Tab")!, { ...base, name: "tab", shift: true })).toBe(false);
+    expect(matchesKeyChord(parseKeyChord("Enter")!, { ...base, name: "return" })).toBe(true);
+    expect(matchesKeyChord(parseKeyChord("CmdOrCtrl+Digit")!, { ...base, name: "3", super: true })).toBe(true);
+    expect(matchesKeyChord(parseKeyChord("CmdOrCtrl+Digit")!, { ...base, name: "0", ctrl: true })).toBe(false);
+    expect(matchesKeyChord(parseKeyChord("CmdOrCtrl+Digit")!, { ...base, name: "2", alt: true })).toBe(false);
+  });
+});
+
+describe("keyChordFromEvent", () => {
+  const base = { ctrl: false, shift: false, alt: false, meta: false, super: false };
+
+  test("records the host's own modifier as CmdOrCtrl and the other one explicitly", () => {
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "t", ctrl: true }, "ctrl")!)).toBe("CmdOrCtrl+T");
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "t", super: true }, "ctrl")!)).toBe("Cmd+T");
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "t", meta: true }, "cmd")!)).toBe("CmdOrCtrl+T");
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "t", ctrl: true }, "cmd")!)).toBe("Ctrl+T");
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "f", ctrl: true, shift: true }, "ctrl")!)).toBe("CmdOrCtrl+Shift+F");
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "R" }, "ctrl")!)).toBe("Shift+R");
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "escape" }, "ctrl")!)).toBe("Escape");
+    expect(serializeKeyChord(keyChordFromEvent({ ...base, name: "?", shift: true }, "ctrl")!)).toBe("?");
+  });
+
+  test("a bare modifier is not a chord", () => {
+    expect(keyChordFromEvent({ ...base, name: "shift", shift: true }, "ctrl")).toBeNull();
+    expect(keyChordFromEvent({ ...base, name: "" }, "ctrl")).toBeNull();
+  });
+});
+
+describe("isTypingChord", () => {
+  test("flags keys a text field would consume", () => {
+    expect(isTypingChord(parseKeyChord("a")!)).toBe(true);
+    expect(isTypingChord(parseKeyChord("Shift+A")!)).toBe(true);
+    expect(isTypingChord(parseKeyChord("Space")!)).toBe(true);
+    expect(isTypingChord(parseKeyChord("Enter")!)).toBe(true);
+    expect(isTypingChord(parseKeyChord("F5")!)).toBe(false);
+    expect(isTypingChord(parseKeyChord("Alt+A")!)).toBe(false);
+    expect(isTypingChord(parseKeyChord("CmdOrCtrl+Shift+A")!)).toBe(false);
+    expect(isTypingChord(parseKeyChord("Escape")!)).toBe(false);
+  });
+});

package/src/app/keybindings/chord.ts

@@ -0,0 +1,302 @@
+/**
+ * One key chord: the key plus the modifiers held with it.
+ *
+ * Bindings are written in the accelerator grammar the menus already use
+ * (`CmdOrCtrl+Shift+F`, `Alt+1`, `F5`, `` ` ``). `CmdOrCtrl` is the primary
+ * modifier: Control in a terminal, Command on the macOS desktop and web hosts,
+ * and either one is accepted when matching, which is how every built-in chord
+ * behaved before bindings became configurable.
+ */
+export interface KeyChord {
+  /**
+   * Lowercase key: a single character, a named key such as `tab` or `f5`, or
+   * `digit`, the 1-9 family used by layout switching.
+   */
+  key: string;
+  /** Control only. Exclusive with `primary`. */
+  ctrl: boolean;
+  /** Command (macOS) or Super/Win only. Exclusive with `primary`. */
+  cmd: boolean;
+  /** Control or Command, whichever the host reports. */
+  primary: boolean;
+  alt: boolean;
+  shift: boolean;
+}
+
+export interface KeyChordEventLike {
+  key?: string;
+  name?: string;
+  sequence?: string;
+  ctrl?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+  meta?: boolean;
+  super?: boolean;
+}
+
+export type PrimaryModifier = "ctrl" | "cmd";
+
+const MODIFIER_TOKENS: Record<string, keyof Omit<KeyChord, "key">> = {
+  ctrl: "ctrl",
+  control: "ctrl",
+  cmd: "cmd",
+  command: "cmd",
+  super: "cmd",
+  meta: "cmd",
+  win: "cmd",
+  cmdorctrl: "primary",
+  "cmd/ctrl": "primary",
+  commandorcontrol: "primary",
+  mod: "primary",
+  primary: "primary",
+  alt: "alt",
+  option: "alt",
+  opt: "alt",
+  shift: "shift",
+};
+
+/**
+ * Named keys, the event names each host reports for them, the label shown, and
+ * the config spelling when it differs from the label.
+ */
+const NAMED_KEYS: Array<{ key: string; aliases: string[]; label: string; spelling?: string }> = [
+  { key: "tab", aliases: ["tab"], label: "Tab" },
+  { key: "return", aliases: ["return", "enter"], label: "Enter" },
+  { key: "escape", aliases: ["escape", "esc"], label: "Esc", spelling: "Escape" },
+  { key: "space", aliases: ["space", " "], label: "Space" },
+  { key: "backspace", aliases: ["backspace"], label: "Backspace" },
+  { key: "delete", aliases: ["delete", "del"], label: "Delete" },
+  { key: "insert", aliases: ["insert", "ins"], label: "Insert" },
+  { key: "up", aliases: ["up", "arrowup"], label: "Up" },
+  { key: "down", aliases: ["down", "arrowdown"], label: "Down" },
+  { key: "left", aliases: ["left", "arrowleft"], label: "Left" },
+  { key: "right", aliases: ["right", "arrowright"], label: "Right" },
+  { key: "home", aliases: ["home"], label: "Home" },
+  { key: "end", aliases: ["end"], label: "End" },
+  { key: "pageup", aliases: ["pageup", "pgup"], label: "PageUp" },
+  { key: "pagedown", aliases: ["pagedown", "pgdn", "pgdown"], label: "PageDown" },
+  { key: "digit", aliases: ["digit", "1-9"], label: "1-9", spelling: "Digit" },
+  ...Array.from({ length: 24 }, (_, index) => ({
+    key: `f${index + 1}`,
+    aliases: [`f${index + 1}`],
+    label: `F${index + 1}`,
+  })),
+];
+
+const NAMED_KEY_BY_ALIAS = new Map<string, typeof NAMED_KEYS[number]>();
+for (const named of NAMED_KEYS) {
+  for (const alias of named.aliases) NAMED_KEY_BY_ALIAS.set(alias, named);
+}
+
+/** Spelled-out punctuation, for people who would rather not quote a backtick in JSON. */
+const SYMBOL_WORDS: Record<string, string> = {
+  plus: "+",
+  minus: "-",
+  comma: ",",
+  period: ".",
+  dot: ".",
+  backtick: "`",
+  grave: "`",
+  slash: "/",
+  backslash: "\\",
+  semicolon: ";",
+  quote: "'",
+  equals: "=",
+  equal: "=",
+  question: "?",
+};
+
+/** Event names that are a modifier on its own, never a chord. */
+const MODIFIER_ONLY_EVENT_NAMES = new Set([
+  "", "shift", "ctrl", "control", "alt", "option", "meta", "super", "cmd", "command", "capslock", "fn",
+]);
+
+export function isNamedKey(key: string): boolean {
+  return NAMED_KEY_BY_ALIAS.get(key)?.key === key;
+}
+
+function isLetter(key: string): boolean {
+  return key.length === 1 && /[a-z]/i.test(key);
+}
+
+function emptyChord(): KeyChord {
+  return { key: "", ctrl: false, cmd: false, primary: false, alt: false, shift: false };
+}
+
+/**
+ * Parses `Ctrl+Shift+P` style text. Returns null for text that names no key or
+ * mixes `Ctrl` or `Cmd` with `CmdOrCtrl`. Case-insensitive throughout, and an
+ * uppercase letter means the letter, not Shift: `Ctrl+K` is Control and k.
+ */
+export function parseKeyChord(text: string): KeyChord | null {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+  // "Ctrl++" and a bare "+" name the plus key; "Ctrl+" names nothing.
+  const tokens = trimmed === "+" || trimmed.endsWith("++")
+    ? [...trimmed.slice(0, -1).split("+").filter((token) => token.length > 0), "+"]
+    : trimmed.split("+");
+  if (tokens.length === 0 || tokens.some((token) => token.trim().length === 0)) return null;
+
+  const chord = emptyChord();
+  const keyToken = tokens[tokens.length - 1]!.trim();
+  for (const token of tokens.slice(0, -1)) {
+    const modifier = MODIFIER_TOKENS[token.trim().toLowerCase()];
+    if (!modifier) return null;
+    chord[modifier] = true;
+  }
+  if (chord.primary && (chord.ctrl || chord.cmd)) return null;
+
+  const lowered = keyToken.toLowerCase();
+  const named = NAMED_KEY_BY_ALIAS.get(lowered);
+  if (named) {
+    chord.key = named.key;
+  } else if (SYMBOL_WORDS[lowered]) {
+    chord.key = SYMBOL_WORDS[lowered]!;
+  } else if ([...keyToken].length === 1) {
+    chord.key = isLetter(keyToken) ? lowered : keyToken;
+  } else {
+    return null;
+  }
+  return chord;
+}
+
+/** Canonical config spelling for a chord, the inverse of {@link parseKeyChord}. */
+export function serializeKeyChord(chord: KeyChord): string {
+  const parts: string[] = [];
+  if (chord.primary) parts.push("CmdOrCtrl");
+  if (chord.ctrl) parts.push("Ctrl");
+  if (chord.cmd) parts.push("Cmd");
+  if (chord.alt) parts.push("Alt");
+  if (chord.shift) parts.push("Shift");
+  const named = NAMED_KEY_BY_ALIAS.get(chord.key);
+  parts.push(named ? named.spelling ?? named.label : isLetter(chord.key) ? chord.key.toUpperCase() : chord.key);
+  return parts.join("+");
+}
+
+export interface FormatKeyChordOptions {
+  /** What `CmdOrCtrl` reads as on this host. */
+  primaryModifier: PrimaryModifier;
+  /** The label for an explicit Command chord; Windows and Linux desktops call it Super. */
+  cmdLabel?: string;
+}
+
+/** The label users see: `Ctrl+Shift+F` in a terminal, `Cmd+Shift+F` on a Mac. */
+export function formatKeyChord(chord: KeyChord, options: FormatKeyChordOptions): string {
+  const cmdLabel = options.cmdLabel ?? "Cmd";
+  const parts: string[] = [];
+  if (chord.primary) parts.push(options.primaryModifier === "cmd" ? cmdLabel : "Ctrl");
+  if (chord.ctrl) parts.push("Ctrl");
+  if (chord.cmd) parts.push(cmdLabel);
+  if (chord.alt) parts.push("Alt");
+  if (chord.shift) parts.push("Shift");
+  const named = NAMED_KEY_BY_ALIAS.get(chord.key);
+  parts.push(named ? named.label : isLetter(chord.key) ? chord.key.toUpperCase() : chord.key);
+  return parts.join("+");
+}
+
+export function keyChordsEqual(left: KeyChord, right: KeyChord): boolean {
+  return left.key === right.key
+    && left.ctrl === right.ctrl
+    && left.cmd === right.cmd
+    && left.primary === right.primary
+    && left.alt === right.alt
+    && left.shift === right.shift;
+}
+
+/** True when the chord could be typed into a text field as-is, so it must not double as a global key. */
+export function isTypingChord(chord: KeyChord): boolean {
+  if (chord.ctrl || chord.cmd || chord.primary || chord.alt) return false;
+  if (chord.key === "digit") return true;
+  return !isNamedKey(chord.key) || ["space", "return", "tab", "backspace", "delete"].includes(chord.key);
+}
+
+function eventKeyName(event: KeyChordEventLike): string {
+  return event.name ?? event.key ?? "";
+}
+
+function eventHasCmd(event: KeyChordEventLike): boolean {
+  return event.meta === true || event.super === true;
+}
+
+/**
+ * Whether the event is this chord. `primary` accepts Control or Command. Shift
+ * matters for letters and named keys, and a letter that arrives uppercase
+ * counts as shifted, which is how some terminals report Shift+R. Punctuation
+ * ignores Shift, because reaching `?` or `` ` `` needs Shift on many layouts
+ * and the host has already resolved which character came out.
+ */
+export function matchesKeyChord(chord: KeyChord, event: KeyChordEventLike): boolean {
+  const ctrl = event.ctrl === true;
+  const cmd = eventHasCmd(event);
+  if (chord.primary) {
+    if (!ctrl && !cmd) return false;
+  } else if (chord.ctrl !== ctrl || chord.cmd !== cmd) {
+    return false;
+  }
+  if (chord.alt !== (event.alt === true)) return false;
+
+  const raw = eventKeyName(event);
+  const shift = event.shift === true;
+  if (chord.key === "digit") {
+    return /^[1-9]$/.test(raw) && chord.shift === shift;
+  }
+  const named = NAMED_KEY_BY_ALIAS.get(chord.key);
+  if (named) {
+    return named.aliases.includes(raw.toLowerCase()) && chord.shift === shift;
+  }
+  if (isLetter(chord.key)) {
+    if (raw.toLowerCase() !== chord.key) return false;
+    const shifted = shift || (raw.length === 1 && raw !== raw.toLowerCase());
+    return chord.shift === shifted;
+  }
+  if (raw === chord.key || event.sequence === chord.key) return true;
+  // Terminals without the kitty protocol report a US-layout "?" as Shift+/.
+  return chord.key === "?" && raw === "/" && shift;
+}
+
+/** The digit an event pressed, for chords on the `digit` family. */
+export function keyChordDigit(event: KeyChordEventLike): number | null {
+  const raw = eventKeyName(event);
+  return /^[1-9]$/.test(raw) ? Number.parseInt(raw, 10) : null;
+}
+
+/**
+ * The chord an event represents, for capture. Returns null for a bare modifier.
+ * The host's own primary modifier is recorded as `CmdOrCtrl`, so a chord bound
+ * from the terminal still fires under Command in the desktop app on the same
+ * machine; the other one stays explicit.
+ */
+export function keyChordFromEvent(event: KeyChordEventLike, primaryModifier: PrimaryModifier): KeyChord | null {
+  const raw = eventKeyName(event);
+  if (MODIFIER_ONLY_EVENT_NAMES.has(raw.toLowerCase())) return null;
+
+  const chord = emptyChord();
+  const ctrl = event.ctrl === true;
+  const cmd = eventHasCmd(event);
+  if (ctrl && cmd) {
+    chord.ctrl = true;
+    chord.cmd = true;
+  } else if (ctrl) {
+    if (primaryModifier === "ctrl") chord.primary = true;
+    else chord.ctrl = true;
+  } else if (cmd) {
+    if (primaryModifier === "cmd") chord.primary = true;
+    else chord.cmd = true;
+  }
+  chord.alt = event.alt === true;
+
+  const named = NAMED_KEY_BY_ALIAS.get(raw.toLowerCase());
+  if (named && named.key !== "digit") {
+    chord.key = named.key;
+    chord.shift = event.shift === true;
+    return chord;
+  }
+  if ([...raw].length !== 1) return null;
+  if (isLetter(raw)) {
+    chord.key = raw.toLowerCase();
+    chord.shift = event.shift === true || raw !== raw.toLowerCase();
+    return chord;
+  }
+  chord.key = raw;
+  return chord;
+}

package/src/app/keybindings/config.ts

@@ -0,0 +1,83 @@
+import type { AppConfig, KeybindingsConfig } from "../../types/config";
+import { getKeybindingAction } from "./actions";
+import { keyChordsEqual, parseKeyChord, serializeKeyChord, type KeyChord } from "./chord";
+
+function withoutEmpty(config: KeybindingsConfig): KeybindingsConfig | undefined {
+  const actions = config.actions && Object.keys(config.actions).length > 0 ? config.actions : undefined;
+  const commands = config.commands && Object.keys(config.commands).length > 0 ? config.commands : undefined;
+  if (!actions && !commands) return undefined;
+  return { ...(actions ? { actions } : {}), ...(commands ? { commands } : {}) };
+}
+
+/** A config with `keybindings` replaced, and the key dropped once nothing is customised. */
+export function updateKeybindingsConfig(config: AppConfig, keybindings: KeybindingsConfig | undefined): AppConfig {
+  const next = keybindings ? withoutEmpty(keybindings) : undefined;
+  const { keybindings: _previous, ...rest } = config;
+  return next ? { ...rest, keybindings: next } : rest;
+}
+
+function defaultChordsFor(actionId: string, defaults?: readonly KeyChord[]): readonly KeyChord[] {
+  if (defaults) return defaults;
+  const def = getKeybindingAction(actionId);
+  return def ? def.defaults.map((text) => parseKeyChord(text)!).filter(Boolean) : [];
+}
+
+function sameChords(left: readonly KeyChord[], right: readonly KeyChord[]): boolean {
+  return left.length === right.length && left.every((chord, index) => keyChordsEqual(chord, right[index]!));
+}
+
+/**
+ * Binds an action to `chords`. An empty list unbinds it; a list equal to the
+ * defaults clears the override instead of recording a redundant one. Plugin
+ * shortcuts pass their own defaults, since the table does not know them.
+ */
+export function applyActionBinding(
+  config: KeybindingsConfig | undefined,
+  actionId: string,
+  chords: readonly KeyChord[],
+  defaults?: readonly KeyChord[],
+): KeybindingsConfig | undefined {
+  const actions = { ...(config?.actions ?? {}) };
+  if (sameChords(chords, defaultChordsFor(actionId, defaults))) {
+    delete actions[actionId];
+  } else if (chords.length === 0) {
+    actions[actionId] = null;
+  } else {
+    const texts = chords.map(serializeKeyChord);
+    actions[actionId] = texts.length === 1 ? texts[0]! : texts;
+  }
+  return withoutEmpty({ ...config, actions });
+}
+
+/** Binds a command bar query to a chord, replacing any command already on that chord. */
+export function setCommandBinding(
+  config: KeybindingsConfig | undefined,
+  chord: KeyChord,
+  query: string,
+): KeybindingsConfig | undefined {
+  const text = serializeKeyChord(chord);
+  const commands: Record<string, string> = {};
+  for (const [existingText, existingQuery] of Object.entries(config?.commands ?? {})) {
+    const existing = parseKeyChord(existingText);
+    if (existing && keyChordsEqual(existing, chord)) continue;
+    commands[existingText] = existingQuery;
+  }
+  commands[text] = query.trim();
+  return withoutEmpty({ ...config, commands });
+}
+
+/** Removes the command on `text`, matching by chord so `alt+1` and `Alt+1` are the same key. */
+export function removeCommandBinding(
+  config: KeybindingsConfig | undefined,
+  text: string,
+): KeybindingsConfig | undefined {
+  const target = parseKeyChord(text);
+  const commands: Record<string, string> = {};
+  for (const [existingText, existingQuery] of Object.entries(config?.commands ?? {})) {
+    if (existingText === text) continue;
+    const existing = parseKeyChord(existingText);
+    if (target && existing && keyChordsEqual(existing, target)) continue;
+    commands[existingText] = existingQuery;
+  }
+  return withoutEmpty({ ...config, commands });
+}

package/src/app/keybindings/index.ts

@@ -0,0 +1,62 @@
+export {
+  KEYBINDING_ACTIONS,
+  PLUGIN_ACTION_PREFIX,
+  getKeybindingAction,
+  isCoreKeybindingActionId,
+  pluginShortcutActionId,
+  type CoreKeybindingActionId,
+  type KeybindingActionCategory,
+  type KeybindingActionDef,
+} from "./actions";
+export {
+  formatKeyChord,
+  isTypingChord,
+  keyChordDigit,
+  keyChordFromEvent,
+  keyChordsEqual,
+  matchesKeyChord,
+  parseKeyChord,
+  serializeKeyChord,
+  type KeyChord,
+  type KeyChordEventLike,
+  type PrimaryModifier,
+} from "./chord";
+export {
+  describeKeybindingIssue,
+  isPaneKeybindingAction,
+  keyChordsOverlap,
+  keybindingActionLabel,
+  matchKeybinding,
+  matchesKeybindingAction,
+  pluginShortcutDefaultChord,
+  resolveKeybindings,
+  resolvePluginShortcutChords,
+  type KeybindingCommand,
+  type KeybindingIssue,
+  type KeybindingMatch,
+  type ResolvedKeybindingAction,
+  type ResolvedKeybindings,
+} from "./resolve";
+export {
+  advertisedChord,
+  chordsForHost,
+  formatActionChords,
+  formatAdvertisedChord,
+  formatChordForHost,
+  menuAcceleratorFor,
+  primaryModifierFor,
+} from "./labels";
+export { KeybindingsProvider, getDefaultKeybindings, useKeybindings, useResolvedKeybindings } from "./react";
+export {
+  applyActionBinding,
+  removeCommandBinding,
+  setCommandBinding,
+  updateKeybindingsConfig,
+} from "./config";
+export {
+  hasKeybindingCaptureRequest,
+  requestKeybindingCapture,
+  subscribeKeybindingCapture,
+  takeKeybindingCaptureRequest,
+  type KeybindingCaptureRequest,
+} from "./capture-request";

package/src/app/keybindings/labels.ts

@@ -0,0 +1,87 @@
+import {
+  detectShortcutPlatform,
+  type ShortcutDisplayMode,
+  type ShortcutPlatform,
+} from "../../utils/shortcut-labels";
+import { formatKeyChord, serializeKeyChord, type KeyChord, type PrimaryModifier } from "./chord";
+import type { ResolvedKeybindings } from "./resolve";
+
+/** What `CmdOrCtrl` is on this host: Control in a terminal, Command on a Mac desktop. */
+export function primaryModifierFor(
+  mode: ShortcutDisplayMode,
+  platform: ShortcutPlatform = detectShortcutPlatform(),
+): PrimaryModifier {
+  if (mode === "terminal") return "ctrl";
+  return platform === "darwin" ? "cmd" : "ctrl";
+}
+
+function cmdLabelFor(platform: ShortcutPlatform): string {
+  return platform === "darwin" ? "Cmd" : "Super";
+}
+
+export function formatChordForHost(
+  chord: KeyChord,
+  mode: ShortcutDisplayMode,
+  platform: ShortcutPlatform = detectShortcutPlatform(),
+): string {
+  return formatKeyChord(chord, {
+    primaryModifier: primaryModifierFor(mode, platform),
+    cmdLabel: cmdLabelFor(platform),
+  });
+}
+
+/**
+ * Chords worth showing on this host. A terminal cannot deliver an explicit
+ * Command chord, so those rows stay out of the terminal's help.
+ */
+export function chordsForHost(chords: readonly KeyChord[], mode: ShortcutDisplayMode): KeyChord[] {
+  return chords.filter((chord) => mode !== "terminal" || !chord.cmd);
+}
+
+export function formatActionChords(
+  resolved: ResolvedKeybindings,
+  actionId: string,
+  mode: ShortcutDisplayMode,
+  platform: ShortcutPlatform = detectShortcutPlatform(),
+): string[] {
+  const action = resolved.actionsById.get(actionId);
+  if (!action) return [];
+  return chordsForHost(action.chords, mode).map((chord) => formatChordForHost(chord, mode, platform));
+}
+
+/**
+ * The one chord a host advertises for an action when there is room for a single
+ * label. The terminal takes the first chord it can deliver; desktop hosts prefer
+ * a chord on the platform modifier, so the header says Cmd+K on a Mac while the
+ * terminal keeps saying Ctrl+P. Empty when the action is unbound.
+ */
+export function advertisedChord(
+  resolved: ResolvedKeybindings,
+  actionId: string,
+  mode: ShortcutDisplayMode,
+): KeyChord | null {
+  const chords = chordsForHost(resolved.actionsById.get(actionId)?.chords ?? [], mode);
+  if (chords.length === 0) return null;
+  if (mode === "terminal") return chords[0]!;
+  return chords.find((chord) => chord.primary || chord.cmd) ?? chords[0]!;
+}
+
+export function formatAdvertisedChord(
+  resolved: ResolvedKeybindings,
+  actionId: string,
+  mode: ShortcutDisplayMode,
+  platform: ShortcutPlatform = detectShortcutPlatform(),
+): string {
+  const chord = advertisedChord(resolved, actionId, mode);
+  return chord ? formatChordForHost(chord, mode, platform) : "";
+}
+
+/**
+ * The accelerator a native menu shows for an action. Menus only take chords on
+ * the platform modifier: a bare backtick as a key equivalent would swallow the
+ * character everywhere.
+ */
+export function menuAcceleratorFor(resolved: ResolvedKeybindings, actionId: string): string | undefined {
+  const chord = resolved.actionsById.get(actionId)?.chords.find((entry) => entry.primary || entry.cmd);
+  return chord ? serializeKeyChord(chord) : undefined;
+}