@oxy.so/services 8.2.0 → 8.4.0

package/src/ui/components/signIn/accountFlowParts.tsx

@@ -1,7 +1,7 @@
 /**
  * The pieces every Oxy sign-in and account screen shares: the error vocabulary,
  * one labelled field, one one-time-code field, the one primary action, a note,
- * and the email-code step.
+ * a notice, and the email-code step.
  * Each screen is built from the same shell as `OxySignInPanel`
  * (`OxyAuthScreen`), so they read as one product in the account dialog, in an
  * app's settings and on auth.oxy.so.
@@ -10,12 +10,14 @@
 import type React from 'react';
 import { useState } from 'react';
 import { StyleSheet, View } from 'react-native';
+import { Admonition } from '@oxy.so/bloom/admonition';
 import { Button } from '@oxy.so/bloom/button';
 import { Field } from '@oxy.so/bloom/field';
 import { InputOtp } from '@oxy.so/bloom/input-otp';
 import { useTheme } from '@oxy.so/bloom/theme';
 import { TextField, TextFieldHint, TextFieldInput, TextFieldLabel } from '@oxy.so/bloom/text-field';
 import { Text } from '@oxy.so/bloom/typography';
+import { WizardProgress } from '@oxy.so/bloom/wizard';
 import {
   EMAIL_CODE_LENGTH,
   EMAIL_SIGNIN_LONG_CODE_ALPHABET,
@@ -119,7 +121,11 @@ export function isCompleteSignInCode(typed: string): boolean {
 /** Characters in a backup code (`xxxxx-xxxxx`, its dash not counted). */
 export const BACKUP_CODE_LENGTH = 10;
 
-/** One labelled input, the way the sign-in screen draws its fields. */
+/**
+ * One labelled input, the way the sign-in screen draws its fields. A
+ * `secureTextEntry` field is always revealable: Bloom's eye button shows and
+ * hides the password, named in the locale Bloom speaks (`OxyProvider` sets it).
+ */
 export const AccountFlowField: React.FC<{
   label: string;
   value: string;
@@ -161,6 +167,7 @@ export const AccountFlowField: React.FC<{
         autoComplete={autoComplete}
         keyboardType={keyboardType}
         secureTextEntry={secureTextEntry}
+        revealable={secureTextEntry}
         autoCapitalize="none"
         autoCorrect={false}
         autoFocus={autoFocus}
@@ -257,6 +264,44 @@ export const AccountFlowNote: React.FC<{ children: React.ReactNode; testID?: str
   );
 };
 
+/**
+ * Something the person should know before acting, above the action it is
+ * about: a wait before trying again, a code that was just sent, a warning. A
+ * Bloom `Admonition`, not a field's error hint — nothing they typed is wrong.
+ */
+export const AccountFlowNotice: React.FC<{
+  children: React.ReactNode;
+  type?: 'info' | 'warning' | 'error';
+  testID?: string;
+}> = ({ children, type = 'info', testID }) => (
+  <View testID={testID}>
+    <Admonition type={type}>{children}</Admonition>
+  </View>
+);
+
+/**
+ * Where a step sits in a flow of several (sign-up, turning on the
+ * authenticator): Bloom's segmented `WizardProgress` and "Step 2 of 3". The
+ * screen's own header names the step, so the progress draws no title; the
+ * titles still name the bar for assistive technology.
+ */
+export const AccountFlowProgress: React.FC<{ steps: readonly string[]; current: number; testID?: string }> = ({
+  steps,
+  current,
+  testID,
+}) => {
+  const { t } = useI18n();
+  return (
+    <WizardProgress
+      steps={steps.map((title, index) => ({ key: String(index), title }))}
+      current={current}
+      hideTitle
+      formatStepCount={(step, total) => t('common.stepOf', { step, total })}
+      testID={testID}
+    />
+  );
+};
+
 /** Why a step failed, where it happened. */
 export const AccountFlowErrorLine: React.FC<{ message: string }> = ({ message }) => {
   const theme = useTheme();
@@ -277,11 +322,19 @@ export interface EmailCodeStepProps {
   onResend: () => Promise<void>;
   /** "Use another email" / "Back" — the step before. */
   back: { label: string; onPress: () => void };
+  /** Where this step sits in a longer flow (a `WizardProgress`), under the header. */
+  progress?: React.ReactNode;
 }
 
 /** "Check your email": the 6-digit code an email verification sent. Submits itself once complete. */
-export const EmailCodeStep: React.FC<EmailCodeStepProps> = ({ description, verificationId, onConfirmed, onResend, back }) => {
-  const theme = useTheme();
+export const EmailCodeStep: React.FC<EmailCodeStepProps> = ({
+  description,
+  verificationId,
+  onConfirmed,
+  onResend,
+  back,
+  progress,
+}) => {
   const { t } = useI18n();
   const { oxyServices } = useOxy();
   const [code, setCode] = useState('');
@@ -317,6 +370,7 @@ export const EmailCodeStep: React.FC<EmailCodeStepProps> = ({ description, verif
   return (
     <OxyAuthScreen>
       <OxyAuthScreenHeader title={t('emailCode.title')} description={description} />
+      {progress}
       <AccountFlowCodeField
         label={t('emailCode.label')}
         value={code}
@@ -330,10 +384,10 @@ export const EmailCodeStep: React.FC<EmailCodeStepProps> = ({ description, verif
         length={EMAIL_CODE_LENGTH}
         testID="email-code"
       />
-      {notice ? <Text style={[styles.note, { color: theme.colors.textSecondary }]}>{notice}</Text> : null}
+      {notice ? <AccountFlowNotice testID="email-code-notice">{notice}</AccountFlowNotice> : null}
       <AccountFlowAction label={t('signin.actions.continue')} onPress={() => confirm(code)} pending={pending} testID="email-code-continue" />
-      <SubtleLink label={t('emailCode.resend')} theme={theme} onPress={resend} disabled={pending} testID="email-code-resend" />
-      <SubtleLink label={back.label} theme={theme} onPress={back.onPress} disabled={pending} testID="email-code-back" />
+      <SubtleLink label={t('emailCode.resend')} onPress={resend} disabled={pending} testID="email-code-resend" />
+      <SubtleLink label={back.label} onPress={back.onPress} disabled={pending} testID="email-code-back" />
     </OxyAuthScreen>
   );
 };

package/src/ui/context/OxyContext.tsx

@@ -7,6 +7,7 @@ import {
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
 } from 'react';
 import { Linking, Platform } from 'react-native';
 import { OxyServices } from '@oxy.so/core';
@@ -43,7 +44,7 @@ import { useLanguageManagement } from '../hooks/useLanguageManagement';
 import { useSessionManagement } from '../hooks/useSessionManagement';
 import { useAuthOperations, clearPersistedAuthSafe } from './hooks/useAuthOperations';
 import { useDeviceManagement } from '../hooks/useDeviceManagement';
-import { getStorageKeys, createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
+import { getStorageKeys, createMemoryStorage, createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
 import type { RouteName } from '../navigation/routes';
 import { showBottomSheet as globalShowBottomSheet } from '../navigation/bottomSheetManager';
 import {
@@ -54,6 +55,7 @@ import {
 } from '../navigation/surfaces';
 import { useQueryClient, onlineManager } from '@tanstack/react-query';
 import { clearQueryCache } from '../hooks/queryClient';
+import { createAccountQueryPersistence, type AccountQueryPersistence } from '../hooks/accountQueryPersistence';
 import { useAvatarPicker } from '../hooks/useAvatarPicker';
 import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
 import { ASSET_DOWNLOAD_URLS_QUERY_KEY } from '../hooks/useResolvedFileUrls';
@@ -94,6 +96,8 @@ export type { LogoutResult, OxyContextState, OxyRuntimeProviderProps } from './o
 
 const OxyRuntimeContext = createContext<OxyContextState | null>(null);
 
+const subscribeNever = (): (() => void) => () => undefined;
+
 type OxyAuthActionsContextState = Pick<
   OxyContextState,
   | 'signIn'
@@ -135,6 +139,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   webAuthMode = 'popup',
   backgroundSession = false,
   platformStorage,
+  accountQueries,
   onAuthStateChange,
   onError,
 }) => {
@@ -283,6 +288,24 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   // Local display/bookkeeping storage (session id list, language). Distinct
   // from `authStore` (the durable credential blob). Exposed as an awaitable so
   // 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;
+  }
+  const accountQueryPersistence = accountQueryPersistenceRef.current;
+  const isAccountCacheReady = useSyncExternalStore(
+    accountQueryPersistence ? accountQueryPersistence.subscribe : subscribeNever,
+    () => accountQueryPersistence?.isReady() ?? true,
+    () => accountQueryPersistence?.isReady() ?? true,
+  );
+
   const storageRef = useRef<StorageInterface | null>(null);
   const [storage, setStorage] = useState<StorageInterface | null>(null);
   const buildStorageDeferred = () => {
@@ -313,12 +336,16 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       .then((storageInstance) => {
         storageRef.current = storageInstance;
         storageReady.resolve(storageInstance);
+        accountQueryPersistence?.setStorage(storageInstance);
         if (mounted) {
           setStorage(storageInstance);
           runtime.setStorageReady(true);
         }
       })
       .catch((err) => {
+        // Nothing persisted can be restored; the account cache still has to
+        // become ready, or RequireOxyAuth would wait forever.
+        accountQueryPersistence?.setStorage(createMemoryStorage());
         if (mounted) {
           logger('Failed to initialize storage', err);
           onError?.({ message: 'Failed to initialize storage', code: 'STORAGE_INIT_ERROR', status: 500 });
@@ -327,7 +354,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     return () => {
       mounted = false;
     };
-  }, [logger, onError, platformStorage, runtime, storageReady]);
+  }, [accountQueryPersistence, logger, onError, platformStorage, runtime, storageReady]);
 
   const {
     currentLanguage,
@@ -344,8 +371,6 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     logger,
   });
 
-  const queryClient = useQueryClient();
-
   const {
     saveSessionIds,
     switchSession,
@@ -1207,6 +1232,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   // buy a refetch storm at first paint.
   const handleSubjectChange = useCallback(
     ({ 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);
       if (previous === null) {
         return;
       }
@@ -1224,7 +1252,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       queryClient.invalidateQueries();
       void refreshAccounts();
     },
-    [queryClient, refreshAccounts],
+    [accountQueryPersistence, queryClient, refreshAccounts],
   );
   subjectChangeRef.current = handleSubjectChange;
 
@@ -1256,6 +1284,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       isPrivateApiPending,
       isAuthResolved: authResolved,
       isStorageReady: snapshot.storageReady,
+      isAccountCacheReady,
       sessionMode: isIdentityBound ? 'identity' : 'account',
       webAuthMode,
       error,
@@ -1310,6 +1339,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       isPrivateApiPending,
       authResolved,
       snapshot.storageReady,
+      isAccountCacheReady,
       isIdentityBound,
       webAuthMode,
       error,

package/src/ui/context/oxyContextTypes.ts

@@ -12,6 +12,7 @@ import type {
 } from '../oauth/explicitOAuthConsent';
 import type { WebAuthMode, WebOAuthSignInResult } from '../oauth/types';
 import type { StorageInterface } from '../utils/storageHelpers';
+import type { AccountQueriesConfig } from '../hooks/accountQueryPersistence';
 
 /**
  * The outcome of `logout()`. It never rejects: a caller reads this instead.
@@ -48,6 +49,12 @@ export interface OxyContextState {
    */
   isAuthResolved: boolean;
   isStorageReady: boolean;
+  /**
+   * Whether the signed-in account's persisted `accountQueries` cache has been
+   * restored. Always `true` signed out or when the app declared none.
+   * `RequireOxyAuth` waits on it.
+   */
+  isAccountCacheReady: boolean;
   /**
    * Who owns this provider's session (see `OxyProviderProps.sessionMode`).
    *
@@ -200,6 +207,8 @@ export interface OxyRuntimeProviderProps {
   onError?: (error: ApiError) => void;
   /** Storage instance owned by the public provider; internal composition seam. */
   platformStorage?: StorageInterface | null;
+  /** See `OxyProviderProps.accountQueries`. Read once, at mount. */
+  accountQueries?: AccountQueriesConfig;
 }
 
 /** Internal commit input — session plus zero-cookie device credential. */

package/src/ui/hooks/accountQueryPersistence.ts

@@ -0,0 +1,201 @@
+/**
+ * Offline persistence for an app's PRIVATE, per-account queries.
+ *
+ * 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:
+ *
+ * - 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
+ *   `RequireOxyAuth` waits on it, so another account's rows never render.
+ * - On sign-out the signed-out account's blob is deleted.
+ */
+
+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';
+
+/** 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.
+   */
+  roots: readonly string[];
+  /**
+   * 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.
+   */
+  memoryOnlyRoots?: readonly string[];
+  /**
+   * Mutation keys whose PAUSED (offline) instances replay after a restart for
+   * the same account. Register their `mutationFn` with `setMutationDefaults`.
+   */
+  mutationKeys?: readonly QueryKey[];
+}
+
+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;
+
+export interface AccountQueryPersistence {
+  /** Storage became available (it initializes asynchronously). */
+  setStorage(storage: StorageInterface): void;
+  /** The signed-in account changed. `null` is a sign-out. Synchronous in-memory reset. */
+  activate(accountId: string | null): 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 {
+  return `${ACCOUNT_QUERY_CACHE_KEY}:${encodeURIComponent(accountId)}`;
+}
+
+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 listeners = new Set<() => void>();
+
+  let storage: StorageInterface | null = null;
+  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();
+
+  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();
+    for (const mutation of mutations.getAll()) {
+      if (ownsMutation(mutation)) mutations.remove(mutation);
+    }
+  };
+
+  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 start = () => {
+    const id = accountId;
+    const target = storage;
+    if (!id || !target || unsubscribePersist) 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(() => {
+      if (current !== generation) return;
+      restoredFor = id;
+      notify();
+    });
+  };
+
+  const stop = () => {
+    unsubscribePersist?.();
+    unsubscribePersist = null;
+  };
+
+  return {
+    setStorage(next) {
+      if (storage) return;
+      storage = next;
+      const current = generation;
+      void restoring.then(() => {
+        if (current === generation) start();
+      });
+    },
+
+    activate(next) {
+      if (next === accountId) return;
+      const previous = accountId;
+      generation += 1;
+      const current = generation;
+      stop();
+      dropScopedData();
+      accountId = next;
+      restoredFor = null;
+      notify();
+
+      if (next === null && previous !== null && storage) {
+        void persisterFor(previous, storage).removeClient();
+      }
+
+      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();
+      });
+    },
+
+    isReady() {
+      return accountId === null || restoredFor === accountId;
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    ownsMutation,
+
+    dispose() {
+      generation += 1;
+      stop();
+      listeners.clear();
+    },
+  };
+}

package/src/ui/hooks/queryClient.ts

@@ -24,7 +24,7 @@
  *   when introducing reads that should survive restart.
  */
 
-import { QueryClient, onlineManager, type Query, type Mutation } from '@tanstack/react-query';
+import { QueryClient, hashKey, onlineManager, type Query, type Mutation, type QueryKey } from '@tanstack/react-query';
 import {
   persistQueryClient,
   type PersistedClient,
@@ -32,6 +32,7 @@ import {
 import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister';
 import { isDev } from '@oxy.so/core';
 import type { StorageInterface } from '../utils/storageHelpers';
+import { getOxyBuildId } from '../utils/buildId';
 
 const QUERY_CACHE_KEY = 'oxy_query_cache_v3';
 const QUERY_CACHE_MAX_AGE = 30 * 24 * 60 * 60 * 1000; // 30 days
@@ -106,13 +107,6 @@ function shouldDehydrateQuery(query: Query): boolean {
   return PERSISTED_QUERY_PREFIXES.includes(head);
 }
 
-/**
- * Persist every mutation regardless of status — paused mutations are
- * exactly the ones that must survive restart to replay when online.
- */
-function shouldDehydrateMutation(_mutation: Mutation): boolean {
-  return true;
-}
 
 /**
  * Create a QueryClient with offline-first defaults.
@@ -191,6 +185,12 @@ export interface AttachPersistenceResult {
 export 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 => {
   if (!storage) {
     return {
@@ -205,10 +205,19 @@ export const attachQueryPersistence = (
     throttleTime: QUERY_PERSIST_THROTTLE_MS,
   });
 
+  // Persist every other mutation regardless of status: paused mutations are
+  // exactly the ones that must survive restart to replay when online.
+  const accountScoped = new Set(accountMutationKeys.map((key) => hashKey(key)));
+  const shouldDehydrateMutation = (mutation: Mutation): boolean => {
+    const key = mutation.options.mutationKey;
+    return key === undefined || !accountScoped.has(hashKey(key));
+  };
+
   const [unsubscribe, restored] = persistQueryClient({
     queryClient,
     persister,
     maxAge: QUERY_CACHE_MAX_AGE,
+    buster: getOxyBuildId(),
     dehydrateOptions: {
       shouldDehydrateQuery,
       shouldDehydrateMutation,

package/src/ui/index.ts

@@ -24,6 +24,8 @@ export { LogoIcon } from './components/logo/LogoIcon';
 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 { default as FollowButton } from './components/FollowButton';
 export { default as PeableButton } from './components/PeableButton';
 export type { PeableButtonProps } from './components/PeableButton';

package/src/ui/screens/AppInfoScreen.tsx

@@ -4,12 +4,12 @@ import {
     View,
     Platform,
     Dimensions,
-    Clipboard,
     ActivityIndicator,
 } from 'react-native';
 import type { BaseScreenProps } from '../types/navigation';
 import { packageInfo } from '@oxy.so/core';
 import { toast } from '@oxy.so/bloom/toast';
+import { copyText } from '../utils/clipboard';
 import OxyServicesLogo from '../../assets/icons/OxyServices';
 import { SettingsIcon } from '../components/SettingsIcon';
 import { useTheme } from '@oxy.so/bloom/theme';
@@ -93,7 +93,7 @@ const AppInfoScreen: React.FC<BaseScreenProps> = ({
 
     const copyToClipboard = async (text: string, label: string) => {
         try {
-            await Clipboard.setString(text);
+            await copyText(text);
             toast.success(t('appInfo.toasts.copiedToClipboard', { label }));
         } catch (error) {
             toast.error(t('appInfo.toasts.copyFailed'));

package/src/ui/types/navigation.ts

@@ -1,5 +1,6 @@
 import type { ReactNode, RefObject } from 'react';
 import type { QueryClient } from '@tanstack/react-query';
+import type { AccountQueriesConfig } from '../hooks/accountQueryPersistence';
 import type { RouteName } from '../navigation/routes';
 import type { User } from '@oxy.so/core';
 import type { ClientSession } from '@oxy.so/core';
@@ -131,6 +132,14 @@ export interface OxyProviderProps {
      */
     webAuthMode?: WebAuthMode;
     queryClient?: QueryClient;
+    /**
+     * The app's private, per-account data, persisted offline by the SDK: stored
+     * per account, discarded by every new build, dropped from memory on an
+     * account switch and deleted on sign-out. `RequireOxyAuth` waits for the
+     * signed-in account's cache to restore, so another account's rows never
+     * render. Works with the SDK's client or one passed as `queryClient`.
+     */
+    accountQueries?: AccountQueriesConfig;
     /**
      * Convenience: wrap the whole app subtree in `<RequireOxyAuth prompt=...>`.
      * `off` (default) renders children unconditionally; `soft` adds a dismissible

package/src/ui/utils/buildId.ts

@@ -0,0 +1,18 @@
+/**
+ * The identity of the JS bundle that is running, used as the buster for every
+ * persisted query cache the SDK owns.
+ *
+ * A persisted cache is restored and served before any refetch (offline-first),
+ * so data written by an older build reaches components in whatever shape that
+ * build used. Busting on the build means no app ever has to remember to bump a
+ * version when a query's shape changes: a new build simply starts from the
+ * network. Inbox shipped exactly that crash when a hand-kept buster was missed.
+ *
+ * `@oxy.so/app-preset`'s Babel config replaces `process.env.OXY_BUILD_ID` with
+ * the commit at bundle time, node_modules included. An app that does not use
+ * the preset gets a constant, which behaves like a buster that is never bumped.
+ */
+export function getOxyBuildId(): string {
+  const buildId = typeof process === 'undefined' ? undefined : process.env.OXY_BUILD_ID;
+  return buildId || 'unversioned';
+}

package/src/ui/utils/clipboard.native.ts

@@ -0,0 +1,20 @@
+/**
+ * Put text on the clipboard on iOS and Android, through `expo-clipboard`.
+ * React Native's own `Clipboard` is deprecated and gone from newer releases.
+ *
+ * `expo-clipboard` is an OPTIONAL peer, loaded with `import()` so an app
+ * without it (or with the JS but not the native module, before a rebuild)
+ * still bundles and boots: the copy rejects here and the caller says nothing
+ * was copied. A static import would instead fail the Metro build or throw
+ * while the root barrel evaluates.
+ *
+ * Only this NATIVE fork names the package; the default fork (`clipboard.ts`,
+ * which `tsc`, Vite and SSR resolve) names nothing, so a consumer's type graph
+ * reaches `expo-clipboard` only when it typechecks `.native` files
+ * (`moduleSuffixes`) — the case package-rules.md#package-boundaries warns
+ * about. `clipboardIsolation.test.ts` keeps it that way.
+ */
+export async function copyText(text: string): Promise<void> {
+  const clipboard = await import('expo-clipboard');
+  await clipboard.setStringAsync(text);
+}

package/src/ui/utils/clipboard.ts

@@ -0,0 +1,14 @@
+/**
+ * Put text on the clipboard: the browser's asynchronous Clipboard API. Rejects
+ * where there is none (an insecure origin, SSR, a denied permission), so the
+ * caller reports only a copy that happened.
+ *
+ * The native fork (`clipboard.native.ts`) uses `expo-clipboard`. React
+ * Native's own `Clipboard` is deprecated and gone from newer releases, so
+ * neither fork reaches for it.
+ */
+export async function copyText(text: string): Promise<void> {
+  const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard;
+  if (!clipboard?.writeText) throw new Error('clipboard unavailable');
+  await clipboard.writeText(text);
+}