modern-cmdk 1.2.3 → 1.3.0

package/README.md

@@ -9,18 +9,19 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/modern-cmdk"><img alt="npm version" src="https://img.shields.io/npm/v/modern-cmdk?style=flat-square&color=dc2626&labelColor=0a0e27"/></a>
-  <a href="https://bundlephobia.com/package/modern-cmdk"><img alt="bundle size" src="https://img.shields.io/bundlephobia/minzip/modern-cmdk?style=flat-square&color=dc2626&labelColor=0a0e27&label=core"/></a>
+  <a href="https://github.com/ABCrimson/modern-cmdk/blob/main/package.json"><img alt="core size budget" src="https://img.shields.io/badge/core-%3C%206.5%20kB%20gzip-dc2626?style=flat-square&labelColor=0a0e27"/></a>
+  <a href="https://github.com/ABCrimson/modern-cmdk/blob/main/package.json"><img alt="react size budget" src="https://img.shields.io/badge/react-%3C%2012%20kB%20gzip-dc2626?style=flat-square&labelColor=0a0e27"/></a>
   <a href="https://github.com/ABCrimson/modern-cmdk/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/ABCrimson/modern-cmdk/ci.yml?style=flat-square&color=dc2626&labelColor=0a0e27&label=CI"/></a>
-  <a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-7.0-dc2626?style=flat-square&labelColor=0a0e27"/></a>
+  <a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-7-dc2626?style=flat-square&labelColor=0a0e27"/></a>
   <a href="https://react.dev/"><img alt="React" src="https://img.shields.io/badge/React-19-dc2626?style=flat-square&labelColor=0a0e27"/></a>
   <a href="https://github.com/ABCrimson/modern-cmdk/blob/main/LICENSE"><img alt="MIT License" src="https://img.shields.io/npm/l/modern-cmdk?style=flat-square&color=dc2626&labelColor=0a0e27"/></a>
 </p>
 
 <p align="center">
-  <a href="https://command.crimson.dev">Documentation</a> &middot;
-  <a href="https://command.crimson.dev/guide/getting-started">Getting Started</a> &middot;
-  <a href="https://command.crimson.dev/api/command">API Reference</a> &middot;
-  <a href="https://command.crimson.dev/examples/basic">Examples</a>
+  <a href="https://abcrimson.github.io/modern-cmdk/">Documentation</a> &middot;
+  <a href="https://abcrimson.github.io/modern-cmdk/guide/getting-started.html">Getting Started</a> &middot;
+  <a href="https://abcrimson.github.io/modern-cmdk/api/command.html">API Reference</a> &middot;
+  <a href="https://abcrimson.github.io/modern-cmdk/examples/basic.html">Examples</a>
 </p>
 
 ---
@@ -33,7 +34,8 @@ npm install modern-cmdk
 
 > [!NOTE]
 > `modern-cmdk` is ESM-only and declares `engines.node >= 26.4.0`. The optional WASM search
-> engine (`modern-cmdk-search-wasm`) is experimental and not yet published to npm.
+> engine (`modern-cmdk-search-wasm`) is a private, unpublished workspace package (0.9.0) that you
+> build from source; it is not on npm.
 
 The package exports three entry points:
 
@@ -43,7 +45,11 @@ import { Command } from 'modern-cmdk/react';               // React 19 component
 import 'modern-cmdk/styles.css';                            // Default styles
 ```
 
-React is an **optional** peer dependency — use the core engine standalone in any framework, or pair it with the React adapter for a batteries-included experience.
+React is an **optional** peer dependency — use the core engine standalone in any framework, or pair it with the React adapter. `modern-cmdk/react` imports `react`, `react-dom` and `radix-ui`, which are optional peers that npm and pnpm do not install for you, so add them yourself (the Quick Start below needs all three):
+
+```bash
+npm install modern-cmdk react react-dom radix-ui
+```
 
 ---
 
@@ -54,62 +60,78 @@ React is an **optional** peer dependency — use the core engine standalone in a
 
 import { Command } from 'modern-cmdk/react';
 import 'modern-cmdk/styles.css';
+import { useEffect, useState } from 'react';
 
 function CommandPalette() {
+  const [open, setOpen] = useState(false);
+
+  // Nothing opens the dialog for you: toggle it from a Mod+K listener (Cmd+K / Ctrl+K).
+  useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((o) => !o);
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, []);
+
   return (
-    <Command.Dialog>
+    <Command.Dialog open={open} onOpenChange={setOpen} label="Command Menu">
       <Command.Input placeholder="Type a command..." />
       <Command.List>
         <Command.Empty>No results found.</Command.Empty>
 
         <Command.Group heading="Actions">
-          <Command.Item value="copy" onSelect={() => copyToClipboard()}>
-            <Command.Highlight>Copy to Clipboard</Command.Highlight>
-            <Command.Shortcut>Mod+C</Command.Shortcut>
+          <Command.Item value="copy" onSelect={() => setOpen(false)}>
+            Copy to Clipboard
+            <Command.Shortcut shortcut="Mod+C" />
           </Command.Item>
-          <Command.Item value="paste" onSelect={() => paste()}>
-            <Command.Highlight>Paste</Command.Highlight>
-            <Command.Shortcut>Mod+V</Command.Shortcut>
+          <Command.Item value="paste" onSelect={() => setOpen(false)}>
+            Paste
+            <Command.Shortcut shortcut="Mod+V" />
           </Command.Item>
         </Command.Group>
 
         <Command.Group heading="Navigation">
-          <Command.Item value="settings" onSelect={() => navigate('/settings')}>
+          <Command.Item value="settings" onSelect={() => setOpen(false)}>
             Settings
             <Command.Badge>New</Command.Badge>
           </Command.Item>
         </Command.Group>
       </Command.List>
-      <Command.Loading>Searching...</Command.Loading>
     </Command.Dialog>
   );
 }
 ```
 
-Or scaffold a new project instantly:
+`<Command label="Command menu">` takes the same children inline, with no dialog; `<Command.Highlight text={...} ranges={...} />` renders match highlighting from scorer ranges.
+
+Or scaffold a new project:
 
 ```bash
-npm create modern-cmdk
+npm create modern-cmdk@latest my-palette -- --template=react-basic
 ```
 
 ---
 
 ## Why modern-cmdk?
 
-A ground-up rewrite of `cmdk` for **React 19**, **ES2026**, and **TypeScript 7**. Framework-agnostic core. Zero compromise on performance, accessibility, or developer experience.
+A ground-up rewrite of `cmdk` for **React 19** and **TypeScript 7**, written in modern ECMAScript. Framework-agnostic core. Zero compromise on performance, accessibility, or developer experience.
 
 | | cmdk | modern-cmdk |
 |---|---|---|
 | **Architecture** | React-only, tightly coupled | Framework-agnostic core + thin adapters |
-| **React** | 18 | 19 (`use()`, `useOptimistic`, `useId`, `ref` as prop) |
-| **Search** | Basic substring | Fuzzy scoring + optional WASM (sub-1ms on 100K items) |
-| **Ranking** | Static order | Frecency with time-based exponential decay |
+| **React** | 18 / 19 | 19 (`use()`, `useOptimistic`, `useId`, `ref` as prop) |
+| **Search** | Fuzzy (`command-score`) | Fuzzy scoring with match ranges; an experimental WASM engine (unpublished, does not work yet) |
+| **Ranking** | Static order | Frecency: frequency x bucketed recency weights |
 | **Virtualization** | None | Automatic variable-height, `content-visibility: auto` |
 | **Animations** | CSS transitions | GPU-composited: `@starting-style`, `scroll-timeline`, spring easing |
 | **Keyboard** | External | Built-in registry, `Mod` key, conflict detection |
 | **Accessibility** | Partial ARIA | Full WAI-ARIA combobox, `forced-colors`, `prefers-contrast` |
-| **Bundle** | ~6 KB | Core ~6.4 KB, React ~9.8 KB |
-| **TypeScript** | 4.x/5.x | 7.0, isolated declarations, branded types |
+| **Bundle** | not compared | Core ~6.4 kB, React ~9.8 kB gzip (budgets: < 6.5 kB, < 12 kB) |
+| **TypeScript** | 4.x/5.x | 7, isolated declarations, branded types |
 | **Cleanup** | Manual | `using`/`await using` (Explicit Resource Management) |
 | **Error handling** | None | `CommandErrorBoundary` with fallback UI |
 | **DevTools** | None | Built-in devtools hook for browser inspection |
@@ -118,12 +140,12 @@ A ground-up rewrite of `cmdk` for **React 19**, **ES2026**, and **TypeScript 7**
 
 ## Features
 
-- **Framework-agnostic core** -- Pure TypeScript state machine. No DOM. No React. Portable to any runtime. The sole runtime dependency (`idb-keyval`) is lazy-loaded only if you opt into IndexedDB frecency persistence.
-- **React 19 adapter** -- 14 compound components. `useSyncExternalStore`, `useTransition`, `useOptimistic`, `use()` for Suspense. React Compiler compatible.
-- **Automatic virtualization** -- Variable-height virtual scrolling kicks in at a configurable threshold (`virtualizeThreshold`, default 100). Handles 100K+ items smoothly with `content-visibility: auto`.
-- **Fuzzy search** -- Built-in TypeScript scorer with incremental filtering. Optional Rust/WASM engine for sub-1ms on 100K items with graceful TS fallback _(experimental, not yet published to npm)_.
-- **Frecency ranking** -- Frequency x recency with time-based exponential decay. Pluggable persistence (memory or IndexedDB).
-- **Keyboard shortcuts** -- Built-in registry with cross-platform `Mod` key, conflict detection, and `RegExp.escape` parsing. Cross-browser helper functions for grouping and set operations.
+- **Framework-agnostic core** -- Pure TypeScript state machine. No React. No hard DOM dependency; DOM APIs are feature-detected and SSR-safe. Portable to any runtime. The sole runtime dependency (`idb-keyval`) is lazy-loaded only if you opt into IndexedDB frecency persistence.
+- **React 19 adapter** -- a `Command` root with 14 compound sub-components (`Command.Input` through `Command.Activity`). `useSyncExternalStore`, `useTransition`, `useOptimistic`, `use()` for Suspense. React Compiler compatible.
+- **Automatic virtualization** -- Variable-height virtual scrolling turns on when more than 100 items match and off again at 50 or fewer (fixed thresholds; force it with `<Command.List virtualize>`). Off-screen items use `content-visibility: auto`. The `virtualizeThreshold` option is accepted but not read yet.
+- **Fuzzy search** -- Built-in TypeScript scorer with incremental filtering. Experimental Rust/WASM engine _(private, not published to npm)_; it does not work yet and always falls back to the TS scorer.
+- **Frecency ranking** -- Frequency x recency, weighted by hour/day/week/month buckets. Pluggable persistence (memory or IndexedDB).
+- **Keyboard shortcuts** -- Built-in registry with cross-platform `Mod` key, and conflict detection. Cross-browser helper functions for grouping and set operations.
 - **Full accessibility** -- WAI-ARIA combobox pattern, `aria-live` announcements, `forced-colors`, `prefers-contrast`, `prefers-reduced-motion`.
 - **GPU-composited animations** -- `@starting-style` entry, `scroll-timeline` progress, spring `linear()` easing. All customizable via CSS custom properties.
 - **Error boundary** -- `CommandErrorBoundary` with static or render-function fallback.
@@ -140,10 +162,10 @@ A ground-up rewrite of `cmdk` for **React 19**, **ES2026**, and **TypeScript 7**
   <Command.Input />      {/* Search input */}
   <Command.List>         {/* Scrollable list with auto-virtualization */}
     <Command.Empty />    {/* Shown when filteredCount === 0 */}
-    <Command.Loading />  {/* Shown when loading */}
+    <Command.Loading />  {/* renders when the `loading` prop is true (or while the active-item transition is pending) */}
     <Command.Group>      {/* Labeled group of items */}
       <Command.Item>     {/* Selectable item */}
-        <Command.Highlight />   {/* Fuzzy match highlighting */}
+        <Command.Highlight text={label} ranges={ranges} />   {/* Fuzzy match highlighting */}
         <Command.Badge />       {/* Status badge */}
         <Command.Shortcut />    {/* Keyboard shortcut display */}
       </Command.Item>
@@ -189,16 +211,17 @@ machine.subscribe(() => {
 
 ## Performance
 
-| Benchmark | Target | Measured |
+| Benchmark | Target | Measured (CI runner) |
 |---|---|---|
-| Search 10K items (TS scorer) | < 16 ms | ~8.2 ms |
-| Search 100K items (WASM) | < 1 ms | ~0.7 ms |
-| Filter 10K (incremental) | < 2 ms | ~1.1 ms |
-| State update cycle | < 4 ms | ~2.3 ms |
+| Search 10K items (TS scorer) | < 16 ms | ~3.5 ms median |
+| State update: `SEARCH_CHANGE` | < 4 ms | ~0.37 ms median |
+| State update: `NAVIGATE` | < 1 ms | ~0.00075 ms median |
 | Core bundle (gzipped) | <= 6.5 KB | ~6.4 KB |
 | React bundle (gzipped) | <= 12 KB | ~9.8 KB |
 
-CI enforces 5% warning / 15% failure regression thresholds with 3-run averaging.
+Timings are medians from `benchmarks/baseline.json`: one CI run of the standalone harness, three runs of 1,000 iterations averaged, measured on a shared GitHub Actions
+runner (noise is +/-20-40 %). CI compares new runs against that baseline with 5 % warning / 15 % failure
+thresholds as a coarse tripwire, not a precise regression gate; the `NAVIGATE` baseline sits below the 0.01 ms noise floor and is reported, not compared, and a median above its target fails. There is no published WASM benchmark.
 
 ---
 
@@ -216,37 +239,69 @@ All animations and dimensions are customizable via CSS custom properties:
   --command-dialog-max-width: 640px;
   --command-item-height: 44px;
   --command-highlight-color: oklch(0.85 0.15 90 / 0.3);
+  --command-muted-color: light-dark(oklch(0.45 0.015 260), oklch(0.75 0.015 260));
 }
 ```
 
+`--command-muted-color` colours secondary text (group headings, shortcuts, the empty state, the
+placeholder). Its default uses `light-dark()`, which follows the used `color-scheme`: set
+`color-scheme` on `:root` or a parent (for example `color-scheme: dark` on a dark theme), or override
+`--command-muted-color`. A dark-themed page that sets no `color-scheme` gets the light value on its dark
+surface (about 2.4:1 contrast).
+
 All styles use `@layer command` for zero-specificity conflicts and CSS logical properties for full RTL support.
 
 ---
 
 ## Migration from cmdk
 
-Automated codemods handle the most common migration patterns:
+Four codemods ship as the `modern-cmdk` bin. Pass a transform name and a glob (quote the glob so your
+shell does not expand it):
 
 ```bash
-npx modern-cmdk import-rewrite ./src
-npx modern-cmdk data-attrs ./src
-npx modern-cmdk forward-ref ./src
-npx modern-cmdk should-filter ./src
+npx modern-cmdk --help
+npx modern-cmdk import-rewrite "./src/**/*.tsx" --dry-run
+npx modern-cmdk import-rewrite "./src/**/*.tsx"
 ```
 
-See the [full migration guide](https://command.crimson.dev/guide/migration-from-cmdk).
+| Transform | What it does |
+|---|---|
+| `import-rewrite` | Rewrites `cmdk` imports to `modern-cmdk/react` |
+| `data-attrs` | Converts `[cmdk-*]` selectors to `[data-command-*]` |
+| `forward-ref` | Removes `React.forwardRef` wrappers (React 19) |
+| `should-filter` | Converts the `shouldFilter` prop to `filter` |
+
+Options: `--dry-run` lists the files that would change and writes nothing; `--concurrency=N` sets how
+many files are processed at once (default 8); `--strict` is described below.
+
+A run prints one `changed <file>` line per rewritten file and a summary. With `--dry-run` the lines read
+`would change <file>` and the summary ends in `(dry run, nothing written)`:
+
+```text
+would change src/a.tsx
+1 changed, 0 unchanged, 0 errors (dry run, nothing written)
+```
+
+Exit codes in 1.x are unchanged by default: `0` for `--help`, missing arguments and per-file errors, and
+`1` for an unknown transform, a glob that matches no files, or an uncaught error. An unknown option is
+warned about on stderr and ignored when the transform and glob are present. A malformed known option
+(`--concurrency` with no value, `--dry-run=yes`) is a usage error that writes nothing and exits `0`.
+With `--strict`, every usage error (including an unknown option, an unknown transform and a malformed
+option) exits `2`, and any file error exits `1`.
+
+See the [full migration guide](https://abcrimson.github.io/modern-cmdk/guide/migration-from-cmdk.html).
 
 ---
 
 ## Documentation
 
-**[command.crimson.dev](https://command.crimson.dev)**
+**[abcrimson.github.io/modern-cmdk](https://abcrimson.github.io/modern-cmdk/)**
 
-**Guides:** [Getting Started](https://command.crimson.dev/guide/getting-started) | [Installation](https://command.crimson.dev/guide/installation) | [Basic Usage](https://command.crimson.dev/guide/basic-usage) | [Async Items](https://command.crimson.dev/guide/async-items) | [WASM Search](https://command.crimson.dev/guide/wasm-search) | [Frecency](https://command.crimson.dev/guide/frecency) | [Shortcuts](https://command.crimson.dev/guide/shortcuts) | [Virtualization](https://command.crimson.dev/guide/virtualization) | [SSR / Next.js](https://command.crimson.dev/guide/ssr) | [Theming](https://command.crimson.dev/guide/theming) | [Accessibility](https://command.crimson.dev/guide/accessibility)
+**Guides:** [Getting Started](https://abcrimson.github.io/modern-cmdk/guide/getting-started.html) | [Installation](https://abcrimson.github.io/modern-cmdk/guide/installation.html) | [Basic Usage](https://abcrimson.github.io/modern-cmdk/guide/basic-usage.html) | [Async Items](https://abcrimson.github.io/modern-cmdk/guide/async-items.html) | [WASM Search](https://abcrimson.github.io/modern-cmdk/guide/wasm-search.html) | [Frecency](https://abcrimson.github.io/modern-cmdk/guide/frecency.html) | [Shortcuts](https://abcrimson.github.io/modern-cmdk/guide/shortcuts.html) | [Virtualization](https://abcrimson.github.io/modern-cmdk/guide/virtualization.html) | [SSR / Next.js](https://abcrimson.github.io/modern-cmdk/guide/ssr.html) | [Theming](https://abcrimson.github.io/modern-cmdk/guide/theming.html) | [Accessibility](https://abcrimson.github.io/modern-cmdk/guide/accessibility.html)
 
-**Recipes:** [File Picker](https://command.crimson.dev/recipes/file-picker) | [Emoji Picker](https://command.crimson.dev/recipes/emoji-picker) | [AI Chat Commands](https://command.crimson.dev/recipes/ai-chat-commands) | [Nested Commands](https://command.crimson.dev/recipes/nested-commands) | [Spotlight Search](https://command.crimson.dev/recipes/spotlight-search)
+**Recipes:** [File Picker](https://abcrimson.github.io/modern-cmdk/recipes/file-picker.html) | [Emoji Picker](https://abcrimson.github.io/modern-cmdk/recipes/emoji-picker.html) | [AI Chat Commands](https://abcrimson.github.io/modern-cmdk/recipes/ai-chat-commands.html) | [Nested Commands](https://abcrimson.github.io/modern-cmdk/recipes/nested-commands.html) | [Spotlight Search](https://abcrimson.github.io/modern-cmdk/recipes/spotlight-search.html)
 
-**API:** [Core Engine](https://command.crimson.dev/api/command) | [React Adapter](https://command.crimson.dev/api/command-react) | [WASM Search](https://command.crimson.dev/api/command-search-wasm)
+**API:** [Core Engine](https://abcrimson.github.io/modern-cmdk/api/command.html) | [React Adapter](https://abcrimson.github.io/modern-cmdk/api/command-react.html) | [WASM Search](https://abcrimson.github.io/modern-cmdk/api/command-search-wasm.html)
 
 ---
 
@@ -254,9 +309,9 @@ See the [full migration guide](https://command.crimson.dev/guide/migration-from-
 
 | Package | Description |
 |---|---|
-| [`create-modern-cmdk`](https://www.npmjs.com/package/create-modern-cmdk) | `npm create modern-cmdk` -- scaffold a new project |
-| `modern-cmdk-search-wasm` _(experimental, not yet published)_ | Rust/WASM fuzzy search -- sub-1ms on 100K items |
-| [`vscode-modern-cmdk`](https://marketplace.visualstudio.com/items?itemName=crimson-dev.vscode-modern-cmdk) | VS Code snippets extension |
+| [`create-modern-cmdk`](https://www.npmjs.com/package/create-modern-cmdk) | `npm create modern-cmdk@latest <name>` -- scaffold a new project |
+| `modern-cmdk-search-wasm` _(private 0.9.0, not published; build from source)_ | Experimental Rust/WASM fuzzy search |
+| `vscode-modern-cmdk` _(not yet published)_ | VS Code snippets extension |
 
 ---
 

package/dist/codemod/cli.d.mts

@@ -1 +1,16 @@
-export {}
+import { API, FileInfo } from "jscodeshift";
+type TransformFn = (fileInfo: FileInfo, api: API) => string;
+/** The two streams the CLI writes to; `process` satisfies this, tests pass collectors. */
+export interface CliIo {
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+}
+/** Test seam: replace how a transform is loaded (the bundled bin imports `./transforms/<name>.mjs`). */
+export interface CliDeps {
+  readonly loadTransform?: (name: string) => Promise<TransformFn>;
+}
+/**
+ * Run the codemod CLI. Resolves to the process exit code; writes only to `io`.
+ */
+export declare function run(argv: readonly string[], io: CliIo, deps?: CliDeps): Promise<number>;
+export {};

package/dist/codemod/cli.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import fsPromises, { readFile, writeFile } from "node:fs/promises";
-import path, { resolve } from "node:path";
+import path, { relative } from "node:path";
+import { parseArgs, promisify, styleText } from "node:util";
 import process$1 from "node:process";
 import fs from "node:fs";
 import "node:stream";
 import "node:events";
 import "node:stream/promises";
-import { promisify } from "node:util";
 import { execFile } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import os from "node:os";
@@ -43584,7 +43584,7 @@ var require_core = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	}
 	module.exports = enrichCore(core, getParser());
 }));
-// src/core/utils/group-by.ts
+// src/codemod/cli.ts
 var import_jscodeshift = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	/**
 	* Copyright (c) Facebook, Inc. and its affiliates.
@@ -43594,21 +43594,6 @@ var import_jscodeshift = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(
 	*/
 	module.exports = require_core();
 })))(), 1);
-/**
-* Groups items from an iterable into a plain object keyed by the string result of `keyFn`.
-* Cross-browser replacement for `Object.groupBy()`.
-*/
-function objectGroupBy(items, keyFn) {
-	const result = Object.create(null);
-	for (const item of items) {
-		const key = keyFn(item);
-		const existing = result[key];
-		if (existing) existing.push(item);
-		else result[key] = [item];
-	}
-	return result;
-}
-// src/codemod/cli.ts
 const AVAILABLE_TRANSFORMS = /* @__PURE__ */ new Map([
 	["import-rewrite", "Rewrites cmdk imports to modern-cmdk/react"],
 	["data-attrs", "Converts [cmdk-*] selectors to [data-command-*]"],
@@ -43619,102 +43604,200 @@ const AVAILABLE_TRANSFORMS = /* @__PURE__ */ new Map([
 * Dynamically import a transform module by name and return its default export.
 */
 async function loadTransform(name) {
-	return (await import(`./transforms/${name}.mjs`)).default;
+	return (await import(
+		/* @vite-ignore */
+		`./transforms/${name}.mjs`
+)).default;
 }
-function printUsage() {
-	AVAILABLE_TRANSFORMS.entries().forEach(([_name, _description]) => {});
+function usageText(stream) {
+	const bold = (s) => styleText("bold", s, { stream });
+	const opt = (s) => styleText("cyan", s.padEnd(17), { stream });
+	return [
+		`${bold("Usage:")} modern-cmdk <transform> <glob> [options]`,
+		"",
+		bold("Transforms:"),
+		...AVAILABLE_TRANSFORMS.entries().map(([name, description]) => `  ${opt(name)}${description}`).toArray(),
+		"",
+		bold("Options:"),
+		`  ${opt("--dry-run")}List the files that would change; write nothing`,
+		`  ${opt("--strict")}Exit 2 on usage errors (incl. unknown options), 1 on file errors`,
+		`  ${opt("--concurrency=N")}Files processed at once (default 8)`,
+		`  ${opt("-h, --help")}Show this help`,
+		""
+	].join("\n");
 }
-function parseArgs(argv) {
-	const args = argv.slice(2);
-	const flags = args.values().filter((a) => a.startsWith("--")).toArray();
-	const positional = args.values().filter((a) => !a.startsWith("--")).toArray();
-	if (positional.length < 2) return null;
-	const transformName = positional[0];
-	const fileGlob = positional[1];
-	const dryRun = flags.some((f) => f === "--dry-run");
-	const concurrencyFlag = flags.values().find((f) => f.startsWith("--concurrency="));
+const OPTIONS = {
+	help: {
+		type: "boolean",
+		short: "h"
+	},
+	strict: { type: "boolean" },
+	"dry-run": { type: "boolean" },
+	concurrency: { type: "string" }
+};
+function parse(argv) {
+	let values;
+	let positionals;
+	let ignored = [];
+	try {
+		({values, positionals} = parseCli(argv));
+	} catch (err) {
+		const strictArg = argv.includes("--strict");
+		if (err.code !== "ERR_PARSE_ARGS_UNKNOWN_OPTION") return {
+			kind: "usage-error",
+			message: err instanceof Error ? err.message : String(err),
+			strict: strictArg
+		};
+		const loose = parseArgs({
+			args: [...argv],
+			options: OPTIONS,
+			allowPositionals: true,
+			strict: false,
+			tokens: true
+		});
+		ignored = loose.tokens.filter((t) => t.kind === "option" && !Object.hasOwn(OPTIONS, t.name)).map((t) => t.rawName);
+		const badValue = loose.tokens.find((t) => t.kind === "option" && Object.hasOwn(OPTIONS, t.name) && (OPTIONS[t.name].type === "boolean" ? t.value !== void 0 : t.value === void 0 || !t.inlineValue && t.value.length > 1 && t.value.startsWith("-")));
+		const badMessage = badValue?.kind === "option" ? badValue.value === void 0 ? `Option '${badValue.rawName} <value>' argument missing` : OPTIONS[badValue.name].type === "boolean" ? `Option '${badValue.rawName}' does not take an argument` : `Option '${badValue.rawName}' argument is ambiguous.\nDid you forget to specify the option argument for '${badValue.rawName}'?\nTo specify an option argument starting with a dash use '${badValue.rawName}=-XYZ'.` : void 0;
+		if (badMessage !== void 0) return {
+			kind: "usage-error",
+			message: badMessage,
+			strict: strictArg
+		};
+		if (strictArg || loose.values.help === true || loose.positionals.length < 2) return {
+			kind: "usage-error",
+			message: `unknown option ${ignored[0]}`,
+			strict: strictArg
+		};
+		values = loose.values;
+		positionals = loose.positionals;
+	}
+	const strict = values.strict === true;
+	if (values.help) return { kind: "help" };
+	if (positionals.length < 2) return {
+		kind: "usage-error",
+		message: void 0,
+		strict
+	};
+	let concurrency = 8;
+	if (values.concurrency !== void 0) {
+		if (typeof values.concurrency !== "string" || !/^[1-9]\d*$/.test(values.concurrency)) return {
+			kind: "usage-error",
+			message: `--concurrency must be a positive integer, got "${String(values.concurrency)}"`,
+			strict
+		};
+		concurrency = Number.parseInt(values.concurrency, 10);
+	}
 	return {
-		transformName,
-		fileGlob,
-		dryRun,
-		concurrency: concurrencyFlag ? Number.parseInt(concurrencyFlag.split("=")[1], 10) : 8
+		kind: "run",
+		transformName: positionals[0],
+		fileGlob: positionals[1],
+		dryRun: values["dry-run"] === true,
+		strict,
+		concurrency,
+		ignored
 	};
 }
+function parseCli(argv) {
+	return parseArgs({
+		args: [...argv],
+		options: OPTIONS,
+		allowPositionals: true,
+		strict: true
+	});
+}
 async function* chunked(items, size) {
 	for (let i = 0; i < items.length; i += size) yield items.slice(i, i + size);
 }
 async function processFile(filePath, transformFn, apiForParser, dryRun) {
-	const source = await readFile(filePath, "utf-8");
-	const parser = filePath.endsWith(".tsx") || filePath.endsWith(".jsx") ? "tsx" : "ts";
-	const result = transformFn({
-		path: filePath,
-		source
-	}, apiForParser(parser));
-	if (result !== source) {
-		if (!dryRun) await writeFile(filePath, result, "utf-8");
+	try {
+		const source = await readFile(filePath, "utf-8");
+		const parser = filePath.endsWith(".tsx") || filePath.endsWith(".jsx") ? "tsx" : "ts";
+		const result = transformFn({
+			path: filePath,
+			source
+		}, apiForParser(parser));
+		if (result !== source) {
+			if (!dryRun) await writeFile(filePath, result, "utf-8");
+			return {
+				filePath,
+				changed: true
+			};
+		}
+		return {
+			filePath,
+			changed: false
+		};
+	} catch (err) {
 		return {
 			filePath,
-			changed: true
+			changed: false,
+			error: err instanceof Error ? err : new Error(String(err))
 		};
 	}
-	return {
-		filePath,
-		changed: false
-	};
 }
-async function main() {
-	const cliArgs = parseArgs(process.argv);
-	if (!cliArgs) {
-		printUsage();
-		process.exit(0);
-	}
-	const { transformName, fileGlob, dryRun, concurrency } = cliArgs;
-	if (!AVAILABLE_TRANSFORMS.has(transformName)) process.exit(1);
-	const files = await globby([fileGlob], {
-		absolute: true,
-		ignore: [
-			"**/node_modules/**",
-			"**/dist/**",
-			"**/build/**",
-			"**/.next/**"
-		]
-	});
-	if (files.length === 0) process.exit(1);
-	const transformFn = await loadTransform(transformName);
-	const apiForParser = (parser) => ({
-		jscodeshift: import_jscodeshift.default.withParser(parser),
-		j: import_jscodeshift.default.withParser(parser),
-		stats: () => {},
-		report: () => {}
-	});
-	let resolveDone;
-	const done = new Promise((r) => {
-		resolveDone = r;
-	});
-	const allResults = [];
-	for await (const batch of chunked(files, concurrency)) (await Promise.allSettled(batch.map((filePath) => processFile(filePath, transformFn, apiForParser, dryRun)))).values().forEach((result) => {
-		if (result.status === "fulfilled") allResults.push(result.value);
-		else allResults.push({
-			filePath: "(unknown)",
-			changed: false,
-			error: result.reason
+/**
+* Run the codemod CLI. Resolves to the process exit code; writes only to `io`.
+*/
+async function run(argv, io, deps = {}) {
+	const out = (s) => void io.stdout.write(`${s}\n`);
+	const err = (s) => void io.stderr.write(`${s}\n`);
+	const fail = (s) => err(`${styleText("red", "error:", { stream: io.stderr })} ${s}`);
+	try {
+		const parsed = parse(argv);
+		if (parsed.kind === "help") {
+			out(usageText(io.stdout));
+			return 0;
+		}
+		if (parsed.kind === "usage-error") {
+			if (parsed.message !== void 0) fail(parsed.message);
+			err(usageText(io.stderr));
+			return parsed.strict ? 2 : 0;
+		}
+		const { transformName, fileGlob, dryRun, strict, concurrency, ignored } = parsed;
+		for (const name of ignored) err(`warning: unknown option ${name} ignored (--strict makes this exit 2)`);
+		if (!AVAILABLE_TRANSFORMS.has(transformName)) {
+			fail(`unknown transform "${transformName}". Valid transforms: ${[...AVAILABLE_TRANSFORMS.keys()].join(", ")}`);
+			return strict ? 2 : 1;
+		}
+		const files = await globby([fileGlob], {
+			absolute: true,
+			ignore: [
+				"**/node_modules/**",
+				"**/dist/**",
+				"**/build/**",
+				"**/.next/**"
+			]
 		});
-	});
-	resolveDone(allResults);
-	const grouped = objectGroupBy(await done, (r) => {
-		if (r.error) return "errors";
-		if (r.changed) return "changed";
-		return "unchanged";
-	});
-	const changedFiles = grouped.changed ?? [];
-	const errorFiles = grouped.errors ?? [];
-	changedFiles.values().forEach((r) => {
-		r.filePath.replace(`${resolve(".")}/`, "");
-	});
-	if (errorFiles.length > 0) errorFiles.values().forEach((_r) => {});
-	if (dryRun && changedFiles.length > 0) {}
+		if (files.length === 0) {
+			fail(`no files matched "${fileGlob}"`);
+			return 1;
+		}
+		const transformFn = await (deps.loadTransform ?? loadTransform)(transformName);
+		const apiForParser = (parser) => ({
+			jscodeshift: import_jscodeshift.default.withParser(parser),
+			j: import_jscodeshift.default.withParser(parser),
+			stats: () => {},
+			report: () => {}
+		});
+		const results = [];
+		for await (const batch of chunked(files, concurrency)) results.push(...await Promise.all(batch.map((filePath) => processFile(filePath, transformFn, apiForParser, dryRun))));
+		const rel = (p) => relative(process.cwd(), p).replaceAll("\\", "/");
+		let changed = 0;
+		let errors = 0;
+		for (const r of results) if (r.error) {
+			errors++;
+			err(`${rel(r.filePath)}: ${r.error.message}`);
+		} else if (r.changed) {
+			changed++;
+			out(`${styleText("green", dryRun ? "would change" : "changed", { stream: io.stdout })} ${rel(r.filePath)}`);
+		}
+		const unchanged = results.length - changed - errors;
+		out(`${changed} changed, ${unchanged} unchanged, ${errors} errors${dryRun ? " (dry run, nothing written)" : ""}`);
+		return strict && errors > 0 ? 1 : 0;
+	} catch (e) {
+		fail(e instanceof Error ? e.message : String(e));
+		return 1;
+	}
 }
-main().catch((_err) => {
-	process.exit(1);
-});
-export {};
+if (import.meta.main) process.exitCode = await run(process.argv.slice(2), process);
+export { run };

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

@@ -14,7 +14,7 @@ const ATTR_MAP = /* @__PURE__ */ new Map([
 const CSS_VAR_MAP = /* @__PURE__ */ new Map([["--cmdk-list-height", "--command-list-height"]]);
 /**
 * Replace all cmdk attribute selectors (bracketed) and CSS vars in a string.
-* Uses ES2026 Set.union to combine both maps into a single pass.
+* Runs replaceAll for each ATTR_MAP entry (bracketed selectors), then for each CSS_VAR_MAP entry.
 */
 function replaceInString(input) {
 	let result = input;

package/dist/core/index.d.mts

@@ -2,7 +2,7 @@
 interface SearchResult {
   readonly id: ItemId;
   readonly score: number;
-  /** Character ranges that matched (for highlighting) — [start, end] tuples */
+  /** Character ranges that matched (for highlighting) — half-open [start, end) tuples, end exclusive */
   readonly matches: ReadonlyArray<readonly [start: number, end: number]>;
 }
 /** A scoring function that evaluates a single item against a query */
@@ -13,7 +13,7 @@ interface SearchEngine extends Disposable {
   index(items: readonly CommandItem[]): void;
   /** Search items by query, return ordered results — uses Iterator pipeline */
   search(query: string, items: readonly CommandItem[]): IteratorObject<SearchResult>;
-  /** Remove items from index — uses Set.difference for efficient bulk removal */
+  /** Remove items from index by id */
   remove(ids: ReadonlySet<ItemId>): void;
   /** Clear the entire index */
   clear(): void;
@@ -162,7 +162,7 @@ interface FrecencyStorage extends Disposable {
   load(namespace: string): FrecencyData | Promise<FrecencyData>;
   save(namespace: string, data: FrecencyData): void | Promise<void>;
 }
-/** Frecency exponential decay bucket configuration */
+/** Frecency step-weight configuration per recency bucket (hour/day/week/month/older) */
 interface FrecencyDecayConfig {
   readonly hourWeight?: number | undefined;
   readonly dayWeight?: number | undefined;
@@ -179,7 +179,7 @@ interface FrecencyOptions {
 }
 /** Default frecency decay configuration */
 export declare const DEFAULT_FRECENCY_DECAY: Required<FrecencyDecayConfig>;
-/** Options for creating a command machine — const type param for narrowed option inference */
+/** Options for creating a command machine */
 interface CommandMachineOptions {
   /** Pre-registered items to populate on creation */
   readonly items?: readonly CommandItem[] | undefined;
@@ -205,7 +205,7 @@ interface CommandMachineOptions {
   readonly onSearchChange?: ((query: string) => void) | undefined;
   /** Whether keyboard navigation loops from last to first item (default: true) */
   readonly loop?: boolean | undefined;
-  /** Item count threshold for automatic virtualization (default: 100) */
+  /** 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 */
@@ -213,7 +213,7 @@ 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 6.2.2.
+ * IndexedDB-backed frecency storage using idb-keyval.
  *
  * Persists frecency data across browser sessions. Implements both
  * `Disposable` and `AsyncDisposable` for use with `using` and `await using`.
@@ -250,7 +250,7 @@ export declare class IdbFrecencyStorage implements FrecencyStorage, AsyncDisposa
 /**
  * Computes a frecency bonus for an item based on usage frequency and recency.
  * Uses hour/day/week/month bucket boundaries with
- * configurable exponential decay weights per time bucket.
+ * configurable step weights per recency bucket (hour/day/week/month/older).
  */
 export declare function computeFrecencyBonus(history: FrecencyRecord, now?: number, config?: FrecencyDecayConfig): number;
 /**
@@ -290,7 +290,7 @@ export declare class MemoryFrecencyStorage implements FrecencyStorage {
   #private;
   load(namespace: string): FrecencyData;
   save(namespace: string, data: FrecencyData): void;
-  /** Serialize all stored data — Iterator Helpers pipeline (ES2026) */
+  /** Serialize all stored data — Iterator Helpers pipeline (ES2025) */
   toJSON(): Record<string, {
     records: Array<[string, FrecencyRecord]>;
   }>;
@@ -340,7 +340,7 @@ 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 via Map.groupBy (ES2026).
+ * global document listener. Detects conflicts with the local mapGroupBy helper (core/utils/group-by.ts).
  */
 export declare class KeyboardShortcutRegistry implements Disposable {
   #private;
@@ -466,7 +466,7 @@ interface SearchEngineOptions {
  * 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.
- * Uses Iterator Helpers (ES2026) for result pipelines and Set.difference for pruning.
+ * Uses Iterator Helpers (ES2025) for result pipelines.
  */
 export declare function createSearchEngine(options?: SearchEngineOptions): SearchEngine;
 interface CommandTelemetryHooks {

package/dist/core/index.mjs

@@ -44,7 +44,7 @@ function storageKey(namespace) {
 }
 let idbModule;
 /**
-* IndexedDB-backed frecency storage using idb-keyval 6.2.2.
+* IndexedDB-backed frecency storage using idb-keyval.
 *
 * Persists frecency data across browser sessions. Implements both
 * `Disposable` and `AsyncDisposable` for use with `using` and `await using`.
@@ -170,7 +170,7 @@ var MemoryFrecencyStorage = class {
 	save(namespace, data) {
 		this.#store.set(namespace, data);
 	}
-	/** Serialize all stored data — Iterator Helpers pipeline (ES2026) */
+	/** Serialize all stored data — Iterator Helpers pipeline (ES2025) */
 	toJSON() {
 		return Object.fromEntries(this.#store.entries().map(([namespace, data]) => [namespace, { records: data.records.entries().toArray() }]));
 	}
@@ -181,7 +181,7 @@ var MemoryFrecencyStorage = class {
 // src/core/frecency/index.ts
 /** Shared empty bonus map — avoids allocation when no frecency records exist */
 const EMPTY_BONUS_MAP = /* @__PURE__ */ new Map();
-/** Pre-computed bucket boundaries in hours — avoids Duration.total() per call */
+/** Bucket boundaries as hour constants — no per-call unit conversion */
 const BUCKET_HOURS = {
 	hour: 1,
 	day: 24,
@@ -191,7 +191,7 @@ const BUCKET_HOURS = {
 /**
 * Computes a frecency bonus for an item based on usage frequency and recency.
 * Uses hour/day/week/month bucket boundaries with
-* configurable exponential decay weights per time bucket.
+* configurable step weights per recency bucket (hour/day/week/month/older).
 */
 function computeFrecencyBonus(history, now = Date.now(), config = DEFAULT_FRECENCY_DECAY) {
 	const hours = (now - history.lastUsed) / 36e5;
@@ -397,7 +397,7 @@ function formatShortcut(parsed) {
 /**
 * Manages keyboard shortcut bindings with global keydown listening.
 * Supports `using` for automatic cleanup of both individual bindings and the
-* global document listener. Detects conflicts via Map.groupBy (ES2026).
+* global document listener. Detects conflicts with the local mapGroupBy helper (core/utils/group-by.ts).
 */
 var KeyboardShortcutRegistry = class {
 	#bindings = /* @__PURE__ */ new Map();
@@ -855,7 +855,7 @@ if (isDev && typeof window !== "undefined") leakRegistry = new FinalizationRegis
 * 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.
-* Uses Iterator Helpers (ES2026) for result pipelines and Set.difference for pruning.
+* Uses Iterator Helpers (ES2025) for result pipelines.
 */
 function createSearchEngine(options) {
 	const customScorer = options?.scorer;
@@ -964,9 +964,10 @@ var TypedEmitter = class {
 // src/core/utils/scheduler.ts
 /** Whether we're in a browser environment with rAF available */
 const hasRAF = typeof requestAnimationFrame === "function";
-/** Feature detection for cutting-edge scheduling APIs */
+/** Feature detection for cutting-edge scheduling APIs, read through globalThis: typeof guards only a bare
+* identifier, so `typeof navigator?.scheduling` would throw where navigator is undeclared (runtimes without one). */
 const canYield = typeof globalThis.scheduler?.yield === "function";
-const hasInputPending = typeof navigator?.scheduling?.isInputPending === "function";
+const hasInputPending = typeof globalThis.navigator?.scheduling?.isInputPending === "function";
 /**
 * Creates a batched update scheduler. Coalesces rapid state updates into a single
 * execution pass using rAF (browser) or queueMicrotask (Node.js).

package/dist/react/index.d.mts

@@ -18,7 +18,7 @@ export declare function CommandActivity({ mode, children }: CommandActivityProps
 interface SearchResult {
   readonly id: ItemId;
   readonly score: number;
-  /** Character ranges that matched (for highlighting) — [start, end] tuples */
+  /** Character ranges that matched (for highlighting) — half-open [start, end) tuples, end exclusive */
   readonly matches: ReadonlyArray<readonly [start: number, end: number]>;
 }
 /** Search engine interface — pluggable into the state machine */
@@ -27,7 +27,7 @@ interface SearchEngine extends Disposable {
   index(items: readonly CommandItem$1[]): void;
   /** Search items by query, return ordered results — uses Iterator pipeline */
   search(query: string, items: readonly CommandItem$1[]): IteratorObject<SearchResult>;
-  /** Remove items from index — uses Set.difference for efficient bulk removal */
+  /** Remove items from index by id */
   remove(ids: ReadonlySet<ItemId>): void;
   /** Clear the entire index */
   clear(): void;
@@ -172,7 +172,7 @@ interface FrecencyStorage extends Disposable {
   load(namespace: string): FrecencyData | Promise<FrecencyData>;
   save(namespace: string, data: FrecencyData): void | Promise<void>;
 }
-/** Frecency exponential decay bucket configuration */
+/** Frecency step-weight configuration per recency bucket (hour/day/week/month/older) */
 interface FrecencyDecayConfig {
   readonly hourWeight?: number | undefined;
   readonly dayWeight?: number | undefined;
@@ -187,7 +187,7 @@ interface FrecencyOptions {
   readonly namespace?: string | undefined;
   readonly decayConfig?: FrecencyDecayConfig | undefined;
 }
-/** Options for creating a command machine — const type param for narrowed option inference */
+/** Options for creating a command machine */
 interface CommandMachineOptions {
   /** Pre-registered items to populate on creation */
   readonly items?: readonly CommandItem$1[] | undefined;
@@ -213,7 +213,7 @@ interface CommandMachineOptions {
   readonly onSearchChange?: ((query: string) => void) | undefined;
   /** Whether keyboard navigation loops from last to first item (default: true) */
   readonly loop?: boolean | undefined;
-  /** Item count threshold for automatic virtualization (default: 100) */
+  /** 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;
 }
 /**
@@ -237,7 +237,7 @@ 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 via Map.groupBy (ES2026).
+ * global document listener. Detects conflicts with the local mapGroupBy helper (core/utils/group-by.ts).
  */
 declare class KeyboardShortcutRegistry implements Disposable {
   #private;
@@ -371,7 +371,7 @@ export declare function CommandGroup({ ref, children, heading, priority, forceId
 interface CommandHighlightProps {
   /** The full text to display */
   readonly text: string;
-  /** Match ranges from search scorer — [start, end] tuples */
+  /** Match ranges from the search scorer — half-open [start, end) tuples, end exclusive */
   readonly ranges: ReadonlyArray<readonly [start: number, end: number]>;
   /** Custom className for highlighted segments */
   readonly highlightClassName?: string;
@@ -463,6 +463,7 @@ type CommandRootId = string & {
 interface CommandContextValue {
   readonly machine: CommandMachine;
   readonly state: CommandState;
+  /** True while an optimistic active-item transition is in flight (search updates never set it). */
   readonly isPending: boolean;
   readonly updateSearch: (query: string) => void;
   readonly setOptimisticActiveId: (id: ItemId | null) => void;
@@ -490,6 +491,7 @@ interface CommandStableContextValue {
 /** State context — values that change on every search/navigation */
 interface CommandStateContextValue {
   readonly state: CommandState;
+  /** True while an optimistic active-item transition is in flight (search updates never set it). */
   readonly isPending: boolean;
   readonly filteredIdSet: ReadonlySet<ItemId>;
   /** IDs currently visible in virtual viewport + overscan. null = not virtualizing (render all filtered). */
@@ -520,14 +522,16 @@ export declare class CommandErrorBoundary extends Component<CommandErrorBoundary
 }
 interface UseCommandReturn {
   readonly state: CommandState;
+  /** True while an optimistic active-item transition is in flight. Search updates never set it: the machine applies them on its own scheduler tick, outside React. */
   readonly isPending: boolean;
+  /** Queue a search query on the machine. Not a React update: Command.Input owns the urgent input value. */
   readonly updateSearch: (query: string) => void;
   readonly setOptimisticActiveId: (id: ItemId | null) => void;
   /** O(1) membership set for filtered items — used by Item component */
   readonly filteredIdSet: ReadonlySet<ItemId>;
   readonly id: CommandRootId;
 }
-/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useTransition, and useOptimistic. */
+/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useOptimistic, and a transition for optimistic active-item updates. */
 export declare function useCommand(machine: CommandMachine): UseCommandReturn;
 /** Get the full command state with proper subscription */
 export declare function useCommandState(): CommandState;

package/dist/react/index.mjs

@@ -139,7 +139,7 @@ var MemoryFrecencyStorage = class {
 	save(namespace, data) {
 		this.#store.set(namespace, data);
 	}
-	/** Serialize all stored data — Iterator Helpers pipeline (ES2026) */
+	/** Serialize all stored data — Iterator Helpers pipeline (ES2025) */
 	toJSON() {
 		return Object.fromEntries(this.#store.entries().map(([namespace, data]) => [namespace, { records: data.records.entries().toArray() }]));
 	}
@@ -150,7 +150,7 @@ var MemoryFrecencyStorage = class {
 // src/core/frecency/index.ts
 /** Shared empty bonus map — avoids allocation when no frecency records exist */
 const EMPTY_BONUS_MAP = /* @__PURE__ */ new Map();
-/** Pre-computed bucket boundaries in hours — avoids Duration.total() per call */
+/** Bucket boundaries as hour constants — no per-call unit conversion */
 const BUCKET_HOURS = {
 	hour: 1,
 	day: 24,
@@ -160,7 +160,7 @@ const BUCKET_HOURS = {
 /**
 * Computes a frecency bonus for an item based on usage frequency and recency.
 * Uses hour/day/week/month bucket boundaries with
-* configurable exponential decay weights per time bucket.
+* configurable step weights per recency bucket (hour/day/week/month/older).
 */
 function computeFrecencyBonus(history, now = Date.now(), config = DEFAULT_FRECENCY_DECAY) {
 	const hours = (now - history.lastUsed) / 36e5;
@@ -362,7 +362,7 @@ function formatShortcut(parsed) {
 /**
 * Manages keyboard shortcut bindings with global keydown listening.
 * Supports `using` for automatic cleanup of both individual bindings and the
-* global document listener. Detects conflicts via Map.groupBy (ES2026).
+* global document listener. Detects conflicts with the local mapGroupBy helper (core/utils/group-by.ts).
 */
 var KeyboardShortcutRegistry = class {
 	#bindings = /* @__PURE__ */ new Map();
@@ -780,7 +780,7 @@ if (isDev && typeof window !== "undefined") leakRegistry = new FinalizationRegis
 * 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.
-* Uses Iterator Helpers (ES2026) for result pipelines and Set.difference for pruning.
+* Uses Iterator Helpers (ES2025) for result pipelines.
 */
 function createSearchEngine(options) {
 	const customScorer = options?.scorer;
@@ -889,9 +889,10 @@ var TypedEmitter = class {
 // src/core/utils/scheduler.ts
 /** Whether we're in a browser environment with rAF available */
 const hasRAF = typeof requestAnimationFrame === "function";
-/** Feature detection for cutting-edge scheduling APIs */
+/** Feature detection for cutting-edge scheduling APIs, read through globalThis: typeof guards only a bare
+* identifier, so `typeof navigator?.scheduling` would throw where navigator is undeclared (runtimes without one). */
 const canYield = typeof globalThis.scheduler?.yield === "function";
-const hasInputPending = typeof navigator?.scheduling?.isInputPending === "function";
+const hasInputPending = typeof globalThis.navigator?.scheduling?.isInputPending === "function";
 /**
 * Creates a batched update scheduler. Coalesces rapid state updates into a single
 * execution pass using rAF (browser) or queueMicrotask (Node.js).
@@ -1214,7 +1215,7 @@ function createCommandMachine(options = {}) {
 	};
 }
 // src/react/hooks/use-command.ts
-/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useTransition, and useOptimistic. */
+/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useOptimistic, and a transition for optimistic active-item updates. */
 function useCommand(machine) {
 	const id = useId();
 	const [isPending, startTransition] = useTransition();
@@ -1227,11 +1228,9 @@ function useCommand(machine) {
 		});
 	}, [rawSetOptimisticActiveId]);
 	const updateSearch = useCallback((query) => {
-		startTransition(() => {
-			machine.send({
-				type: "SEARCH_CHANGE",
-				query
-			});
+		machine.send({
+			type: "SEARCH_CHANGE",
+			query
 		});
 	}, [machine]);
 	return {
@@ -1587,8 +1586,22 @@ function CommandHighlight({ text, ranges, highlightClassName }) {
 function CommandInput({ ref, placeholder = "Search...", onValueChange, ...props }) {
 	const stable = useStableContext("Command.Input");
 	const stateCtx = useStateContext("Command.Input");
+	const machineState = useSyncExternalStore(stable.machine.subscribe, stable.machine.getState, stable.machine.getState);
+	const [draft, setDraft] = useState(machineState.search);
+	const inFlight = useRef([]);
+	useLayoutEffect(() => {
+		const { search } = machineState;
+		const echoed = inFlight.current.lastIndexOf(search);
+		if (echoed !== -1) inFlight.current.splice(0, echoed + 1);
+		else {
+			inFlight.current = [];
+			setDraft(search);
+		}
+	}, [machineState]);
 	const handleChange = useCallback((event) => {
 		const { value } = event.target;
+		inFlight.current.push(value);
+		setDraft(value);
 		stable.updateSearch(value);
 		onValueChange?.(value);
 	}, [stable.updateSearch, onValueChange]);
@@ -1607,7 +1620,7 @@ function CommandInput({ ref, placeholder = "Search...", onValueChange, ...props
 		autoCorrect: "off",
 		spellCheck: false,
 		placeholder,
-		value: stateCtx.state.search,
+		value: draft,
 		onChange: handleChange,
 		...props
 	});

package/dist/react/styles.css

@@ -6,6 +6,12 @@
 /* CSS Logical Properties: full RTL/LTR support */
 /* CSS Nesting, @layer cascade control, oklch() color space */
 /* Container queries for responsive item layout */
+/* Secondary text (group headings, shortcuts, empty state, placeholder) is coloured with
+   --command-muted-color, never faded with opacity: opacity stacks on the consumer's text
+   colour and cannot be checked against it. The default is light-dark(), so it follows the
+   used color-scheme of the page (set color-scheme on :root or a parent, or override the
+   token); it is 4.5:1 or better on white, black and the usual near-white / near-black
+   surfaces. Only [data-disabled] items keep opacity (WCAG 1.4.3 exempts disabled controls). */
 
 /* ─── CSS Custom Properties ─── */
 
@@ -40,7 +46,7 @@
 }
 
 /* ─── User-Customizable Animation Properties ─── */
-/* Override these on [data-command-root] or :root to customize all animations */
+/* Override these with unlayered CSS on [data-command-root] loaded after this file, or on a more specific unlayered selector; this block sits outside every @layer, so a normal (non-!important) value set inside a layer loses here whatever its selector, and a :root value is shadowed by this declaration */
 
 [data-command-root] {
   --command-spring-easing: linear(
@@ -99,10 +105,11 @@
   --command-item-height: 44px;
   --command-fade-edge-size: 16px;
   --command-highlight-color: oklch(0.85 0.15 90 / 0.3);
+  --command-muted-color: light-dark(oklch(0.45 0.015 260), oklch(0.75 0.015 260));
 }
 
 /* ─── Spring Easing ─── */
-/* linear() approximation of a critically-damped spring (stiffness: 100, damping: 15) */
+/* linear() spring approximations: --command-spring-easing settles without overshoot; --command-spring-easing-bouncy peaks at 1.033 before settling */
 /* Generated from spring physics: x(t) = 1 - e^(-zt)(cos(wd*t) + (zw/wd)sin(wd*t)) */
 
 @layer command.base, command.layout, command.animation, command.a11y;
@@ -173,7 +180,9 @@
     font: inherit;
 
     &::placeholder {
-      opacity: 0.5;
+      color: var(--command-muted-color);
+      /* Firefox fades ::placeholder by default; the colour token carries the contrast */
+      opacity: 1;
     }
   }
 
@@ -232,7 +241,7 @@
     font-size: 0.75em;
     text-transform: uppercase;
     letter-spacing: 0.05em;
-    opacity: 0.6;
+    color: var(--command-muted-color);
   }
 
   /* ─── Separator ─── */
@@ -255,7 +264,7 @@
 
   [data-command-empty] {
     text-align: center;
-    opacity: 0.6;
+    color: var(--command-muted-color);
   }
 
   /* ─── Shortcut Badge ─── */
@@ -263,7 +272,7 @@
   [data-command-shortcut] {
     font-family: inherit;
     font-size: 0.75em;
-    opacity: 0.5;
+    color: var(--command-muted-color);
     letter-spacing: 0.05em;
   }
 
@@ -543,7 +552,7 @@
     }
 
     [data-command-group-heading] {
-      opacity: 0.8;
+      color: inherit;
     }
 
     [data-command-highlight] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modern-cmdk",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "type": "module",
   "description": "The definitive command palette engine for the modern web",
   "license": "MIT",