@inklu/keys 1.0.0 → 1.2.0

package/README.md

@@ -1,18 +1,17 @@
 # @inklu/keys
 
-Keyboard shortcut management for the web. Define commands once, bind keys to them separately, and let users remap anything.
-
-Built on [TanStack Hotkeys](https://tanstack.com/hotkeys) for key matching, which means typed hotkey strings, portable `Mod` bindings, layout-aware parsing and a single document listener no matter how many commands you register. `@inklu/keys` adds what an application needs on top: a registry, scopes, conflict detection, persistence, rebinding, and shortcuts a screen reader can read.
+Keyboard shortcut management for the web. Built on TanStack Hotkeys, `@inklu/keys` provides a registry, scopes, conflict detection, and screen-reader-ready shortcuts.
 
 ```bash
 pnpm add @inklu/keys
 ```
 
-## The idea
+## 1. Define Commands
 
-A **command** is an addressable thing your app can do — it has an id, a title and a handler. A **binding** is a key that triggers it. Keeping them apart is what makes the rest possible: the same command runs from the keyboard, a palette, a menu item or code, and a user can rebind it without you touching its definition.
+A command is an addressable action. It has an id, title, and a handler.
 
 ```ts
+// commands.ts
 import { createCommands, seq } from "@inklu/keys";
 
 export const commands = createCommands({
@@ -21,237 +20,116 @@ export const commands = createCommands({
     keys: "Mod+K",
     run: () => setPaletteOpen(true),
   },
-  "doc.save": {
-    title: "Save document",
-    keys: "Mod+S",
-    when: () => isDirty(),
-    run: () => save(),
-  },
   "nav.inbox": {
     title: "Go to inbox",
     keys: seq("G", "I"), // press G, then I
     run: () => navigate("/inbox"),
   },
 });
-
-commands.mount(); // start listening; returns a function to stop
 ```
 
-Ids are inferred from the object, so `commands.run("doc.save")` autocompletes and a typo is a type error. So is a typo in a definition — `key:` instead of `keys:` would otherwise bind nothing at all, silently.
-
-`Mod` resolves to <kbd>⌘</kbd> on macOS and <kbd>Ctrl</kbd> everywhere else, so you write a shortcut once.
-
-### What this is not
-
-This is not a command-palette toolkit. There is no palette component, no fuzzy matcher, no ranking, and no `group` or `description` on a command — a command is an id, a title, a handler and its keys, and that is the whole of it. Filtering commands is your app's business and every app wants it slightly differently. This package gives you the list, current shortcuts and current state; sorting it is three lines you own:
-
-```ts
-const results = commands.filter((command) =>
-  command.title.toLowerCase().includes(query.toLowerCase()),
-);
-```
+## 2. React Setup
 
-## React
+Pass the registry explicitly to all hooks. There is no Context provider.
 
 ```tsx
-import { useCommands, useMountCommands } from "@inklu/keys/react";
+import { useCommands, useMountCommands, useShortcut } from "@inklu/keys/react";
 import { commands } from "./commands";
 
 function App() {
+  // Starts listening in an effect
   useMountCommands(commands);
-  return <Shortcuts />;
+  return <ShortcutButton />;
 }
 
-function Shortcuts() {
-  const list = useCommands(commands);
-
-  return list.map((command) => (
-    <button
-      key={command.id}
-      onClick={() => commands.run(command.id)}
-      aria-keyshortcuts={command.aria || undefined}
+function ShortcutButton() {
+  // Get live shortcut state
+  const shortcut = useShortcut(commands, "palette.open");
+  
+  return (
+    <button 
+      onClick={() => commands.run("palette.open")}
+      aria-keyshortcuts={shortcut.aria || undefined}
     >
-      {command.title}
-      {command.tokens[0]?.map((token, i) => <kbd key={i}>{token}</kbd>)}
+      Open Palette
+      {shortcut.tokens[0]?.map((token, i) => <kbd key={i}>{token}</kbd>)}
     </button>
-  ));
+  );
 }
 ```
 
-`useMountCommands` starts listening in an effect, so nothing touches the DOM during render and the registry is safe to create at module scope in a server-rendered app.
-
-**Every hook takes the registry as its first argument.** There is no provider and no context: you already have the registry by importing it, and passing it explicitly is what keeps the ids typed — through context they widen to `string` and `useShortcut("typo")` stops being an error.
-
-| Hook | What it gives you |
-| :--- | :--- |
-| `useMountCommands(commands)` | Starts listening for as long as the component lives |
-| `useCommands(commands)` | Every command, with live shortcuts and state |
-| `useCommand(commands, id)` | One command's live state |
-| `useShortcut(commands, id)` | `{ display, tokens, aria }`, ready to render |
-| `useScope(commands, name, active, { exclusive })` | Activates a scope while a component is mounted |
-| `useRegisterCommand(commands, id, definition)` | A command that exists only while a feature is on screen |
-| `useRebind(commands, id)` | The "press the keys you want" flow, with conflicts |
-| `useHeldKeys()` | The keys physically down right now |
-
-## Server rendering
-
-There is no `navigator` on the server, so a shortcut has to be written for *some* platform before the browser can be asked. The registry writes `Ctrl+K` on the server and in the first client render, then settles on the real platform at `mount()` and re-renders. A Mac user sees `⌘K` a frame later instead of a hydration mismatch.
-
-Pin `platform` if you know better, and nothing ever changes:
-
-```ts
-createCommands(definitions, { platform: "mac" });
-```
-
-## Accessibility
+## 3. Scopes
 
-Every command carries an `aria` string — the value for [`aria-keyshortcuts`](https://developer.mozilla.org/docs/Web/Accessibility/ARIA/Attributes/aria-keyshortcuts), which is what a screen reader announces. It is deliberately not the display string: the attribute wants resolved key *names*, so `Mod+K` becomes `Meta+K` on macOS and `Control+K` elsewhere, never `⌘K`.
+Use scopes to isolate commands when modals or dialogs are open.
 
 ```tsx
-<button aria-keyshortcuts={command.aria || undefined}>Save</button>
-```
-
-Sequences produce `""`. The attribute separates *alternatives* with spaces, so emitting `seq("G","I")` as `"G I"` would announce "press G or I" — the opposite of what it means. There is no way to express a sequence, so the package says nothing rather than something false.
+import { useScope } from "@inklu/keys/react";
 
-If you render shortcuts as `<kbd>⌘</kbd>`, give the control an accessible name too — a screen reader reads that glyph by its Unicode name, not as "Command".
+function Dialog({ isOpen }) {
+  // When exclusive is true, commands outside this scope are silenced
+  useScope(commands, "dialog", isOpen, { exclusive: true });
 
-## Scopes
+  return isOpen ? <div className="dialog">...</div> : null;
+}
+```
 
-A scope decides whether a command is reachable. Push one while a dialog is open and it shadows the rest of the app, so you do not end up writing `if (!modalOpen)` in twenty different handlers.
+`exclusive` is a barrier: it silences the whole app beneath it. To claim only a few keys, drop it and give those commands a `scope` instead — see below.
 
-```ts
-const release = commands.pushScope("dialog", { exclusive: true });
-// …everything below this barrier stops responding
-release();
-```
+### When two commands share a key
 
-In React that is `useScope("dialog", isOpen, { exclusive: true })`.
+Exactly one command runs per keypress. The winner is:
 
-`exclusive` is a **barrier, not a filter**: everything at or above the topmost barrier stays reachable, everything below it goes quiet. That is what lets a menu opened inside a dialog keep working while the page behind the dialog does not. Commands scoped `"*"` always fire.
+1. The command in a named scope, over a global one. `"*"` counts as global here — it means "survives barriers", not "belongs to a region of the UI".
+2. Failing that, the one registered later. Registration order tracks mount order, so the most recently opened surface claims the key.
 
-Scoping is resolved when a scope is pushed or released, never per keystroke — an open dialog costs one pass over the registrations rather than a check on every key the user presses.
+A winner whose `when()` currently returns `false` steps aside rather than swallowing the keypress. This is how `Escape` closes the dialog when one is open and the panel otherwise, without making the dialog `exclusive`. Two commands sharing a chord *in the same scope* can never separate, so that case warns in development.
 
-## Rebinding
+## 4. Rebinding
 
-Bindings live in a keymap, layered as defaults plus user overrides, so "reset to default" is exact rather than approximate.
+Overrides are layered over defaults.
 
 ```ts
 commands.keymap.set("palette.open", "Mod+P");     // remap
 commands.keymap.add("palette.open", "Control+P"); // an additional key
-commands.keymap.set("palette.open", null);        // unbind, but keep the command
-commands.keymap.reset("palette.open");            // forget the override, back to the default
-commands.keymap.reset();                          // …for every command
+commands.keymap.set("palette.open", null);        // unbind
+commands.keymap.reset("palette.open");            // reset to default
 ```
 
-`set(id, null)` and `reset(id)` are different on purpose: the first records an explicit "no keys" that survives, the second forgets that the user chose anything at all.
-
-Persist them by handing the registry a storage getter:
+To rebind a command you did not define — one a package shipped — pass `bindings` when creating the registry. An unknown id is a compile error, and `reset` returns here rather than to the definition's `keys`:
 
 ```ts
-createCommands(definitions, {
-  persist: { storage: () => localStorage },
+createCommands(commands, {
+  bindings: {
+    "palette.open": "Mod+P", // replace the shipped default
+    "doc.publish": null,     // ship it unbound
+  },
 });
 ```
 
-A getter is the only accepted form, so nothing touches `localStorage` at module scope and the package stays safe to import on the server. Overrides that no longer parse — a hand-edited value, a key that was renamed — are skipped rather than thrown on, so one bad row cannot lock a user out of their own shortcuts.
-
-**Overrides are user data.** They are keyed by command id and outlive the command: unregistering a feature drops its defaults but keeps the key someone chose, so a panel that comes and goes does not quietly reset it. Only `keymap.reset(id)` forgets one.
-
-### Conflicts
-
-```ts
-commands.conflicts("Mod+K", { ignore: "palette.open" });
-// → [{ id: "search.open", display: "⌘K", scope: undefined }]
-```
-
-Two commands only conflict when their scopes can be active at the same time, so the same key may safely mean different things in different places. A global command conflicts with every scope, because it stays reachable inside them.
+These are defaults, applied before persisted overrides load, so a user's own rebinding still wins.
 
-In development the registry reports collisions itself: once at startup for the initial map, and again whenever a command is added at runtime, which in a React app is where most of them come from. It also warns about bindings the key parser cannot read — a mistyped modifier is otherwise silent, because the parser drops the part it does not recognize and `"Mdo+K"` quietly becomes a bare `K`.
-
-### Recording
+In React, use the `useRebind` hook for a capture flow:
 
 ```tsx
-const rebind = useRebind("palette.open");
+const rebind = useRebind(commands, "palette.open");
 
 <button onClick={rebind.start}>
   {rebind.recording ? "Press keys…" : rebind.display}
 </button>;
-{rebind.overridden && <button onClick={rebind.reset}>Reset</button>}
-{rebind.conflicts.length > 0 && <p>Also used by {rebind.conflicts[0].id}</p>}
-```
-
-`display`, `tokens` and `overridden` come from the command itself rather than from the last capture, so a rebind made anywhere else in the app still shows up here.
-
-Commands are suppressed while recording, so capturing `Mod+K` does not also fire whatever `Mod+K` is currently bound to.
-
-## Markup
-
-For pages that are not React, `@inklu/keys/attributes` wires the DOM to a registry with one delegated listener:
-
-```html
-<button data-command="palette.open">
-  Search <kbd data-command-keys="palette.open"></kbd>
-</button>
-```
-
-```ts
-import { observe } from "@inklu/keys/attributes";
-const dispose = observe(commands);
-```
-
-Elements with `data-command-keys` are filled with the current shortcut and stay in sync when it is rebound. Elements with `data-command` also get `aria-keyshortcuts` set for free.
-
-## Behaviour worth knowing
-
-**Typing in inputs.** Bare keys and Shift/Alt combos are ignored while the user is in an `input`, `textarea` or contenteditable; Ctrl/Meta shortcuts and `Escape` still fire. So `Mod+K` works from inside your search box, and `/` does not. Override per command with `ignoreInputs`.
-
-**Consuming the event.** A command calls `preventDefault()` only when it actually runs. A command that is disabled, out of scope, or blocked by `when` leaves the key alone for the browser and for other handlers. Opt out with `preventDefault: false`. Propagation is never stopped — the matcher already prevents other hotkeys from firing, and halting the DOM event too would silently break delegation in your app.
-
-**`when` is a guard, not state.** It is checked immediately before running and is not observed, so it will not re-render anything. Use `setEnabled` or scopes for state that should be visible in the UI — `command.reachable` reflects both.
-
-**Why didn't my shortcut fire?** `commands.whyNotRun(id)` returns `"disabled"`, `"out-of-scope"`, `"guarded"`, `"unknown"`, or `null` when it would have run.
-
-**Knowing what ran.** `onRun` is called for every command, whatever triggered it — that is the hook for recent-command ordering, analytics or an activity log, so a command's own `run` does not have to report on itself.
-
-```ts
-createCommands(definitions, {
-  onRun: ({ id, source }) => recents.push(id),
-});
-```
-
-**Async commands.** `run` may be async. Nothing awaits it — a keystroke is fire-and-forget — but a rejection still reaches `onError` rather than the unhandled-rejection channel. If you need to await, do it inside your own handler.
-
-**One way to write a binding.** A chord is a string, `"Mod+K"`. A sequence is `seq("G", "I")`. An array means alternatives — `keys: ["Mod+K", "/"]` binds two different keys to one command. There is no object form of a chord and no inline `"G I"` string, so nothing has to normalize a binding before it can compare, format or store one.
-
-## API
-
-```ts
-createCommands(definitions, options)  // → Commands
-commands.list()                       // → readonly Command[], stable identity
-commands.get(id)
-commands.run(id, options?)            // → boolean
-commands.canRun(id) / commands.whyNotRun(id)
-commands.setEnabled(id, enabled)
-commands.add(id, definition)          // → { run, dispose }
-commands.remove(id)                   // keeps the user's override
-commands.pushScope(name, { exclusive })  // → release()
-commands.conflicts(binding, { ignore, scope })
-commands.display(id) / commands.tokens(id)   // "" / [] when unbound
-commands.mount()                      // → stop()
-commands.subscribe(listener)          // → unsubscribe()
-commands.destroy()
-commands.keymap                       // get / set / add / reset / export / import
 ```
 
-`list()` returns the same array until something actually changes, so it can go straight into `useSyncExternalStore`. Each `Command` carries `title`, `scope`, `bindings`, `display`, `tokens`, `aria`, `enabled`, `reachable` and `overridden`.
+## API Summary
 
-`display(id)` and `tokens(id)` take a command id. To format a binding you are holding directly — one out of `conflicts()`, say — `formatBinding` and `bindingTokens` are exported for that, and every `Conflict` already carries its own `display`.
+- `createCommands(definitions, options)` - creates the registry
+  - `options`: `{ bindings, platform, target, persist, display, onRun, onError }`
+- `useMountCommands(commands)` - starts listening
+- `useShortcut(commands, id)` - gets display tokens and aria for rendering
+- `useScope(commands, name, active, { exclusive })` - isolates command execution
+- `useRebind(commands, id)` - records user shortcuts
 
-`CommandId<typeof commands>` is the id union, for typing values that travel alongside the registry:
+## Accessibility
 
-```ts
-export type AppCommandId = CommandId<typeof commands>;
-```
+Every command carries an `aria` string. Apply it to `aria-keyshortcuts` so screen readers announce the exact key sequence.
 
 ## License
 

package/dist/{attributes-lCPeoWII.d.ts → attributes-DbxlLdrb.d.ts}

@@ -143,7 +143,25 @@ interface CommandKeymap<Id extends string = string> {
 //#endregion
 //#region src/registry.d.ts
 /** Configuration options for a commands registry. */
-interface CommandsOptions {
+interface CommandsOptions<Id extends string = string> {
+  /**
+   * Replaces the default `keys` a command was defined with, keyed by command
+   * id. Lets an app rebind commands it did not define — a package ships the
+   * behaviour, the app decides which key reaches it — and an unknown id is a
+   * compile error rather than a silent no-op. `null` ships the command with
+   * no default binding at all.
+   *
+   * These are defaults, applied before persisted overrides load, so a user's
+   * own rebinding still wins.
+   *
+   * @example
+   * ```ts
+   * createCommands(commands, {
+   *   bindings: { "palette.open": "Mod+P", "doc.publish": null },
+   * });
+   * ```
+   */
+  bindings?: Partial<Record<Id, BindingInput | null>>;
   /** Platform for modifier resolution and display formatting. Defaults to auto-detection. */
   platform?: Platform;
   /** Target element for key events. Defaults to `document`. */
@@ -260,7 +278,7 @@ interface Commands<Id extends string = string> {
  * });
  * ```
  */
-declare function createCommands<const T extends { [K in keyof T]: CommandDefinition & Record<Exclude<keyof T[K], keyof CommandDefinition>, never>; }>(definitions: T, options?: CommandsOptions): Commands<Extract<keyof T, string>>;
+declare function createCommands<const T extends { [K in keyof T]: CommandDefinition & Record<Exclude<keyof T[K], keyof CommandDefinition>, never>; }>(definitions: T, options?: CommandsOptions<Extract<keyof T, string>>): Commands<Extract<keyof T, string>>;
 /**
  * Extracts command ID union from a Commands registry type.
  *

package/dist/attributes.d.ts

@@ -1,2 +1,2 @@
-import { n as observe, t as ObserveOptions } from "./attributes-lCPeoWII.js";
+import { n as observe, t as ObserveOptions } from "./attributes-DbxlLdrb.js";
 export { ObserveOptions, observe };

package/dist/{index-WDNLK0dX.d.ts → index-D4UoKAQU.d.ts}

@@ -1,4 +1,4 @@
-import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-lCPeoWII.js";
+import { M as SequenceBinding, T as Conflict, a as Commands, b as Chord, v as Binding } from "./attributes-DbxlLdrb.js";
 import { Hotkey } from "@tanstack/hotkeys";
 //#region src/bindings.d.ts
 /**

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-lCPeoWII.js";
-import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-WDNLK0dX.js";
+import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-DbxlLdrb.js";
+import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-D4UoKAQU.js";
 export { ALWAYS_SCOPE, type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandle, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictOptions, type DisplayOptions, type Hotkey, type HotkeySequence, type KeymapPersistence, type KeymapStorage, type ObserveOptions, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, validateBinding };

package/dist/index.js

@@ -1,3 +1,3 @@
 import { observe } from "./attributes.js";
-import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, t as createCommands, u as validateBinding } from "./src-B305icXC.js";
+import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, t as createCommands, u as validateBinding } from "./src-DyFUgmho.js";
 export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, observe, seq, validateBinding };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-lCPeoWII.js";
-import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-WDNLK0dX.js";
+import { A as Platform, C as CommandDefinition, D as HotkeySequence, E as Hotkey, M as SequenceBinding, N as SerializedBinding, O as KeymapPersistence, S as CommandContext, T as Conflict, _ as formatBinding, a as Commands, b as Chord, c as PendingSequence, d as createCommands, f as CommandKeymap, g as bindingTokens, h as ariaKeyShortcuts, i as CommandId, j as ScopeOptions, k as KeymapStorage, l as RunBlockReason, m as DisplayOptions, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as Binding, w as CommandSource, x as Command, y as BindingInput } from "./attributes-DbxlLdrb.js";
+import { a as Rebinder, c as seq, i as RebindState, l as validateBinding, n as RebindMode, o as createRebinder, r as RebindOptions, s as BindingValidation, t as ALWAYS_SCOPE } from "./index-D4UoKAQU.js";
 //#region src/react/hooks.d.ts
 /**
  * Mounts a commands registry for the lifecycle of the component.

package/dist/react.js

@@ -1,6 +1,6 @@
 "use client";
 import { observe } from "./attributes.js";
-import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, l as toBindings, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, s as bindingSignature, t as createCommands, u as validateBinding } from "./src-B305icXC.js";
+import { a as bindingTokens, c as seq, i as ariaKeyShortcuts, l as toBindings, n as ALWAYS_SCOPE, o as formatBinding, r as createRebinder, s as bindingSignature, t as createCommands, u as validateBinding } from "./src-DyFUgmho.js";
 import { getKeyStateTracker } from "@tanstack/hotkeys";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 //#region src/react/hooks.ts

package/dist/{src-B305icXC.js → src-DyFUgmho.js}

@@ -340,7 +340,7 @@ var Binder = class {
 		this.#bound.clear();
 	}
 	#register(id, binding, signature, definition, enabled) {
-		const callback = (event) => this.#handle(id, binding, event);
+		const callback = (event) => this.#handle(id, binding, signature, event);
 		const options = {
 			preventDefault: false,
 			stopPropagation: false,
@@ -370,8 +370,18 @@ var Binder = class {
 			return null;
 		}
 	}
-	#handle(id, binding, event) {
+	/**
+	* One keypress can reach several registrations (see `conflictBehavior`
+	* above), so every candidate asks the registry whether it won before doing
+	* anything observable. Arbitration comes before `preventDefault` on
+	* purpose: a losing command must leave the event exactly as it found it,
+	* or a command declaring `preventDefault: false` would still have the
+	* browser's default action cancelled by whichever rival happened to be
+	* registered alongside it.
+	*/
+	#handle(id, binding, signature, event) {
 		if (!this.#host.canRun(id)) return;
+		if (!this.#host.claims(id, signature)) return;
 		const definition = this.#host.getDefinition(id);
 		if (!definition) return;
 		if (definition.preventDefault !== false) event.preventDefault();
@@ -394,7 +404,7 @@ var Keymap = class {
 	constructor(persistence) {
 		this.#persistence = persistence;
 	}
-	/** Sets a command's default bindings. */
+	/** Sets a command's default bindings. `null` leaves the command unbound. */
 	setDefault(loose, input) {
 		const id = loose;
 		const bindings = toBindings(input);
@@ -573,6 +583,7 @@ var CommandRegistry = class {
 	#pendingSubscription = null;
 	#snapshot = null;
 	#index = null;
+	#ownerIndex = null;
 	#mounts = 0;
 	#hydrated = false;
 	#barrier = false;
@@ -584,6 +595,7 @@ var CommandRegistry = class {
 			getBindings: (id) => this.#keymap.get(id),
 			canRun: (id) => this.canRun(id),
 			isReachable: (id) => this.#isReachable(id),
+			claims: (id, signature) => this.#claims(id, signature),
 			platform: () => this.#platform(),
 			execute: (id, context) => {
 				this.#execute(id, context);
@@ -808,7 +820,9 @@ var CommandRegistry = class {
 		const definition = this.#definition(id);
 		if (!definition) return;
 		this.#enabled.set(id, definition.enabled !== false);
-		this.#keymap.setDefault(id, definition.keys);
+		const overrides = this.#options.bindings;
+		const keys = overrides && Object.hasOwn(overrides, id) ? overrides[id] : definition.keys;
+		this.#keymap.setDefault(id, keys);
 	}
 	#drop(id) {
 		this.#stacks.delete(id);
@@ -822,6 +836,57 @@ var CommandRegistry = class {
 		if (!(this.#enabled.get(id) ?? false)) return false;
 		return this.#scopes.isActive(this.#definition(id)?.scope);
 	}
+	/**
+	* Decides which of several commands sharing one binding gets to run.
+	*
+	* Without this every registration for the pressed chord fires, so two
+	* commands bound to `Mod+S` in overlapping scopes both ran and the only
+	* defence was a dev-time console warning. Exclusive scopes could not fix
+	* it either: a barrier shadows *every* global command, not just the one
+	* colliding, so "Esc closes the dialog, and the panel otherwise" forced
+	* the whole dialog to become exclusive.
+	*
+	* Ranking, highest first:
+	*
+	*   1. A command in a named scope beats a global one. `ALWAYS_SCOPE` is
+	*      global for this purpose — it means "survives barriers", not
+	*      "belongs to some region of the UI".
+	*   2. Later registration beats earlier. Registration order tracks mount
+	*      order, so the most recently opened surface claims the key — the
+	*      same intuition that makes `add()` stack definitions per id.
+	*
+	* Guards are evaluated live rather than baked into the ranking, so a
+	* winner whose `when()` currently returns false steps aside instead of
+	* swallowing the keypress.
+	*/
+	#claims(id, signature) {
+		const candidates = this.#owners().get(signature);
+		if (!candidates || candidates.length < 2) return true;
+		for (const candidate of candidates) {
+			if (candidate !== id && !this.canRun(candidate)) continue;
+			return candidate === id;
+		}
+		return false;
+	}
+	/** Binding signature → command ids that share it, ranked by `#claims`. */
+	#owners() {
+		if (this.#ownerIndex) return this.#ownerIndex;
+		const platform = this.#platform();
+		const index = /* @__PURE__ */ new Map();
+		for (const id of this.#order) for (const binding of this.#keymap.get(id)) {
+			const signature = bindingSignature(binding, platform);
+			const ids = index.get(signature);
+			if (ids) ids.unshift(id);
+			else index.set(signature, [id]);
+		}
+		for (const ids of index.values()) if (ids.length > 1) ids.sort((a, b) => this.#scopeRank(b) - this.#scopeRank(a));
+		this.#ownerIndex = index;
+		return index;
+	}
+	#scopeRank(id) {
+		const scope = this.#definition(id)?.scope;
+		return scope === void 0 || scope === "*" ? 0 : 1;
+	}
 	#execute(id, context) {
 		const definition = this.#definition(id);
 		if (!definition) return;
@@ -894,6 +959,7 @@ var CommandRegistry = class {
 	#invalidate() {
 		this.#snapshot = null;
 		this.#index = null;
+		this.#ownerIndex = null;
 		for (const listener of this.#listeners) listener();
 	}
 	#warnAboutConflicts() {
@@ -908,10 +974,10 @@ var CommandRegistry = class {
 					seen.set(key, id);
 					continue;
 				}
-				collisions.push(`${formatBinding(binding, this.#displayOptions())} — "${owner}" and "${id}"`);
+				collisions.push(`${formatBinding(binding, this.#displayOptions())} — "${id}" shadows "${owner}"`);
 			}
 		}
-		if (collisions.length > 0) console.warn(`[@inklu/keys] ${collisions.length} conflicting binding(s):\n  ${collisions.join("\n  ")}`);
+		if (collisions.length > 0) console.warn(`[@inklu/keys] ${collisions.length} unreachable binding(s) — same chord, same scope:\n  ${collisions.join("\n  ")}`);
 	}
 	#warnAboutBindings(id) {
 		for (const binding of this.#keymap.get(id)) {
@@ -921,9 +987,17 @@ var CommandRegistry = class {
 			console.warn(`[@inklu/keys] "${id}" has an unrecognized binding ${describeBinding(binding)}, which resolves to "${resolved}". ${errors.join("; ")}.`);
 		}
 	}
+	/** Catches ids in `options.bindings` that TypeScript could not — plain JS, or a runtime-only command. */
+	#warnAboutUnknownOverrides() {
+		const overrides = this.#options.bindings;
+		if (!overrides) return;
+		const unknown = Object.keys(overrides).filter((id) => !this.#stacks.has(id));
+		if (unknown.length > 0) console.warn(`[@inklu/keys] bindings override ${unknown.map((id) => `"${id}"`).join(", ")}, which ${unknown.length === 1 ? "is not a registered command" : "are not registered commands"}.`);
+	}
 	#audit() {
 		if (!isDevelopment()) return;
 		for (const id of this.#order) this.#warnAboutBindings(id);
+		this.#warnAboutUnknownOverrides();
 		this.#warnAboutConflicts();
 	}
 	#auditAdded(id) {
@@ -933,7 +1007,10 @@ var CommandRegistry = class {
 		for (const conflict of this.conflicts(this.#keymap.get(id), {
 			ignore: id,
 			scope
-		})) console.warn(`[@inklu/keys] "${id}" binds ${conflict.display}, which "${conflict.id}" already uses.`);
+		})) {
+			const winner = this.#scopeRank(conflict.id) > this.#scopeRank(id) ? conflict.id : id;
+			console.warn(`[@inklu/keys] "${id}" binds ${conflict.display}, which "${conflict.id}" already uses. While both are runnable the key goes to "${winner}".`);
+		}
 	}
 };
 function describeBinding(binding) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inklu/keys",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A command system for the web — typed commands, portable keybindings, scopes, sequences, conflict detection, rebinding, and platform-aware display.",
   "keywords": [
     "keyboard",