@inklu/keys 2.1.0 → 3.0.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 and recording a shortcut 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
@@ -20,7 +20,7 @@ pnpm add @inklu/keys
 
 Declare every command in one module. Ids come from the object keys, so `commands.run("doc.save")` autocompletes and a typo is a type error.
 
-A chord is written modifiers first, then one key: `"Mod+Shift+S"`. The modifiers are `Mod`, `Control`, `Alt`, `Shift` and `Meta`, in that order, and `Mod` is Command on macOS and Control elsewhere. The key is the character or the name `KeyboardEvent.key` gives it (`"K"`, `"?"`, `"Escape"`, `"ArrowUp"`), or a physical key in brackets (`"[KeyK]"`) that stays put whatever the layout. Chords are typed, so a misspelling is a compile error. An array of chords means alternatives; a sequence is `seq("G", "I")`.
+A chord is written modifiers first, then one key: `"Mod+Shift+S"`. The modifiers are `Mod`, `Control`, `Alt`, `Shift` and `Meta`, in that order, and `Mod` is Command on macOS and Control elsewhere. The key is the character or the name `KeyboardEvent.key` gives it (`"K"`, `"?"`, `"Escape"`, `"ArrowUp"`). Chords are typed, so a misspelling is a compile error. An array of chords means alternatives; a sequence is `seq("G", "I")`, and its steps must come within a second of each other.
 
 ```ts
 // commands.ts
@@ -38,40 +38,40 @@ export const commands = createCommands({
 });
 ```
 
+A chord names what the key types, so `Mod+S` matches the key that types `s` on the user's layout. Where a layout types no Latin letter on a letter key (Cyrillic, Greek), or on the digit row, the key at that position on a US layout matches too.
+
+### Keys that differ by platform
+
+`Mod` covers most shortcuts. 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: keys the browser or operating system keeps (`Mod+N`, `Mod+T`, `Mod+W` and their `Shift` forms, `Control+Tab`, `Mod+Q` on a Mac, `Alt+F4` and anything holding `Meta` elsewhere), which the page mostly never receives, so `doc.new` above is not `Mod+N`; and `Control+Alt` with a character key, which is AltGr on many Windows and Linux layouts and the VoiceOver modifier on a Mac, so `Mod+Alt+N` is fine on a Mac and not elsewhere. Browser features a page _can_ take over (`Mod+F`, `Mod+P`, `Mod+L`, `Mod+R`) are left to your judgement.
+
+Commands generated from data are typed when the generated object's keys are: give an `Object.fromEntries` result its key type (`as Record<\`go.${Slug}\`, CommandDefinition>`) before spreading it in, or name every id yourself with `createCommands<AppCommandId>({ … })`.
+
 ## 2. React Setup
 
 Pass the registry explicitly to all hooks. There is no Context provider.
 
 ```tsx
-import { useCommandHandler, useMountCommands, useShortcut } from "@inklu/keys/react";
+import { useMountCommands, useShortcut } from "@inklu/keys/react";
 import { commands } from "./commands";
 
-function App() {
-	// Starts listening in an effect
-	useMountCommands(commands);
-	return <ShortcutButton />;
-}
-
-function Palette() {
-	const [open, setOpen] = useState(false);
-	// What the command does, attached where the state lives.
-	useCommandHandler(commands, "palette.open", () => setOpen(true));
-	return open ? <dialog open>…</dialog> : null;
-}
+useMountCommands(commands); // once, near the root: starts listening in an effect
 
 function ShortcutButton() {
-	// Live state for the primary binding: `tokens` is one string per key
-	const shortcut = useShortcut(commands, "palette.open");
-
+	// Live state for the primary binding: `display` to read, `tokens` one string per key
+	const { display, aria } = useShortcut(commands, "palette.open");
 	return (
-		<button
-			onClick={() => commands.run("palette.open")}
-			aria-keyshortcuts={shortcut.aria || undefined}
-		>
-			Open Palette
-			{shortcut.tokens.map((token, i) => (
-				<kbd key={i}>{token}</kbd>
-			))}
+		<button onClick={() => commands.run("palette.open")} aria-keyshortcuts={aria || undefined}>
+			Open Palette <kbd>{display}</kbd>
 		</button>
 	);
 }
@@ -86,9 +86,9 @@ A command runs when its scope is open and it has a handler. A definition's own `
 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.
+- A command with no handler cannot run and leaves its key alone, so unmounting a feature switches its shortcuts off with it. Outside React, `commands.handle(id, run)` does the same and returns a function that detaches.
 - 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.
+- Keep a handler with its state in code that is already loaded: inside a lazily loaded component it 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.
 
@@ -97,14 +97,8 @@ Switch a command off by its handler (`enabled`, or detaching) rather than with a
 Use scopes to isolate commands when modals or dialogs are open.
 
 ```tsx
-import { useScope } from "@inklu/keys/react";
-
-function Dialog({ isOpen }) {
-	// When exclusive is true, the keys of commands outside this scope are silenced
-	useScope(commands, "dialog", isOpen, { exclusive: true });
-
-	return isOpen ? <div className="dialog">...</div> : null;
-}
+// In the dialog: while open, the keys of commands outside this scope are silenced.
+useScope(commands, "dialog", isOpen, { exclusive: true });
 ```
 
 `exclusive` is a barrier: it silences every key beneath it. To claim only a few keys, drop it and give those commands a `scope` instead — see below.
@@ -116,11 +110,9 @@ A barrier claims the keyboard, not the command: `commands.run(id)` still works b
 Exactly one command runs per keypress. Among the commands that could take it, the winner is:
 
 1. A sequence being finished, over a chord on the same key.
-2. The command whose scope was opened most recently. Scopes track the surfaces on screen, so the dialog on top claims `Escape` before the panel beneath it, and any scoped command beats a global one. `"*"` counts as global here — it means "survives barriers", not "belongs to a region of the UI".
+2. The command whose scope was opened most recently. Scopes track the surfaces on screen, so the dialog on top claims `Escape` before the panel beneath it, and any scoped command beats a global one. `"*"` counts as global here — it means "survives barriers", not "belongs to a region of the UI". With `useScope`, "most recently" is the order React runs effects in: of a parent and a child that open in the same render, the child is pushed first.
 3. Failing that, the one defined later.
 
-Scopes rank in the order they were pushed. With `useScope` that is the order React runs effects in: a surface opened later ranks higher, but of a parent and a child that open in the same render, the child is pushed first. Open the inner surface after the outer one when their order matters.
-
 A command with no handler is never a candidate, so it 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 only be told apart by which has a handler, so that case warns in development.
 
 ## 4. Rebinding
@@ -129,125 +121,85 @@ 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", ["Mod+P", "Mod+K"]); // two keys for it
 commands.keymap.set("palette.open", null); // unbind
 commands.keymap.reset("palette.open"); // reset to default
 ```
 
-`set` replaces the command's keys outright; setting exactly the default forgets the override instead. `add` layers on top of the default rather than copying it, so if a later release of your app changes the default, the user gets the new one and keeps the keys they added.
-
-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(commands, {
-	bindings: {
-		"palette.open": "Mod+P", // replace the shipped default
-		"doc.publish": null, // ship it unbound
-	},
-});
-```
+`set` replaces the command's keys outright; setting exactly the default forgets the override instead.
 
-These are defaults, applied before persisted overrides load, so a user's own rebinding still wins.
+To rebind a command you did not define — one a package shipped — pass `bindings: { "palette.open": "Mod+P", "doc.publish": null }` when creating the registry (`null` ships it unbound). An unknown id is a compile error, and `reset` returns here rather than to the definition's `keys`. These are defaults, applied before persisted overrides load, so a user's own rebinding still wins.
 
-In React, use the `useRebind` hook for a capture flow:
+In React, `useRebind` is a capture flow; `createRebinder` is the same without React:
 
 ```tsx
-const rebind = useRebind(commands, "palette.open");
-
-<button onClick={rebind.start}>{rebind.recording ? "Press keys…" : rebind.display}</button>;
-```
-
-To build your own capture UI without React, use `createRebinder`:
-
-```ts
-import { createRebinder } from "@inklu/keys";
+const rebind = useRebind(commands, "palette.open"); // { sequence: true } records steps until Enter
+<button onClick={rebind.recording ? rebind.cancel : rebind.start}>
+	{rebind.recording ? "Press keys…" : rebind.display}
+</button>;
 
 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
-	onRecord: (binding, conflicts) => {},
+	onRecord: (binding, conflicts) => {}, // `binding` is null for Backspace, which unbinds
 });
 rebinder.subscribe(() => render(rebinder.state)); // { recording, binding, steps, conflicts }
 rebinder.start(); // Escape cancels, Backspace unbinds
 ```
 
-While recording, every command is silenced — including `"*"` ones — so the keys being recorded never run anything. The rebinder is built on `commands.capture(onKey)`, which hands every keypress to `onKey(event, chord)` until the function it returns is called; use it directly for a recorder of your own.
+While recording, every command is silenced — including `"*"` ones — so the keys being recorded never run anything. The rebinder applies whatever is recorded: keys the browser keeps are warned about in development, not refused. It is built on `commands.capture(onKey)`, which hands every keypress to `onKey(event, chord)` until the function it returns is called; use it directly for a recorder of your own.
 
 ## 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 the commands in overlapping scopes whose keys stand in the way of `binding`. Each result has the other command's `id`, its `binding` and `display`, and a `kind`:
 
 - `"exact"` — 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.
+A settings row shows them as `Also used by ${commands.get(conflict.id)?.title}`. In development, both are also reported with `console.warn` when the registry is created, for the defaults on both kinds of platform, along with keys the browser or operating system keeps. 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.
 
-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.
+Only user overrides are stored — never defaults. To move them between devices yourself, `exportKeymap(commands)` returns them as `{ version, overrides }` and `importKeymap(commands, data)` puts them back and saves them. Data in a version this release does not know is ignored instead of misread.
 
-The registry is safe to create at module scope and render on the server:
+For a store that is not Web Storage, `persist` takes any object shaped like `KeymapStore`: `read()` returns a `Map` of bindings by command id (or `null` when it cannot) and `write(overrides)` takes one, both synchronous. For something asynchronous, such as a user's account, use `exportKeymap` and `importKeymap` instead.
 
-- 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.
-- Nothing listens for keys until `mount()` (or `useMountCommands`).
+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, and `keymap.set/reset` before mount loads them first. 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.
+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`), no command fires except one on `Escape`, so typing and the field's own editing keys are never hijacked. A command that should work there too, such as save on `Mod+S`, sets `ignoreInputs: false`. 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 that runs claims its key with `preventDefault()`, as does a key that is a step on the way through one of its sequences; one that is unhandled, out of scope or outranked leaves the event alone. Propagation is never stopped. A held key runs its command once: auto-repeat is ignored. A handler may be async; nothing awaits it.
 
 `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.
 
-## 8. Sequence progress
-
-```tsx
-const pending = usePendingSequences(commands); // [{ id, matched, total, remaining }]
-// e.g. show "G → …" while the user is halfway through `G then I`
-```
-
-`commands.subscribePending()` / `commands.pending()` are the non-React equivalents. Progress is tracked only while something is subscribed, so `pending()` is empty otherwise.
-
-## 9. Command palette
+## 8. Command palette
 
-Definitions can carry what a palette needs to list and find them, and `matchCommands` does the filtering:
-
-```ts
-createCommands({
-	"doc.find": {
-		title: "Find in document",
-		description: "Search the open document",
-		group: "Document", // heading to list it under
-		keywords: ["search", "lookup"], // extra search terms
-		keys: "Mod+F",
-	},
-	"palette.close": { title: "Close palette", hidden: true, scope: "palette", keys: "Escape" },
-});
-```
+The registry lists every command with its `title`, its keys as `tokens` and whether it is `reachable`; the app filters and groups that list. What the registry does not hold, such as group headings or the ids to leave out, is a map of your own keyed by command id.
 
 ```tsx
-import { matchCommands } from "@inklu/keys";
-
-// List what can run right now: it has a handler and its scope is open.
-const runnable = useCommands(commands).filter((command) => commands.canRun(command.id));
-const results = matchCommands(runnable, query);
+const GROUPS: Partial<Record<CommandId<typeof commands>, string>> = { "doc.find": "Document" };
+const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+
+// What can run right now (it has a handler and its scope is open), and matches every word.
+const results = useCommands(commands).filter(
+	(command) =>
+		commands.whyNotRun(command.id) === null &&
+		words.every((word) => command.title.toLowerCase().includes(word)),
+);
 ```
 
-Every word of the query must match the title, description, group, keywords, id or displayed shortcut. Titles starting with the query come first, then titles containing it, then everything else, each in list order. `hidden` commands never match; they still run and still appear in `list()`.
+Give `palette.open` `ignoreInputs: false`, so `Mod+K` works from a text field and from the palette's own search box.
 
-## 10. Without React: data attributes
+## 9. Without React: data attributes
 
 ```ts
 import { observe } from "@inklu/keys/attributes";
@@ -261,50 +213,69 @@ 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.
 
+## 10. Recipes
+
+Patterns the pieces above already cover, so none of them needs an API of its own. Which item a shortcut acts on is your state: compute the target once and pass `targets.length > 0` as `enabled`, so with nothing targeted the key falls through, `reachable` is false for its button, and a palette that lists what can run leaves it out.
+
+### A shortcut sheet on `?` and `Mod+/`
+
+```ts
+"help.shortcuts": { title: "Keyboard shortcuts", keys: ["?", "Mod+/"], scope: "*" },
+```
+
+Build the sheet from `useCommands(commands)`, grouped and searched the way the palette is. 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
+
+Nothing fires while the user types, so give them a key that leaves the field. `Escape` is the one key that fires inside an input:
+
+```tsx
+// "field.leave": { title: "Leave field", keys: "Escape" }
+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 }`
-  - `commands.run(id)`, `canRun(id)`, `whyNotRun(id)`, `handle(id, run)`
-  - `commands.get(id)`, `list()`, `subscribe(listener)`: snapshots with `display`, `tokens`, `aria`, `spoken`, `reachable`, `overridden`
+  - `options`: `{ bindings, platform, persist, singleKeyShortcuts, onRun }`; `platform` is `"mac"` or `"other"`
+  - a definition: `{ title, keys, scope, ignoreInputs, run }`
+  - `commands.run(id)`, `whyNotRun(id)`, `handle(id, run)`
+  - `commands.get(id)`, `list()`, `subscribe(listener)`: snapshots with `display`, `tokens`, `aria`, `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`, `reset`
   - `commands.setSingleKeyShortcuts(enabled)`, `commands.singleKeyShortcuts`
+- `webStorage(key, storage?)` - the `persist` option: Web Storage
+- `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(binding, platform?)`, `bindingTokens(binding, platform?)`, `ariaKeyShortcuts(binding, platform?)`, `isSingleKeyBinding`, `seq`
 - React (`@inklu/keys/react`):
   - `useMountCommands(commands)` - starts listening
   - `useCommands(commands)`, `useCommand(commands, id)` - live command snapshots
-  - `useShortcut(commands, id)` - `{ display, tokens, aria, spoken }` for the primary binding
+  - `useShortcut(commands, id)` - `{ display, tokens, aria }` for the primary binding
   - `useScope(commands, name, active, { exclusive })` - opens a scope while a component needs it
   - `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
 
 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:
-
-```tsx
-const { aria, spoken } = useShortcut(commands, "nav.inbox");
-<button aria-keyshortcuts={aria || undefined} aria-description={spoken || undefined}>
-	Inbox
-</button>;
-```
+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.
 
-WCAG 2.1.4 (Character Key Shortcuts) requires that users can turn off shortcuts made of printable characters without a modifier — `?`, `G then I` — because speech input and stray keypresses trigger them. Expose a setting wired to:
+Every command carries an `aria` string for the `aria-keyshortcuts` attribute. It holds key names (`Meta+K`), which is what screen readers expect, not glyphs, and lists chords only: the attribute separates alternatives with spaces, so it cannot express a sequence. For a sequence, `aria` is empty; write its hint in visible text next to the control ("G then I"), which is read as words:
 
-```ts
-commands.setSingleKeyShortcuts(false); // or createCommands(defs, { singleKeyShortcuts: false })
+```tsx
+const { aria, display } = useShortcut(commands, "nav.inbox");
+<button aria-keyshortcuts={aria || undefined}>Inbox {display}</button>;
 ```
 
-While off, those bindings neither fire nor appear in `display`, `tokens`, `aria` or `spoken`; chords with `Control`, `Alt` or `Meta` and keys like `Escape` or `F1` keep working. Users can also remap any shortcut with `useRebind`.
+WCAG 2.1.4 (Character Key Shortcuts) requires that users can turn off shortcuts made of printable characters without a modifier — `?`, `G then I` — because speech input and stray keypresses trigger them. Expose a setting wired to `commands.setSingleKeyShortcuts(false)` (or `createCommands(defs, { singleKeyShortcuts: false })`). While off, those bindings neither fire nor appear in `display`, `tokens` or `aria`; chords with `Control`, `Alt` or `Meta` and keys like `Escape` or `F1` keep working. Users can also remap any shortcut with `useRebind`.
 
 ## Acknowledgements
 

package/dist/attributes.d.mts

@@ -1,4 +1,4 @@
-import { l as Commands } from "./types-QEXldPnL.mjs";
+import { l as Commands } from "./types-BxMI3b4a.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-BnB38jCF.d.mts

@@ -0,0 +1,139 @@
+import { C as Chord, S as SerializedKeymap, T as Platform, a as CommandDefinition, b as SequenceBinding, d as Conflict, h as KeymapStore, l as Commands, p as Json, t as Binding, u as CommandsOptions } from "./types-BxMI3b4a.mjs";
+//#region src/bindings.d.ts
+/**
+ * Creates a sequence binding from ordered chords.
+ *
+ * @example
+ * ```ts
+ * keys: seq("G", "I")
+ * ```
+ */
+declare function seq(...steps: Array<Chord>): SequenceBinding;
+/**
+ * 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;
+//#endregion
+//#region src/display.d.ts
+/**
+ * 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, platform?: Platform): string;
+/**
+ * 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, platform?: Platform): Array<string>;
+/**
+ * The `aria-keyshortcuts` value for a chord, as in `"Meta+K"`. Empty for a
+ * sequence, which the attribute cannot express, 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`. `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
+/** Current state of a rebinding session. */
+interface RebindState<Id extends string = string> {
+  /** Whether keys are actively being recorded. */
+  readonly recording: boolean;
+  /** What the last recording produced: a binding, or `null` for Backspace, which unbinds. */
+  readonly binding: Binding | null;
+  /** The steps typed so far, while recording a sequence. */
+  readonly steps: ReadonlyArray<Chord>;
+  /** Other commands using the recorded binding. */
+  readonly conflicts: ReadonlyArray<Conflict<Id>>;
+}
+/** Options for creating a rebinder. */
+interface RebindOptions<Id extends string = string> {
+  /** Record a sequence of chords, finished with Enter, instead of one chord. Defaults to `false`. */
+  sequence?: boolean;
+  /** Whether to write the recording into the keymap. Defaults to `true`. */
+  apply?: boolean;
+  /** Leave the keymap alone when the recording conflicts with another command. Defaults to `false`. */
+  rejectConflicts?: boolean;
+  /** Called with what was recorded: a binding, or `null` for Backspace, which unbinds. */
+  onRecord?: (binding: Binding | null, conflicts: ReadonlyArray<Conflict<Id>>) => void;
+  /** Called when a recording is cancelled with Escape or `cancel()`. */
+  onCancel?: () => void;
+}
+/** Controller instance for managing a rebinding session. */
+interface Rebinder<Id extends string = string> {
+  /** Begins capturing keys. */
+  start: () => void;
+  /** Stops capturing keys without recording. */
+  cancel: () => void;
+  /** Records the sequence steps typed so far, as Enter does. */
+  commit: () => void;
+  /** Current rebinder state. */
+  readonly state: RebindState<Id>;
+  /** Subscribes to rebinder state changes. Returns an unsubscribe function. */
+  subscribe: (listener: () => void) => () => void;
+  /** Ends any recording, silently. The rebinder is not for use afterwards. */
+  destroy: () => void;
+}
+/**
+ * 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) => showConflicts(conflicts),
+ * });
+ * rebinder.start();
+ * ```
+ */
+declare function createRebinder<Id extends string>(registry: Commands<Id>, id: Id, options?: RebindOptions<Id>): Rebinder<Id>;
+//#endregion
+//#region src/registry.d.ts
+/**
+ * Creates a command registry.
+ *
+ * @example
+ * ```ts
+ * export const commands = createCommands({
+ *   "palette.open": { title: "Open command palette", keys: "Mod+K" },
+ *   "nav.inbox": {
+ *     title: "Go to inbox",
+ *     keys: seq("G", "I"),
+ *     run: () => router.navigate("/inbox"),
+ *   },
+ * });
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * export const commands = createCommands({ … });
+ * export type AppCommandId = CommandId<typeof commands>;
+ * ```
+ */
+type CommandId<C> = C extends Commands<infer Id> ? Id : never;
+//#endregion
+export { Rebinder as a, importKeymap as c, bindingTokens as d, formatBinding as f, RebindState as i, webStorage as l, seq as m, createCommands as n, createRebinder as o, isSingleKeyBinding as p, RebindOptions as r, exportKeymap as s, CommandId as t, ariaKeyShortcuts 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 Chord, S as SerializedKeymap, T as Platform, _ as RunBlockReason, a as CommandDefinition, b as SequenceBinding, c as CommandSource, d as Conflict, f as ConflictOptions, g as PlatformBindings, h as KeymapStore, i as CommandContext, l as Commands, m as KeyCapture, n as BindingInput, o as CommandHandler, p as Json, r as Command, s as CommandKeymap, t as Binding, u as CommandsOptions, v as RunOptions, w as Key, x as SerializedBinding, y as ScopeOptions } from "./types-BxMI3b4a.mjs";
+import { a as Rebinder, c as importKeymap, d as bindingTokens, f as formatBinding, i as RebindState, l as webStorage, m as seq, n as createCommands, o as createRebinder, p as isSingleKeyBinding, r as RebindOptions, s as exportKeymap, t as CommandId, u as ariaKeyShortcuts } from "./index-BnB38jCF.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 Json, type Key, type KeyCapture, type KeymapStore, type Platform, type PlatformBindings, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, seq, 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 webStorage, c as formatBinding, i as importKeymap, l as isSingleKeyBinding, n as createRebinder, o as ariaKeyShortcuts, r as exportKeymap, s as bindingTokens, t as createCommands, u as seq } from "./src-CGKvYKjd.mjs";
+export { ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, seq, webStorage };