@eifi1/ui-kit 0.44.0 → 0.46.0

package/src/notifications/use-push-device.ts

@@ -2,6 +2,11 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useMediaQuery } from "../hooks/use-media-query";
 import { httpStatusOf } from "../auth/auth-errors";
+import { PUSH_SUBSCRIPTION_CHANGED, keyBytes, pushSubscriptionInput as inputOf } from "./push-worker";
+import type { PushSubscriptionInput } from "./push-worker";
+
+export { PUSH_SUBSCRIPTION_CHANGED };
+export type { PushSubscriptionInput };
 
 /**
  * This browser's Web Push subscription for the signed-in account
@@ -34,13 +39,6 @@ export class PushDeviceError extends Error {
   }
 }
 
-/** What `register` sends: `POST /notifications/devices` (§3.5). */
-export interface PushSubscriptionInput {
-  endpoint: string;
-  keys: { p256dh: string; auth: string };
-  user_agent: string | null;
-}
-
 export interface UsePushDeviceOptions {
   /** `GET /notifications/push-key` → its `key`; `""` when push is off on the server. */
   pushKey: () => Promise<string>;
@@ -92,14 +90,15 @@ export interface PushDevice {
   sendTest: () => Promise<{ sent: number }>;
 }
 
-/**
- * The window event every mounted {@link usePushDevice} re-reads its state on. Fired by
- * every enable and disable, and by `PushDevicesSetting` when it removes this device — so
- * an app's own card on the same hook (keksdose's check-up) stays in step. The hook that
- * fires it does not re-read: it knows what it changed. Namespaced for the kit;
- * keksdose's was `"keksdose:push-subscription-changed"`.
+/*
+ * PUSH_SUBSCRIPTION_CHANGED (push-worker.ts): the window event every mounted
+ * {@link usePushDevice} re-reads its state on. Fired by every enable and disable, and by
+ * `PushDevicesSetting` when it removes this device — so an app's own card on the same
+ * hook (keksdose's check-up) stays in step. The hook that fires it does not re-read: it
+ * knows what it changed. Since 0.46 also the message a service worker posts after a
+ * rotated subscription was re-registered (`handlePushSubscriptionChange`). Namespaced
+ * for the kit; keksdose's was `"keksdose:push-subscription-changed"`.
  */
-export const PUSH_SUBSCRIPTION_CHANGED = "eifi1:push-subscription-changed";
 
 /** Tell every {@link usePushDevice} that this browser's subscription changed. */
 export function notifyPushSubscriptionChanged(): void {
@@ -151,25 +150,6 @@ async function activeRegistration(): Promise<ServiceWorkerRegistration> {
   return within(navigator.serviceWorker.ready, READY_TIMEOUT_MS, "no_service_worker");
 }
 
-/** A VAPID public key (base64url) as the bytes `PushManager.subscribe` wants. */
-function keyBytes(key: string): Uint8Array<ArrayBuffer> {
-  const base64 = key.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (key.length % 4)) % 4);
-  const raw = atob(base64);
-  const bytes = new Uint8Array(new ArrayBuffer(raw.length));
-  for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
-  return bytes;
-}
-
-/** A subscription's register body, or `null` when the browser handed back an incomplete
- *  one. */
-function inputOf(subscription: PushSubscription): PushSubscriptionInput | null {
-  const json = subscription.toJSON();
-  const p256dh = json.keys?.p256dh;
-  const auth = json.keys?.auth;
-  if (!json.endpoint || !p256dh || !auth) return null;
-  return { endpoint: json.endpoint, keys: { p256dh, auth }, user_agent: navigator.userAgent || null };
-}
-
 const defaultEndpointTaken = (error: unknown) => httpStatusOf(error) === 409;
 
 /**
@@ -289,11 +269,18 @@ export function usePushDevice(options: UsePushDeviceOptions): PushDevice {
     const heard = () => {
       if (!announcing.current) void sync();
     };
+    // The worker's word after it re-registered a rotated subscription (0.46).
+    const fromWorker = (event: MessageEvent) => {
+      if ((event.data as { type?: unknown } | null)?.type === PUSH_SUBSCRIPTION_CHANGED) void sync();
+    };
+    const worker = navigator.serviceWorker as ServiceWorkerContainer | undefined;
     void sync();
     window.addEventListener(PUSH_SUBSCRIPTION_CHANGED, heard);
+    worker?.addEventListener?.("message", fromWorker);
     return () => {
       cancelled = true;
       window.removeEventListener(PUSH_SUBSCRIPTION_CHANGED, heard);
+      worker?.removeEventListener?.("message", fromWorker);
     };
   }, [supported]);
 

package/src/offline/local-first.ts

@@ -0,0 +1,76 @@
+import { isTransientRefreshFailure } from "../lib/session-refresh";
+
+/*
+ * The leaf utilities of local-first (docs/local-first-harmonization.md §2.3, 0.46): what a
+ * page and a sync engine both need, with no store behind them. One module that both
+ * `@eifi1/ui-kit/offline` and `@eifi1/ui-kit/sync` export, so `/sync` never loads
+ * `/offline`'s TanStack and idb-keyval peers, and `/offline` never loads Dexie. It imports
+ * no package at all (packaging-contract.test.ts holds that).
+ */
+
+/**
+ * An `updated_at` that wins Last-Write-Wins over `previous`: now, or one millisecond past
+ * `previous` when that is not behind this clock (keksdose's sync-client.ts:639-643).
+ *
+ * `/sync` keeps the server's row when it is STRICTLY newer, comparing this device's clock
+ * with the server's. A row the server just wrote carries the server's time, so an edit
+ * stamped by a clock a second slow would lose and come straight back. The millisecond is
+ * enough although the server keeps microseconds: `Date.parse` truncates them.
+ */
+export function stampAfter(previous: unknown): string {
+  const now = Date.now();
+  const prior = typeof previous === "string" ? Date.parse(previous) : Number.NaN;
+  return new Date(Number.isFinite(prior) && prior >= now ? prior + 1 : now).toISOString();
+}
+
+/**
+ * The connection, not the server, failed: the request had no answer (an axios-like error
+ * without `response`, or `fetch`'s `TypeError`), or the session refresh marked a 401 as
+ * passing because the server was out of reach ({@link isTransientRefreshFailure}). A real
+ * HTTP answer — a 4xx or a 5xx — is never offline: the caller must see it.
+ */
+export function isOfflineError(err: unknown): boolean {
+  if (isTransientRefreshFailure(err)) return true;
+  if (typeof err !== "object" || err === null) return false;
+  const bag = err as { isAxiosError?: unknown; response?: unknown };
+  if (bag.isAxiosError === true || "response" in bag) return bag.response == null;
+  return err instanceof TypeError;
+}
+
+/**
+ * Read from the server, and from the device's copy only when the connection failed
+ * ({@link isOfflineError}); a 4xx or 5xx still throws. `onOnline` gets the server's answer
+ * before it is returned (to refresh the copy, say); a throw from it counts as a failure of
+ * the online path. The plain form of keksdose's net.ts:58, without its sealed-household
+ * and cold-start branches (those stay keksdose's).
+ */
+export async function readLocalFirst<T>(
+  online: () => Promise<T>,
+  offline: () => Promise<T>,
+  onOnline?: (result: T) => void | Promise<void>,
+): Promise<T> {
+  try {
+    const result = await online();
+    await onOnline?.(result);
+    return result;
+  } catch (err) {
+    if (!isOfflineError(err)) throw err;
+    return offline();
+  }
+}
+
+/**
+ * Write through the server first (`rest`), and queue the change on the device (`queue`)
+ * only when the connection failed; any other failure throws, nothing queued. Online writes
+ * stay server-stamped (D2). A create mints its id BEFORE calling this and sends it on both
+ * paths, so a REST create that timed out after the server applied it is not created twice
+ * (D16).
+ */
+export async function writeLocalFirst<T>(rest: () => Promise<T>, queue: () => Promise<T>): Promise<T> {
+  try {
+    return await rest();
+  } catch (err) {
+    if (!isOfflineError(err)) throw err;
+    return queue();
+  }
+}

package/src/offline/pwa-update-prompt-labels.ts

@@ -0,0 +1,9 @@
+// The English words of ./pwa-update-prompt, in a module with no component code (0.34, KS U8).
+// keksdose's reviewed words (pwa.updateAvailable, pwa.reload) are the canon.
+
+import type { PwaUpdatePromptLabels } from "./pwa-update-prompt";
+
+export const DEFAULT_PWA_UPDATE_PROMPT_LABELS: PwaUpdatePromptLabels = {
+  updateAvailable: "A new version is available.",
+  reload: "Reload",
+};

package/src/offline/pwa-update-prompt.tsx

@@ -0,0 +1,72 @@
+import { useEffect, useRef } from "react";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { toast } from "../components/toast";
+import { DEFAULT_PWA_UPDATE_PROMPT_LABELS } from "./pwa-update-prompt-labels";
+
+/**
+ * "A new version is available. — Reload": keksdose's service-worker toast
+ * (app/pwa-update-prompt.tsx) as a kit component (docs/local-first-harmonization.md §1.5
+ * D8). The app keeps `useRegisterSW` (vite-plugin-pwa, `registerType: "prompt"`) and hands
+ * its state in: `needRefresh` from it, `onReload` = `updateServiceWorker(true)`,
+ * `onDismiss` = `setNeedRefresh(false)`.
+ *
+ * `hold` defers the prompt while a reload would hurt — a handover being signed, a tour
+ * running. Nothing shows while it holds; the toast appears once it drops. A hold that
+ * starts while the toast is up takes it down again until it drops.
+ *
+ * Renders nothing itself: the toast needs a mounted `<Toaster>`.
+ */
+export interface PwaUpdatePromptLabels {
+  updateAvailable: string;
+  reload: string;
+}
+
+// Defined in ./pwa-update-prompt-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_PWA_UPDATE_PROMPT_LABELS };
+
+export interface PwaUpdatePromptProps {
+  /** A new service worker is waiting. */
+  needRefresh: boolean;
+  /** Activates it and reloads — `updateServiceWorker(true)`. */
+  onReload: () => void;
+  /** The toast was closed without reloading. */
+  onDismiss?: () => void;
+  /** Wait: a handover is open, a tour runs. */
+  hold?: boolean;
+  labels?: LabelOverride<PwaUpdatePromptLabels>;
+}
+
+/** The toast's id: one prompt at a time, replaced in place. */
+const PWA_UPDATE_TOAST_ID = "pwa-update";
+
+export function PwaUpdatePrompt({ needRefresh, onReload, onDismiss, hold = false, labels: labelsProp }: PwaUpdatePromptProps) {
+  const labels = useKitLabels("pwaUpdate", DEFAULT_PWA_UPDATE_PROMPT_LABELS, labelsProp);
+  // The callbacks are read at click time, so a new function each render does not
+  // re-raise the toast.
+  const handlers = useRef({ onReload, onDismiss });
+  useEffect(() => {
+    handlers.current = { onReload, onDismiss };
+  });
+
+  const show = needRefresh && !hold;
+  useEffect(() => {
+    if (!show) return;
+    // sonner calls `onDismiss` for a programmatic dismiss too: the one this effect makes
+    // when a hold starts must not tell the app the person waved the update away.
+    let ours = false;
+    toast(labels.updateAvailable, {
+      id: PWA_UPDATE_TOAST_ID,
+      duration: Infinity,
+      action: { label: labels.reload, onClick: () => handlers.current.onReload() },
+      onDismiss: () => {
+        if (!ours) handlers.current.onDismiss?.();
+      },
+    });
+    return () => {
+      ours = true;
+      toast.dismiss(PWA_UPDATE_TOAST_ID);
+    };
+  }, [show, labels.updateAvailable, labels.reload]);
+
+  return null;
+}

package/src/offline/query-persistence.ts

@@ -0,0 +1,356 @@
+import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
+import type { QueryClient } from "@tanstack/react-query";
+import type { PersistedClient, PersistQueryClientOptions } from "@tanstack/react-query-persist-client";
+import { del, get, keys, set } from "idb-keyval";
+
+/**
+ * The persisted TanStack Query cache, keksdose's policy as a kit helper
+ * (docs/local-first-harmonization.md §1.5 D4, D5, D7; §1.6). keksdose's
+ * shared/state/query-client.ts is the canon: an IndexedDB persister, a deny-list, the
+ * plain-JSON guard on write (`shouldDehydrateQuery`) and its twin on restore that keeps
+ * paused mutations. On top: a key per account (and company), a scrub list that removes
+ * secret fields from payloads that are otherwise wanted offline, and `removeStale` for
+ * another account's leftovers.
+ *
+ * The only module of the kit that imports TanStack and idb-keyval: both are optional peers
+ * of `@eifi1/ui-kit/offline` and never reached from the main barrel (packaging-contract).
+ */
+
+/** A field name the scrub removes: an exact name, or a pattern (`/^signature_/`). */
+export type ScrubField = string | RegExp;
+
+/**
+ * Removed from every query's data, at any depth, before it is persisted (D4, D7): bank
+ * account numbers and the handover protocol's signatures. A page restored offline shows
+ * such a field as missing ("Needs a connection").
+ */
+export const DEFAULT_SCRUB_FIELDS: readonly ScrubField[] = Object.freeze([
+  "iban",
+  "qr_iban",
+  "default_qr_iban",
+  /^signature_/,
+]);
+
+/** The storage the persister writes to. The default is IndexedDB through idb-keyval. */
+export interface QueryPersistenceStorage {
+  getItem: (key: string) => Promise<string | null | undefined>;
+  setItem: (key: string, value: string) => Promise<unknown>;
+  removeItem: (key: string) => Promise<unknown>;
+  /** Every key in the store — what `removeStale` walks. */
+  keys: () => Promise<readonly unknown[]>;
+}
+
+export interface QueryPersistenceOptions {
+  /** The app's name, the key's first part: `kastlan` → `kastlan-query-cache-…`. */
+  app: string;
+  /** The signed-in account. One cache per account (D5). */
+  user: string | number;
+  /** The acting company, where the app has several (kastlan): the switch changes the key,
+   *  so no wipe and no cross-company leak — provided the app switches as
+   *  {@link QueryPersistence.leave} says (leave, then remount the provider per key). */
+  company?: string | number | null;
+  /** The app's own rule, beside `denyRoots` — keksdose denies one exact key and every key
+   *  whose second segment is `"admin"`. `false` keeps the query out. */
+  shouldPersistKey?: (queryKey: readonly unknown[]) => boolean;
+  /** Query roots (`queryKey[0]`) that never reach the disk: admin, billing, reports… */
+  denyRoots?: readonly string[];
+  /** Replaces {@link DEFAULT_SCRUB_FIELDS}; spread it to add to it. `[]` scrubs nothing.
+   *  A paused mutation whose variables carry one of these fields is never persisted (a
+   *  scrubbed mutation would send something else), and one an older build wrote is dropped
+   *  on restore. */
+  scrubFields?: readonly ScrubField[];
+  /** Told when a query's data is not plain JSON and is therefore not persisted. Default:
+   *  `console.error`, as keksdose's `cacheSafeOrWarn`. */
+  onUnsafe?: (queryKey: readonly unknown[], data: unknown) => void;
+  /** Changes with each deploy (the app version), so a new build discards the old cache. */
+  buster: string;
+  /** How long a persisted cache is good for, in ms (keksdose: 24 h). The QueryClient's
+   *  `gcTime` must be at least this, or restore drops every query. */
+  maxAge: number;
+  /** Default: IndexedDB (idb-keyval). Tests pass an in-memory one. */
+  storage?: QueryPersistenceStorage;
+  /** Default 1000 ms, as keksdose. */
+  throttleTime?: number;
+  /**
+   * 0.46 (kastlan K1): whether paused mutations are written with the cache. Default `true`
+   * (keksdose: an offline write waits in TanStack's queue and is sent after a reload).
+   * `false` keeps every mutation off the disk, and drops any an older build wrote on
+   * restore — for an app that queues offline writes in its own outbox (kastlan's Dexie
+   * outbox), instead of overriding `dehydrateOptions` by hand.
+   */
+  persistMutations?: boolean;
+}
+
+/**
+ * One persisted cache, for one key. **Mount it per key**: the provider subscribes once and
+ * ignores a changed `persistOptions`, so give it the key as its React key —
+ *
+ * ```tsx
+ * <PersistQueryClientProvider key={persistence.key} client={queryClient} persistOptions={persistence.persistOptions}>
+ * ```
+ *
+ * — and create the persistence once the account (and company) is known (`useMemo` on
+ * them); before sign-in, mount the plain `QueryClientProvider`. On a company switch, call
+ * {@link QueryPersistence.leave} on the old one BEFORE the new key mounts, instead of a bare
+ * `queryClient.clear()`: otherwise the old subscription saves the emptied (or the next
+ * company's) cache under the old key.
+ */
+export interface QueryPersistence {
+  /** `<app>-query-cache-<user>[-<company>]`. */
+  key: string;
+  /** Everything `<PersistQueryClientProvider persistOptions>` needs. */
+  persistOptions: Omit<PersistQueryClientOptions, "queryClient">;
+  /** Sign-out: stops writing under this key, empties the in-memory cache and deletes this
+   *  key's persisted copy. Best-effort; never throws. */
+  clear: (queryClient: QueryClient) => Promise<void>;
+  /** The company switch (or any change of key without a sign-out): stops writing under this
+   *  key — a save already scheduled is dropped too — and empties the in-memory cache, so
+   *  the next key's provider starts clean. The persisted copy stays for the way back. A
+   *  provider that mounts this persistence again re-arms it with its restore. Never throws. */
+  leave: (queryClient: QueryClient) => Promise<void>;
+  /** At sign-in: deletes this app's OTHER persisted caches older than `maxAge` (another
+   *  account's, another company's). Other apps' keys and fresh ones stay. Never throws. */
+  removeStale: () => Promise<void>;
+}
+
+const idbStorage: QueryPersistenceStorage = {
+  getItem: (key) => get<string>(key),
+  setItem: (key, value) => set(key, value),
+  removeItem: (key) => del(key),
+  keys: () => keys(),
+};
+
+export interface RemoveStaleQueryCopiesOptions {
+  /** Default: IndexedDB (idb-keyval), the store {@link createQueryPersistence} writes to. */
+  storage?: QueryPersistenceStorage;
+  /** One key to spare whatever its age — the signed-in account's own
+   *  (`QueryPersistence.removeStale` passes its key). */
+  keep?: string;
+}
+
+/**
+ * 0.46 (kastlan K2): deletes this app's persisted query caches (`<app>-query-cache-…`)
+ * older than `maxAge`, with no persistence at hand — for the sign-in page, where no
+ * account is known. A session that ended with no user known (a refresh token refused at
+ * boot) cannot name its key for `clear`; this sweeps its copy once it is stale, without
+ * waiting for someone's next sign-in. Other apps' keys, other stores' keys and fresh
+ * caches stay; an unreadable one is stale. Never throws.
+ * {@link QueryPersistence.removeStale} is this with `keep` = its own key.
+ */
+export async function removeStaleQueryCopies(
+  app: string,
+  maxAge: number,
+  { storage = idbStorage, keep }: RemoveStaleQueryCopiesOptions = {},
+): Promise<void> {
+  const prefix = `${app}-query-cache-`;
+  try {
+    const now = Date.now();
+    for (const k of await storage.keys()) {
+      if (typeof k !== "string" || !k.startsWith(prefix) || k === keep) continue;
+      let timestamp = 0;
+      try {
+        const raw = await storage.getItem(k);
+        const parsed: unknown = raw ? JSON.parse(raw) : null;
+        if (parsed && typeof parsed === "object" && typeof (parsed as PersistedClient).timestamp === "number") {
+          timestamp = (parsed as PersistedClient).timestamp;
+        }
+      } catch {
+        /* unreadable: stale */
+      }
+      if (now - timestamp > maxAge) await storage.removeItem(k);
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * True when `data` still means the same thing after JSON.stringify and JSON.parse —
+ * keksdose's `isCacheSafe` (query-client.ts:165). Class instances, Map/Set/Date/Blob, a
+ * non-finite number, a function: all refused. An `undefined` property survives.
+ */
+export function isCacheSafe(data: unknown, depth = 0): boolean {
+  if (depth > 12) return false;
+  if (data === null) return true;
+  const t = typeof data;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(data as number);
+  if (t !== "object") return false;
+  if (Array.isArray(data)) return data.every((v) => isCacheSafe(v, depth + 1));
+  const proto: unknown = Object.getPrototypeOf(data);
+  if (proto !== Object.prototype && proto !== null) return false;
+  return Object.values(data as Record<string, unknown>).every((v) => v === undefined || isCacheSafe(v, depth + 1));
+}
+
+/** A copy of `data` without the scrubbed fields, at any depth. The input is not touched. */
+function scrub(data: unknown, fields: readonly ScrubField[]): unknown {
+  if (fields.length === 0 || data === null || typeof data !== "object") return data;
+  if (Array.isArray(data)) return data.map((v) => scrub(v, fields));
+  const out: Record<string, unknown> = {};
+  for (const [name, value] of Object.entries(data as Record<string, unknown>)) {
+    if (fields.some((f) => (typeof f === "string" ? f === name : f.test(name)))) continue;
+    out[name] = scrub(value, fields);
+  }
+  return out;
+}
+
+const defaultOnUnsafe = (queryKey: readonly unknown[]) => {
+  console.error(
+    `[query-cache] refusing to persist ${JSON.stringify(queryKey)}: the value is not plain JSON ` +
+      `(a class instance, Map, Set, Date or Blob). Return plain data from the queryFn and build ` +
+      `the rich object at the call site.`,
+  );
+};
+
+export function createQueryPersistence({
+  app,
+  user,
+  company,
+  shouldPersistKey,
+  denyRoots = [],
+  scrubFields = DEFAULT_SCRUB_FIELDS,
+  onUnsafe = defaultOnUnsafe,
+  buster,
+  maxAge,
+  storage = idbStorage,
+  throttleTime = 1000,
+  persistMutations = true,
+}: QueryPersistenceOptions): QueryPersistence {
+  const prefix = `${app}-query-cache-`;
+  const key = `${prefix}${user}${company === undefined || company === null || company === "" ? "" : `-${company}`}`;
+  const denied = new Set(denyRoots);
+  // Set by `leave` and `clear`: a write under this key after the person left it (a
+  // throttled save of the emptied cache) is dropped. A restore re-arms it.
+  let retired = false;
+
+  const keyAllowed = (queryKey: readonly unknown[]) =>
+    !denied.has(String(queryKey[0])) && (shouldPersistKey ? shouldPersistKey(queryKey) : true);
+
+  /** The write side: a success, an allowed key, plain JSON (or the warning). */
+  const shouldDehydrateQuery = (query: {
+    queryKey: readonly unknown[];
+    state: { status: string; data?: unknown };
+  }): boolean => {
+    if (query.state.status !== "success" || !keyAllowed(query.queryKey)) return false;
+    if (isCacheSafe(query.state.data)) return true;
+    onUnsafe(query.queryKey, query.state.data);
+    return false;
+  };
+
+  /** One persisted query entry, scrubbed; `null` when it may not be restored. */
+  const restorable = (entry: unknown): unknown => {
+    if (!entry || typeof entry !== "object") return null;
+    const { queryKey, state } = entry as { queryKey?: unknown; state?: { data?: unknown } };
+    if (!Array.isArray(queryKey) || !keyAllowed(queryKey)) return null;
+    if (!isCacheSafe(state?.data)) return null;
+    return withScrubbedData(entry);
+  };
+
+  /** Whether `value` has a scrubbed field's name anywhere in it. */
+  const carriesScrubbed = (value: unknown, depth = 0): boolean => {
+    if (scrubFields.length === 0 || depth > 12 || value === null || typeof value !== "object") return false;
+    if (Array.isArray(value)) return value.some((v) => carriesScrubbed(v, depth + 1));
+    return Object.entries(value as Record<string, unknown>).some(
+      ([name, v]) =>
+        scrubFields.some((f) => (typeof f === "string" ? f === name : f.test(name))) || carriesScrubbed(v, depth + 1),
+    );
+  };
+
+  /** The write side for mutations: TanStack's default (paused ones), minus any whose
+   *  variables carry a scrubbed field (S6); none at all with `persistMutations: false`. */
+  const shouldDehydrateMutation = (mutation: { state: { isPaused: boolean; variables?: unknown } }): boolean =>
+    persistMutations && mutation.state.isPaused && !carriesScrubbed(mutation.state.variables);
+
+  const withScrubbedData = (entry: unknown): unknown => {
+    const query = entry as { state?: { data?: unknown } };
+    if (!query.state || !("data" in query.state)) return entry;
+    return { ...query, state: { ...query.state, data: scrub(query.state.data, scrubFields) } };
+  };
+
+  // The scrub on the way OUT: the in-memory cache keeps the field (the page that is open
+  // shows it), the disk never sees it. Mutations are a paused write queue and are kept
+  // whole — scrubbing one would change what it sends — so one carrying a scrubbed field is
+  // not written at all (`shouldDehydrateMutation`).
+  const serialize = (client: PersistedClient): string =>
+    JSON.stringify({
+      ...client,
+      clientState: { ...client.clientState, queries: client.clientState.queries.map(withScrubbedData) },
+    });
+
+  // The twin on the way IN (keksdose's `sanitizePersistedCache`, :264-298): an older build
+  // wrote what this one may deny. Never throws; an unreadable blob comes back with
+  // `timestamp: 0`, which the restore treats as unusable and removes.
+  const deserialize = (raw: string): PersistedClient => {
+    const empty: PersistedClient = { timestamp: 0, buster: "", clientState: { mutations: [], queries: [] } };
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object") return empty;
+      const { timestamp, buster: stored, clientState } = parsed as Partial<PersistedClient>;
+      if (typeof timestamp !== "number" || typeof stored !== "string") return empty;
+      if (!clientState || typeof clientState !== "object" || !Array.isArray(clientState.queries)) return empty;
+      return {
+        timestamp,
+        buster: stored,
+        clientState: {
+          mutations: persistMutations && Array.isArray(clientState.mutations)
+            ? clientState.mutations.filter(
+                (m) => !carriesScrubbed((m as { state?: { variables?: unknown } } | null)?.state?.variables),
+              )
+            : [],
+          queries: clientState.queries.map(restorable).filter((q) => q !== null) as PersistedClient["clientState"]["queries"],
+        },
+      };
+    } catch {
+      return empty;
+    }
+  };
+
+  const persister = createAsyncStoragePersister({
+    storage: {
+      // Only the provider's restore reads: mounting this persistence again re-arms it.
+      getItem: async (k) => {
+        retired = false;
+        return (await storage.getItem(k)) ?? null;
+      },
+      setItem: async (k, v) => {
+        if (!retired) await storage.setItem(k, v);
+      },
+      removeItem: async (k) => {
+        await storage.removeItem(k);
+      },
+    },
+    key,
+    throttleTime,
+    serialize,
+    deserialize,
+  });
+
+  const leave = async (queryClient: QueryClient) => {
+    retired = true;
+    try {
+      queryClient.clear();
+    } catch {
+      /* best-effort */
+    }
+  };
+
+  const clear = async (queryClient: QueryClient) => {
+    retired = true;
+    try {
+      queryClient.clear();
+      await persister.removeClient();
+    } catch {
+      /* best-effort: private mode / IndexedDB unavailable */
+    }
+  };
+
+  const removeStale = () => removeStaleQueryCopies(app, maxAge, { storage, keep: key });
+
+  return {
+    key,
+    persistOptions: { persister, maxAge, buster, dehydrateOptions: { shouldDehydrateQuery, shouldDehydrateMutation } },
+    clear,
+    leave,
+    removeStale,
+  };
+}