@oxy.so/services 13.1.0 → 13.3.0

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/hooks/useAccountTheme.ts

@@ -0,0 +1,177 @@
+/**
+ * useAccountTheme / useAccountThemeControls
+ *
+ * The Oxy account carries a portable theme (`user.themePreference`: a mode and
+ * a colour preset) that every Oxy app can wear. The COLOUR is the account
+ * colour and always applies (`useAccountColor`). Whether an app also follows
+ * the account's MODE is the viewer's choice per device: the theme SOURCE.
+ *
+ * - `account` (the default): the account's mode is applied to Bloom, and a mode
+ *   chosen here is written back to the account for the other Oxy apps.
+ * - `app`: the mode stays on this device; nothing is written to the account.
+ *
+ * The source is a local preference, never sent anywhere. On web it is read
+ * synchronously, so the first paint already knows it; on native it resolves
+ * from AsyncStorage right after mount. Bloom's own persistence still paints the
+ * last theme instantly on cold boot, so the account theme lands without a flash
+ * once the session resolves.
+ */
+
+import { useCallback, useEffect } from 'react';
+import { create } from 'zustand';
+import { logger, type User } from '@oxy.so/core';
+import { useBloomTheme, type AppColorName, type ThemeMode } from '@oxy.so/bloom/theme';
+import { createPlatformStorage, isReactNative } from '../utils/storageHelpers';
+import { resolveAccountColor, useAccountColor } from './useAccountColor';
+import { useAuth } from './useAuth';
+import { useUpdateProfile } from './mutations/useAccountMutations';
+
+/** Where the app's theme MODE comes from on this device. */
+export type ThemeSource = 'app' | 'account';
+
+type PortableThemeMode = NonNullable<User['themePreference']>['mode'];
+
+const THEME_SOURCE_KEY = 'oxy.theme.source';
+
+function normalizeSource(stored: string | null | undefined): ThemeSource {
+  return stored === 'app' ? 'app' : 'account';
+}
+
+/**
+ * Bloom's richer mode set onto the portable subset the account stores
+ * (`adaptive` has no cross-app meaning, so it is `system`).
+ */
+function toPortableMode(mode: ThemeMode): PortableThemeMode {
+  return mode === 'light' || mode === 'dark' ? mode : 'system';
+}
+
+/** Web reads `localStorage` synchronously; native resolves in `hydrate`. */
+function readInitialSource(): { source: ThemeSource; hydrated: boolean } {
+  if (isReactNative() || typeof window === 'undefined') {
+    return { source: 'account', hydrated: false };
+  }
+  try {
+    return {
+      source: normalizeSource(window.localStorage?.getItem(THEME_SOURCE_KEY)),
+      hydrated: true,
+    };
+  } catch {
+    // A sandboxed document's storage getter throws: no stored choice.
+    return { source: 'account', hydrated: true };
+  }
+}
+
+interface ThemeSourceState {
+  source: ThemeSource;
+  /** True once the stored source is known (at once on web). */
+  hydrated: boolean;
+  setSource: (source: ThemeSource) => void;
+  hydrate: () => Promise<void>;
+}
+
+const useThemeSourceStore = create<ThemeSourceState>((set, get) => ({
+  ...readInitialSource(),
+  setSource(source) {
+    set({ source, hydrated: true });
+    void createPlatformStorage()
+      .then((storage) => storage.setItem(THEME_SOURCE_KEY, source))
+      .catch(() => undefined);
+  },
+  async hydrate() {
+    if (get().hydrated) return;
+    const stored = await createPlatformStorage()
+      .then((storage) => storage.getItem(THEME_SOURCE_KEY))
+      .catch(() => null);
+    // A choice made while storage was being read wins over the stored one.
+    if (!get().hydrated) set({ source: normalizeSource(stored), hydrated: true });
+  },
+}));
+
+/**
+ * Apply the account theme to Bloom: the colour always (through
+ * `useAccountColor`, which `canUse` can narrow), the mode while this device's
+ * source is `account`. Mount ONCE, inside `OxyProvider` and Bloom's theme
+ * provider.
+ */
+export function useAccountTheme({
+  canUse,
+}: {
+  canUse?: (name: AppColorName) => boolean;
+} = {}): void {
+  const { isAuthenticated, user } = useAuth();
+  const source = useThemeSourceStore((state) => state.source);
+  const hydrated = useThemeSourceStore((state) => state.hydrated);
+  const hydrate = useThemeSourceStore((state) => state.hydrate);
+  const { setMode } = useBloomTheme();
+  useAccountColor({ canUse });
+
+  useEffect(() => {
+    void hydrate();
+  }, [hydrate]);
+
+  const accountMode = user?.themePreference?.mode;
+  useEffect(() => {
+    if (!hydrated || !isAuthenticated || source !== 'account' || !accountMode) return;
+    setMode(accountMode);
+  }, [hydrated, isAuthenticated, source, accountMode, setMode]);
+}
+
+export interface AccountThemeControls {
+  /** The effective source: `app` whenever no session can reach the account. */
+  source: ThemeSource;
+  /** Switch this device's source; enabling `account` seeds an account with no theme yet. */
+  changeThemeSource: (source: ThemeSource) => void;
+  /** Change the mode now; on the `account` source, also write it to the account. */
+  changeThemeMode: (mode: ThemeMode) => Promise<void>;
+}
+
+/**
+ * Source-aware theme mode changes for a settings screen. Bloom changes at once;
+ * on the `account` source the account's portable theme follows. Without a
+ * usable session the effective source is `app`, so changes stay local, and the
+ * stored choice applies again once signed in. The colour is chosen with
+ * `useAccountColorSave`.
+ */
+export function useAccountThemeControls(): AccountThemeControls {
+  const { user, canUsePrivateApi } = useAuth();
+  const { mode, colorPreset, setMode } = useBloomTheme();
+  const { mutateAsync } = useUpdateProfile();
+  const storedSource = useThemeSourceStore((state) => state.source);
+  const setSource = useThemeSourceStore((state) => state.setSource);
+  const source: ThemeSource = canUsePrivateApi ? storedSource : 'app';
+
+  const persist = useCallback(
+    async (next: { mode: ThemeMode; colorPreset: AppColorName }) => {
+      await mutateAsync({
+        themePreference: { mode: toPortableMode(next.mode), colorPreset: next.colorPreset },
+      });
+    },
+    [mutateAsync],
+  );
+
+  const changeThemeMode = useCallback(
+    async (nextMode: ThemeMode) => {
+      setMode(nextMode);
+      if (source === 'account') await persist({ mode: nextMode, colorPreset });
+    },
+    [setMode, source, persist, colorPreset],
+  );
+
+  const accountTheme = user?.themePreference;
+  const hasAccountTheme =
+    !!accountTheme && resolveAccountColor({ themePreference: accountTheme }) !== null;
+  const changeThemeSource = useCallback(
+    (nextSource: ThemeSource) => {
+      setSource(nextSource);
+      // An existing account theme is applied by `useAccountTheme`; only an
+      // account without one is seeded, from what the viewer sees now.
+      if (nextSource !== 'account' || !canUsePrivateApi || hasAccountTheme) return;
+      persist({ mode, colorPreset }).catch((error: unknown) => {
+        logger.error('Failed to seed the account theme', error);
+      });
+    },
+    [setSource, canUsePrivateApi, hasAccountTheme, persist, mode, colorPreset],
+  );
+
+  return { source, changeThemeSource, changeThemeMode };
+}