modern-cmdk 1.0.2 → 1.1.0

package/dist/react/index.mjs

@@ -1,8 +1,9 @@
-import { C as itemId, S as groupId, d as formatShortcut, f as parseShortcut, i as createCommandMachine } from "../core-CgQYpHK3.mjs";
+'use client';
 import * as React from "react";
 import { Component, Suspense, createContext, use, useCallback, useEffect, useId, useLayoutEffect, useMemo, useOptimistic, useRef, useState, useSyncExternalStore, useTransition } from "react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Dialog } from "radix-ui";
+import { createPortal } from "react-dom";
 //#region src/react/activity.tsx
 const ActivityComponent = "Activity" in React ? React.Activity : null;
 /**
@@ -24,20 +25,28 @@ const CommandStableContext = createContext(null);
 CommandStableContext.displayName = "CommandStableContext";
 const CommandStateContext = createContext(null);
 CommandStateContext.displayName = "CommandStateContext";
-/**
-* @deprecated Use CommandStableContext and CommandStateContext instead.
-* Kept for backward compatibility with useCommandState hook.
-*/
-const CommandContext = createContext(null);
-CommandContext.displayName = "CommandContext";
+/** Consume stable context with a descriptive error — replaces 3-line boilerplate in every component */
+function useStableContext(component) {
+	const ctx = use(CommandStableContext);
+	if (!ctx) throw new Error(`${component} must be used within a <Command> component`);
+	return ctx;
+}
+/** Consume state context with a descriptive error — replaces 3-line boilerplate in every component */
+function useStateContext(component) {
+	const ctx = use(CommandStateContext);
+	if (!ctx) throw new Error(`${component} must be used within a <Command> component`);
+	return ctx;
+}
 const CommandGroupContext = createContext(null);
 CommandGroupContext.displayName = "CommandGroupContext";
+/** Context for the status container rendered outside the listbox — used by Command.Empty */
+const CommandListStatusContext = createContext(null);
+CommandListStatusContext.displayName = "CommandListStatusContext";
 //#endregion
 //#region src/react/async-items.tsx
 /** Inner component that suspends via use() until items resolve */
 function AsyncItemsInner({ items: itemsPromise, children }) {
-	const stable = use(CommandStableContext);
-	if (!stable) throw new Error("Command.AsyncItems must be used within a <Command> component");
+	const stable = useStableContext("Command.AsyncItems");
 	const items = use(itemsPromise);
 	useLayoutEffect(() => {
 		stable.machine.send({
@@ -47,6 +56,7 @@ function AsyncItemsInner({ items: itemsPromise, children }) {
 	}, [stable.machine, items]);
 	return /* @__PURE__ */ jsx(Fragment, { children: children(items) });
 }
+/** Suspense-based async item loader that resolves a promise of items using React 19 `use()`. */
 function CommandAsyncItems({ items, fallback, children }) {
 	const stableRef = useRef(items);
 	if (stableRef.current !== items) stableRef.current = items;
@@ -60,6 +70,7 @@ function CommandAsyncItems({ items, fallback, children }) {
 }
 //#endregion
 //#region src/react/badge.tsx
+/** Inline badge for categorization or status indicators on command items. */
 function CommandBadge({ ref, children, ...props }) {
 	return /* @__PURE__ */ jsx("span", {
 		ref,
@@ -69,13 +80,1078 @@ function CommandBadge({ ref, children, ...props }) {
 	});
 }
 //#endregion
+//#region src/core/types.ts
+/** Create a branded {@link ItemId} from a plain string. Ensures well-formed Unicode (ES2026). */
+function itemId(id) {
+	return id.isWellFormed() ? id : id.toWellFormed();
+}
+/** Create a branded {@link GroupId} from a plain string. Ensures well-formed Unicode (ES2026). */
+function groupId(id) {
+	return id.isWellFormed() ? id : id.toWellFormed();
+}
+/** Default frecency decay configuration */
+const DEFAULT_FRECENCY_DECAY = {
+	hourWeight: 4,
+	dayWeight: 2,
+	weekWeight: 1.5,
+	monthWeight: 1,
+	olderWeight: .5
+};
+/** Initial state factory */
+function createInitialState(options) {
+	return {
+		search: "",
+		activeId: null,
+		filteredIds: [],
+		groupedIds: /* @__PURE__ */ new Map(),
+		filteredCount: 0,
+		loading: false,
+		page: "root",
+		pageStack: [],
+		open: options?.open ?? false,
+		lastUpdated: Temporal.Now.instant()
+	};
+}
+//#endregion
+//#region src/core/frecency/memory-storage.ts
+/**
+* In-memory implementation of FrecencyStorage using a Map.
+* Data does not persist across page reloads. Suitable for ephemeral
+* sessions or as the default when no persistent storage is configured.
+*/
+var MemoryFrecencyStorage = class {
+	#store = /* @__PURE__ */ new Map();
+	load(namespace) {
+		return this.#store.get(namespace) ?? { records: /* @__PURE__ */ new Map() };
+	}
+	save(namespace, data) {
+		this.#store.set(namespace, data);
+	}
+	/** Serialize all stored data — Iterator Helpers pipeline (ES2026) */
+	toJSON() {
+		return Object.fromEntries(this.#store.entries().map(([namespace, data]) => [namespace, { records: data.records.entries().toArray() }]));
+	}
+	[Symbol.dispose]() {
+		this.#store.clear();
+	}
+};
+//#endregion
+//#region 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 */
+const BUCKET_HOURS = {
+	hour: 1,
+	day: 24,
+	week: 168,
+	month: 720
+};
+/**
+* Computes a frecency bonus for an item based on usage frequency and recency.
+* Uses Temporal.Duration bucket boundaries (hour/day/week/month) with
+* configurable exponential decay weights per time bucket.
+*/
+function computeFrecencyBonus(history, now = Temporal.Now.instant(), config = DEFAULT_FRECENCY_DECAY) {
+	const hours = now.since(history.lastUsed).total("hours");
+	const { hourWeight = 4, dayWeight = 2, weekWeight = 1.5, monthWeight = 1, olderWeight = .5 } = config;
+	const recencyWeight = hours < BUCKET_HOURS.hour ? hourWeight : hours < BUCKET_HOURS.day ? dayWeight : hours < BUCKET_HOURS.week ? weekWeight : hours < BUCKET_HOURS.month ? monthWeight : olderWeight;
+	return history.frequency * recencyWeight;
+}
+/**
+* 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 Temporal.Now.instant() for timestamps.
+*/
+var FrecencyEngine = class {
+	#storage;
+	#namespace;
+	#data;
+	#config;
+	#dirty = false;
+	constructor(options) {
+		this.#storage = options.storage ?? new MemoryFrecencyStorage();
+		this.#namespace = options.namespace ?? "default";
+		this.#config = options.decayConfig ?? DEFAULT_FRECENCY_DECAY;
+		this.#data = { records: /* @__PURE__ */ new Map() };
+	}
+	/** Load frecency data from storage */
+	async load() {
+		this.#data = await this.#storage.load(this.#namespace);
+	}
+	/** Record a selection event for an item */
+	recordSelection(itemId) {
+		const now = Temporal.Now.instant();
+		const updated = {
+			frequency: (this.#data.records.get(itemId)?.frequency ?? 0) + 1,
+			lastUsed: now
+		};
+		this.#data.records.set(itemId, updated);
+		this.#dirty = true;
+	}
+	/** Get frecency bonus for an item */
+	getBonus(itemId, now) {
+		const record = this.#data.records.get(itemId);
+		if (!record) return 0;
+		return computeFrecencyBonus(record, now, this.#config);
+	}
+	/** Get all frecency bonuses as a map — for...of for hot ranking path (no closure overhead) */
+	getAllBonuses(now = Temporal.Now.instant()) {
+		if (this.#data.records.size === 0) return EMPTY_BONUS_MAP;
+		const bonuses = /* @__PURE__ */ new Map();
+		for (const [id, record] of this.#data.records) bonuses.set(id, computeFrecencyBonus(record, now, this.#config));
+		return bonuses;
+	}
+	/** Get the decay configuration */
+	getConfig() {
+		return this.#config;
+	}
+	/** Update decay configuration at runtime */
+	setConfig(config) {
+		this.#config = {
+			...this.#config,
+			...config
+		};
+	}
+	/** Flush dirty data to storage */
+	async flush() {
+		if (!this.#dirty) return;
+		await this.#storage.save(this.#namespace, this.#data);
+		this.#dirty = false;
+	}
+	/** Get the raw frecency data */
+	getData() {
+		return this.#data;
+	}
+	/** Async dispose — flushes dirty data before cleanup. Use with `await using`. */
+	async [Symbol.asyncDispose]() {
+		if (this.#dirty) {
+			await this.#storage.save(this.#namespace, this.#data);
+			this.#dirty = false;
+		}
+		this.#storage[Symbol.dispose]();
+	}
+	[Symbol.dispose]() {
+		if (this.#dirty) Promise.try(() => this.#storage.save(this.#namespace, this.#data)).catch((err) => {
+			console.warn("[modern-cmdk] FrecencyEngine dispose flush failed:", err);
+		});
+		this.#storage[Symbol.dispose]();
+	}
+};
+//#endregion
+//#region src/core/keyboard/matcher.ts
+/**
+* Tests whether a KeyboardEvent exactly matches a ParsedShortcut,
+* comparing all four modifier keys (meta, ctrl, shift, alt) and the primary key.
+*/
+function matchesShortcut(event, shortcut) {
+	if (shortcut.meta !== event.metaKey) return false;
+	if (shortcut.ctrl !== event.ctrlKey) return false;
+	if (shortcut.shift !== event.shiftKey) return false;
+	if (shortcut.alt !== event.altKey) return false;
+	return event.key.toLowerCase() === shortcut.key;
+}
+/**
+* Detects conflicting shortcut bindings by grouping on their normalized form
+* via Map.groupBy (ES2026). Returns only groups with two or more colliding shortcuts.
+* Map.groupBy returns a Map directly — no Object.entries conversion needed.
+*/
+function detectConflicts(shortcuts) {
+	const grouped = Map.groupBy(shortcuts, (s) => s.normalized);
+	return new Map(grouped.entries().filter(([, group]) => group.length > 1));
+}
+//#endregion
+//#region src/core/keyboard/parser.ts
+const isMac = typeof navigator !== "undefined" && (navigator.userAgentData?.platform === "macOS" || /Mac|iPod|iPhone|iPad/.test(navigator.platform));
+/** Modifier aliases — cross-platform Mod resolution */
+const MODIFIER_MAP = {
+	mod: isMac ? "meta" : "ctrl",
+	meta: "meta",
+	cmd: "meta",
+	command: "meta",
+	ctrl: "ctrl",
+	control: "ctrl",
+	shift: "shift",
+	alt: "alt",
+	option: "alt",
+	opt: "alt"
+};
+/**
+* Parse a shortcut string like "Mod+Shift+K" into a structured ParsedShortcut.
+* Uses String.isWellFormed() (ES2026) to ensure valid Unicode input.
+*/
+function parseShortcut(shortcut) {
+	const safeShortcut = shortcut.isWellFormed() ? shortcut : shortcut.toWellFormed();
+	const parts = safeShortcut.split("+").map((p) => p.trim().toLowerCase());
+	let meta = false;
+	let ctrl = false;
+	let shift = false;
+	let alt = false;
+	let key = "";
+	for (const part of parts) {
+		const modifier = MODIFIER_MAP[part];
+		if (modifier) switch (modifier) {
+			case "meta":
+				meta = true;
+				break;
+			case "ctrl":
+				ctrl = true;
+				break;
+			case "shift":
+				shift = true;
+				break;
+			case "alt":
+				alt = true;
+				break;
+		}
+		else key = part;
+	}
+	const modifiers = [];
+	if (meta) modifiers.push("meta");
+	if (ctrl) modifiers.push("ctrl");
+	if (shift) modifiers.push("shift");
+	if (alt) modifiers.push("alt");
+	modifiers.push(key);
+	return {
+		key,
+		meta,
+		ctrl,
+		shift,
+		alt,
+		raw: safeShortcut,
+		normalized: modifiers.join("+")
+	};
+}
+/**
+* Formats a ParsedShortcut for display using platform-appropriate symbols.
+* On macOS: renders glyphs (⌘, ⇧, ⌥, ⌃). On other platforms: text labels joined by "+".
+*/
+function formatShortcut(parsed) {
+	const parts = [];
+	if (parsed.meta) parts.push(isMac ? "⌘" : "Ctrl");
+	if (parsed.ctrl && !(!isMac && parsed.meta)) parts.push(isMac ? "⌃" : "Ctrl");
+	if (parsed.shift) parts.push(isMac ? "⇧" : "Shift");
+	if (parsed.alt) parts.push(isMac ? "⌥" : "Alt");
+	const displayKey = parsed.key.length === 1 ? parsed.key.toUpperCase() : parsed.key.charAt(0).toUpperCase() + parsed.key.slice(1);
+	parts.push(displayKey);
+	return isMac ? parts.join("") : parts.join("+");
+}
+//#endregion
+//#region src/core/keyboard/index.ts
+/**
+* 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).
+*/
+var KeyboardShortcutRegistry = class {
+	#bindings = /* @__PURE__ */ new Map();
+	#globalListener = null;
+	#enabled = true;
+	constructor(options) {
+		this.#enabled = options?.enabled ?? true;
+		this.#attachGlobalListener();
+	}
+	/** Register a shortcut binding — returns Disposable for `using` auto-deregister */
+	register(shortcutStr, itemId, handler) {
+		const shortcut = parseShortcut(shortcutStr);
+		this.#bindings.set(shortcut.normalized, {
+			shortcut,
+			itemId,
+			handler
+		});
+		return { [Symbol.dispose]: () => {
+			this.#bindings.delete(shortcut.normalized);
+		} };
+	}
+	/** Unregister a shortcut by its string representation */
+	unregister(shortcutStr) {
+		const shortcut = parseShortcut(shortcutStr);
+		this.#bindings.delete(shortcut.normalized);
+	}
+	/** Unregister all shortcuts for a given item — Map spec allows deletion during iteration */
+	unregisterByItem(itemId) {
+		for (const [key, binding] of this.#bindings) if (binding.itemId === itemId) this.#bindings.delete(key);
+	}
+	/** Check for conflicting shortcuts */
+	getConflicts() {
+		return detectConflicts(this.#bindings.values().map((b) => b.shortcut).toArray());
+	}
+	/** Enable or disable global shortcut listening */
+	setEnabled(enabled) {
+		this.#enabled = enabled;
+	}
+	/** Get all registered bindings */
+	getBindings() {
+		return this.#bindings;
+	}
+	#attachGlobalListener() {
+		if (typeof document === "undefined") return;
+		this.#globalListener = (event) => {
+			if (!this.#enabled) return;
+			for (const binding of this.#bindings.values()) if (matchesShortcut(event, binding.shortcut)) {
+				event.preventDefault();
+				event.stopPropagation();
+				binding.handler();
+				return;
+			}
+		};
+		document.addEventListener("keydown", this.#globalListener);
+	}
+	#detachGlobalListener() {
+		if (this.#globalListener && typeof document !== "undefined") {
+			document.removeEventListener("keydown", this.#globalListener);
+			this.#globalListener = null;
+		}
+	}
+	[Symbol.dispose]() {
+		this.#detachGlobalListener();
+		this.#bindings.clear();
+	}
+};
+//#endregion
+//#region src/core/registry.ts
+/**
+* Manages registration and lookup of command items and groups.
+* Uses ES2026 Set methods (union/intersection/difference) for efficient ID operations.
+* All registration methods return Disposable for automatic cleanup via `using`.
+*/
+var CommandRegistry = class {
+	#items = /* @__PURE__ */ new Map();
+	#groups = /* @__PURE__ */ new Map();
+	#itemOrder = [];
+	#itemOrderSet = /* @__PURE__ */ new Set();
+	#cachedItems = null;
+	#cachedGroups = null;
+	#invalidateCache() {
+		this.#cachedItems = null;
+	}
+	#invalidateGroupCache() {
+		this.#cachedGroups = null;
+	}
+	/** Register an item — returns Disposable for `using` auto-deregister */
+	registerItem(item) {
+		this.#items.set(item.id, item);
+		if (!this.#itemOrderSet.has(item.id)) {
+			this.#itemOrder.push(item.id);
+			this.#itemOrderSet.add(item.id);
+		}
+		this.#invalidateCache();
+		return { [Symbol.dispose]: () => {
+			this.unregisterItem(item.id);
+		} };
+	}
+	/** Register multiple items at once — single Disposable for batch cleanup. for...of for hot path. */
+	registerItems(items) {
+		for (const item of items) {
+			this.#items.set(item.id, item);
+			if (!this.#itemOrderSet.has(item.id)) {
+				this.#itemOrder.push(item.id);
+				this.#itemOrderSet.add(item.id);
+			}
+		}
+		this.#invalidateCache();
+		const ids = new Set(items.values().map((i) => i.id));
+		return { [Symbol.dispose]: () => {
+			this.unregisterItems(ids);
+		} };
+	}
+	/** Unregister a single item — O(1) Map/Set delete, indexOf+toSpliced for order */
+	unregisterItem(id) {
+		if (!this.#items.has(id)) return;
+		this.#items.delete(id);
+		this.#itemOrderSet.delete(id);
+		const idx = this.#itemOrder.indexOf(id);
+		if (idx !== -1) this.#itemOrder = this.#itemOrder.toSpliced(idx, 1);
+		this.#invalidateCache();
+	}
+	/** Bulk unregister using Set.difference (ES2026) — for...of for hot path */
+	unregisterItems(ids) {
+		for (const id of ids) this.#items.delete(id);
+		this.#itemOrderSet = this.#itemOrderSet.difference(ids);
+		this.#itemOrder = this.#itemOrder.filter((id) => !ids.has(id));
+		this.#invalidateCache();
+	}
+	/** Register a group */
+	registerGroup(group) {
+		this.#groups.set(group.id, group);
+		this.#invalidateGroupCache();
+		return { [Symbol.dispose]: () => {
+			this.#groups.delete(group.id);
+			this.#invalidateGroupCache();
+		} };
+	}
+	/** Unregister a group */
+	unregisterGroup(id) {
+		this.#groups.delete(id);
+		this.#invalidateGroupCache();
+	}
+	/** Get an item by ID — O(1) */
+	getItem(id) {
+		return this.#items.get(id);
+	}
+	/** Get a group by ID — O(1) */
+	getGroup(id) {
+		return this.#groups.get(id);
+	}
+	/** Get all registered items in insertion order — cached between mutations */
+	getItems() {
+		if (this.#cachedItems !== null) return this.#cachedItems;
+		this.#cachedItems = this.#itemOrder.values().map((id) => this.#items.get(id)).filter((item) => item != null).toArray();
+		return this.#cachedItems;
+	}
+	/** Get all registered groups sorted by priority — cached between group mutations */
+	getGroups() {
+		if (this.#cachedGroups !== null) return this.#cachedGroups;
+		this.#cachedGroups = this.#groups.values().toArray().toSorted((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+		return this.#cachedGroups;
+	}
+	/** Get items grouped by groupId using Map.groupBy (ES2026) — direct Map, no Object.entries conversion */
+	getGroupedItems() {
+		const items = this.getItems();
+		const grouped = Map.groupBy(items, (item) => item.groupId ?? "__ungrouped");
+		const result = /* @__PURE__ */ new Map();
+		for (const group of this.getGroups()) {
+			const groupItems = grouped.get(group.id);
+			if (groupItems != null) result.set(group.id, groupItems);
+		}
+		const ungrouped = grouped.get("__ungrouped");
+		if (ungrouped) result.set("__ungrouped", ungrouped);
+		return result;
+	}
+	/** Get item IDs as a Set — returns internal set (O(1), no allocation) */
+	getItemIds() {
+		return this.#itemOrderSet;
+	}
+	/** Find intersection of registered items with a candidate set (ES2026 Set.intersection) */
+	intersectWith(candidateIds) {
+		return this.#itemOrderSet.intersection(candidateIds);
+	}
+	/** Find items registered but not in a given set (ES2026 Set.difference) */
+	differenceFrom(otherIds) {
+		return this.#itemOrderSet.difference(otherIds);
+	}
+	/** Union of registered IDs with another set (ES2026 Set.union) */
+	unionWith(otherIds) {
+		return this.#itemOrderSet.union(otherIds);
+	}
+	/** Check if registered items are a subset of the given set (ES2026 Set.isSubsetOf) */
+	isSubsetOf(otherIds) {
+		return this.#itemOrderSet.isSubsetOf(otherIds);
+	}
+	/** Check if registered items are a superset of the given set (ES2026 Set.isSupersetOf) */
+	isSupersetOf(otherIds) {
+		return this.#itemOrderSet.isSupersetOf(otherIds);
+	}
+	/** Check if registered items share no IDs with the given set (ES2026 Set.isDisjointFrom) */
+	isDisjointFrom(otherIds) {
+		return this.#itemOrderSet.isDisjointFrom(otherIds);
+	}
+	/** Symmetric difference between registered IDs and another set (ES2026 Set.symmetricDifference) */
+	symmetricDifferenceWith(otherIds) {
+		return this.#itemOrderSet.symmetricDifference(otherIds);
+	}
+	/** Total number of registered items */
+	get size() {
+		return this.#items.size;
+	}
+	/** Total number of registered groups */
+	get groupCount() {
+		return this.#groups.size;
+	}
+	/** Clear all items and groups */
+	clear() {
+		this.#items.clear();
+		this.#groups.clear();
+		this.#itemOrder = [];
+		this.#itemOrderSet.clear();
+		this.#invalidateCache();
+		this.#invalidateGroupCache();
+	}
+	[Symbol.dispose]() {
+		this.clear();
+	}
+};
+//#endregion
+//#region src/core/search/default-scorer.ts
+function isWordSeparator(code) {
+	return code === 32 || code === 9 || code === 45 || code === 95 || code === 46 || code === 47 || code === 92;
+}
+/**
+* Internal fast path: called by search engine with pre-lowered query and targets.
+* Eliminates all toLowerCase() calls on the hot path.
+*/
+function scoreItemPreLowered(lowerQuery, id, lowerValue, lowerKeywords) {
+	let bestScore = 0;
+	let bestMatches = null;
+	const valueResult = scoreTarget(lowerQuery, lowerValue);
+	if (valueResult !== null) {
+		bestScore = valueResult.score;
+		bestMatches = valueResult.matches;
+		if (bestScore >= 1) return {
+			id,
+			score: 1,
+			matches: bestMatches
+		};
+	}
+	if (lowerKeywords !== void 0) for (let i = 0; i < lowerKeywords.length; i++) {
+		const result = scoreTarget(lowerQuery, lowerKeywords[i]);
+		if (result !== null && result.score > bestScore) {
+			bestScore = result.score;
+			bestMatches = result.matches;
+			if (bestScore >= 1) break;
+		}
+	}
+	return bestMatches !== null ? {
+		id,
+		score: bestScore,
+		matches: bestMatches
+	} : null;
+}
+function scoreTarget(query, lowerTarget) {
+	const tLen = lowerTarget.length;
+	if (tLen === 0) return null;
+	const qLen = query.length;
+	if (qLen === 0) return {
+		score: 1,
+		matches: []
+	};
+	if (qLen > tLen) return null;
+	if (lowerTarget === query) return {
+		score: 1,
+		matches: [[0, qLen]]
+	};
+	if (lowerTarget.startsWith(query)) return {
+		score: .9 + .1 * (qLen / tLen),
+		matches: [[0, qLen]]
+	};
+	const substringIdx = lowerTarget.indexOf(query);
+	if (substringIdx !== -1) {
+		const positionBonus = 1 - substringIdx / tLen;
+		const lengthRatio = qLen / tLen;
+		return {
+			score: .5 + .3 * positionBonus + .2 * lengthRatio,
+			matches: [[substringIdx, substringIdx + qLen]]
+		};
+	}
+	const wordBoundaryResult = scoreWordBoundary(query, qLen, lowerTarget, tLen);
+	if (wordBoundaryResult) return wordBoundaryResult;
+	return scoreFuzzy(query, qLen, lowerTarget, tLen);
+}
+function scoreWordBoundary(query, qLen, lowerTarget, tLen) {
+	let queryIdx = 0;
+	const matches = [];
+	let totalWeightedLen = 0;
+	let i = 0;
+	while (i < tLen && queryIdx < qLen) if ((i === 0 || isWordSeparator(lowerTarget.charCodeAt(i - 1))) && lowerTarget.charCodeAt(i) === query.charCodeAt(queryIdx)) {
+		const matchStart = i;
+		let matchLen = 0;
+		while (queryIdx < qLen && i < tLen && !isWordSeparator(lowerTarget.charCodeAt(i)) && lowerTarget.charCodeAt(i) === query.charCodeAt(queryIdx)) {
+			queryIdx++;
+			i++;
+			matchLen++;
+		}
+		matches.push([matchStart, matchStart + matchLen]);
+		totalWeightedLen += matchLen * 2;
+	} else i++;
+	if (queryIdx !== qLen) return null;
+	const maxPossible = qLen * 2;
+	return {
+		score: .3 + .4 * (totalWeightedLen / maxPossible),
+		matches
+	};
+}
+function scoreFuzzy(query, qLen, lowerTarget, tLen) {
+	let queryIdx = 0;
+	let targetIdx = 0;
+	const matches = [];
+	let currentMatchStart = -1;
+	let contiguityScore = 0;
+	while (queryIdx < qLen && targetIdx < tLen) if (query.charCodeAt(queryIdx) === lowerTarget.charCodeAt(targetIdx)) {
+		if (currentMatchStart === -1) currentMatchStart = targetIdx;
+		queryIdx++;
+		targetIdx++;
+	} else {
+		if (currentMatchStart !== -1) {
+			const segmentLen = targetIdx - currentMatchStart;
+			matches.push([currentMatchStart, targetIdx]);
+			contiguityScore += segmentLen * segmentLen;
+			currentMatchStart = -1;
+		}
+		targetIdx++;
+	}
+	if (currentMatchStart !== -1) {
+		const segmentLen = targetIdx - currentMatchStart;
+		matches.push([currentMatchStart, targetIdx]);
+		contiguityScore += segmentLen * segmentLen;
+	}
+	if (queryIdx !== qLen) return null;
+	const maxContiguity = qLen * qLen;
+	const contiguityRatio = contiguityScore / maxContiguity;
+	const positionBonus = 1 - (matches[0]?.[0] ?? 0) / tLen;
+	const lengthRatio = qLen / tLen;
+	return {
+		score: .1 + .3 * contiguityRatio + .15 * positionBonus + .1 * lengthRatio,
+		matches
+	};
+}
+//#endregion
+//#region src/core/search/index.ts
+const __DEV__$1 = globalThis.process ? globalThis.process.env.NODE_ENV !== "production" : false;
+let leakRegistry;
+if (__DEV__$1) leakRegistry = new FinalizationRegistry((label) => {
+	console.warn(`[modern-cmdk] ${label} was garbage collected without being disposed. Use \`using\` or call [Symbol.dispose]() to prevent leaks.`);
+});
+/**
+* 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.
+*/
+function createSearchEngine(options) {
+	const customScorer = options?.scorer;
+	const useDefaultScorer = customScorer === void 0;
+	const indexedEntries = /* @__PURE__ */ new Map();
+	let previousQuery = "";
+	let previousResults = /* @__PURE__ */ new Set();
+	const sentinel = {};
+	if (__DEV__$1 && leakRegistry) leakRegistry.register(sentinel, "SearchEngine", sentinel);
+	return {
+		index(items) {
+			for (const item of items) indexedEntries.set(item.id, {
+				item,
+				lowerValue: item.value.toLowerCase(),
+				lowerKeywords: item.keywords?.map((k) => k.toLowerCase())
+			});
+			previousQuery = "";
+			previousResults = /* @__PURE__ */ new Set();
+		},
+		search(query, items) {
+			if (query === "") {
+				previousQuery = "";
+				previousResults = new Set(items.values().map((i) => i.id));
+				return items.values().map((item) => ({
+					id: item.id,
+					score: 1,
+					matches: []
+				}));
+			}
+			const lowerQuery = query.toLowerCase();
+			const candidateItems = query.startsWith(previousQuery) && previousQuery.length > 0 ? items.values().filter((item) => previousResults.has(item.id)) : items;
+			const results = [];
+			if (useDefaultScorer) for (const item of candidateItems) {
+				const entry = indexedEntries.get(item.id);
+				const result = entry ? scoreItemPreLowered(lowerQuery, item.id, entry.lowerValue, entry.lowerKeywords) : scoreItemPreLowered(lowerQuery, item.id, item.value.toLowerCase(), item.keywords?.map((k) => k.toLowerCase()));
+				if (result !== null) results.push(result);
+			}
+			else for (const item of candidateItems) {
+				const result = customScorer(query, item);
+				if (result != null) results.push(result);
+			}
+			results.sort((a, b) => b.score - a.score);
+			previousQuery = query;
+			previousResults = new Set(results.values().map((r) => r.id));
+			return results.values();
+		},
+		remove(ids) {
+			for (const id of ids) indexedEntries.delete(id);
+			previousResults = previousResults.difference(ids);
+		},
+		clear() {
+			indexedEntries.clear();
+			previousQuery = "";
+			previousResults.clear();
+		},
+		[Symbol.dispose]() {
+			indexedEntries.clear();
+			previousResults.clear();
+			if (__DEV__$1 && leakRegistry) leakRegistry.unregister(sentinel);
+		}
+	};
+}
+//#endregion
+//#region src/core/utils/event-emitter.ts
+/**
+* Type-safe event emitter with strong references and Disposable subscriptions.
+* Returns Disposable from `on()` for automatic unsubscription via `using`.
+*/
+var TypedEmitter = class {
+	#listeners = /* @__PURE__ */ new Map();
+	/** Subscribe to an event. Returns a Disposable that removes the listener when disposed. */
+	on(event, listener) {
+		let set = this.#listeners.get(event);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.#listeners.set(event, set);
+		}
+		const fn = listener;
+		set.add(fn);
+		return { [Symbol.dispose]: () => {
+			set.delete(fn);
+		} };
+	}
+	/** Emit an event to all listeners. Snapshots the set to prevent live-iteration issues. */
+	emit(event, data) {
+		const set = this.#listeners.get(event);
+		if (!set || set.size === 0) return;
+		for (const fn of [...set]) fn(data);
+	}
+	/** Check if any listeners exist for an event */
+	has(event) {
+		const set = this.#listeners.get(event);
+		return set !== void 0 && set.size > 0;
+	}
+	/** Get count of listeners for an event */
+	listenerCount(event) {
+		return this.#listeners.get(event)?.size ?? 0;
+	}
+	/** Remove all listeners */
+	removeAll() {
+		this.#listeners.clear();
+	}
+	[Symbol.dispose]() {
+		this.#listeners.clear();
+	}
+};
+//#endregion
+//#region 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 */
+const canYield = typeof globalThis.scheduler?.yield === "function";
+const hasInputPending = typeof 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).
+*/
+function createScheduler() {
+	let pending = [];
+	let rafId = null;
+	let microtaskScheduled = false;
+	function executeBatch() {
+		const batch = pending;
+		pending = [];
+		rafId = null;
+		microtaskScheduled = false;
+		if (batch.length > 10 && hasInputPending && navigator.scheduling?.isInputPending?.()) {
+			pending = [...batch, ...pending];
+			if (canYield) globalThis.scheduler?.yield?.().then(() => void executeBatch());
+			else rafId ??= requestAnimationFrame(() => void executeBatch());
+			return;
+		}
+		for (const update of batch) try {
+			update();
+		} catch (error) {
+			queueMicrotask(() => {
+				throw error;
+			});
+		}
+	}
+	function flush() {
+		if (rafId !== null) {
+			cancelAnimationFrame(rafId);
+			rafId = null;
+		}
+		microtaskScheduled = false;
+		executeBatch();
+	}
+	return {
+		schedule(update) {
+			pending.push(update);
+			if (hasRAF) rafId ??= requestAnimationFrame(() => void executeBatch());
+			else if (!microtaskScheduled) {
+				microtaskScheduled = true;
+				queueMicrotask(executeBatch);
+			}
+		},
+		flush,
+		[Symbol.dispose]() {
+			if (rafId !== null) {
+				cancelAnimationFrame(rafId);
+				rafId = null;
+			}
+			microtaskScheduled = false;
+			pending = [];
+		}
+	};
+}
+//#endregion
+//#region src/core/machine.ts
+/**
+* Creates a headless command palette state machine with search, frecency,
+* and keyboard shortcut support. Implements Disposable for `using` cleanup.
+*
+* @example
+* ```ts
+* using machine = createCommandMachine({ items, loop: true });
+* machine.subscribe(() => console.log(machine.getState()));
+* ```
+*/
+function createCommandMachine(options = {}) {
+	let state = createInitialState(options);
+	let filteredIdSet = /* @__PURE__ */ new Set();
+	let filteredIdIndex = /* @__PURE__ */ new Map();
+	const registry = new CommandRegistry();
+	const searchEngine = options.search ?? createSearchEngine(typeof options.filter === "function" ? { scorer: (query, item) => {
+		const score = options.filter(item, query);
+		if (score === false) return null;
+		return {
+			id: item.id,
+			score,
+			matches: []
+		};
+	} } : void 0);
+	const scheduler = createScheduler();
+	const emitter = new TypedEmitter();
+	const keyboardRegistry = new KeyboardShortcutRegistry();
+	let frecencyEngine = null;
+	if (options.frecency?.enabled) {
+		frecencyEngine = new FrecencyEngine(options.frecency);
+		frecencyEngine.load();
+	}
+	if (options.items) {
+		registry.registerItems(options.items);
+		searchEngine.index(options.items);
+		for (const item of options.items) if (item.shortcut != null && item.onSelect != null) keyboardRegistry.register(item.shortcut, item.id, item.onSelect);
+	}
+	if (options.groups) for (const group of options.groups) registry.registerGroup(group);
+	refilter("");
+	function setState(newState) {
+		state = newState;
+		emitter.emit("stateChange", state);
+	}
+	function refilter(query) {
+		const items = registry.getItems();
+		const disableFilter = options.filter === false;
+		let filteredIds;
+		if (disableFilter || query === "") filteredIds = items.values().filter((i) => !i.disabled).map((i) => i.id).toArray();
+		else {
+			let results = searchEngine.search(query, items).toArray();
+			if (frecencyEngine) {
+				const bonuses = frecencyEngine.getAllBonuses();
+				results = results.toSorted((a, b) => {
+					const aBonus = bonuses.get(a.id) ?? 0;
+					const bBonus = bonuses.get(b.id) ?? 0;
+					return b.score + bBonus - (a.score + aBonus);
+				});
+			}
+			filteredIds = results.map((r) => r.id);
+		}
+		filteredIdSet = new Set(filteredIds);
+		filteredIdIndex = new Map(filteredIds.entries().map(([i, id]) => [id, i]));
+		const groupedIds = Map.groupBy(filteredIds, (id) => {
+			return registry.getItem(id)?.groupId ?? "__ungrouped";
+		});
+		const activeId = state.activeId && filteredIdSet.has(state.activeId) ? state.activeId : filteredIds[0] ?? null;
+		setState({
+			...state,
+			search: query,
+			filteredIds,
+			groupedIds,
+			filteredCount: filteredIds.length,
+			activeId,
+			lastUpdated: Temporal.Now.instant()
+		});
+	}
+	function navigate(direction) {
+		const { filteredIds, activeId } = state;
+		if (filteredIds.length === 0) return;
+		if (direction === "first") {
+			const newActiveId = filteredIds[0] ?? null;
+			if (newActiveId !== activeId) {
+				setState({
+					...state,
+					activeId: newActiveId,
+					lastUpdated: Temporal.Now.instant()
+				});
+				options.onActiveChange?.(newActiveId);
+			}
+			return;
+		}
+		if (direction === "last") {
+			const newActiveId = filteredIds[filteredIds.length - 1] ?? null;
+			if (newActiveId !== activeId) {
+				setState({
+					...state,
+					activeId: newActiveId,
+					lastUpdated: Temporal.Now.instant()
+				});
+				options.onActiveChange?.(newActiveId);
+			}
+			return;
+		}
+		const loop = options.loop ?? true;
+		const currentIdx = activeId ? filteredIdIndex.get(activeId) ?? -1 : -1;
+		let newIdx;
+		if (direction === "next") if (currentIdx === -1 || currentIdx >= filteredIds.length - 1) newIdx = loop ? 0 : filteredIds.length - 1;
+		else newIdx = currentIdx + 1;
+		else if (currentIdx <= 0) newIdx = loop ? filteredIds.length - 1 : 0;
+		else newIdx = currentIdx - 1;
+		const newActiveId = filteredIds[newIdx] ?? null;
+		if (newActiveId !== activeId) {
+			setState({
+				...state,
+				activeId: newActiveId,
+				lastUpdated: Temporal.Now.instant()
+			});
+			options.onActiveChange?.(newActiveId);
+		}
+	}
+	function handleEvent(event) {
+		switch (event.type) {
+			case "SEARCH_CHANGE":
+				refilter(event.query);
+				options.onSearchChange?.(event.query);
+				break;
+			case "ITEM_SELECT": {
+				const item = registry.getItem(event.id);
+				if (item && !item.disabled) {
+					item.onSelect?.();
+					frecencyEngine?.recordSelection(event.id);
+					emitter.emit("select", event.id);
+					options.onSelect?.(event.id);
+				}
+				break;
+			}
+			case "ITEM_ACTIVATE":
+				if (filteredIdSet.has(event.id)) {
+					setState({
+						...state,
+						activeId: event.id,
+						lastUpdated: Temporal.Now.instant()
+					});
+					options.onActiveChange?.(event.id);
+				}
+				break;
+			case "NAVIGATE":
+				navigate(event.direction);
+				break;
+			case "PAGE_PUSH":
+				setState({
+					...state,
+					page: event.page,
+					pageStack: [...state.pageStack, state.page],
+					lastUpdated: Temporal.Now.instant()
+				});
+				break;
+			case "PAGE_POP": {
+				const prevPage = state.pageStack.at(-1);
+				if (prevPage != null) setState({
+					...state,
+					page: prevPage,
+					pageStack: state.pageStack.toSpliced(-1, 1),
+					lastUpdated: Temporal.Now.instant()
+				});
+				break;
+			}
+			case "OPEN":
+				setState({
+					...state,
+					open: true,
+					lastUpdated: Temporal.Now.instant()
+				});
+				emitter.emit("openChange", true);
+				options.onOpenChange?.(true);
+				break;
+			case "CLOSE":
+				setState({
+					...state,
+					open: false,
+					lastUpdated: Temporal.Now.instant()
+				});
+				emitter.emit("openChange", false);
+				options.onOpenChange?.(false);
+				break;
+			case "TOGGLE": {
+				const newOpen = !state.open;
+				setState({
+					...state,
+					open: newOpen,
+					lastUpdated: Temporal.Now.instant()
+				});
+				emitter.emit("openChange", newOpen);
+				options.onOpenChange?.(newOpen);
+				break;
+			}
+			case "ITEMS_LOADED":
+				registry.registerItems(event.items);
+				searchEngine.index(event.items);
+				state = {
+					...state,
+					loading: false
+				};
+				refilter(state.search);
+				break;
+			case "REGISTER_ITEM":
+				registry.registerItem(event.item);
+				searchEngine.index([event.item]);
+				if (event.item.shortcut && event.item.onSelect) keyboardRegistry.register(event.item.shortcut, event.item.id, event.item.onSelect);
+				refilter(state.search);
+				break;
+			case "UNREGISTER_ITEM":
+				registry.unregisterItem(event.id);
+				searchEngine.remove(new Set([event.id]));
+				keyboardRegistry.unregisterByItem(event.id);
+				refilter(state.search);
+				break;
+			case "REGISTER_GROUP":
+				registry.registerGroup(event.group);
+				refilter(state.search);
+				break;
+			case "UNREGISTER_GROUP":
+				registry.unregisterGroup(event.id);
+				refilter(state.search);
+				break;
+		}
+	}
+	return {
+		getState() {
+			return state;
+		},
+		send(event) {
+			scheduler.schedule(() => handleEvent(event));
+		},
+		subscribe(listener) {
+			const disposable = emitter.on("stateChange", listener);
+			return () => disposable[Symbol.dispose]();
+		},
+		subscribeState(listener) {
+			return emitter.on("stateChange", listener);
+		},
+		getRegistry() {
+			return registry;
+		},
+		getKeyboardRegistry() {
+			return keyboardRegistry;
+		},
+		getFilteredIdSet() {
+			return filteredIdSet;
+		},
+		getFilteredIdIndex() {
+			return filteredIdIndex;
+		},
+		[Symbol.dispose]() {
+			scheduler[Symbol.dispose]();
+			registry[Symbol.dispose]();
+			searchEngine[Symbol.dispose]();
+			emitter[Symbol.dispose]();
+			keyboardRegistry[Symbol.dispose]();
+			frecencyEngine?.[Symbol.dispose]();
+		}
+	};
+}
+//#endregion
 //#region src/react/hooks/use-command.ts
+/** Core hook that binds a CommandMachine to React via useSyncExternalStore, useTransition, and useOptimistic. */
 function useCommand(machine) {
 	const id = useId();
 	const [isPending, startTransition] = useTransition();
 	const state = useSyncExternalStore(machine.subscribe, machine.getState, machine.getState);
-	const filteredIdSet = useMemo(() => new Set(state.filteredIds), [state.filteredIds]);
-	const [optimisticActiveId, setOptimisticActiveId] = useOptimistic(state.activeId);
+	const filteredIdSet = useMemo(() => machine.getFilteredIdSet(), [state.filteredIds, machine]);
+	const [optimisticActiveId, rawSetOptimisticActiveId] = useOptimistic(state.activeId);
+	const setOptimisticActiveId = useCallback((id) => {
+		startTransition(() => {
+			rawSetOptimisticActiveId(id);
+		});
+	}, [rawSetOptimisticActiveId]);
 	const updateSearch = useCallback((query) => {
 		startTransition(() => {
 			machine.send({
@@ -143,30 +1219,77 @@ function createKeydownHandler(machine, getState) {
 	};
 }
 //#endregion
-//#region src/react/dialog.tsx
-function CommandDialog({ children, className, overlayClassName, contentClassName, label = "Command palette", open: controlledOpen, onOpenChange, container, ...machineOptions }) {
-	const rootId = useId();
-	const listId = `${rootId}-list`;
-	const inputId = `${rootId}-input`;
-	const onOpenChangeRef = useRef(onOpenChange);
-	onOpenChangeRef.current = onOpenChange;
+//#region src/react/hooks/use-command-setup.ts
+/**
+* Shared setup for Command and Command.Dialog — creates machine once,
+* subscribes via useSyncExternalStore, memoizes context values, and
+* registers disposal on unmount.
+*
+* @param machineFactory - Called exactly once (first render) to create the machine.
+*   Subsequent renders skip it via ref guard.
+* @param label - Accessible label for the command palette (included in stable context).
+*/
+function useCommandSetup(machineFactory, label) {
 	const machineRef = useRef(null);
-	if (machineRef.current === null) machineRef.current = createCommandMachine({
-		...machineOptions,
-		open: controlledOpen ?? false,
-		onOpenChange: (open) => {
-			onOpenChangeRef.current?.(open);
-		}
-	});
+	if (machineRef.current === null) machineRef.current = machineFactory();
 	const machine = machineRef.current;
 	const { state, isPending, updateSearch, setOptimisticActiveId, filteredIdSet, id } = useCommand(machine);
+	const listId = `${id}-list`;
+	const inputId = `${id}-input`;
 	useEffect(() => {
 		return () => {
 			machineRef.current?.[Symbol.dispose]();
 			machineRef.current = null;
 		};
 	}, []);
-	const handleKeyDown = useCallback(createKeydownHandler(machine, () => machine.getState()), []);
+	return {
+		machine,
+		state,
+		isPending,
+		listId,
+		inputId,
+		handleKeyDown: useMemo(() => createKeydownHandler(machine, () => machine.getState()), [machine]),
+		stableContextValue: useMemo(() => ({
+			machine,
+			rootId: id,
+			listId,
+			inputId,
+			label,
+			updateSearch,
+			setOptimisticActiveId
+		}), [
+			machine,
+			id,
+			listId,
+			inputId,
+			label,
+			updateSearch,
+			setOptimisticActiveId
+		]),
+		stateContextValue: useMemo(() => ({
+			state,
+			isPending,
+			filteredIdSet
+		}), [
+			state,
+			isPending,
+			filteredIdSet
+		])
+	};
+}
+//#endregion
+//#region src/react/dialog.tsx
+/** Dialog variant that wraps the command palette in a Radix UI Dialog with focus trap and overlay. */
+function CommandDialog({ children, className, overlayClassName, contentClassName, label = "Command palette", description = "Type a command or search...", open: controlledOpen, onOpenChange, container, ...machineOptions }) {
+	const onOpenChangeRef = useRef(onOpenChange);
+	onOpenChangeRef.current = onOpenChange;
+	const { machine, state, handleKeyDown, stableContextValue, stateContextValue, inputId } = useCommandSetup(() => createCommandMachine({
+		...machineOptions,
+		open: controlledOpen ?? false,
+		onOpenChange: (open) => {
+			onOpenChangeRef.current?.(open);
+		}
+	}), label);
 	useEffect(() => {
 		if (!state.open) return;
 		document.addEventListener("keydown", handleKeyDown);
@@ -174,42 +1297,16 @@ function CommandDialog({ children, className, overlayClassName, contentClassName
 			document.removeEventListener("keydown", handleKeyDown);
 		};
 	}, [handleKeyDown, state.open]);
-	const prevControlledOpen = useRef(controlledOpen);
 	useEffect(() => {
-		if (controlledOpen !== void 0 && controlledOpen !== prevControlledOpen.current) {
-			prevControlledOpen.current = controlledOpen;
-			machine.send({ type: controlledOpen ? "OPEN" : "CLOSE" });
-		}
+		if (controlledOpen !== void 0) machine.send({ type: controlledOpen ? "OPEN" : "CLOSE" });
 	}, [controlledOpen, machine]);
+	const handleOpenAutoFocus = useCallback((e) => {
+		e.preventDefault();
+		document.getElementById(inputId)?.focus();
+	}, [inputId]);
 	const handleRadixOpenChange = useCallback((open) => {
 		machine.send({ type: open ? "OPEN" : "CLOSE" });
 	}, [machine]);
-	const stableContextValue = useMemo(() => ({
-		machine,
-		rootId: id,
-		listId,
-		inputId,
-		label,
-		updateSearch,
-		setOptimisticActiveId
-	}), [
-		machine,
-		id,
-		listId,
-		inputId,
-		label,
-		updateSearch,
-		setOptimisticActiveId
-	]);
-	const stateContextValue = useMemo(() => ({
-		state,
-		isPending,
-		filteredIdSet
-	}), [
-		state,
-		isPending,
-		filteredIdSet
-	]);
 	return /* @__PURE__ */ jsx(Dialog.Root, {
 		open: state.open,
 		onOpenChange: handleRadixOpenChange,
@@ -224,10 +1321,7 @@ function CommandDialog({ children, className, overlayClassName, contentClassName
 				"data-state": state.open ? "open" : "closed",
 				className,
 				"aria-label": label,
-				onOpenAutoFocus: (e) => {
-					e.preventDefault();
-					document.getElementById(inputId)?.focus();
-				},
+				onOpenAutoFocus: handleOpenAutoFocus,
 				children: [
 					/* @__PURE__ */ jsx(Dialog.Title, {
 						className: "sr-only",
@@ -235,7 +1329,7 @@ function CommandDialog({ children, className, overlayClassName, contentClassName
 					}),
 					/* @__PURE__ */ jsx(Dialog.Description, {
 						className: "sr-only",
-						children: "Type a command or search..."
+						children: description
 					}),
 					/* @__PURE__ */ jsx(CommandStableContext, {
 						value: stableContextValue,
@@ -260,11 +1354,12 @@ function CommandDialog({ children, className, overlayClassName, contentClassName
 }
 //#endregion
 //#region src/react/empty.tsx
+/** Rendered when no items match the current search query. */
 function CommandEmpty({ ref, children, ...props }) {
-	const stateCtx = use(CommandStateContext);
-	if (!stateCtx) throw new Error("Command.Empty must be used within a <Command> component");
+	const stateCtx = useStateContext("Command.Empty");
+	const statusContainerRef = use(CommandListStatusContext);
 	if (stateCtx.state.filteredCount > 0 || stateCtx.state.loading) return null;
-	return /* @__PURE__ */ jsx("div", {
+	const content = /* @__PURE__ */ jsx("div", {
 		ref,
 		"data-command-empty": "",
 		role: "status",
@@ -272,15 +1367,21 @@ function CommandEmpty({ ref, children, ...props }) {
 		...props,
 		children
 	});
+	if (statusContainerRef?.current) return createPortal(content, statusContainerRef.current);
+	return content;
 }
 //#endregion
 //#region src/react/hooks/use-register.ts
 /** Register a command item with the machine — auto-deregisters on unmount */
 function useRegisterItem(value, options) {
-	const stable = use(CommandStableContext);
-	if (!stable) throw new Error("useRegisterItem must be used within a <Command> component");
+	const stable = useStableContext("useRegisterItem");
 	const generatedId = useId();
 	const id = itemId(options?.forceId ?? generatedId);
+	const onSelectRef = useRef(options?.onSelect);
+	onSelectRef.current = options?.onSelect;
+	const dataRef = useRef(options?.data);
+	dataRef.current = options?.data;
+	const keywordsDep = options?.keywords?.join("\0");
 	useLayoutEffect(() => {
 		const item = {
 			id,
@@ -289,8 +1390,8 @@ function useRegisterItem(value, options) {
 			groupId: options?.groupId ? groupId(options.groupId) : void 0,
 			shortcut: options?.shortcut,
 			disabled: options?.disabled,
-			onSelect: options?.onSelect,
-			data: options?.data
+			onSelect: () => onSelectRef.current?.(),
+			data: dataRef.current
 		};
 		stable.machine.send({
 			type: "REGISTER_ITEM",
@@ -307,18 +1408,15 @@ function useRegisterItem(value, options) {
 		id,
 		value,
 		options?.groupId,
-		options?.data,
 		options?.disabled,
-		options?.keywords,
-		options?.onSelect,
+		keywordsDep,
 		options?.shortcut
 	]);
 	return id;
 }
 /** Register a command group with the machine — auto-deregisters on unmount */
 function useRegisterGroup(heading, options) {
-	const stable = use(CommandStableContext);
-	if (!stable) throw new Error("useRegisterGroup must be used within a <Command> component");
+	const stable = useStableContext("useRegisterGroup");
 	const generatedId = useId();
 	const id = groupId(options?.forceId ?? generatedId);
 	useLayoutEffect(() => {
@@ -347,9 +1445,11 @@ function useRegisterGroup(heading, options) {
 }
 //#endregion
 //#region src/react/group.tsx
+/** Module-level constant — avoids allocating a new object on every render of hidden groups */
+const HIDDEN_STYLE = { display: "none" };
+/** Visual grouping container with an optional heading that hides when no items match. */
 function CommandGroup({ ref, children, heading, priority, forceId, ...props }) {
-	const stateCtx = use(CommandStateContext);
-	if (!stateCtx) throw new Error("Command.Group must be used within a <Command> component");
+	const stateCtx = useStateContext("Command.Group");
 	const headingId = useId();
 	const groupId = useRegisterGroup(heading, {
 		...priority !== void 0 && { priority },
@@ -361,7 +1461,13 @@ function CommandGroup({ ref, children, heading, priority, forceId, ...props }) {
 		groupId,
 		headingId
 	}), [groupId, headingId]);
-	if (!hasVisibleItems) return null;
+	if (!hasVisibleItems) return /* @__PURE__ */ jsx(CommandGroupContext, {
+		value: groupContext,
+		children: /* @__PURE__ */ jsx("div", {
+			style: HIDDEN_STYLE,
+			children
+		})
+	});
 	return /* @__PURE__ */ jsx(CommandGroupContext, {
 		value: groupContext,
 		children: /* @__PURE__ */ jsxs("div", {
@@ -384,13 +1490,14 @@ function CommandGroup({ ref, children, heading, priority, forceId, ...props }) {
 }
 //#endregion
 //#region src/react/highlight.tsx
+/** Renders search match highlighting by splitting text at scored match ranges. */
 function CommandHighlight({ text, ranges, highlightClassName }) {
 	return useMemo(() => {
 		if (ranges.length === 0) return text;
-		const sorted = Iterator.from(ranges).toArray().sort((a, b) => a[0] - b[0]);
+		const sorted = ranges.toSorted((a, b) => a[0] - b[0]);
 		const segments = [];
 		let lastEnd = 0;
-		Iterator.from(sorted).forEach(([start, end], i) => {
+		sorted.forEach(([start, end], i) => {
 			if (start > lastEnd) segments.push(text.slice(lastEnd, start));
 			segments.push(/* @__PURE__ */ jsx("mark", {
 				"data-command-highlight": "",
@@ -409,11 +1516,10 @@ function CommandHighlight({ text, ranges, highlightClassName }) {
 }
 //#endregion
 //#region src/react/input.tsx
+/** Combobox input that drives the command palette search state. */
 function CommandInput({ ref, placeholder = "Search...", onValueChange, ...props }) {
-	const stable = use(CommandStableContext);
-	if (!stable) throw new Error("Command.Input must be used within a <Command> component");
-	const stateCtx = use(CommandStateContext);
-	if (!stateCtx) throw new Error("Command.Input must be used within a <Command> component");
+	const stable = useStableContext("Command.Input");
+	const stateCtx = useStateContext("Command.Input");
 	const handleChange = useCallback((event) => {
 		const { value } = event.target;
 		stable.updateSearch(value);
@@ -424,7 +1530,7 @@ function CommandInput({ ref, placeholder = "Search...", onValueChange, ...props
 		"data-command-input": "",
 		type: "text",
 		role: "combobox",
-		"aria-expanded": stateCtx.state.filteredCount > 0,
+		"aria-expanded": true,
 		"aria-controls": stable.listId,
 		"aria-activedescendant": stateCtx.state.activeId ?? void 0,
 		"aria-autocomplete": "list",
@@ -441,17 +1547,18 @@ function CommandInput({ ref, placeholder = "Search...", onValueChange, ...props
 }
 //#endregion
 //#region src/react/item.tsx
+/** Individual selectable item in the command list with keyboard and pointer activation. */
 function CommandItem({ ref, children, value, keywords, onSelect, disabled = false, shortcut, forceId, ...props }) {
-	const stable = use(CommandStableContext);
-	if (!stable) throw new Error("Command.Item must be used within a <Command> component");
-	const stateCtx = use(CommandStateContext);
-	if (!stateCtx) throw new Error("Command.Item must be used within a <Command> component");
+	const stable = useStableContext("Command.Item");
+	const stateCtx = useStateContext("Command.Item");
+	const groupCtx = use(CommandGroupContext);
 	const id = useRegisterItem(value, {
 		...keywords !== void 0 && { keywords },
 		...shortcut !== void 0 && { shortcut },
 		disabled,
 		...onSelect !== void 0 && { onSelect },
-		...forceId !== void 0 && { forceId }
+		...forceId !== void 0 && { forceId },
+		...groupCtx !== null && { groupId: groupCtx.groupId }
 	});
 	const isActive = stateCtx.state.activeId === id;
 	const isFiltered = stateCtx.filteredIdSet.has(id);
@@ -501,6 +1608,7 @@ function CommandItem({ ref, children, value, keywords, onSelect, disabled = fals
 }
 //#endregion
 //#region src/react/hooks/use-virtualizer.ts
+/** Lightweight virtualizer for large item lists using ResizeObserver and scroll tracking. */
 function useVirtualizer(options) {
 	const { count, estimateSize, overscan = 8, scrollElement, enabled = true } = options;
 	const [scrollOffset, setScrollOffset] = useState(0);
@@ -514,17 +1622,12 @@ function useVirtualizer(options) {
 			if (lastEntry) setContainerHeight(lastEntry.contentRect.height);
 		});
 		observer.observe(scrollElement);
-		return () => {
-			observer.disconnect();
-		};
-	}, [scrollElement, enabled]);
-	useEffect(() => {
-		if (!scrollElement || !enabled) return;
 		const handleScroll = () => {
 			setScrollOffset(scrollElement.scrollTop);
 		};
 		scrollElement.addEventListener("scroll", handleScroll, { passive: true });
 		return () => {
+			observer.disconnect();
 			scrollElement.removeEventListener("scroll", handleScroll);
 		};
 	}, [scrollElement, enabled]);
@@ -612,11 +1715,17 @@ function useVirtualizer(options) {
 }
 //#endregion
 //#region src/react/list.tsx
-function CommandList({ ref, children, virtualize, estimateSize = 44, overscan = 8, style, ...props }) {
-	const stable = use(CommandStableContext);
-	if (!stable) throw new Error("Command.List must be used within a <Command> component");
-	const stateCtx = use(CommandStateContext);
-	if (!stateCtx) throw new Error("Command.List must be used within a <Command> component");
+/** Base style for virtual items — hoisted to avoid allocation per item per render */
+const VIRTUAL_ITEM_BASE_STYLE = {
+	position: "absolute",
+	top: 0,
+	left: 0,
+	width: "100%"
+};
+/** Scrollable list container with auto-virtualization and aria-live announcements. */
+function CommandList({ ref, children, virtualize, estimateSize = 44, overscan = 8, announceResults, style, ...props }) {
+	const stable = useStableContext("Command.List");
+	const stateCtx = useStateContext("Command.List");
 	const innerRef = useRef(null);
 	const scrollRef = useRef(null);
 	const [height, setHeight] = useState(0);
@@ -645,7 +1754,7 @@ function CommandList({ ref, children, virtualize, estimateSize = 44, overscan =
 		if (stateCtx.state.activeId && stateCtx.state.activeId !== prevActiveId.current) {
 			prevActiveId.current = stateCtx.state.activeId;
 			if (shouldVirtualize) {
-				const idx = stateCtx.state.filteredIds.indexOf(stateCtx.state.activeId);
+				const idx = stable.machine.getFilteredIdIndex().get(stateCtx.state.activeId) ?? -1;
 				if (idx >= 0) virtualizer.scrollToIndex(idx);
 			} else (scrollRef.current?.querySelector(`[id="${CSS.escape(stateCtx.state.activeId)}"]`))?.scrollIntoView({
 				block: "nearest",
@@ -654,71 +1763,77 @@ function CommandList({ ref, children, virtualize, estimateSize = 44, overscan =
 		}
 	}, [
 		stateCtx.state.activeId,
-		stateCtx.state.filteredIds,
 		shouldVirtualize,
-		virtualizer
+		virtualizer,
+		stable.machine.getFilteredIdIndex
 	]);
-	const mergedStyle = {
+	const mergedStyle = useMemo(() => ({
 		...style,
 		"--command-list-height": `${height.toFixed(1)}px`
-	};
-	return /* @__PURE__ */ jsxs("div", {
-		ref: useCallback((el) => {
-			scrollRef.current = el;
-			if (typeof ref === "function") ref(el);
-			else if (ref) ref.current = el;
-		}, [ref]),
-		"data-command-list": "",
-		role: "listbox",
-		"aria-label": stable.label,
-		"aria-busy": stateCtx.state.loading,
-		id: stable.listId,
-		style: mergedStyle,
-		...props,
-		children: [shouldVirtualize ? /* @__PURE__ */ jsxs("div", {
-			"data-command-list-virtual": "",
-			style: {
-				height: `${virtualizer.totalSize}px`,
-				position: "relative"
-			},
-			children: [virtualizer.virtualItems.map((vItem) => /* @__PURE__ */ jsx("div", {
-				"data-command-virtual-item": "",
-				"data-index": vItem.index,
-				ref: virtualizer.measureElement,
-				style: {
-					position: "absolute",
-					top: 0,
-					left: 0,
-					width: "100%",
-					translate: `0 ${vItem.start}px`
-				}
-			}, vItem.key)), children]
-		}) : /* @__PURE__ */ jsx("div", {
-			ref: innerRef,
-			"data-command-list-inner": "",
-			children
-		}), /* @__PURE__ */ jsxs("div", {
-			"aria-live": "polite",
-			"aria-atomic": true,
-			role: "status",
-			"data-command-aria-live": "",
-			className: "sr-only",
-			children: [
-				stateCtx.state.filteredCount,
-				" result",
-				stateCtx.state.filteredCount !== 1 ? "s" : "",
-				" ",
-				"available."
-			]
-		})]
+	}), [style, height]);
+	const externalRefRef = useRef(ref);
+	externalRefRef.current = ref;
+	const setScrollRef = useCallback((el) => {
+		scrollRef.current = el;
+		const externalRef = externalRefRef.current;
+		if (typeof externalRef === "function") externalRef(el);
+		else if (externalRef) externalRef.current = el;
+	}, []);
+	const statusContainerRef = useRef(null);
+	return /* @__PURE__ */ jsxs(CommandListStatusContext, {
+		value: statusContainerRef,
+		children: [
+			/* @__PURE__ */ jsx("div", {
+				ref: setScrollRef,
+				"data-command-list": "",
+				role: "listbox",
+				"aria-label": stable.label,
+				"aria-busy": stateCtx.state.loading,
+				id: stable.listId,
+				style: mergedStyle,
+				...props,
+				children: shouldVirtualize ? /* @__PURE__ */ jsxs("div", {
+					"data-command-list-virtual": "",
+					style: {
+						height: `${virtualizer.totalSize}px`,
+						position: "relative"
+					},
+					children: [virtualizer.virtualItems.map((vItem) => /* @__PURE__ */ jsx("div", {
+						"data-command-virtual-item": "",
+						"data-index": vItem.index,
+						ref: virtualizer.measureElement,
+						style: {
+							...VIRTUAL_ITEM_BASE_STYLE,
+							translate: `0 ${vItem.start}px`
+						}
+					}, vItem.key)), children]
+				}) : /* @__PURE__ */ jsx("div", {
+					ref: innerRef,
+					"data-command-list-inner": "",
+					children
+				})
+			}),
+			/* @__PURE__ */ jsx("div", {
+				ref: statusContainerRef,
+				"data-command-list-status": ""
+			}),
+			/* @__PURE__ */ jsx("div", {
+				"aria-live": "polite",
+				"aria-atomic": true,
+				role: "status",
+				"data-command-aria-live": "",
+				className: "sr-only",
+				children: announceResults ? announceResults(stateCtx.state.filteredCount) : `${stateCtx.state.filteredCount} result${stateCtx.state.filteredCount !== 1 ? "s" : ""} available.`
+			})
+		]
 	});
 }
 //#endregion
 //#region src/react/loading.tsx
+/** Shown during async operations, with configurable loading state override. */
 function CommandLoading({ ref, children, loading: loadingOverride, ...props }) {
-	const stateCtx = use(CommandStateContext);
-	if (!stateCtx) throw new Error("Command.Loading must be used within a <Command> component");
-	if (!(loadingOverride ?? stateCtx.state.loading ?? stateCtx.isPending)) return null;
+	const stateCtx = useStateContext("Command.Loading");
+	if (!(loadingOverride ?? (stateCtx.state.loading || stateCtx.isPending))) return null;
 	return /* @__PURE__ */ jsx("div", {
 		ref,
 		"data-command-loading": "",
@@ -731,10 +1846,9 @@ function CommandLoading({ ref, children, loading: loadingOverride, ...props }) {
 }
 //#endregion
 //#region src/react/page.tsx
+/** Page navigation container that only renders when its ID matches the active page. */
 function CommandPage({ id, children }) {
-	const stateCtx = use(CommandStateContext);
-	if (!stateCtx) throw new Error("Command.Page must be used within a <Command> component");
-	if (stateCtx.state.page !== id) return null;
+	if (useStateContext("Command.Page").state.page !== id) return null;
 	return /* @__PURE__ */ jsx("div", {
 		"data-command-page": "",
 		"data-command-page-id": id,
@@ -743,77 +1857,48 @@ function CommandPage({ id, children }) {
 }
 //#endregion
 //#region src/react/separator.tsx
+/** Visual divider between items or groups, rendered as a presentational element. */
 function CommandSeparator({ ref, ...props }) {
 	return /* @__PURE__ */ jsx("div", {
 		ref,
 		"data-command-separator": "",
-		role: "separator",
+		role: "none",
 		...props
 	});
 }
 //#endregion
 //#region src/react/shortcut.tsx
+/** Keyboard shortcut display with platform-aware formatting (e.g., Cmd vs Ctrl). */
 function CommandShortcut({ ref, shortcut, children, ...props }) {
-	const displayText = useMemo(() => shortcut ? formatShortcut(parseShortcut(shortcut)) : children, [shortcut, children]);
+	const formattedShortcut = useMemo(() => shortcut ? formatShortcut(parseShortcut(shortcut)) : null, [shortcut]);
 	return /* @__PURE__ */ jsx("kbd", {
 		ref,
 		"data-command-shortcut": "",
 		...props,
-		children: displayText
+		children: formattedShortcut ?? children
 	});
 }
 //#endregion
 //#region src/react/command.tsx
+/** Root compound component that provides the command state machine context to all children. */
 function CommandRoot({ children, className, label = "Command palette", ...machineOptions }) {
-	const rootId = useId();
-	const listId = `${rootId}-list`;
-	const inputId = `${rootId}-input`;
 	const rootRef = useRef(null);
-	const machineRef = useRef(null);
-	if (machineRef.current === null) machineRef.current = createCommandMachine(machineOptions);
-	const machine = machineRef.current;
-	const { state, isPending, updateSearch, setOptimisticActiveId, filteredIdSet, id } = useCommand(machine);
+	const { state, handleKeyDown, stableContextValue, stateContextValue } = useCommandSetup(() => createCommandMachine(machineOptions), label);
 	useEffect(() => {
-		return () => {
-			machineRef.current?.[Symbol.dispose]();
-			machineRef.current = null;
+		const root = rootRef.current;
+		if (!root) return;
+		const scopedHandler = (e) => {
+			if (root.contains(e.target)) handleKeyDown(e);
 		};
-	}, []);
-	const handleKeyDown = useCallback(createKeydownHandler(machine, () => machine.getState()), []);
-	useEffect(() => {
-		document.addEventListener("keydown", handleKeyDown);
+		document.addEventListener("keydown", scopedHandler);
 		return () => {
-			document.removeEventListener("keydown", handleKeyDown);
+			document.removeEventListener("keydown", scopedHandler);
 		};
 	}, [handleKeyDown]);
 	return /* @__PURE__ */ jsx(CommandStableContext, {
-		value: useMemo(() => ({
-			machine,
-			rootId: id,
-			listId,
-			inputId,
-			label,
-			updateSearch,
-			setOptimisticActiveId
-		}), [
-			machine,
-			id,
-			listId,
-			inputId,
-			label,
-			updateSearch,
-			setOptimisticActiveId
-		]),
+		value: stableContextValue,
 		children: /* @__PURE__ */ jsx(CommandStateContext, {
-			value: useMemo(() => ({
-				state,
-				isPending,
-				filteredIdSet
-			}), [
-				state,
-				isPending,
-				filteredIdSet
-			]),
+			value: stateContextValue,
 			children: /* @__PURE__ */ jsx("div", {
 				ref: rootRef,
 				"data-command-root": "",
@@ -847,6 +1932,7 @@ const Command = Object.assign(CommandRoot, {
 //#region src/react/error-boundary.tsx
 /** Initial state — no error captured */
 const INITIAL_STATE = { error: null };
+/** Error boundary for graceful failure recovery in command subtrees. */
 var CommandErrorBoundary = class extends Component {
 	state = INITIAL_STATE;
 	static getDerivedStateFromError(error) {
@@ -868,8 +1954,7 @@ var CommandErrorBoundary = class extends Component {
 //#endregion
 //#region src/react/hooks/use-command-state.ts
 function useCommandState(selector) {
-	const stable = use(CommandStableContext);
-	if (!stable) throw new Error("useCommandState must be used within a <Command> component");
+	const stable = useStableContext("useCommandState");
 	const selectorRef = useRef(selector);
 	selectorRef.current = selector;
 	const getSnapshot = useCallback(() => selectorRef.current ? selectorRef.current(stable.machine.getState()) : stable.machine.getState(), [stable.machine]);
@@ -892,11 +1977,11 @@ const DEVTOOLS_KEY = "__CRIMSON_COMMAND_DEVTOOLS__";
 * ```
 */
 function useCommandDevtools(label = "default") {
-	if (!__DEV__) return;
 	const stable = use(CommandStableContext);
 	const stateCtx = use(CommandStateContext);
 	const stateRef = useRef(null);
 	useEffect(() => {
+		if (!__DEV__) return;
 		if (!stable || !stateCtx) return;
 		const update = () => {
 			const s = stateCtx.state;
@@ -933,5 +2018,3 @@ function useCommandDevtools(label = "default") {
 }
 //#endregion
 export { Command, CommandActivity, CommandAsyncItems, CommandBadge, CommandDialog, CommandEmpty, CommandErrorBoundary, CommandGroup, CommandHighlight, CommandInput, CommandItem, CommandList, CommandLoading, CommandPage, CommandSeparator, CommandShortcut, CommandStableContext, CommandStateContext, createKeydownHandler, useCommand, useCommandDevtools, useCommandState, useRegisterGroup, useRegisterItem, useVirtualizer };
-
-//# sourceMappingURL=index.mjs.map