@veams/status-quo-query 0.12.0 → 0.13.1

package/.turbo/turbo-build.log

@@ -1,14 +1,14 @@
 
 
-> @veams/status-quo-query@0.3.0 build
+> @veams/status-quo-query@0.12.0 build
 > npm-run-all compile
 
 
-> @veams/status-quo-query@0.3.0 compile
+> @veams/status-quo-query@0.12.0 compile
 > npm-run-all bundle:ts
 
 
-> @veams/status-quo-query@0.3.0 bundle:ts
+> @veams/status-quo-query@0.12.0 bundle:ts
 > tsc --project tsconfig.json
 
 ⠙⠙⠙

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+- Fixed `QueryHandle.subscribe(...)` to mount the TanStack `QueryClient` lifecycle while a query handle subscription is active, restoring `refetchOnWindowFocus` and reconnect behavior for stale subscribed queries.
+- Documented how `staleTime`, `refetchOnWindowFocus`, `bindSubscribable(...)`, and passive cache reads interact in the wrapper.
+
 ## 0.1.0
 
 - Initial package scaffold for TanStack Query and mutation services.

package/README.md

@@ -19,11 +19,11 @@ npm install react
 Status Quo Query deliberately keeps the public surface small:
 
 - `QueryHandle<TData, TError>` is the read handle for one query.
-- `MutationService<TData, TError, TVariables>` is the write handle for one mutation.
+- `MutationHandle<TData, TError, TVariables>` is the write handle for one mutation.
 - snapshots are passive state objects returned from `getSnapshot()` and `subscribe(...)`.
 - commands stay on the handle: `refetch()`, `invalidate()`, `mutate()`, `reset()`.
 - `QueryManager` is the broader coordination layer for cross-query work.
-- `@veams/status-quo-query/react` is optional and adds one React subscription hook over the same handle shape.
+- `@veams/status-quo-query/react` is optional and adds React subscription hooks (`useQueryHandle`, `useMutationHandle`) over the same handle shape.
 
 That keeps the package usable in service code, query handlers, state handlers, and React components without changing the core query or mutation API.
 
@@ -49,13 +49,13 @@ Root exports:
 - `CreateUntrackedMutation`
 - `QueryHandle`
 - `QueryHandleData`
-- `MutationService`
+- `MutationHandle`
 - `QueryHandleSnapshot`
-- `MutationServiceSnapshot`
+- `MutationHandleSnapshot`
 - `QueryDependencyTuple`
 - `QueryHandleOptions`
-- `MutationServiceOptions`
-- `TrackedMutationServiceOptions`
+- `MutationHandleOptions`
+- `TrackedMutationHandleOptions`
 - `QueryInvalidateOptions`
 - `QueryMetaState`
 - `TrackedDependencyRecord`
@@ -70,7 +70,7 @@ Subpath exports:
 - `@veams/status-quo-query/provider`
 - `@veams/status-quo-query/query`
 - `@veams/status-quo-query/mutation`
-- `@veams/status-quo-query/react`
+- `@veams/status-quo-query/react` (`useQueryHandle`, `useMutationHandle`)
 
 ## Quickstart
 
@@ -133,8 +133,9 @@ await userQuery.invalidate({ refetchType: 'none' });
 
 ## React Bindings
 
-The React entrypoint exposes `useQueryHandle(...)` and keeps `react` optional unless you
-import `@veams/status-quo-query/react`.
+The React entrypoint exposes `useQueryHandle(...)` and `useMutationHandle(...)` and keeps `react` optional unless you import `@veams/status-quo-query/react`.
+
+### `useQueryHandle`
 
 ```tsx
 import { useQueryHandle } from '@veams/status-quo-query/react';
@@ -153,6 +154,35 @@ Use the hook when a component should subscribe directly to a query handle and re
 - call `query.refetch()` or `query.invalidate()` on the handle itself
 - derive view-specific values in the component instead of adding selector logic to the hook
 
+### `useMutationHandle`
+
+```tsx
+import { useMutationHandle } from '@veams/status-quo-query/react';
+import type { MutationHandle } from '@veams/status-quo-query';
+
+function SaveButton({
+  mutation,
+  payload,
+}: {
+  mutation: MutationHandle<{ ok: boolean }, Error, { name: string }>;
+  payload: { name: string };
+}) {
+  const snapshot = useMutationHandle(mutation);
+
+  return (
+    <button onClick={() => mutation.mutate(payload)} disabled={snapshot.isPending}>
+      {snapshot.isPending ? 'Saving…' : 'Save'}
+    </button>
+  );
+}
+```
+
+Use `useMutationHandle` when a component should react to mutation state (pending, success, error). Keep imperative calls on the handle itself:
+
+- read `status`, `isPending`, `isError`, `isSuccess`, `data`, `error`, `variables` from the snapshot
+- call `mutation.mutate(variables)` or `mutation.reset()` on the handle itself
+- the hook does not trigger the mutation — it only subscribes to its state
+
 ## Status Quo Integration
 
 The same query handle can also feed a `status-quo` handler through `bindSubscribable(...)`.
@@ -763,7 +793,7 @@ Only `deps` participates in automatic invalidation tracking. `view` is optional
 
 `createQuery(queryKey, queryFn, options?)` returns the same `QueryHandle<TData, TError>` shape as `createUntrackedQuery(...)`, but it registers the query hash under every `deps` entry, re-registers on `refetch()` or the first `subscribe(...)` if TanStack has removed the cache entry in the meantime, and keeps the registry in sync when `dependsOn` derives a new tracked key at runtime.
 
-`createMutation(mutationFn, options?)` returns the same `MutationService<TData, TError, TVariables, TOnMutateResult>` shape as `createUntrackedMutation(...)`, but adds:
+`createMutation(mutationFn, options?)` returns the same `MutationHandle<TData, TError, TVariables, TOnMutateResult>` shape as `createUntrackedMutation(...)`, but adds:
 
 - `dependencyKeys?`
 - `resolveDependencies?`
@@ -786,7 +816,7 @@ Captures dependency names once and returns:
 - the tracked query factory
 - a tracked mutation factory whose default resolver reads `variables[dependencyKey]`
 
-The tracked query factory still expects a query key with a final `{ deps, view? }` segment. The tracked mutation factory keeps the same `MutationService` shape as `createMutation(...)`, but no longer needs `dependencyKeys` repeated in each call.
+The tracked query factory still expects a query key with a final `{ deps, view? }` segment. The tracked mutation factory keeps the same `MutationHandle` shape as `createMutation(...)`, but no longer needs `dependencyKeys` repeated in each call.
 
 Reach for standalone `createMutation(...)` when:
 
@@ -840,15 +870,106 @@ It also adds:
 
 `unsafe_getResult()` returns the raw TanStack `QueryObserverResult`.
 
+### Window focus and stale queries
+
+`QueryHandle.subscribe(...)` activates the same TanStack `QueryClient` lifecycle that
+`QueryClientProvider` activates for `useQuery`.
+
+TanStack's `refetchOnWindowFocus` support does not live on the individual
+`QueryObserver` alone. A `QueryClient` has to be mounted so TanStack can subscribe to
+the global `focusManager` and forward browser focus changes to the query cache. Native
+React Query users usually get this through:
+
+```tsx
+<QueryClientProvider client={queryClient}>
+  <App />
+</QueryClientProvider>
+```
+
+Status Quo Query does not require that provider because query handles can be used in
+service code, state handlers, and React components. Instead, a subscribed query handle
+mounts the provided `QueryClient` for as long as that handle subscription is active:
+
+```ts
+const query = createUntrackedQuery(['clock'], fetchClock, {
+  staleTime: 5_000,
+  refetchOnWindowFocus: true,
+});
+
+const unsubscribe = query.subscribe((snapshot) => {
+  console.log(snapshot.data);
+});
+
+// Later, when the state handler or component is destroyed:
+unsubscribe();
+```
+
+With an active subscription, the flow is:
+
+1. The first `subscribe(...)` mounts the `QueryClient`.
+2. TanStack installs its focus and online listeners through `focusManager` and
+   `onlineManager`.
+3. The `QueryObserver` performs its normal mount behavior and starts stale timers.
+4. Once `staleTime` has elapsed, the observer marks the current result stale.
+5. When the browser window becomes focused again, TanStack calls `queryCache.onFocus()`.
+6. Active stale queries with `refetchOnWindowFocus: true` refetch.
+7. Unsubscribing removes the observer and unmounts the client lifecycle for that
+   subscription.
+
+This means `staleTime` and `refetchOnWindowFocus` behave the same way through a
+`QueryHandle` subscription as they do through `useQuery`:
+
+```ts
+const query = createUntrackedQuery(
+  ['staleTime'],
+  () => Promise.resolve(new Date()),
+  {
+    staleTime: 5_000,
+  }
+);
+```
+
+The default TanStack behavior is preserved. `refetchOnWindowFocus` defaults to `true`,
+so the query above refetches on focus only after it has become stale. Use
+`refetchOnWindowFocus: 'always'` when focus should refetch even while the cached data is
+still fresh, or `refetchOnWindowFocus: false` when focus should never refetch that
+query.
+
+`bindSubscribable(...)` integrations also participate automatically because they call
+`QueryHandle.subscribe(...)` internally:
+
+```ts
+this.bindSubscribable(productQuery, (snapshot) => {
+  this.setState({
+    product: snapshot.data,
+    productStatus: snapshot.status,
+  });
+});
+```
+
+The state handler receives:
+
+- an initial snapshot, either synchronously from the observer or through
+  `getSnapshot()`
+- the stale-result update after `staleTime` expires
+- a fresh snapshot after the window regains focus and the stale query refetches
+
+One-off reads do not install focus listeners. `getSnapshot()`, `getQueryData(...)`,
+`getQueryState(...)`, and `fetchQuery(...)` are passive cache reads or explicit fetches;
+they are not live observers. Use `subscribe(...)`, `useQueryHandle(...)`, or
+`bindSubscribable(...)` when the query should respond to TanStack observer lifecycle
+events such as `refetchOnWindowFocus`, `refetchOnReconnect`, stale timers, and refetch
+intervals.
+
 ### `setupMutation(queryClient)`
 
 Creates a `createUntrackedMutation` factory bound to a `QueryClient`.
 
-`createUntrackedMutation(mutationFn, options?)` returns `MutationService<TData, TError, TVariables, TOnMutateResult>`.
+`createUntrackedMutation(mutationFn, options?)` returns `MutationHandle<TData, TError, TVariables, TOnMutateResult>`.
 
-`MutationServiceOptions` is based on TanStack `MutationObserverOptions`, without `mutationFn` because it is provided directly to `createUntrackedMutation`.
+`MutationHandleOptions` is based on TanStack `MutationObserverOptions`, without `mutationFn` because it is provided directly to `createUntrackedMutation`.
 
-`MutationService` methods:
+`MutationHandle` methods:
 
 - `getSnapshot()`
 - `subscribe(listener)`
@@ -856,7 +977,7 @@ Creates a `createUntrackedMutation` factory bound to a `QueryClient`.
 - `reset()`
 - `unsafe_getResult()`
 
-`MutationServiceSnapshot<TData, TError, TVariables>` fields:
+`MutationHandleSnapshot<TData, TError, TVariables>` fields:
 
 - `data`
 - `error`

package/dist/mutation.d.ts

@@ -4,7 +4,7 @@ export type MutationStatus = TanstackMutationStatus;
 /**
  * Represents a stable snapshot of the mutation service's state.
  */
-export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
+export interface MutationHandleSnapshot<TData = unknown, TError = Error, TVariables = void> {
     data: TData | undefined;
     error: TError | null;
     status: MutationStatus;
@@ -17,9 +17,9 @@ export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVaria
 /**
  * Defines the public API for a mutation service.
  */
-export interface MutationService<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> {
-    getSnapshot: () => MutationServiceSnapshot<TData, TError, TVariables>;
-    subscribe: (listener: (snapshot: MutationServiceSnapshot<TData, TError, TVariables>) => void) => () => void;
+export interface MutationHandle<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> {
+    getSnapshot: () => MutationHandleSnapshot<TData, TError, TVariables>;
+    subscribe: (listener: (snapshot: MutationHandleSnapshot<TData, TError, TVariables>) => void) => () => void;
     mutate: (variables: TVariables, options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>) => Promise<TData>;
     reset: () => void;
     unsafe_getResult: () => MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
@@ -27,12 +27,12 @@ export interface MutationService<TData = unknown, TError = Error, TVariables = v
 /**
  * Configuration options for creating a mutation service, excluding the mutation function itself.
  */
-export type MutationServiceOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
+export type MutationHandleOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
 /**
  * Function signature for the untracked mutation factory.
  */
 export interface CreateUntrackedMutation {
-    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 /**
  * Additional options for tracked mutations that invalidate queries automatically.
@@ -41,7 +41,7 @@ export interface CreateUntrackedMutation {
  * options only describe how the facade should derive dependency values and when it should
  * invalidate matching tracked queries after the mutation lifecycle settles.
  */
-export interface TrackedMutationServiceOptions<TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> extends MutationServiceOptions<TData, TError, TVariables, TOnMutateResult> {
+export interface TrackedMutationHandleOptions<TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> extends MutationHandleOptions<TData, TError, TVariables, TOnMutateResult> {
     dependencyKeys?: readonly (keyof TDeps & string)[];
     resolveDependencies?: (variables: TVariables) => Partial<TDeps>;
     invalidateOn?: TrackedInvalidateOn;
@@ -51,7 +51,7 @@ export interface TrackedMutationServiceOptions<TDeps extends TrackedDependencyRe
  * Function signature for the default mutation factory with automatic invalidation.
  */
 export interface CreateMutation {
-    <TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    <TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: TrackedMutationHandleOptions<TDeps, TData, TError, TVariables, TOnMutateResult>): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 /**
  * Prepares the mutation factory by binding it to a specific QueryClient instance.

package/dist/mutation.js

@@ -8,7 +8,7 @@ import { pickTrackedDependencies, resolveTrackedQueries, toTrackedDependencyEntr
 export function setupMutation(queryClient) {
     // Returns the actual factory function for creating individual mutation services.
     return function createMutation(mutationFn, options) {
-        return createMutationService(queryClient, mutationFn, options);
+        return createMutationHandle(queryClient, mutationFn, options);
     };
 }
 /**
@@ -22,8 +22,8 @@ export function setupTrackedMutation(queryClient, trackingRegistry, defaultDepen
     return function createMutation(mutationFn, options) {
         // Split tracked-only options from the underlying TanStack mutation observer options.
         const { dependencyKeys, invalidateOn = 'success', matchMode = 'intersection', resolveDependencies, ...mutationOptions } = options ?? {};
-        // Reuse the normal mutation service so snapshots and subscription behavior stay identical.
-        const service = createMutationService(queryClient, mutationFn, mutationOptions);
+        // Reuse the normal mutation handle so snapshots and subscription behavior stay identical.
+        const handle = createMutationHandle(queryClient, mutationFn, mutationOptions);
         // The paired helper injects dependency keys here, while standalone tracked mutations can
         // still provide them directly or bypass them with a custom resolver.
         const resolvedDependencyKeys = (dependencyKeys ?? defaultDependencyKeys);
@@ -41,12 +41,12 @@ export function setupTrackedMutation(queryClient, trackingRegistry, defaultDepen
             })));
         };
         return {
-            ...service,
+            ...handle,
             mutate: async (variables, mutateOptions) => {
                 try {
                     // Let TanStack finish the mutation first so its own callbacks and state machine remain
                     // authoritative. The facade only coordinates the follow-up invalidation.
-                    const result = await service.mutate(variables, mutateOptions);
+                    const result = await handle.mutate(variables, mutateOptions);
                     if (invalidateOn === 'success' || invalidateOn === 'settled') {
                         await invalidateTrackedQueries(variables);
                     }
@@ -71,7 +71,7 @@ export function setupTrackedMutation(queryClient, trackingRegistry, defaultDepen
 /**
  * Internal helper to transform a raw Tanstack mutation result into our public snapshot format.
  */
-function toMutationServiceSnapshot(result) {
+function toMutationHandleSnapshot(result) {
     // Extract and return the relevant fields for the UI or other services.
     return {
         data: result.data,
@@ -84,7 +84,7 @@ function toMutationServiceSnapshot(result) {
         isSuccess: result.isSuccess,
     };
 }
-function createMutationService(queryClient, mutationFn, options) {
+function createMutationHandle(queryClient, mutationFn, options) {
     // Keep the original mutation implementation in one place so tracked and untracked mutations
     // always expose the same observer-backed runtime behavior.
     const observer = new MutationObserver(queryClient, {
@@ -92,9 +92,9 @@ function createMutationService(queryClient, mutationFn, options) {
         mutationFn,
     });
     return {
-        getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+        getSnapshot: () => toMutationHandleSnapshot(observer.getCurrentResult()),
         subscribe: (listener) => observer.subscribe((result) => {
-            listener(toMutationServiceSnapshot(result));
+            listener(toMutationHandleSnapshot(result));
         }),
         mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
         reset: () => observer.reset(),

package/dist/mutation.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"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"}

package/dist/provider.d.ts

@@ -1,5 +1,5 @@
 import { type QueryClient, type MutationFunction } from '@tanstack/query-core';
-import { type CreateMutation, type CreateUntrackedMutation, type MutationService, type TrackedMutationServiceOptions } from './mutation.js';
+import { type CreateMutation, type CreateUntrackedMutation, type MutationHandle, type TrackedMutationHandleOptions } from './mutation.js';
 import { type CreateQuery, type CreateUntrackedQuery } from './query.js';
 import { type TrackedDependencyValue } from './tracking.js';
 /**
@@ -9,7 +9,7 @@ import { type TrackedDependencyValue } from './tracking.js';
  * once at setup time and injects them automatically for each tracked mutation it creates.
  */
 export interface CreateMutationWithDefaults<TDependencyKey extends string> {
-    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: Omit<TrackedMutationServiceOptions<Record<TDependencyKey, TrackedDependencyValue>, TData, TError, TVariables, TOnMutateResult>, 'dependencyKeys'>): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: Omit<TrackedMutationHandleOptions<Record<TDependencyKey, TrackedDependencyValue>, TData, TError, TVariables, TOnMutateResult>, 'dependencyKeys'>): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 /**
  * Paired tracked helper that captures dependency keys once for default mutation resolution.

package/dist/query.js

@@ -152,9 +152,13 @@ function createQueryHandle(queryClient, queryKey, queryFn, options) {
         setDerivedState,
         handle: {
             getSnapshot: () => toQueryHandleSnapshot(observer.getCurrentResult()),
-            subscribe: (listener) => observer.subscribe((result) => {
+            subscribe: (listener) => 
+            // QueryObserver subscriptions alone are not enough for browser lifecycle events.
+            // TanStack wires focus/reconnect refetching through QueryClient.mount(), so every
+            // live QueryHandle subscription must also activate the client lifecycle.
+            subscribeToMountedQueryClient(queryClient, () => observer.subscribe((result) => {
                 listener(toQueryHandleSnapshot(result));
-            }),
+            })),
             refetch: async (refetchOptions) => toQueryHandleSnapshot(await observer.refetch(refetchOptions)),
             invalidate: (invalidateOptions) => queryClient.invalidateQueries({
                 exact: true,
@@ -167,6 +171,49 @@ function createQueryHandle(queryClient, queryKey, queryFn, options) {
         },
     };
 }
+/**
+ * Subscribes to a TanStack observer while the owning QueryClient is mounted.
+ *
+ * Native `useQuery` users normally get this lifecycle from `QueryClientProvider`, which calls
+ * `queryClient.mount()` and lets TanStack subscribe to `focusManager` and `onlineManager`.
+ * Status Quo Query can be used without a React provider, so the wrapper has to mount the client
+ * when a query handle becomes live.
+ *
+ * Mounting is intentionally scoped to `subscribe(...)` rather than `setupQuery(...)`:
+ *
+ * - passive reads such as `getSnapshot()` and `getQueryData(...)` should not install global
+ *   focus/online listeners
+ * - short-lived factories should not leave a permanently mounted client behind
+ * - TanStack reference-counts `mount()` / `unmount()`, so multiple active handles can safely
+ *   mount the same client at the same time
+ *
+ * This is the piece that makes `staleTime` + `refetchOnWindowFocus` behave like native
+ * `useQuery`: the observer marks itself stale after the stale timer expires, then the mounted
+ * client forwards the next focus event to the query cache so active stale queries refetch.
+ */
+function subscribeToMountedQueryClient(queryClient, subscribe) {
+    queryClient.mount();
+    let isSubscribed = true;
+    let unsubscribe;
+    try {
+        unsubscribe = subscribe();
+    }
+    catch (error) {
+        // Keep mount/unmount balanced if the observer subscription throws before returning cleanup.
+        queryClient.unmount();
+        throw error;
+    }
+    return () => {
+        if (!isSubscribed) {
+            return;
+        }
+        isSubscribed = false;
+        unsubscribe();
+        // Balance the mount for this specific subscription. TanStack keeps the client mounted while
+        // any other active subscription has also called mount().
+        queryClient.unmount();
+    };
+}
 function bindQueryDependencies(queryHandle, queryKey, dependsOn) {
     const dependencyController = createDependencyController(queryKey, queryHandle.setDerivedState, dependsOn);
     let subscriberCount = 0;

package/dist/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/dist/react/hooks/index.d.ts

@@ -1 +1,2 @@
 export { useQueryHandle } from './use-query-handle.js';
+export { useMutationHandle } from './use-mutation-handle.js';

package/dist/react/hooks/index.js

@@ -1,2 +1,3 @@
 export { useQueryHandle } from './use-query-handle.js';
+export { useMutationHandle } from './use-mutation-handle.js';
 //# sourceMappingURL=index.js.map

package/dist/react/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/react/hooks/use-mutation-handle.d.ts

@@ -0,0 +1,2 @@
+import type { MutationHandle, MutationHandleSnapshot } from '../../mutation.js';
+export declare function useMutationHandle<TData, TError = Error, TVariables = void>(mutationHandle: MutationHandle<TData, TError, TVariables>): MutationHandleSnapshot<TData, TError, TVariables>;

package/dist/react/hooks/use-mutation-handle.js

@@ -0,0 +1,71 @@
+// Import the React hooks needed to memoize callbacks, hold mutable cache state,
+// and connect an external store to React rendering.
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+// Subscribe a React component to a MutationHandle and return its latest snapshot.
+export function useMutationHandle(
+// Receive the external mutation handle instance to subscribe to.
+mutationHandle) {
+    // Count store notifications so we can tell when our cached snapshot is stale.
+    const snapshotVersionRef = useRef(0);
+    // Cache one client-side snapshot per observed version to keep getSnapshot stable.
+    const snapshotCacheRef = useRef(null);
+    // Cache the server snapshot separately for the useSyncExternalStore SSR fallback.
+    const serverSnapshotCacheRef = useRef(null);
+    // Create the subscribe function expected by useSyncExternalStore.
+    const subscribe = useCallback(
+    // React passes a listener that must run whenever the external store changes.
+    (listener) => 
+    // Forward the subscription to the mutation handle.
+    mutationHandle.subscribe(() => {
+        // Bump the version so later reads know the previous cache is outdated.
+        snapshotVersionRef.current += 1;
+        // Drop the cached client snapshot because the store just changed.
+        snapshotCacheRef.current = null;
+        // Drop the cached server snapshot for the same reason.
+        serverSnapshotCacheRef.current = null;
+        // Notify React that it should read a fresh snapshot.
+        listener();
+    }), 
+    // Recreate the subscription function only when the handle instance changes.
+    [mutationHandle]);
+    // Read the current client snapshot in a referentially stable way for React.
+    const getSnapshot = useCallback(() => {
+        // Read the latest store version number.
+        const version = snapshotVersionRef.current;
+        // Read the last cached client snapshot, if there is one.
+        const cachedSnapshot = snapshotCacheRef.current;
+        // Reuse the cached snapshot when it was produced for the current version.
+        if (cachedSnapshot && cachedSnapshot.version === version) {
+            // Return the cached snapshot so repeated reads in the same render stay stable.
+            return cachedSnapshot.snapshot;
+        }
+        // Ask the mutation handle for the latest snapshot because the cache is empty or stale.
+        const snapshot = mutationHandle.getSnapshot();
+        // Store the new snapshot together with the version it belongs to.
+        snapshotCacheRef.current = {
+            snapshot,
+            version,
+        };
+        // Return the freshly read snapshot to React.
+        return snapshot;
+    }, [mutationHandle]);
+    // Read the server snapshot used by React during SSR or hydration fallback paths.
+    const getServerSnapshot = useCallback(() => {
+        // Read the cached server snapshot, if one was stored earlier.
+        const cachedSnapshot = serverSnapshotCacheRef.current;
+        // Reuse the cached server snapshot to keep server reads stable.
+        if (cachedSnapshot) {
+            // Return the cached server snapshot directly.
+            return cachedSnapshot;
+        }
+        // Ask the mutation handle for a snapshot because no server cache exists yet.
+        const snapshot = mutationHandle.getSnapshot();
+        // Cache that snapshot for the next server read.
+        serverSnapshotCacheRef.current = snapshot;
+        // Return the freshly read server snapshot.
+        return snapshot;
+    }, [mutationHandle]);
+    // Let React subscribe to the external store and read snapshots through the callbacks above.
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+//# sourceMappingURL=use-mutation-handle.js.map

package/dist/react/hooks/use-mutation-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mutation-handle.js","sourceRoot":"","sources":["../../../src/react/hooks/use-mutation-handle.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAelE,kFAAkF;AAClF,MAAM,UAAU,iBAAiB;AAC/B,iEAAiE;AACjE,cAAyD;IAEzD,8EAA8E;IAC9E,MAAM,kBAAkB,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACrC,kFAAkF;IAClF,MAAM,gBAAgB,GAAG,MAAM,CAAuD,IAAI,CAAC,CAAC;IAC5F,kFAAkF;IAClF,MAAM,sBAAsB,GAAG,MAAM,CACnC,IAAI,CACL,CAAC;IAEF,kEAAkE;IAClE,MAAM,SAAS,GAAG,WAAW;IAC3B,6EAA6E;IAC7E,CAAC,QAAkB,EAAE,EAAE;IACrB,mDAAmD;IACnD,cAAc,CAAC,SAAS,CAAC,GAAG,EAAE;QAC5B,uEAAuE;QACvE,kBAAkB,CAAC,OAAO,IAAI,CAAC,CAAC;QAChC,kEAAkE;QAClE,gBAAgB,CAAC,OAAO,GAAG,IAAI,CAAC;QAChC,uDAAuD;QACvD,sBAAsB,CAAC,OAAO,GAAG,IAAI,CAAC;QACtC,qDAAqD;QACrD,QAAQ,EAAE,CAAC;IACb,CAAC,CAAC;IACJ,4EAA4E;IAC5E,CAAC,cAAc,CAAC,CACjB,CAAC;IAEF,4EAA4E;IAC5E,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;QACnC,wCAAwC;QACxC,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC;QAC3C,yDAAyD;QACzD,MAAM,cAAc,GAAG,gBAAgB,CAAC,OAAO,CAAC;QAEhD,0EAA0E;QAC1E,IAAI,cAAc,IAAI,cAAc,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YACzD,+EAA+E;YAC/E,OAAO,cAAc,CAAC,QAAQ,CAAC;QACjC,CAAC;QAED,uFAAuF;QACvF,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;QAC9C,kEAAkE;QAClE,gBAAgB,CAAC,OAAO,GAAG;YACzB,QAAQ;YACR,OAAO;SACR,CAAC;QAEF,6CAA6C;QAC7C,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAErB,iFAAiF;IACjF,MAAM,iBAAiB,GAAG,WAAW,CAAC,GAAG,EAAE;QACzC,8DAA8D;QAC9D,MAAM,cAAc,GAAG,sBAAsB,CAAC,OAAO,CAAC;QAEtD,gEAAgE;QAChE,IAAI,cAAc,EAAE,CAAC;YACnB,8CAA8C;YAC9C,OAAO,cAAc,CAAC;QACxB,CAAC;QAED,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;QAC9C,gDAAgD;QAChD,sBAAsB,CAAC,OAAO,GAAG,QAAQ,CAAC;QAE1C,2CAA2C;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAErB,4FAA4F;IAC5F,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;AACzE,CAAC"}

package/dist/react/index.d.ts

@@ -1 +1 @@
-export { useQueryHandle } from './hooks/index.js';
+export { useQueryHandle, useMutationHandle } from './hooks/index.js';

package/dist/react/index.js

@@ -1,2 +1,2 @@
-export { useQueryHandle } from './hooks/index.js';
+export { useQueryHandle, useMutationHandle } from './hooks/index.js';
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo-query",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/__tests__/query.spec.ts

@@ -1,4 +1,4 @@
-import { QueryClient } from '@tanstack/query-core';
+import { focusManager, QueryClient } from '@tanstack/query-core';
 
 import { isQueryLoading, setupQuery, toQueryMetaState } from '../query';
 
@@ -43,6 +43,40 @@ describe('Query Service', () => {
     expect(statuses).toContain('success');
   });
 
+  it('refetches stale subscribed queries when window focus returns', async () => {
+    jest.useFakeTimers();
+
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const createQuery = setupQuery(queryClient);
+    const queryFn = jest
+      .fn()
+      .mockResolvedValueOnce('initial')
+      .mockResolvedValueOnce('focused');
+    const service = createQuery(['demo', 'focus'], queryFn, { staleTime: 5_000 });
+    const unsubscribe = service.subscribe(() => undefined);
+
+    try {
+      await flushTasks();
+
+      expect(queryFn).toHaveBeenCalledTimes(1);
+      expect(service.getSnapshot().data).toBe('initial');
+
+      jest.advanceTimersByTime(5_001);
+      await flushTasks();
+
+      focusManager.setFocused(false);
+      focusManager.setFocused(true);
+      await flushTasks();
+
+      expect(queryFn).toHaveBeenCalledTimes(2);
+      expect(service.getSnapshot().data).toBe('focused');
+    } finally {
+      unsubscribe();
+      focusManager.setFocused(undefined);
+      jest.useRealTimers();
+    }
+  });
+
   it('invalidates its own query key exactly', async () => {
     const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
     const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');

package/src/mutation.ts

@@ -32,7 +32,7 @@ export type MutationStatus = TanstackMutationStatus;
 /**
  * Represents a stable snapshot of the mutation service's state.
  */
-export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
+export interface MutationHandleSnapshot<TData = unknown, TError = Error, TVariables = void> {
   // The data returned from a successful mutation.
   data: TData | undefined;
   // The error object if the mutation failed.
@@ -54,17 +54,17 @@ export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVaria
 /**
  * Defines the public API for a mutation service.
  */
-export interface MutationService<
+export interface MutationHandle<
   TData = unknown,
   TError = Error,
   TVariables = void,
   TOnMutateResult = unknown,
 > {
   // Returns the current state snapshot of the mutation.
-  getSnapshot: () => MutationServiceSnapshot<TData, TError, TVariables>;
+  getSnapshot: () => MutationHandleSnapshot<TData, TError, TVariables>;
   // Subscribes a listener to state changes; returns an unsubscribe function.
   subscribe: (
-    listener: (snapshot: MutationServiceSnapshot<TData, TError, TVariables>) => void
+    listener: (snapshot: MutationHandleSnapshot<TData, TError, TVariables>) => void
   ) => () => void;
   // Triggers the mutation with the given variables and optional lifecycle callbacks.
   mutate: (
@@ -80,7 +80,7 @@ export interface MutationService<
 /**
  * Configuration options for creating a mutation service, excluding the mutation function itself.
  */
-export type MutationServiceOptions<
+export type MutationHandleOptions<
   TData = unknown,
   TError = Error,
   TVariables = void,
@@ -95,8 +95,8 @@ export interface CreateUntrackedMutation {
     // The asynchronous function that performs the mutation.
     mutationFn: MutationFunction<TData, TVariables>,
     // Optional configuration for behavior like retry or lifecycle hooks.
-    options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 
 /**
@@ -106,13 +106,13 @@ export interface CreateUntrackedMutation {
  * options only describe how the facade should derive dependency values and when it should
  * invalidate matching tracked queries after the mutation lifecycle settles.
  */
-export interface TrackedMutationServiceOptions<
+export interface TrackedMutationHandleOptions<
   TDeps extends TrackedDependencyRecord = TrackedDependencyRecord,
   TData = unknown,
   TError = Error,
   TVariables = void,
   TOnMutateResult = unknown,
-> extends MutationServiceOptions<TData, TError, TVariables, TOnMutateResult> {
+> extends MutationHandleOptions<TData, TError, TVariables, TOnMutateResult> {
   // Optional dependency keys used by the default variable reader.
   dependencyKeys?: readonly (keyof TDeps & string)[];
   // Optional custom resolver when mutation variables do not expose dependency fields directly.
@@ -135,8 +135,8 @@ export interface CreateMutation {
     TOnMutateResult = unknown,
   >(
     mutationFn: MutationFunction<TData, TVariables>,
-    options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    options?: TrackedMutationHandleOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 
 /**
@@ -151,9 +151,9 @@ export function setupMutation(queryClient: QueryClient): CreateUntrackedMutation
     TOnMutateResult = unknown,
   >(
     mutationFn: MutationFunction<TData, TVariables>,
-    options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult> {
-    return createMutationService(queryClient, mutationFn, options);
+    options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult> {
+    return createMutationHandle(queryClient, mutationFn, options);
   };
 }
 
@@ -177,8 +177,8 @@ export function setupTrackedMutation(
     TOnMutateResult = unknown,
   >(
     mutationFn: MutationFunction<TData, TVariables>,
-    options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult> {
+    options?: TrackedMutationHandleOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult> {
     // Split tracked-only options from the underlying TanStack mutation observer options.
     const {
       dependencyKeys,
@@ -187,8 +187,8 @@ export function setupTrackedMutation(
       resolveDependencies,
       ...mutationOptions
     } = options ?? {};
-    // Reuse the normal mutation service so snapshots and subscription behavior stay identical.
-    const service = createMutationService(queryClient, mutationFn, mutationOptions);
+    // Reuse the normal mutation handle so snapshots and subscription behavior stay identical.
+    const handle = createMutationHandle(queryClient, mutationFn, mutationOptions);
     // The paired helper injects dependency keys here, while standalone tracked mutations can
     // still provide them directly or bypass them with a custom resolver.
     const resolvedDependencyKeys = (dependencyKeys ?? defaultDependencyKeys);
@@ -220,12 +220,12 @@ export function setupTrackedMutation(
     };
 
     return {
-      ...service,
+      ...handle,
       mutate: async (variables, mutateOptions) => {
         try {
           // Let TanStack finish the mutation first so its own callbacks and state machine remain
           // authoritative. The facade only coordinates the follow-up invalidation.
-          const result = await service.mutate(variables, mutateOptions);
+          const result = await handle.mutate(variables, mutateOptions);
 
           if (invalidateOn === 'success' || invalidateOn === 'settled') {
             await invalidateTrackedQueries(variables);
@@ -252,9 +252,9 @@ export function setupTrackedMutation(
 /**
  * Internal helper to transform a raw Tanstack mutation result into our public snapshot format.
  */
-function toMutationServiceSnapshot<TData, TError, TVariables, TOnMutateResult>(
+function toMutationHandleSnapshot<TData, TError, TVariables, TOnMutateResult>(
   result: MutationObserverResult<TData, TError, TVariables, TOnMutateResult>
-): MutationServiceSnapshot<TData, TError, TVariables> {
+): MutationHandleSnapshot<TData, TError, TVariables> {
   // Extract and return the relevant fields for the UI or other services.
   return {
     data: result.data,
@@ -268,7 +268,7 @@ function toMutationServiceSnapshot<TData, TError, TVariables, TOnMutateResult>(
   };
 }
 
-function createMutationService<
+function createMutationHandle<
   TData = unknown,
   TError = Error,
   TVariables = void,
@@ -276,8 +276,8 @@ function createMutationService<
 >(
   queryClient: QueryClient,
   mutationFn: MutationFunction<TData, TVariables>,
-  options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
-): MutationService<TData, TError, TVariables, TOnMutateResult> {
+  options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>
+): MutationHandle<TData, TError, TVariables, TOnMutateResult> {
   // Keep the original mutation implementation in one place so tracked and untracked mutations
   // always expose the same observer-backed runtime behavior.
   const observer = new MutationObserver<TData, TError, TVariables, TOnMutateResult>(queryClient, {
@@ -286,10 +286,10 @@ function createMutationService<
   });
 
   return {
-    getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+    getSnapshot: () => toMutationHandleSnapshot(observer.getCurrentResult()),
     subscribe: (listener) =>
       observer.subscribe((result) => {
-        listener(toMutationServiceSnapshot(result));
+        listener(toMutationHandleSnapshot(result));
       }),
     mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
     reset: () => observer.reset(),

package/src/provider.ts

@@ -8,8 +8,8 @@ import {
 import {
   type CreateMutation,
   type CreateUntrackedMutation,
-  type MutationService,
-  type TrackedMutationServiceOptions,
+  type MutationHandle,
+  type TrackedMutationHandleOptions,
   setupMutation,
   setupTrackedMutation,
 } from './mutation.js';
@@ -29,7 +29,7 @@ export interface CreateMutationWithDefaults<TDependencyKey extends string> {
   <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
     mutationFn: MutationFunction<TData, TVariables>,
     options?: Omit<
-      TrackedMutationServiceOptions<
+      TrackedMutationHandleOptions<
         Record<TDependencyKey, TrackedDependencyValue>,
         TData,
         TError,
@@ -38,7 +38,7 @@ export interface CreateMutationWithDefaults<TDependencyKey extends string> {
       >,
       'dependencyKeys'
     >
-  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 
 /**
@@ -54,13 +54,13 @@ export interface CreateQueryAndMutation {
  * Defines the public API for the query manager facade.
  */
 export interface QueryManager {
-  // Factory for creating a dependency-tracked mutation service within the context of this provider.
+  // Factory for creating a dependency-tracked mutation handle within the context of this provider.
   createMutation: CreateMutation;
   // Factory for creating a dependency-tracked query handle within the context of this provider.
   createQuery: CreateQuery;
   // Factory for creating an untracked query handle within the context of this provider.
   createUntrackedQuery: CreateUntrackedQuery;
-  // Factory for creating an untracked mutation service within the context of this provider.
+  // Factory for creating an untracked mutation handle within the context of this provider.
   createUntrackedMutation: CreateUntrackedMutation;
   // Convenience helper that shares dependency keys between tracked queries and mutations.
   createQueryAndMutation: CreateQueryAndMutation;
@@ -126,7 +126,7 @@ export function setupQueryManager(queryClient: QueryClient): QueryManager {
       > = <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
         mutationFn: MutationFunction<TData, TVariables>,
         options?: Omit<
-          TrackedMutationServiceOptions<
+          TrackedMutationHandleOptions<
             Record<TDependencyKeys[number], TrackedDependencyValue>,
             TData,
             TError,

package/src/query.ts

@@ -424,9 +424,14 @@ function createQueryHandle<
     handle: {
       getSnapshot: () => toQueryHandleSnapshot(observer.getCurrentResult()),
       subscribe: (listener) =>
-        observer.subscribe((result) => {
-          listener(toQueryHandleSnapshot(result));
-        }),
+        // QueryObserver subscriptions alone are not enough for browser lifecycle events.
+        // TanStack wires focus/reconnect refetching through QueryClient.mount(), so every
+        // live QueryHandle subscription must also activate the client lifecycle.
+        subscribeToMountedQueryClient(queryClient, () =>
+          observer.subscribe((result) => {
+            listener(toQueryHandleSnapshot(result));
+          })
+        ),
       refetch: async (refetchOptions) =>
         toQueryHandleSnapshot(await observer.refetch(refetchOptions)),
       invalidate: (invalidateOptions) =>
@@ -445,6 +450,56 @@ function createQueryHandle<
   };
 }
 
+/**
+ * Subscribes to a TanStack observer while the owning QueryClient is mounted.
+ *
+ * Native `useQuery` users normally get this lifecycle from `QueryClientProvider`, which calls
+ * `queryClient.mount()` and lets TanStack subscribe to `focusManager` and `onlineManager`.
+ * Status Quo Query can be used without a React provider, so the wrapper has to mount the client
+ * when a query handle becomes live.
+ *
+ * Mounting is intentionally scoped to `subscribe(...)` rather than `setupQuery(...)`:
+ *
+ * - passive reads such as `getSnapshot()` and `getQueryData(...)` should not install global
+ *   focus/online listeners
+ * - short-lived factories should not leave a permanently mounted client behind
+ * - TanStack reference-counts `mount()` / `unmount()`, so multiple active handles can safely
+ *   mount the same client at the same time
+ *
+ * This is the piece that makes `staleTime` + `refetchOnWindowFocus` behave like native
+ * `useQuery`: the observer marks itself stale after the stale timer expires, then the mounted
+ * client forwards the next focus event to the query cache so active stale queries refetch.
+ */
+function subscribeToMountedQueryClient(
+  queryClient: QueryClient,
+  subscribe: () => () => void
+): () => void {
+  queryClient.mount();
+
+  let isSubscribed = true;
+  let unsubscribe: () => void;
+
+  try {
+    unsubscribe = subscribe();
+  } catch (error) {
+    // Keep mount/unmount balanced if the observer subscription throws before returning cleanup.
+    queryClient.unmount();
+    throw error;
+  }
+
+  return () => {
+    if (!isSubscribed) {
+      return;
+    }
+
+    isSubscribed = false;
+    unsubscribe();
+    // Balance the mount for this specific subscription. TanStack keeps the client mounted while
+    // any other active subscription has also called mount().
+    queryClient.unmount();
+  };
+}
+
 function bindQueryDependencies<
   TSources extends readonly unknown[] = [],
   TQueryFnData = unknown,

package/src/react/__tests__/use-mutation-handle.spec.tsx

@@ -0,0 +1,107 @@
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { QueryClient } from '@tanstack/query-core';
+
+import { setupMutation } from '../../mutation.js';
+import { useMutationHandle } from '../hooks/use-mutation-handle.js';
+
+import type { MutationHandle, MutationHandleSnapshot } from '../../mutation.js';
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+describe('useMutationHandle', () => {
+  let container: HTMLDivElement;
+
+  beforeAll(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+  });
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it('renders the latest mutation snapshot', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { mutations: { retry: 0 } } });
+    const createMutation = setupMutation(queryClient);
+    const mutationFn = jest.fn((_payload: { name: string }) =>
+      Promise.resolve({ ok: true as const })
+    );
+    const handle = createMutation(mutationFn);
+    const statuses: string[] = [];
+
+    const Consumer = () => {
+      const snapshot = useMutationHandle(handle);
+      statuses.push(snapshot.status);
+
+      return <span>{snapshot.status}</span>;
+    };
+
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(<Consumer />);
+    });
+
+    expect(container.textContent).toBe('idle');
+
+    await act(async () => {
+      await handle.mutate({ name: 'Ada' });
+    });
+
+    expect(container.textContent).toBe('success');
+    expect(statuses).toContain('idle');
+    expect(statuses).toContain('pending');
+    expect(statuses).toContain('success');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('cleans up the store subscription on unmount', async () => {
+    const snapshot: MutationHandleSnapshot<{ ok: true }, Error, void> = {
+      data: { ok: true },
+      error: null,
+      status: 'success',
+      variables: undefined,
+      isError: false,
+      isIdle: false,
+      isPending: false,
+      isSuccess: true,
+    };
+    const unsubscribe = jest.fn();
+    const handle: MutationHandle<{ ok: true }, Error, void> = {
+      getSnapshot: () => snapshot,
+      subscribe: jest.fn(() => unsubscribe),
+      mutate: jest.fn(async () => ({ ok: true as const })),
+      reset: jest.fn(),
+      unsafe_getResult: jest.fn(),
+    };
+
+    const root = createRoot(container);
+
+    const Consumer = () => {
+      useMutationHandle(handle);
+      return <span>ready</span>;
+    };
+
+    await act(async () => {
+      root.render(<Consumer />);
+    });
+
+    expect(handle.subscribe).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      root.unmount();
+    });
+
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/hooks/index.ts

@@ -1 +1,2 @@
 export { useQueryHandle } from './use-query-handle.js';
+export { useMutationHandle } from './use-mutation-handle.js';

package/src/react/hooks/use-mutation-handle.ts

@@ -0,0 +1,98 @@
+// Import the React hooks needed to memoize callbacks, hold mutable cache state,
+// and connect an external store to React rendering.
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+
+// Import the mutation-handle contract and the stable snapshot shape the hook returns.
+import type { MutationHandle, MutationHandleSnapshot } from '../../mutation.js';
+// Describe the no-argument listener shape expected by useSyncExternalStore.
+type Listener = () => void;
+
+// Store one cached snapshot together with the store version it belongs to.
+type SnapshotCacheEntry<TData, TError, TVariables> = {
+  // Hold the snapshot returned by the mutation handle for this version.
+  snapshot: MutationHandleSnapshot<TData, TError, TVariables>;
+  // Track which subscription version produced the cached snapshot.
+  version: number;
+};
+
+// Subscribe a React component to a MutationHandle and return its latest snapshot.
+export function useMutationHandle<TData, TError = Error, TVariables = void>(
+  // Receive the external mutation handle instance to subscribe to.
+  mutationHandle: MutationHandle<TData, TError, TVariables>
+) {
+  // Count store notifications so we can tell when our cached snapshot is stale.
+  const snapshotVersionRef = useRef(0);
+  // Cache one client-side snapshot per observed version to keep getSnapshot stable.
+  const snapshotCacheRef = useRef<SnapshotCacheEntry<TData, TError, TVariables> | null>(null);
+  // Cache the server snapshot separately for the useSyncExternalStore SSR fallback.
+  const serverSnapshotCacheRef = useRef<MutationHandleSnapshot<TData, TError, TVariables> | null>(
+    null
+  );
+
+  // Create the subscribe function expected by useSyncExternalStore.
+  const subscribe = useCallback(
+    // React passes a listener that must run whenever the external store changes.
+    (listener: Listener) =>
+      // Forward the subscription to the mutation handle.
+      mutationHandle.subscribe(() => {
+        // Bump the version so later reads know the previous cache is outdated.
+        snapshotVersionRef.current += 1;
+        // Drop the cached client snapshot because the store just changed.
+        snapshotCacheRef.current = null;
+        // Drop the cached server snapshot for the same reason.
+        serverSnapshotCacheRef.current = null;
+        // Notify React that it should read a fresh snapshot.
+        listener();
+      }),
+    // Recreate the subscription function only when the handle instance changes.
+    [mutationHandle]
+  );
+
+  // Read the current client snapshot in a referentially stable way for React.
+  const getSnapshot = useCallback(() => {
+    // Read the latest store version number.
+    const version = snapshotVersionRef.current;
+    // Read the last cached client snapshot, if there is one.
+    const cachedSnapshot = snapshotCacheRef.current;
+
+    // Reuse the cached snapshot when it was produced for the current version.
+    if (cachedSnapshot && cachedSnapshot.version === version) {
+      // Return the cached snapshot so repeated reads in the same render stay stable.
+      return cachedSnapshot.snapshot;
+    }
+
+    // Ask the mutation handle for the latest snapshot because the cache is empty or stale.
+    const snapshot = mutationHandle.getSnapshot();
+    // Store the new snapshot together with the version it belongs to.
+    snapshotCacheRef.current = {
+      snapshot,
+      version,
+    };
+
+    // Return the freshly read snapshot to React.
+    return snapshot;
+  }, [mutationHandle]);
+
+  // Read the server snapshot used by React during SSR or hydration fallback paths.
+  const getServerSnapshot = useCallback(() => {
+    // Read the cached server snapshot, if one was stored earlier.
+    const cachedSnapshot = serverSnapshotCacheRef.current;
+
+    // Reuse the cached server snapshot to keep server reads stable.
+    if (cachedSnapshot) {
+      // Return the cached server snapshot directly.
+      return cachedSnapshot;
+    }
+
+    // Ask the mutation handle for a snapshot because no server cache exists yet.
+    const snapshot = mutationHandle.getSnapshot();
+    // Cache that snapshot for the next server read.
+    serverSnapshotCacheRef.current = snapshot;
+
+    // Return the freshly read server snapshot.
+    return snapshot;
+  }, [mutationHandle]);
+
+  // Let React subscribe to the external store and read snapshots through the callbacks above.
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/react/index.ts

@@ -1 +1 @@
-export { useQueryHandle } from './hooks/index.js';
+export { useQueryHandle, useMutationHandle } from './hooks/index.js';