@wow-two-beta/ui-vue 0.0.2

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

@@ -0,0 +1,8 @@
+import { ChordPlatformOptions } from '../shortcuts';
+import { Command } from './Command';
+/**
+ * Renders a command's shortcut for display (`'mod+k'` → `⌘K` on Apple, `Ctrl+K` elsewhere). Returns `undefined`
+ * when the command carries no shortcut, and the raw string when it carries one the chord parser rejects.
+ * Pass `{ applePlatform }` to force the platform (SSR, tests, a per-user preference).
+ */
+export declare function commandShortcutLabel(command: Command, options?: ChordPlatformOptions): string | undefined;

package/dist/foundation/commands/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<readonly Command[]>, registry?: CommandRegistry): void;

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

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

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

@@ -0,0 +1,28 @@
+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;
+/** 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. */
+    readonly TitlePrefix: 0;
+    /** The title contains the query somewhere after the start. */
+    readonly TitleSubstring: 1;
+    /** One of the `keywords` contains the query. */
+    readonly Keyword: 2;
+    /** The `group` label contains the query — the weakest signal. */
+    readonly Group: 3;
+};
+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
+ * 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;
+/**
+ * Filters and ranks commands for a palette's search box. Non-matching commands are dropped; matches sort by
+ * {@link CommandMatchRank}, ties keeping their original relative order. An empty / whitespace-only query returns
+ * the input untouched (same reference, original order).
+ *
+ * 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[];

package/dist/foundation/commands/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<readonly 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<readonly Command[]>;

package/dist/foundation/commands/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.
+ *
+ * Failures are swallowed by design — `registry.run` never throws and routes errors to the registry's `onError`.
+ */
+export declare function useCommandShortcuts(registry: CommandRegistry, options?: CommandShortcutOptions): void;

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

@@ -0,0 +1,8 @@
+export { CommandRunOutcome, 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 { 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';

package/dist/foundation/commands/index.js

@@ -0,0 +1,278 @@
+import { a as formatChordString } from "../../chunks/Chord-D9Z-j3O0.js";
+import { computed, shallowRef, onMounted, onScopeDispose, toValue, provide, inject, watch, defineComponent, renderSlot } from "vue";
+import { u as useHotkeyMap } from "../../chunks/UseHotkeys-CKIYK5Mq.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. */
+  Unavailable: "unavailable",
+  /** The handler threw or rejected — the error was routed to the registry's `onError`. */
+  Failed: "failed"
+};
+function createCommandRegistry(options) {
+  const entries = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  let revision = 0;
+  function notify() {
+    revision += 1;
+    for (const listener of [...listeners]) listener();
+  }
+  function removeExact(command) {
+    if (entries.get(command.id) !== command) return false;
+    entries.delete(command.id);
+    return true;
+  }
+  return {
+    register(command) {
+      entries.set(command.id, command);
+      notify();
+      return () => {
+        if (removeExact(command)) notify();
+      };
+    },
+    registerAll(commands) {
+      const registered = [...commands];
+      for (const command of registered) entries.set(command.id, command);
+      notify();
+      return () => {
+        let removed = false;
+        for (const command of registered) removed = removeExact(command) || removed;
+        if (removed) notify();
+      };
+    },
+    unregister(id) {
+      if (!entries.delete(id)) return false;
+      notify();
+      return true;
+    },
+    get(id) {
+      return entries.get(id);
+    },
+    list() {
+      return [...entries.values()];
+    },
+    available() {
+      return [...entries.values()].filter(isCommandAvailable);
+    },
+    async run(id, context) {
+      const command = entries.get(id);
+      if (command === void 0) return CommandRunOutcome.NotFound;
+      try {
+        if (!isCommandAvailable(command)) return CommandRunOutcome.Unavailable;
+        await command.run(context);
+        return CommandRunOutcome.Ran;
+      } catch (error) {
+        options?.onError?.(error, command);
+        return CommandRunOutcome.Failed;
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    version() {
+      return revision;
+    }
+  };
+}
+const NO_MATCH = Number.POSITIVE_INFINITY;
+const CommandMatchRank = {
+  /** The title starts with the query — the strongest signal. */
+  TitlePrefix: 0,
+  /** The title contains the query somewhere after the start. */
+  TitleSubstring: 1,
+  /** One of the `keywords` contains the query. */
+  Keyword: 2,
+  /** The `group` label contains the query — the weakest signal. */
+  Group: 3
+};
+function rankCommand(command, query) {
+  const needle = query.trim().toLowerCase();
+  if (needle === "") return CommandMatchRank.TitlePrefix;
+  const title = command.title.toLowerCase();
+  if (title.startsWith(needle)) return CommandMatchRank.TitlePrefix;
+  if (title.includes(needle)) return CommandMatchRank.TitleSubstring;
+  const keywords = command.keywords;
+  if (keywords !== void 0 && keywords.some((keyword) => keyword.toLowerCase().includes(needle))) {
+    return CommandMatchRank.Keyword;
+  }
+  const group = command.group;
+  if (group !== void 0 && group.toLowerCase().includes(needle)) return CommandMatchRank.Group;
+  return NO_MATCH;
+}
+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 });
+  });
+  matches.sort((left, right) => left.rank - right.rank || left.index - right.index);
+  return matches.map((match) => match.command);
+}
+function commandShortcutLabel(command, options) {
+  const shortcut = command.shortcut;
+  if (shortcut === void 0) return void 0;
+  try {
+    return formatChordString(shortcut, options);
+  } catch {
+    return shortcut;
+  }
+}
+function useCommandRegistryVersion(registry) {
+  const version = shallowRef(registry.version());
+  let unsubscribe;
+  onMounted(() => {
+    version.value = registry.version();
+    unsubscribe = registry.subscribe(() => {
+      version.value = registry.version();
+    });
+  });
+  onScopeDispose(() => {
+    unsubscribe?.();
+    unsubscribe = void 0;
+  });
+  return version;
+}
+function useCommandList(registry) {
+  const version = useCommandRegistryVersion(registry);
+  return computed(() => {
+    void version.value;
+    return registry.list();
+  });
+}
+function useAvailableCommands(registry) {
+  const version = useCommandRegistryVersion(registry);
+  return computed(() => {
+    void version.value;
+    return registry.available();
+  });
+}
+function useCommandShortcuts(registry, options) {
+  const version = useCommandRegistryVersion(registry);
+  const trigger = (id) => {
+    void registry.run(id, toValue(options?.context)).then(() => options?.onRun?.(id));
+  };
+  useHotkeyMap(() => {
+    void version.value;
+    const bindings = {};
+    for (const command of registry.available()) {
+      const shortcut = command.shortcut;
+      if (shortcut === void 0) continue;
+      const id = command.id;
+      bindings[shortcut] = () => trigger(id);
+    }
+    return bindings;
+  }, options);
+}
+const CommandsKey = Symbol("wow-two.commands");
+function provideCommands(registry, onError) {
+  const owned = createCommandRegistry({
+    onError: (error, command) => toValue(onError)?.(error, command)
+  });
+  const resolved = toValue(registry) ?? owned;
+  provide(CommandsKey, resolved);
+  return resolved;
+}
+function useCommands() {
+  const registry = inject(CommandsKey, void 0);
+  if (registry === void 0) {
+    throw new Error("useCommands must be used inside a <CommandsProvider>");
+  }
+  return registry;
+}
+function useCommand(id) {
+  const registry = useCommands();
+  const version = useCommandRegistryVersion(registry);
+  return computed(() => {
+    void version.value;
+    return registry.get(toValue(id));
+  });
+}
+function metadataSignature(command) {
+  return JSON.stringify([
+    command.id,
+    command.title,
+    command.description ?? "",
+    command.group ?? "",
+    command.keywords ?? [],
+    command.shortcut ?? "",
+    command.enabled !== false
+  ]);
+}
+function bindToLatest(command, latest) {
+  const id = command.id;
+  const resolve = () => toValue(latest).find((candidate) => candidate.id === id);
+  return {
+    ...command,
+    when: () => {
+      const current = resolve();
+      return current !== void 0 && isCommandAvailable(current);
+    },
+    run: (context) => resolve()?.run(context)
+  };
+}
+function useRegisterCommands(commands, registry) {
+  const target = registry ?? inject(CommandsKey, void 0);
+  if (target === void 0) {
+    throw new Error("useRegisterCommands must be used inside a <CommandsProvider>, or given an explicit registry");
+  }
+  const signature = computed(() => toValue(commands).map(metadataSignature).join(""));
+  watch(
+    signature,
+    (_next, _previous, onCleanup) => {
+      const dispose = target.registerAll(
+        toValue(commands).map((command) => bindToLatest(command, commands))
+      );
+      onCleanup(dispose);
+    },
+    { immediate: true }
+  );
+}
+const _sfc_main = /* @__PURE__ */ defineComponent({
+  ...{ name: "CommandsProvider" },
+  __name: "CommandsProvider",
+  props: {
+    registry: {},
+    onError: { type: Function }
+  },
+  setup(__props) {
+    const props = __props;
+    provideCommands(
+      () => props.registry,
+      () => props.onError
+    );
+    return (_ctx, _cache) => {
+      return renderSlot(_ctx.$slots, "default");
+    };
+  }
+});
+export {
+  CommandMatchRank,
+  CommandRunOutcome,
+  CommandsKey,
+  _sfc_main as CommandsProvider,
+  NO_MATCH,
+  commandShortcutLabel,
+  createCommandRegistry,
+  isCommandAvailable,
+  provideCommands,
+  rankCommand,
+  searchCommands,
+  useAvailableCommands,
+  useCommand,
+  useCommandList,
+  useCommandRegistryVersion,
+  useCommandShortcuts,
+  useCommands,
+  useRegisterCommands
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,60 @@
+/** Tunes one field's presence policy and fallback. A `default` (or `required: false`) makes the field optional. */
+export interface ConfigFieldOptions<T> {
+    /** Marks the field required. Defaults to `true` unless a `default` is supplied. */
+    readonly required?: boolean;
+    /** The value used when the key is absent or empty. Supplying it makes the field optional. */
+    readonly default?: T;
+    /** Redacts the raw value from `ConfigError` messages — set for tokens, keys, and passwords. */
+    readonly secret?: boolean;
+}
+/**
+ * Describes a single configuration key: its scalar type, presence policy, and how to parse a present raw
+ * string into `T`. `Optional` is a phantom flag the schema inference reads to widen the output to `T | undefined`
+ * for a field that is `required: false` with no `default`.
+ */
+export interface ConfigField<T, Optional extends boolean = false> {
+    /** The human-facing type name used in error messages (`string`, `number`, `one of [...]`, …). */
+    readonly typeName: string;
+    /** Whether a missing key is an error. `false` when a `default` is present or `required: false`. */
+    readonly required: boolean;
+    /** Whether an explicit `default` was supplied. */
+    readonly hasDefault: boolean;
+    /** The configured fallback, meaningful only when `hasDefault` is `true`. */
+    readonly defaultValue?: T;
+    /** Whether the raw value is redacted from error output. */
+    readonly secret: boolean;
+    /** Phantom marker: `true` widens the inferred output type to `T | undefined`. Never read at runtime. */
+    readonly __optional?: Optional;
+    /** 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`. */
+type Optionality<O> = O extends {
+    default: unknown;
+} ? false : O extends {
+    required: false;
+} ? true : false;
+/** The upper bound for a field of unknown scalar type — every concrete `ConfigField<T, …>` is assignable to it. */
+export type AnyConfigField = ConfigField<unknown, boolean>;
+/** A string field — the raw value is trimmed and rejected when empty (empty already reads as "missing"). */
+export declare function str<const O extends ConfigFieldOptions<string> = ConfigFieldOptions<string>>(options?: O): ConfigField<string, Optionality<O>>;
+/** A finite-number field — rejects any raw string that does not parse to a finite JS number. */
+export declare function num<const O extends ConfigFieldOptions<number> = ConfigFieldOptions<number>>(options?: O): ConfigField<number, Optionality<O>>;
+/** A boolean field — accepts `true/1/yes/on` and `false/0/no/off` (case-insensitive); rejects anything else. */
+export declare function bool<const O extends ConfigFieldOptions<boolean> = ConfigFieldOptions<boolean>>(options?: O): ConfigField<boolean, Optionality<O>>;
+/** An enum field — the value must be one of `values`; the output type narrows to that literal union. */
+export declare function oneOf<const V extends readonly string[], const O extends ConfigFieldOptions<V[number]> = ConfigFieldOptions<V[number]>>(values: V, options?: O): ConfigField<V[number], Optionality<O>>;
+/** A URL field — validated with the `URL` constructor; the parsed string is returned unchanged. */
+export declare function url<const O extends ConfigFieldOptions<string> = ConfigFieldOptions<string>>(options?: O): ConfigField<string, Optionality<O>>;
+/** A TCP-port field — a finite integer in `1..65535`. */
+export declare function port<const O extends ConfigFieldOptions<number> = ConfigFieldOptions<number>>(options?: O): ConfigField<number, Optionality<O>>;
+/** A JSON field — `JSON.parse`d into `T`; a malformed document is rejected. */
+export declare function json<T, const O extends ConfigFieldOptions<T> = ConfigFieldOptions<T>>(options?: O): ConfigField<T, Optionality<O>>;
+/** Tunes how a `list` field splits its raw value. */
+export interface ListFieldOptions extends ConfigFieldOptions<readonly string[]> {
+    /** The item separator. Defaults to a comma. */
+    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 {};

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

@@ -0,0 +1,24 @@
+/** 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__";
+/**
+ * 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.
+ */
+export declare function importMetaEnvSource(): ConfigSource;
+/**
+ * The runtime source — a global object (default `window.__APP_CONFIG__`) a deployment injects before the app
+ * boots. Returns `{}` when there is no `window` (SSR / Node) or the global is absent or not an object.
+ */
+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[];
+/**
+ * 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;

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

@@ -0,0 +1,43 @@
+import { AnyConfigField, ConfigField } from './ConfigField';
+import { ConfigSource } from './ConfigSource';
+/** A schema: a map from output key to its field spec. */
+export type ConfigSchema = Readonly<Record<string, AnyConfigField>>;
+/** Widens an optional field's output to include `undefined`; a required / defaulted field stays `T`. */
+type InferField<F> = F extends ConfigField<infer T, infer Optional> ? (Optional extends true ? T | undefined : T) : never;
+/** The resolved, typed config object inferred from a schema. */
+export type InferConfig<S extends ConfigSchema> = {
+    readonly [K in keyof S]: InferField<S[K]>;
+};
+/** 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[];
+    /** A prefix prepended to every schema key on lookup (e.g. `'VITE_'` → key `API_URL` reads `VITE_API_URL`). */
+    readonly prefix?: string;
+}
+/** One resolution failure — a missing required key or a value that failed its field's `parse`. */
+export interface ConfigIssue {
+    /** The schema key (output name, without the lookup prefix). */
+    readonly key: string;
+    /** The full source key looked up (with prefix). */
+    readonly lookupKey: string;
+    /** Why it failed. */
+    readonly reason: 'missing' | 'invalid';
+    /** A human-readable description; a `secret` field's raw value is never included. */
+    readonly message: string;
+}
+/** 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[]);
+}
+/**
+ * Resolves a typed configuration object from `schema`. Each key is looked up across the source list (prefix
+ * applied), parsed through its field, and defaulted when absent. Empty strings count as absent. All missing /
+ * invalid problems are aggregated and thrown together as a single {@link ConfigError}; on success the returned
+ * object is frozen. Pass an explicit `sources` (e.g. `[staticSource({...})]`) to make resolution deterministic
+ * in tests.
+ */
+export declare function defineConfig<const S extends ConfigSchema>(schema: S, options?: DefineConfigOptions): InferConfig<S>;
+export {};

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

@@ -0,0 +1,3 @@
+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 ConfigSchema, type InferConfig, type DefineConfigOptions, type ConfigIssue, ConfigError, defineConfig, } from './DefineConfig';