@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/hooks/useAutosave/useAutosave.d.ts

@@ -0,0 +1,46 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+/** The lifecycle of the autosave pipeline. */
+export type AutosaveStatus = 
+/** No save has been scheduled since the last settle. */
+'idle'
+/** A change is waiting out the debounce window. */
+ | 'pending'
+/** An async `save` is in flight. */
+ | 'saving'
+/** The most recent save resolved successfully. */
+ | 'saved'
+/** The most recent save threw or rejected. */
+ | 'error';
+/** Tunes autosave timing and gating. */
+export interface UseAutosaveOptions {
+    /** The quiet period (ms) a value must hold before it is saved. Defaults to `800`. */
+    readonly delayMs?: MaybeRefOrGetter<number>;
+    /** Whether autosave is active; when `false`, pending saves are cancelled and none are scheduled. Defaults to `true`. */
+    readonly enabled?: MaybeRefOrGetter<boolean>;
+    /** Invoked with the failure when a `save` throws or rejects. */
+    readonly onError?: (error: unknown) => void;
+}
+/** The autosave handle — current status, the last-saved timestamp, and manual `flush` / `cancel` controls. */
+export interface AutosaveControls {
+    /** The current pipeline status. */
+    readonly status: Readonly<ShallowRef<AutosaveStatus>>;
+    /** `Date.now()` of the last successful save, or null if none has succeeded. */
+    readonly lastSavedAt: Readonly<ShallowRef<number | null>>;
+    /** Cancels any pending debounce and saves the latest value immediately. */
+    flush(): void;
+    /** Drops a pending save without running it; returns the pipeline to `idle`. */
+    cancel(): void;
+}
+/**
+ * Autosaves `value` through `save`, debounced by `delayMs`. Each change to `value` restarts the debounce; when
+ * it elapses, `save(value)` runs. An async `save` drives `status` through `saving` → `saved` / `error`; a stale
+ * run (a newer change superseded it) is ignored so status never flickers backwards. A pending save is flushed
+ * synchronously when the scope is disposed so an in-progress edit is not lost.
+ *
+ * `value` is watched deeply, which is the point of the Vue signature: pass a `reactive` draft or a getter over
+ * one (`() => form.state`) and a nested edit schedules a save — no need to rebuild the object to signal a
+ * change, as the React original required. `enabled` is watched too: flipping it off cancels the pending save,
+ * flipping it back on schedules one. `delayMs` is read when a save is scheduled, so a change to it applies from
+ * the next edit rather than rescheduling the current window.
+ */
+export declare function useAutosave<T>(value: MaybeRefOrGetter<T>, save: (value: T) => void | Promise<void>, options?: UseAutosaveOptions): AutosaveControls;

package/dist/foundation/hooks/useClipboard/index.d.ts

@@ -0,0 +1 @@
+export * from './useClipboard';

package/dist/foundation/hooks/useClipboard/useClipboard.d.ts

@@ -0,0 +1,24 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+export interface UseClipboardOptions {
+    /** Reset `copied` back to false after this many ms. Default 2000. Set 0 to keep state until explicitly reset. */
+    resetAfter?: MaybeRefOrGetter<number>;
+}
+export interface ClipboardControls {
+    /** True for `resetAfter` ms after a successful copy. */
+    copied: Readonly<ShallowRef<boolean>>;
+    /** Last error from `navigator.clipboard.writeText`, if any. */
+    error: Readonly<ShallowRef<Error | null>>;
+    /** Write `text` to the system clipboard. Returns the promise. */
+    copy: (text: string) => Promise<void>;
+    /** Force-clear the `copied` flag. */
+    reset: () => void;
+}
+/**
+ * Wraps `navigator.clipboard.writeText` with a transient `copied` flag for
+ * post-action UI (icon swap, "Copied!" tooltip). Pass `resetAfter: 0` to
+ * keep `copied` true until you call `reset()`.
+ *
+ * `resetAfter` may be a ref or getter; it is read at copy time, so a window
+ * changed between copies takes effect on the next one.
+ */
+export declare function useClipboard({ resetAfter }?: UseClipboardOptions): ClipboardControls;

package/dist/foundation/hooks/useControlled/index.d.ts

@@ -0,0 +1 @@
+export * from './useControlled';

package/dist/foundation/hooks/useControlled/useControlled.d.ts

@@ -0,0 +1,31 @@
+import { MaybeRefOrGetter, WritableComputedRef } from 'vue';
+interface UseControlledOptions<T> {
+    controlled: MaybeRefOrGetter<T | undefined>;
+    default: MaybeRefOrGetter<T>;
+    onChange?: (value: T) => void;
+}
+/** The controlled/uncontrolled handle — a writable value plus the explicit setter it delegates to. */
+export interface ControlledValue<T> {
+    /**
+     * The resolved value. Writable: `value.value = next` runs the same path as `setValue(next)`,
+     * so it drops straight into `v-model`. A writable computed rather than a plain ref because the
+     * controlled branch must never keep its own copy of the value.
+     */
+    readonly value: WritableComputedRef<T>;
+    /** Sets the next value — updates internal state when uncontrolled, and always fires `onChange`. */
+    readonly setValue: (value: T) => void;
+}
+/**
+ * Standard controlled/uncontrolled pattern.
+ *
+ * - If `controlled` resolves to a defined value, the component is controlled — internal state is
+ *   ignored, `setValue` only fires `onChange`.
+ * - Otherwise the component owns its state, `setValue` updates it, and `onChange`
+ *   still fires for consumers that want to observe changes.
+ *
+ * Pass `controlled` as a getter (`() => props.value`) so the controlled branch tracks the prop.
+ * `default` is read once, at setup — it seeds the uncontrolled state, exactly as the original's
+ * `useState(defaultValue)` did.
+ */
+export declare function useControlled<T>({ controlled, default: defaultValue, onChange, }: UseControlledOptions<T>): ControlledValue<T>;
+export {};

package/dist/foundation/hooks/useDebounceHandler/index.d.ts

@@ -0,0 +1 @@
+export * from './useDebounceHandler';

package/dist/foundation/hooks/useDebounceHandler/useDebounceHandler.d.ts

@@ -0,0 +1,16 @@
+import { MaybeRefOrGetter } from 'vue';
+/**
+ * Throttle a DOM event handler. First call in a `ms` window fires; subsequent
+ * within the window are swallowed via `event.preventDefault()`. When `ms` is
+ * `undefined`, the handler passes through unchanged. Use to prevent rapid-fire
+ * gestures (double-clicks, double-submits, repeated touches) without wiring
+ * timer state in the consumer.
+ *
+ * Functionally a *throttle* (first wins). The `Debounce` naming is kept for
+ * vocabulary consistency with the `debounceMs` props on consuming components.
+ *
+ * `ms` may be a ref or getter and is read per event. `handler` is captured at
+ * setup (a function argument cannot double as a getter) — wrap it when the
+ * callee must stay live: `useDebounceHandler((e) => props.onClick?.(e), ms)`.
+ */
+export declare function useDebounceHandler<E extends Event = Event>(handler: ((event: E) => void) | undefined, ms: MaybeRefOrGetter<number | undefined>): (event: E) => void;

package/dist/foundation/hooks/useDisclosure/index.d.ts

@@ -0,0 +1 @@
+export * from './useDisclosure';

package/dist/foundation/hooks/useDisclosure/useDisclosure.d.ts

@@ -0,0 +1,18 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+export interface DisclosureControls {
+    /** The open flag. Writable — `isOpen.value = true` is equivalent to `open()`. */
+    isOpen: Ref<boolean>;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    setOpen: (next: boolean) => void;
+}
+/**
+ * Minimal open/close state. The standard backbone for Modal, Drawer, Popover,
+ * Menu, Accordion, etc. Use `useControlled` underneath when the consumer may
+ * also pass a controlled `open` prop.
+ *
+ * `initial` is read once, at setup — pass a getter only if the source is not
+ * yet resolved at call time; later changes to it do not reopen the disclosure.
+ */
+export declare function useDisclosure(initial?: MaybeRefOrGetter<boolean>): DisclosureControls;

package/dist/foundation/hooks/useEscape/index.d.ts

@@ -0,0 +1 @@
+export * from './useEscape';

package/dist/foundation/hooks/useEscape/useEscape.d.ts

@@ -0,0 +1,10 @@
+import { MaybeRefOrGetter } from 'vue';
+/**
+ * Fire `handler` when the Escape key is pressed at the document level.
+ * For nested overlays, the topmost should call `event.stopPropagation()` in
+ * its handler — `DismissableLayer` handles this stack-style.
+ *
+ * `enabled` may be a ref or a getter (`() => props.isOpen`); the listener
+ * detaches and re-attaches as it flips.
+ */
+export declare function useEscape(handler: (event: KeyboardEvent) => void, enabled?: MaybeRefOrGetter<boolean>): void;

package/dist/foundation/hooks/useEventListener/index.d.ts

@@ -0,0 +1 @@
+export * from './useEventListener';

package/dist/foundation/hooks/useEventListener/useEventListener.d.ts

@@ -0,0 +1,17 @@
+import { MaybeRefOrGetter } from 'vue';
+type Target = Window | Document | HTMLElement | null | undefined;
+/**
+ * Add an event listener and clean it up automatically. Every argument may be a
+ * ref or a getter, so a `useTemplateRef` target attaches the moment the element
+ * mounts and re-attaches if it is swapped — the Vue stand-in for the original's
+ * handler-in-a-ref indirection.
+ *
+ * `handler` is captured at setup (it is a plain function, never a getter — a
+ * getter is indistinguishable from the handler itself). Pass a wrapper when the
+ * callee must stay live: `useEventListener('click', (e) => props.onClick?.(e))`.
+ *
+ * The default target is resolved lazily so importing this in an SSR pass never
+ * touches `document`.
+ */
+export declare function useEventListener<K extends string>(event: MaybeRefOrGetter<K>, handler: (event: Event) => void, target?: MaybeRefOrGetter<Target>, options?: MaybeRefOrGetter<boolean | AddEventListenerOptions | undefined>): void;
+export {};

package/dist/foundation/hooks/useFocusTrap/index.d.ts

@@ -0,0 +1 @@
+export * from './useFocusTrap';

package/dist/foundation/hooks/useFocusTrap/useFocusTrap.d.ts

@@ -0,0 +1,15 @@
+import { MaybeRefOrGetter } from 'vue';
+/**
+ * Trap Tab / Shift+Tab focus inside the referenced element. Once the element
+ * exists, focuses the first focusable child (unless already focused inside).
+ * When the trap tears down — the element unmounts, `enabled` flips, or the
+ * scope is disposed — focus returns to the element that had it beforehand.
+ *
+ * Takes the element as a ref or getter rather than handing one back, so the
+ * caller keeps ownership of its `useTemplateRef`. The effect is post-flush,
+ * so the element is in the DOM by the time the trap arms.
+ *
+ * For richer behavior (sentinels, nested traps), wrap `FocusScope` instead —
+ * this composable is the lower primitive.
+ */
+export declare function useFocusTrap(target: MaybeRefOrGetter<HTMLElement | null | undefined>, enabled?: MaybeRefOrGetter<boolean>): void;

package/dist/foundation/hooks/useId/index.d.ts

@@ -0,0 +1 @@
+export * from './useId';

package/dist/foundation/hooks/useId/useId.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wraps Vue 3.5's built-in `useId`. Optionally accepts a stable prefix so generated
+ * IDs are easier to spot in DevTools (e.g. `useId('checkbox')` → `v-0-checkbox`).
+ *
+ * Must be called during `setup()` — the id is drawn from the app instance's counter,
+ * which is what keeps it stable across a server render and its client hydration.
+ */
+export declare function useId(prefix?: string): string;

package/dist/foundation/hooks/useMediaQuery/index.d.ts

@@ -0,0 +1 @@
+export * from './useMediaQuery';

package/dist/foundation/hooks/useMediaQuery/useMediaQuery.d.ts

@@ -0,0 +1,12 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+/**
+ * Reactively follow a CSS media query. Pass a query string like
+ * `'(min-width: 768px)'` or `'(prefers-reduced-motion: reduce)'`, or a ref /
+ * getter when the query itself changes.
+ *
+ * SSR-safe — the ref holds `false` on the server and during the first render,
+ * then syncs to the real value once mounted. The subscription is the Vue
+ * counterpart of the original's `useSyncExternalStore`: subscribe on mount,
+ * unsubscribe when the scope is disposed.
+ */
+export declare function useMediaQuery(query: MaybeRefOrGetter<string>): Readonly<ShallowRef<boolean>>;

package/dist/foundation/hooks/useOutsideClick/index.d.ts

@@ -0,0 +1 @@
+export * from './useOutsideClick';

package/dist/foundation/hooks/useOutsideClick/useOutsideClick.d.ts

@@ -0,0 +1,12 @@
+import { MaybeRefOrGetter } from 'vue';
+/** One element source — a template ref, a plain element, or a getter that resolves to either. */
+export type OutsideClickTarget = MaybeRefOrGetter<HTMLElement | null | undefined>;
+/**
+ * Fire `handler` when the user clicks outside any of the provided targets.
+ * Uses `pointerdown` so it fires before focus shifts (avoids losing focus
+ * inside an overlay before a click on a trigger registers).
+ *
+ * Pass a `useTemplateRef` (or an array of them) — each is resolved at event
+ * time, so a target that mounts later is still honoured without re-attaching.
+ */
+export declare function useOutsideClick(targets: OutsideClickTarget | ReadonlyArray<OutsideClickTarget>, handler: (event: PointerEvent) => void, enabled?: MaybeRefOrGetter<boolean>): void;

package/dist/foundation/hooks/usePersistentState/index.d.ts

@@ -0,0 +1 @@
+export { usePersistentState, type PersistentStateOptions, type PersistentState, type SetPersistentState, } from './usePersistentState';

package/dist/foundation/hooks/usePersistentState/usePersistentState.d.ts

@@ -0,0 +1,31 @@
+import { MaybeRefOrGetter, WritableComputedRef } from 'vue';
+import { StorageBroker } from '../../storage';
+/** Defines the options that tune where and how `usePersistentState` persists. */
+export interface PersistentStateOptions {
+    /** The persistence seam to read and write through; defaults to `localStorageStorageBroker`. */
+    readonly broker?: StorageBroker;
+}
+/** A setter that accepts a next value or an updater fn, mirroring the original's `useState` dispatch. */
+export type SetPersistentState<T> = (next: T | ((previous: T) => T)) => void;
+/** The persistent-state handle — a writable value plus the updater-accepting setter it delegates to. */
+export interface PersistentState<T> {
+    /**
+     * The live value. Writable: `value.value = next` runs the same write-through path as `setValue(next)`.
+     * A writable computed rather than a plain ref, so persistence is driven by the assignment itself —
+     * mutating a nested field in place does not persist, exactly as the original required a setter call.
+     */
+    readonly value: WritableComputedRef<T>;
+    /** Sets the next value — or derives it from the previous one — and writes it through the broker. */
+    readonly setValue: SetPersistentState<T>;
+}
+/**
+ * Manages a piece of state mirrored into a `StorageBroker` under `key`. Hydrates from the broker on
+ * mount (SSR-safe: the first render always uses `initial`, then a mount hook adopts any persisted value, so
+ * server and client markup match), writes through on every set, and — when backed by `localStorage` —
+ * adopts writes from other tabs via the window `storage` event.
+ *
+ * Returns `{ value, setValue }` rather than a tuple: `value` is writable (`state.value = next`), and
+ * `setValue` is kept because it additionally accepts an updater fn. `key` may be a ref or getter — changing
+ * it re-hydrates from the new slot.
+ */
+export declare function usePersistentState<T>(key: MaybeRefOrGetter<string>, initial: T, options?: PersistentStateOptions): PersistentState<T>;

package/dist/foundation/hooks/useRecentItems/index.d.ts

@@ -0,0 +1 @@
+export { useRecentItems, prependRecent, type RecentItemsOptions, type RecentItems, } from './useRecentItems';

package/dist/foundation/hooks/useRecentItems/useRecentItems.d.ts

@@ -0,0 +1,34 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { StorageBroker } from '../../storage';
+/** Defines the options that configure a recent-items list — identity, cap, and the persistence seam. */
+export interface RecentItemsOptions<T> {
+    /** Derives a stable de-duplication key for an item; re-pushing a matching item moves it to the front. */
+    readonly identify: (item: T) => string;
+    /** The maximum number of items retained, most-recent-first; defaults to 24. */
+    readonly max?: MaybeRefOrGetter<number>;
+    /** The persistence seam to store the list through; defaults to `localStorageStorageBroker` via `usePersistentState`. */
+    readonly broker?: StorageBroker;
+}
+/** Represents a most-recently-used list plus the operations that mutate it. */
+export interface RecentItems<T> {
+    /** The retained items, most-recent-first. */
+    readonly recents: ComputedRef<ReadonlyArray<T>>;
+    /** Records `item` as the most recent — de-duplicated by identity and capped at `max`. */
+    readonly push: (item: T) => void;
+    /** Empties the list. */
+    readonly clear: () => void;
+}
+/**
+ * Prepends `item` to `items` as the most recent, de-duplicating by `identify` (an existing match is removed so
+ * the item resurfaces at the front) and capping the result to `max`. Pure — the reducer the composable writes
+ * through its adapter.
+ */
+export declare function prependRecent<T>(items: ReadonlyArray<T>, item: T, identify: (item: T) => string, max: number): ReadonlyArray<T>;
+/**
+ * Manages a persisted most-recently-used list under `key`, layered on `usePersistentState`. `push` records an
+ * item at the front, de-duplicated by `identify` and capped at `max` (default 24); `clear` empties it. The list
+ * inherits the underlying composable's hydrate-on-mount, write-through, and cross-tab sync.
+ *
+ * `recents` is a read-only computed — mutate the list through `push` / `clear`, never in place.
+ */
+export declare function useRecentItems<T>(key: MaybeRefOrGetter<string>, options: RecentItemsOptions<T>): RecentItems<T>;

package/dist/foundation/hooks/useReducedMotion/index.d.ts

@@ -0,0 +1 @@
+export * from './useReducedMotion';

package/dist/foundation/hooks/useReducedMotion/useReducedMotion.d.ts

@@ -0,0 +1,7 @@
+import { ShallowRef } from 'vue';
+/**
+ * Returns a ref that is `true` when the user has requested reduced motion via
+ * OS settings. Components should short-circuit looping/transitional animations
+ * to a static final state when it is `true`.
+ */
+export declare function useReducedMotion(): Readonly<ShallowRef<boolean>>;

package/dist/foundation/hooks/useResizeObserver/index.d.ts

@@ -0,0 +1 @@
+export * from './useResizeObserver';

package/dist/foundation/hooks/useResizeObserver/useResizeObserver.d.ts

@@ -0,0 +1,11 @@
+import { MaybeRefOrGetter } from 'vue';
+/**
+ * Run `callback` whenever the referenced element's size changes. The effect is
+ * post-flush, so the element is in the DOM (and laid out) before the observer
+ * attaches. Disconnects automatically when the element changes, `enabled`
+ * flips, or the scope is disposed.
+ *
+ * Takes the element as a ref or getter rather than handing one back, so the
+ * caller keeps ownership of its `useTemplateRef`.
+ */
+export declare function useResizeObserver<T extends HTMLElement = HTMLElement>(target: MaybeRefOrGetter<T | null | undefined>, callback: (entry: ResizeObserverEntry) => void, enabled?: MaybeRefOrGetter<boolean>): void;

package/dist/foundation/hooks/useScrollLock/index.d.ts

@@ -0,0 +1 @@
+export * from './useScrollLock';

package/dist/foundation/hooks/useScrollLock/useScrollLock.d.ts

@@ -0,0 +1,11 @@
+import { MaybeRefOrGetter } from 'vue';
+/**
+ * Prevent body scroll while at least one consumer has the lock active.
+ * Internally counted — multiple overlays may lock; only the last unlock restores.
+ * Compensates for scrollbar width to avoid layout shift.
+ *
+ * `enabled` may be a ref or a getter (`() => props.isEnabled`), so the lock
+ * follows a prop without the consumer re-invoking anything. The counter is
+ * module-level and shared, exactly as in the original.
+ */
+export declare function useScrollLock(enabled?: MaybeRefOrGetter<boolean>): void;

package/dist/foundation/hooks/useTypeahead/index.d.ts

@@ -0,0 +1 @@
+export * from './useTypeahead';

package/dist/foundation/hooks/useTypeahead/useTypeahead.d.ts

@@ -0,0 +1,42 @@
+import { MaybeRefOrGetter } from 'vue';
+/** Resolves the typeahead item pool — a static array, a ref, or a getter read lazily on each keystroke. */
+type ItemSource<T> = MaybeRefOrGetter<readonly T[]>;
+/** Configures {@link useTypeahead}. `T` is the item type the caller stores per option. */
+export interface UseTypeaheadOptions<T> {
+    /** Supplies the items to match against; a ref or function is re-read on every keystroke (live lists). */
+    items: ItemSource<T>;
+    /** Extracts the comparable label from an item. Matching is case-insensitive on this string. */
+    getLabel: (item: T) => string;
+    /** Reports whether an item is disabled; disabled items are skipped during matching. */
+    isDisabled?: (item: T) => boolean;
+    /** Fires with the matched item and its index in the (live) item array when a keystroke resolves. */
+    onMatch: (item: T, index: number) => void;
+    /** Returns the index of the currently-active item — same-letter cycling starts after it. */
+    getActiveIndex?: () => number;
+    /** Disables the matcher when `false`; every key falls through unhandled. Defaults to `true`. */
+    enabled?: MaybeRefOrGetter<boolean>;
+    /** Idle time (ms) after which the typed buffer resets. Defaults to `500`. */
+    timeout?: MaybeRefOrGetter<number>;
+}
+/** The keyboard handler + manual reset returned by {@link useTypeahead}. */
+export interface UseTypeaheadReturn {
+    /** Feeds a keydown into the matcher. Returns `true` when consumed (caller should stop), else `false`. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+    /** Clears the typed buffer immediately (e.g. on blur / close). */
+    reset: () => void;
+}
+/**
+ * APG-correct type-to-select matcher (WAI-ARIA listbox/combobox typeahead). Accumulates printable
+ * chars into a buffer (resets after `timeout` ms idle): a repeated single char cycles to the next
+ * label starting with it (after `getActiveIndex()`, wrap-around), else prefix-matches the whole
+ * buffer case-insensitively; disabled items skipped. On a hit `onMatch(item, index)` fires; consumed
+ * keys return `true`, others `false` to fall through. Space is typeable only while buffering (a
+ * leading Space reaches the caller). SSR-safe; reset timer cleared when the scope is disposed.
+ *
+ * `items`, `enabled` and `timeout` may each be a ref or getter and are read per keystroke, so the
+ * matcher tracks a live list without the original's options-in-a-ref indirection. The callbacks
+ * (`getLabel`, `onMatch`, …) are read off the options object at call time — pass a `reactive`
+ * options object if they must be swappable.
+ */
+export declare function useTypeahead<T>(options: UseTypeaheadOptions<T>): UseTypeaheadReturn;
+export {};

package/dist/foundation/http/ApiError.d.ts

@@ -0,0 +1,7 @@
+import { ProblemDetails } from './ProblemDetails';
+/** Defines a typed transport error thrown on a non-2xx response (or network status `0`), carrying the HTTP status and parsed problem body. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly problem: ProblemDetails | null;
+    constructor(status: number, problem: ProblemDetails | null, message?: string);
+}

package/dist/foundation/http/ApiResponse.d.ts

@@ -0,0 +1,4 @@
+/** Defines the success envelope every wow-two API wraps its payload in: `{ data: T }`. */
+export interface ApiResponse<T> {
+    data: T;
+}

package/dist/foundation/http/CreateApiClient.d.ts

@@ -0,0 +1,65 @@
+import { RetryPolicy } from '../resilience';
+import { ApiError } from './ApiError';
+import { ResponseEnvelope } from './Envelope';
+/** Defines query params appended to a request path — arrays repeat the key; `null`/`undefined` entries are skipped; everything else is `String()`-ed. */
+export type ApiQueryParams = Record<string, unknown>;
+/** Defines the per-request init accepted by every {@link ApiClient} method. */
+export interface ApiRequestInit {
+    /** The query params appended to the path (see {@link ApiQueryParams}); merged onto any query string already in the path. */
+    readonly query?: ApiQueryParams;
+    /** The request body — JSON-stringified with `Content-Type: application/json`, except `FormData`, which passes through untouched (the runtime sets the multipart boundary). */
+    readonly body?: unknown;
+    /** Aborts the request (and any retry wait) — an abort rethrows the native `AbortError`, never an {@link ApiError}. */
+    readonly signal?: AbortSignal | null;
+    /** Extra headers merged last — they win over the computed JSON headers, the client defaults, and the bearer token. */
+    readonly headers?: HeadersInit;
+    /** Whether to run the envelope's unwrap on the parsed body. Default `true`; `false` returns the body exactly as parsed — the request flag wins over {@link ApiClientOptions.envelope}. */
+    readonly unwrap?: boolean;
+    /** The HTTP method for the `request` escape hatch. Default `GET`. The verb helpers force their own method. */
+    readonly method?: string;
+}
+/** Defines the options for {@link createApiClient}. */
+export interface ApiClientOptions {
+    /** The prefix for every request path. Default `''` (same-origin — the SPA is served by the API host). */
+    readonly baseUrl?: string;
+    /** Supplies the bearer token, re-read on every attempt — return `null` to skip the `Authorization` header (signed-out / cookie mode). */
+    readonly getAuthToken?: () => string | null | Promise<string | null>;
+    /** The fetch credentials mode — `'include'` for cross-origin cookie auth; omit for the runtime default. */
+    readonly credentials?: RequestCredentials;
+    /** Fires on a 401 after the {@link ApiError} is built (which is still thrown) — wire session-expiry handling here. */
+    readonly onUnauthorized?: (error: ApiError) => void;
+    /** Headers applied to every request; per-request headers win. */
+    readonly defaultHeaders?: HeadersInit;
+    /** Whether to parse response bodies through the Temporal reviver so ISO date fields arrive as `Temporal.*`. Default `false`. */
+    readonly reviveTemporal?: boolean;
+    /** The wire-contract strategy — how 2xx bodies unwrap and how non-2xx bodies become thrown errors. Default {@link wowTwoEnvelope} (zero-config for wow-two APIs); use `rawEnvelope` for un-enveloped APIs, or supply your own. */
+    readonly envelope?: ResponseEnvelope;
+    /** The transport-level retry policy for transient failures. Default `false` (off) — leave off under `/query`, which owns retries, or requests double-retry. */
+    readonly retry?: RetryPolicy | false;
+    /** The fetch implementation, resolved per request. Default the global `fetch` — injectable for tests. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/** Defines the typed HTTP client returned by {@link createApiClient}. */
+export interface ApiClient {
+    /** Sends a GET request. */
+    get<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;
+    /** Sends a POST request. */
+    post<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;
+    /** Sends a PUT request. */
+    put<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;
+    /** Sends a PATCH request. */
+    patch<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;
+    /** Sends a DELETE request. */
+    delete<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;
+    /** Sends a request with an arbitrary method (`init.method`, default `GET`) — the escape hatch under the verb helpers. */
+    request<T = unknown>(path: string, init?: ApiRequestInit): Promise<T>;
+}
+/**
+ * Creates the typed fetch client every wow-two frontend talks through — JSON by default, a swappable
+ * wire contract ({@link ApiClientOptions.envelope}, default {@link wowTwoEnvelope}: `{ data }` unwrap +
+ * ProblemDetails → {@link ApiError}), body-driven empties (an empty body resolves `undefined` and a
+ * literal `null` body resolves `null`, whatever the status), bearer/cookie auth, optional Temporal
+ * revive, and opt-in transport retry (network failure → {@link ApiError} status `0`, envelope-independent).
+ * Aborts rethrow the native `AbortError` so `/query` cancellation semantics stay intact.
+ */
+export declare function createApiClient(options?: ApiClientOptions): ApiClient;

package/dist/foundation/http/DateBrands.d.ts

@@ -0,0 +1,8 @@
+/** Defines a branded alias for a raw ISO-8601 date-time string (`2026-07-04T12:00:00Z`) on a wire DTO. */
+export type IsoDateTime = string & {
+    readonly __brand: 'IsoDateTime';
+};
+/** Defines a branded alias for a raw ISO-8601 calendar-date string (`2026-07-04`) on a wire DTO. */
+export type IsoDate = string & {
+    readonly __brand: 'IsoDate';
+};

package/dist/foundation/http/Envelope.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Defines the wire-contract strategy for `createApiClient` — how a parsed 2xx body yields the payload
+ * and how a parsed non-2xx body yields the thrown error. The client core stays contract-free: it reads
+ * and parses the body (an empty body resolves `undefined` before any strategy runs; a network failure
+ * throws a core {@link ApiError} status `0` — there is no response to delegate) and hands the rest here.
+ */
+export interface ResponseEnvelope {
+    /** Extracts the payload from a parsed 2xx body. Skipped when the request passes `unwrap: false` — the request flag wins over the strategy. */
+    readonly unwrap: (parsed: unknown, response: Response) => unknown;
+    /**
+     * Builds the error thrown for a non-2xx response from its parsed body (plain JSON, no Temporal
+     * revive; `undefined` when empty or malformed). Return an {@link ApiError} to keep retry and
+     * `onUnauthorized` working — both key off the thrown error's `status` — a foreign `Error` type
+     * simply never triggers them.
+     */
+    readonly toError: (parsed: unknown, response: Response) => Error;
+}
+/**
+ * Provides the wow-two wire contract (the default): a 2xx object body shaped `{ data }` (`ApiResponse`)
+ * unwraps to its `data` member — anything else, including a literal `null` body, passes through
+ * unchanged — and a non-2xx JSON-object body is taken as the RFC 7807 {@link ProblemDetails} (non-object
+ * bodies → `null` problem), thrown as {@link ApiError} with its message precedence: title → detail →
+ * status fallback.
+ */
+export declare const wowTwoEnvelope: ResponseEnvelope;
+/**
+ * Provides the identity contract for un-enveloped APIs: 2xx bodies pass through unchanged, and a
+ * non-2xx response throws `ApiError(status, null, statusText)` — deliberately still an {@link ApiError}
+ * rather than a plain `Error`, so `status`-keyed retry, `onUnauthorized`, and caller `instanceof`
+ * handling stay uniform across envelopes. The error body is ignored (no contract to read a problem
+ * from); an empty `statusText` (HTTP/2 sends none) falls back to `Request failed with status N`.
+ */
+export declare const rawEnvelope: ResponseEnvelope;

package/dist/foundation/http/FieldErrors.d.ts

@@ -0,0 +1,16 @@
+import { FieldIssue } from '../validation/Messages';
+/**
+ * Extracts the per-field validation failures from a thrown error — the `errors` member of an
+ * {@link ApiError}'s problem body, normalized to `field → issues` with each rule code and its operands
+ * preserved. Handles both the ASP.NET ValidationProblemDetails / ModelState dict (`{ field: string[] }`,
+ * a bare string value counts as one message — that shape carries no code) and the wow-two backend's
+ * array shape (`[{ property, message, code?, params? }]`, grouped by property). Anything else —
+ * non-`ApiError`, no problem body, no `errors` member — yields `{}` so callers can map unconditionally.
+ */
+export declare function fieldIssues(error: unknown): Record<string, FieldIssue[]>;
+/**
+ * Extracts the per-field validation messages from a thrown error, normalized to `field → messages` for
+ * mapping onto form fields. The message-only view of {@link fieldIssues} — reach for that one when the
+ * rule code matters (message catalogue, per-code UI); this stays the shape every existing caller expects.
+ */
+export declare function fieldErrors(error: unknown): Record<string, string[]>;

package/dist/foundation/http/Page.d.ts

@@ -0,0 +1,47 @@
+/** Defines a page's rows — the universal fragment every page carries. */
+export interface IHasItems<T> {
+    items: ReadonlyArray<T>;
+}
+/** Defines the effective page size a read was served at. */
+export interface IHasPageSize {
+    pageSize: number;
+}
+/** Defines the 1-based page index echo (offset paradigm; matches the `Pagination` component's `page`). */
+export interface IHasPageNumber {
+    pageNumber: number;
+}
+/** Defines the raw skip/limit echo — the alternate offset encoding for skip/take backends. */
+export interface IHasOffset {
+    offset: number;
+}
+/** Defines the total number of matching rows across all pages (offset paradigm). */
+export interface IHasTotalCount {
+    totalCount: number;
+}
+/**
+ * Defines the opaque forward continuation cursor (cursor/token paradigm). Generic over the token type
+ * (`string` by default, but a `number`, id, or any opaque cursor). An **absent** token marks the last page.
+ */
+export interface IHasPageToken<TToken = string> {
+    nextPageToken?: TToken;
+}
+/** Defines an explicit "another page exists" flag — carry only when a backend sends one; otherwise has-more is derived. */
+export interface IHasMore {
+    hasMore: boolean;
+}
+/** Defines the server-side query elapsed time (diagnostics) — carry only where a screen renders it. */
+export interface IHasQueryTiming {
+    queryElapsedMs?: number;
+}
+/** Defines an echo of the applied filter/sort/paging (`TQuery` = the product's `{Noun}QueryDto`) — stretch, opt-in. */
+export interface IHasAppliedQuery<TQuery> {
+    appliedQuery?: TQuery;
+}
+/** Defines an offset/page-indexed slice of a list read — the shape `useAppPaginatedQuery` binds `TPage` to. */
+export interface Page<T> extends IHasItems<T>, IHasPageNumber, IHasPageSize, IHasTotalCount {
+}
+/** Defines a cursor/token slice of a list read — the shape `useAppInfiniteQuery` binds `TPage` to. */
+export interface TokenPage<T, TToken = string> extends IHasItems<T>, IHasPageToken<TToken>, IHasPageSize {
+}
+/** Documented alias for {@link TokenPage} — "cursor" and "token" are the same keyset-forward paradigm for the client. */
+export type CursorPage<T, TToken = string> = TokenPage<T, TToken>;

package/dist/foundation/http/ProblemDetails.d.ts

@@ -0,0 +1,9 @@
+/** Defines an RFC 7807 problem-details error body, with an index signature for extension members. */
+export interface ProblemDetails {
+    type?: string;
+    title?: string;
+    status?: number;
+    detail?: string;
+    instance?: string;
+    [key: string]: unknown;
+}