@inklu/keys 2.0.2 → 2.2.0

package/dist/index-DRXMJmbc.d.mts

@@ -0,0 +1,173 @@
+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.
+ *
+ * @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, options?: DisplayOptions): 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;
+/**
+ * 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";
+/** 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. */
+  readonly binding: Binding | null;
+  /** Captured steps in the current sequence session. */
+  readonly steps: ReadonlyArray<Chord>;
+  /** 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. */
+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`. */
+  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.
+   */
+  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. */
+  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. */
+  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. */
+  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
+//#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 };

package/dist/index.d.mts

@@ -1,3 +1,3 @@
-import { A as HotkeySequence, C as Command, D as Conflict, E as CommandSource, F as SequenceBinding, I as SerializedBinding, M as KeymapStorage, N as Platform, O as ConflictKind, P as ScopeOptions, S as Chord, T as CommandDefinition, _ as bindingTokens, a as Commands, b as Binding, c as PendingSequence, d as createCommands, f as CommandKeymap, g as ariaKeyShortcuts, h as DisplayOptions, i as CommandId, j as KeymapPersistence, k as Hotkey, l as RunBlockReason, m as SerializedOverride, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as formatBinding, w as CommandContext, x as BindingInput, y as spokenBinding } from "./attributes-DotLr2MW.mjs";
-import { a as RebindState, c as BindingValidation, d as validateBinding, i as RebindOptions, l as isSingleKeyBinding, n as ALWAYS_SCOPE, o as Rebinder, r as RebindMode, s as createRebinder, t as matchCommands, u as seq } from "./index-BTgscYdI.mjs";
-export { ALWAYS_SCOPE, type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandle, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Hotkey, type HotkeySequence, type KeymapPersistence, type KeymapStorage, type ObserveOptions, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, 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,3 +1,2 @@
-import { observe } from "./attributes.mjs";
-import { a as ariaKeyShortcuts, c as spokenBinding, d as seq, i as createRebinder, n as createCommands, o as bindingTokens, p as validateBinding, r as ALWAYS_SCOPE, s as formatBinding, t as matchCommands, u as isSingleKeyBinding } from "./src-DgYjA1oS.mjs";
-export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, 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 { A as HotkeySequence, C as Command, D as Conflict, E as CommandSource, F as SequenceBinding, I as SerializedBinding, M as KeymapStorage, N as Platform, O as ConflictKind, P as ScopeOptions, S as Chord, T as CommandDefinition, _ as bindingTokens, a as Commands, b as Binding, c as PendingSequence, d as createCommands, f as CommandKeymap, g as ariaKeyShortcuts, h as DisplayOptions, i as CommandId, j as KeymapPersistence, k as Hotkey, l as RunBlockReason, m as SerializedOverride, n as observe, o as CommandsOptions, p as SerializedKeymap, r as CommandHandle, s as ConflictOptions, t as ObserveOptions, u as RunOptions, v as formatBinding, w as CommandContext, x as BindingInput, y as spokenBinding } from "./attributes-DotLr2MW.mjs";
-import { a as RebindState, c as BindingValidation, d as validateBinding, i as RebindOptions, l as isSingleKeyBinding, n as ALWAYS_SCOPE, o as Rebinder, r as RebindMode, s as createRebinder, t as matchCommands, u as seq } from "./index-BTgscYdI.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 RebindState, c as BindingValidation, d as validateBinding, i as Re
  * ```
  */
 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
@@ -29,7 +33,9 @@ export declare function useShortcut<Id extends string>(registry: Commands<Id>, i
   spoken: string;
 };
 /**
- * Activates a scope for the lifecycle of the component.
+ * Activates a scope for the lifecycle of the component. Scopes rank in the
+ * order React runs effects in: of a parent and a child opening in the same
+ * render, the child is pushed first.
  *
  * @example
  * ```tsx
@@ -37,8 +43,19 @@ 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;
-/** Registers a dynamic command for the lifecycle of the component. */
-export declare function useRegisterCommand<Id extends string>(registry: Commands<Id>, id: NoInfer<Id> | (string & {}), definition: CommandDefinition<NoInfer<Id>>): void;
+/**
+ * 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
+ * useCommandHandler(commands, "palette.open", () => setOpen(true));
+ * useCommandHandler(commands, "doc.save", save, dirty);
+ * ```
+ */
+export declare function useCommandHandler<Id extends string>(registry: Commands<Id>, id: NoInfer<Id>, run: CommandHandler<NoInfer<Id>>, enabled?: boolean): void;
 /** State and actions for rebinding a command. */
 interface UseRebindResult<Id extends string = string> extends RebindState<Id> {
   /** Active display string for the shortcut. */
@@ -56,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 { ALWAYS_SCOPE, type Binding, type BindingInput, type BindingValidation, type Chord, type Command, type CommandContext, type CommandDefinition, type CommandHandle, type CommandId, type CommandKeymap, type CommandSource, type Commands, type CommandsOptions, type Conflict, type ConflictKind, type ConflictOptions, type DisplayOptions, type Hotkey, type HotkeySequence, type KeymapPersistence, type KeymapStorage, type ObserveOptions, type PendingSequence, type Platform, type RebindMode, type RebindOptions, type RebindState, type Rebinder, type RunBlockReason, type RunOptions, type ScopeOptions, type SequenceBinding, type SerializedBinding, type SerializedKeymap, type SerializedOverride, type UseRebindResult, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, 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 };

package/dist/react.mjs

@@ -1,16 +1,66 @@
 "use client";
-import { observe } from "./attributes.mjs";
-import { a as ariaKeyShortcuts, c as spokenBinding, d as seq, f as toBindings, i as createRebinder, l as bindingSignature, n as createCommands, o as bindingTokens, p as validateBinding, r as ALWAYS_SCOPE, s as formatBinding, t as matchCommands, u as isSingleKeyBinding } from "./src-DgYjA1oS.mjs";
-import { getKeyStateTracker } from "@tanstack/hotkeys";
-import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { a as importKeymap, c as bindingTokens, d as isSingleKeyBinding, f as seq, i as exportKeymap, l as formatBinding, m as keyName, n as createCommands, o as webStorage, p as isModifierKey, r as createRebinder, s as ariaKeyShortcuts, t as matchCommands, u as spokenBinding } from "./src-TaZw4V61.mjs";
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+//#region src/held.ts
+/** Which keys are down right now. Listens only while something is subscribed. */
+const NONE = [];
+/** Held keys by physical key, so two keys producing one character stay apart. */
+const down = /* @__PURE__ */ new Map();
+const listeners = /* @__PURE__ */ new Set();
+let held = NONE;
+const identify = (event) => event.code || `key:${keyName(event.key)}`;
+function publish() {
+	held = down.size === 0 ? NONE : [...new Set(down.values())];
+	for (const listener of listeners) listener();
+}
+function onKeyDown(event) {
+	if (!event.key || down.has(identify(event))) return;
+	down.set(identify(event), keyName(event.key));
+	publish();
+}
+function onKeyUp(event) {
+	down.delete(identify(event));
+	if (event.key === "Meta") {
+		for (const [identity, key] of down) if (!isModifierKey(key)) down.delete(identity);
+	}
+	publish();
+}
+/** Leaving the window or hiding the page swallows the keyups, so nothing is held any more. */
+function onLeave() {
+	if (down.size === 0) return;
+	down.clear();
+	publish();
+}
+/** The keys held right now, by name. Empty unless something is subscribed. */
+function heldKeys() {
+	return held;
+}
+/** Watches held keys until the returned function is called. */
+function subscribeHeldKeys(listener) {
+	listeners.add(listener);
+	if (listeners.size === 1) {
+		document.addEventListener("keydown", onKeyDown, true);
+		document.addEventListener("keyup", onKeyUp, true);
+		document.addEventListener("visibilitychange", onLeave);
+		window.addEventListener("blur", onLeave);
+	}
+	return () => {
+		listeners.delete(listener);
+		if (listeners.size > 0) return;
+		document.removeEventListener("keydown", onKeyDown, true);
+		document.removeEventListener("keyup", onKeyUp, true);
+		document.removeEventListener("visibilitychange", onLeave);
+		window.removeEventListener("blur", onLeave);
+		down.clear();
+		held = NONE;
+	};
+}
+//#endregion
 //#region src/react/hooks.ts
 const EMPTY_TOKENS = [];
-const EMPTY_CODES = {};
 const EMPTY_PENDING = [];
 const getEmptyTokens = () => EMPTY_TOKENS;
-const getEmptyCodes = () => EMPTY_CODES;
 const getEmptyPending = () => EMPTY_PENDING;
-const getFalse = () => false;
 /**
 * Mounts a commands registry for the lifecycle of the component.
 *
@@ -25,20 +75,23 @@ const getFalse = () => false;
 function useMountCommands(registry) {
 	useEffect(() => registry.mount(), [registry]);
 }
-function useCommandList(registry) {
+/**
+* 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.
+*/
+function useCommands(registry) {
 	const subscribe = useCallback((onChange) => registry.subscribe(onChange), [registry]);
 	const getSnapshot = useCallback(() => registry.list(), [registry]);
 	const getServerSnapshot = useCallback(() => registry.serverList(), [registry]);
 	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
-/** Returns all registered commands, re-rendering when the registry changes. */
-function useCommands(registry) {
-	return useCommandList(registry);
-}
-/** Returns a specific command snapshot by ID. */
+/** Returns one command's snapshot, re-rendering only when that command changes. */
 function useCommand(registry, id) {
-	const commands = useCommandList(registry);
-	return useMemo(() => commands.find((command) => command.id === id), [commands, id]);
+	const subscribe = useCallback((onChange) => registry.subscribe(onChange), [registry]);
+	const getSnapshot = useCallback(() => registry.get(id), [registry, id]);
+	const getServerSnapshot = useCallback(() => registry.serverList().find((command) => command.id === id), [registry, id]);
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }
 /**
 * Returns display and accessibility shortcuts for a command's primary
@@ -55,7 +108,9 @@ function useShortcut(registry, id) {
 	}), [command]);
 }
 /**
-* Activates a scope for the lifecycle of the component.
+* Activates a scope for the lifecycle of the component. Scopes rank in the
+* order React runs effects in: of a parent and a child opening in the same
+* render, the child is pushed first.
 *
 * @example
 * ```tsx
@@ -64,113 +119,83 @@ function useShortcut(registry, id) {
 */
 function useScope(registry, name, active = true, options = {}) {
 	const exclusive = options.exclusive === true;
-	const strict = options.strict === true;
 	useEffect(() => {
 		if (!active) return;
-		return registry.pushScope(name, {
-			exclusive,
-			strict
-		});
+		return registry.pushScope(name, { exclusive });
 	}, [
 		registry,
 		name,
 		active,
-		exclusive,
-		strict
+		exclusive
 	]);
 }
-/** Registers a dynamic command for the lifecycle of the component. */
-function useRegisterCommand(registry, id, definition) {
-	const latest = useRef(definition);
-	latest.current = definition;
-	const signature = useMemo(() => definitionSignature(definition), [definition]);
+/**
+* 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
+* useCommandHandler(commands, "palette.open", () => setOpen(true));
+* useCommandHandler(commands, "doc.save", save, dirty);
+* ```
+*/
+function useCommandHandler(registry, id, run, enabled = true) {
+	const latest = useRef(run);
+	latest.current = run;
 	useEffect(() => {
-		const handle = registry.add(id, {
-			...latest.current,
-			run: (context) => latest.current.run(context),
-			when: () => latest.current.when?.() !== false
-		});
-		return () => handle.dispose();
+		if (!enabled) return;
+		return registry.handle(id, (context) => latest.current(context));
 	}, [
 		registry,
 		id,
-		signature
+		enabled
 	]);
 }
-function definitionSignature(definition) {
-	return [
-		toBindings(definition.keys).map((binding) => bindingSignature(binding)).join("|"),
-		definition.scope ?? "",
-		definition.title,
-		definition.description ?? "",
-		definition.group ?? "",
-		(definition.keywords ?? []).join(","),
-		definition.hidden === true ? "1" : "0",
-		definition.enabled === false ? "0" : "1",
-		definition.preventDefault === false ? "0" : "1",
-		definition.ignoreInputs === void 0 ? "" : String(definition.ignoreInputs),
-		definition.requireReset === true ? "1" : "0",
-		definition.sequenceTimeout === void 0 ? "" : String(definition.sequenceTimeout)
-	].join(" ");
-}
-const IDLE_REBIND = {
-	recording: false,
-	binding: null,
-	steps: [],
-	conflicts: []
-};
 /** Hook for recording and configuring a command's keybindings. */
 function useRebind(registry, id, options = {}) {
 	const latest = useRef(options);
 	latest.current = options;
-	const command = useCommand(registry, id);
-	const [rebinder, setRebinder] = useState(null);
-	const [state, setState] = useState(IDLE_REBIND);
 	const mode = options.mode ?? "chord";
-	const idleTimeout = options.idleTimeout;
-	useEffect(() => {
-		const instance = createRebinder(registry, id, {
-			mode,
-			idleTimeout,
-			get apply() {
-				return latest.current.apply;
-			},
-			get add() {
-				return latest.current.add;
-			},
-			get rejectConflicts() {
-				return latest.current.rejectConflicts;
-			},
-			get ignoreInputs() {
-				return latest.current.ignoreInputs;
-			},
-			onRecord: (binding, conflicts) => latest.current.onRecord?.(binding, conflicts),
-			onCancel: () => latest.current.onCancel?.(),
-			onClear: () => latest.current.onClear?.()
-		});
-		const unsubscribe = instance.subscribe(() => setState(instance.state));
-		setRebinder(instance);
-		return () => {
-			unsubscribe();
-			instance.destroy();
-			setRebinder(null);
-			setState(IDLE_REBIND);
-		};
-	}, [
+	const rebinder = useMemo(() => createRebinder(registry, id, {
+		mode,
+		get apply() {
+			return latest.current.apply;
+		},
+		get add() {
+			return latest.current.add;
+		},
+		get rejectConflicts() {
+			return latest.current.rejectConflicts;
+		},
+		get ignoreInputs() {
+			return latest.current.ignoreInputs;
+		},
+		get idleTimeout() {
+			return latest.current.idleTimeout;
+		},
+		onRecord: (binding, conflicts) => latest.current.onRecord?.(binding, conflicts),
+		onCancel: () => latest.current.onCancel?.(),
+		onClear: () => latest.current.onClear?.()
+	}), [
 		registry,
 		id,
-		mode,
-		idleTimeout
+		mode
 	]);
+	useEffect(() => rebinder.destroy, [rebinder]);
+	const getState = useCallback(() => rebinder.state, [rebinder]);
+	const state = useSyncExternalStore(rebinder.subscribe, getState, getState);
+	const command = useCommand(registry, id);
 	return useMemo(() => ({
 		...state,
 		display: command?.display[0] ?? "",
 		tokens: command?.tokens[0] ?? EMPTY_TOKENS,
 		overridden: command?.overridden ?? false,
-		start: () => rebinder?.start(),
-		stop: () => rebinder?.stop(),
-		cancel: () => rebinder?.cancel(),
-		commit: () => rebinder?.commit(),
+		start: rebinder.start,
+		stop: rebinder.stop,
+		cancel: rebinder.cancel,
+		commit: rebinder.commit,
 		clear: () => registry.keymap.set(id, null),
 		reset: () => registry.keymap.reset(id)
 	}), [
@@ -181,45 +206,15 @@ function useRebind(registry, id, options = {}) {
 		id
 	]);
 }
-function useKeyState() {
-	return useCallback((onChange) => {
-		const subscription = getKeyStateTracker().store.subscribe(onChange);
-		return () => subscription.unsubscribe();
-	}, []);
-}
-/** Returns an array of keys currently held down. */
+/** Returns the keys held down right now, by the name `KeyboardEvent.key` gives each. */
 function useHeldKeys() {
-	return useSyncExternalStore(useKeyState(), () => getKeyStateTracker().store.state.heldKeys, getEmptyTokens);
+	return useSyncExternalStore(subscribeHeldKeys, heldKeys, getEmptyTokens);
 }
-/**
-* Checks whether a specific key is currently held down.
-*
-* @example
-* ```tsx
-* const shift = useKeyHold("Shift");
-* ```
-*/
-function useKeyHold(key) {
-	const subscribe = useKeyState();
-	const getSnapshot = useCallback(() => getKeyStateTracker().isKeyHeld(key), [key]);
-	return useSyncExternalStore(subscribe, getSnapshot, getFalse);
-}
-/** Returns a map of held key identifiers to physical event codes. */
-function useHeldKeyCodes() {
-	return useSyncExternalStore(useKeyState(), () => getKeyStateTracker().store.state.heldCodes, getEmptyCodes);
-}
-/**
-* Returns currently active partially-typed sequences.
-*
-* @example
-* ```tsx
-* const pending = usePendingSequences(commands);
-* ```
-*/
+/** Returns the half-typed sequences, for a hint such as "G …". */
 function usePendingSequences(registry) {
 	const subscribe = useCallback((onChange) => registry.subscribePending(onChange), [registry]);
 	const getSnapshot = useCallback(() => registry.pending(), [registry]);
 	return useSyncExternalStore(subscribe, getSnapshot, getEmptyPending);
 }
 //#endregion
-export { ALWAYS_SCOPE, ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, formatBinding, isSingleKeyBinding, matchCommands, observe, seq, spokenBinding, useCommand, useCommands, useHeldKeyCodes, useHeldKeys, useKeyHold, useMountCommands, usePendingSequences, useRebind, useRegisterCommand, useScope, useShortcut, validateBinding };
+export { ariaKeyShortcuts, bindingTokens, createCommands, createRebinder, exportKeymap, formatBinding, importKeymap, isSingleKeyBinding, matchCommands, seq, spokenBinding, useCommand, useCommandHandler, useCommands, useHeldKeys, useMountCommands, usePendingSequences, useRebind, useScope, useShortcut, webStorage };