modern-cmdk 1.1.0 → 1.1.3

package/dist/core/index.mjs

@@ -1,16 +1,34 @@
+//#region src/core/utils/string-wellformed.ts
+/**
+* Regex matching lone surrogates (unpaired high or low surrogates).
+* A lone high surrogate (U+D800–U+DBFF) not followed by a low surrogate,
+* or a lone low surrogate (U+DC00–U+DFFF) not preceded by a high surrogate.
+*/
+const LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+/** Unicode replacement character used to replace lone surrogates. */
+const REPLACEMENT_CHAR = "�";
+/**
+* Ensures a string is well-formed Unicode by replacing lone surrogates
+* with the Unicode replacement character (U+FFFD).
+* Cross-browser replacement for `str.isWellFormed() ? str : str.toWellFormed()`.
+*/
+function ensureWellFormed(str) {
+	return str.replace(LONE_SURROGATE_RE, REPLACEMENT_CHAR);
+}
+//#endregion
 //#region src/core/frecency/idb-storage.ts
 /** Serialize a FrecencyRecord to a JSON-safe format */
 function serializeRecord(record) {
 	return {
 		frequency: record.frequency,
-		lastUsedNs: record.lastUsed.epochNanoseconds.toString()
+		lastUsedMs: record.lastUsed
 	};
 }
 /** Deserialize a FrecencyRecord from its JSON-safe form */
 function deserializeRecord(serialized) {
 	return {
 		frequency: serialized.frequency,
-		lastUsed: Temporal.Instant.fromEpochNanoseconds(BigInt(serialized.lastUsedNs))
+		lastUsed: serialized.lastUsedMs
 	};
 }
 /** Serialize FrecencyData for IndexedDB storage — uses Iterator Helpers */
@@ -21,9 +39,9 @@ function serializeData(data) {
 function deserializeData(serialized) {
 	return { records: new Map(serialized.records.values().map(([id, record]) => [id, deserializeRecord(record)])) };
 }
-/** Build the namespaced IDB key — String.toWellFormed() (ES2026) ensures valid Unicode in key */
+/** Build the namespaced IDB key — ensures valid Unicode in key */
 function storageKey(namespace) {
-	return `frecency:${namespace.isWellFormed() ? namespace : namespace.toWellFormed()}`;
+	return `frecency:${ensureWellFormed(namespace)}`;
 }
 let idbModule;
 /**
@@ -103,13 +121,13 @@ var IdbFrecencyStorage = class {
 };
 //#endregion
 //#region src/core/types.ts
-/** Create a branded {@link ItemId} from a plain string. Ensures well-formed Unicode (ES2026). */
+/** Create a branded {@link ItemId} from a plain string. Ensures well-formed Unicode. */
 function itemId(id) {
-	return id.isWellFormed() ? id : id.toWellFormed();
+	return ensureWellFormed(id);
 }
-/** Create a branded {@link GroupId} from a plain string. Ensures well-formed Unicode (ES2026). */
+/** Create a branded {@link GroupId} from a plain string. Ensures well-formed Unicode. */
 function groupId(id) {
-	return id.isWellFormed() ? id : id.toWellFormed();
+	return ensureWellFormed(id);
 }
 /** Default frecency decay configuration */
 const DEFAULT_FRECENCY_DECAY = {
@@ -137,7 +155,7 @@ function createInitialState(options) {
 		page: "root",
 		pageStack: [],
 		open: options?.open ?? false,
-		lastUpdated: Temporal.Now.instant()
+		lastUpdated: Date.now()
 	};
 }
 //#endregion
@@ -176,11 +194,11 @@ const BUCKET_HOURS = {
 };
 /**
 * Computes a frecency bonus for an item based on usage frequency and recency.
-* Uses Temporal.Duration bucket boundaries (hour/day/week/month) with
+* Uses hour/day/week/month bucket boundaries 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");
+function computeFrecencyBonus(history, now = Date.now(), config = DEFAULT_FRECENCY_DECAY) {
+	const hours = (now - history.lastUsed) / 36e5;
 	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;
@@ -188,7 +206,7 @@ function computeFrecencyBonus(history, now = Temporal.Now.instant(), config = DE
 /**
 * 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.
+* and automatic flush on dispose. Uses Date.now() for timestamps.
 */
 var FrecencyEngine = class {
 	#storage;
@@ -208,7 +226,7 @@ var FrecencyEngine = class {
 	}
 	/** Record a selection event for an item */
 	recordSelection(itemId) {
-		const now = Temporal.Now.instant();
+		const now = Date.now();
 		const updated = {
 			frequency: (this.#data.records.get(itemId)?.frequency ?? 0) + 1,
 			lastUsed: now
@@ -223,7 +241,7 @@ var FrecencyEngine = class {
 		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()) {
+	getAllBonuses(now = Date.now()) {
 		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));
@@ -259,13 +277,29 @@ var FrecencyEngine = class {
 		this.#storage[Symbol.dispose]();
 	}
 	[Symbol.dispose]() {
-		if (this.#dirty) Promise.try(() => this.#storage.save(this.#namespace, this.#data)).catch((err) => {
+		if (this.#dirty) Promise.resolve().then(() => 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/utils/group-by.ts
+/**
+* Groups items from an iterable into a Map keyed by the result of `keyFn`.
+* Cross-browser replacement for `Map.groupBy()`.
+*/
+function mapGroupBy(items, keyFn) {
+	const map = /* @__PURE__ */ new Map();
+	for (const item of items) {
+		const key = keyFn(item);
+		const group = map.get(key);
+		if (group) group.push(item);
+		else map.set(key, [item]);
+	}
+	return map;
+}
+//#endregion
 //#region src/core/keyboard/matcher.ts
 /**
 * Tests whether a KeyboardEvent exactly matches a ParsedShortcut,
@@ -288,7 +322,7 @@ function findMatchingShortcut(event, shortcuts) {
 * Map.groupBy returns a Map directly — no Object.entries conversion needed.
 */
 function detectConflicts(shortcuts) {
-	const grouped = Map.groupBy(shortcuts, (s) => s.normalized);
+	const grouped = mapGroupBy(shortcuts, (s) => s.normalized);
 	return new Map(grouped.entries().filter(([, group]) => group.length > 1));
 }
 //#endregion
@@ -309,10 +343,10 @@ const MODIFIER_MAP = {
 };
 /**
 * Parse a shortcut string like "Mod+Shift+K" into a structured ParsedShortcut.
-* Uses String.isWellFormed() (ES2026) to ensure valid Unicode input.
+* Ensures valid Unicode input via ensureWellFormed helper.
 */
 function parseShortcut(shortcut) {
-	const safeShortcut = shortcut.isWellFormed() ? shortcut : shortcut.toWellFormed();
+	const safeShortcut = ensureWellFormed(shortcut);
 	const parts = safeShortcut.split("+").map((p) => p.trim().toLowerCase());
 	let meta = false;
 	let ctrl = false;
@@ -440,10 +474,54 @@ var KeyboardShortcutRegistry = class {
 	}
 };
 //#endregion
+//#region src/core/utils/set-ops.ts
+/** Returns a new Set containing elements present in both `a` and `b`. */
+function setIntersection(a, b) {
+	const result = /* @__PURE__ */ new Set();
+	const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+	for (const item of smaller) if (larger.has(item)) result.add(item);
+	return result;
+}
+/** Returns a new Set containing elements in `a` but not in `b`. */
+function setDifference(a, b) {
+	const result = /* @__PURE__ */ new Set();
+	for (const item of a) if (!b.has(item)) result.add(item);
+	return result;
+}
+/** Returns a new Set containing all elements from both `a` and `b`. */
+function setUnion(a, b) {
+	const result = new Set(a);
+	for (const item of b) result.add(item);
+	return result;
+}
+/** Returns `true` if every element in `a` is also in `b`. */
+function setIsSubsetOf(a, b) {
+	if (a.size > b.size) return false;
+	for (const item of a) if (!b.has(item)) return false;
+	return true;
+}
+/** Returns `true` if every element in `b` is also in `a`. */
+function setIsSupersetOf(a, b) {
+	return setIsSubsetOf(b, a);
+}
+/** Returns `true` if `a` and `b` share no elements. */
+function setIsDisjointFrom(a, b) {
+	const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+	for (const item of smaller) if (larger.has(item)) return false;
+	return true;
+}
+/** Returns a new Set containing elements in either `a` or `b` but not both. */
+function setSymmetricDifference(a, b) {
+	const result = new Set(a);
+	for (const item of b) if (result.has(item)) result.delete(item);
+	else result.add(item);
+	return result;
+}
+//#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.
+* Uses set operation helpers (union/intersection/difference) for efficient ID operations.
 * All registration methods return Disposable for automatic cleanup via `using`.
 */
 var CommandRegistry = class {
@@ -495,10 +573,10 @@ var CommandRegistry = class {
 		if (idx !== -1) this.#itemOrder = this.#itemOrder.toSpliced(idx, 1);
 		this.#invalidateCache();
 	}
-	/** Bulk unregister using Set.difference (ES2026) — for...of for hot path */
+	/** Bulk unregister — for...of for hot path */
 	unregisterItems(ids) {
 		for (const id of ids) this.#items.delete(id);
-		this.#itemOrderSet = this.#itemOrderSet.difference(ids);
+		this.#itemOrderSet = setDifference(this.#itemOrderSet, ids);
 		this.#itemOrder = this.#itemOrder.filter((id) => !ids.has(id));
 		this.#invalidateCache();
 	}
@@ -536,10 +614,9 @@ var CommandRegistry = class {
 		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 */
+	/** Get items grouped by groupId — direct Map, no Object.entries conversion */
 	getGroupedItems() {
-		const items = this.getItems();
-		const grouped = Map.groupBy(items, (item) => item.groupId ?? "__ungrouped");
+		const grouped = mapGroupBy(this.getItems(), (item) => item.groupId ?? "__ungrouped");
 		const result = /* @__PURE__ */ new Map();
 		for (const group of this.getGroups()) {
 			const groupItems = grouped.get(group.id);
@@ -553,33 +630,33 @@ var CommandRegistry = class {
 	getItemIds() {
 		return this.#itemOrderSet;
 	}
-	/** Find intersection of registered items with a candidate set (ES2026 Set.intersection) */
+	/** Find intersection of registered items with a candidate set */
 	intersectWith(candidateIds) {
-		return this.#itemOrderSet.intersection(candidateIds);
+		return setIntersection(this.#itemOrderSet, candidateIds);
 	}
-	/** Find items registered but not in a given set (ES2026 Set.difference) */
+	/** Find items registered but not in a given set */
 	differenceFrom(otherIds) {
-		return this.#itemOrderSet.difference(otherIds);
+		return setDifference(this.#itemOrderSet, otherIds);
 	}
-	/** Union of registered IDs with another set (ES2026 Set.union) */
+	/** Union of registered IDs with another set */
 	unionWith(otherIds) {
-		return this.#itemOrderSet.union(otherIds);
+		return setUnion(this.#itemOrderSet, otherIds);
 	}
-	/** Check if registered items are a subset of the given set (ES2026 Set.isSubsetOf) */
+	/** Check if registered items are a subset of the given set */
 	isSubsetOf(otherIds) {
-		return this.#itemOrderSet.isSubsetOf(otherIds);
+		return setIsSubsetOf(this.#itemOrderSet, otherIds);
 	}
-	/** Check if registered items are a superset of the given set (ES2026 Set.isSupersetOf) */
+	/** Check if registered items are a superset of the given set */
 	isSupersetOf(otherIds) {
-		return this.#itemOrderSet.isSupersetOf(otherIds);
+		return setIsSupersetOf(this.#itemOrderSet, otherIds);
 	}
-	/** Check if registered items share no IDs with the given set (ES2026 Set.isDisjointFrom) */
+	/** Check if registered items share no IDs with the given set */
 	isDisjointFrom(otherIds) {
-		return this.#itemOrderSet.isDisjointFrom(otherIds);
+		return setIsDisjointFrom(this.#itemOrderSet, otherIds);
 	}
-	/** Symmetric difference between registered IDs and another set (ES2026 Set.symmetricDifference) */
+	/** Symmetric difference between registered IDs and another set */
 	symmetricDifferenceWith(otherIds) {
-		return this.#itemOrderSet.symmetricDifference(otherIds);
+		return setSymmetricDifference(this.#itemOrderSet, otherIds);
 	}
 	/** Total number of registered items */
 	get size() {
@@ -825,7 +902,7 @@ function createSearchEngine(options) {
 		},
 		remove(ids) {
 			for (const id of ids) indexedEntries.delete(id);
-			previousResults = previousResults.difference(ids);
+			previousResults = setDifference(previousResults, ids);
 		},
 		clear() {
 			indexedEntries.clear();
@@ -1009,7 +1086,7 @@ function createCommandMachine(options = {}) {
 		}
 		filteredIdSet = new Set(filteredIds);
 		filteredIdIndex = new Map(filteredIds.entries().map(([i, id]) => [id, i]));
-		const groupedIds = Map.groupBy(filteredIds, (id) => {
+		const groupedIds = mapGroupBy(filteredIds, (id) => {
 			return registry.getItem(id)?.groupId ?? "__ungrouped";
 		});
 		const activeId = state.activeId && filteredIdSet.has(state.activeId) ? state.activeId : filteredIds[0] ?? null;
@@ -1020,7 +1097,7 @@ function createCommandMachine(options = {}) {
 			groupedIds,
 			filteredCount: filteredIds.length,
 			activeId,
-			lastUpdated: Temporal.Now.instant()
+			lastUpdated: Date.now()
 		});
 	}
 	function navigate(direction) {
@@ -1032,7 +1109,7 @@ function createCommandMachine(options = {}) {
 				setState({
 					...state,
 					activeId: newActiveId,
-					lastUpdated: Temporal.Now.instant()
+					lastUpdated: Date.now()
 				});
 				options.onActiveChange?.(newActiveId);
 			}
@@ -1044,7 +1121,7 @@ function createCommandMachine(options = {}) {
 				setState({
 					...state,
 					activeId: newActiveId,
-					lastUpdated: Temporal.Now.instant()
+					lastUpdated: Date.now()
 				});
 				options.onActiveChange?.(newActiveId);
 			}
@@ -1062,7 +1139,7 @@ function createCommandMachine(options = {}) {
 			setState({
 				...state,
 				activeId: newActiveId,
-				lastUpdated: Temporal.Now.instant()
+				lastUpdated: Date.now()
 			});
 			options.onActiveChange?.(newActiveId);
 		}
@@ -1088,7 +1165,7 @@ function createCommandMachine(options = {}) {
 					setState({
 						...state,
 						activeId: event.id,
-						lastUpdated: Temporal.Now.instant()
+						lastUpdated: Date.now()
 					});
 					options.onActiveChange?.(event.id);
 				}
@@ -1101,7 +1178,7 @@ function createCommandMachine(options = {}) {
 					...state,
 					page: event.page,
 					pageStack: [...state.pageStack, state.page],
-					lastUpdated: Temporal.Now.instant()
+					lastUpdated: Date.now()
 				});
 				break;
 			case "PAGE_POP": {
@@ -1110,7 +1187,7 @@ function createCommandMachine(options = {}) {
 					...state,
 					page: prevPage,
 					pageStack: state.pageStack.toSpliced(-1, 1),
-					lastUpdated: Temporal.Now.instant()
+					lastUpdated: Date.now()
 				});
 				break;
 			}
@@ -1118,7 +1195,7 @@ function createCommandMachine(options = {}) {
 				setState({
 					...state,
 					open: true,
-					lastUpdated: Temporal.Now.instant()
+					lastUpdated: Date.now()
 				});
 				emitter.emit("openChange", true);
 				options.onOpenChange?.(true);
@@ -1127,7 +1204,7 @@ function createCommandMachine(options = {}) {
 				setState({
 					...state,
 					open: false,
-					lastUpdated: Temporal.Now.instant()
+					lastUpdated: Date.now()
 				});
 				emitter.emit("openChange", false);
 				options.onOpenChange?.(false);
@@ -1137,7 +1214,7 @@ function createCommandMachine(options = {}) {
 				setState({
 					...state,
 					open: newOpen,
-					lastUpdated: Temporal.Now.instant()
+					lastUpdated: Date.now()
 				});
 				emitter.emit("openChange", newOpen);
 				options.onOpenChange?.(newOpen);
@@ -1213,26 +1290,30 @@ function createCommandMachine(options = {}) {
 //#endregion
 //#region src/core/search/fuzzy-scorer.ts
 /**
-* Async-safe fuzzy scorer — wraps scoring in Promise.try (ES2026) for error resilience.
-* Falls back gracefully on error via Promise.try's synchronous-throw capture.
+* Async-safe fuzzy scorer — wraps scoring in Promise for error resilience.
+* Falls back gracefully on error via synchronous-throw capture.
 */
 function scoreItemAsync(query, item) {
-	return Promise.try(() => scoreItem(query, item));
+	return new Promise((resolve) => {
+		resolve(scoreItem(query, item));
+	});
 }
 /**
-* Batch score items synchronously inside a single Promise.try (ES2026).
+* Batch score items synchronously inside a single Promise.
 * Eliminates per-item microtask overhead from async generators — runs the
 * entire scoring pipeline in one synchronous pass, wrapped for error safety.
 */
 function batchScoreItems(query, items) {
-	return Promise.try(() => items.values().map((item) => scoreItem(query, item)).filter((r) => r != null).toArray().toSorted((a, b) => b.score - a.score));
+	return new Promise((resolve) => {
+		resolve(items.values().map((item) => scoreItem(query, item)).filter((r) => r != null).toArray().toSorted((a, b) => b.score - a.score));
+	});
 }
 //#endregion
 //#region src/core/telemetry.ts
 /**
 * Creates a telemetry middleware that measures command palette interactions.
-* Uses Temporal.Now.instant() (ES2026) for nanosecond-precision timestamps
-* and Temporal.Instant.since() for accurate duration computation.
+* Uses Date.now() for millisecond-precision timestamps
+* and subtraction for duration computation.
 *
 * @example
 * ```ts
@@ -1246,19 +1327,19 @@ function createTelemetryMiddleware(hooks) {
 	let openTimestamp = null;
 	return {
 		onOpen() {
-			openTimestamp = Temporal.Now.instant();
+			openTimestamp = Date.now();
 			hooks.onPaletteOpen?.();
 		},
 		onClose() {
 			if (openTimestamp != null) {
-				const elapsed = Temporal.Now.instant().since(openTimestamp);
-				hooks.onPaletteClose?.(elapsed.total("milliseconds"));
+				const durationMs = Date.now() - openTimestamp;
+				hooks.onPaletteClose?.(durationMs);
 				openTimestamp = null;
 			}
 		},
 		onSearch(query, resultCount, startTime) {
-			const elapsed = Temporal.Now.instant().since(startTime);
-			hooks.onSearchComplete?.(query, resultCount, elapsed.total("milliseconds"));
+			const durationMs = Date.now() - startTime;
+			hooks.onSearchComplete?.(query, resultCount, durationMs);
 		},
 		onSelect(itemId, query, position) {
 			hooks.onItemSelected?.(itemId, query, position);

package/dist/react/index.d.mts

@@ -123,8 +123,8 @@ interface CommandState {
   readonly pageStack: readonly string[];
   /** Whether the command palette dialog is open */
   readonly open: boolean;
-  /** Temporal.Instant of the last state mutation (ES2026) */
-  readonly lastUpdated: Temporal.Instant;
+  /** Epoch-millisecond timestamp of the last state mutation */
+  readonly lastUpdated: number;
 }
 /** All possible events the state machine accepts */
 type CommandEvent = {
@@ -169,7 +169,8 @@ type CommandEvent = {
 /** Frecency record for a single item */
 interface FrecencyRecord {
   readonly frequency: number;
-  readonly lastUsed: Temporal.Instant;
+  /** Epoch-millisecond timestamp of last usage */
+  readonly lastUsed: number;
 }
 /** Complete frecency data for persistence */
 interface FrecencyData {
@@ -274,7 +275,7 @@ declare class KeyboardShortcutRegistry implements Disposable {
 //#region src/core/registry.d.ts
 /**
 * Manages registration and lookup of command items and groups.
-* Uses ES2026 Set methods (union/intersection/difference) for efficient ID operations.
+* Uses set operation helpers (union/intersection/difference) for efficient ID operations.
 * All registration methods return Disposable for automatic cleanup via `using`.
 */
 declare class CommandRegistry implements Disposable {
@@ -285,7 +286,7 @@ declare class CommandRegistry implements Disposable {
   registerItems(items: readonly CommandItem$1[]): Disposable;
   /** Unregister a single item — O(1) Map/Set delete, indexOf+toSpliced for order */
   unregisterItem(id: ItemId): void;
-  /** Bulk unregister using Set.difference (ES2026) — for...of for hot path */
+  /** Bulk unregister — for...of for hot path */
   unregisterItems(ids: ReadonlySet<ItemId>): void;
   /** Register a group */
   registerGroup(group: CommandGroup$1): Disposable;
@@ -299,23 +300,23 @@ declare class CommandRegistry implements Disposable {
   getItems(): readonly CommandItem$1[];
   /** Get all registered groups sorted by priority — cached between group mutations */
   getGroups(): readonly CommandGroup$1[];
-  /** Get items grouped by groupId using Map.groupBy (ES2026) — direct Map, no Object.entries conversion */
+  /** Get items grouped by groupId — direct Map, no Object.entries conversion */
   getGroupedItems(): ReadonlyMap<GroupId, readonly CommandItem$1[]>;
   /** Get item IDs as a Set — returns internal set (O(1), no allocation) */
   getItemIds(): ReadonlySet<ItemId>;
-  /** Find intersection of registered items with a candidate set (ES2026 Set.intersection) */
+  /** Find intersection of registered items with a candidate set */
   intersectWith(candidateIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
-  /** Find items registered but not in a given set (ES2026 Set.difference) */
+  /** Find items registered but not in a given set */
   differenceFrom(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
-  /** Union of registered IDs with another set (ES2026 Set.union) */
+  /** Union of registered IDs with another set */
   unionWith(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
-  /** Check if registered items are a subset of the given set (ES2026 Set.isSubsetOf) */
+  /** Check if registered items are a subset of the given set */
   isSubsetOf(otherIds: ReadonlySet<ItemId>): boolean;
-  /** Check if registered items are a superset of the given set (ES2026 Set.isSupersetOf) */
+  /** Check if registered items are a superset of the given set */
   isSupersetOf(otherIds: ReadonlySet<ItemId>): boolean;
-  /** Check if registered items share no IDs with the given set (ES2026 Set.isDisjointFrom) */
+  /** Check if registered items share no IDs with the given set */
   isDisjointFrom(otherIds: ReadonlySet<ItemId>): boolean;
-  /** Symmetric difference between registered IDs and another set (ES2026 Set.symmetricDifference) */
+  /** Symmetric difference between registered IDs and another set */
   symmetricDifferenceWith(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
   /** Total number of registered items */
   get size(): number;
@@ -593,6 +594,10 @@ interface CommandContextValue {
   readonly setOptimisticActiveId: (id: ItemId | null) => void;
   /** O(1) membership check for filtered items — avoids O(n) Array.includes per item */
   readonly filteredIdSet: ReadonlySet<ItemId>;
+  /** IDs currently visible in virtual viewport + overscan. null = not virtualizing (render all filtered). */
+  readonly visibleIdSet: ReadonlySet<ItemId> | null;
+  /** Map of visible item IDs to their translateY pixel offsets. null = not virtualizing. */
+  readonly virtualPositionMap: ReadonlyMap<ItemId, number> | null;
   readonly rootId: CommandRootId;
   readonly listId: string;
   readonly inputId: string;
@@ -613,6 +618,10 @@ interface CommandStateContextValue {
   readonly state: CommandState;
   readonly isPending: boolean;
   readonly filteredIdSet: ReadonlySet<ItemId>;
+  /** IDs currently visible in virtual viewport + overscan. null = not virtualizing (render all filtered). */
+  readonly visibleIdSet: ReadonlySet<ItemId> | null;
+  /** Map of visible item IDs to their translateY pixel offsets. null = not virtualizing. */
+  readonly virtualPositionMap: ReadonlyMap<ItemId, number> | null;
 }
 declare const CommandStableContext: Context<CommandStableContextValue | null>;
 declare const CommandStateContext: Context<CommandStateContextValue | null>;