modern-cmdk 1.2.3 → 1.4.0

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";
@@ -7427,7 +7427,7 @@ const globby = normalizeArguments(async (patterns, options) => {
 	return unionFastGlobResultsAsync(results, filter);
 });
 const { convertPathToPattern } = import_out.default;
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/utils/intersection.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/utils/intersection.js
 var require_intersection = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	/**
 	* Copyright (c) Facebook, Inc. and its affiliates.
@@ -21523,7 +21523,7 @@ var require_main = /* @__PURE__ */ __commonJSMin(((exports) => {
 		});
 	}
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/utils/union.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/utils/union.js
 var require_union = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	/**
 	* Copyright (c) Facebook, Inc. and its affiliates.
@@ -21541,7 +21541,7 @@ var require_union = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		return Array.from(result);
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/Collection.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/Collection.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -21874,7 +21874,7 @@ var require_Collection = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.hasConflictingRegistration = hasConflictingRegistration;
 	exports.setDefaultCollectionType = setDefaultCollectionType;
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/matchNode.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/matchNode.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -21902,7 +21902,7 @@ var require_matchNode = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	}
 	module.exports = matchNode;
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/utils/once.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/utils/once.js
 var require_once = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	/**
 	* Copyright (c) Facebook, Inc. and its affiliates.
@@ -21923,7 +21923,7 @@ var require_once = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		};
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/collections/Node.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/collections/Node.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -22071,7 +22071,7 @@ var require_Node = /* @__PURE__ */ __commonJSMin(((exports) => {
 	}
 	exports.register = once(register);
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/collections/VariableDeclarator.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/collections/VariableDeclarator.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -22167,7 +22167,7 @@ renameTo: function(newName) {
 	exports.register = once(register);
 	exports.filters = filterMethods;
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/collections/JSXElement.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/collections/JSXElement.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -22324,7 +22324,7 @@ getRootName: function(path) {
 	exports.filters = filterMethods;
 	exports.mappings = mappingMethods;
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/collections/ImportDeclaration.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/collections/ImportDeclaration.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -22395,7 +22395,7 @@ var require_ImportDeclaration = /* @__PURE__ */ __commonJSMin(((exports) => {
 	}
 	exports.register = once(register);
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/collections/index.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/collections/index.js
 var require_collections = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	/**
 	* Copyright (c) Facebook, Inc. and its affiliates.
@@ -35145,7 +35145,7 @@ var require_lib = /* @__PURE__ */ __commonJSMin(((exports) => {
 	exports.parseExpression = parseExpression;
 	exports.tokTypes = tokTypes;
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/parser/babylon.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/parser/babylon.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43182,7 +43182,7 @@ var require_dist = /* @__PURE__ */ __commonJSMin(((exports) => {
 		stripFlowTypes: StripFlowTypes.transformProgram
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/parser/flow.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/parser/flow.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43211,7 +43211,7 @@ var require_flow = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		} };
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/parser/tsOptions.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/parser/tsOptions.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43256,7 +43256,7 @@ var require_tsOptions = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		]
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/parser/ts.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/parser/ts.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43276,7 +43276,7 @@ var require_ts = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		} };
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/parser/tsx.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/parser/tsx.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43298,7 +43298,7 @@ var require_tsx = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		} };
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/parser/babel5Compat.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/parser/babel5Compat.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43341,7 +43341,7 @@ var require_babel5Compat = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		} };
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/getParser.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/getParser.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43359,7 +43359,7 @@ var require_getParser = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		}
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/template.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/template.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -43450,7 +43450,7 @@ var require_template = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		};
 	};
 }));
-// ../../node_modules/.pnpm/jscodeshift@17.4.0/node_modules/jscodeshift/src/core.js
+// ../../node_modules/.pnpm/jscodeshift@17.4.0_supports-color@7.2.0/node_modules/jscodeshift/src/core.js
 /**
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
@@ -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,202 @@ 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`,
+		"",
+		"Node >= 26.4.0 (the floor modern-cmdk's toolchain and create-modern-cmdk declare; modern-cmdk itself declares no engines)",
+		""
+	].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 {