@inklu/keys 2.1.0 → 2.2.0

package/README.md

@@ -8,9 +8,9 @@ Three ideas, learned as you need them:
 - **Handler**: what the command does, attached from the component that owns the state.
 - **Keymap**: the keys, kept apart from the definition so users can rebind them.
 
-It has no dependencies, and listens with one `keydown` listener however many commands exist.
+It has no dependencies, and listens with one `keydown` listener however many commands exist. What an app does not use, it does not ship: persistence, recording a shortcut and palette search are imports of their own, and the registry does not pull them in.
 
-Docs: [inklu.saddy.me/keys](https://inklu.saddy.me/keys) · For agents: [llms.txt](https://inklu.saddy.me/keys/llms.txt) · Agent skill: `npx skills add nkurunziza-saddy/inklu --skill inklu-keys`
+Docs: [inklu.saddy.me/keys](https://inklu.saddy.me/keys) · For agents: [llms.txt](https://inklu.saddy.me/keys/llms.txt) · Agent skills: `npx skills add nkurunziza-saddy/inklu --skill inklu-keys` for the API, and `--skill inklu-keys-practices` for choosing and showing shortcuts well
 
 ```bash
 pnpm add @inklu/keys
@@ -38,6 +38,43 @@ export const commands = createCommands({
 });
 ```
 
+### Keys that differ by platform
+
+`Mod` covers most shortcuts, since it is Command on a Mac and Control everywhere else. Where the platforms' own conventions differ, give each its keys: `mac` is for Apple keyboards (macOS, iPadOS, iOS), `other` for the rest. A side left out is unbound there.
+
+```ts
+createCommands({
+	"edit.redo": { title: "Redo", keys: { mac: "Mod+Shift+Z", other: ["Mod+Y", "Mod+Shift+Z"] } },
+	"nav.back": { title: "Back", keys: { mac: "Mod+[", other: "Alt+ArrowLeft" } },
+	"doc.new": { title: "New document", keys: { mac: "Mod+Alt+N", other: "Alt+N" } },
+});
+```
+
+Some keys are not an app's to bind, and the registry warns about them in development:
+
+- **Reserved by the browser or the operating system.** `Mod+N`, `Mod+T`, `Mod+W` and their `Shift` forms, `Control+Tab`, `Mod+Q` on a Mac, `Alt+F4` and anything holding `Meta` (the Windows or Super key) elsewhere. The page never receives most of these, so `preventDefault()` cannot help. That is why `doc.new` above is not `Mod+N`.
+- **`Control+Alt` with a character key, on Windows and Linux.** Many keyboard layouts report AltGr as `Control+Alt`, and there the keys type a character (`@`, `€`, `{`) instead. `Mod+Alt+N` is fine on a Mac and not elsewhere, which is the other reason for `{ mac, other }`.
+- **`Control+Alt` on a Mac.** It is the VoiceOver modifier.
+
+Browser features a page _can_ take over (`Mod+F`, `Mod+P`, `Mod+L`, `Mod+R`) are left to your judgement: do it only where your version does the same job better.
+
+### Commands generated from data
+
+Ids come from the object's keys, so generated commands are typed when their keys are. `Object.fromEntries` returns plain string keys; give the result its key type where you build it:
+
+```ts
+const pages = Object.fromEntries(
+	docs.map((doc) => [`go.${doc.slug}`, { title: doc.title, run: () => router.navigate(doc.path) }]),
+) as Record<`go.${Slug}`, CommandDefinition>;
+
+export const commands = createCommands({
+	"palette.open": { title: "Open command palette", keys: "Mod+K" },
+	...pages,
+});
+```
+
+Spread from a `Record<string, CommandDefinition>` instead, the commands still exist at runtime but the types only know the literal keys. To have the compiler check that every id is present, name the ids yourself: `createCommands<AppCommandId>({ … })`.
+
 ## 2. React Setup
 
 Pass the registry explicitly to all hooks. There is no Context provider.
@@ -89,6 +126,7 @@ useCommandHandler(commands, "doc.save", save, dirty);
 - A command with no handler cannot run and leaves its key alone, so unmounting a feature switches its shortcuts off with it.
 - The most recently mounted handler wins. Unmounting hands the command back to the one before it, or to the definition's `run`. "Most recently" is the order React runs effects in, so of a parent and a child mounting in the same render, the parent's comes last and wins.
 - Outside React, `commands.handle(id, run)` does the same and returns a function that detaches.
+- A handler is attached when its component mounts. Keep it with its state in code that is already loaded, and lazy-load only what it shows: a handler inside a lazily loaded component leaves the key to the browser until its chunk arrives.
 
 Switch a command off by its handler (`enabled`, or detaching) rather than with an early `return` inside it: only then does the key fall through to another command or the browser.
 
@@ -165,6 +203,7 @@ import { createRebinder } from "@inklu/keys";
 const rebinder = createRebinder(commands, "palette.open", {
 	mode: "chord", // or "sequence": Enter or `commit()` finishes it
 	rejectConflicts: true, // don't apply a binding another command uses
+	// A binding the browser or OS reserves is never applied, whatever this says.
 	onRecord: (binding, conflicts) => {},
 });
 rebinder.subscribe(() => render(rebinder.state)); // { recording, binding, steps, conflicts }
@@ -175,39 +214,51 @@ While recording, every command is silenced — including `"*"` ones — so the k
 
 ## 5. Conflicts
 
-`commands.conflicts(binding, { scope, ignore })` lists commands in overlapping scopes whose bindings collide with `binding`. Each result has a `kind`:
+`commands.conflicts(binding, { scope, ignore })` lists what stands in the way of `binding`. Each result has a `kind`:
 
-- `"exact"` — the same keys. Only one command runs (see above).
+- `"reserved"` — the browser or operating system keeps these keys on this platform (see [Keys that differ by platform](#keys-that-differ-by-platform)). Listed first. A rebinder reports it and never applies the binding.
+- `"exact"` — a command in an overlapping scope has the same keys. Only one command runs (see above).
 - `"prefix"` — one binding starts the other, like `G` against `seq("G", "I")`. These cannot be arbitrated: pressing `G` runs the chord, and continuing with `I` runs the sequence too.
 
-In development, both kinds are also reported with `console.warn` when the registry is created. The check is dropped from production builds.
+Only a conflict with a command has an `id`, so narrow on `kind` before reading it:
+
+```tsx
+rebind.conflicts.map((conflict) =>
+	conflict.kind === "reserved"
+		? `${conflict.display} belongs to the browser`
+		: `Also used by ${commands.get(conflict.id)?.title}`,
+);
+```
+
+In development, all three are also reported with `console.warn` when the registry is created, for the defaults on both kinds of platform. The check is dropped from production builds.
 
 ## 6. Persistence and SSR
 
 ```ts
-createCommands(definitions, {
-	persist: {
-		storage: () => (typeof window === "undefined" ? null : localStorage),
-		key: "my-app.keys",
-	},
-});
+import { createCommands, webStorage } from "@inklu/keys";
+
+createCommands(definitions, { persist: webStorage("my-app.keys") });
 ```
 
-Only user overrides are stored — never defaults. `keymap.export()` / `keymap.import(json)` move them between devices. The stored data carries a `version`, and a release that doesn't recognise a version ignores it instead of misreading it; the user's next change then replaces it. Data from releases before the version field still loads.
+`webStorage(key, storage?)` keeps the user's overrides in `localStorage`. It is an import, so a registry created without it carries no storage code. Pass a second argument to keep them elsewhere: a function returning the storage, as in `webStorage("my-app.keys", () => sessionStorage)`. Any object with `getItem`, `setItem` and `removeItem` will do, and the function is only called in the browser.
+
+Only user overrides are stored — never defaults. To move them between devices yourself, `exportKeymap(commands)` returns them as JSON-safe data and `importKeymap(commands, data)` puts them back and saves them. The data carries a `version`, and data in a version this release does not know is ignored instead of misread.
+
+While mounted, the registry follows edits other tabs make to the same storage key, so a shortcut rebound in one tab applies in every open tab, and a stale tab can't overwrite it on its next save. Each mount reads what is stored, so a registry that was unmounted for a while has caught up by the time it listens again.
 
-While mounted, the registry follows edits other tabs make to the same storage key, so a shortcut rebound in one tab applies in every open tab, and a stale tab can't overwrite it on its next save.
+For a store that is not Web Storage, `persist` takes any object shaped like `KeymapStore`: `read()`, `write(overrides)` and `watch(onChange)`, all synchronous, with `Override` the type of one command's entry. For something asynchronous, such as a user's account, use `exportKeymap` and `importKeymap` instead.
 
 The registry is safe to create at module scope and render on the server:
 
 - Persisted overrides load on the first `mount()`, not at creation, so the server render and the client's first render match. Subscribers (and every hook) are notified when they arrive. Calling `keymap.set/add/reset` before mount loads them first, so an early edit never overwrites stored ones.
-- Before mount, shortcuts render in the non-Apple form (`Ctrl+K`); after mount they switch to the detected platform (`⌘ K`). Pass `platform` to pin it.
+- Before mount, shortcuts render in the non-Apple form (`Ctrl+K`); after mount they switch to the detected platform (`⌘K`), and `{ mac, other }` keys to its side. Pass `platform` to pin it.
 - Nothing listens for keys until `mount()` (or `useMountCommands`).
 
 ## 7. Inputs and events
 
-`ignoreInputs` on a command decides whether it fires while focus is in a text input, textarea, select or contenteditable. When omitted, chords holding `Control` or `Meta` (so any `Mod+…`) and bare `Escape` still fire there; bare keys, `Shift`/`Alt` chords and sequences starting with one are ignored, so typing is never hijacked. Keydowns that are part of an IME composition never trigger commands.
+`ignoreInputs` on a command decides whether it fires while focus is in a text input, textarea, select or contenteditable, or in a custom widget with a text-entry role (`textbox`, `searchbox`, `combobox`, `spinbutton`, `slider`). When omitted, chords holding `Control` or `Meta` (so any `Mod+…`) and bare `Escape` still fire there; bare keys, `Shift`/`Alt` chords and sequences starting with one are ignored, so typing is never hijacked. Editing is not hijacked either. Select all, copy, cut, paste, undo and redo (`Mod+A`, `C`, `X`, `V`, `Z`, `Shift+Z`, `Shift+V`, and `Mod+Y` off the Mac) are ignored in a field too, and so is `Mod` with `Backspace`, `Delete`, an arrow, `Home` or `End`, which move and delete by word or line. An app's own undo, select-all or delete-item leaves the field's alone. Set `ignoreInputs: false` on a command that should take one of them anyway. Keydowns that are part of an IME composition never trigger commands.
 
-A command calls `preventDefault()` only when it actually runs, or when the key is a step on the way through one of its sequences; one that is unhandled, out of scope or outranked leaves the event alone. Opt out per command with `preventDefault: false`. Propagation is never stopped. A handler may be async: nothing awaits it, but a rejection reaches `onError`. Holding a chord down runs its command again on each auto-repeat.
+A command calls `preventDefault()` only when it actually runs, or when the key is a step on the way through one of its sequences; one that is unhandled, out of scope or outranked leaves the event alone. Opt out per command with `preventDefault: false`. Propagation is never stopped. A handler may be async: nothing awaits it, but a rejection reaches `onError`. Holding a chord down runs its command again on each auto-repeat, which suits stepping and undo; give a toggle, or anything that should happen once per press, `repeat: false`. It still claims its key for as long as the key is held.
 
 `commands.whyNotRun(id)` explains a command that would not run: `"unhandled"` (nothing has attached a handler), `"out-of-scope"` (its scope is not open), `"unknown"`, or `null` when it would run.
 
@@ -261,20 +312,84 @@ const stop = observe(commands); // or observe(commands, { root: element })
 
 Clicking an element with `data-command` runs that command (`source: "dom"`), unless the element or an ancestor has `aria-disabled="true"` or another handler already called `preventDefault()`. Elements with `data-command-keys` get the shortcut as text, and `data-command` elements get `aria-keyshortcuts`; both stay current across rebinds and DOM changes.
 
+## 11. Recipes
+
+Patterns the pieces above already cover, so none of them needs an API of its own.
+
+### Act on the selection, else on the highlighted item
+
+Which item a shortcut applies to is your state. Compute the target once, and let it switch the handler on and off:
+
+```tsx
+const targets = selection.size > 0 ? [...selection] : highlighted ? [highlighted] : [];
+
+useCommandHandler(commands, "issue.setStatus", () => openStatusPicker(targets), targets.length > 0);
+useCommandHandler(commands, "issue.selectAll", () => setSelection(new Set(visibleIds)));
+```
+
+With nothing targeted the command has no handler, so its key falls through, `reachable` is false for its button, and a palette that lists what `canRun` leaves it out: the palette follows the selection without being told. `issue.selectAll` can be `Mod+A`: inside a text field that stays the field's own select-all.
+
+### Hold a key to peek
+
+`repeat: false` runs a command once per press. Letting go is a `keyup` away:
+
+```tsx
+// "issue.peek": { title: "Peek", keys: "Space", repeat: false }
+const [peeking, setPeeking] = useState(false);
+useCommandHandler(commands, "issue.peek", () => setPeeking(true), highlighted !== null);
+
+useEffect(() => {
+	if (!peeking) return;
+	const stop = () => setPeeking(false);
+	window.addEventListener("keyup", stop);
+	window.addEventListener("blur", stop);
+	return () => {
+		window.removeEventListener("keyup", stop);
+		window.removeEventListener("blur", stop);
+	};
+}, [peeking]);
+```
+
+Bind a hold to a bare key. While Command is down, macOS sends no `keyup` for the other keys, so a held `Mod+…` chord cannot tell when it was let go.
+
+### A shortcut sheet on `?` and `Mod+/`
+
+```ts
+"help.shortcuts": { title: "Keyboard shortcuts", keys: ["?", "Mod+/"], scope: "*" },
+```
+
+Build the sheet from `useCommands(commands)`, grouped by `group`, and search it with `matchCommands`, which also matches the displayed shortcut. When a user turns single-key shortcuts off, `?` goes and `Mod+/` stays, so the sheet that explains the setting is still reachable.
+
+### A way out of a text field
+
+Bare keys are ignored while the user types, so give them a key that leaves the field. `Escape` is the one bare key that fires inside an input:
+
+```tsx
+// "field.leave": { title: "Leave field", keys: "Escape", hidden: true }
+const [editing, setEditing] = useState(false);
+useCommandHandler(commands, "field.leave", () => rowRef.current?.focus(), editing);
+
+<input onFocus={() => setEditing(true)} onBlur={() => setEditing(false)} />;
+```
+
+Move focus to the item the field belongs to, not to nothing, so the next key has a target.
+
 ## API Summary
 
 - `createCommands(definitions, options)` - creates the registry
-  - `options`: `{ bindings, platform, target, persist, display, singleKeyShortcuts, onRun, onError }`
+  - `options`: `{ bindings, platform, target, persist, display, singleKeyShortcuts, onRun, onError }`; `platform` is `"mac"` or `"other"`
   - `commands.run(id)`, `canRun(id)`, `whyNotRun(id)`, `handle(id, run)`
   - `commands.get(id)`, `list()`, `subscribe(listener)`: snapshots with `display`, `tokens`, `aria`, `spoken`, `reachable`, `overridden`
   - `commands.pushScope(name, { exclusive })`, `capture(onKey)`, `conflicts(binding, options)`, `mount()`, `destroy()`
   - `commands.serverList()`: the list as the server rendered it, for a framework's hydration snapshot
-  - `commands.keymap`: `get`, `set`, `add`, `reset`, `export`, `import`
+  - `commands.keymap`: `get`, `set`, `add`, `reset`
   - `commands.setSingleKeyShortcuts(enabled)`, `commands.singleKeyShortcuts`
+- `webStorage(key, storage?)` - the `persist` option: Web Storage, followed across tabs
+- `exportKeymap(commands)`, `importKeymap(commands, data)` - user overrides as JSON-safe data
 - `createRebinder(commands, id, options)` - framework-agnostic shortcut recording
 - `observe(commands, { root })` from `@inklu/keys/attributes` - declarative DOM wiring
 - `matchCommands(list, query)` - palette filtering over `title`, `description`, `group`, `keywords`, id and displayed shortcut
-- `formatBinding`, `bindingTokens`, `ariaKeyShortcuts`, `spokenBinding`, `validateBinding`, `isSingleKeyBinding`, `seq`
+- `formatBinding`, `bindingTokens`, `ariaKeyShortcuts`, `spokenBinding`, `isSingleKeyBinding`, `seq`
 - React (`@inklu/keys/react`):
   - `useMountCommands(commands)` - starts listening
   - `useCommands(commands)`, `useCommand(commands, id)` - live command snapshots
@@ -283,13 +398,15 @@ Clicking an element with `data-command` runs that command (`source: "dom"`), unl
   - `useCommandHandler(commands, id, run, enabled)` - what a command does while a component is mounted
   - `useRebind(commands, id, options)` - records user shortcuts
   - `usePendingSequences(commands)` - half-typed sequences
-  - `useHeldKeys()`, `useHeldKeyCodes()`, `useKeyHold(key)` - live key state
+  - `useHeldKeys()` - the keys held down right now, by name
 
 Inside a handler, the context's `commands` is typed with the registry's own ids, so `commands.run("typo")` is a compile error.
 
 ## Accessibility
 
-Every command carries an `aria` string for the `aria-keyshortcuts` attribute. It lists chords only: the attribute separates alternatives with spaces, so it cannot express a sequence. Every command also carries `spoken` — `"Control+K"`, or `"G then I"` for a sequence — for visually hidden text or `aria-description`, which is how a sequence gets announced:
+Shortcuts are written the way each platform writes them: `⇧⌘S` on a Mac, symbols run together in Apple's order, and `Ctrl+Shift+S` elsewhere. `tokens` holds the same keys one at a time, for a `<kbd>` each.
+
+Every command carries an `aria` string for the `aria-keyshortcuts` attribute. It lists chords only: the attribute separates alternatives with spaces, so it cannot express a sequence. Every command also carries `spoken` — `"Command K"` on a Mac and `"Control K"` elsewhere, or `"G then I"` for a sequence — for visually hidden text or `aria-description`, which is how a sequence gets announced:
 
 ```tsx
 const { aria, spoken } = useShortcut(commands, "nav.inbox");

package/dist/attributes.d.mts

@@ -1,4 +1,4 @@
-import { l as Commands } from "./types-QEXldPnL.mjs";
+import { l as Commands } from "./types-D-hUKGoN.mjs";
 //#region src/attributes.d.ts
 export interface ObserveOptions {
   /** Root document or element to delegate from. Defaults to `document`. */

package/dist/attributes.mjs

@@ -52,28 +52,25 @@ function observe(registry, options = {}) {
 		lastPainted = next;
 		paintWithin(root);
 	});
-	let observer;
-	if ("MutationObserver" in globalThis) {
-		observer = new MutationObserver((mutations) => {
-			for (const mutation of mutations) {
-				if (mutation.type === "attributes" && mutation.target instanceof Element) {
-					paintElement(mutation.target);
-					continue;
-				}
-				for (const node of mutation.addedNodes) if (node instanceof Element) paintWithin(node);
+	const observer = new MutationObserver((mutations) => {
+		for (const mutation of mutations) {
+			if (mutation.type === "attributes" && mutation.target instanceof Element) {
+				paintElement(mutation.target);
+				continue;
 			}
-		});
-		observer.observe(root instanceof Document ? root.documentElement : root, {
-			childList: true,
-			subtree: true,
-			attributes: true,
-			attributeFilter: [COMMAND_ATTRIBUTE, KEYS_ATTRIBUTE]
-		});
-	}
+			for (const node of mutation.addedNodes) if (node instanceof Element) paintWithin(node);
+		}
+	});
+	observer.observe(root instanceof Document ? root.documentElement : root, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: [COMMAND_ATTRIBUTE, KEYS_ATTRIBUTE]
+	});
 	return () => {
 		root.removeEventListener("click", onClick);
 		unsubscribe();
-		observer?.disconnect();
+		observer.disconnect();
 	};
 }
 //#endregion

package/dist/{index-3d9f54ln.d.mts → index-DRXMJmbc.d.mts}

@@ -1,4 +1,4 @@
-import { C as SequenceBinding, D as Chord, a as CommandDefinition, d as Conflict, k as Platform, l as Commands, m as DisplayOptions, r as Command, t as Binding, u as CommandsOptions } from "./types-QEXldPnL.mjs";
+import { C as SequenceBinding, D as Chord, T as SerializedKeymap, a as CommandDefinition, d as Conflict, g as KeymapStore, k as Platform, l as Commands, m as Json, p as DisplayOptions, r as Command, t as Binding, u as CommandsOptions } from "./types-D-hUKGoN.mjs";
 //#region src/bindings.d.ts
 /**
  * Creates a sequence binding from ordered chords.
@@ -10,35 +10,54 @@ import { C as SequenceBinding, D as Chord, a as CommandDefinition, d as Conflict
  */
 declare function seq(...steps: Array<Chord>): SequenceBinding;
 /**
- * Whether every step of a binding is a single printable character with no
- * Control, Alt or Meta — the "character key shortcuts" WCAG 2.1.4 lets users
- * turn off, since speech input and stray keypresses trigger them by accident.
+ * Whether every step is a printable character with no Control, Alt or Meta:
+ * the "character key shortcuts" WCAG 2.1.4 lets users turn off.
  */
 declare function isSingleKeyBinding(binding: Binding): boolean;
-/** Validation result for a hotkey binding. */
-interface BindingValidation {
-  readonly valid: boolean;
-  readonly errors: ReadonlyArray<string>;
-  readonly warnings: ReadonlyArray<string>;
-}
-/** Validates a binding's syntax without logging warnings or errors. */
-declare function validateBinding(binding: Binding): BindingValidation;
 //#endregion
 //#region src/display.d.ts
-/** Formats a binding for display on the target platform (e.g. `⌘ K` or `Ctrl+K`). */
+/**
+ * Formats a binding the way its platform writes shortcuts: `⇧⌘S` on a Mac,
+ * `Ctrl+Shift+S` elsewhere. The steps of a sequence are set apart by a space.
+ */
 declare function formatBinding(binding: Binding, options?: DisplayOptions): string;
-/** Splits a binding into display tokens for rendering `<kbd>` elements. */
+/**
+ * Splits a binding into display tokens for rendering `<kbd>` elements: one
+ * per key of a chord, one per step of a sequence.
+ */
 declare function bindingTokens(binding: Binding, options?: DisplayOptions): Array<string>;
 /**
- * Phrases a binding for a screen reader: `"Control+K"` for a chord,
- * `"G then I"` for a sequence. `aria-keyshortcuts` cannot express a sequence
- * (a space there means "or"), so this is how a sequence gets announced — put it
- * in visually hidden text or `aria-description`.
+ * Phrases a binding for a screen reader: `"Command K"` for a chord,
+ * `"G then I"` for a sequence, which `aria-keyshortcuts` cannot express.
  */
 declare function spokenBinding(binding: Binding, platform?: Platform): string;
-/** Generates an `aria-keyshortcuts` attribute string for a binding. */
+/**
+ * The `aria-keyshortcuts` value for a chord, as in `"Meta+K"`. Empty for a
+ * sequence and for a chord that cannot be read.
+ */
 declare function ariaKeyShortcuts(binding: Binding, platform?: Platform): string;
 //#endregion
+//#region src/persist.d.ts
+type WebStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+/**
+ * Keeps user overrides in Web Storage under `key`, and follows edits made in
+ * other tabs. `storage` is only called in the browser; return
+ * `sessionStorage` or an object of your own to keep them somewhere else.
+ *
+ * @example
+ * ```ts
+ * createCommands(definitions, { persist: webStorage("my-app.keys") });
+ * ```
+ */
+declare function webStorage(key?: string, storage?: () => WebStorage | null): KeymapStore;
+/** A registry's user overrides as JSON-safe data, for your own storage or another device. */
+declare function exportKeymap<Id extends string>(commands: Pick<Commands<Id>, "keymap">): SerializedKeymap;
+/**
+ * Replaces a registry's user overrides with exported data, and saves them.
+ * Data in another format changes nothing.
+ */
+declare function importKeymap<Id extends string>(commands: Pick<Commands<Id>, "keymap">, data: Json): void;
+//#endregion
 //#region src/rebind.d.ts
 /** Hotkey capture mode: single `"chord"` or multi-step `"sequence"`. */
 type RebindMode = "chord" | "sequence";
@@ -50,7 +69,7 @@ interface RebindState<Id extends string = string> {
   readonly binding: Binding | null;
   /** Captured steps in the current sequence session. */
   readonly steps: ReadonlyArray<Chord>;
-  /** Conflicting commands for the captured binding. */
+  /** What stands in the captured binding's way: other commands using it, or the platform reserving it. */
   readonly conflicts: ReadonlyArray<Conflict<Id>>;
 }
 /** Options for creating a rebinder. */
@@ -61,7 +80,10 @@ interface RebindOptions<Id extends string = string> {
   apply?: boolean;
   /** Whether to append rather than replace existing bindings. Defaults to `false`. */
   add?: boolean;
-  /** Prevent applying bindings that conflict with other commands. Defaults to `false`. */
+  /**
+   * Prevent applying bindings that conflict with other commands. Defaults to
+   * `false`. A binding the browser or operating system reserves is never applied.
+   */
   rejectConflicts?: boolean;
   /** Ignore key events from inputs while recording. Defaults to `true`. */
   ignoreInputs?: boolean;
@@ -92,17 +114,14 @@ interface Rebinder<Id extends string = string> {
   destroy: () => void;
 }
 /**
- * Creates a rebinder instance for capturing and remapping a command's keys.
- * While it records it holds the whole keyboard, so no command runs on the
- * keys being pressed. Escape cancels, Backspace removes the shortcut (or the
- * last step of a sequence), and Enter finishes a sequence.
+ * Creates a rebinder for recording a command's keys. While it records, no
+ * command runs. Escape cancels, Backspace removes the shortcut (or the last
+ * step of a sequence), and Enter finishes a sequence.
  *
  * @example
  * ```ts
  * const rebinder = createRebinder(commands, "palette.open", {
- *   onRecord: (binding, conflicts) => {
- *     if (conflicts.length) console.warn("Conflict with", conflicts[0].id);
- *   },
+ *   onRecord: (binding, conflicts) => showConflicts(conflicts),
  * });
  * rebinder.start();
  * ```
@@ -125,7 +144,7 @@ declare function createRebinder<Id extends string>(registry: Commands<Id>, id: I
  * });
  * ```
  */
-declare function createCommands<Id extends string>(definitions: { [K in Id]: CommandDefinition<Id>; }, options?: CommandsOptions<NoInfer<Id>>): Commands<Id>;
+declare function createCommands<Id extends string>(definitions: { [K in Id]: CommandDefinition<NoInfer<Id>>; }, options?: CommandsOptions<NoInfer<Id>>): Commands<Id>;
 /**
  * Extracts command ID union from a Commands registry type.
  *
@@ -139,12 +158,10 @@ type CommandId<C> = C extends Commands<infer Id> ? Id : never;
 //#endregion
 //#region src/search.d.ts
 /**
- * Filters commands for a search query, as a command palette does, leaving
- * out `hidden` ones. Every word of the query must appear somewhere in the
- * command — title, description, group, keywords, id or displayed shortcut —
- * in any order. Title matches come first: titles starting with the query,
- * then titles containing every word, then the rest; each tier keeps the
- * list's own order. An empty query returns every visible command.
+ * Filters commands for a search query, leaving out `hidden` ones. Every word
+ * must appear in the title, description, group, keywords, id or displayed
+ * shortcut. Titles starting with the query come first, then titles containing
+ * every word, then the rest. An empty query returns every visible command.
  *
  * @example
  * ```ts
@@ -153,4 +170,4 @@ type CommandId<C> = C extends Commands<infer Id> ? Id : never;
  */
 declare function matchCommands<Id extends string>(commands: ReadonlyArray<Command<Id>>, query: string): Array<Command<Id>>;
 //#endregion
-export { RebindOptions as a, createRebinder as c, formatBinding as d, spokenBinding as f, validateBinding as g, seq as h, RebindMode as i, ariaKeyShortcuts as l, isSingleKeyBinding as m, CommandId as n, RebindState as o, BindingValidation as p, createCommands as r, Rebinder as s, matchCommands as t, bindingTokens as u };
+export { seq as _, RebindOptions as a, createRebinder as c, webStorage as d, ariaKeyShortcuts as f, isSingleKeyBinding as g, spokenBinding as h, RebindMode as i, exportKeymap as l, formatBinding as m, CommandId as n, RebindState as o, bindingTokens as p, createCommands as r, Rebinder as s, matchCommands as t, importKeymap as u };

package/dist/index.d.mts

@@ -1,3 +1,3 @@
-import { C as SequenceBinding, D as Chord, E as SerializedOverride, O as Key, S as ScopeOptions, T as SerializedKeymap, _ as KeymapPersistence, a as CommandDefinition, b as RunBlockReason, c as CommandSource, d as Conflict, f as ConflictKind, g as KeyCapture, h as Json, i as CommandContext, k as Platform, l as Commands, m as DisplayOptions, n as BindingInput, o as CommandHandler, p as ConflictOptions, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as KeymapStorage, w as SerializedBinding, x as RunOptions, y as PendingSequence } from "./types-QEXldPnL.mjs";
-import { a as RebindOptions, c as createRebinder, d as formatBinding, f as spokenBinding, g as validateBinding, h as seq, i as RebindMode, l as ariaKeyShortcuts, m as isSingleKeyBinding, n as CommandId, o as RebindState, p as BindingValidation, r as createCommands, s as Rebinder, t as matchCommands, u as bindingTokens } from "./index-3d9f54ln.mjs";
-export { type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Json, type Key, type KeyCapture, type KeymapPersistence, type KeymapStorage, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, seq, spokenBinding, validateBinding };
+import { C as SequenceBinding, D as Chord, E as SerializedOverride, O as Key, S as ScopeOptions, T as SerializedKeymap, _ as Override, a as CommandDefinition, b as RunBlockReason, c as CommandSource, d as Conflict, f as ConflictOptions, g as KeymapStore, h as KeyCapture, i as CommandContext, k as Platform, l as Commands, m as Json, n as BindingInput, o as CommandHandler, p as DisplayOptions, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as PendingSequence, w as SerializedBinding, x as RunOptions, y as PlatformBindings } from "./types-D-hUKGoN.mjs";
+import { _ as seq, a as RebindOptions, c as createRebinder, d as webStorage, f as ariaKeyShortcuts, g as isSingleKeyBinding, h as spokenBinding, i as RebindMode, l as exportKeymap, m as formatBinding, n as CommandId, o as RebindState, p as bindingTokens, r as createCommands, s as Rebinder, t as matchCommands, u as importKeymap } from "./index-DRXMJmbc.mjs";
+export { type Binding, type BindingInput, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictOptions, type DisplayOptions, type Json, type Key, type KeyCapture, type KeymapStore, type Override, type PendingSequence, type Platform, type PlatformBindings, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, matchCommands, seq, spokenBinding, webStorage };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as bindingTokens, c as isSingleKeyBinding, i as ariaKeyShortcuts, l as seq, n as createCommands, o as formatBinding, r as createRebinder, s as spokenBinding, t as matchCommands, u as validateBinding } from "./src-B76YvObL.mjs";
-export { ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, seq, spokenBinding, validateBinding };
+import { a as importKeymap, c as bindingTokens, d as isSingleKeyBinding, f as seq, i as exportKeymap, l as formatBinding, n as createCommands, o as webStorage, r as createRebinder, s as ariaKeyShortcuts, t as matchCommands, u as spokenBinding } from "./src-TaZw4V61.mjs";
+export { ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, matchCommands, seq, spokenBinding, webStorage };

package/dist/react.d.mts

@@ -1,5 +1,5 @@
-import { C as SequenceBinding, D as Chord, E as SerializedOverride, O as Key, S as ScopeOptions, T as SerializedKeymap, _ as KeymapPersistence, a as CommandDefinition, b as RunBlockReason, c as CommandSource, d as Conflict, f as ConflictKind, g as KeyCapture, h as Json, i as CommandContext, k as Platform, l as Commands, m as DisplayOptions, n as BindingInput, o as CommandHandler, p as ConflictOptions, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as KeymapStorage, w as SerializedBinding, x as RunOptions, y as PendingSequence } from "./types-QEXldPnL.mjs";
-import { a as RebindOptions, c as createRebinder, d as formatBinding, f as spokenBinding, g as validateBinding, h as seq, i as RebindMode, l as ariaKeyShortcuts, m as isSingleKeyBinding, n as CommandId, o as RebindState, p as BindingValidation, r as createCommands, s as Rebinder, t as matchCommands, u as bindingTokens } from "./index-3d9f54ln.mjs";
+import { C as SequenceBinding, D as Chord, E as SerializedOverride, O as Key, S as ScopeOptions, T as SerializedKeymap, _ as Override, a as CommandDefinition, b as RunBlockReason, c as CommandSource, d as Conflict, f as ConflictOptions, g as KeymapStore, h as KeyCapture, i as CommandContext, k as Platform, l as Commands, m as Json, n as BindingInput, o as CommandHandler, p as DisplayOptions, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as PendingSequence, w as SerializedBinding, x as RunOptions, y as PlatformBindings } from "./types-D-hUKGoN.mjs";
+import { _ as seq, a as RebindOptions, c as createRebinder, d as webStorage, f as ariaKeyShortcuts, g as isSingleKeyBinding, h as spokenBinding, i as RebindMode, l as exportKeymap, m as formatBinding, n as CommandId, o as RebindState, p as bindingTokens, r as createCommands, s as Rebinder, t as matchCommands, u as importKeymap } from "./index-DRXMJmbc.mjs";
 //#region src/react/hooks.d.ts
 /**
  * Mounts a commands registry for the lifecycle of the component.
@@ -13,9 +13,13 @@ import { a as RebindOptions, c as createRebinder, d as formatBinding, f as spoke
  * ```
  */
 export declare function useMountCommands<Id extends string>(registry: Commands<Id>): void;
-/** Returns all registered commands, re-rendering when the registry changes. */
+/**
+ * Returns all registered commands, re-rendering when the registry changes.
+ * Hydrates against `serverList()`, so a subtree that hydrates late still
+ * matches the server's HTML.
+ */
 export declare function useCommands<Id extends string>(registry: Commands<Id>): ReadonlyArray<Command<Id>>;
-/** Returns a specific command snapshot by ID. */
+/** Returns one command's snapshot, re-rendering only when that command changes. */
 export declare function useCommand<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>): Command<Id> | undefined;
 /**
  * Returns display and accessibility shortcuts for a command's primary
@@ -30,9 +34,8 @@ export declare function useShortcut<Id extends string>(registry: Commands<Id>, i
 };
 /**
  * Activates a scope for the lifecycle of the component. Scopes rank in the
- * order they are pushed, which here is the order React runs effects in: a
- * surface opened later ranks higher, but of a parent and a child opening in
- * the same render the child is pushed first.
+ * order React runs effects in: of a parent and a child opening in the same
+ * render, the child is pushed first.
  *
  * @example
  * ```tsx
@@ -41,12 +44,10 @@ export declare function useShortcut<Id extends string>(registry: Commands<Id>, i
  */
 export declare function useScope<Id extends string>(registry: Commands<Id>, name: string, active?: boolean, options?: ScopeOptions): void;
 /**
- * Attaches what a command does for the lifecycle of the component, so the
- * behaviour lives where its state does. The latest `run` is always the one
- * called. While `enabled` is `false` the component steps back: the command
- * falls to the handler attached before it, or cannot run if there is none.
- * The handler attached last wins, and React attaches a parent's after its
- * children's when they mount together.
+ * Attaches what a command does for the lifecycle of the component. The latest
+ * `run` is always the one called, and the handler attached last wins. While
+ * `enabled` is `false` the command falls to the handler attached before it,
+ * or cannot run if there is none.
  *
  * @example
  * ```tsx
@@ -72,27 +73,9 @@ interface UseRebindResult<Id extends string = string> extends RebindState<Id> {
 }
 /** Hook for recording and configuring a command's keybindings. */
 export declare function useRebind<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>, options?: RebindOptions<Id>): UseRebindResult<Id>;
-/** Returns an array of keys currently held down. */
+/** Returns the keys held down right now, by the name `KeyboardEvent.key` gives each. */
 export declare function useHeldKeys(): ReadonlyArray<string>;
-/**
- * Checks whether a specific key is currently held down.
- *
- * @example
- * ```tsx
- * const shift = useKeyHold("Shift");
- * ```
- */
-export declare function useKeyHold(key: string): boolean;
-/** Returns a map of held key identifiers to physical event codes. */
-export declare function useHeldKeyCodes(): Readonly<Record<string, string>>;
-/**
- * Returns currently active partially-typed sequences.
- *
- * @example
- * ```tsx
- * const pending = usePendingSequences(commands);
- * ```
- */
+/** Returns the half-typed sequences, for a hint such as "G …". */
 export declare function usePendingSequences<Id extends string>(registry: Commands<Id>): ReadonlyArray<PendingSequence<Id>>;
 //#endregion
-export { type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Json, type Key, type KeyCapture, type KeymapPersistence, type KeymapStorage, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, seq, spokenBinding, validateBinding };
+export { type Binding, type BindingInput, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandler, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictOptions, type DisplayOptions, type Json, type Key, type KeyCapture, type KeymapStore, type Override, type PendingSequence, type Platform, type PlatformBindings, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, matchCommands, seq, spokenBinding, webStorage };