@wow-two-beta/ui-vue 0.0.5 → 0.0.6

package/dist/foundation/commands/CommandRegistry.d.ts

@@ -1,29 +1,30 @@
-import { CommandRunOutcome, Command, CommandContext } from './Command';
-/** Receives an error thrown or rejected by a command's `run` (or its `when` predicate), alongside the offending command. */
+import { CommandRunResult } from './models/CommandRunResult';
+import { Command, CommandContext } from './Command';
+/** Receives an error thrown or rejected by a command's `run` (or its `when` predicate), with the offending command. */
 export type CommandErrorHandler = (error: unknown, command: Command) => void;
-/** Notified after any registry mutation — register, replace, or unregister. Carries no payload; re-read the registry. */
+/** Notified after any registry mutation — register, replace, or unregister. No payload; re-read the registry. */
 export type CommandRegistryListener = () => void;
 /** Tunes a registry at creation. */
 export interface CommandRegistryOptions {
-    /** Where a failing `run` is reported. Omitted → failures are swallowed and surface only as a `'failed'` outcome. */
+    /** Reports a programmer exception before the run promise rejects with it. */
     readonly onError?: CommandErrorHandler;
 }
 /** The headless command store — registration, lookup, availability, execution, and change notification. */
 export interface CommandRegistry {
-    /** Registers (or replaces, when the `id` already exists) a command; returns a disposer that removes exactly this entry. */
+    /** Registers (or replaces, when the `id` exists) a command; returns a disposer removing exactly this entry. */
     readonly register: (command: Command) => () => void;
     /** Registers many commands with a single change notification; returns one disposer removing all of them. */
-    readonly registerAll: (commands: readonly Command[]) => () => void;
+    readonly registerAll: (commands: ReadonlyArray<Command>) => () => void;
     /** Removes the command under `id`; returns whether anything was removed. */
     readonly unregister: (id: string) => boolean;
-    /** Looks up one command by id — `undefined` when absent. Identity is stable between mutations (safe as a snapshot). */
+    /** Looks up a command by id — `undefined` when absent. Identity is stable between mutations (safe to snapshot). */
     readonly get: (id: string) => Command | undefined;
     /** Every registered command in insertion order (a replaced entry keeps its original slot). Fresh array per call. */
     readonly list: () => readonly Command[];
-    /** The subset of `list()` that `isCommandAvailable` accepts — what a palette should actually show. Fresh array per call. */
+    /** The subset of `list()` that `isCommandAvailable` accepts — what a palette should show. Fresh array per call. */
     readonly available: () => readonly Command[];
-    /** Executes a command by id. Never throws — see {@link CommandRunOutcome}. An async handler is awaited. */
-    readonly run: (id: string, context?: CommandContext) => Promise<CommandRunOutcome>;
+    /** Executes a command by id. Expected failures return Result; programmer errors reject after reporting. */
+    readonly run: (id: string, context?: CommandContext) => Promise<CommandRunResult>;
     /** Subscribes to mutations; returns an unsubscribe. */
     readonly subscribe: (listener: CommandRegistryListener) => () => void;
     /** A monotonic counter bumped on every mutation — the stable-identity snapshot the composables subscribe to. */

package/dist/foundation/commands/CommandRunFailureCode.d.ts

@@ -0,0 +1,7 @@
+/** Expected reasons a command did not complete. */
+export declare const CommandRunFailureCode: {
+    readonly NotFound: "notFound";
+    readonly Unavailable: "unavailable";
+    readonly Failed: "failed";
+};
+export type CommandRunFailureCode = (typeof CommandRunFailureCode)[keyof typeof CommandRunFailureCode];

package/dist/foundation/commands/SearchCommands.d.ts

@@ -1,6 +1,6 @@
 import { Command } from './Command';
 /** The rank of a command the query excludes — compare against this to test a match. */
-export declare const NO_MATCH: number;
+export declare const NoMatch: number;
 /** The tier a match landed in — lower sorts first. Exported so a surface can label or style a match by its origin. */
 export declare const CommandMatchRank: {
     /** The title starts with the query — the strongest signal. */
@@ -14,7 +14,7 @@ export declare const CommandMatchRank: {
 };
 export type CommandMatchRank = (typeof CommandMatchRank)[keyof typeof CommandMatchRank];
 /**
- * Scores one command against a query — a {@link CommandMatchRank} when it matches, {@link NO_MATCH} when it
+ * Scores one command against a query — a {@link CommandMatchRank} when it matches, {@link NoMatch} when it
  * doesn't. Case-insensitive; the query is trimmed. An empty query matches everything at the best rank.
  */
 export declare function rankCommand(command: Command, query: string): number;
@@ -25,4 +25,4 @@ export declare function rankCommand(command: Command, query: string): number;
  *
  * Availability is NOT applied here — pass `registry.available()` when the palette should hide blocked commands.
  */
-export declare function searchCommands(commands: readonly Command[], query: string): readonly Command[];
+export declare function searchCommands(commands: ReadonlyArray<Command>, query: string): ReadonlyArray<Command>;

package/dist/foundation/commands/hooks/UseCommandRegistry.d.ts

@@ -0,0 +1,19 @@
+import { ComputedRef, ShallowRef } from 'vue';
+import { Command } from '../Command';
+import { CommandRegistry } from '../CommandRegistry';
+/**
+ * Subscribes to a registry's mutations and returns its current version counter. The building block behind
+ * {@link useCommandList} / {@link useAvailableCommands}; use it directly to derive a custom projection
+ * (`computed(() => (version.value, registry.list().filter(mine)))`).
+ */
+export declare function useCommandRegistryVersion(registry: CommandRegistry): Readonly<ShallowRef<number>>;
+/** Every registered command in insertion order, updating the caller whenever the registry mutates. */
+export declare function useCommandList(registry: CommandRegistry): ComputedRef<ReadonlyArray<Command>>;
+/**
+ * The commands a palette should show — `available()` re-evaluated on every registry mutation.
+ *
+ * Availability also depends on whatever `when()` reads, and a registry mutation is the only trigger here: a
+ * `when` predicate closing over unrelated state won't re-run on its own. Keep predicates over state the registry
+ * sees (re-register on change — `useRegisterCommands` does this for you), not over free-floating variables.
+ */
+export declare function useAvailableCommands(registry: CommandRegistry): ComputedRef<ReadonlyArray<Command>>;

package/dist/foundation/commands/hooks/UseCommandShortcuts.d.ts

@@ -0,0 +1,18 @@
+import { MaybeRefOrGetter } from 'vue';
+import { HotkeyOptions } from '../../shortcuts';
+import { CommandContext } from '../Command';
+import { CommandRegistry } from '../CommandRegistry';
+/** Tunes command-shortcut binding — every `useHotkeyMap` option, plus the payload passed to the command. */
+export interface CommandShortcutOptions extends HotkeyOptions {
+    /** Forwarded to `registry.run(id, context)` on every trigger. Read live, so changing it needs no re-binding. */
+    readonly context?: MaybeRefOrGetter<CommandContext>;
+    /** Notified after a triggered command settles — the seam for closing a palette or logging the outcome. */
+    readonly onRun?: (id: string) => void;
+}
+/**
+ * Binds the chord of every available command in `registry`, running the command on trigger. Re-binds whenever the
+ * registry changes. Commands without a `shortcut`, and commands `when()`/`enabled` currently blocks, bind nothing.
+ *
+ * Expected failures settle normally; programmer exceptions are reported by the registry and remain rejected.
+ */
+export declare function useCommandShortcuts(registry: CommandRegistry, options?: CommandShortcutOptions): void;

package/dist/foundation/commands/index.d.ts

@@ -1,8 +1,11 @@
-export { CommandRunOutcome, isCommandAvailable, type Command, type CommandContext, } from './Command';
+export { isCommandAvailable, type Command, type CommandContext } from './Command';
 export { createCommandRegistry, type CommandErrorHandler, type CommandRegistry, type CommandRegistryListener, type CommandRegistryOptions, } from './CommandRegistry';
-export { CommandMatchRank, NO_MATCH, rankCommand, searchCommands } from './SearchCommands';
+export { CommandMatchRank, NoMatch, rankCommand, searchCommands } from './SearchCommands';
 export { commandShortcutLabel } from './CommandShortcut';
-export { useAvailableCommands, useCommandList, useCommandRegistryVersion, } from './UseCommandRegistry';
-export { useCommandShortcuts, type CommandShortcutOptions } from './UseCommandShortcuts';
-export { CommandsKey, provideCommands, useCommand, useCommands, useRegisterCommands, } from './CommandsContext';
-export { default as CommandsProvider, type CommandsProviderProps } from './CommandsProvider.vue';
+export { useAvailableCommands, useCommandList, useCommandRegistryVersion } from './hooks/UseCommandRegistry';
+export { useCommandShortcuts, type CommandShortcutOptions } from './hooks/UseCommandShortcuts';
+export { CommandsKey, provideCommands, useCommand, useCommands, useRegisterCommands, } from './providers/CommandsContext';
+export { default as CommandsProvider, type CommandsProviderProps } from './providers/CommandsProvider.vue';
+export { CommandRunFailureCode } from './CommandRunFailureCode';
+export type { CommandRunFailure } from './models/CommandRunFailure';
+export type { CommandRunResult } from './models/CommandRunResult';

package/dist/foundation/commands/index.js

@@ -1,18 +1,14 @@
-import { a as formatChordString } from "../../chunks/Chord-D9Z-j3O0.js";
+import { R as ResultExtensions } from "../../chunks/ResultExtensions-B7dWH0FZ.js";
+import { a as formatChordString } from "../../chunks/Chord-C3OKRsgk.js";
 import { computed, shallowRef, onMounted, onScopeDispose, toValue, provide, inject, watch, defineComponent, renderSlot } from "vue";
-import { u as useHotkeyMap } from "../../chunks/UseHotkeys-CKIYK5Mq.js";
+import { u as useHotkeyMap } from "../../chunks/UseHotkeys-dSOwoutT.js";
 function isCommandAvailable(command) {
   if (command.enabled === false) return false;
   return command.when === void 0 || command.when();
 }
-const CommandRunOutcome = {
-  /** The handler ran to completion (an async handler resolved). */
-  Ran: "ran",
-  /** No command is registered under that id. */
-  NotFound: "not-found",
-  /** The command exists but `when()` / `enabled` blocked it. */
+const CommandRunFailureCode = {
+  NotFound: "notFound",
   Unavailable: "unavailable",
-  /** The handler threw or rejected — the error was routed to the registry's `onError`. */
   Failed: "failed"
 };
 function createCommandRegistry(options) {
@@ -62,14 +58,14 @@ function createCommandRegistry(options) {
     },
     async run(id, context) {
       const command = entries.get(id);
-      if (command === void 0) return CommandRunOutcome.NotFound;
+      if (command === void 0) return ResultExtensions.fail({ code: CommandRunFailureCode.NotFound });
       try {
-        if (!isCommandAvailable(command)) return CommandRunOutcome.Unavailable;
-        await command.run(context);
-        return CommandRunOutcome.Ran;
+        if (!isCommandAvailable(command)) return ResultExtensions.fail({ code: CommandRunFailureCode.Unavailable });
+        const result = await command.run(context);
+        return result === void 0 || result.ok ? ResultExtensions.ok(void 0) : ResultExtensions.fail({ code: CommandRunFailureCode.Failed, error: result.failure });
       } catch (error) {
         options?.onError?.(error, command);
-        return CommandRunOutcome.Failed;
+        throw error;
       }
     },
     subscribe(listener) {
@@ -83,7 +79,7 @@ function createCommandRegistry(options) {
     }
   };
 }
-const NO_MATCH = Number.POSITIVE_INFINITY;
+const NoMatch = Number.POSITIVE_INFINITY;
 const CommandMatchRank = {
   /** The title starts with the query — the strongest signal. */
   TitlePrefix: 0,
@@ -106,14 +102,14 @@ function rankCommand(command, query) {
   }
   const group = command.group;
   if (group !== void 0 && group.toLowerCase().includes(needle)) return CommandMatchRank.Group;
-  return NO_MATCH;
+  return NoMatch;
 }
 function searchCommands(commands, query) {
   if (query.trim() === "") return commands;
   const matches = [];
   commands.forEach((command, index) => {
     const rank = rankCommand(command, query);
-    if (rank !== NO_MATCH) matches.push({ command, rank, index });
+    if (rank !== NoMatch) matches.push({ command, rank, index });
   });
   matches.sort((left, right) => left.rank - right.rank || left.index - right.index);
   return matches.map((match) => match.command);
@@ -229,9 +225,7 @@ function useRegisterCommands(commands, registry) {
   watch(
     signature,
     (_next, _previous, onCleanup) => {
-      const dispose = target.registerAll(
-        toValue(commands).map((command) => bindToLatest(command, commands))
-      );
+      const dispose = target.registerAll(toValue(commands).map((command) => bindToLatest(command, commands)));
       onCleanup(dispose);
     },
     { immediate: true }
@@ -257,10 +251,10 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
 });
 export {
   CommandMatchRank,
-  CommandRunOutcome,
+  CommandRunFailureCode,
   CommandsKey,
   _sfc_main as CommandsProvider,
-  NO_MATCH,
+  NoMatch,
   commandShortcutLabel,
   createCommandRegistry,
   isCommandAvailable,

package/dist/foundation/commands/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/commands/Command.ts","../../../src/foundation/commands/CommandRegistry.ts","../../../src/foundation/commands/SearchCommands.ts","../../../src/foundation/commands/CommandShortcut.ts","../../../src/foundation/commands/UseCommandRegistry.ts","../../../src/foundation/commands/UseCommandShortcuts.ts","../../../src/foundation/commands/CommandsContext.ts","../../../src/foundation/commands/CommandsProvider.vue"],"sourcesContent":["// The command contract — the pure, framework-free vocabulary of the commands vector. A `Command` is one\n// invocable action (`file.save`, `nav.settings`) carrying everything a palette, menu, or keybinding layer needs\n// to present and run it: identity, label, extra search terms, an optional chord, and an availability predicate.\n//\n// Two deliberate type choices keep this file dependency-free:\n// - `icon` is `unknown`. Naming a Vue icon component type here would drag presentation into foundation; the\n//   render site knows its own icon library and casts (`command.icon as Component`).\n// - `context` is `unknown` rather than a generic parameter. Making `Command<TContext>` generic would force the\n//   registry, the search, and every composable generic too, for a payload that only the app's own `run` reads back.\n//\n// Registry mechanics (register / run / subscribe) live in `CommandRegistry.ts`; this file stays a vocabulary.\n\n/** The opaque payload handed to a command's `run` — apps narrow it inside their own handler (`ctx as MyCtx`). */\nexport type CommandContext = unknown;\n\n/** Describes one invocable action — the unit a palette lists, a menu renders, and a chord triggers. */\nexport interface Command {\n  /** The stable identity. Re-registering the same `id` replaces the prior entry, so keep it constant across renders. */\n  readonly id: string;\n\n  /** The human label — the primary search field and the text a palette row shows. */\n  readonly title: string;\n\n  /** Optional supporting text for the row. Deliberately NOT searched: a long description matches nearly every query. */\n  readonly description?: string;\n\n  /** Optional grouping label (`Navigation`, `Editor`) — used for section headers and searched at the lowest rank. */\n  readonly group?: string;\n\n  /** Extra search terms that don't belong in the title (`['theme', 'appearance']` for \"Toggle dark mode\"). */\n  readonly keywords?: readonly string[];\n\n  /** Optional chord string in `foundation/shortcuts` syntax (`'mod+k'`) — bound by `useCommandShortcuts`, rendered by `commandShortcutLabel`. */\n  readonly shortcut?: string;\n\n  /** Optional icon slot, intentionally untyped — foundation must not name a Vue icon component type. The render site casts. */\n  readonly icon?: unknown;\n\n  /** Availability predicate re-evaluated on every read. Must be cheap and side-effect free (`available()` calls it per command). */\n  readonly when?: () => boolean;\n\n  /** Hard off-switch — `false` hides the command from `available()` regardless of `when`. Defaults to `true`. */\n  readonly enabled?: boolean;\n\n  /** The handler. May be sync or async; the registry awaits it and routes a rejection to its `onError`. */\n  readonly run: (context?: CommandContext) => void | Promise<void>;\n}\n\n/**\n * Reports whether a command may run right now — `enabled !== false` **and** `when()` (when present) passing.\n * Exported so a surface holding a plain array (not a registry) applies the same rule the registry does.\n * Propagates a throw from `when`; `registry.run` guards against that, direct callers should not pass a throwing predicate.\n */\nexport function isCommandAvailable(command: Command): boolean {\n  if (command.enabled === false) return false;\n  return command.when === undefined || command.when();\n}\n\n/**\n * Defines the result of `registry.run(...)`. Every path resolves to one of these — the registry never throws, so a\n * keystroke handler needs no try/catch and a caller can distinguish \"no such command\" from \"blocked\" from \"failed\".\n */\nexport const CommandRunOutcome = {\n  /** The handler ran to completion (an async handler resolved). */\n  Ran: 'ran',\n  /** No command is registered under that id. */\n  NotFound: 'not-found',\n  /** The command exists but `when()` / `enabled` blocked it. */\n  Unavailable: 'unavailable',\n  /** The handler threw or rejected — the error was routed to the registry's `onError`. */\n  Failed: 'failed',\n} as const;\n\nexport type CommandRunOutcome = (typeof CommandRunOutcome)[keyof typeof CommandRunOutcome];\n","// The registry — the headless core of the commands vector: a mutable, insertion-ordered `id → Command` store that\n// a palette, menu, or keybinding layer reads from. Framework-free on purpose (no Vue import) so one can be\n// created at module scope, inside a provider, or in a plain node test.\n//\n// Non-obvious decisions:\n// - Re-registering an existing `id` REPLACES the entry (last wins) and keeps its ORIGINAL position in `list()`.\n//   A `Map.set` on an existing key doesn't move it, which is what we want: a re-registration refreshing a command\n//   must not make the palette's rows jump around.\n// - A `register` disposer removes only the entry it registered. A stale disposer firing after a replace is a\n//   no-op — exactly what an effect cleanup racing a re-registration needs (cleanup runs after the next register).\n// - `run` never throws. A missing id, a `when()`-blocked command, a throwing predicate, and a rejecting handler\n//   all resolve to a `CommandRunOutcome`, with the error routed to `onError`. A keystroke handler shouldn't need\n//   a try/catch, and a palette shouldn't crash because one command misbehaves.\n// - Mutations bump a monotonic `version()` on top of notifying listeners. A subscribing composable needs a\n//   snapshot whose identity is stable between mutations; `list()` / `available()` build fresh arrays every call\n//   and would look changed on every read. The version number is the stable cursor those composables read instead.\n// - `registerAll` applies every entry then notifies ONCE, so registering a screen's ten commands wakes\n//   subscribers a single time.\n\nimport { CommandRunOutcome, isCommandAvailable, type Command, type CommandContext } from './Command';\n\n/** Receives an error thrown or rejected by a command's `run` (or its `when` predicate), alongside the offending command. */\nexport type CommandErrorHandler = (error: unknown, command: Command) => void;\n\n/** Notified after any registry mutation — register, replace, or unregister. Carries no payload; re-read the registry. */\nexport type CommandRegistryListener = () => void;\n\n/** Tunes a registry at creation. */\nexport interface CommandRegistryOptions {\n  /** Where a failing `run` is reported. Omitted → failures are swallowed and surface only as a `'failed'` outcome. */\n  readonly onError?: CommandErrorHandler;\n}\n\n/** The headless command store — registration, lookup, availability, execution, and change notification. */\nexport interface CommandRegistry {\n  /** Registers (or replaces, when the `id` already exists) a command; returns a disposer that removes exactly this entry. */\n  readonly register: (command: Command) => () => void;\n\n  /** Registers many commands with a single change notification; returns one disposer removing all of them. */\n  readonly registerAll: (commands: readonly Command[]) => () => void;\n\n  /** Removes the command under `id`; returns whether anything was removed. */\n  readonly unregister: (id: string) => boolean;\n\n  /** Looks up one command by id — `undefined` when absent. Identity is stable between mutations (safe as a snapshot). */\n  readonly get: (id: string) => Command | undefined;\n\n  /** Every registered command in insertion order (a replaced entry keeps its original slot). Fresh array per call. */\n  readonly list: () => readonly Command[];\n\n  /** The subset of `list()` that `isCommandAvailable` accepts — what a palette should actually show. Fresh array per call. */\n  readonly available: () => readonly Command[];\n\n  /** Executes a command by id. Never throws — see {@link CommandRunOutcome}. An async handler is awaited. */\n  readonly run: (id: string, context?: CommandContext) => Promise<CommandRunOutcome>;\n\n  /** Subscribes to mutations; returns an unsubscribe. */\n  readonly subscribe: (listener: CommandRegistryListener) => () => void;\n\n  /** A monotonic counter bumped on every mutation — the stable-identity snapshot the composables subscribe to. */\n  readonly version: () => number;\n}\n\n/**\n * Creates a {@link CommandRegistry}. One per app is the norm (a `CommandsProvider` owns it); create extra ones for\n * isolation in tests or for a scoped palette that must not see the global set.\n */\nexport function createCommandRegistry(options?: CommandRegistryOptions): CommandRegistry {\n  const entries = new Map<string, Command>();\n  const listeners = new Set<CommandRegistryListener>();\n  let revision = 0;\n\n  /** Bumps the version then fans out to listeners over a copy, so a listener may unsubscribe while being notified. */\n  function notify(): void {\n    revision += 1;\n    for (const listener of [...listeners]) listener();\n  }\n\n  /** Removes `command` only if it is still the entry under its id; reports whether it removed anything. */\n  function removeExact(command: Command): boolean {\n    if (entries.get(command.id) !== command) return false;\n    entries.delete(command.id);\n    return true;\n  }\n\n  return {\n    register(command: Command): () => void {\n      entries.set(command.id, command);\n      notify();\n      return () => {\n        if (removeExact(command)) notify();\n      };\n    },\n\n    registerAll(commands: readonly Command[]): () => void {\n      const registered = [...commands];\n      for (const command of registered) entries.set(command.id, command);\n      notify();\n      return () => {\n        let removed = false;\n        for (const command of registered) removed = removeExact(command) || removed;\n        if (removed) notify();\n      };\n    },\n\n    unregister(id: string): boolean {\n      if (!entries.delete(id)) return false;\n      notify();\n      return true;\n    },\n\n    get(id: string): Command | undefined {\n      return entries.get(id);\n    },\n\n    list(): readonly Command[] {\n      return [...entries.values()];\n    },\n\n    available(): readonly Command[] {\n      return [...entries.values()].filter(isCommandAvailable);\n    },\n\n    async run(id: string, context?: CommandContext): Promise<CommandRunOutcome> {\n      const command = entries.get(id);\n      if (command === undefined) return CommandRunOutcome.NotFound;\n      try {\n        // Inside the try so a throwing `when` degrades to `'failed'` rather than escaping the \"never throws\" promise.\n        if (!isCommandAvailable(command)) return CommandRunOutcome.Unavailable;\n        await command.run(context);\n        return CommandRunOutcome.Ran;\n      } catch (error) {\n        options?.onError?.(error, command);\n        return CommandRunOutcome.Failed;\n      }\n    },\n\n    subscribe(listener: CommandRegistryListener): () => void {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    version(): number {\n      return revision;\n    },\n  };\n}\n","// Search + ranking — the pure half of a palette's filter box. Kept out of the registry so any list can be ranked\n// (a static array, a scoped subset, an app set merged with the SDK's) without owning a registry, and so the\n// ranking is testable without mounting anything.\n//\n// Non-obvious decisions:\n// - Matching covers `title`, `keywords`, and `group` only. `description` is deliberately excluded: a sentence-long\n//   description matches almost any short query, which floods the list and destroys the ranking.\n// - Ranking is tiered, not fuzzy. Fuzzy scoring reorders rows unpredictably as the user types; four ordered tiers\n//   (title prefix → title substring → keyword → group) stay legible and cheap.\n// - Ties keep the caller's original order — the sort is explicitly stabilized on the source index rather than\n//   relying on engine sort stability, so a palette's rows never reshuffle between keystrokes.\n// - An empty (or whitespace-only) query returns the SAME array reference it was given, so a `useMemo`d caller\n//   doesn't churn on the common \"nothing typed yet\" path.\n\nimport type { Command } from './Command';\n\n/** The rank of a command the query excludes — compare against this to test a match. */\nexport const NO_MATCH = Number.POSITIVE_INFINITY;\n\n/** The tier a match landed in — lower sorts first. Exported so a surface can label or style a match by its origin. */\nexport const CommandMatchRank = {\n  /** The title starts with the query — the strongest signal. */\n  TitlePrefix: 0,\n  /** The title contains the query somewhere after the start. */\n  TitleSubstring: 1,\n  /** One of the `keywords` contains the query. */\n  Keyword: 2,\n  /** The `group` label contains the query — the weakest signal. */\n  Group: 3,\n} as const;\n\nexport type CommandMatchRank = (typeof CommandMatchRank)[keyof typeof CommandMatchRank];\n\n/**\n * Scores one command against a query — a {@link CommandMatchRank} when it matches, {@link NO_MATCH} when it\n * doesn't. Case-insensitive; the query is trimmed. An empty query matches everything at the best rank.\n */\nexport function rankCommand(command: Command, query: string): number {\n  const needle = query.trim().toLowerCase();\n  if (needle === '') return CommandMatchRank.TitlePrefix;\n\n  const title = command.title.toLowerCase();\n  if (title.startsWith(needle)) return CommandMatchRank.TitlePrefix;\n  if (title.includes(needle)) return CommandMatchRank.TitleSubstring;\n\n  const keywords = command.keywords;\n  if (keywords !== undefined && keywords.some((keyword) => keyword.toLowerCase().includes(needle))) {\n    return CommandMatchRank.Keyword;\n  }\n\n  const group = command.group;\n  if (group !== undefined && group.toLowerCase().includes(needle)) return CommandMatchRank.Group;\n\n  return NO_MATCH;\n}\n\n/**\n * Filters and ranks commands for a palette's search box. Non-matching commands are dropped; matches sort by\n * {@link CommandMatchRank}, ties keeping their original relative order. An empty / whitespace-only query returns\n * the input untouched (same reference, original order).\n *\n * Availability is NOT applied here — pass `registry.available()` when the palette should hide blocked commands.\n */\nexport function searchCommands(commands: readonly Command[], query: string): readonly Command[] {\n  if (query.trim() === '') return commands;\n\n  const matches: { readonly command: Command; readonly rank: number; readonly index: number }[] = [];\n  commands.forEach((command, index) => {\n    const rank = rankCommand(command, query);\n    if (rank !== NO_MATCH) matches.push({ command, rank, index });\n  });\n\n  matches.sort((left, right) => left.rank - right.rank || left.index - right.index);\n  return matches.map((match) => match.command);\n}\n","// The display half of a command's shortcut. A palette row shows `⌘K` / `Ctrl+K` next to the title; without this\n// helper every surface would re-derive that label from the raw `'mod+k'` string and eventually drift from what\n// `useCommandShortcuts` actually binds. Delegating to `foundation/shortcuts`' `formatChordString` keeps the label\n// and the binding on one parser, including the platform split (`mod` → ⌘ on Apple, Ctrl elsewhere).\n//\n// An unparseable chord degrades to the raw string instead of throwing: a typo'd shortcut should render oddly, not\n// crash the palette rendering it. The error still surfaces loudly the moment the chord is bound.\n\nimport { formatChordString, type ChordPlatformOptions } from '../shortcuts';\n\nimport type { Command } from './Command';\n\n/**\n * Renders a command's shortcut for display (`'mod+k'` → `⌘K` on Apple, `Ctrl+K` elsewhere). Returns `undefined`\n * when the command carries no shortcut, and the raw string when it carries one the chord parser rejects.\n * Pass `{ applePlatform }` to force the platform (SSR, tests, a per-user preference).\n */\nexport function commandShortcutLabel(command: Command, options?: ChordPlatformOptions): string | undefined {\n  const shortcut = command.shortcut;\n  if (shortcut === undefined) return undefined;\n  try {\n    return formatChordString(shortcut, options);\n  } catch {\n    return shortcut;\n  }\n}\n","// The Vue subscription seam over a registry — how a component updates when commands come and go.\n//\n// The non-obvious part is why these track `registry.version()` instead of the command list directly: `list()` /\n// `available()` build a fresh array per call, so either as the tracked value would report a change on every\n// read. The monotonic version number is identity-stable between mutations, so it is what the subscription\n// mirrors into a `shallowRef`; the arrays are derived from it through a `computed` that touches the version.\n//\n// The subscription is attached in `onMounted` and dropped in `onScopeDispose`, matching every other subscription\n// in the port. Nothing here reads a platform global — a registry is plain in-memory state — so the SSR pass\n// reads a correct version rather than a placeholder; the mount hook exists for the listener alone.\n//\n// These composables take the registry explicitly (no injection), so a scoped palette can drive its own registry.\n// `CommandsContext.ts` provides the ambient-registry conveniences on top.\n\nimport { computed, onMounted, onScopeDispose, shallowRef, type ComputedRef, type ShallowRef } from 'vue';\n\nimport type { Command } from './Command';\nimport type { CommandRegistry } from './CommandRegistry';\n\n/**\n * Subscribes to a registry's mutations and returns its current version counter. The building block behind\n * {@link useCommandList} / {@link useAvailableCommands}; use it directly to derive a custom projection\n * (`computed(() => (version.value, registry.list().filter(mine)))`).\n */\nexport function useCommandRegistryVersion(registry: CommandRegistry): Readonly<ShallowRef<number>> {\n  const version = shallowRef(registry.version());\n\n  let unsubscribe: (() => void) | undefined;\n\n  onMounted(() => {\n    // Re-read first: a mutation between setup and mount would otherwise be missed entirely.\n    version.value = registry.version();\n    unsubscribe = registry.subscribe(() => {\n      version.value = registry.version();\n    });\n  });\n\n  onScopeDispose(() => {\n    unsubscribe?.();\n    unsubscribe = undefined;\n  });\n\n  return version;\n}\n\n/** Every registered command in insertion order, updating the caller whenever the registry mutates. */\nexport function useCommandList(registry: CommandRegistry): ComputedRef<readonly Command[]> {\n  const version = useCommandRegistryVersion(registry);\n  // `version` is the mutation cursor that invalidates the list — touched, then discarded.\n  return computed(() => {\n    void version.value;\n    return registry.list();\n  });\n}\n\n/**\n * The commands a palette should show — `available()` re-evaluated on every registry mutation.\n *\n * Availability also depends on whatever `when()` reads, and a registry mutation is the only trigger here: a\n * `when` predicate closing over unrelated state won't re-run on its own. Keep predicates over state the registry\n * sees (re-register on change — `useRegisterCommands` does this for you), not over free-floating variables.\n */\nexport function useAvailableCommands(registry: CommandRegistry): ComputedRef<readonly Command[]> {\n  const version = useCommandRegistryVersion(registry);\n  return computed(() => {\n    void version.value;\n    return registry.available();\n  });\n}\n","// Binds every available command that carries a `shortcut` to its chord, in one composable. This is the join\n// between the commands vector and `foundation/shortcuts`: the registry owns \"what can run\", `useHotkeyMap` owns\n// \"what the keyboard did\", and this composable keeps the two in sync as commands register and unregister.\n//\n// Non-obvious decisions:\n// - The map is a GETTER over `registry.available()` that touches the version cursor, so it is rebuilt on every\n//   registry mutation and a command whose `when()` starts failing loses its binding instead of firing invisibly.\n//   `useHotkeyMap` accepts a `MaybeRefOrGetter` map for exactly this shape.\n// - Two commands claiming the same chord collapse to one entry — last registered wins, matching the registry's\n//   own last-wins rule for duplicate ids. Object keys can't hold both, and silently binding only one is better\n//   than throwing while building the map.\n// - `context` and `onRun` are read through `toValue` at trigger time, so changing either needs no re-binding.\n// - Chord parsing is NOT duplicated here — the raw `shortcut` string is handed to `useHotkeyMap`, which parses it\n//   with the same `applePlatform` option `commandShortcutLabel` uses for display.\n\nimport { toValue, type MaybeRefOrGetter } from 'vue';\n\nimport { useHotkeyMap, type HotkeyOptions } from '../shortcuts';\n\nimport type { CommandContext } from './Command';\nimport type { CommandRegistry } from './CommandRegistry';\nimport { useCommandRegistryVersion } from './UseCommandRegistry';\n\n/** Tunes command-shortcut binding — every `useHotkeyMap` option, plus the payload passed to the command. */\nexport interface CommandShortcutOptions extends HotkeyOptions {\n  /** Forwarded to `registry.run(id, context)` on every trigger. Read live, so changing it needs no re-binding. */\n  readonly context?: MaybeRefOrGetter<CommandContext>;\n\n  /** Notified after a triggered command settles — the seam for closing a palette or logging the outcome. */\n  readonly onRun?: (id: string) => void;\n}\n\n/**\n * Binds the chord of every available command in `registry`, running the command on trigger. Re-binds whenever the\n * registry changes. Commands without a `shortcut`, and commands `when()`/`enabled` currently blocks, bind nothing.\n *\n * Failures are swallowed by design — `registry.run` never throws and routes errors to the registry's `onError`.\n */\nexport function useCommandShortcuts(registry: CommandRegistry, options?: CommandShortcutOptions): void {\n  const version = useCommandRegistryVersion(registry);\n\n  const trigger = (id: string): void => {\n    void registry.run(id, toValue(options?.context)).then(() => options?.onRun?.(id));\n  };\n\n  useHotkeyMap(() => {\n    // `version` is the mutation cursor that invalidates the map — touched, then discarded.\n    void version.value;\n    const bindings: Record<string, (event: KeyboardEvent) => void> = {};\n    for (const command of registry.available()) {\n      const shortcut = command.shortcut;\n      if (shortcut === undefined) continue;\n      const id = command.id;\n      bindings[shortcut] = () => trigger(id);\n    }\n    return bindings;\n  }, options);\n}\n","// The Vue seam — an ambient registry so a screen deep in the tree can contribute commands without threading a\n// registry through props, following the repo's `LocaleContext` / `DirectionContext` provide + inject shape.\n//\n// Non-obvious decisions:\n// - `useCommands` THROWS without a provider, where `useLocale` falls back to a default. A locale has a sane\n//   default (`en-US`); a registry does not — a silent fallback would accept registrations into a throwaway store\n//   and the palette would just be empty, which is far harder to debug than a named error.\n// - `useRegisterCommands` keys its watcher on a CONTENT signature of the commands, never on array identity. The\n//   React original needed that to avoid an infinite register → notify → re-render → register loop; here it earns\n//   its place for a plainer reason: a `computed` array rebuilt on an unrelated dependency would otherwise churn\n//   the registry (and the palette's row order) for no change the user could see.\n// - Because the watcher skips identity changes, the entries it registers delegate `run` / `when` back through\n//   `toValue` to the LATEST value of the caller's source. Without that, a handler closing over reactive state\n//   would be frozen at the value that last changed the signature. Text metadata is part of the signature, so it\n//   re-registers when it changes; behaviour is always live. Net effect: the caller memoizes nothing.\n// - The signature is built with `JSON.stringify`, not a delimiter join: JSON quoting makes each field\n//   self-delimiting, so a title containing the delimiter can't forge a boundary and alias two different sets.\n// - Nothing here touches a platform global, so the registration watcher is `immediate` — a server-rendered\n//   palette lists the commands its subtree registered, exactly as the client does.\n\nimport {\n  computed,\n  inject,\n  provide,\n  toValue,\n  watch,\n  type ComputedRef,\n  type InjectionKey,\n  type MaybeRefOrGetter,\n} from 'vue';\n\nimport { isCommandAvailable, type Command } from './Command';\nimport { createCommandRegistry, type CommandErrorHandler, type CommandRegistry } from './CommandRegistry';\nimport { useCommandRegistryVersion } from './UseCommandRegistry';\n\n/** The injection key — React's `createContext(undefined)` becomes a key plus an explicit throw at the read site. */\nexport const CommandsKey: InjectionKey<CommandRegistry> = Symbol('wow-two.commands');\n\n/**\n * The provider half — used by `CommandsProvider`, and by any component that owns a registry.\n *\n * @param registry An existing registry to share (module-scope singleton, a test's registry). Omitted → one is\n *   created and owned here.\n * @param onError Where a failing command's error goes. Read live, and ignored when `registry` is supplied —\n *   that registry carries its own handler.\n * @returns The registry that was provided.\n */\nexport function provideCommands(\n  registry?: MaybeRefOrGetter<CommandRegistry | undefined>,\n  onError?: MaybeRefOrGetter<CommandErrorHandler | undefined>,\n): CommandRegistry {\n  // Read live so a fresh `onError` closure is picked up without rebuilding the registry.\n  const owned = createCommandRegistry({\n    onError: (error, command) => toValue(onError)?.(error, command),\n  });\n  const resolved = toValue(registry) ?? owned;\n  provide(CommandsKey, resolved);\n  return resolved;\n}\n\n/** Reads the ambient registry. Throws when no {@link CommandsKey} provider is mounted — see the file header. */\nexport function useCommands(): CommandRegistry {\n  const registry = inject(CommandsKey, undefined);\n  if (registry === undefined) {\n    throw new Error('useCommands must be used inside a <CommandsProvider>');\n  }\n  return registry;\n}\n\n/**\n * Reads one command from the ambient registry by id, updating when that command is registered, replaced, or\n * removed. `undefined` while nothing owns the id — a palette row can render a disabled placeholder from it.\n */\nexport function useCommand(id: MaybeRefOrGetter<string>): ComputedRef<Command | undefined> {\n  const registry = useCommands();\n  const version = useCommandRegistryVersion(registry);\n  // `get` returns the stored object, whose identity is stable between mutations; `version` is the cursor that\n  // says when to look again.\n  return computed(() => {\n    void version.value;\n    return registry.get(toValue(id));\n  });\n}\n\n/**\n * Builds the content key that decides when a registration is stale — every searchable / rendered text field plus\n * `enabled`. `run`, `when`, and `icon` are excluded (functions and opaque slots don't serialize); they stay fresh\n * through {@link bindToLatest} instead.\n */\nfunction metadataSignature(command: Command): string {\n  return JSON.stringify([\n    command.id,\n    command.title,\n    command.description ?? '',\n    command.group ?? '',\n    command.keywords ?? [],\n    command.shortcut ?? '',\n    command.enabled !== false,\n  ]);\n}\n\n/**\n * Wraps a command so `run` / `when` resolve against the latest value of the caller's source rather than the\n * snapshot captured when the watcher last ran. Metadata comes from the snapshot — it is covered by the\n * signature, so it can't drift.\n */\nfunction bindToLatest(command: Command, latest: MaybeRefOrGetter<readonly Command[]>): Command {\n  const id = command.id;\n  const resolve = (): Command | undefined => toValue(latest).find((candidate) => candidate.id === id);\n  return {\n    ...command,\n    when: () => {\n      const current = resolve();\n      // Gone from the caller's array but not yet unregistered (mid-cleanup) → treat as unavailable.\n      return current !== undefined && isCommandAvailable(current);\n    },\n    run: (context) => resolve()?.run(context),\n  };\n}\n\n/**\n * Registers commands for as long as the calling scope lives, unregistering when it is disposed. The array may be\n * an inline literal, a ref, or a getter — registration re-runs when the commands' text metadata changes, and\n * `run` / `when` always call through to the latest value.\n *\n * Pass `registry` to target a specific registry; otherwise the ambient one is used (and a missing provider throws).\n */\nexport function useRegisterCommands(\n  commands: MaybeRefOrGetter<readonly Command[]>,\n  registry?: CommandRegistry,\n): void {\n  const target = registry ?? inject(CommandsKey, undefined);\n  if (target === undefined) {\n    throw new Error('useRegisterCommands must be used inside a <CommandsProvider>, or given an explicit registry');\n  }\n\n  // The content-stable key standing in for the array — see the file header on why identity fails.\n  const signature = computed(() => toValue(commands).map(metadataSignature).join(''));\n\n  watch(\n    signature,\n    (_next, _previous, onCleanup) => {\n      const dispose = target.registerAll(\n        toValue(commands).map((command) => bindToLatest(command, commands)),\n      );\n      onCleanup(dispose);\n    },\n    { immediate: true },\n  );\n}\n","<script lang=\"ts\">\nimport type { CommandErrorHandler, CommandRegistry } from './CommandRegistry';\n\n/** Props for `CommandsProvider`. */\nexport interface CommandsProviderProps {\n  /** An existing registry to share (module-scope singleton, a test's registry). Omitted → the provider owns one. */\n  registry?: CommandRegistry;\n\n  /** Where a failing command's error goes. Ignored when `registry` is supplied — that registry carries its own handler. */\n  onError?: CommandErrorHandler;\n}\n</script>\n\n<script setup lang=\"ts\">\nimport { provideCommands } from './CommandsContext';\n\n/**\n * Provides a command registry to every descendant — the mount point for `useCommands` / `useRegisterCommands`.\n *\n * Renders no element of its own — the slot passes straight through. A component that already owns a registry can\n * call `provideCommands` directly instead of wrapping its subtree in this.\n */\ndefineOptions({ name: 'CommandsProvider' });\n\nconst props = defineProps<CommandsProviderProps>();\n\nprovideCommands(\n  () => props.registry,\n  () => props.onError,\n);\n</script>\n\n<template>\n  <slot />\n</template>\n"],"names":["_renderSlot"],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/commands/Command.ts","../../../src/foundation/commands/CommandRunFailureCode.ts","../../../src/foundation/commands/CommandRegistry.ts","../../../src/foundation/commands/SearchCommands.ts","../../../src/foundation/commands/CommandShortcut.ts","../../../src/foundation/commands/hooks/UseCommandRegistry.ts","../../../src/foundation/commands/hooks/UseCommandShortcuts.ts","../../../src/foundation/commands/providers/CommandsContext.ts","../../../src/foundation/commands/providers/CommandsProvider.vue"],"sourcesContent":["// The command contract — the pure, framework-free vocabulary of the commands vector. A `Command` is one\n// invocable action (`file.save`, `nav.settings`) carrying everything a palette, menu, or keybinding layer needs\n// to present and run it: identity, label, extra search terms, an optional chord, and an availability predicate.\n//\n// Two deliberate type choices keep the command payload independent of presentation:\n// - `icon` is `unknown`. Naming a Vue icon component type here would drag presentation into foundation; the\n//   render site knows its own icon library and casts (`command.icon as Component`).\n// - `context` is `unknown` rather than a generic parameter. Making `Command<TContext>` generic would force the\n//   registry, the search, and every composable generic too, for a payload that only the app's own `run` reads back.\n//\n// Registry mechanics (register / run / subscribe) live in `CommandRegistry.ts`; this file stays a vocabulary.\n\nimport type { Result } from '../results';\n\n/** The opaque payload handed to a command's `run` — apps narrow it inside their own handler (`ctx as MyCtx`). */\nexport type CommandContext = unknown;\n\n/** Describes one invocable action — the unit a palette lists, a menu renders, and a chord triggers. */\nexport interface Command {\n  /** The stable identity. Re-registering the same `id` replaces the prior entry, so keep it constant across renders. */\n  readonly id: string;\n\n  /** The human label — the primary search field and the text a palette row shows. */\n  readonly title: string;\n\n  /** Optional supporting text for the row. Deliberately NOT searched: a long description matches nearly every query. */\n  readonly description?: string;\n\n  /** Optional grouping label (`Navigation`, `Editor`) — used for section headers and searched at the lowest rank. */\n  readonly group?: string;\n\n  /** Extra search terms that don't belong in the title (`['theme', 'appearance']` for \"Toggle dark mode\"). */\n  readonly keywords?: ReadonlyArray<string>;\n\n  /**\n   * Optional chord string in `foundation/shortcuts` syntax (`'mod+k'`) — bound by `useCommandShortcuts`,\n   * rendered by `commandShortcutLabel`.\n   */\n  readonly shortcut?: string;\n\n  /** Optional icon slot, intentionally untyped — the render site casts it to its icon component type. */\n  readonly icon?: unknown;\n\n  /**\n   * Availability predicate re-evaluated on every read. Must be cheap and side-effect free (`available()` calls it\n   * per command).\n   */\n  readonly when?: () => boolean;\n\n  /** Hard off-switch — `false` hides the command from `available()` regardless of `when`. Defaults to `true`. */\n  readonly enabled?: boolean;\n\n  /** Expected failures return Result; total handlers may return void. Programmer exceptions remain exceptional. */\n  readonly run: (context?: CommandContext) => void | Result | Promise<void | Result>;\n}\n\n/**\n * Reports whether a command may run right now — `enabled !== false` **and** `when()` (when present) passing.\n * Exported so a surface holding a plain array (not a registry) applies the same rule the registry does.\n * Programmer exceptions from a broken predicate propagate; registry execution reports them before rejecting.\n */\nexport function isCommandAvailable(command: Command): boolean {\n  if (command.enabled === false) return false;\n  return command.when === undefined || command.when();\n}\n","/** Expected reasons a command did not complete. */\nexport const CommandRunFailureCode = {\n  NotFound: 'notFound',\n  Unavailable: 'unavailable',\n  Failed: 'failed',\n} as const;\n\nexport type CommandRunFailureCode = (typeof CommandRunFailureCode)[keyof typeof CommandRunFailureCode];\n","// The registry — the headless core of the commands vector: a mutable, insertion-ordered `id → Command` store that\n// a palette, menu, or keybinding layer reads from. Framework-free on purpose (no Vue import) so one can be\n// created at module scope, inside a provider, or in a plain node test.\n//\n// Non-obvious decisions:\n// - Re-registering an existing `id` REPLACES the entry (last wins) and keeps its ORIGINAL position in `list()`.\n//   A `Map.set` on an existing key doesn't move it, which is what we want: a re-registration refreshing a command\n//   must not make the palette's rows jump around.\n// - A `register` disposer removes only the entry it registered. A stale disposer firing after a replace is a\n//   no-op — exactly what an effect cleanup racing a re-registration needs (cleanup runs after the next register).\n// - Expected missing/blocked/handler failures resolve to CommandRunResult. Programmer exceptions from\n//   predicates or handlers are reported to onError, then reject instead of masquerading as recoverable failures.\n// - Mutations bump a monotonic `version()` on top of notifying listeners. A subscribing composable needs a\n//   snapshot whose identity is stable between mutations; `list()` / `available()` build fresh arrays every call\n//   and would look changed on every read. The version number is the stable cursor those composables read instead.\n// - `registerAll` applies every entry then notifies ONCE, so registering a screen's ten commands wakes\n//   subscribers a single time.\n\nimport { ResultExtensions } from '../results';\nimport { CommandRunFailureCode } from './CommandRunFailureCode';\nimport type { CommandRunResult } from './models/CommandRunResult';\n\nimport { isCommandAvailable, type Command, type CommandContext } from './Command';\n\n/** Receives an error thrown or rejected by a command's `run` (or its `when` predicate), with the offending command. */\nexport type CommandErrorHandler = (error: unknown, command: Command) => void;\n\n/** Notified after any registry mutation — register, replace, or unregister. No payload; re-read the registry. */\nexport type CommandRegistryListener = () => void;\n\n/** Tunes a registry at creation. */\nexport interface CommandRegistryOptions {\n  /** Reports a programmer exception before the run promise rejects with it. */\n  readonly onError?: CommandErrorHandler;\n}\n\n/** The headless command store — registration, lookup, availability, execution, and change notification. */\nexport interface CommandRegistry {\n  /** Registers (or replaces, when the `id` exists) a command; returns a disposer removing exactly this entry. */\n  readonly register: (command: Command) => () => void;\n\n  /** Registers many commands with a single change notification; returns one disposer removing all of them. */\n  readonly registerAll: (commands: ReadonlyArray<Command>) => () => void;\n\n  /** Removes the command under `id`; returns whether anything was removed. */\n  readonly unregister: (id: string) => boolean;\n\n  /** Looks up a command by id — `undefined` when absent. Identity is stable between mutations (safe to snapshot). */\n  readonly get: (id: string) => Command | undefined;\n\n  /** Every registered command in insertion order (a replaced entry keeps its original slot). Fresh array per call. */\n  readonly list: () => readonly Command[];\n\n  /** The subset of `list()` that `isCommandAvailable` accepts — what a palette should show. Fresh array per call. */\n  readonly available: () => readonly Command[];\n\n  /** Executes a command by id. Expected failures return Result; programmer errors reject after reporting. */\n  readonly run: (id: string, context?: CommandContext) => Promise<CommandRunResult>;\n\n  /** Subscribes to mutations; returns an unsubscribe. */\n  readonly subscribe: (listener: CommandRegistryListener) => () => void;\n\n  /** A monotonic counter bumped on every mutation — the stable-identity snapshot the composables subscribe to. */\n  readonly version: () => number;\n}\n\n/**\n * Creates a {@link CommandRegistry}. One per app is the norm (a `CommandsProvider` owns it); create extra ones for\n * isolation in tests or for a scoped palette that must not see the global set.\n */\nexport function createCommandRegistry(options?: CommandRegistryOptions): CommandRegistry {\n  const entries = new Map<string, Command>();\n  const listeners = new Set<CommandRegistryListener>();\n  let revision = 0;\n\n  /** Bumps the version then fans out to listeners over a copy, so a listener may unsubscribe while being notified. */\n  function notify(): void {\n    revision += 1;\n    for (const listener of [...listeners]) listener();\n  }\n\n  /** Removes `command` only if it is still the entry under its id; reports whether it removed anything. */\n  function removeExact(command: Command): boolean {\n    if (entries.get(command.id) !== command) return false;\n    entries.delete(command.id);\n    return true;\n  }\n\n  return {\n    register(command: Command): () => void {\n      entries.set(command.id, command);\n      notify();\n      return () => {\n        if (removeExact(command)) notify();\n      };\n    },\n\n    registerAll(commands: ReadonlyArray<Command>): () => void {\n      const registered = [...commands];\n      for (const command of registered) entries.set(command.id, command);\n      notify();\n      return () => {\n        let removed = false;\n        for (const command of registered) removed = removeExact(command) || removed;\n        if (removed) notify();\n      };\n    },\n\n    unregister(id: string): boolean {\n      if (!entries.delete(id)) return false;\n      notify();\n      return true;\n    },\n\n    get(id: string): Command | undefined {\n      return entries.get(id);\n    },\n\n    list(): ReadonlyArray<Command> {\n      return [...entries.values()];\n    },\n\n    available(): ReadonlyArray<Command> {\n      return [...entries.values()].filter(isCommandAvailable);\n    },\n\n    async run(id: string, context?: CommandContext): Promise<CommandRunResult> {\n      const command = entries.get(id);\n      if (command === undefined) return ResultExtensions.fail({ code: CommandRunFailureCode.NotFound });\n      try {\n        // A predicate bug is reported with the same command context as a handler bug.\n        if (!isCommandAvailable(command)) return ResultExtensions.fail({ code: CommandRunFailureCode.Unavailable });\n        const result = await command.run(context);\n        return result === undefined || result.ok\n          ? ResultExtensions.ok(undefined)\n          : ResultExtensions.fail({ code: CommandRunFailureCode.Failed, error: result.failure });\n      } catch (error) {\n        options?.onError?.(error, command);\n        throw error;\n      }\n    },\n\n    subscribe(listener: CommandRegistryListener): () => void {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n\n    version(): number {\n      return revision;\n    },\n  };\n}\n","// Search + ranking — the pure half of a palette's filter box. Kept out of the registry so any list can be ranked\n// (a static array, a scoped subset, an app set merged with the SDK's) without owning a registry, and so the\n// ranking is testable without mounting anything.\n//\n// Non-obvious decisions:\n// - Matching covers `title`, `keywords`, and `group` only. `description` is deliberately excluded: a sentence-long\n//   description matches almost any short query, which floods the list and destroys the ranking.\n// - Ranking is tiered, not fuzzy. Fuzzy scoring reorders rows unpredictably as the user types; four ordered tiers\n//   (title prefix → title substring → keyword → group) stay legible and cheap.\n// - Ties keep the caller's original order — the sort is explicitly stabilized on the source index rather than\n//   relying on engine sort stability, so a palette's rows never reshuffle between keystrokes.\n// - An empty (or whitespace-only) query returns the SAME array reference it was given, so a `useMemo`d caller\n//   doesn't churn on the common \"nothing typed yet\" path.\n\nimport type { Command } from './Command';\n\n/** The rank of a command the query excludes — compare against this to test a match. */\nexport const NoMatch = Number.POSITIVE_INFINITY;\n\n/** The tier a match landed in — lower sorts first. Exported so a surface can label or style a match by its origin. */\nexport const CommandMatchRank = {\n  /** The title starts with the query — the strongest signal. */\n  TitlePrefix: 0,\n  /** The title contains the query somewhere after the start. */\n  TitleSubstring: 1,\n  /** One of the `keywords` contains the query. */\n  Keyword: 2,\n  /** The `group` label contains the query — the weakest signal. */\n  Group: 3,\n} as const;\n\nexport type CommandMatchRank = (typeof CommandMatchRank)[keyof typeof CommandMatchRank];\n\n/**\n * Scores one command against a query — a {@link CommandMatchRank} when it matches, {@link NoMatch} when it\n * doesn't. Case-insensitive; the query is trimmed. An empty query matches everything at the best rank.\n */\nexport function rankCommand(command: Command, query: string): number {\n  const needle = query.trim().toLowerCase();\n  if (needle === '') return CommandMatchRank.TitlePrefix;\n\n  const title = command.title.toLowerCase();\n  if (title.startsWith(needle)) return CommandMatchRank.TitlePrefix;\n  if (title.includes(needle)) return CommandMatchRank.TitleSubstring;\n\n  const keywords = command.keywords;\n  if (keywords !== undefined && keywords.some((keyword) => keyword.toLowerCase().includes(needle))) {\n    return CommandMatchRank.Keyword;\n  }\n\n  const group = command.group;\n  if (group !== undefined && group.toLowerCase().includes(needle)) return CommandMatchRank.Group;\n\n  return NoMatch;\n}\n\n/**\n * Filters and ranks commands for a palette's search box. Non-matching commands are dropped; matches sort by\n * {@link CommandMatchRank}, ties keeping their original relative order. An empty / whitespace-only query returns\n * the input untouched (same reference, original order).\n *\n * Availability is NOT applied here — pass `registry.available()` when the palette should hide blocked commands.\n */\nexport function searchCommands(commands: ReadonlyArray<Command>, query: string): ReadonlyArray<Command> {\n  if (query.trim() === '') return commands;\n\n  const matches: { readonly command: Command; readonly rank: number; readonly index: number }[] = [];\n  commands.forEach((command, index) => {\n    const rank = rankCommand(command, query);\n    if (rank !== NoMatch) matches.push({ command, rank, index });\n  });\n\n  matches.sort((left, right) => left.rank - right.rank || left.index - right.index);\n  return matches.map((match) => match.command);\n}\n","// The display half of a command's shortcut. A palette row shows `⌘K` / `Ctrl+K` next to the title; without this\n// helper every surface would re-derive that label from the raw `'mod+k'` string and eventually drift from what\n// `useCommandShortcuts` actually binds. Delegating to `foundation/shortcuts`' `formatChordString` keeps the label\n// and the binding on one parser, including the platform split (`mod` → ⌘ on Apple, Ctrl elsewhere).\n//\n// An unparseable chord degrades to the raw string instead of throwing: a typo'd shortcut should render oddly, not\n// crash the palette rendering it. The error still surfaces loudly the moment the chord is bound.\n\nimport { formatChordString, type ChordPlatformOptions } from '../shortcuts';\n\nimport type { Command } from './Command';\n\n/**\n * Renders a command's shortcut for display (`'mod+k'` → `⌘K` on Apple, `Ctrl+K` elsewhere). Returns `undefined`\n * when the command carries no shortcut, and the raw string when it carries one the chord parser rejects.\n * Pass `{ applePlatform }` to force the platform (SSR, tests, a per-user preference).\n */\nexport function commandShortcutLabel(command: Command, options?: ChordPlatformOptions): string | undefined {\n  const shortcut = command.shortcut;\n  if (shortcut === undefined) return undefined;\n  try {\n    return formatChordString(shortcut, options);\n  } catch {\n    return shortcut;\n  }\n}\n","// The Vue subscription seam over a registry — how a component updates when commands come and go.\n//\n// The non-obvious part is why these track `registry.version()` instead of the command list directly: `list()` /\n// `available()` build a fresh array per call, so either as the tracked value would report a change on every\n// read. The monotonic version number is identity-stable between mutations, so it is what the subscription\n// mirrors into a `shallowRef`; the arrays are derived from it through a `computed` that touches the version.\n//\n// The subscription is attached in `onMounted` and dropped in `onScopeDispose`, matching every other subscription\n// in the port. Nothing here reads a platform global — a registry is plain in-memory state — so the SSR pass\n// reads a correct version rather than a placeholder; the mount hook exists for the listener alone.\n//\n// These composables take the registry explicitly (no injection), so a scoped palette can drive its own registry.\n// `CommandsContext.ts` provides the ambient-registry conveniences on top.\n\nimport { computed, onMounted, onScopeDispose, shallowRef, type ComputedRef, type ShallowRef } from 'vue';\n\nimport type { Command } from '../Command';\nimport type { CommandRegistry } from '../CommandRegistry';\n\n/**\n * Subscribes to a registry's mutations and returns its current version counter. The building block behind\n * {@link useCommandList} / {@link useAvailableCommands}; use it directly to derive a custom projection\n * (`computed(() => (version.value, registry.list().filter(mine)))`).\n */\nexport function useCommandRegistryVersion(registry: CommandRegistry): Readonly<ShallowRef<number>> {\n  const version = shallowRef(registry.version());\n\n  let unsubscribe: (() => void) | undefined;\n\n  onMounted(() => {\n    // Re-read first: a mutation between setup and mount would otherwise be missed entirely.\n    version.value = registry.version();\n    unsubscribe = registry.subscribe(() => {\n      version.value = registry.version();\n    });\n  });\n\n  onScopeDispose(() => {\n    unsubscribe?.();\n    unsubscribe = undefined;\n  });\n\n  return version;\n}\n\n/** Every registered command in insertion order, updating the caller whenever the registry mutates. */\nexport function useCommandList(registry: CommandRegistry): ComputedRef<ReadonlyArray<Command>> {\n  const version = useCommandRegistryVersion(registry);\n  // `version` is the mutation cursor that invalidates the list — touched, then discarded.\n  return computed(() => {\n    void version.value;\n    return registry.list();\n  });\n}\n\n/**\n * The commands a palette should show — `available()` re-evaluated on every registry mutation.\n *\n * Availability also depends on whatever `when()` reads, and a registry mutation is the only trigger here: a\n * `when` predicate closing over unrelated state won't re-run on its own. Keep predicates over state the registry\n * sees (re-register on change — `useRegisterCommands` does this for you), not over free-floating variables.\n */\nexport function useAvailableCommands(registry: CommandRegistry): ComputedRef<ReadonlyArray<Command>> {\n  const version = useCommandRegistryVersion(registry);\n  return computed(() => {\n    void version.value;\n    return registry.available();\n  });\n}\n","// Binds every available command that carries a `shortcut` to its chord, in one composable. This is the join\n// between the commands vector and `foundation/shortcuts`: the registry owns \"what can run\", `useHotkeyMap` owns\n// \"what the keyboard did\", and this composable keeps the two in sync as commands register and unregister.\n//\n// Non-obvious decisions:\n// - The map is a GETTER over `registry.available()` that touches the version cursor, so it is rebuilt on every\n//   registry mutation and a command whose `when()` starts failing loses its binding instead of firing invisibly.\n//   `useHotkeyMap` accepts a `MaybeRefOrGetter` map for exactly this shape.\n// - Two commands claiming the same chord collapse to one entry — last registered wins, matching the registry's\n//   own last-wins rule for duplicate ids. Object keys can't hold both, and silently binding only one is better\n//   than throwing while building the map.\n// - `context` and `onRun` are read through `toValue` at trigger time, so changing either needs no re-binding.\n// - Chord parsing is NOT duplicated here — the raw `shortcut` string is handed to `useHotkeyMap`, which parses it\n//   with the same `applePlatform` option `commandShortcutLabel` uses for display.\n\nimport { toValue, type MaybeRefOrGetter } from 'vue';\n\nimport { useHotkeyMap, type HotkeyOptions } from '../../shortcuts';\n\nimport type { CommandContext } from '../Command';\nimport type { CommandRegistry } from '../CommandRegistry';\nimport { useCommandRegistryVersion } from './UseCommandRegistry';\n\n/** Tunes command-shortcut binding — every `useHotkeyMap` option, plus the payload passed to the command. */\nexport interface CommandShortcutOptions extends HotkeyOptions {\n  /** Forwarded to `registry.run(id, context)` on every trigger. Read live, so changing it needs no re-binding. */\n  readonly context?: MaybeRefOrGetter<CommandContext>;\n\n  /** Notified after a triggered command settles — the seam for closing a palette or logging the outcome. */\n  readonly onRun?: (id: string) => void;\n}\n\n/**\n * Binds the chord of every available command in `registry`, running the command on trigger. Re-binds whenever the\n * registry changes. Commands without a `shortcut`, and commands `when()`/`enabled` currently blocks, bind nothing.\n *\n * Expected failures settle normally; programmer exceptions are reported by the registry and remain rejected.\n */\nexport function useCommandShortcuts(registry: CommandRegistry, options?: CommandShortcutOptions): void {\n  const version = useCommandRegistryVersion(registry);\n\n  const trigger = (id: string): void => {\n    void registry.run(id, toValue(options?.context)).then(() => options?.onRun?.(id));\n  };\n\n  useHotkeyMap(() => {\n    // `version` is the mutation cursor that invalidates the map — touched, then discarded.\n    void version.value;\n    const bindings: Record<string, (event: KeyboardEvent) => void> = {};\n    for (const command of registry.available()) {\n      const shortcut = command.shortcut;\n      if (shortcut === undefined) continue;\n      const id = command.id;\n      bindings[shortcut] = () => trigger(id);\n    }\n    return bindings;\n  }, options);\n}\n","// The Vue seam — an ambient registry so a screen deep in the tree can contribute commands without threading a\n// registry through props, following the repo's `LocaleContext` / `DirectionContext` provide + inject shape.\n//\n// Non-obvious decisions:\n// - `useCommands` THROWS without a provider, where `useLocale` falls back to a default. A locale has a sane\n//   default (`en-US`); a registry does not — a silent fallback would accept registrations into a throwaway store\n//   and the palette would just be empty, which is far harder to debug than a named error.\n// - `useRegisterCommands` keys its watcher on a CONTENT signature of the commands, never on array identity. The\n//   React original needed that to avoid an infinite register → notify → re-render → register loop; here it earns\n//   its place for a plainer reason: a `computed` array rebuilt on an unrelated dependency would otherwise churn\n//   the registry (and the palette's row order) for no change the user could see.\n// - Because the watcher skips identity changes, the entries it registers delegate `run` / `when` back through\n//   `toValue` to the LATEST value of the caller's source. Without that, a handler closing over reactive state\n//   would be frozen at the value that last changed the signature. Text metadata is part of the signature, so it\n//   re-registers when it changes; behaviour is always live. Net effect: the caller memoizes nothing.\n// - The signature is built with `JSON.stringify`, not a delimiter join: JSON quoting makes each field\n//   self-delimiting, so a title containing the delimiter can't forge a boundary and alias two different sets.\n// - Nothing here touches a platform global, so the registration watcher is `immediate` — a server-rendered\n//   palette lists the commands its subtree registered, exactly as the client does.\n\nimport {\n  computed,\n  inject,\n  provide,\n  toValue,\n  watch,\n  type ComputedRef,\n  type InjectionKey,\n  type MaybeRefOrGetter,\n} from 'vue';\n\nimport { isCommandAvailable, type Command } from '../Command';\nimport { createCommandRegistry, type CommandErrorHandler, type CommandRegistry } from '../CommandRegistry';\nimport { useCommandRegistryVersion } from '../hooks/UseCommandRegistry';\n\n/** The injection key — React's `createContext(undefined)` becomes a key plus an explicit throw at the read site. */\nexport const CommandsKey: InjectionKey<CommandRegistry> = Symbol('wow-two.commands');\n\n/**\n * The provider half — used by `CommandsProvider`, and by any component that owns a registry.\n *\n * @param registry An existing registry to share (module-scope singleton, a test's registry). Omitted → one is\n *   created and owned here.\n * @param onError Where a failing command's error goes. Read live, and ignored when `registry` is supplied —\n *   that registry carries its own handler.\n * @returns The registry that was provided.\n */\nexport function provideCommands(\n  registry?: MaybeRefOrGetter<CommandRegistry | undefined>,\n  onError?: MaybeRefOrGetter<CommandErrorHandler | undefined>,\n): CommandRegistry {\n  // Read live so a fresh `onError` closure is picked up without rebuilding the registry.\n  const owned = createCommandRegistry({\n    onError: (error, command) => toValue(onError)?.(error, command),\n  });\n  const resolved = toValue(registry) ?? owned;\n  provide(CommandsKey, resolved);\n  return resolved;\n}\n\n/** Reads the ambient registry. Throws when no {@link CommandsKey} provider is mounted — see the file header. */\nexport function useCommands(): CommandRegistry {\n  const registry = inject(CommandsKey, undefined);\n  if (registry === undefined) {\n    throw new Error('useCommands must be used inside a <CommandsProvider>');\n  }\n  return registry;\n}\n\n/**\n * Reads one command from the ambient registry by id, updating when that command is registered, replaced, or\n * removed. `undefined` while nothing owns the id — a palette row can render a disabled placeholder from it.\n */\nexport function useCommand(id: MaybeRefOrGetter<string>): ComputedRef<Command | undefined> {\n  const registry = useCommands();\n  const version = useCommandRegistryVersion(registry);\n  // `get` returns the stored object, whose identity is stable between mutations; `version` is the cursor that\n  // says when to look again.\n  return computed(() => {\n    void version.value;\n    return registry.get(toValue(id));\n  });\n}\n\n/**\n * Builds the content key that decides when a registration is stale — every searchable / rendered text field plus\n * `enabled`. `run`, `when`, and `icon` are excluded (functions and opaque slots don't serialize); they stay fresh\n * through {@link bindToLatest} instead.\n */\nfunction metadataSignature(command: Command): string {\n  return JSON.stringify([\n    command.id,\n    command.title,\n    command.description ?? '',\n    command.group ?? '',\n    command.keywords ?? [],\n    command.shortcut ?? '',\n    command.enabled !== false,\n  ]);\n}\n\n/**\n * Wraps a command so `run` / `when` resolve against the latest value of the caller's source rather than the\n * snapshot captured when the watcher last ran. Metadata comes from the snapshot — it is covered by the\n * signature, so it can't drift.\n */\nfunction bindToLatest(command: Command, latest: MaybeRefOrGetter<ReadonlyArray<Command>>): Command {\n  const id = command.id;\n  const resolve = (): Command | undefined => toValue(latest).find((candidate) => candidate.id === id);\n  return {\n    ...command,\n    when: () => {\n      const current = resolve();\n      // Gone from the caller's array but not yet unregistered (mid-cleanup) → treat as unavailable.\n      return current !== undefined && isCommandAvailable(current);\n    },\n    run: (context) => resolve()?.run(context),\n  };\n}\n\n/**\n * Registers commands for as long as the calling scope lives, unregistering when it is disposed. The array may be\n * an inline literal, a ref, or a getter — registration re-runs when the commands' text metadata changes, and\n * `run` / `when` always call through to the latest value.\n *\n * Pass `registry` to target a specific registry; otherwise the ambient one is used (and a missing provider throws).\n */\nexport function useRegisterCommands(\n  commands: MaybeRefOrGetter<ReadonlyArray<Command>>,\n  registry?: CommandRegistry,\n): void {\n  const target = registry ?? inject(CommandsKey, undefined);\n  if (target === undefined) {\n    throw new Error('useRegisterCommands must be used inside a <CommandsProvider>, or given an explicit registry');\n  }\n\n  // The content-stable key standing in for the array — see the file header on why identity fails.\n  const signature = computed(() => toValue(commands).map(metadataSignature).join(''));\n\n  watch(\n    signature,\n    (_next, _previous, onCleanup) => {\n      const dispose = target.registerAll(toValue(commands).map((command) => bindToLatest(command, commands)));\n      onCleanup(dispose);\n    },\n    { immediate: true },\n  );\n}\n","<script lang=\"ts\">\nimport type { CommandErrorHandler, CommandRegistry } from '../CommandRegistry';\n\n/** Props for `CommandsProvider`. */\nexport interface CommandsProviderProps {\n  /** An existing registry to share (module-scope singleton, a test's registry). Omitted → the provider owns one. */\n  readonly registry?: CommandRegistry;\n\n  /** Where a failing command's error goes. Ignored when `registry` is supplied — it carries its own handler. */\n  readonly onError?: CommandErrorHandler;\n}\n</script>\n\n<script setup lang=\"ts\">\nimport { provideCommands } from './CommandsContext';\n\n/**\n * Renders no element of its own — the slot passes straight through — while providing a command registry to every\n * descendant, the mount point for `useCommands` / `useRegisterCommands`.\n *\n * A component that already owns a registry can call `provideCommands` directly instead of wrapping its subtree\n * in this.\n */\ndefineOptions({ name: 'CommandsProvider' });\n\nconst props = defineProps<CommandsProviderProps>();\n\ndefineSlots<{\n  /** The subtree that reads the provided command registry. */\n  default(): unknown;\n}>();\n\nprovideCommands(\n  () => props.registry,\n  () => props.onError,\n);\n</script>\n\n<template>\n  <slot />\n</template>\n"],"names":["_renderSlot"],"mappings":"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"}

package/dist/foundation/commands/models/CommandRunFailure.d.ts

@@ -0,0 +1,11 @@
+import { AppError } from '../../results';
+import { CommandRunFailureCode } from '../CommandRunFailureCode';
+/** Distinguishes registry availability failures from an explicitly reported handler failure. */
+export type CommandRunFailure = {
+    readonly code: typeof CommandRunFailureCode.NotFound;
+} | {
+    readonly code: typeof CommandRunFailureCode.Unavailable;
+} | {
+    readonly code: typeof CommandRunFailureCode.Failed;
+    readonly error: AppError;
+};

package/dist/foundation/commands/models/CommandRunResult.d.ts

@@ -0,0 +1,4 @@
+import { Result } from '../../results';
+import { CommandRunFailure } from './CommandRunFailure';
+/** The completed operation, carrying either its value or its typed failure. */
+export type CommandRunResult = Result<void, CommandRunFailure>;

package/dist/foundation/commands/providers/CommandsContext.d.ts

@@ -0,0 +1,30 @@
+import { ComputedRef, InjectionKey, MaybeRefOrGetter } from 'vue';
+import { Command } from '../Command';
+import { CommandErrorHandler, CommandRegistry } from '../CommandRegistry';
+/** The injection key — React's `createContext(undefined)` becomes a key plus an explicit throw at the read site. */
+export declare const CommandsKey: InjectionKey<CommandRegistry>;
+/**
+ * The provider half — used by `CommandsProvider`, and by any component that owns a registry.
+ *
+ * @param registry An existing registry to share (module-scope singleton, a test's registry). Omitted → one is
+ *   created and owned here.
+ * @param onError Where a failing command's error goes. Read live, and ignored when `registry` is supplied —
+ *   that registry carries its own handler.
+ * @returns The registry that was provided.
+ */
+export declare function provideCommands(registry?: MaybeRefOrGetter<CommandRegistry | undefined>, onError?: MaybeRefOrGetter<CommandErrorHandler | undefined>): CommandRegistry;
+/** Reads the ambient registry. Throws when no {@link CommandsKey} provider is mounted — see the file header. */
+export declare function useCommands(): CommandRegistry;
+/**
+ * Reads one command from the ambient registry by id, updating when that command is registered, replaced, or
+ * removed. `undefined` while nothing owns the id — a palette row can render a disabled placeholder from it.
+ */
+export declare function useCommand(id: MaybeRefOrGetter<string>): ComputedRef<Command | undefined>;
+/**
+ * Registers commands for as long as the calling scope lives, unregistering when it is disposed. The array may be
+ * an inline literal, a ref, or a getter — registration re-runs when the commands' text metadata changes, and
+ * `run` / `when` always call through to the latest value.
+ *
+ * Pass `registry` to target a specific registry; otherwise the ambient one is used (and a missing provider throws).
+ */
+export declare function useRegisterCommands(commands: MaybeRefOrGetter<ReadonlyArray<Command>>, registry?: CommandRegistry): void;

package/dist/foundation/commands/providers/CommandsProvider.vue.d.ts

@@ -0,0 +1,18 @@
+import { CommandErrorHandler, CommandRegistry } from '../CommandRegistry';
+/** Props for `CommandsProvider`. */
+export interface CommandsProviderProps {
+    /** An existing registry to share (module-scope singleton, a test's registry). Omitted → the provider owns one. */
+    readonly registry?: CommandRegistry;
+    /** Where a failing command's error goes. Ignored when `registry` is supplied — it carries its own handler. */
+    readonly onError?: CommandErrorHandler;
+}
+declare const _default: __VLS_WithSlots<import('vue').DefineComponent<CommandsProviderProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<CommandsProviderProps> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>, {
+    /** The subtree that reads the provided command registry. */
+    default(): unknown;
+}>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/foundation/config/ConfigField.d.ts

@@ -28,7 +28,7 @@ export interface ConfigField<T, Optional extends boolean = false> {
     /** Parses a present, non-empty raw string into `T`; throws a `string` message describing the failure. */
     parse(raw: string): T;
 }
-/** Computes a field's phantom optionality from its options literal — optional iff no `default` and `required: false`. */
+/** Computes a field's phantom optionality from its options — optional iff no `default` and `required: false`. */
 type Optionality<O> = O extends {
     default: unknown;
 } ? false : O extends {
@@ -56,5 +56,5 @@ export interface ListFieldOptions extends ConfigFieldOptions<readonly string[]>
     readonly separator?: string;
 }
 /** A string-list field — splits on `separator` (default `,`), trims each item, and drops empty items. */
-export declare function list<const O extends ListFieldOptions = ListFieldOptions>(options?: O): ConfigField<readonly string[], Optionality<O>>;
+export declare function list<const O extends ListFieldOptions = ListFieldOptions>(options?: O): ConfigField<ReadonlyArray<string>, Optionality<O>>;
 export {};

package/dist/foundation/config/ConfigSource.d.ts

@@ -1,7 +1,7 @@
 /** A flat, read-only key/value store of raw configuration strings. */
 export type ConfigSource = Readonly<Record<string, string | undefined>>;
 /** The default runtime-config global — `window.__APP_CONFIG__`, injected per-environment ahead of build-time env. */
-export declare const DEFAULT_RUNTIME_CONFIG_KEY = "__APP_CONFIG__";
+export declare const DefaultRuntimeConfigKey = "__APP_CONFIG__";
 /**
  * The build-time source — Vite's `import.meta.env`, inlined at build. Returns `{}` outside a bundler context
  * (e.g. a plain Node test) where `import.meta.env` is absent, so it is always safe to include.
@@ -15,10 +15,10 @@ export declare function windowConfigSource(globalKey?: string): ConfigSource;
 /** An explicit source over a plain record — the injection seam for tests and for values resolved elsewhere. */
 export declare function staticSource(values: Record<string, string | undefined>): ConfigSource;
 /** The default source order: runtime `window.__APP_CONFIG__` layered ahead of build-time `import.meta.env`. */
-export declare function defaultSources(): readonly ConfigSource[];
+export declare function defaultSources(): ReadonlyArray<ConfigSource>;
 /**
  * Resolves `key` across an ordered source list, first non-empty match wins (earlier source = higher priority).
  * A non-string hit (e.g. `import.meta.env.DEV` is a boolean) is coerced to its string form; an empty string is
  * treated as absent so an unset-but-declared env var falls through to the next source or the field default.
  */
-export declare function resolveRaw(sources: readonly ConfigSource[], key: string): string | undefined;
+export declare function resolveRaw(sources: ReadonlyArray<ConfigSource>, key: string): string | undefined;

package/dist/foundation/config/DefineConfig.d.ts

@@ -11,7 +11,7 @@ export type InferConfig<S extends ConfigSchema> = {
 /** Tunes where `defineConfig` reads from and how keys are namespaced. */
 export interface DefineConfigOptions {
     /** The ordered source list; earlier wins. Defaults to `[window.__APP_CONFIG__, import.meta.env]`. */
-    readonly sources?: readonly ConfigSource[];
+    readonly sources?: ReadonlyArray<ConfigSource>;
     /** A prefix prepended to every schema key on lookup (e.g. `'VITE_'` → key `API_URL` reads `VITE_API_URL`). */
     readonly prefix?: string;
 }
@@ -29,8 +29,8 @@ export interface ConfigIssue {
 /** Thrown by `defineConfig` when one or more keys are missing or invalid — aggregates every issue found. */
 export declare class ConfigError extends Error {
     /** Every resolution failure across the schema. */
-    readonly issues: readonly ConfigIssue[];
-    constructor(issues: readonly ConfigIssue[]);
+    readonly issues: ReadonlyArray<ConfigIssue>;
+    constructor(issues: ReadonlyArray<ConfigIssue>);
 }
 /**
  * Resolves a typed configuration object from `schema`. Each key is looked up across the source list (prefix

package/dist/foundation/config/Environment.d.ts

@@ -0,0 +1,12 @@
+/** Defines the build environment. */
+export declare const Environment: {
+    /** Refers to a local development build. */
+    readonly Development: "development";
+    /** Refers to a production build. */
+    readonly Production: "production";
+    /** Refers to a test build. */
+    readonly Test: "test";
+};
+export type Environment = (typeof Environment)[keyof typeof Environment];
+export declare const IsDevelopment: boolean;
+export declare const IsProduction: boolean;

package/dist/foundation/config/index.d.ts

@@ -1,3 +1,4 @@
 export { type ConfigField, type ConfigFieldOptions, type AnyConfigField, type ListFieldOptions, str, num, bool, oneOf, url, port, json, list, } from './ConfigField';
-export { type ConfigSource, DEFAULT_RUNTIME_CONFIG_KEY, importMetaEnvSource, windowConfigSource, staticSource, defaultSources, resolveRaw, } from './ConfigSource';
+export { type ConfigSource, DefaultRuntimeConfigKey, importMetaEnvSource, windowConfigSource, staticSource, defaultSources, resolveRaw, } from './ConfigSource';
 export { type ConfigSchema, type InferConfig, type DefineConfigOptions, type ConfigIssue, ConfigError, defineConfig, } from './DefineConfig';
+export { Environment, IsDevelopment, IsProduction } from './Environment';