@oxy.so/services 8.4.0 → 9.1.0

package/lib/typescript/module/ui/hooks/queryClient.d.ts

@@ -5,27 +5,25 @@
  * - TanStack Query with `networkMode: 'offlineFirst'` for queries and mutations
  *   so cached data is served immediately and mutations are queued (paused) while
  *   the browser/device reports offline.
- * - `persistQueryClient(...)` from `@tanstack/react-query-persist-client` so that
- *   query results AND paused mutations survive a cold restart (kill-and-relaunch).
+ * - `attachQueryPersistence(...)` so that query results AND paused mutations
+ *   survive a cold restart (kill-and-relaunch); see `persistedQueryCache.ts`.
  * - `onlineManager` resume hook so paused mutations replay the moment the
  *   network is reported back, even if the host app swapped in a custom
  *   onlineManager implementation.
  *
- * Storage layer:
- * - React Native -> AsyncStorage via `createAsyncStoragePersister`.
- * - Web -> localStorage via `createSyncStoragePersister` (wrapped in the
- *   async persister API for a single call site).
- * - Both adapters are content-shape compatible with our `StorageInterface`.
+ * Storage layer: the platform `StorageInterface` (AsyncStorage on native,
+ * localStorage on web).
  *
  * Whitelist policy:
  * - Persist every account/user/session/privacy query and every queued mutation.
  * - DO NOT persist large list queries (e.g. activity feeds) — they go stale
  *   fast and would balloon storage. Add new keys to `PERSISTED_QUERY_PREFIXES`
- *   when introducing reads that should survive restart.
+ *   (`persistedQueryCache.ts`) when introducing reads that should survive restart.
  */
-import { QueryClient, type QueryKey } from '@tanstack/react-query';
-import { type PersistedClient } from '@tanstack/react-query-persist-client';
+import { QueryClient } from '@tanstack/react-query';
+import type { PersistedClient } from '@tanstack/react-query-persist-client';
 import type { StorageInterface } from '../utils/storageHelpers.js';
+import { type AccountQueriesConfig } from './accountQueryPersistence.js';
 /** Retry only failures that another attempt can plausibly change. */
 export declare function shouldRetryQuery(failureCount: number, error: unknown): boolean;
 /**
@@ -47,21 +45,18 @@ export interface AttachPersistenceResult {
     unsubscribe: () => void;
 }
 /**
- * Wire `persistQueryClient` to the supplied storage adapter.
+ * Restore, then keep writing, the account-agnostic cache.
  *
- * Returns once the in-flight restore promise is available so callers can
- * `await result.restored` before rendering UI that depends on cached data.
+ * Queries written by another build are dropped; queued mutations are kept
+ * (`persistedQueryCache.ts`). Whatever the app declared account-scoped
+ * (`accountQueries`) is left to `createAccountQueryPersistence`, even under
+ * one of the SDK's prefixes, so private rows never land in the shared blob and
+ * a paused mutation cannot replay twice or under another account.
  *
  * Safe to no-op if `storage` is null/undefined (e.g. server-side render
  * with no host storage).
  */
-export declare const attachQueryPersistence: (queryClient: QueryClient, storage: StorageInterface | null | undefined, 
-/**
- * Mutation keys the app declared account-scoped (`accountQueries`). Those are
- * persisted per account by `createAccountQueryPersistence`, never here, so a
- * paused mutation cannot replay twice or under another account.
- */
-accountMutationKeys?: readonly QueryKey[]) => AttachPersistenceResult;
+export declare const attachQueryPersistence: (queryClient: QueryClient, storage: StorageInterface | null | undefined, accountQueries?: AccountQueriesConfig) => AttachPersistenceResult;
 /**
  * Remove the persisted query+mutation cache (used on full sign-out / data reset).
  * Safe to call even if persistence was never attached.

package/lib/typescript/module/ui/hooks/queryClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queryClient.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/queryClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,WAAW,EAAqD,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtH,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAAyB,CAAC;AAehE,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAK9E;AAwDD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,QAAO,WA6CpC,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GACjC,aAAa,WAAW,EACxB,SAAS,gBAAgB,GAAG,IAAI,GAAG,SAAS;AAC5C;;;;GAIG;AACH,sBAAqB,SAAS,QAAQ,EAAO,KAC5C,uBAwCF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAQ7E,CAAC;AAEF;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"queryClient.d.ts","sourceRoot":"","sources":["../../../../../src/ui/hooks/queryClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,WAAW,EAA4C,MAAM,uBAAuB,CAAC;AAC9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAAyB,CAAC;AAChE,OAAO,EAAyB,KAAK,oBAAoB,EAAE,MAAM,8BAA2B,CAAC;AAe7F,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAK9E;AAeD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,QAAO,WA6CpC,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,aAAa,WAAW,EACxB,SAAS,gBAAgB,GAAG,IAAI,GAAG,SAAS,EAC5C,iBAAiB,oBAAoB,KACpC,uBA8CF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAU,SAAS,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAQ7E,CAAC;AAEF;;GAEG;AACH,YAAY,EAAE,eAAe,EAAE,CAAC"}

package/lib/typescript/module/ui/icons/MaterialCommunityIcons.d.ts

@@ -1,4 +1,4 @@
 /** Glyphs are decorative: hidden from assistive technology (see `decorativeIconSet`). */
-declare const MaterialCommunityIcons: import("@expo/vector-icons/build/createIconSet").Icon<"function" | "sort" | "at" | "label" | "link" | "ellipse" | "image" | "switch" | "text" | "alert" | "alert-circle" | "alert-circle-outline" | "apps" | "archive" | "arrow-down" | "arrow-up" | "briefcase-outline" | "bug" | "calendar" | "calendar-outline" | "camera" | "camera-outline" | "card" | "card-outline" | "cart-outline" | "chevron-down" | "chevron-up" | "close" | "close-circle" | "cloud-outline" | "cloud-upload" | "cloud-upload-outline" | "cog" | "cog-outline" | "cube-outline" | "download" | "download-outline" | "earth" | "ellipse-outline" | "eye" | "eye-off-outline" | "filter-outline" | "flash" | "folder" | "folder-open-outline" | "folder-outline" | "gift" | "gift-outline" | "grid" | "heart" | "heart-outline" | "help-circle" | "help-circle-outline" | "image-outline" | "information" | "information-outline" | "key" | "leaf" | "library" | "pencil-outline" | "play" | "pulse" | "radio" | "receipt-outline" | "resize" | "rocket" | "scale" | "school-outline" | "server" | "share-outline" | "shield" | "star" | "sync" | "trophy" | "trophy-outline" | "volume-off" | "wallet" | "wallet-outline" | "watch" | "wifi" | "solid" | "account" | "account-circle" | "account-cog-outline" | "account-eye-outline" | "account-group" | "account-multiple" | "account-multiple-outline" | "account-outline" | "account-plus" | "account-search" | "account-switch" | "android" | "archive-arrow-down" | "arrow-left" | "bell" | "bell-outline" | "bio" | "bullhorn" | "cake-variant" | "cake-variant-outline" | "cancel" | "cellphone" | "cellphone-basic" | "cellphone-message" | "cellphone-screenshot" | "chart-line" | "check-all" | "check-circle" | "chip" | "circle-outline" | "clock" | "clock-outline" | "code-tags" | "contain" | "content-copy" | "controller" | "cookie" | "credit-card" | "database-outline" | "delete" | "delete-outline" | "devices" | "dots-horizontal" | "email" | "email-outline" | "file" | "file-document" | "file-document-edit-outline" | "file-document-outline" | "file-excel-outline" | "file-outline" | "file-pdf-box" | "folder-image" | "folder-zip-outline" | "ghost" | "history" | "image-multiple-outline" | "link-variant" | "loading" | "lock-outline" | "logout" | "magnify" | "map-marker" | "map-marker-multiple" | "map-marker-outline" | "message" | "message-outline" | "minus-circle" | "motion" | "music-note-outline" | "network" | "null" | "numeric" | "opacity" | "open-in-app" | "openid" | "palette" | "palette-outline" | "pan" | "phone" | "phone-outline" | "plus" | "plus-circle" | "post" | "presentation" | "react" | "read" | "security" | "shield-account-outline" | "shield-check" | "shield-search" | "signature" | "sort-alphabetical-variant" | "sort-numeric-variant" | "store" | "tag" | "tag-outline" | "text-box-outline" | "theme-light-dark" | "transfer" | "translate" | "trash-can-outline" | "tray-arrow-down" | "update" | "video-outline" | "web" | "wifi-off" | "wrap" | "wrench" | "xml", "OxyServicesMaterialCommunityIcons">;
+declare const MaterialCommunityIcons: import("@expo/vector-icons/build/createIconSet").Icon<"function" | "devices" | "sort" | "at" | "label" | "link" | "ellipse" | "image" | "switch" | "text" | "alert" | "alert-circle" | "alert-circle-outline" | "apps" | "archive" | "arrow-down" | "arrow-up" | "briefcase-outline" | "bug" | "calendar" | "calendar-outline" | "camera" | "camera-outline" | "card" | "card-outline" | "cart-outline" | "chevron-down" | "chevron-up" | "close" | "close-circle" | "cloud-outline" | "cloud-upload" | "cloud-upload-outline" | "cog" | "cog-outline" | "cube-outline" | "download" | "download-outline" | "earth" | "ellipse-outline" | "eye" | "eye-off-outline" | "filter-outline" | "flash" | "folder" | "folder-open-outline" | "folder-outline" | "gift" | "gift-outline" | "grid" | "heart" | "heart-outline" | "help-circle" | "help-circle-outline" | "image-outline" | "information" | "information-outline" | "key" | "leaf" | "library" | "pencil-outline" | "play" | "pulse" | "radio" | "receipt-outline" | "resize" | "rocket" | "scale" | "school-outline" | "server" | "share-outline" | "shield" | "star" | "sync" | "trophy" | "trophy-outline" | "volume-off" | "wallet" | "wallet-outline" | "watch" | "wifi" | "solid" | "opacity" | "wrap" | "account" | "account-circle" | "account-cog-outline" | "account-eye-outline" | "account-group" | "account-multiple" | "account-multiple-outline" | "account-outline" | "account-plus" | "account-search" | "account-switch" | "android" | "archive-arrow-down" | "arrow-left" | "bell" | "bell-outline" | "bio" | "bullhorn" | "cake-variant" | "cake-variant-outline" | "cancel" | "cellphone" | "cellphone-basic" | "cellphone-message" | "cellphone-screenshot" | "chart-line" | "check-all" | "check-circle" | "chip" | "circle-outline" | "clock" | "clock-outline" | "code-tags" | "contain" | "content-copy" | "controller" | "cookie" | "credit-card" | "database-outline" | "delete" | "delete-outline" | "dots-horizontal" | "email" | "email-outline" | "file" | "file-document" | "file-document-edit-outline" | "file-document-outline" | "file-excel-outline" | "file-outline" | "file-pdf-box" | "folder-image" | "folder-zip-outline" | "ghost" | "history" | "image-multiple-outline" | "link-variant" | "loading" | "lock-outline" | "logout" | "magnify" | "map-marker" | "map-marker-multiple" | "map-marker-outline" | "message" | "message-outline" | "minus-circle" | "motion" | "music-note-outline" | "network" | "null" | "numeric" | "open-in-app" | "openid" | "palette" | "palette-outline" | "pan" | "phone" | "phone-outline" | "plus" | "plus-circle" | "post" | "presentation" | "react" | "read" | "security" | "shield-account-outline" | "shield-check" | "shield-search" | "signature" | "sort-alphabetical-variant" | "sort-numeric-variant" | "store" | "tag" | "tag-outline" | "text-box-outline" | "theme-light-dark" | "transfer" | "translate" | "trash-can-outline" | "tray-arrow-down" | "update" | "video-outline" | "web" | "wifi-off" | "wrench" | "xml", "OxyServicesMaterialCommunityIcons">;
 export default MaterialCommunityIcons;
 //# sourceMappingURL=MaterialCommunityIcons.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/services",
-  "version": "8.4.0",
+  "version": "9.1.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -178,7 +178,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^20.19.43",
     "@types/react": "*",
-    "@oxy.so/bloom": "^4.35.0",
+    "@oxy.so/bloom": "^5.1.0",
     "copyfiles": "^2.4.1",
     "expo-clipboard": "~57.0.2",
     "expo-constants": "~57.0.5",
@@ -212,10 +212,10 @@
     "typescript": "^5.9.2",
     "zustand": "^5.0.14"
   },
-  "//@oxy.so/bloom": "RE-RAISE THIS FLOOR ON EVERY BREAKING BLOOM RELEASE, in the same commit as the root package.json catalog entry and the code that requires it. The breaking position is the MAJOR, so `^3.0.1` means `>=3.0.1 <4.0.0`: 3.x minors are admitted on semver's additive promise, and Bloom 4.0.0 is refused until someone raises this deliberately. The CAP is the part that is load-bearing. An earlier revision of this key recorded the opposite trade -- an uncapped `>=` floor, accepted so that intentionally-breaking Bloom 0.x minors would not be blocked -- and that trade is closed by evidence rather than by preference: an unbounded range is exactly what let `bun install` pair this package with Bloom 1.0.0 and emit no warning at all, and 1.0.0 broke it four ways (a deleted provider, a renamed confirm option, a renamed Chip fill, and two REMOVED SUBPATHS that fail at bundle time, before any typecheck runs). A floor is a claim about what was measured; a cap is the claim that nothing beyond it was. RAISED TO 3.0.1 from `^2.1.0`. Bloom 3.0.0 breaks exactly two things -- `PageHeader` defaults to `presentation=\"floating\"` and stops hiding the title under `transparent`, and `Field disabled` now reaches the control that reads the field context -- and THIS PACKAGE IMPORTS NEITHER: it renders no `PageHeader` and no `Field`, and 3.0 removes no subpath (unlike 2.0.0, which is why that floor cost code changes and this one does not). Its six `transparent` occurrences are CSS colour values, not the PageHeader prop. The cap had to move rather than widen to a union, because leaving `^2.1.0` in place is what made `bun install` resolve a SECOND, nested Bloom 2.12.4 under this package for any app on Bloom 3 -- two copies of a library whose 3.0 contracts (`control-surface`, `TopEdgeProvider`, `ScrollOffsetProvider`) are React contexts, so a provider from one copy cannot be read by a consumer from the other. Mention's `oxyRuntimeCompatibility` test is what caught it; nothing in a typecheck can. RAISED AGAIN TO 3.2.0 from `^3.0.1`, for the same class of reason the 2.x note records, only in the other direction: 3.2.0 ADDS the per-glyph icon subpaths (`@oxy.so/bloom/icons/RiAtLine`) that this package's screens now import instead of the `@oxy.so/bloom/icons` barrel, and a missing subpath fails at bundle time, in the consumer's Metro, long after this package has typechecked and shipped. `^3.0.1` would have admitted Bloom 3.0.1 and 3.1.0, neither of which has those subpaths, so the floor is the only thing standing between a consumer and a red build. Nothing else about 3.1.0 or 3.2.0 is required here; the cap stays at the major. RAISED TO ^4.2.0: FollowButton now delegates its visuals to Bloom media-header FollowButton with loading, textStyle and large size; the new shared UI contracts require one Bloom4 context across Services and its consumer. RAISED TO ^4.31.0: the sign-in and account screens type one-time codes into `InputOtp` with `type=\"alphanumeric\"` (the long sign-in code and backup codes), which 4.31.0 adds; older 4.x drops the letters. RAISED TO ^4.35.0: every password field passes `revealable` to `TextFieldInput` (the eye button, 4.35.0); older 4.x drops the prop silently and the password cannot be shown. The provider also mounts `@oxy.so/bloom/locale` (4.32.0+).",
+  "//@oxy.so/bloom": "RE-RAISE THIS FLOOR ON EVERY BREAKING BLOOM RELEASE, in the same commit as the root package.json catalog entry and the code that requires it. The breaking position is the MAJOR, so `^3.0.1` means `>=3.0.1 <4.0.0`: 3.x minors are admitted on semver's additive promise, and Bloom 4.0.0 is refused until someone raises this deliberately. The CAP is the part that is load-bearing. An earlier revision of this key recorded the opposite trade -- an uncapped `>=` floor, accepted so that intentionally-breaking Bloom 0.x minors would not be blocked -- and that trade is closed by evidence rather than by preference: an unbounded range is exactly what let `bun install` pair this package with Bloom 1.0.0 and emit no warning at all, and 1.0.0 broke it four ways (a deleted provider, a renamed confirm option, a renamed Chip fill, and two REMOVED SUBPATHS that fail at bundle time, before any typecheck runs). A floor is a claim about what was measured; a cap is the claim that nothing beyond it was. RAISED TO 3.0.1 from `^2.1.0`. Bloom 3.0.0 breaks exactly two things -- `PageHeader` defaults to `presentation=\"floating\"` and stops hiding the title under `transparent`, and `Field disabled` now reaches the control that reads the field context -- and THIS PACKAGE IMPORTS NEITHER: it renders no `PageHeader` and no `Field`, and 3.0 removes no subpath (unlike 2.0.0, which is why that floor cost code changes and this one does not). Its six `transparent` occurrences are CSS colour values, not the PageHeader prop. The cap had to move rather than widen to a union, because leaving `^2.1.0` in place is what made `bun install` resolve a SECOND, nested Bloom 2.12.4 under this package for any app on Bloom 3 -- two copies of a library whose 3.0 contracts (`control-surface`, `TopEdgeProvider`, `ScrollOffsetProvider`) are React contexts, so a provider from one copy cannot be read by a consumer from the other. Mention's `oxyRuntimeCompatibility` test is what caught it; nothing in a typecheck can. RAISED AGAIN TO 3.2.0 from `^3.0.1`, for the same class of reason the 2.x note records, only in the other direction: 3.2.0 ADDS the per-glyph icon subpaths (`@oxy.so/bloom/icons/RiAtLine`) that this package's screens now import instead of the `@oxy.so/bloom/icons` barrel, and a missing subpath fails at bundle time, in the consumer's Metro, long after this package has typechecked and shipped. `^3.0.1` would have admitted Bloom 3.0.1 and 3.1.0, neither of which has those subpaths, so the floor is the only thing standing between a consumer and a red build. Nothing else about 3.1.0 or 3.2.0 is required here; the cap stays at the major. RAISED TO ^4.2.0: FollowButton now delegates its visuals to Bloom media-header FollowButton with loading, textStyle and large size; the new shared UI contracts require one Bloom4 context across Services and its consumer. RAISED TO ^4.31.0: the sign-in and account screens type one-time codes into `InputOtp` with `type=\"alphanumeric\"` (the long sign-in code and backup codes), which 4.31.0 adds; older 4.x drops the letters. RAISED TO ^4.35.0: every password field passes `revealable` to `TextFieldInput` (the eye button, 4.35.0); older 4.x drops the prop silently and the password cannot be shown. The provider also mounts `@oxy.so/bloom/locale` (4.32.0+). RAISED TO ^5.1.0 (services 9.0.0, a major because consumers must move to Bloom 5 with it): Bloom 5.0.0 types `Card`'s `style` without radius, border width or `overflow` (geometry goes through `radius`/`border`/`clipContent`) and stops clipping a Card's children by default, so `BenefitList`'s `overflow: 'visible'` became both a type error and unnecessary; it is removed. The cap MOVES rather than widening to a `^4 || ^5` union, for the reason the 3.0.1 note records: a union lets an app resolve a second, nested Bloom copy and split the React contexts. The floor is 5.1.0 because that is the version measured here (every package builds and tests against it); 5.0.0 was not measured.",
   "peerDependencies": {
     "@expo/vector-icons": "^15.0.3",
-    "@oxy.so/bloom": "^4.35.0",
+    "@oxy.so/bloom": "^5.1.0",
     "@oxy.so/core": "^3.2.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": ">=11.4.1",

package/src/ui/components/BenefitList.tsx

@@ -103,7 +103,7 @@ export const BenefitList: React.FC<BenefitListProps> = ({
         border="hairline"
         elevation="s"
         className={className}
-        style={[{ padding: SPACING['space-16'], gap: SPACING['space-16'], overflow: 'visible' }, style]}
+        style={[{ padding: SPACING['space-16'], gap: SPACING['space-16'] }, style]}
         accessibilityLabel={accessibilityLabel}
     >
         {children}

package/src/ui/components/OxyProvider.tsx

@@ -105,7 +105,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
     const persistenceUnsubRef = useRef<(() => void) | null>(null);
     const ownsQueryClientRef = useRef(providedQueryClient === undefined);
     // `accountQueries` is read once, at mount, like the client itself.
-    const accountMutationKeysRef = useRef(accountQueries?.mutationKeys);
+    const accountQueriesRef = useRef(accountQueries);
     const [platformStorage, setPlatformStorage] = useState<StorageInterface | null>(null);
 
     // If the consumer supplied their own QueryClient we use it as-is and skip
@@ -139,7 +139,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
             setPlatformStorage(storage);
             const client = queryClientRef.current;
             if (!client || !ownsQueryClientRef.current) return;
-            const persistence = attachQueryPersistence(client, storage, accountMutationKeysRef.current);
+            const persistence = attachQueryPersistence(client, storage, accountQueriesRef.current);
             persistenceUnsubRef.current = persistence.unsubscribe;
             await persistence.restored;
         };

package/src/ui/context/OxyContext.tsx

@@ -300,6 +300,10 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       : null;
   }
   const accountQueryPersistence = accountQueryPersistenceRef.current;
+  useEffect(() => {
+    accountQueryPersistence?.attach();
+    return () => accountQueryPersistence?.detach();
+  }, [accountQueryPersistence]);
   const isAccountCacheReady = useSyncExternalStore(
     accountQueryPersistence ? accountQueryPersistence.subscribe : subscribeNever,
     () => accountQueryPersistence?.isReady() ?? true,

package/src/ui/hooks/accountQueryPersistence.ts

@@ -8,29 +8,43 @@
  *
  * - Storage is keyed by the account (`oxy_account_queries:<accountId>`), so a
  *   restore can only ever hydrate the account that is signed in.
- * - The buster is the build (`getOxyBuildId`), so no cache written by an older
- *   bundle, in an older shape, is ever served.
- * - On a subject change the declared roots, memory-only ones included, and the
- *   account's paused mutations are dropped
- *   from memory synchronously, before anyone is woken, and the new account's
- *   blob is restored. `isReady()` is false until that restore settles, and
+ * - Queries written by another build are dropped on restore; queued (paused)
+ *   mutations are kept (`persistedQueryCache.ts`).
+ * - On a subject change the account's queries, memory-only ones included, and
+ *   its paused mutations are dropped from memory synchronously, before anyone
+ *   is woken. The leaving account's latest state is written first, a sign-out
+ *   then deletes it, and only then is the next account's blob read.
+ * - `isReady()` is false until the signed-in account's blob is restored, and
  *   `RequireOxyAuth` waits on it, so another account's rows never render.
- * - On sign-out the signed-out account's blob is deleted.
+ *
+ * Every storage operation runs through one queue, in order, and a restore
+ * checks that its account is still the active one in the same tick it hydrates.
  */
 
 import { hashKey, type Mutation, type Query, type QueryClient, type QueryKey } from '@tanstack/react-query';
-import { persistQueryClient } from '@tanstack/react-query-persist-client';
-import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
 import type { StorageInterface } from '../utils/storageHelpers';
-import { getOxyBuildId } from '../utils/buildId';
+import {
+  PERSISTED_QUERY_PREFIXES,
+  SDK_MEMORY_ONLY_ROOTS,
+  hydrateSnapshot,
+  rootOf,
+  snapshot,
+  subscribeSnapshots,
+  type PersistFilters,
+} from './persistedQueryCache';
 
 /** An app's declaration of which data is private to the signed-in account. */
 export interface AccountQueriesConfig {
   /**
    * Query-key roots (`queryKey[0]`) whose data belongs to the signed-in account
-   * and survives a restart.
+   * and survives a restart. `'all'`: every query the app runs, for an app whose
+   * every read may depend on who is signed in, so no root can be forgotten.
+   *
+   * The roots `accounts`, `sessions` and `devices` are reserved for the SDK's
+   * device-level data: an app must not use them. `users` and `privacy` are the
+   * SDK's too, and with `'all'` they are dropped on a switch like the app's.
    */
-  roots: readonly string[];
+  roots: readonly string[] | 'all';
   /**
    * Roots that belong to the account too, but must not be written to disk
    * (signed URLs, AI output, search results): dropped on a switch, never persisted.
@@ -43,6 +57,46 @@ export interface AccountQueriesConfig {
   mutationKeys?: readonly QueryKey[];
 }
 
+/** Which queries and mutations an `AccountQueriesConfig` makes the account's. */
+export interface AccountQueryOwnership {
+  /** Dropped from memory on a subject change. */
+  ownsQuery: (query: Query) => boolean;
+  /** Written to the account's blob. */
+  persistsQuery: (query: Query) => boolean;
+  ownsMutation: (mutation: Mutation) => boolean;
+}
+
+/** SDK roots that hold device-level data, the same whoever is signed in. */
+const DEVICE_ROOTS = new Set(['accounts', 'sessions', 'devices']);
+
+export function accountQueryOwnership(config: AccountQueriesConfig): AccountQueryOwnership {
+  const memoryOnly = new Set([...(config.memoryOnlyRoots ?? []), ...SDK_MEMORY_ONLY_ROOTS]);
+  const sdkRoots = new Set(PERSISTED_QUERY_PREFIXES);
+  const declared = config.roots === 'all' ? null : new Set(config.roots);
+  const mutationHashes = new Set((config.mutationKeys ?? []).map((key) => hashKey(key)));
+
+  const ownsQuery = (query: Query): boolean => {
+    const root = rootOf(query);
+    if (root !== null && memoryOnly.has(root)) return true;
+    if (declared === null) return root === null || !DEVICE_ROOTS.has(root);
+    return root !== null && declared.has(root);
+  };
+  return {
+    ownsQuery,
+    persistsQuery: (query) => {
+      if (!ownsQuery(query)) return false;
+      const root = rootOf(query);
+      if (root === null) return true;
+      // The SDK's own roots stay with the SDK persister.
+      return !memoryOnly.has(root) && (declared !== null || !sdkRoots.has(root));
+    },
+    ownsMutation: (mutation) => {
+      const key = mutation.options.mutationKey;
+      return key !== undefined && mutationHashes.has(hashKey(key));
+    },
+  };
+}
+
 export const ACCOUNT_QUERY_CACHE_KEY = 'oxy_account_queries';
 const ACCOUNT_QUERY_CACHE_MAX_AGE = 7 * 24 * 60 * 60 * 1000; // 7 days
 const ACCOUNT_QUERY_PERSIST_THROTTLE_MS = 1_000;
@@ -52,12 +106,13 @@ export interface AccountQueryPersistence {
   setStorage(storage: StorageInterface): void;
   /** The signed-in account changed. `null` is a sign-out. Synchronous in-memory reset. */
   activate(accountId: string | null): void;
+  /** The owning provider mounted: restore and persist the active account. */
+  attach(): void;
+  /** The owning provider unmounted: stop touching the client and storage. */
+  detach(): void;
   /** True once the active account's cache is restored (always true signed out). */
   isReady(): boolean;
   subscribe(listener: () => void): () => void;
-  /** Whether a mutation is account-scoped (so the SDK's own persister skips it). */
-  ownsMutation(mutation: Mutation): boolean;
-  dispose(): void;
 }
 
 function storageKeyFor(accountId: string): string {
@@ -68,36 +123,37 @@ export function createAccountQueryPersistence(
   queryClient: QueryClient,
   config: AccountQueriesConfig,
 ): AccountQueryPersistence {
-  const persistedRoots = new Set(config.roots);
-  const accountRoots = new Set([...config.roots, ...(config.memoryOnlyRoots ?? [])]);
-  const mutationHashes = new Set((config.mutationKeys ?? []).map((key) => hashKey(key)));
+  const { ownsQuery, persistsQuery, ownsMutation } = accountQueryOwnership(config);
+  const filters: PersistFilters = {
+    shouldDehydrateQuery: (query) => query.state.status === 'success' && persistsQuery(query),
+    shouldDehydrateMutation: (mutation) => mutation.state.isPaused && ownsMutation(mutation),
+  };
   const listeners = new Set<() => void>();
 
-  let storage: StorageInterface | null = null;
+  let resolveStorage: (storage: StorageInterface) => void = () => undefined;
+  const storageReady = new Promise<StorageInterface>((resolve) => {
+    resolveStorage = resolve;
+  });
+  let hasStorage = false;
+  // Every read, write and delete runs here, in order, once storage exists.
+  let io: Promise<unknown> = storageReady;
+  const enqueue = (operation: (storage: StorageInterface) => Promise<unknown> | unknown) => {
+    io = io
+      .then(() => storageReady)
+      .then(operation)
+      .catch(() => undefined);
+  };
+
+  let attached = false;
   let accountId: string | null = null;
   let restoredFor: string | null = null;
   let generation = 0;
-  let unsubscribePersist: (() => void) | null = null;
-  // The in-flight restore. A new account waits for it, so a late restore can
-  // never hydrate the previous account's rows after the switch.
-  let restoring: Promise<void> = Promise.resolve();
+  let writer: ReturnType<typeof subscribeSnapshots> | null = null;
 
   const notify = () => {
     for (const listener of listeners) listener();
   };
 
-  const rootOf = (query: Query): string | null => {
-    const head = query.queryKey[0];
-    return typeof head === 'string' ? head : null;
-  };
-  const ownsQuery = (query: Query): boolean => accountRoots.has(rootOf(query) ?? '');
-  const persistsQuery = (query: Query): boolean => persistedRoots.has(rootOf(query) ?? '');
-
-  const ownsMutation = (mutation: Mutation): boolean => {
-    const key = mutation.options.mutationKey;
-    return key !== undefined && mutationHashes.has(hashKey(key));
-  };
-
   const dropScopedData = () => {
     queryClient.removeQueries({ predicate: ownsQuery });
     const mutations = queryClient.getMutationCache();
@@ -106,77 +162,76 @@ export function createAccountQueryPersistence(
     }
   };
 
-  const persisterFor = (id: string, target: StorageInterface) =>
-    createAsyncStoragePersister({
-      storage: {
-        getItem: (key) => target.getItem(key),
-        setItem: (key, value) => target.setItem(key, value),
-        removeItem: (key) => target.removeItem(key),
-      },
-      key: storageKeyFor(id),
-      throttleTime: ACCOUNT_QUERY_PERSIST_THROTTLE_MS,
-    });
+  const stopWriting = () => {
+    writer?.unsubscribe();
+    writer = null;
+  };
 
-  const start = () => {
+  const restore = () => {
     const id = accountId;
-    const target = storage;
-    if (!id || !target || unsubscribePersist) return;
+    if (!attached || id === null) return;
     const current = generation;
-    const [unsubscribe, restored] = persistQueryClient({
-      queryClient,
-      persister: persisterFor(id, target),
-      maxAge: ACCOUNT_QUERY_CACHE_MAX_AGE,
-      buster: getOxyBuildId(),
-      dehydrateOptions: {
-        shouldDehydrateQuery: (query) => query.state.status === 'success' && persistsQuery(query),
-        shouldDehydrateMutation: (mutation) => mutation.state.isPaused && ownsMutation(mutation),
-      },
-    });
-    unsubscribePersist = unsubscribe;
-    restoring = restored.catch(() => undefined).then(() => {
+    const key = storageKeyFor(id);
+    enqueue(async (storage) => {
+      const raw = await storage.getItem(key);
+      // Same tick as the hydrate: a switch in between cannot be missed.
       if (current !== generation) return;
+      if (!hydrateSnapshot(queryClient, raw, ACCOUNT_QUERY_CACHE_MAX_AGE) && raw) {
+        await storage.removeItem(key);
+        if (current !== generation) return;
+      }
       restoredFor = id;
+      writer = subscribeSnapshots(queryClient, filters, ACCOUNT_QUERY_PERSIST_THROTTLE_MS, (serialized) => {
+        if (current !== generation) return;
+        enqueue((target) => target.setItem(key, serialized));
+      });
       notify();
     });
   };
 
-  const stop = () => {
-    unsubscribePersist?.();
-    unsubscribePersist = null;
-  };
-
   return {
     setStorage(next) {
-      if (storage) return;
-      storage = next;
-      const current = generation;
-      void restoring.then(() => {
-        if (current === generation) start();
-      });
+      if (hasStorage) return;
+      hasStorage = true;
+      resolveStorage(next);
     },
 
     activate(next) {
       if (next === accountId) return;
       const previous = accountId;
+      // Keep the leaving account's latest state, but only once its own blob was
+      // restored: before that, the cache holds none of it to write.
+      if (previous !== null && restoredFor === previous) {
+        const serialized = snapshot(queryClient, filters);
+        const key = storageKeyFor(previous);
+        enqueue((storage) => storage.setItem(key, serialized));
+      }
       generation += 1;
-      const current = generation;
-      stop();
+      stopWriting();
       dropScopedData();
       accountId = next;
       restoredFor = null;
+      if (next === null && previous !== null) {
+        const key = storageKeyFor(previous);
+        enqueue((storage) => storage.removeItem(key));
+      }
       notify();
+      restore();
+    },
 
-      if (next === null && previous !== null && storage) {
-        void persisterFor(previous, storage).removeClient();
-      }
+    attach() {
+      if (attached) return;
+      attached = true;
+      restore();
+    },
 
-      void restoring.then(() => {
-        if (current !== generation) return;
-        // A restore that was already in flight may have hydrated the previous
-        // account's rows; drop them again before this account's restore.
-        dropScopedData();
-        start();
-      });
+    detach() {
+      if (!attached) return;
+      attached = false;
+      writer?.flush();
+      generation += 1;
+      stopWriting();
+      restoredFor = null;
     },
 
     isReady() {
@@ -189,13 +244,5 @@ export function createAccountQueryPersistence(
         listeners.delete(listener);
       };
     },
-
-    ownsMutation,
-
-    dispose() {
-      generation += 1;
-      stop();
-      listeners.clear();
-    },
   };
 }

package/src/ui/hooks/persistedQueryCache.ts

@@ -0,0 +1,126 @@
+/**
+ * The storage format and restore rules shared by the SDK's two query caches:
+ * the account-agnostic one (`attachQueryPersistence`) and the per-account one
+ * (`createAccountQueryPersistence`).
+ *
+ * A blob is `{ buster, timestamp, clientState }`, TanStack's persisted-client
+ * shape. Restoring it treats its two halves differently:
+ *
+ * - Queries are served before any refetch, so a query written by another
+ *   build, in whatever shape that build used, is dropped (`getOxyBuildId`).
+ * - Paused mutations are the user's queued actions (a star, a send made
+ *   offline). A deploy must not lose them, so they are restored whatever build
+ *   wrote them; the current build's `setMutationDefaults` replays them.
+ */
+
+import {
+  dehydrate,
+  hydrate,
+  type DehydratedState,
+  type Mutation,
+  type Query,
+  type QueryClient,
+} from '@tanstack/react-query';
+import { getOxyBuildId } from '../utils/buildId';
+
+/** The SDK's own account-agnostic query roots, persisted by `attachQueryPersistence`. */
+export const PERSISTED_QUERY_PREFIXES: ReadonlyArray<string> = [
+  'accounts',
+  'users',
+  'sessions',
+  'devices',
+  'privacy',
+];
+
+/**
+ * SDK queries whose data (or key) carries a signed, expiring URL. Never
+ * written to disk: a restored one would serve an expired URL.
+ */
+export const SDK_MEMORY_ONLY_ROOTS: ReadonlyArray<string> = [
+  'assetDownloadUrls',
+  'avatarCropSource',
+  'avatarCropMeasure',
+  'justifiedPhotoDimensions',
+];
+
+export interface PersistFilters {
+  shouldDehydrateQuery: (query: Query) => boolean;
+  shouldDehydrateMutation: (mutation: Mutation) => boolean;
+}
+
+interface PersistedBlob {
+  buster: string;
+  timestamp: number;
+  clientState: DehydratedState;
+}
+
+export function rootOf(query: Query): string | null {
+  const head = query.queryKey[0];
+  return typeof head === 'string' ? head : null;
+}
+
+/** Serialize what the filters select, stamped with this build. */
+export function snapshot(queryClient: QueryClient, filters: PersistFilters): string {
+  const blob: PersistedBlob = {
+    buster: getOxyBuildId(),
+    timestamp: Date.now(),
+    clientState: dehydrate(queryClient, filters),
+  };
+  return JSON.stringify(blob);
+}
+
+/**
+ * Hydrate a stored blob into the client, synchronously, so a caller can check
+ * it is still wanted immediately before. Returns false when there was nothing
+ * usable (absent, unreadable or expired), in which case the caller removes it.
+ */
+export function hydrateSnapshot(queryClient: QueryClient, raw: string | null, maxAge: number): boolean {
+  if (!raw) return false;
+  let blob: PersistedBlob;
+  try {
+    blob = JSON.parse(raw) as PersistedBlob;
+  } catch {
+    return false;
+  }
+  if (!blob?.clientState || typeof blob.timestamp !== 'number' || Date.now() - blob.timestamp > maxAge) {
+    return false;
+  }
+  const sameBuild = blob.buster === getOxyBuildId();
+  hydrate(queryClient, {
+    queries: sameBuild ? blob.clientState.queries : [],
+    mutations: blob.clientState.mutations ?? [],
+  });
+  return true;
+}
+
+/**
+ * Write the filtered cache on every change, at most once per `throttleMs`.
+ * `write` receives the serialized snapshot; `flush()` writes now.
+ */
+export function subscribeSnapshots(
+  queryClient: QueryClient,
+  filters: PersistFilters,
+  throttleMs: number,
+  write: (serialized: string) => void,
+): { flush: () => void; unsubscribe: () => void } {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const flush = () => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    write(snapshot(queryClient, filters));
+  };
+  const schedule = () => {
+    if (!timer) timer = setTimeout(flush, throttleMs);
+  };
+  const offQueries = queryClient.getQueryCache().subscribe(schedule);
+  const offMutations = queryClient.getMutationCache().subscribe(schedule);
+  return {
+    flush,
+    unsubscribe: () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      offQueries();
+      offMutations();
+    },
+  };
+}