@wow-two-beta/ui-vue 0.0.2

package/dist/query/QueryProgressBridge.d.ts

@@ -0,0 +1,16 @@
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+/**
+ * Lights the router's manual heartbeat while the query layer has any fetch or mutation in flight.
+ *
+ * Call inside BOTH a query client scope (`queryPlugin` / `<QueryProvider>`) and a `<ProgressProvider>`
+ * — `useNavigationProgress` THROWS outside one. Wires effects only; it drives
+ * `<NavigationProgress variant="heartbeat" mode="manual" />`.
+ */
+export declare function useQueryProgressBridge(): void;
+/**
+ * Renders nothing; wires `useQueryProgressBridge`.
+ *
+ * The component form React shipped, kept so an app can drop `<QueryProgressBridge />` into its
+ * shell unchanged. Authored as a `defineComponent` rather than an SFC — it has no template.
+ */
+export declare const QueryProgressBridge: DefineComponent<{}, () => null, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;

package/dist/query/QueryProvider.vue.d.ts

@@ -0,0 +1,17 @@
+import { QueryClient } from '@tanstack/vue-query';
+import { DefineComponent, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+/** Defines the props for {@link QueryProvider}. */
+export interface QueryProviderProps {
+    /** The app `QueryClient` (from `createQueryClient`). */
+    client: QueryClient;
+}
+declare const _default: __VLS_WithSlots< DefineComponent<QueryProviderProps, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<QueryProviderProps> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>, {
+    /** The subtree with access to the client. */
+    default(): unknown;
+}>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/query/QueryTestUtils.d.ts

@@ -0,0 +1,54 @@
+import { App } from 'vue';
+import { QueryClient } from '@tanstack/vue-query';
+import { ComponentMountingOptions, GlobalMountOptions, VueWrapper } from '@vue/test-utils';
+/** Creates a `QueryClient` tuned for tests — retries off, no gc eviction, no focus-refetch. */
+export declare function createTestQueryClient(): QueryClient;
+/** Defines options for `mountWithQuery` — `@vue/test-utils` mounting options plus the client to provide. */
+export type MountWithQueryOptions<T> = ComponentMountingOptions<T> & {
+    /** The client to provide; a fresh test client when omitted. */
+    readonly client?: QueryClient;
+};
+/** Represents the `@vue/test-utils` wrapper augmented with the `QueryClient` it was mounted against. */
+export type MountWithQueryResult = VueWrapper & {
+    readonly client: QueryClient;
+};
+/**
+ * Mounts `component` with a query client provided, for tests — returns the `@vue/test-utils` wrapper
+ * plus the client used.
+ *
+ * `@testing-library/react` has no Vue counterpart in this repo; `@vue/test-utils` is the installed
+ * equivalent, and it MOUNTS A COMPONENT rather than rendering an already-created element, which is
+ * why this takes `(component, { props, slots, … })` where React took `(ui)`.
+ */
+export declare function mountWithQuery<T>(component: T, options?: MountWithQueryOptions<T>): MountWithQueryResult;
+/** @deprecated The React name for {@link mountWithQuery} — kept so a ported test compiles; the signature is the Vue one (component + mounting options). */
+export declare const renderWithQuery: typeof mountWithQuery;
+/**
+ * Builds the `@vue/test-utils` mounting options that provide a query client — spread into a `mount`
+ * call: `mount(Component, createQueryWrapper(client))`.
+ *
+ * React returned a WRAPPER COMPONENT for `renderHook(fn, { wrapper })`. `@vue/test-utils` has no
+ * `renderHook`, and providing a client is a mount option here rather than a wrapping component, so
+ * that is the shape. For a composable with no component at all, reach for `runWithQuery`.
+ */
+export declare function createQueryWrapper(client?: QueryClient): {
+    global: GlobalMountOptions;
+};
+/** Represents a composable run under a query client — its return value plus the teardown. */
+export interface RunWithQueryResult<T> {
+    /** Whatever the composable returned. */
+    readonly result: T;
+    /** The client it ran against. */
+    readonly client: QueryClient;
+    /** The host app, for `app.config` tweaks. */
+    readonly app: App;
+    /** Tears the host app down — runs `onScopeDispose` / `onUnmounted` cleanups. */
+    readonly unmount: () => void;
+}
+/**
+ * Runs a composable inside a throwaway app with a query client provided — the counterpart of React's
+ * `renderHook` + wrapper, which `@vue/test-utils` does not ship.
+ *
+ * Mounts a renderless host into a detached element, so it needs a DOM environment.
+ */
+export declare function runWithQuery<T>(composable: () => T, client?: QueryClient): RunWithQueryResult<T>;

package/dist/query/ToApiError.d.ts

@@ -0,0 +1,7 @@
+import { ApiError } from '../foundation/http';
+/**
+ * Coerces any thrown value into the SDK `ApiError` — passes through an `ApiError`, wraps everything
+ * else as status `0` (network / unknown) with the message `getErrorMessage` reads off it, so an
+ * `Error` from another realm (iframe · worker) keeps its message instead of failing `instanceof`.
+ */
+export declare function toApiError(error: unknown): ApiError;

package/dist/query/UseAppInfiniteQuery.d.ts

@@ -0,0 +1,45 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { QueryKey } from '@tanstack/vue-query';
+import { ApiError } from '../foundation/http';
+import { AppQueryMeta } from './CreateQueryClient';
+/** Defines options for `useAppInfiniteQuery`. */
+export interface UseAppInfiniteQueryOptions<TItem, TPage> {
+    /** The cache key (from `queryKeys`). */
+    readonly key: MaybeRefOrGetter<QueryKey>;
+    /** Fetches one page for `pageParam`; receives the `AbortSignal`. */
+    readonly queryFn: (ctx: {
+        pageParam: unknown;
+        signal: AbortSignal;
+    }) => Promise<TPage>;
+    /** Derives the next page's param from the last page — return `undefined`/`null` to stop. */
+    readonly getNextPageParam: (lastPage: TPage, allPages: readonly TPage[]) => unknown;
+    /** The param for the first page. */
+    readonly initialPageParam: unknown;
+    /** Extracts items from a page — the page itself is the item array when omitted. */
+    readonly mapPage?: (page: TPage) => readonly TItem[];
+    /** Poll interval in ms, or a fn of the current items → ms / `false` (poll-while-running). */
+    readonly refetchInterval?: number | ((items: readonly TItem[]) => number | false);
+    /** Gates the query — skips fetching while `false`. */
+    readonly enabled?: MaybeRefOrGetter<boolean>;
+    /** Metadata surfaced to the global `onError` seam — `suppressGlobalError: true` keeps this query's failures out of it (e.g. polls that would otherwise toast per failed refetch). */
+    readonly meta?: AppQueryMeta;
+}
+/** Represents an infinite query's slice — every member reactive. */
+export interface UseAppInfiniteQueryReturn<TItem> {
+    /** Every fetched page flattened to items. */
+    readonly items: ComputedRef<readonly TItem[]>;
+    /** True while there is no page yet and a fetch is in flight. */
+    readonly loading: ComputedRef<boolean>;
+    /** The failure coerced to `ApiError`, or `null`. */
+    readonly error: ComputedRef<ApiError | null>;
+    /** Whether another page can be fetched. */
+    readonly hasNextPage: Ref<boolean>;
+    /** Fetches the next page. */
+    readonly fetchNextPage: (...args: never[]) => unknown;
+    /** True while the next page is in flight. */
+    readonly isFetchingNextPage: Ref<boolean>;
+    /** Refetches every fetched page. */
+    readonly refetch: () => unknown;
+}
+/** Manages a paginated resource — wraps `useInfiniteQuery`, flattens pages to items, and supports poll-while-running. */
+export declare function useAppInfiniteQuery<TItem, TPage>({ key, queryFn, getNextPageParam, initialPageParam, mapPage, refetchInterval, enabled, meta, }: UseAppInfiniteQueryOptions<TItem, TPage>): UseAppInfiniteQueryReturn<TItem>;

package/dist/query/UseAppLazyQuery.d.ts

@@ -0,0 +1,40 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { QueryKey } from '@tanstack/vue-query';
+import { ApiError } from '../foundation/http';
+import { AppQueryMeta } from './CreateQueryClient';
+/** Defines options for `useAppLazyQuery` — `TRaw` first so it infers from `queryFn` (a spread def) and `TData` defaults to it when `map` is absent. */
+export interface UseAppLazyQueryOptions<TRaw, TData = TRaw> {
+    /** The cache key (from `queryKeys`) — read at each `fetch()`, so a ref or getter re-keys the next call. */
+    readonly key: MaybeRefOrGetter<QueryKey>;
+    /** Fetches the raw payload; receives the `AbortSignal`. */
+    readonly queryFn: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<TRaw>;
+    /** Maps the raw payload to the domain shape — identity when omitted. */
+    readonly map?: (raw: TRaw) => TData;
+    /** Metadata surfaced to the global `onError` seam — `suppressGlobalError: true` keeps this query's failures out of it. */
+    readonly meta?: AppQueryMeta;
+}
+/** Represents an imperative query's slice — state as refs, plus the two commands. */
+export interface UseAppLazyQueryReturn<TData> {
+    /** The mapped payload from the latest settled `fetch()`, or `undefined` while idle. */
+    readonly data: Ref<TData | undefined>;
+    /** True while a `fetch()` is in flight. */
+    readonly loading: Ref<boolean>;
+    /** The latest failure coerced to `ApiError`, or `null`. */
+    readonly error: Ref<ApiError | null>;
+    /** Runs the request on demand; resolves the mapped data and rejects with the raw error. */
+    readonly fetch: () => Promise<TData>;
+    /** Returns the hook to its idle state and orphans any in-flight call. */
+    readonly reset: () => void;
+}
+/**
+ * Manages an imperative query — does not fetch on mount; `fetch()` runs the request on demand,
+ * caching by key via the client (which dedupes concurrent calls and serves a still-fresh cache entry
+ * without refetching — the client's `staleTime` window applies). Drives local `data`/`loading`/`error`
+ * state with latest-call-wins semantics: a slower earlier `fetch()` (or one orphaned by `reset`) never
+ * overwrites newer state, though every call's promise still settles with its own outcome. `fetch()`
+ * resolves the mapped data and rejects with the raw error, while `error` holds the coerced `ApiError`.
+ * For fetch-on-submit / export-on-click flows. `reset` returns it to the idle state.
+ */
+export declare function useAppLazyQuery<TRaw, TData = TRaw>({ key, queryFn, map, meta, }: UseAppLazyQueryOptions<TRaw, TData>): UseAppLazyQueryReturn<TData>;

package/dist/query/UseAppMutation.d.ts

@@ -0,0 +1,32 @@
+import { ComputedRef, Ref } from 'vue';
+import { QueryClient, QueryKey } from '@tanstack/vue-query';
+import { ApiError } from '../foundation/http';
+import { AppQueryMeta } from './CreateQueryClient';
+/** Defines options for `useAppMutation`. */
+export interface UseAppMutationOptions<TData, TVars> {
+    /** Performs the mutation against the backend. */
+    readonly mutationFn: (vars: TVars) => Promise<TData>;
+    /** Query keys to invalidate on success — derived from the vars and the server's returned value. */
+    readonly invalidates?: (vars: TVars, data: TData) => readonly QueryKey[];
+    /** Reconciles the cache from the server's confirmed result (e.g. `setQueryData`) after invalidation. */
+    readonly onConfirmed?: (data: TData, vars: TVars, queryClient: QueryClient) => void;
+    /** Metadata surfaced to the global `onError` seam — `suppressGlobalError: true` keeps this mutation's failures out of it. */
+    readonly meta?: AppQueryMeta;
+}
+/** Represents a mutation's slice — state as refs, commands as plain functions. */
+export interface UseAppMutationReturn<TData, TVars> {
+    /** Fires the mutation, fire-and-forget. */
+    readonly mutate: (vars: TVars) => void;
+    /** Fires the mutation and resolves with its result. */
+    readonly mutateAsync: (vars: TVars) => Promise<TData>;
+    /** The last successful result. */
+    readonly data: Ref<TData | undefined>;
+    /** True while the mutation is in flight. */
+    readonly loading: Ref<boolean>;
+    /** The failure coerced to `ApiError`, or `null`. */
+    readonly error: ComputedRef<ApiError | null>;
+    /** Clears the mutation back to idle. */
+    readonly reset: () => void;
+}
+/** Manages a passive mutation — reconciles the cache only from the backend-confirmed result; no optimistic update, no rollback. */
+export declare function useAppMutation<TData, TVars>({ mutationFn, invalidates, onConfirmed, meta, }: UseAppMutationOptions<TData, TVars>): UseAppMutationReturn<TData, TVars>;

package/dist/query/UseAppPaginatedQuery.d.ts

@@ -0,0 +1,39 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { QueryKey } from '@tanstack/vue-query';
+import { ApiError } from '../foundation/http';
+import { AppQueryMeta } from './CreateQueryClient';
+/** Defines options for `useAppPaginatedQuery`. */
+export interface UseAppPaginatedQueryOptions<TItem, TPage> {
+    /** The base cache key (from `queryKeys`) — the active `page` is appended to form the per-page key. */
+    readonly key: MaybeRefOrGetter<QueryKey>;
+    /** Fetches one page; receives the controlled `page` and the `AbortSignal`. */
+    readonly queryFn: (ctx: {
+        page: number;
+        signal: AbortSignal;
+    }) => Promise<TPage>;
+    /** The controlled page index — the caller owns it; changing it loads that page. A ref or getter drives it reactively (React re-rendered instead). */
+    readonly page: MaybeRefOrGetter<number>;
+    /** Extracts items from a page — the page itself is the item array when omitted. */
+    readonly mapPage?: (page: TPage) => readonly TItem[];
+    /** Gates the query — skips fetching while `false`. */
+    readonly enabled?: MaybeRefOrGetter<boolean>;
+    /** Metadata surfaced to the global `onError` seam — `suppressGlobalError: true` keeps this query's failures out of it. */
+    readonly meta?: AppQueryMeta;
+}
+/** Represents a page/offset paginated query's slice — every member reactive. */
+export interface UseAppPaginatedQueryReturn<TItem, TPage> {
+    /** The current page's items. */
+    readonly items: ComputedRef<readonly TItem[]>;
+    /** The raw page as fetched (`TPage`) — total count / page count / `hasMore` live here; `undefined` until the first page resolves. While `isPlaceholder`, it is the held previous page. */
+    readonly page: Ref<TPage | undefined>;
+    /** True while there is no page yet and a fetch is in flight. */
+    readonly loading: ComputedRef<boolean>;
+    /** The failure coerced to `ApiError`, or `null`. */
+    readonly error: ComputedRef<ApiError | null>;
+    /** True while the held previous page is being shown during a page change. */
+    readonly isPlaceholder: Ref<boolean>;
+    /** Refetches the active page. */
+    readonly refetch: () => unknown;
+}
+/** Manages page/offset pagination — wraps `useQuery` with `keepPreviousData` so the list holds steady between pages. */
+export declare function useAppPaginatedQuery<TItem, TPage>({ key, queryFn, page, mapPage, enabled, meta, }: UseAppPaginatedQueryOptions<TItem, TPage>): UseAppPaginatedQueryReturn<TItem, TPage>;

package/dist/query/UseAppQueries.d.ts

@@ -0,0 +1,43 @@
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
+import { QueryKey } from '@tanstack/vue-query';
+import { ApiError } from '../foundation/http';
+/** Defines one entry in a parallel `useAppQueries` batch — `TRaw` first so it infers from `queryFn` (a spread def) and `TData` defaults to it when `map` is absent. */
+export interface AppQueriesEntry<TRaw, TData = TRaw> {
+    /** The cache key (from `queryKeys`). */
+    readonly key: QueryKey;
+    /** Fetches this entry's raw payload; receives the `AbortSignal` so the request cancels on unmount. */
+    readonly queryFn: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<TRaw>;
+    /** Maps the raw payload to the domain shape — identity when omitted. */
+    readonly map?: (raw: TRaw) => TData;
+}
+/** Represents one entry's slice of a `useAppQueries` batch. */
+export interface AppQueryResult<TData> {
+    /** The mapped domain payload, or `undefined` until this entry resolves. */
+    readonly data: TData | undefined;
+    /** True while this entry has no data yet and a fetch is in flight. */
+    readonly loading: boolean;
+    /** This entry's failure coerced to `ApiError`, or `null`. */
+    readonly error: ApiError | null;
+}
+/** Defines options for `useAppQueries`. */
+export interface UseAppQueriesOptions<TRaw, TData = TRaw> {
+    /** The queries to run in parallel — the count may vary. A ref or getter re-builds the batch reactively. */
+    readonly queries: MaybeRefOrGetter<readonly AppQueriesEntry<TRaw, TData>[]>;
+    /** Gates the whole batch — skips fetching every entry while `false`. */
+    readonly enabled?: MaybeRefOrGetter<boolean>;
+}
+/** Represents a parallel batch's aggregated slice — every member reactive. */
+export interface UseAppQueriesReturn<TData> {
+    /** One slice per entry, in the order they were given. */
+    readonly results: ComputedRef<readonly AppQueryResult<TData>[]>;
+    /** Just the payloads, positionally aligned with the entries. */
+    readonly data: ComputedRef<readonly (TData | undefined)[]>;
+    /** True while any entry is still loading. */
+    readonly loading: ComputedRef<boolean>;
+    /** Every entry's failure, coerced. */
+    readonly errors: ComputedRef<readonly ApiError[]>;
+}
+/** Manages a dynamic batch of parallel queries — wraps `useQueries`, maps each raw→domain, and aggregates loading/errors. */
+export declare function useAppQueries<TRaw, TData = TRaw>({ queries, enabled, }: UseAppQueriesOptions<TRaw, TData>): UseAppQueriesReturn<TData>;

package/dist/query/UseAppQuery.d.ts

@@ -0,0 +1,38 @@
+import { ComputedRef, MaybeRefOrGetter, Ref } from 'vue';
+import { QueryKey } from '@tanstack/vue-query';
+import { ApiError } from '../foundation/http';
+import { AppQueryMeta } from './CreateQueryClient';
+/** Defines options for `useAppQuery` — `TRaw` first so it infers from `queryFn` (a spread def) and `TData` defaults to it when `map` is absent. */
+export interface UseAppQueryOptions<TRaw, TData = TRaw> {
+    /** The cache key (from `queryKeys`). A ref or getter re-keys the query reactively — React re-ran the hook instead. */
+    readonly key: MaybeRefOrGetter<QueryKey>;
+    /** Fetches the raw payload; receives the `AbortSignal` so the request cancels on unmount. */
+    readonly queryFn: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<TRaw>;
+    /** Maps the raw payload to the domain shape — identity when omitted. */
+    readonly map?: (raw: TRaw) => TData;
+    /** Gates the query — skips fetching while `false`. A ref or getter toggles it reactively. */
+    readonly enabled?: MaybeRefOrGetter<boolean>;
+    /** Metadata surfaced to the global `onError` seam — `suppressGlobalError: true` keeps this query's failures out of it. */
+    readonly meta?: AppQueryMeta;
+}
+/** Represents a single-resource query's slice — every member reactive. */
+export interface UseAppQueryReturn<TData> {
+    /** The mapped domain payload, or `undefined` until it resolves. */
+    readonly data: Ref<TData | undefined>;
+    /** True while there is no data yet and a fetch is in flight. */
+    readonly loading: ComputedRef<boolean>;
+    /** The failure coerced to `ApiError`, or `null`. */
+    readonly error: ComputedRef<ApiError | null>;
+    /** Refetches the query. */
+    readonly refetch: () => unknown;
+}
+/**
+ * Manages a single-resource query — wraps `useQuery`, maps raw→domain via `select`, and coerces
+ * failures to `ApiError`.
+ *
+ * Returns REFS, not values: `@tanstack/vue-query` hands back a ref per field, and a composable that
+ * unwrapped them would freeze at the first render. Read `data.value` (or bind `data` in a template).
+ */
+export declare function useAppQuery<TRaw, TData = TRaw>({ key, queryFn, map, enabled, meta, }: UseAppQueryOptions<TRaw, TData>): UseAppQueryReturn<TData>;

package/dist/query/UseAppSuspenseQuery.d.ts

@@ -0,0 +1,42 @@
+import { MaybeRefOrGetter, Ref } from 'vue';
+import { QueryKey } from '@tanstack/vue-query';
+import { AppQueryMeta } from './CreateQueryClient';
+/** Defines a suspenseful query — a key, a fetcher, and an optional raw→view mapper. `TRaw` first so it infers from `queryFn` (a spread def); `TData` defaults to it when `map` is absent. */
+export interface AppSuspenseQueryOptions<TRaw, TData = TRaw> {
+    /** The query key that identifies and caches this query. */
+    readonly key: MaybeRefOrGetter<QueryKey>;
+    /** Fetches the raw data; receives the abort signal the library manages. */
+    readonly queryFn: (context: {
+        signal: AbortSignal;
+    }) => Promise<TRaw>;
+    /** Maps the raw fetched shape to the view shape; identity when omitted. */
+    readonly map?: (raw: TRaw) => TData;
+    /** Metadata surfaced to the global `onError` seam — `suppressGlobalError: true` keeps this query's failures out of it (boundary-handled errors would otherwise double-surface). */
+    readonly meta?: AppQueryMeta;
+}
+/** Represents a resolved suspenseful query — `data` is already filled when the composable resolves. */
+export interface AppSuspenseQueryReturn<TData> {
+    /** The resolved payload. Defined on resolve, and kept live afterwards. */
+    readonly data: Ref<TData>;
+    /** Refetches the query. */
+    readonly refetch: () => unknown;
+}
+/**
+ * Manages a suspenseful query — the composable AWAITS the first resolution, so a `<script setup>`
+ * that awaits it suspends until data is there.
+ *
+ * ```vue
+ * <script setup lang="ts">
+ * const { data } = await useAppSuspenseQuery({ key: ['user'], queryFn });
+ * </script>
+ * ```
+ *
+ * `@tanstack/vue-query` ships no `useSuspenseQuery` — Vue suspends on an async `setup()` rather than
+ * on a thrown promise, so the library exposes `suspense()` on the query result and this awaits it.
+ * That makes this composable ASYNC where React's was synchronous, the one shape change the two
+ * suspense models force.
+ *
+ * The caller still owns both boundaries: a `<Suspense>` for loading, and an error boundary for
+ * failure — a rejected query rejects this promise and bubbles past the hook.
+ */
+export declare function useAppSuspenseQuery<TRaw, TData = TRaw>({ key, queryFn, map, meta, }: AppSuspenseQueryOptions<TRaw, TData>): Promise<AppSuspenseQueryReturn<TData>>;

package/dist/query/UseOptimisticMutation.d.ts

@@ -0,0 +1,25 @@
+import { QueryKey } from '@tanstack/vue-query';
+import { Endpoint } from './Endpoints';
+import { UseAppMutationReturn } from './UseAppMutation';
+/** Defines one cached query an optimistic mutation patches — where it lives and how it changes. */
+export interface OptimisticTarget<TVars, TCached = unknown> {
+    /** Locates the cached entry to patch — a query key, or an endpoint def (patched at its `key`). */
+    readonly key: QueryKey | Endpoint<TCached>;
+    /**
+     * Produces the next cached value from the current one and the mutation vars — pure, no side effects.
+     * `current` is `undefined` when the key holds no data yet; returning a value then seeds the entry
+     * (and rollback removes the seed).
+     */
+    apply(current: TCached | undefined, vars: TVars): TCached;
+}
+/** Defines options for `useOptimisticMutation`. */
+export interface UseOptimisticMutationOptions<TData, TVars> {
+    /** Performs the mutation against the backend. */
+    readonly mutationFn: (vars: TVars) => Promise<TData>;
+    /** The cached queries this mutation patches — each is cancelled, snapshotted, and applied before the request fires, then rolled back on error. */
+    readonly targets: readonly OptimisticTarget<TVars>[];
+    /** Invalidates every target key once the mutation settles (success or error) so the server truth reconciles the patch — `true` when omitted. */
+    readonly invalidateOnSettle?: boolean;
+}
+/** Manages an optimistic mutation — the canonical TanStack v5 flow in the house shape: cancel + snapshot + patch every target on mutate, roll the patches back on error, reconcile with the server on settle. `useAppMutation` stays the passive default. */
+export declare function useOptimisticMutation<TData, TVars>({ mutationFn, targets, invalidateOnSettle, }: UseOptimisticMutationOptions<TData, TVars>): UseAppMutationReturn<TData, TVars>;

package/dist/query/UsePrefetchQuery.d.ts

@@ -0,0 +1,26 @@
+import { QueryKey } from '@tanstack/vue-query';
+/** Defines a prefetch target — a query key paired with its fetcher. */
+export interface PrefetchTarget {
+    /** The query key to warm — the same key the live query reads. */
+    readonly key: QueryKey;
+    /** Fetches the data to cache; receives the abort signal the library manages. */
+    readonly queryFn: (context: {
+        signal: AbortSignal;
+    }) => Promise<unknown>;
+}
+/**
+ * Defines the hover/focus listeners to `v-bind` onto a link for data prefetch.
+ *
+ * `onMouseenter`, not React's `onMouseEnter`: Vue derives the DOM event name with `hyphenate()`, so
+ * a camel-humped `onMouseEnter` key would bind a `mouse-enter` event that never fires.
+ */
+export interface PrefetchProps {
+    /** Warms the target query when the pointer enters the link. */
+    readonly onMouseenter: () => void;
+    /** Warms the target query when the link gains focus. */
+    readonly onFocus: () => void;
+}
+/** Manages intent-based data prefetch — returns a `prefetch(target)` that warms a query on hover/focus. */
+export declare function usePrefetchQuery(): (target: PrefetchTarget) => void;
+/** Builds hover/focus listeners that warm a query's data on intent — `v-bind` onto a link beside the router's `prefetchProps`. Requires a mounted `usePrefetchQuery`. */
+export declare function prefetchProps(target: PrefetchTarget): PrefetchProps;

package/dist/query/UseQueryCache.d.ts

@@ -0,0 +1,31 @@
+import { QueryKey } from '@tanstack/vue-query';
+/** Defines a prefetch target for the query cache — a key paired with its fetcher. */
+export interface QueryCachePrefetch {
+    /** The query key to warm — the same key the live query reads. */
+    readonly key: QueryKey;
+    /** Fetches the data to cache; receives the `AbortSignal`. */
+    readonly queryFn: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<unknown>;
+}
+/** Defines the imperative cache accessor returned by `useQueryCache`. */
+export interface QueryCacheApi {
+    /** Reads the cached value at `key`, or `undefined` when absent. */
+    readonly get: <TData>(key: QueryKey) => TData | undefined;
+    /** Writes `key` — a value, or an updater `(previous) => next` (the TanStack setter form). */
+    readonly set: <TData>(key: QueryKey, data: TData | ((previous: TData | undefined) => TData)) => void;
+    /** Marks the queries under `key` stale and refetches the active ones. */
+    readonly invalidate: (key: QueryKey) => Promise<void>;
+    /** Removes the queries under `key` from the cache. */
+    readonly remove: (key: QueryKey) => void;
+    /** Warms `key` in the background — deduped against a live query. */
+    readonly prefetch: (target: QueryCachePrefetch) => Promise<void>;
+}
+/**
+ * Provides access to the query cache — imperative get/set/invalidate/remove/prefetch by key,
+ * wrapping the active `QueryClient`.
+ *
+ * Returns a plain object, as React did. There is nothing reactive here: every member is a command,
+ * and the client is stable for the component's lifetime, so React's `useMemo` has no counterpart.
+ */
+export declare function useQueryCache(): QueryCacheApi;

package/dist/query/index.d.ts

@@ -0,0 +1,19 @@
+export { createQueryClient, type CreateQueryClientOptions, type AppQueryMeta, type QueryErrorContext, } from './CreateQueryClient';
+export { queryPlugin } from './QueryPlugin';
+export { default as QueryProvider, type QueryProviderProps } from './QueryProvider.vue';
+export { toApiError } from './ToApiError';
+export { defineEndpoint, type Endpoint, type EndpointFn } from './Endpoints';
+export { useAppQuery, type UseAppQueryOptions, type UseAppQueryReturn } from './UseAppQuery';
+export { useAppInfiniteQuery, type UseAppInfiniteQueryOptions, type UseAppInfiniteQueryReturn, } from './UseAppInfiniteQuery';
+export { useAppMutation, type UseAppMutationOptions, type UseAppMutationReturn } from './UseAppMutation';
+export { useOptimisticMutation, type UseOptimisticMutationOptions, type OptimisticTarget, } from './UseOptimisticMutation';
+export { useAppQueries, type UseAppQueriesOptions, type UseAppQueriesReturn, type AppQueriesEntry, type AppQueryResult, } from './UseAppQueries';
+export { useAppPaginatedQuery, type UseAppPaginatedQueryOptions, type UseAppPaginatedQueryReturn, } from './UseAppPaginatedQuery';
+export { byPageToken, pageItems } from './PageHelpers';
+export { useAppLazyQuery, type UseAppLazyQueryOptions, type UseAppLazyQueryReturn } from './UseAppLazyQuery';
+export { useQueryCache, type QueryCacheApi, type QueryCachePrefetch } from './UseQueryCache';
+export { usePrefetchQuery, prefetchProps, type PrefetchTarget, type PrefetchProps } from './UsePrefetchQuery';
+export { useAppSuspenseQuery, type AppSuspenseQueryOptions, type AppSuspenseQueryReturn, } from './UseAppSuspenseQuery';
+export { QueryProgressBridge, useQueryProgressBridge } from './QueryProgressBridge';
+export { default as QueryDevtools, type QueryDevtoolsProps } from './Devtools.vue';
+export { setupQueryPersistence, type SetupQueryPersistenceOptions, type QueryPersistenceHandle } from './Persistence';