modern-cmdk 1.0.2 → 1.1.0

package/dist/codemod/cli.mjs

@@ -89734,7 +89734,7 @@ const AVAILABLE_TRANSFORMS = new Map([
 * Dynamically import a transform module by name and return its default export.
 */
 async function loadTransform(name) {
-	return (await import(`./transforms/${name}.js`)).default;
+	return (await import(`./transforms/${name}.mjs`)).default;
 }
 function printUsage() {
 	AVAILABLE_TRANSFORMS.entries().forEach(([_name, _description]) => {});
@@ -89832,5 +89832,3 @@ main().catch((_err) => {
 });
 //#endregion
 export {};
-
-//# sourceMappingURL=cli.mjs.map

package/dist/codemod/transforms/data-attrs.d.mts

@@ -7,5 +7,4 @@ import { API, FileInfo } from "jscodeshift";
 */
 declare function transform(fileInfo: FileInfo, api: API): string;
 //#endregion
-export { transform as default };
-//# sourceMappingURL=data-attrs.d.mts.map
+export { transform as default };

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

@@ -64,5 +64,3 @@ function transform(fileInfo, api) {
 }
 //#endregion
 export { transform as default };
-
-//# sourceMappingURL=data-attrs.mjs.map

package/dist/codemod/transforms/forward-ref.d.mts

@@ -7,5 +7,4 @@ import { API, FileInfo } from "jscodeshift";
 */
 declare function transform(fileInfo: FileInfo, api: API): string;
 //#endregion
-export { transform as default };
-//# sourceMappingURL=forward-ref.d.mts.map
+export { transform as default };

package/dist/codemod/transforms/forward-ref.mjs

@@ -49,5 +49,3 @@ function transform(fileInfo, api) {
 }
 //#endregion
 export { transform as default };
-
-//# sourceMappingURL=forward-ref.mjs.map

package/dist/codemod/transforms/import-rewrite.d.mts

@@ -7,5 +7,4 @@ import { API, FileInfo } from "jscodeshift";
 */
 declare function transform(fileInfo: FileInfo, api: API): string;
 //#endregion
-export { transform as default };
-//# sourceMappingURL=import-rewrite.d.mts.map
+export { transform as default };

package/dist/codemod/transforms/import-rewrite.mjs

@@ -41,5 +41,3 @@ function transform(fileInfo, api) {
 }
 //#endregion
 export { transform as default };
-
-//# sourceMappingURL=import-rewrite.mjs.map

package/dist/codemod/transforms/should-filter.d.mts

@@ -6,5 +6,4 @@ import { API, FileInfo } from "jscodeshift";
 */
 declare function transform(fileInfo: FileInfo, api: API): string;
 //#endregion
-export { transform as default };
-//# sourceMappingURL=should-filter.d.mts.map
+export { transform as default };

package/dist/codemod/transforms/should-filter.mjs

@@ -17,5 +17,3 @@ function transform(fileInfo, api) {
 }
 //#endregion
 export { transform as default };
-
-//# sourceMappingURL=should-filter.mjs.map

package/dist/core/index.d.mts

@@ -1,2 +1,568 @@
-import { A as DEFAULT_FRECENCY_DECAY, B as groupId, C as computeFrecencyBonus, D as CommandItem, E as CommandGroup, F as FrecencyRecord, H as ScorerFn, I as FrecencyStorage, L as GroupId, M as FrecencyData, N as FrecencyDecayConfig, O as CommandMachineOptions, P as FrecencyOptions, R as ItemId, S as FrecencyEngine, T as CommandEvent, U as SearchEngine, V as itemId, W as SearchResult, _ as matchesShortcut, a as TelemetryMiddleware, b as parseShortcut, c as batchScoreItems, d as CommandMachine, f as createCommandMachine, g as findMatchingShortcut, h as detectConflicts, i as CommandTelemetryHooks, j as DEFAULT_MACHINE_OPTIONS, k as CommandState, l as scoreItemAsync, m as KeyboardShortcutRegistry, n as createScheduler, o as createTelemetryMiddleware, p as CommandRegistry, r as TypedEmitter, s as createSearchEngine, t as Scheduler, u as scoreItem, v as ParsedShortcut, w as IdbFrecencyStorage, x as MemoryFrecencyStorage, y as formatShortcut, z as createInitialState } from "../index-C6g94P7V.mjs";
-export { CommandEvent, CommandGroup, CommandItem, CommandMachine, CommandMachineOptions, CommandRegistry, CommandState, CommandTelemetryHooks, DEFAULT_FRECENCY_DECAY, DEFAULT_MACHINE_OPTIONS, FrecencyData, FrecencyDecayConfig, FrecencyEngine, FrecencyOptions, FrecencyRecord, FrecencyStorage, GroupId, IdbFrecencyStorage, ItemId, KeyboardShortcutRegistry, MemoryFrecencyStorage, ParsedShortcut, Scheduler, ScorerFn, SearchEngine, SearchResult, TelemetryMiddleware, TypedEmitter, batchScoreItems, computeFrecencyBonus, createCommandMachine, createInitialState, createScheduler, createSearchEngine, createTelemetryMiddleware, detectConflicts, findMatchingShortcut, formatShortcut, groupId, itemId, matchesShortcut, parseShortcut, scoreItem, scoreItemAsync };
+//#region src/core/search/types.d.ts
+/** Result of scoring a single item against a query */
+interface SearchResult {
+  readonly id: ItemId;
+  readonly score: number;
+  /** Character ranges that matched (for highlighting) — [start, end] tuples */
+  readonly matches: ReadonlyArray<readonly [start: number, end: number]>;
+}
+/** A scoring function that evaluates a single item against a query */
+type ScorerFn = (query: string, item: CommandItem) => SearchResult | null;
+/** Search engine interface — pluggable into the state machine */
+interface SearchEngine extends Disposable {
+  /** Index items for fast lookup (call on registration) */
+  index(items: 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(ids: ReadonlySet<ItemId>): void;
+  /** Clear the entire index */
+  clear(): void;
+  /** Dispose resources */
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/types.d.ts
+/**
+* Branded type for command item IDs.
+* Prevents accidental mixing with plain strings at the type level.
+*
+* @example
+* ```ts
+* const id = itemId('copy');
+* // id has type ItemId, not string — catches type errors at compile time
+* ```
+*/
+declare const __itemIdBrand: unique symbol;
+type ItemId = string & {
+  readonly [__itemIdBrand]: never;
+};
+/**
+* Branded type for group IDs.
+* Prevents accidental mixing with plain strings or ItemId at the type level.
+*/
+declare const __groupIdBrand: unique symbol;
+type GroupId = string & {
+  readonly [__groupIdBrand]: never;
+};
+/** Create a branded {@link ItemId} from a plain string. Ensures well-formed Unicode (ES2026). */
+declare function itemId(id: string): ItemId;
+/** Create a branded {@link GroupId} from a plain string. Ensures well-formed Unicode (ES2026). */
+declare function groupId(id: string): GroupId;
+/**
+* A registered command item in the palette.
+* All fields are readonly — state machine creates new items on update.
+*/
+interface CommandItem {
+  /** Unique identifier (branded type) */
+  readonly id: ItemId;
+  /** Display text — also used as the primary search target */
+  readonly value: string;
+  /** Additional searchable terms (matched but not displayed) */
+  readonly keywords?: readonly string[] | undefined;
+  /** Group this item belongs to (items without groupId are ungrouped) */
+  readonly groupId?: GroupId | undefined;
+  /** Keyboard shortcut string (e.g., "Ctrl+C", "Mod+K") */
+  readonly shortcut?: string | undefined;
+  /** Whether this item is disabled (excluded from filtering and selection) */
+  readonly disabled?: boolean | undefined;
+  /** Callback fired when this item is selected */
+  readonly onSelect?: (() => void) | undefined;
+  /** Arbitrary metadata attached to the item */
+  readonly data?: Readonly<Record<string, unknown>> | undefined;
+}
+/**
+* A command group for categorizing items.
+* Groups are rendered with headings and sorted by priority.
+*/
+interface CommandGroup {
+  /** Unique identifier (branded type) */
+  readonly id: GroupId;
+  /** Display heading text (rendered above the group's items) */
+  readonly heading?: string | undefined;
+  /** Sort priority — lower values appear first (default: 0) */
+  readonly priority?: number | undefined;
+}
+/**
+* Immutable state snapshot of the command palette.
+* Consumed by React via `useSyncExternalStore` — each mutation
+* produces a new object reference for efficient re-render detection.
+*/
+interface CommandState {
+  /** Current search query string */
+  readonly search: string;
+  /** Currently active (highlighted) item ID, or null if none */
+  readonly activeId: ItemId | null;
+  /** Ordered list of item IDs that pass the current filter */
+  readonly filteredIds: readonly ItemId[];
+  /** Map of group IDs to their visible item IDs */
+  readonly groupedIds: ReadonlyMap<GroupId, readonly ItemId[]>;
+  /** Count of visible items (shortcut for `filteredIds.length`) */
+  readonly filteredCount: number;
+  /** Whether async items are currently loading */
+  readonly loading: boolean;
+  /** Current page identifier (for multi-page navigation) */
+  readonly page: string;
+  /** Stack of previous pages for back-navigation */
+  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;
+}
+/** All possible events the state machine accepts */
+type CommandEvent = {
+  readonly type: "SEARCH_CHANGE";
+  readonly query: string;
+} | {
+  readonly type: "ITEM_SELECT";
+  readonly id: ItemId;
+} | {
+  readonly type: "ITEM_ACTIVATE";
+  readonly id: ItemId;
+} | {
+  readonly type: "NAVIGATE";
+  readonly direction: "next" | "prev" | "first" | "last";
+} | {
+  readonly type: "PAGE_PUSH";
+  readonly page: string;
+} | {
+  readonly type: "PAGE_POP";
+} | {
+  readonly type: "OPEN";
+} | {
+  readonly type: "CLOSE";
+} | {
+  readonly type: "TOGGLE";
+} | {
+  readonly type: "ITEMS_LOADED";
+  readonly items: readonly CommandItem[];
+} | {
+  readonly type: "REGISTER_ITEM";
+  readonly item: CommandItem;
+} | {
+  readonly type: "UNREGISTER_ITEM";
+  readonly id: ItemId;
+} | {
+  readonly type: "REGISTER_GROUP";
+  readonly group: CommandGroup;
+} | {
+  readonly type: "UNREGISTER_GROUP";
+  readonly id: GroupId;
+};
+/** Frecency record for a single item */
+interface FrecencyRecord {
+  readonly frequency: number;
+  readonly lastUsed: Temporal.Instant;
+}
+/** Complete frecency data for persistence */
+interface FrecencyData {
+  readonly records: ReadonlyMap<ItemId, FrecencyRecord>;
+}
+/** Pluggable frecency storage interface */
+interface FrecencyStorage extends Disposable {
+  load(namespace: string): FrecencyData | Promise<FrecencyData>;
+  save(namespace: string, data: FrecencyData): void | Promise<void>;
+}
+/** Frecency exponential decay bucket configuration */
+interface FrecencyDecayConfig {
+  readonly hourWeight?: number | undefined;
+  readonly dayWeight?: number | undefined;
+  readonly weekWeight?: number | undefined;
+  readonly monthWeight?: number | undefined;
+  readonly olderWeight?: number | undefined;
+}
+/** Frecency configuration options */
+interface FrecencyOptions {
+  readonly enabled: boolean;
+  readonly storage?: FrecencyStorage | undefined;
+  readonly namespace?: string | undefined;
+  readonly decayConfig?: FrecencyDecayConfig | undefined;
+}
+/** Default frecency decay configuration */
+declare const DEFAULT_FRECENCY_DECAY: Required<FrecencyDecayConfig>;
+/** Options for creating a command machine — const type param for narrowed option inference */
+interface CommandMachineOptions {
+  /** Pre-registered items to populate on creation */
+  readonly items?: readonly CommandItem[] | undefined;
+  /** Pre-registered groups for item categorization */
+  readonly groups?: readonly CommandGroup[] | undefined;
+  /** Custom filter function, or `false` to disable filtering entirely */
+  readonly filter?: ((item: CommandItem, query: string) => number | false) | false | undefined;
+  /** Accessible label for the command palette */
+  readonly label?: string | undefined;
+  /** Initial open state */
+  readonly open?: boolean | undefined;
+  /** Frecency configuration for usage-aware ranking */
+  readonly frecency?: FrecencyOptions | undefined;
+  /** Pluggable search engine — drop-in replacement for the default scorer (e.g., WASM engine) */
+  readonly search?: SearchEngine | undefined;
+  /** Callback fired when an item is selected */
+  readonly onSelect?: ((id: ItemId) => void) | undefined;
+  /** Callback fired when the active (highlighted) item changes */
+  readonly onActiveChange?: ((id: ItemId | null) => void) | undefined;
+  /** Callback fired when the dialog open state changes */
+  readonly onOpenChange?: ((open: boolean) => void) | undefined;
+  /** Callback fired when the search query changes */
+  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) */
+  readonly virtualizeThreshold?: number | undefined;
+}
+/** Default machine options */
+declare const DEFAULT_MACHINE_OPTIONS: Partial<CommandMachineOptions>;
+/** Initial state factory */
+declare function createInitialState(options?: CommandMachineOptions): CommandState;
+//#endregion
+//#region src/core/frecency/idb-storage.d.ts
+/**
+* IndexedDB-backed frecency storage using idb-keyval 6.2.2.
+*
+* Persists frecency data across browser sessions. Implements both
+* `Disposable` and `AsyncDisposable` for use with `using` and `await using`.
+*
+* idb-keyval is lazy-loaded on first method call — consumers who import
+* the core module without using IDB frecency pay zero cost.
+*
+* @example
+* ```ts
+* await using storage = new IdbFrecencyStorage();
+* const data = await storage.load('my-app');
+* ```
+*/
+declare class IdbFrecencyStorage implements FrecencyStorage, AsyncDisposable {
+  #private;
+  /**
+  * Create an IDB-backed frecency storage.
+  *
+  * @param dbName — IndexedDB database name (default: 'modern-cmdk')
+  * @param storeName — IndexedDB object store name (default: 'frecency')
+  */
+  constructor(dbName?: string, storeName?: string);
+  /** Load frecency data from IndexedDB for the given namespace */
+  load(namespace: string): Promise<FrecencyData>;
+  /** Save frecency data to IndexedDB for the given namespace */
+  save(namespace: string, data: FrecencyData): Promise<void>;
+  /** Delete frecency data for a namespace from IndexedDB */
+  delete(namespace: string): Promise<void>;
+  /** Synchronous dispose — marks as disposed (best-effort cleanup) */
+  [Symbol.dispose](): void;
+  /** Async dispose — marks as disposed, suitable for `await using` */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+//#endregion
+//#region src/core/frecency/index.d.ts
+/**
+* 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.
+*/
+declare function computeFrecencyBonus(history: FrecencyRecord, now?: Temporal.Instant, config?: FrecencyDecayConfig): number;
+/**
+* Stateful frecency engine that tracks item selection history and provides
+* ranking boosts for search results. Supports pluggable storage backends
+* and automatic flush on dispose. Uses Temporal.Now.instant() for timestamps.
+*/
+declare class FrecencyEngine implements Disposable, AsyncDisposable {
+  #private;
+  constructor(options: FrecencyOptions);
+  /** Load frecency data from storage */
+  load(): Promise<void>;
+  /** Record a selection event for an item */
+  recordSelection(itemId: ItemId): void;
+  /** Get frecency bonus for an item */
+  getBonus(itemId: ItemId, now?: Temporal.Instant): number;
+  /** Get all frecency bonuses as a map — for...of for hot ranking path (no closure overhead) */
+  getAllBonuses(now?: Temporal.Instant): ReadonlyMap<ItemId, number>;
+  /** Get the decay configuration */
+  getConfig(): FrecencyDecayConfig;
+  /** Update decay configuration at runtime */
+  setConfig(config: FrecencyDecayConfig): void;
+  /** Flush dirty data to storage */
+  flush(): Promise<void>;
+  /** Get the raw frecency data */
+  getData(): FrecencyData;
+  /** Async dispose — flushes dirty data before cleanup. Use with `await using`. */
+  [Symbol.asyncDispose](): Promise<void>;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/frecency/memory-storage.d.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.
+*/
+declare class MemoryFrecencyStorage implements FrecencyStorage {
+  #private;
+  load(namespace: string): FrecencyData;
+  save(namespace: string, data: FrecencyData): void;
+  /** Serialize all stored data — Iterator Helpers pipeline (ES2026) */
+  toJSON(): Record<string, {
+    records: Array<[string, FrecencyRecord]>;
+  }>;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/keyboard/parser.d.ts
+/**
+* Structured representation of a keyboard shortcut after parsing.
+* The `normalized` field provides a deterministic string for dedup and comparison.
+*/
+interface ParsedShortcut {
+  readonly key: string;
+  readonly meta: boolean;
+  readonly ctrl: boolean;
+  readonly shift: boolean;
+  readonly alt: boolean;
+  readonly raw: string;
+  readonly normalized: string;
+}
+/**
+* Parse a shortcut string like "Mod+Shift+K" into a structured ParsedShortcut.
+* Uses String.isWellFormed() (ES2026) to ensure valid Unicode input.
+*/
+declare function parseShortcut(shortcut: string): ParsedShortcut;
+/**
+* Formats a ParsedShortcut for display using platform-appropriate symbols.
+* On macOS: renders glyphs (⌘, ⇧, ⌥, ⌃). On other platforms: text labels joined by "+".
+*/
+declare function formatShortcut(parsed: ParsedShortcut): string;
+//#endregion
+//#region src/core/keyboard/matcher.d.ts
+/**
+* Tests whether a KeyboardEvent exactly matches a ParsedShortcut,
+* comparing all four modifier keys (meta, ctrl, shift, alt) and the primary key.
+*/
+declare function matchesShortcut(event: KeyboardEvent, shortcut: ParsedShortcut): boolean;
+/** Match a KeyboardEvent against a list of shortcuts — Iterator Helpers .find() */
+declare function findMatchingShortcut(event: KeyboardEvent, shortcuts: readonly ParsedShortcut[]): ParsedShortcut | null;
+/**
+* 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.
+*/
+declare function detectConflicts(shortcuts: readonly ParsedShortcut[]): ReadonlyMap<string, readonly ParsedShortcut[]>;
+//#endregion
+//#region src/core/keyboard/index.d.ts
+interface ShortcutBinding {
+  readonly shortcut: ParsedShortcut;
+  readonly itemId: ItemId;
+  readonly handler: () => void;
+}
+/**
+* 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).
+*/
+declare class KeyboardShortcutRegistry implements Disposable {
+  #private;
+  constructor(options?: {
+    enabled?: boolean;
+  });
+  /** Register a shortcut binding — returns Disposable for `using` auto-deregister */
+  register(shortcutStr: string, itemId: ItemId, handler: () => void): Disposable;
+  /** Unregister a shortcut by its string representation */
+  unregister(shortcutStr: string): void;
+  /** Unregister all shortcuts for a given item — Map spec allows deletion during iteration */
+  unregisterByItem(itemId: ItemId): void;
+  /** Check for conflicting shortcuts */
+  getConflicts(): ReadonlyMap<string, readonly ParsedShortcut[]>;
+  /** Enable or disable global shortcut listening */
+  setEnabled(enabled: boolean): void;
+  /** Get all registered bindings */
+  getBindings(): ReadonlyMap<string, ShortcutBinding>;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#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.
+* All registration methods return Disposable for automatic cleanup via `using`.
+*/
+declare class CommandRegistry implements Disposable {
+  #private;
+  /** Register an item — returns Disposable for `using` auto-deregister */
+  registerItem(item: CommandItem): Disposable;
+  /** Register multiple items at once — single Disposable for batch cleanup. for...of for hot path. */
+  registerItems(items: readonly CommandItem[]): Disposable;
+  /** Unregister a single item — O(1) Map/Set delete, indexOf+toSpliced for order */
+  unregisterItem(id: ItemId): void;
+  /** Bulk unregister using Set.difference (ES2026) — for...of for hot path */
+  unregisterItems(ids: ReadonlySet<ItemId>): void;
+  /** Register a group */
+  registerGroup(group: CommandGroup): Disposable;
+  /** Unregister a group */
+  unregisterGroup(id: GroupId): void;
+  /** Get an item by ID — O(1) */
+  getItem(id: ItemId): CommandItem | undefined;
+  /** Get a group by ID — O(1) */
+  getGroup(id: GroupId): CommandGroup | undefined;
+  /** Get all registered items in insertion order — cached between mutations */
+  getItems(): readonly CommandItem[];
+  /** Get all registered groups sorted by priority — cached between group mutations */
+  getGroups(): readonly CommandGroup[];
+  /** Get items grouped by groupId using Map.groupBy (ES2026) — direct Map, no Object.entries conversion */
+  getGroupedItems(): ReadonlyMap<GroupId, readonly CommandItem[]>;
+  /** 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) */
+  intersectWith(candidateIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Find items registered but not in a given set (ES2026 Set.difference) */
+  differenceFrom(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Union of registered IDs with another set (ES2026 Set.union) */
+  unionWith(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Check if registered items are a subset of the given set (ES2026 Set.isSubsetOf) */
+  isSubsetOf(otherIds: ReadonlySet<ItemId>): boolean;
+  /** Check if registered items are a superset of the given set (ES2026 Set.isSupersetOf) */
+  isSupersetOf(otherIds: ReadonlySet<ItemId>): boolean;
+  /** Check if registered items share no IDs with the given set (ES2026 Set.isDisjointFrom) */
+  isDisjointFrom(otherIds: ReadonlySet<ItemId>): boolean;
+  /** Symmetric difference between registered IDs and another set (ES2026 Set.symmetricDifference) */
+  symmetricDifferenceWith(otherIds: ReadonlySet<ItemId>): ReadonlySet<ItemId>;
+  /** Total number of registered items */
+  get size(): number;
+  /** Total number of registered groups */
+  get groupCount(): number;
+  /** Clear all items and groups */
+  clear(): void;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/machine.d.ts
+/** Command machine — explicit resource management via `using` */
+interface CommandMachine extends Disposable {
+  getState(): CommandState;
+  send(event: CommandEvent): void;
+  /** Subscribe to state changes — useSyncExternalStore-compatible (returns cleanup function) */
+  subscribe(listener: () => void): () => void;
+  /** Subscribe to full state changes — returns Disposable for `using` pattern */
+  subscribeState(listener: (state: CommandState) => void): Disposable;
+  getRegistry(): CommandRegistry;
+  getKeyboardRegistry(): KeyboardShortcutRegistry;
+  /** Get the current set of filtered item IDs — O(1) membership checks */
+  getFilteredIdSet(): ReadonlySet<ItemId>;
+  /** Get the index map for filtered IDs — O(1) positional lookup */
+  getFilteredIdIndex(): ReadonlyMap<ItemId, number>;
+  [Symbol.dispose](): void;
+}
+/**
+* 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()));
+* ```
+*/
+declare function createCommandMachine(options?: CommandMachineOptions): CommandMachine;
+//#endregion
+//#region src/core/search/default-scorer.d.ts
+/**
+* Public API: scores a command item against a search query.
+* Multi-strategy: exact → prefix → substring → word-boundary → fuzzy.
+* Returns null if no match. For batch use, prefer the search engine
+* which pre-caches lowercase and normalizes query once.
+*/
+declare function scoreItem(query: string, item: CommandItem): SearchResult | null;
+//#endregion
+//#region src/core/search/fuzzy-scorer.d.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.
+*/
+declare function scoreItemAsync(query: string, item: CommandItem): Promise<SearchResult | null>;
+/**
+* Batch score items synchronously inside a single Promise.try (ES2026).
+* Eliminates per-item microtask overhead from async generators — runs the
+* entire scoring pipeline in one synchronous pass, wrapped for error safety.
+*/
+declare function batchScoreItems(query: string, items: readonly CommandItem[]): Promise<SearchResult[]>;
+//#endregion
+//#region src/core/search/index.d.ts
+interface SearchEngineOptions {
+  readonly scorer?: ScorerFn | undefined;
+}
+/**
+* Creates a search engine with pluggable scorer and incremental filtering.
+* When the query extends the previous one, only prior matches are re-scored.
+* Pre-caches lowercase at index time — zero toLowerCase() calls during search.
+* Uses Iterator Helpers (ES2026) for result pipelines and Set.difference for pruning.
+*/
+declare function createSearchEngine(options?: SearchEngineOptions): SearchEngine;
+//#endregion
+//#region src/core/telemetry.d.ts
+interface CommandTelemetryHooks {
+  /** Called when the command palette opens */
+  readonly onPaletteOpen?: () => void;
+  /** Called when the command palette closes, with session duration in ms */
+  readonly onPaletteClose?: (durationMs: number) => void;
+  /** Called after each search completes, with query, result count, and latency */
+  readonly onSearchComplete?: (query: string, resultCount: number, durationMs: number) => void;
+  /** Called when an item is selected, with item ID, active query, and position in list */
+  readonly onItemSelected?: (itemId: ItemId, searchQuery: string, position: number) => void;
+}
+interface TelemetryMiddleware {
+  readonly onOpen: () => void;
+  readonly onClose: () => void;
+  readonly onSearch: (query: string, resultCount: number, startTime: Temporal.Instant) => void;
+  readonly onSelect: (itemId: ItemId, query: string, position: number) => void;
+}
+/**
+* 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.
+*
+* @example
+* ```ts
+* const telemetry = createTelemetryMiddleware({
+*   onPaletteOpen: () => analytics.track('palette_opened'),
+*   onItemSelected: (id, query, pos) => analytics.track('item_selected', { id, query, position: pos }),
+* });
+* ```
+*/
+declare function createTelemetryMiddleware(hooks: CommandTelemetryHooks): TelemetryMiddleware;
+//#endregion
+//#region src/core/utils/event-emitter.d.ts
+type EventMap = {
+  [key: string]: unknown;
+};
+/**
+* Type-safe event emitter with strong references and Disposable subscriptions.
+* Returns Disposable from `on()` for automatic unsubscription via `using`.
+*/
+declare class TypedEmitter<T extends EventMap> implements Disposable {
+  #private;
+  /** Subscribe to an event. Returns a Disposable that removes the listener when disposed. */
+  on<K extends keyof T>(event: K, listener: (data: T[K]) => void): Disposable;
+  /** Emit an event to all listeners. Snapshots the set to prevent live-iteration issues. */
+  emit<K extends keyof T>(event: K, data: T[K]): void;
+  /** Check if any listeners exist for an event */
+  has<K extends keyof T>(event: K): boolean;
+  /** Get count of listeners for an event */
+  listenerCount<K extends keyof T>(event: K): number;
+  /** Remove all listeners */
+  removeAll(): void;
+  [Symbol.dispose](): void;
+}
+//#endregion
+//#region src/core/utils/scheduler.d.ts
+/**
+* Batched update scheduler that coalesces state updates into a single tick.
+* Uses requestAnimationFrame in browsers, queueMicrotask in Node.js/tests.
+*/
+interface Scheduler extends Disposable {
+  schedule(update: () => void): void;
+  flush(): void;
+  [Symbol.dispose](): void;
+}
+/**
+* Creates a batched update scheduler. Coalesces rapid state updates into a single
+* execution pass using rAF (browser) or queueMicrotask (Node.js).
+*/
+declare function createScheduler(): Scheduler;
+//#endregion
+export { type CommandEvent, type CommandGroup, type CommandItem, type CommandMachine, type CommandMachineOptions, CommandRegistry, type CommandState, type CommandTelemetryHooks, DEFAULT_FRECENCY_DECAY, DEFAULT_MACHINE_OPTIONS, type FrecencyData, type FrecencyDecayConfig, FrecencyEngine, type FrecencyOptions, type FrecencyRecord, type FrecencyStorage, type GroupId, IdbFrecencyStorage, type ItemId, KeyboardShortcutRegistry, MemoryFrecencyStorage, type ParsedShortcut, type Scheduler, type ScorerFn, type SearchEngine, type SearchResult, type TelemetryMiddleware, TypedEmitter, batchScoreItems, computeFrecencyBonus, createCommandMachine, createInitialState, createScheduler, createSearchEngine, createTelemetryMiddleware, detectConflicts, findMatchingShortcut, formatShortcut, groupId, itemId, matchesShortcut, parseShortcut, scoreItem, scoreItemAsync };