@oxy.so/services 13.0.0 → 13.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/services",
-  "version": "13.0.0",
+  "version": "13.2.0",
   "description": "OxyHQ Expo/React Native SDK — UI components, screens, and native features",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -140,6 +140,7 @@
     "verify:package": "node scripts/verify-package.mjs",
     "generate:icon-fonts": "node scripts/generate-icon-font-subsets.mjs",
     "check:icon-fonts": "node scripts/check-icon-font-subsets.mjs",
+    "check:compat-expo-54": "bun compat/expo-54/check.mjs",
     "build:js": "bun x react-native-builder-bob build --target commonjs && bun x react-native-builder-bob build --target module && bun run copy-assets",
     "test": "jest --passWithNoTests",
     "test:watch": "jest --watch",
@@ -159,11 +160,10 @@
     "@commitlint/config-conventional": "^21.2.0",
     "@expo/app-integrity": "~58.0.2",
     "@expo/vector-icons": "^15.0.3",
-    "@oxy.so/core": "7.0.0",
+    "@oxy.so/core": "7.1.0",
     "@react-native-async-storage/async-storage": "^2.0.0",
     "@react-native-community/netinfo": "^12.0.1",
     "@react-native/babel-preset": "^0.88.0",
-    "@release-it/conventional-changelog": "^12.0.2",
     "@tanstack/query-async-storage-persister": "^5.101",
     "@tanstack/query-sync-storage-persister": "^5.101",
     "@tanstack/react-query": "^5.101",
@@ -176,26 +176,26 @@
     "@types/react": "*",
     "@oxy.so/bloom": "15.18.0",
     "copyfiles": "^2.4.1",
-    "expo-clipboard": "~58.0.3",
-    "expo-constants": "~58.0.12",
-    "expo-file-system": "~58.0.9",
+    "expo-clipboard": "~58.0.4",
+    "expo-constants": "~58.0.13",
+    "expo-file-system": "~58.0.11",
     "expo-haptics": "~58.0.7",
-    "expo-image": "~58.0.15",
-    "expo-image-manipulator": "~58.0.14",
+    "expo-image": "~58.0.17",
+    "expo-image-manipulator": "~58.0.15",
     "expo-linear-gradient": "~58.0.3",
-    "expo-notifications": "~58.1.5",
-    "expo-modules-core": "~58.0.22",
+    "expo-notifications": "~58.1.6",
+    "expo-modules-core": "~58.0.26",
     "expo-secure-store": "~58.0.2",
     "expo-web-browser": "~58.0.6",
     "husky": "^4.3.8",
     "jest": "^30.5.1",
     "lint-staged": "^15.2.4",
-    "nativewind": "5.0.0-preview.3",
+    "nativewind": "5.0.0-rc.0",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "react-native": "0.88.0",
     "react-native-builder-bob": "^0.43.0",
-    "react-native-css": "^3.0.6",
+    "react-native-css": "3.1.0-rc.0",
     "react-native-gesture-handler": "~3.3.0",
     "react-native-keyboard-controller": "1.22.7",
     "react-native-qrcode-svg": "^6.3.0",
@@ -206,12 +206,13 @@
     "ts-jest": "^29.4.12",
     "typescript": "^5.9.2",
     "zustand": "^5.0.14",
-    "expo-video": "~58.0.11"
+    "expo-video": "~58.0.12"
   },
   "//@oxy.so/bloom": "Bloom 11.1.0 adds the shared grouped sections, usage card, subscription plans, frame appearance and overlay navigation APIs used by this SDK. First-party Bloom peers remain open above this tested minimum.",
   "//@oxy.so/core": "Core 6.16.0 supplies `requireServerVerdict` and `onHolderRejected`, with which the cold boot checks a session it painted from the cache; 6.13.0 supplies the `accounts.settings.*` strings (picture, categories) the account settings speak in every language; 6.12.0 supplies `fileManagement.contentLost` and the `lost` file status a lost file is listed with; 6.11.0 supplies the `follow.errors.*` strings the follow error codes are worded with; 6.4.0 the `follow.*` strings the follow buttons read for every verb and language; 6.1.0 the `oxy.auth.email.{startChange,change,remove}` and `oxy.auth.password.remove` the sign-in & security panels call. Keep one Core instance per app; raise this floor with the root catalogue when new runtime APIs are required.",
+  "//react-native": "React Native 0.81 to 0.88, React 19.1+ and Expo SDK 54 to 58. The floors are the Expo SDK 54 stack (react-native 0.81.6, react 19.1.4, react-native-web 0.21.4, expo 54.0.38 and the module versions its bundledNativeModules.json pins), which compat/expo-54 installs as an external consumer and checks on every CI run (`bun check.mjs`): every peer here admits that stack, services' published src typechecks against its types, and <OxyProvider> mounts and settles its cold boot on iOS (React Native 0.81), web (react-native-web 0.21) and react-native-macos 0.81 with the native modules macOS lacks absent. Astro, Oxy's browser, runs react-native-macos 0.81 (0.83 is its latest release), which is why the floor is not 0.85. The SDK 56 floors these replaced were the versions current when the ranges were first written, not measurements.",
   "peerDependencies": {
-    "@expo/app-integrity": ">=56.0.0 <59.0.0",
+    "@expo/app-integrity": ">=0.1.10 <59.0.0",
     "@expo/vector-icons": "^15.0.3",
     "@oxy.so/bloom": ">=11.1.0",
     "@oxy.so/core": "^7.0.0",
@@ -223,31 +224,31 @@
     "@tanstack/react-query-persist-client": "^5.101",
     "@types/react": "<20.0.0",
     "@types/react-native": "<1.0.0",
-    "expo": ">=56.0.0 <59.0.0",
-    "expo-clipboard": ">=56.0.0 <59.0.0",
-    "expo-constants": ">=56.0.0 <59.0.0",
-    "expo-document-picker": ">=56.0.0 <59.0.0",
-    "expo-file-system": ">=56.0.0 <59.0.0",
-    "expo-haptics": ">=56.0.0 <59.0.0",
+    "expo": ">=54.0.0 <59.0.0",
+    "expo-clipboard": ">=8.0.0 <59.0.0",
+    "expo-constants": ">=18.0.0 <59.0.0",
+    "expo-document-picker": ">=14.0.0 <59.0.0",
+    "expo-file-system": ">=19.0.0 <59.0.0",
+    "expo-haptics": ">=15.0.0 <59.0.0",
     "expo-image": ">=2.0.0 <59.0.0",
-    "expo-image-manipulator": ">=56.0.0 <59.0.0",
-    "expo-image-picker": ">=56.0.0 <59.0.0",
-    "expo-linear-gradient": ">=56.0.0 <59.0.0",
+    "expo-image-manipulator": ">=14.0.0 <59.0.0",
+    "expo-image-picker": ">=17.0.0 <59.0.0",
+    "expo-linear-gradient": ">=15.0.0 <59.0.0",
     "expo-modules-core": "<59.0.0",
-    "expo-notifications": ">=56.0.0 <59.0.0",
-    "expo-web-browser": ">=56.0.0 <59.0.0",
+    "expo-notifications": ">=0.32.0 <59.0.0",
+    "expo-web-browser": ">=15.0.0 <59.0.0",
     "nativewind": ">=5.0.0-preview.3 <6.0.0",
     "react-native-css": "^3.0.6 || 3.1.0-rc.0",
     "react": ">=18.0.0 <20.0.0",
-    "react-native": ">=0.85.0 <0.89.0",
-    "react-native-gesture-handler": ">=2.31.1 <4.0.0",
-    "react-native-keyboard-controller": ">=1.21.0 <2.0.0",
+    "react-native": ">=0.81.0 <0.89.0",
+    "react-native-gesture-handler": ">=2.28.0 <4.0.0",
+    "react-native-keyboard-controller": ">=1.18.5 <2.0.0",
     "react-native-qrcode-svg": "^6.3.0",
-    "react-native-reanimated": ">=4.3.0 <5.0.0",
-    "react-native-safe-area-context": ">=5.7.0 <6.0.0",
-    "react-native-svg": ">=15.15.0 <16.0.0",
+    "react-native-reanimated": ">=4.1.0 <5.0.0",
+    "react-native-safe-area-context": ">=5.6.0 <6.0.0",
+    "react-native-svg": ">=15.12.1 <16.0.0",
     "zustand": "^5.0.0",
-    "expo-video": ">=57.0.0 <59.0.0"
+    "expo-video": ">=3.0.0 <59.0.0"
   },
   "peerDependenciesMeta": {
     "nativewind": {

package/src/index.ts

@@ -323,7 +323,7 @@ export type {
 export { RequireOxyAuth } from './ui/components/RequireOxyAuth';
 export type { RequireOxyAuthProps, RequireOxyAuthPrompt } from './ui/components/RequireOxyAuth';
 // `OxyProvider`'s `accountQueries`: the app's per-account offline cache.
-export type { AccountQueriesConfig } from './ui/hooks/accountQueryPersistence';
+export type { AccountQueriesConfig, AccountQueryMeta } from './ui/hooks/accountQueryPersistence';
 
 export { default as FollowButton } from './ui/components/FollowButton';
 export type {

package/src/ui/components/ExpoImage.macos.tsx

@@ -0,0 +1,59 @@
+/**
+ * react-native-macos fork of `ExpoImage.tsx`. expo-image ships no macOS
+ * podspec, and importing it throws there (`requireNativeModule('ExpoImage')`
+ * runs at import), so on macOS the SDK draws with react-native's `Image`,
+ * which react-native-macos backs with NSImage. Fresco, the reason the other
+ * platforms avoid react-native's `Image`, is Android-only.
+ *
+ * It accepts expo-image's props, so every call site typechecks once against the
+ * default fork, and maps the ones the SDK uses; the rest (transition, cache
+ * policy, placeholders) have no macOS equivalent here and are dropped.
+ */
+import type { ImageContentFit, ImageProps, ImageSource } from 'expo-image';
+import { Image, type ImageResizeMode, type ImageSourcePropType } from 'react-native';
+
+const RESIZE_MODE: Record<ImageContentFit, ImageResizeMode> = {
+  cover: 'cover',
+  contain: 'contain',
+  fill: 'stretch',
+  none: 'center',
+  'scale-down': 'contain',
+};
+
+function toImageSource(source: ImageProps['source']): ImageSourcePropType | undefined {
+  if (source == null) return undefined;
+  if (typeof source === 'number') return source;
+  if (typeof source === 'string') return { uri: source };
+  if (Array.isArray(source)) return source.length > 0 ? toImageSource(source[0]) : undefined;
+  if (typeof source === 'object' && 'uri' in source) {
+    const { uri, headers, width, height } = source as ImageSource;
+    return { uri, headers, width: width ?? undefined, height: height ?? undefined };
+  }
+  return undefined;
+}
+
+export function ExpoImage({
+  source,
+  contentFit = 'cover',
+  onError,
+  style,
+  blurRadius,
+  accessible,
+  accessibilityLabel,
+  testID,
+  className,
+}: ImageProps & { className?: string }) {
+  return (
+    <Image
+      source={toImageSource(source) ?? { uri: '' }}
+      resizeMode={RESIZE_MODE[contentFit]}
+      onError={onError ? () => onError({ error: 'The image could not be loaded' }) : undefined}
+      style={style}
+      blurRadius={blurRadius}
+      accessible={accessible}
+      accessibilityLabel={accessibilityLabel}
+      testID={testID}
+      {...(className ? { className } : null)}
+    />
+  );
+}

package/src/ui/components/ExpoImage.tsx

@@ -0,0 +1,11 @@
+/**
+ * The image every SDK surface draws with: expo-image's `Image` (Glide on
+ * Android, SDWebImage on iOS, an `<img>` on web), never react-native's
+ * (`__tests__/packaging/rnImageBoundary.test.ts`).
+ *
+ * Its one fork, `ExpoImage.macos.tsx`, exists because expo-image has no macOS
+ * implementation: its module calls `requireNativeModule('ExpoImage')` when it
+ * is first imported, so on react-native-macos merely importing this file's
+ * target would throw and take the whole SDK down with it.
+ */
+export { Image as ExpoImage } from 'expo-image';

package/src/ui/components/KeyboardBoundary.macos.tsx

@@ -0,0 +1,8 @@
+import type { FC, ReactNode } from 'react';
+
+/**
+ * react-native-macos fork: react-native-keyboard-controller has no macOS
+ * implementation and throws when imported without its native module, and a
+ * desktop keyboard never covers the window, so there is nothing to track.
+ */
+export const KeyboardBoundary: FC<{ children: ReactNode }> = ({ children }) => <>{children}</>;

package/src/ui/components/fileManagement/FileViewer.tsx

@@ -4,7 +4,7 @@ import { useMemo, useState, useEffect } from 'react';
 import { View, ScrollView, StyleSheet } from 'react-native';
 import { Button } from '@oxy.so/bloom/button';
 import { Text } from '@oxy.so/bloom/typography';
-import { Image as ExpoImage } from 'expo-image';
+import { ExpoImage } from '../ExpoImage';
 import MaterialCommunityIcons from '../../icons/MaterialCommunityIcons';
 import { useTheme } from '@oxy.so/bloom/theme';
 import type { FileMetadata } from '@oxy.so/core';

package/src/ui/components/fileManagement/UploadPreview.tsx

@@ -3,7 +3,7 @@ import { View, ScrollView, StyleSheet } from 'react-native';
 import { Button } from '@oxy.so/bloom/button';
 import { Card } from '@oxy.so/bloom/card';
 import { Text } from '@oxy.so/bloom/typography';
-import { Image as ExpoImage } from 'expo-image';
+import { ExpoImage } from '../ExpoImage';
 import Ionicons from '../../icons/Ionicons';
 import { Dialog, type DialogControlProps } from '@oxy.so/bloom/dialog';
 import { useTheme } from '@oxy.so/bloom/theme';

package/src/ui/context/OxyContext.tsx

@@ -130,8 +130,6 @@ export {
   OxyProviderMissingError,
 } from './oxyRuntimeContext';
 
-const subscribeNever = (): (() => void) => () => undefined;
-
 /**
  * The SDK's internal runtime provider — the session/account state machine that
  * backs `useOxy()`.
@@ -350,24 +348,23 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   // a persistence write is never dropped because it raced storage init.
   const queryClient = useQueryClient();
 
-  // The app's per-account offline cache (`accountQueries`). Built once, like the
-  // runtime. `handleSubjectChange` activates it BEFORE anyone is woken, so a
-  // consumer of the new account never reads the previous account's rows.
-  const accountQueryPersistenceRef = useRef<AccountQueryPersistence | null | undefined>(undefined);
-  if (accountQueryPersistenceRef.current === undefined) {
-    accountQueryPersistenceRef.current = accountQueries
-      ? createAccountQueryPersistence(queryClient, accountQueries)
-      : null;
+  // The account's offline cache: the app's `accountQueries` roots and every
+  // query marked `meta: { persist: 'account' }`. Built once, like the runtime.
+  // `handleSubjectChange` activates it BEFORE anyone is woken, so a consumer of
+  // the new account never reads the previous account's rows.
+  const accountQueryPersistenceRef = useRef<AccountQueryPersistence | null>(null);
+  if (accountQueryPersistenceRef.current === null) {
+    accountQueryPersistenceRef.current = createAccountQueryPersistence(queryClient, accountQueries);
   }
   const accountQueryPersistence = accountQueryPersistenceRef.current;
   useEffect(() => {
-    accountQueryPersistence?.attach();
-    return () => accountQueryPersistence?.detach();
+    accountQueryPersistence.attach();
+    return () => accountQueryPersistence.detach();
   }, [accountQueryPersistence]);
   const isAccountCacheReady = useSyncExternalStore(
-    accountQueryPersistence ? accountQueryPersistence.subscribe : subscribeNever,
-    () => accountQueryPersistence?.isReady() ?? true,
-    () => accountQueryPersistence?.isReady() ?? true,
+    accountQueryPersistence.subscribe,
+    accountQueryPersistence.isReady,
+    accountQueryPersistence.isReady,
   );
 
   const storageRef = useRef<StorageInterface | null>(null);
@@ -409,7 +406,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       .then((storageInstance) => {
         storageRef.current = storageInstance;
         storageReady.resolve(storageInstance);
-        accountQueryPersistence?.setStorage(storageInstance);
+        accountQueryPersistence.setStorage(storageInstance);
         if (mounted) {
           setStorage(storageInstance);
           runtime.setStorageReady(true);
@@ -418,7 +415,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       .catch((err) => {
         // Nothing persisted can be restored; the account cache still has to
         // become ready, or RequireOxyAuth would wait forever.
-        accountQueryPersistence?.setStorage(createMemoryStorage());
+        accountQueryPersistence.setStorage(createMemoryStorage());
         if (mounted) {
           logger('Failed to initialize storage', err);
           onError?.({
@@ -1378,9 +1375,20 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       runtime.setAccount(cached.user);
     });
     onAuthStateChangeRef.current?.(cached.user);
+    // The account's cached queries are part of this paint: one local read,
+    // started by the subject change above, so nothing renders without them.
+    await accountQueryPersistence.whenReady();
     markAuthResolvedRef.current();
     return true;
-  }, [identity, clientIdProp, authStore, oxyServices, runtime, syncDeviceCredentialToHost]);
+  }, [
+    identity,
+    clientIdProp,
+    authStore,
+    oxyServices,
+    runtime,
+    syncDeviceCredentialToHost,
+    accountQueryPersistence,
+  ]);
 
   // A painted session the server could not be asked about yet stays on screen
   // and is asked again: on the lost-token backoff, and at once when the device
@@ -1687,7 +1695,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     ({ previous, next }: SubjectTransition): void => {
       // Every transition, the first sign-in included: the account cache is
       // keyed by the subject, and a sign-out deletes the signed-out one's.
-      accountQueryPersistence?.activate(next);
+      accountQueryPersistence.activate(next);
       if (previous === null) {
         return;
       }

package/src/ui/hooks/accountQueryPersistence.ts

@@ -4,7 +4,9 @@
  * The SDK's own persister (`attachQueryPersistence`) keeps account-agnostic
  * data. An app's mail, library or drafts belong to one account, and every app
  * that wanted them to survive a restart had to scope a persister to the session
- * itself. The SDK owns the session, so it owns this too:
+ * itself. The SDK owns the session, so it owns this too, for every root an app
+ * declares (`accountQueries`) and for any single query marked
+ * `meta: { persist: 'account' }`, with no declaration at all:
  *
  * - Storage is keyed by the account (`oxy_account_queries:<accountId>`), so a
  *   restore can only ever hydrate the account that is signed in.
@@ -15,7 +17,9 @@
  *   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.
+ *   `RequireOxyAuth` waits on it, so another account's rows never render. A
+ *   cold boot that paints a cached session waits on it too (`whenReady()`), so
+ *   the first paint already has the account's rows.
  *
  * 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.
@@ -39,12 +43,29 @@ import {
   type PersistFilters,
 } from './persistedQueryCache';
 
+/**
+ * The `meta` that makes one query the signed-in account's and keeps it across
+ * restarts, exactly like a query under a declared root: for the few reads that
+ * shape a returning user's first paint (the tabs, the theme), not for lists.
+ *
+ * `useQuery({ queryKey, queryFn, meta: { persist: 'account' } })`
+ */
+export interface AccountQueryMeta {
+  persist: 'account';
+}
+
+function isAccountQuery(query: Query): boolean {
+  return (query.meta as Partial<AccountQueryMeta> | undefined)?.persist === 'account';
+}
+
 /** 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. `'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.
+   * Every root's queries are written on every change to any of them: for one
+   * or two queries under a busy root, mark those instead (`AccountQueryMeta`).
    *
    * 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
@@ -75,13 +96,19 @@ export interface AccountQueryOwnership {
 /** 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 {
+/** No declared roots: only the queries marked `AccountQueryMeta` are the account's. */
+const NO_ROOTS: AccountQueriesConfig = { roots: [] };
+
+export function accountQueryOwnership(
+  config: AccountQueriesConfig = NO_ROOTS,
+): 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 => {
+    if (isAccountQuery(query)) return true;
     const root = rootOf(query);
     if (root !== null && memoryOnly.has(root)) return true;
     if (declared === null) return root === null || !DEVICE_ROOTS.has(root);
@@ -94,7 +121,9 @@ export function accountQueryOwnership(config: AccountQueriesConfig): AccountQuer
       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));
+      return (
+        !memoryOnly.has(root) && (isAccountQuery(query) || declared !== null || !sdkRoots.has(root))
+      );
     },
     ownsMutation: (mutation) => {
       const key = mutation.options.mutationKey;
@@ -118,6 +147,8 @@ export interface AccountQueryPersistence {
   detach(): void;
   /** True once the active account's cache is restored (always true signed out). */
   isReady(): boolean;
+  /** Resolves once `isReady()`, or once the account it waited for is left. */
+  whenReady(): Promise<void>;
   subscribe(listener: () => void): () => void;
 }
 
@@ -127,11 +158,11 @@ function storageKeyFor(accountId: string): string {
 
 export function createAccountQueryPersistence(
   queryClient: QueryClient,
-  config: AccountQueriesConfig,
+  config?: AccountQueriesConfig,
 ): AccountQueryPersistence {
   const { ownsQuery, persistsQuery, ownsMutation } = accountQueryOwnership(config);
   const filters: PersistFilters = {
-    shouldDehydrateQuery: (query) => query.state.status === 'success' && persistsQuery(query),
+    persistsQuery,
     shouldDehydrateMutation: (mutation) => mutation.state.isPaused && ownsMutation(mutation),
   };
   const listeners = new Set<() => void>();
@@ -159,6 +190,13 @@ export function createAccountQueryPersistence(
   const notify = () => {
     for (const listener of listeners) listener();
   };
+  const subscribe = (listener: () => void) => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+  const isReady = () => accountId === null || restoredFor === accountId;
 
   const dropScopedData = () => {
     queryClient.removeQueries({ predicate: ownsQuery });
@@ -179,11 +217,12 @@ export function createAccountQueryPersistence(
     const current = generation;
     const key = storageKeyFor(id);
     enqueue(async (storage) => {
-      const raw = await storage.getItem(key);
+      // An unreadable blob restores nothing; it must not leave the account unready.
+      const raw = await storage.getItem(key).catch(() => null);
       // 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);
+        await storage.removeItem(key).catch(() => undefined);
         if (current !== generation) return;
       }
       restoredFor = id;
@@ -245,15 +284,21 @@ export function createAccountQueryPersistence(
       restoredFor = null;
     },
 
-    isReady() {
-      return accountId === null || restoredFor === accountId;
-    },
+    isReady,
 
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
+    whenReady() {
+      const waitingFor = generation;
+      const settled = () => isReady() || generation !== waitingFor;
+      if (settled()) return Promise.resolve();
+      return new Promise((resolve) => {
+        const off = subscribe(() => {
+          if (!settled()) return;
+          off();
+          resolve();
+        });
+      });
     },
+
+    subscribe,
   };
 }

package/src/ui/hooks/persistedQueryCache.ts

@@ -44,7 +44,8 @@ export const SDK_MEMORY_ONLY_ROOTS: ReadonlyArray<string> = [
 ];
 
 export interface PersistFilters {
-  shouldDehydrateQuery: (query: Query) => boolean;
+  /** The queries this cache keeps, whatever their state; only successful ones are written. */
+  persistsQuery: (query: Query) => boolean;
   shouldDehydrateMutation: (mutation: Mutation) => boolean;
 }
 
@@ -64,7 +65,11 @@ export function snapshot(queryClient: QueryClient, filters: PersistFilters): str
   const blob: PersistedBlob = {
     buster: getOxyBuildId(),
     timestamp: Date.now(),
-    clientState: dehydrate(queryClient, filters),
+    clientState: dehydrate(queryClient, {
+      shouldDehydrateQuery: (query) =>
+        query.state.status === 'success' && filters.persistsQuery(query),
+      shouldDehydrateMutation: filters.shouldDehydrateMutation,
+    }),
   };
   return JSON.stringify(blob);
 }
@@ -102,8 +107,9 @@ export function hydrateSnapshot(
 }
 
 /**
- * Write the filtered cache on every change, at most once per `throttleMs`.
- * `write` receives the serialized snapshot; `flush()` writes now.
+ * Write the filtered cache whenever one of its queries or any mutation changes,
+ * at most once per `throttleMs`. Activity in queries it does not keep (feeds,
+ * search) never serializes it. `write` receives the snapshot; `flush()` writes now.
  */
 export function subscribeSnapshots(
   queryClient: QueryClient,
@@ -120,7 +126,9 @@ export function subscribeSnapshots(
   const schedule = () => {
     if (!timer) timer = setTimeout(flush, throttleMs);
   };
-  const offQueries = queryClient.getQueryCache().subscribe(schedule);
+  const offQueries = queryClient.getQueryCache().subscribe((event) => {
+    if (filters.persistsQuery(event.query)) schedule();
+  });
   const offMutations = queryClient.getMutationCache().subscribe(schedule);
   return {
     flush,

package/src/ui/hooks/queryClient.ts

@@ -21,7 +21,7 @@
  *   (`persistedQueryCache.ts`) when introducing reads that should survive restart.
  */
 
-import { QueryClient, onlineManager, type Mutation, type Query } from '@tanstack/react-query';
+import { QueryClient, onlineManager, type Query } from '@tanstack/react-query';
 import type { PersistedClient } from '@tanstack/react-query-persist-client';
 import { isDev } from '@oxy.so/core';
 import type { StorageInterface } from '../utils/storageHelpers';
@@ -30,6 +30,7 @@ import {
   PERSISTED_QUERY_PREFIXES,
   hydrateSnapshot,
   subscribeSnapshots,
+  type PersistFilters,
 } from './persistedQueryCache';
 
 const QUERY_CACHE_KEY = 'oxy_query_cache_v3';
@@ -53,15 +54,8 @@ export function shouldRetryQuery(failureCount: number, error: unknown): boolean
   return status === 408 || status === 425 || status === 429 || status >= 500;
 }
 
-/**
- * Whether a query belongs in the account-agnostic cache: successful (a
- * `pending`/`error` state is not worth keeping, and an error would leak
- * failure objects across restarts) and under one of the SDK's own prefixes.
- */
+/** Whether a query is under one of the SDK's own account-agnostic prefixes. */
 function isSharedQuery(query: Query): boolean {
-  if (query.state.status !== 'success') {
-    return false;
-  }
   const head = query.queryKey[0];
   return typeof head === 'string' && PERSISTED_QUERY_PREFIXES.includes(head);
 }
@@ -135,10 +129,11 @@ export interface AttachPersistenceResult {
  * Restore, then keep writing, the account-agnostic cache.
  *
  * 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.
+ * (`persistedQueryCache.ts`). Whatever belongs to the account (`accountQueries`,
+ * or a query marked `meta: { persist: 'account' }`) 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).
@@ -155,13 +150,12 @@ export const attachQueryPersistence = (
     };
   }
 
-  const account = accountQueries ? accountQueryOwnership(accountQueries) : null;
-  const filters = {
-    shouldDehydrateQuery: (query: Query) =>
-      isSharedQuery(query) && !(account?.ownsQuery(query) ?? false),
+  const account = accountQueryOwnership(accountQueries);
+  const filters: PersistFilters = {
+    persistsQuery: (query) => isSharedQuery(query) && !account.ownsQuery(query),
     // Every other mutation, whatever its status: paused ones are exactly the
     // ones that must survive a restart to replay when online.
-    shouldDehydrateMutation: (mutation: Mutation) => !(account?.ownsMutation(mutation) ?? false),
+    shouldDehydrateMutation: (mutation) => !account.ownsMutation(mutation),
   };
 
   let stopped = false;

package/src/ui/index.ts

@@ -34,7 +34,7 @@ export { LogoText } from './components/logo/LogoText';
 export { RequireOxyAuth } from './components/RequireOxyAuth';
 export type { RequireOxyAuthProps, RequireOxyAuthPrompt } from './components/RequireOxyAuth';
 // `OxyProvider`'s `accountQueries`: the app's per-account offline cache.
-export type { AccountQueriesConfig } from './hooks/accountQueryPersistence';
+export type { AccountQueriesConfig, AccountQueryMeta } from './hooks/accountQueryPersistence';
 export { default as FollowButton } from './components/FollowButton';
 export { default as PeableButton } from './components/PeableButton';
 export type { PeableButtonProps } from './components/PeableButton';

package/src/ui/oauth/nativeAuthTransport.ts

@@ -87,7 +87,11 @@ export async function startNativeOAuthSignIn(
     if (!redirectUrl.startsWith(prefix) || redirectUrl.includes('#'))
       return { status: 'failed', reason: 'native-callback-invalid' };
     const parameters = new URLSearchParams(redirectUrl.slice(prefix.length));
-    if ([...new URL(options.redirectUri).searchParams.keys()].some((key) => parameters.has(key)))
+    if (
+      Array.from(new URL(options.redirectUri).searchParams, ([key]) => key).some((key) =>
+        parameters.has(key),
+      )
+    )
       return { status: 'failed', reason: 'native-callback-invalid' };
     if (
       ['code', 'state', 'error', 'error_description'].some(