@oxy.so/services 9.0.0 → 9.2.0

package/src/ui/components/FollowTargetButton.tsx

@@ -32,7 +32,7 @@
  */
 
 import { memo, useCallback, useMemo } from 'react';
-import type { FollowApplicationMode, FollowStatus } from '@oxy.so/contracts';
+import type { FollowStatus } from '@oxy.so/contracts';
 import type { StyleProp, ViewStyle } from 'react-native';
 import { View } from 'react-native';
 import { FollowButton as BloomFollowButton } from '@oxy.so/bloom/media-header';
@@ -51,6 +51,13 @@ import {
 import { toast } from '@oxy.so/bloom/toast';
 import { useFollowTarget } from '../hooks/useFollowTarget';
 import { useFollowTargetStore } from '../stores/followTargetStore';
+import {
+  buildFollowMenuItems,
+  FOLLOW_ACTION_LEAVES_ACTIVE,
+  resolveFollowPrimaryAction,
+  type FollowDuration,
+  type FollowMenuItem,
+} from './followRules';
 
 /**
  * The small vocabulary of verbs the ecosystem actually uses. An application
@@ -82,12 +89,6 @@ const VERB_LABELS: Record<FollowVerb, FollowLabels> = {
   watch: { idle: 'Watch', active: 'Watching', pending: 'Requested', disabled: 'Off here' },
 };
 
-/** A timed-follow choice offered in the menu. */
-export interface FollowDuration {
-  label: string;
-  seconds: number;
-}
-
 const HOUR = 60 * 60;
 
 /**
@@ -101,111 +102,6 @@ const DEFAULT_DURATIONS: FollowDuration[] = [
   { label: 'A week', seconds: 7 * 24 * HOUR },
 ];
 
-/**
- * Whether an action leaves the target ACTIVE in this application.
- *
- * One table, read by both the primary button and the menu, because the same
- * action reached from two controls once reported differently — and a rule
- * living in two switch statements is a rule that drifts. `Record` rather than
- * a function with a default, so a new action is a compile error instead of a
- * silent `false`.
- */
-export const FOLLOW_ACTION_LEAVES_ACTIVE: Record<
-  'follow' | 'follow-timed' | 'enable-here' | 'disable-here' | 'unfollow',
-  boolean
-> = {
-  follow: true,
-  'follow-timed': true,
-  // Re-enabling here does not change the global follow — the user already had
-  // it — but it does change whether this application acts on it, which is what
-  // a mirror is asking about.
-  'enable-here': true,
-  'disable-here': false,
-  unfollow: false,
-};
-
-/** One line in the disclosure menu. */
-export interface FollowMenuItem {
-  key: string;
-  label: string;
-  /** What the component should call. Named so the table below stays pure. */
-  action:
-    | { type: 'follow-timed'; seconds: number; durationLabel: string }
-    | { type: 'enable-here' }
-    | { type: 'disable-here' }
-    | { type: 'unfollow' };
-}
-
-/**
- * Which choices exist, given the state.
- *
- * Pure and exported because this is the product decision, not a rendering
- * detail: a timed follow is only offered before following, turning it off here
- * is only offered while following, and NEITHER is offered before the server has
- * answered — every one of them addresses a relationship that does not exist
- * yet, so offering them mid-write would mean sending a guessed id.
- */
-/**
- * What the main button should do for the current state.
- *
- * Exported because the product rule is not obvious from the label alone: a
- * follow switched off here still reads as "following" globally, so the primary
- * press must re-enable here — not unfollow everywhere.
- */
-export function resolveFollowPrimaryAction(input: {
-  isFollowing: boolean;
-  applicationMode: FollowApplicationMode;
-}): 'follow' | 'unfollow' | 'enable-here' {
-  if (!input.isFollowing) return 'follow';
-  if (input.applicationMode === 'disabled') return 'enable-here';
-  return 'unfollow';
-}
-
-export function buildFollowMenuItems(input: {
-  following: boolean;
-  applicationMode: FollowApplicationMode;
-  hasRelationship: boolean;
-  isPending: boolean;
-  durations: FollowDuration[] | false;
-  idleVerb: string;
-  applicationName: string;
-}): FollowMenuItem[] {
-  const items: FollowMenuItem[] = [];
-
-  if (!input.following) {
-    if (input.durations === false) return items;
-    for (const d of input.durations) {
-      items.push({
-        key: `for-${d.seconds}`,
-        label: `${input.idleVerb} for ${d.label.toLowerCase()}`,
-        action: { type: 'follow-timed', seconds: d.seconds, durationLabel: d.label },
-      });
-    }
-    return items;
-  }
-
-  if (!input.hasRelationship || input.isPending) return items;
-
-  items.push(
-    input.applicationMode === 'disabled'
-      ? { key: 'enable-here', label: `Show in ${input.applicationName}`, action: { type: 'enable-here' } }
-      : {
-          key: 'disable-here',
-          label: `Don’t show in ${input.applicationName}`,
-          action: { type: 'disable-here' },
-        }
-  );
-  items.push({
-    // Named for what it does. "Unfollow" beside "don't show here" would read as
-    // the same action twice, and the user would pick the wrong one.
-    key: 'unfollow-everywhere',
-    label: 'Unfollow everywhere',
-    action: { type: 'unfollow' },
-  });
-
-  return items;
-}
-
 export interface FollowTargetButtonProps {
   /** The registered target's id. Registration is separate — see the SDK. */
   targetId: string;

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/components/__tests__/followTargetButton.test.ts

@@ -16,7 +16,7 @@ import {
   buildFollowMenuItems,
   FOLLOW_ACTION_LEAVES_ACTIVE,
   resolveFollowPrimaryAction,
-} from '../FollowTargetButton';
+} from '../followRules';
 import {
   isCompleteFollowStatus,
   followRecordToStatus,

package/src/ui/components/followRules.ts

@@ -0,0 +1,121 @@
+/**
+ * The follow button's product rules, without the button.
+ *
+ * Pure: no React, no Bloom. `FollowTargetButton` renders them, and an
+ * application drawing its own affordance (a chip grid, a compact row) imports
+ * them from here — through `@oxy.so/services/ui/client` — without paying for the
+ * button's dropdown menu.
+ */
+
+import type { FollowApplicationMode } from '@oxy.so/contracts';
+
+/** A timed-follow choice offered in the menu. */
+export interface FollowDuration {
+  label: string;
+  seconds: number;
+}
+
+/**
+ * Whether an action leaves the target ACTIVE in this application.
+ *
+ * One table, read by both the primary button and the menu, because the same
+ * action reached from two controls once reported differently — and a rule
+ * living in two switch statements is a rule that drifts. `Record` rather than
+ * a function with a default, so a new action is a compile error instead of a
+ * silent `false`.
+ */
+export const FOLLOW_ACTION_LEAVES_ACTIVE: Record<
+  'follow' | 'follow-timed' | 'enable-here' | 'disable-here' | 'unfollow',
+  boolean
+> = {
+  follow: true,
+  'follow-timed': true,
+  // Re-enabling here does not change the global follow — the user already had
+  // it — but it does change whether this application acts on it, which is what
+  // a mirror is asking about.
+  'enable-here': true,
+  'disable-here': false,
+  unfollow: false,
+};
+
+/** One line in the disclosure menu. */
+export interface FollowMenuItem {
+  key: string;
+  label: string;
+  /** What the component should call. Named so the table below stays pure. */
+  action:
+    | { type: 'follow-timed'; seconds: number; durationLabel: string }
+    | { type: 'enable-here' }
+    | { type: 'disable-here' }
+    | { type: 'unfollow' };
+}
+
+/**
+ * Which choices exist, given the state.
+ *
+ * Pure and exported because this is the product decision, not a rendering
+ * detail: a timed follow is only offered before following, turning it off here
+ * is only offered while following, and NEITHER is offered before the server has
+ * answered — every one of them addresses a relationship that does not exist
+ * yet, so offering them mid-write would mean sending a guessed id.
+ */
+/**
+ * What the main button should do for the current state.
+ *
+ * Exported because the product rule is not obvious from the label alone: a
+ * follow switched off here still reads as "following" globally, so the primary
+ * press must re-enable here — not unfollow everywhere.
+ */
+export function resolveFollowPrimaryAction(input: {
+  isFollowing: boolean;
+  applicationMode: FollowApplicationMode;
+}): 'follow' | 'unfollow' | 'enable-here' {
+  if (!input.isFollowing) return 'follow';
+  if (input.applicationMode === 'disabled') return 'enable-here';
+  return 'unfollow';
+}
+
+export function buildFollowMenuItems(input: {
+  following: boolean;
+  applicationMode: FollowApplicationMode;
+  hasRelationship: boolean;
+  isPending: boolean;
+  durations: FollowDuration[] | false;
+  idleVerb: string;
+  applicationName: string;
+}): FollowMenuItem[] {
+  const items: FollowMenuItem[] = [];
+
+  if (!input.following) {
+    if (input.durations === false) return items;
+    for (const d of input.durations) {
+      items.push({
+        key: `for-${d.seconds}`,
+        label: `${input.idleVerb} for ${d.label.toLowerCase()}`,
+        action: { type: 'follow-timed', seconds: d.seconds, durationLabel: d.label },
+      });
+    }
+    return items;
+  }
+
+  if (!input.hasRelationship || input.isPending) return items;
+
+  items.push(
+    input.applicationMode === 'disabled'
+      ? { key: 'enable-here', label: `Show in ${input.applicationName}`, action: { type: 'enable-here' } }
+      : {
+          key: 'disable-here',
+          label: `Don’t show in ${input.applicationName}`,
+          action: { type: 'disable-here' },
+        }
+  );
+  items.push({
+    // Named for what it does. "Unfollow" beside "don't show here" would read as
+    // the same action twice, and the user would pick the wrong one.
+    key: 'unfollow-everywhere',
+    label: 'Unfollow everywhere',
+    action: { type: 'unfollow' },
+  });
+
+  return items;
+}

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();
-    },
   };
 }