@inklu/keys 2.2.0 → 3.0.0

package/README.md

@@ -8,7 +8,7 @@ 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. 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.
+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 skills: `npx skills add nkurunziza-saddy/inklu --skill inklu-keys` for the API, and `--skill inklu-keys-practices` for choosing and showing shortcuts well
 
@@ -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,9 +38,11 @@ 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, 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.
+`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({
@@ -50,65 +52,26 @@ createCommands({
 });
 ```
 
-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,
-});
-```
+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.
 
-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>({ … })`.
+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>
 	);
 }
@@ -123,10 +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.
-- 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.
+- 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.
 
@@ -135,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.
@@ -154,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
@@ -167,70 +121,41 @@ 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.
+`set` replaces the command's keys outright; setting exactly the default forgets the override instead.
 
-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`:
+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.
 
-```ts
-createCommands(commands, {
-	bindings: {
-		"palette.open": "Mod+P", // replace the shipped default
-		"doc.publish": null, // ship it unbound
-	},
-});
-```
-
-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
-	// A binding the browser or OS reserves is never applied, whatever this says.
-	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 what stands in the way of `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`:
 
-- `"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).
+- `"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.
 
-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.
+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
 
@@ -240,65 +165,41 @@ import { createCommands, webStorage } from "@inklu/keys";
 createCommands(definitions, { persist: webStorage("my-app.keys") });
 ```
 
-`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.
+`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.
 
-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.
+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`), and `{ mac, other }` keys to its side. 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, 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.
+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, 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.
+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
-
-Definitions can carry what a palette needs to list and find them, and `matchCommands` does the filtering:
+## 8. Command palette
 
-```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";
@@ -312,45 +213,9 @@ 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
+## 10. Recipes
 
-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.
+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+/`
 
@@ -358,17 +223,16 @@ Bind a hold to a bare key. While Command is down, macOS sends no `keyup` for the
 "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.
+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
 
-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:
+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", hidden: true }
+// "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)} />;
 ```
 
@@ -377,28 +241,26 @@ Move focus to the item the field belongs to, not to nothing, so the next key has
 ## API Summary
 
 - `createCommands(definitions, options)` - creates the registry
-  - `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`
+  - `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`
+  - `commands.keymap`: `get`, `set`, `reset`
   - `commands.setSingleKeyShortcuts(enabled)`, `commands.singleKeyShortcuts`
-- `webStorage(key, storage?)` - the `persist` option: Web Storage, followed across tabs
+- `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`, `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()` - 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.
 
@@ -406,22 +268,14 @@ Inside a handler, the context's `commands` is typed with the registry's own ids,
 
 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:
+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:
 
 ```tsx
-const { aria, spoken } = useShortcut(commands, "nav.inbox");
-<button aria-keyshortcuts={aria || undefined} aria-description={spoken || undefined}>
-	Inbox
-</button>;
-```
-
-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:
-
-```ts
-commands.setSingleKeyShortcuts(false); // or createCommands(defs, { singleKeyShortcuts: false })
+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-D-hUKGoN.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/{index-DRXMJmbc.d.mts → index-BnB38jCF.d.mts}

@@ -1,4 +1,4 @@
-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";
+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.
@@ -20,29 +20,24 @@ declare function isSingleKeyBinding(binding: Binding): boolean;
  * 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;
+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, options?: DisplayOptions): Array<string>;
-/**
- * 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;
+declare function bindingTokens(binding: Binding, platform?: Platform): Array<string>;
 /**
  * The `aria-keyshortcuts` value for a chord, as in `"Meta+K"`. Empty for a
- * sequence and for a chord that cannot be read.
+ * 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`, 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.
+ * 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
@@ -59,58 +54,43 @@ declare function exportKeymap<Id extends string>(commands: Pick<Commands<Id>, "k
 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";
 /** Current state of a rebinding session. */
 interface RebindState<Id extends string = string> {
   /** Whether keys are actively being recorded. */
   readonly recording: boolean;
-  /** Most recently captured binding. */
+  /** What the last recording produced: a binding, or `null` for Backspace, which unbinds. */
   readonly binding: Binding | null;
-  /** Captured steps in the current sequence session. */
+  /** The steps typed so far, while recording a sequence. */
   readonly steps: ReadonlyArray<Chord>;
-  /** What stands in the captured binding's way: other commands using it, or the platform reserving it. */
+  /** Other commands using the recorded binding. */
   readonly conflicts: ReadonlyArray<Conflict<Id>>;
 }
 /** Options for creating a rebinder. */
 interface RebindOptions<Id extends string = string> {
-  /** Capture mode. Defaults to `"chord"`. */
-  mode?: RebindMode;
-  /** Whether to write the recorded (or cleared) binding into the keymap. Defaults to `true`. */
+  /** 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;
-  /** Whether to append rather than replace existing bindings. Defaults to `false`. */
-  add?: boolean;
-  /**
-   * Prevent applying bindings that conflict with other commands. Defaults to
-   * `false`. A binding the browser or operating system reserves is never applied.
-   */
+  /** Leave the keymap alone when the recording conflicts with another command. Defaults to `false`. */
   rejectConflicts?: boolean;
-  /** Ignore key events from inputs while recording. Defaults to `true`. */
-  ignoreInputs?: boolean;
-  /** Inactivity timeout in milliseconds before a sequence commits. */
-  idleTimeout?: number;
-  /** Callback fired when a binding is recorded. */
-  onRecord?: (binding: Binding, conflicts: ReadonlyArray<Conflict<Id>>) => void;
-  /** Callback fired when recording is cancelled. */
+  /** 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;
-  /** Callback fired when Backspace or Delete clears the binding while recording. */
-  onClear?: () => void;
 }
 /** Controller instance for managing a rebinding session. */
 interface Rebinder<Id extends string = string> {
   /** Begins capturing keys. */
   start: () => void;
   /** Stops capturing keys without recording. */
-  stop: () => void;
-  /** Stops capturing keys and reports cancellation. */
   cancel: () => void;
-  /** Commits the currently captured sequence steps. */
+  /** 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;
-  /** Destroys the rebinder and cleans up listeners. */
+  /** Ends any recording, silently. The rebinder is not for use afterwards. */
   destroy: () => void;
 }
 /**
@@ -156,18 +136,4 @@ declare function createCommands<Id extends string>(definitions: { [K in Id]: Com
  */
 type CommandId<C> = C extends Commands<infer Id> ? Id : never;
 //#endregion
-//#region src/search.d.ts
-/**
- * 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
- * const results = matchCommands(commands.list(), "go inbox");
- * ```
- */
-declare function matchCommands<Id extends string>(commands: ReadonlyArray<Command<Id>>, query: string): Array<Command<Id>>;
-//#endregion
-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 };
+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 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 };
+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 };