modern-cmdk 1.5.0 → 1.6.0

package/README.md

@@ -119,7 +119,7 @@ function CommandPalette() {
 ```ts
 import { createCommandMachine, itemId } from 'modern-cmdk';
 
-using machine = createCommandMachine({
+const machine = createCommandMachine({
   items: [
     { id: itemId('copy'), value: 'Copy', shortcut: 'Mod+C', onSelect: () => navigator.clipboard.writeText(getSelection()?.toString() ?? '') },
     { id: itemId('paste'), value: 'Paste', shortcut: 'Mod+V', onSelect: () => navigator.clipboard.readText().then((text) => console.log('Pasted:', text)) },
@@ -128,14 +128,30 @@ using machine = createCommandMachine({
   loop: true,
 });
 
+const unsubscribe = machine.subscribe(() => {
+  console.log(machine.getState());
+});
+
+// send() is batched: the machine applies these three events on the next animation frame
+// (a microtask where requestAnimationFrame is absent, such as Node), commits one
+// stateChange for the batch (each SEARCH_CHANGE filters when it runs; registry events refilter once
+// per batch; with `frecency` on, the frecency load can commit one more stateChange when it settles
+// after the batch). getState() right after send() still returns the previous state.
+// The sample is for a browser: the copy item's onSelect uses getSelection() and navigator.clipboard.
 machine.send({ type: 'SEARCH_CHANGE', query: 'cop' });
 machine.send({ type: 'NAVIGATE', direction: 'next' });
 machine.send({ type: 'ITEM_SELECT', id: itemId('copy') });
 
-machine.subscribe(() => {
-  console.log(machine.getState());
-});
-// Automatic cleanup via `using` -- no manual dispose needed
+// Teardown, when the palette goes away (not right after send(): dispose drops events still pending
+// and removes the global shortcut listener):
+export function teardown(): void {
+  unsubscribe();
+  machine[Symbol.dispose]();
+}
+
+// Do not write `using machine = ...` at module top level: it disposes the machine when the module
+// finishes evaluating, before the batch runs. `await using machine = ...` inside an async scope that
+// outlives the work also works, and additionally awaits a pending frecency save before it disposes.
 ```
 
 ## What is in it
@@ -144,10 +160,10 @@ machine.subscribe(() => {
 - **React 19 adapter** -- compound components over `useSyncExternalStore`, `useTransition` and `use()`; React Compiler compatible.
 - **Automatic virtualization** -- turns on when more than 100 items match and off again at 50 or fewer (fixed thresholds; force it with `<Command.List virtualize>` or `virtualize={false}`). The `virtualizeThreshold` option is accepted but not read yet.
 - **Fuzzy search and frecency** -- a built-in TypeScript scorer with match ranges, and frequency x recency ranking with memory or IndexedDB persistence. `modern-cmdk-search-wasm` is an experimental, unpublished workspace package that does not work yet.
-- **Keyboard shortcuts** -- a registry with a cross-platform `Mod` key and conflict detection.
+- **Keyboard shortcuts** -- a registry with a cross-platform `Mod` key. Two items bound to one key are a conflict: the later binding wins the keydown (disposing it restores the earlier one), `getConflicts()` lists the keys with two or more bindings and `getBindings()` returns the winning binding of each key.
 - **Accessibility** -- WAI-ARIA combobox pattern, `aria-live` announcements, `forced-colors`, `prefers-contrast`, `prefers-reduced-motion`.
 - **Animation** -- the stylesheet defines the dialog enter and exit on opacity, scale and translate, which are compositor-only; the overlay fades opacity and also transitions `--command-overlay-opacity`, its background alpha, which repaints, and the list height and item background-color transitions are not compositor-only either. In 1.x neither the dialog nor the overlay animates on enter or exit, because their duration and easing tokens are declared only on `[data-command-root]`, which sits inside the dialog (DT-19, planned for 1.8.0).
-- **Extras** -- `CommandErrorBoundary`, `useCommandDevtools()` and telemetry middleware.
+- **Extras** -- `CommandErrorBoundary`, `useCommandDevtools()` and `createTelemetryMiddleware()`, which returns hooks that your code calls itself (the machine and the React components have no telemetry option).
 
 Theming (CSS custom properties, `@layer command`) is covered in the [theming guide](https://abcrimson.github.io/modern-cmdk/guide/theming.html).
 

package/dist/codemod/chunk-worker.mjs

@@ -219,17 +219,26 @@ async function relativeToRoot(files, cwd, root) {
 }
 const key = (path) => process.platform === "win32" ? path.toLowerCase() : path;
 /**
-* Root-relative paths of the gitlinks (mode 160000: submodules) in the repository at `root`. One
-* level is enough: a submodule nested inside a submodule is not looked for.
+* Root-relative paths (forward slashes) of the gitlinks (mode 160000: submodules) in the
+* repository at `root`, and of the gitlinks inside each submodule that holds one of `rels` (the
+* root-relative files being checked), at any depth: a submodule nested in a submodule is its own
+* repository, and git refuses a path that lies inside it.
 */
-async function gitlinksOf(root, boundary) {
+async function gitlinksOf(root, boundary, rels) {
 	const { code, stdout, stderr } = await runGit([
 		"ls-files",
 		"-s",
 		"-z"
 	], root, boundary);
 	if (code !== 0) throw new Error(`git ls-files failed (exit ${code}): ${stderr.trim()}`);
-	return stdout.split("\0").filter((entry) => entry.startsWith("160000 ")).map((entry) => entry.slice(entry.indexOf("	") + 1));
+	const links = stdout.split("\0").filter((entry) => entry.startsWith("160000 ")).map((entry) => entry.slice(entry.indexOf("	") + 1));
+	const found = [...links];
+	for (const link of links) {
+		const below = rels.filter((rel) => key(rel).startsWith(`${key(link)}/`)).map((rel) => rel.slice(link.length + 1));
+		if (below.length === 0) continue;
+		for (const nested of await gitlinksOf(join(root, link), boundary, below)) found.push(`${link}/${nested}`);
+	}
+	return found;
 }
 /** The paths of `rels` that `git check-ignore` run in `owner` reports as ignored. */
 async function ignoredIn(owner, rels, boundary) {
@@ -250,7 +259,7 @@ async function dropGitIgnored(files, cwd, boundary, warn) {
 	if (repo.kind === "none") return files;
 	const rels = await relativeToRoot(files, cwd, repo.root);
 	if (!rels.some((rel) => rel !== void 0)) return files;
-	const gitlinks = (await gitlinksOf(repo.root, boundary)).map(key);
+	const gitlinks = (await gitlinksOf(repo.root, boundary, rels.filter((rel) => rel !== void 0))).map(key);
 	const groups = /* @__PURE__ */ new Map();
 	rels.forEach((rel, index) => {
 		if (rel === void 0) return;

package/dist/codemod/transforms/data-attrs.mjs

@@ -36,9 +36,9 @@ const ATTRIBUTE_SELECTOR = /\[\s*([A-Za-z_][\w-]*)\s*(?:([~|^$*]?=)\s*("[^"]*"|'
 */
 const PARTIAL_ATTRIBUTE_SELECTOR = /\[\s*([A-Za-z_][\w-]*)(?=\s*[~|^$*]?=|\s*$)/dy;
 /** Tailwind presence form of the two state attributes: data-[selected]:, data-[disabled]/name:. */
-const TAILWIND_PRESENCE = /(?<!\w)data-\[(selected|disabled)\](?=[:/])/g;
+const TAILWIND_PRESENCE = /(?<!\w)data-\[((?i:selected|disabled))\](?=[:/])/g;
 /** Tailwind value variants of the two state attributes: data-[selected=true]:, data-[disabled='false']/name:. */
-const TAILWIND_STATE = /(?<!\w)data-\[(selected|disabled)=(?:(["'])(true|false)\2|(true|false))\](?=[:/])/g;
+const TAILWIND_STATE = /(?<!\w)data-\[((?i:selected|disabled))=(?:(["'])(true|false)\2|(true|false))\](?=[:/])/g;
 /** Whitespace that only pads a closing parenthesis, a comma or a combinator inside parentheses. */
 const ARGUMENT_PADDING = /\s*[),>+~]/y;
 /** Tailwind's `*:` and `**:` variants, which move a class to the element's children or descendants. */
@@ -63,6 +63,7 @@ function unquote(value) {
 * The text is cut into compounds (runs of simple selectors with no combinator, comma, brace or
 * whitespace at the top level). Inside any compound, a bracketed attribute whose name is in
 * ATTR_MAP gets its name replaced, operator and value kept; a name in UNMAPPED_ATTRS is reported.
+* Attribute names match case-insensitively, as they do in an HTML document: [CMDK-ITEM] is [cmdk-item].
 * A compound that holds a cmdk attribute also has its data-selected / data-disabled value
 * attributes rewritten: ="true" to the presence attribute, ="false" to :not(presence); any other
 * form is reported. In a stylesheet, a compound starting with `&` counts as holding a cmdk
@@ -97,9 +98,9 @@ function selectorEdits(text, css, report, tailwind) {
 	let brackets = 0;
 	if (!css) {
 		const whole = text.trim();
-		const reason = UNMAPPED_ATTRS.get(whole);
+		const reason = UNMAPPED_ATTRS.get(whole.toLowerCase());
 		if (reason !== void 0) report(text.indexOf(whole), `${whole} has no modern-cmdk equivalent: ${reason}; left unchanged`);
-		const mapped = ATTR_MAP.get(whole);
+		const mapped = ATTR_MAP.get(whole.toLowerCase());
 		if (mapped !== void 0) report(text.indexOf(whole), `${whole} is a cmdk attribute name outside a selector; modern-cmdk renders ${mapped}; left unchanged`);
 	}
 	const endCompound = (isArgument = false) => {
@@ -121,7 +122,7 @@ function selectorEdits(text, css, report, tailwind) {
 			}
 			const reason = UNMAPPED_ATTRS.get(a.name);
 			if (reason !== void 0) {
-				report(a.start, `${a.name} has no modern-cmdk equivalent: ${reason}; left unchanged`);
+				report(a.start, `${text.slice(a.nameStart, a.nameEnd)} has no modern-cmdk equivalent: ${reason}; left unchanged`);
 				continue;
 			}
 			const presence = STATE_ATTRS.get(a.name);
@@ -237,7 +238,7 @@ function selectorEdits(text, css, report, tailwind) {
 				attrs.push({
 					start: i,
 					end: ATTRIBUTE_SELECTOR.lastIndex,
-					name: m[1],
+					name: m[1].toLowerCase(),
 					nameStart: nameSpan[0],
 					nameEnd: nameSpan[1],
 					operator: m[2],
@@ -254,7 +255,7 @@ function selectorEdits(text, css, report, tailwind) {
 				attrs.push({
 					start: i,
 					end: PARTIAL_ATTRIBUTE_SELECTOR.lastIndex,
-					name: partial[1],
+					name: partial[1].toLowerCase(),
 					nameStart: partialName[0],
 					nameEnd: partialName[1],
 					operator: void 0,
@@ -325,16 +326,40 @@ function selectorEdits(text, css, report, tailwind) {
 function rewriteTailwind(text, report) {
 	return applyEdits(text, tailwindEdits(text, report));
 }
+/**
+* Reports a data variant that tests the state of another element and returns true; false for a
+* variant on the element itself. Those are the `group-`, `peer-` and `in-` variants, their
+* `-has-` forms and `not-` forms: they style an element by the state of an ancestor or a sibling,
+* which need not be a cmdk element (a cmdk item has no cmdk ancestor with a selected state), so
+* rewriting them to data-active would be a guess. A bare `has-` tests the descendants, which are
+* cmdk items in the common case, and stays rewritable.
+*/
+function reportedAsOther(text, m, report) {
+	const start = /(?<![\w-])(?:not-)?(?:(?:group|peer)(?:-has)?|in)-$/.exec(text.slice(0, m.index))?.index;
+	if (start === void 0) return false;
+	report(start, `${text.slice(start, m.index + m[0].length)}: styles this element by the state of another element (an ancestor or a sibling) that need not be a cmdk element, so it cannot be migrated automatically; left unchanged: check it by hand`);
+	return true;
+}
+/**
+* Reports the other-element data variants of a class list on an element that is not cmdk-bound:
+* nothing there is rewritten, but a `group-data-[selected=true]:` under a cmdk item stops working
+* once the item renders data-active.
+*/
+function reportOtherElements(text, report) {
+	for (const pattern of [TAILWIND_PRESENCE, TAILWIND_STATE]) for (const m of text.matchAll(pattern)) reportedAsOther(text, m, report);
+}
 /** The edits rewriteTailwind applies, as ranges of `text`. */
 function tailwindEdits(text, report) {
 	const edits = [];
 	for (const m of text.matchAll(TAILWIND_PRESENCE)) {
-		const name = `data-${m[1]}`;
+		if (reportedAsOther(text, m, report)) continue;
+		const name = `data-${m[1].toLowerCase()}`;
 		const presence = STATE_ATTRS.get(name);
 		report(m.index, `${m[0]}: on a cmdk element cannot be migrated automatically: cmdk rendered ${name} with a "true" or "false" value, modern-cmdk sets ${presence} only while the state holds; left unchanged`);
 	}
 	for (const m of text.matchAll(TAILWIND_STATE)) {
-		const presence = STATE_ATTRS.get(`data-${m[1]}`);
+		if (reportedAsOther(text, m, report)) continue;
+		const presence = STATE_ATTRS.get(`data-${m[1].toLowerCase()}`);
 		if ((m[3] ?? m[4]) === "true") edits.push({
 			start: m.index,
 			end: m.index + m[0].length,
@@ -444,7 +469,7 @@ function applyCookedEdits(inner, decoded, edits) {
 * literals, and Tailwind state variants on cmdk-bound elements.
 */
 function transform(fileInfo, api) {
-	if (!fileInfo.source.includes("cmdk")) return fileInfo.source;
+	if (!/cmdk/i.test(fileInfo.source)) return fileInfo.source;
 	const j = api.jscodeshift;
 	const root = j(fileInfo.source);
 	const sites = [];
@@ -471,19 +496,20 @@ function transform(fileInfo, api) {
 		return current?.type === "JSXIdentifier" && bound.has(current.name);
 	};
 	const tailwind = /* @__PURE__ */ new WeakSet();
+	const unbound = /* @__PURE__ */ new WeakSet();
 	root.find(j.JSXAttribute).forEach((path) => {
 		const attrName = path.node.name;
 		if (attrName.type !== "JSXIdentifier" || !CLASS_ATTRS.has(attrName.name)) return;
 		const element = path.parent?.node;
-		if (!isBound(element?.name)) return;
-		j(path).find(j.Literal).forEach((p) => void tailwind.add(p.node));
-		j(path).find(j.TemplateLiteral).forEach((p) => void tailwind.add(p.node));
+		const into = isBound(element?.name) ? tailwind : unbound;
+		j(path).find(j.Literal).forEach((p) => void into.add(p.node));
+		j(path).find(j.TemplateLiteral).forEach((p) => void into.add(p.node));
 	});
 	root.find(j.JSXAttribute).forEach((path) => {
 		const attrName = path.node.name;
 		if (attrName.type !== "JSXIdentifier") return;
-		const target = ATTR_MAP.get(attrName.name);
-		const reason = UNMAPPED_ATTRS.get(attrName.name);
+		const target = ATTR_MAP.get(attrName.name.toLowerCase());
+		const reason = UNMAPPED_ATTRS.get(attrName.name.toLowerCase());
 		if (target === void 0 && reason === void 0) return;
 		const node = path.node;
 		sites.push({
@@ -503,12 +529,14 @@ function transform(fileInfo, api) {
 		const raw = rawOf(node);
 		const inJsxAttribute = path.parent?.node?.type === "JSXAttribute";
 		const useTailwind = tailwind.has(path.node);
+		const reportOther = unbound.has(path.node);
 		sites.push({
 			pos: startOf(node),
 			run: () => {
 				const quote = raw?.[0];
 				if (!(quote === "\"" || quote === "'")) {
 					const report = reportAt(original, node.loc?.start?.line);
+					if (reportOther) reportOtherElements(original, report);
 					let rewritten = rewriteSelectors(original, false, report, useTailwind);
 					if (useTailwind) rewritten = rewriteTailwind(rewritten, report);
 					if (rewritten === original) return;
@@ -523,6 +551,7 @@ function transform(fileInfo, api) {
 					rawEnd: Array.from({ length: inner.length }, (_, k) => k + 1)
 				} : decodeRaw(inner);
 				const report = reportAt(decoded.cooked, node.loc?.start?.line);
+				if (reportOther) reportOtherElements(decoded.cooked, report);
 				const edits = selectorEdits(decoded.cooked, false, report, useTailwind);
 				if (useTailwind) edits.push(...tailwindEdits(decoded.cooked, report));
 				if (edits.length === 0) return;
@@ -537,6 +566,7 @@ function transform(fileInfo, api) {
 	root.find(j.TemplateLiteral).forEach((path) => {
 		const literal = path.node;
 		const useTailwind = tailwind.has(path.node);
+		const reportOther = unbound.has(path.node);
 		sites.push({
 			pos: startOf(literal),
 			run: () => {
@@ -557,6 +587,7 @@ function transform(fileInfo, api) {
 					}
 					api.report(line + message.replaceAll(PLACEHOLDER, PLACEHOLDER_TEXT));
 				};
+				if (reportOther) reportOtherElements(original, report);
 				let rewritten = rewriteSelectors(original, false, report, useTailwind);
 				if (useTailwind) rewritten = rewriteTailwind(rewritten, report);
 				if (rewritten === original) return;

package/dist/core/index.d.mts

@@ -2,14 +2,23 @@
 interface SearchResult {
   readonly id: ItemId;
   readonly score: number;
-  /** Character ranges that matched (for highlighting) — half-open [start, end) tuples, end exclusive */
+  /**
+   * Character ranges that matched (for highlighting) — half-open [start, end) tuples, end exclusive. The
+   * ranges index the original `item.value`, not its lowercased copy. A match on keywords only reports
+   * `matches: []`: there is nothing in the value to highlight.
+   */
   readonly matches: ReadonlyArray<readonly [start: number, end: number]>;
 }
 /** A scoring function that evaluates a single item against a query */
 type ScorerFn = (query: string, item: CommandItem) => SearchResult | null;
 /** Search engine interface — pluggable into the state machine */
 interface SearchEngine extends Disposable {
-  /** Index items for fast lookup (call on registration) */
+  /**
+   * Index items for fast lookup. The machine calls it on registration (the initial items, ITEMS_LOADED,
+   * REGISTER_ITEM) and again on UPDATE_ITEM with the updated item, so an id that is already indexed must
+   * be replaced by the new item, not appended to the index. Indexing is incremental: ids not in `items`
+   * stay indexed.
+   */
   index(items: readonly CommandItem[]): void;
   /** Search items by query, return ordered results — uses Iterator pipeline */
   search(query: string, items: readonly CommandItem[]): IteratorObject<SearchResult>;
@@ -42,6 +51,12 @@ declare const __groupIdBrand: unique symbol;
 type GroupId = string & {
   readonly [__groupIdBrand]: never;
 };
+/**
+ * The `groupedIds` key of items that have no group. The value is an observable key of
+ * `CommandState.groupedIds` and stays `'__ungrouped'`. A group registered under this id shares the
+ * bucket: its items are listed with the ungrouped ones and the bucket takes its priority.
+ */
+export declare const UNGROUPED_GROUP_ID: GroupId;
 /** Create a branded {@link ItemId} from a plain string. Ensures well-formed Unicode. */
 export declare function itemId(id: string): ItemId;
 /** Create a branded {@link GroupId} from a plain string. Ensures well-formed Unicode. */
@@ -61,7 +76,7 @@ interface CommandItem {
   readonly groupId?: GroupId | undefined;
   /** Keyboard shortcut string (e.g., "Ctrl+C", "Mod+K") */
   readonly shortcut?: string | undefined;
-  /** Whether this item is disabled (excluded from filtering and selection) */
+  /** Whether this item is disabled: excluded from navigation and selection; rendered unless `disabledItems: 'hide'` */
   readonly disabled?: boolean | undefined;
   /** Callback fired when this item is selected */
   readonly onSelect?: (() => void) | undefined;
@@ -92,7 +107,12 @@ interface CommandState {
   readonly activeId: ItemId | null;
   /** Ordered list of item IDs that pass the current filter */
   readonly filteredIds: readonly ItemId[];
-  /** Map of group IDs to their visible item IDs */
+  /**
+   * Map of group IDs to their visible item IDs. The keys are in group priority order (lower first; ungrouped
+   * items and unregistered group ids count as 0, in first-appearance order), while `filteredIds` and
+   * `NAVIGATE` keep the search order: a renderer that draws by `groupedIds` shows the groups in this order,
+   * so arrow-key order and display order can differ when group priorities differ.
+   */
   readonly groupedIds: ReadonlyMap<GroupId, readonly ItemId[]>;
   /** Count of visible items (shortcut for `filteredIds.length`) */
   readonly filteredCount: number;
@@ -141,6 +161,9 @@ type CommandEvent = {
 } | {
   readonly type: "REGISTER_ITEM";
   readonly item: CommandItem;
+} | {
+  readonly type: "UPDATE_ITEM";
+  readonly item: CommandItem;
 } | {
   readonly type: "UNREGISTER_ITEM";
   readonly id: ItemId;
@@ -178,6 +201,7 @@ interface FrecencyDecayConfig {
 interface FrecencyOptions {
   /** Turns frecency tracking and re-ranking on. Default false. */
   readonly enabled?: boolean | undefined;
+  /** Where the history persists; a storage you pass is yours to dispose, the engine disposes only the in-memory one it creates when you pass none. */
   readonly storage?: FrecencyStorage | undefined;
   readonly namespace?: string | undefined;
   readonly decayConfig?: FrecencyDecayConfig | undefined;
@@ -190,7 +214,10 @@ interface CommandMachineOptions {
   readonly items?: readonly CommandItem[] | undefined;
   /** Pre-registered groups for item categorization */
   readonly groups?: readonly CommandGroup[] | undefined;
-  /** Custom filter function, or `false` to disable filtering entirely */
+  /**
+   * Custom filter function, or `false` to disable filtering entirely. It returns a score: above 0 keeps the item
+   * (higher ranks first); 0, a negative score or `false` excludes it.
+   */
   readonly filter?: ((item: CommandItem, query: string) => number | false) | false | undefined;
   /** Accessible label for the command palette */
   readonly label?: string | undefined;
@@ -210,15 +237,31 @@ interface CommandMachineOptions {
   readonly onSearchChange?: ((query: string) => void) | undefined;
   /** Whether keyboard navigation loops from last to first item (default: true) */
   readonly loop?: boolean | undefined;
+  /**
+   * How disabled items are listed: `'show'` keeps them in `filteredIds` under every query (rendered with
+   * `aria-disabled`, never active, skipped by navigation and activation, not selectable); `'hide'` drops them
+   * from `filteredIds` in every branch (default: `'show'`)
+   */
+  readonly disabledItems?: "hide" | "show" | undefined;
+  /**
+   * What an item's keyboard shortcut does. `'direct'` (the default through 1.x) calls the item's `onSelect`
+   * and binds only items that have one; `'select'` dispatches `ITEM_SELECT` for the item, so the disabled guard,
+   * frecency, the select event and `options.onSelect` apply, and binds every enabled item with a shortcut. 2.0 flips
+   * the default to `'select'`. Under both, a disabled item is not bound: its shortcut does nothing and leaves the key to the page.
+   */
+  readonly shortcutAction?: "select" | "direct" | undefined;
   /** Accepted but not read yet: Command.List uses fixed thresholds (on above 100 matches, off at 50 or fewer) (default: 100) */
   readonly virtualizeThreshold?: number | undefined;
 }
-/** Default machine options */
+/**
+ * Default machine options. The machine reads `loop` and `open` from here when its options leave them out
+ * (the other options are opt-ins whose absence is their default); `virtualizeThreshold` is not read yet.
+ */
 export declare const DEFAULT_MACHINE_OPTIONS: Partial<CommandMachineOptions>;
 /** Initial state factory */
 export declare function createInitialState(options?: CommandMachineOptions): CommandState;
 /**
- * IndexedDB-backed frecency storage using idb-keyval.
+ * IndexedDB-backed frecency storage using idb-keyval's get, set and del.
  *
  * Persists frecency data across browser sessions. Implements both
  * `Disposable` and `AsyncDisposable` for use with `using` and `await using`.
@@ -260,15 +303,27 @@ export declare class IdbFrecencyStorage implements FrecencyStorage, AsyncDisposa
 export declare function computeFrecencyBonus(history: FrecencyRecord, now?: number, config?: FrecencyDecayConfig): number;
 /**
  * Stateful frecency engine that tracks item selection history and provides
- * ranking boosts for search results. Supports pluggable storage backends
- * and automatic flush on dispose. Uses Date.now() for timestamps.
+ * ranking boosts for search results. Supports pluggable storage backends.
+ * Dirty data is saved 1000 ms after the last `recordSelection`, when the page
+ * becomes hidden or is hidden for good (`visibilitychange`, `pagehide`), on
+ * `flush()` and on dispose; a save waits for a `load()` in flight, so it writes the merged
+ * history. Dispose disposes the storage only when the engine created it (no `storage`
+ * option): a storage the caller passes is the caller's to dispose. Uses Date.now() for
+ * timestamps.
  */
 export declare class FrecencyEngine implements Disposable, AsyncDisposable {
   #private;
   constructor(options: FrecencyOptions);
-  /** Load frecency data from storage */
+  /**
+   * Merge the data in storage into the engine: frequencies add, `lastUsed` takes the later
+   * time, and selections recorded before the load resolves are kept. Call it once per
+   * engine; a second load would add the persisted frequencies again. A save started while
+   * the load is in flight waits for it, so the history it writes is the merged one, and a load
+   * that never settles holds every save, and `await using`, forever. A failed load rejects here
+   * and turns persistence off for this engine: saving would replace a history it could not read.
+   */
   load(): Promise<void>;
-  /** Record a selection event for an item */
+  /** Record a selection event for an item and schedule a save 1000 ms after the last one */
   recordSelection(itemId: ItemId): void;
   /** Get frecency bonus for an item */
   getBonus(itemId: ItemId, now?: number): number;
@@ -278,12 +333,20 @@ export declare class FrecencyEngine implements Disposable, AsyncDisposable {
   getConfig(): FrecencyDecayConfig;
   /** Update decay configuration at runtime */
   setConfig(config: FrecencyDecayConfig): void;
-  /** Flush dirty data to storage */
+  /**
+   * Flush dirty data to storage and wait for every save in flight; saves run one after
+   * another, each after the load in flight (one that never settles holds them all), none after a
+   * rejected load, and a rejected save leaves the data dirty and rethrows to the flush that started it
+   */
   flush(): Promise<void>;
   /** Get the raw frecency data */
   getData(): FrecencyData;
-  /** Async dispose — flushes dirty data before cleanup. Use with `await using`. */
+  /**
+   * Async dispose — flushes dirty data, then disposes the storage the engine created, even
+   * when the save rejects (the rejection propagates). Use with `await using`.
+   */
   [Symbol.asyncDispose](): Promise<void>;
+  /** Sync dispose — starts the flush without awaiting it and disposes the storage the engine created once it settles */
   [Symbol.dispose](): void;
 }
 /**
@@ -345,7 +408,9 @@ interface ShortcutBinding {
 /**
  * Manages keyboard shortcut bindings with global keydown listening.
  * Supports `using` for automatic cleanup of both individual bindings and the
- * global document listener. Detects conflicts with the local mapGroupBy helper (core/utils/group-by.ts).
+ * global document listener. Every normalized shortcut keeps a stack of bindings, one per item: the later
+ * binding wins the keydown, disposing it restores the earlier one, and `getConflicts()` reports the keys with
+ * two or more bindings (through `detectConflicts`, which groups with the local mapGroupBy helper).
  */
 export declare class KeyboardShortcutRegistry implements Disposable {
   #private;
@@ -354,15 +419,18 @@ export declare class KeyboardShortcutRegistry implements Disposable {
   });
   /** Register a shortcut binding — returns Disposable for `using` auto-deregister */
   register(shortcutStr: string, itemId: ItemId, handler: () => void): Disposable;
-  /** Unregister a shortcut by its string representation */
+  /** Unregister a shortcut by its string representation — every binding of that key */
   unregister(shortcutStr: string): void;
-  /** Unregister all shortcuts for a given item — Map spec allows deletion during iteration */
-  unregisterByItem(itemId: ItemId): void;
-  /** Check for conflicting shortcuts */
+  /**
+   * Unregister all shortcuts for a given item — only the stacks of the keys it is bound under are touched.
+   * `keep` names one shortcut whose binding stays (a re-bind then replaces it in place, see register).
+   */
+  unregisterByItem(itemId: ItemId, keep?: string): void;
+  /** Keys bound by two or more items (normalized shortcut -> the parsed shortcuts, earliest first) */
   getConflicts(): ReadonlyMap<string, readonly ParsedShortcut[]>;
   /** Enable or disable global shortcut listening */
   setEnabled(enabled: boolean): void;
-  /** Get all registered bindings */
+  /** The winning binding of every key (a snapshot: the later of the bindings that share a key) */
   getBindings(): ReadonlyMap<string, ShortcutBinding>;
   [Symbol.dispose](): void;
 }
@@ -377,7 +445,7 @@ export declare class CommandRegistry implements Disposable {
   registerItem(item: CommandItem): Disposable;
   /** Register multiple items at once — single Disposable for batch cleanup. for...of for hot path. */
   registerItems(items: readonly CommandItem[]): Disposable;
-  /** Unregister a single item — O(1) Map/Set delete, indexOf+toSpliced for order */
+  /** Unregister a single item — O(1) Map/Set delete */
   unregisterItem(id: ItemId): void;
   /** Bulk unregister — for...of for hot path */
   unregisterItems(ids: ReadonlySet<ItemId>): void;
@@ -437,20 +505,31 @@ interface CommandMachine extends Disposable {
 }
 /**
  * Creates a headless command palette state machine with search, frecency,
- * and keyboard shortcut support. Implements Disposable for `using` cleanup.
+ * and keyboard shortcut support. Implements Disposable and AsyncDisposable for
+ * `using` and `await using` cleanup (the latter awaits the pending frecency save).
  *
  * @example
  * ```ts
- * using machine = createCommandMachine({ items, loop: true });
- * machine.subscribe(() => console.log(machine.getState()));
+ * const machine = createCommandMachine({ items, loop: true });
+ * const unsubscribe = machine.subscribe(() => console.log(machine.getState()));
+ * machine.send({ type: 'SEARCH_CHANGE', query: 'app' }); // handled in the next frame
+ *
+ * // on teardown
+ * unsubscribe();
+ * machine[Symbol.dispose]();
  * ```
  */
-export declare function createCommandMachine(options?: CommandMachineOptions): CommandMachine;
+export declare function createCommandMachine(options?: CommandMachineOptions): CommandMachine & AsyncDisposable;
 /**
  * Public API: scores a command item against a search query.
  * Multi-strategy: exact → prefix → substring → word-boundary → fuzzy.
  * Returns null if no match. For batch use, prefer the search engine
  * which pre-caches lowercase and normalizes query once.
+ *
+ * `matches` are half-open ranges into `item.value` itself (UTF-16 indices of the original
+ * string, even where lowercasing changes its length, as 'İ' → 'i̇' does). A keyword has no
+ * position in the label: when a keyword outscores the value, `matches` keeps the value's own
+ * ranges if the value matched and is `[]` otherwise.
  */
 export declare function scoreItem(query: string, item: CommandItem): SearchResult | null;
 /**
@@ -468,9 +547,10 @@ interface SearchEngineOptions {
   readonly scorer?: ScorerFn | undefined;
 }
 /**
- * Creates a search engine with pluggable scorer and incremental filtering.
- * When the query extends the previous one, only prior matches are re-scored.
- * Pre-caches lowercase at index time — zero toLowerCase() calls during search.
+ * Creates a search engine with pluggable scorer.
+ * With the default scorer, a query that extends the previous one (compared lowercased) re-scores
+ * only the prior matches; a custom scorer is called for every item on every non-empty query.
+ * Pre-caches lowercase at index time; indexed items are not re-lowered during search.
  * Uses Iterator Helpers (ES2025) for result pipelines.
  */
 export declare function createSearchEngine(options?: SearchEngineOptions): SearchEngine;
@@ -504,18 +584,19 @@ interface TelemetryMiddleware {
  * ```
  */
 export declare function createTelemetryMiddleware(hooks: CommandTelemetryHooks): TelemetryMiddleware;
-type EventMap = {
-  [key: string]: unknown;
-};
 /**
  * Type-safe event emitter with strong references and Disposable subscriptions.
+ * `T` maps event names to payload types; an interface or a type alias both work (`object`, not an index signature, which an interface lacks).
  * Returns Disposable from `on()` for automatic unsubscription via `using`.
  */
-export declare class TypedEmitter<T extends EventMap> implements Disposable {
+export declare class TypedEmitter<T extends object> implements Disposable {
   #private;
   /** Subscribe to an event. Returns a Disposable that removes the listener when disposed. */
   on<K extends keyof T>(event: K, listener: (data: T[K]) => void): Disposable;
-  /** Emit an event to all listeners. Snapshots the set to prevent live-iteration issues. */
+  /**
+   * Emit an event to all listeners. Snapshots the set to prevent live-iteration issues.
+   * A throwing listener does not stop the later ones: its error is rethrown from a microtask, as the scheduler does.
+   */
   emit<K extends keyof T>(event: K, data: T[K]): void;
   /** Check if any listeners exist for an event */
   has<K extends keyof T>(event: K): boolean;
@@ -527,7 +608,8 @@ export declare class TypedEmitter<T extends EventMap> implements Disposable {
 }
 /**
  * Batched update scheduler that coalesces state updates into a single tick.
- * Uses requestAnimationFrame in browsers, queueMicrotask in Node.js/tests.
+ * Uses requestAnimationFrame in browsers, queueMicrotask where requestAnimationFrame is absent (Node.js, SSR).
+ * flush() synchronously applies the updates pending when it is called, in the order scheduled; one scheduled during the flush runs on the next frame or microtask.
  */
 interface Scheduler extends Disposable {
   schedule(update: () => void): void;
@@ -536,7 +618,7 @@ interface Scheduler extends Disposable {
 }
 /**
  * Creates a batched update scheduler. Coalesces rapid state updates into a single
- * execution pass using rAF (browser) or queueMicrotask (Node.js).
+ * execution pass using rAF (browser) or queueMicrotask (where rAF is absent: Node.js, SSR).
  */
 export declare function createScheduler(): Scheduler;
 export type { CommandEvent, CommandGroup, CommandItem, CommandMachine, CommandMachineOptions, CommandState, CommandTelemetryHooks, FrecencyData, FrecencyDecayConfig, FrecencyOptions, FrecencyRecord, FrecencyStorage, GroupId, ItemId, ParsedShortcut, Scheduler, ScorerFn, SearchEngine, SearchResult, TelemetryMiddleware };