@oxyhq/services 22.1.0 → 22.3.0

package/src/ui/components/OxyAuthChooser.tsx

@@ -61,6 +61,7 @@ import { MaterialCommunityIcons } from '@expo/vector-icons';
 import QRCode from 'react-native-qrcode-svg';
 import { Avatar } from '@oxyhq/bloom/avatar';
 import { Button } from '@oxyhq/bloom/button';
+import { toast } from '@oxyhq/bloom';
 import { Text } from '@oxyhq/bloom/typography';
 import {
   useTheme,
@@ -138,52 +139,61 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({ onComplete }) => {
   const { t } = useI18n();
   const queryClient = useQueryClient();
 
-  // A credential minted for `oxy.so` can only be asserted there (or a loopback
-  // dev host) — this is a hard WebAuthn RP-ID boundary, not feature detection,
-  // so it is the ONLY gate on the passkey affordances. `isOxyRpOrigin()` is
-  // `false` on native by construction (no `location`), so no separate native
-  // check is needed.
-  const passkeyAvailable = useMemo(() => isOxyRpOrigin(), []);
+  // A credential minted for `oxy.so` can only be ASSERTED there (or a loopback
+  // dev host) — a hard WebAuthn RP-ID boundary the browser enforces, not
+  // feature detection. On a first-party Oxy web origin the ceremony runs
+  // directly ('direct'). On any OTHER web origin (b2) it can't run locally, so
+  // the passkey action instead opens a popup at the auth.oxy.so passkey hub —
+  // where the SAME ceremony IS first-party — and relays the resulting session
+  // back via `AccountDialogController.startPasskeyHubSignIn` ('hub'). Native
+  // has neither: Commons owns identity there ('none'). `isOxyRpOrigin()` reads
+  // `location` once and is stable for the component's lifetime.
+  const passkeyMode = useMemo<'direct' | 'hub' | 'none'>(() => {
+    if (!isWebBrowser()) return 'none';
+    return isOxyRpOrigin() ? 'direct' : 'hub';
+  }, []);
+  const passkeyAvailable = passkeyMode !== 'none';
 
   const [signInPasskeyPending, setSignInPasskeyPending] = useState(false);
-  const [signInPasskeyError, setSignInPasskeyError] = useState<string | null>(null);
   const handleSignInWithPasskey = useCallback(async () => {
     if (signInPasskeyPending) return;
     setSignInPasskeyPending(true);
-    setSignInPasskeyError(null);
     try {
       await signInWithPasskey();
       onComplete?.();
     } catch (error) {
       // A cancelled/failed ceremony keeps the view open so the user can retry
-      // or fall back to the QR — surface a concise message, never swallow.
-      setSignInPasskeyError(
-        error instanceof Error && error.message ? error.message : 'Passkey sign-in failed.',
+      // or fall back to the QR — surface the reason as a toast (owner mandate:
+      // errors never render inline inside the dialog), never swallow.
+      toast.error(
+        error instanceof Error && error.message
+          ? error.message
+          : t('accountSwitcher.toasts.passkeySignInFailed') || 'Passkey sign-in failed.',
       );
     } finally {
       setSignInPasskeyPending(false);
     }
-  }, [signInPasskeyPending, signInWithPasskey, onComplete]);
+  }, [signInPasskeyPending, signInWithPasskey, onComplete, t]);
 
   const [createPasskeyPending, setCreatePasskeyPending] = useState(false);
-  const [createPasskeyError, setCreatePasskeyError] = useState<string | null>(null);
   const handleCreateWithPasskey = useCallback(
     async (username: string) => {
       if (createPasskeyPending) return;
       setCreatePasskeyPending(true);
-      setCreatePasskeyError(null);
       try {
         await registerWithPasskey({ username });
         onComplete?.();
       } catch (error) {
-        setCreatePasskeyError(
-          error instanceof Error && error.message ? error.message : 'Account creation failed.',
+        toast.error(
+          error instanceof Error && error.message
+            ? error.message
+            : t('signup.toasts.passkeyCreateFailed') || 'Account creation failed.',
         );
       } finally {
         setCreatePasskeyPending(false);
       }
     },
-    [createPasskeyPending, registerWithPasskey, onComplete],
+    [createPasskeyPending, registerWithPasskey, onComplete, t],
   );
 
   // Bind the headless controller. `getSnapshot` returns a stable reference
@@ -200,6 +210,30 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({ onComplete }) => {
   const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
   const { view } = snapshot;
 
+  // Sign-in device-flow failures land on `snapshot.signIn` asynchronously (poll /
+  // socket / popup cancel). Toast at the controller notification site — never an
+  // inline banner in the QR view (owner mandate, same contract as account-switch).
+  useEffect(() => {
+    if (!controller) return;
+    let lastToastedSignInError: string | null = null;
+    const maybeToastSignInError = () => {
+      const { signIn } = controller.getSnapshot();
+      if (signIn.phase === 'error' && signIn.error && signIn.error !== lastToastedSignInError) {
+        lastToastedSignInError = signIn.error;
+        toast.error(
+          signIn.error ||
+            t('accountSwitcher.toasts.signInFailed') ||
+            'Sign-in failed. Please try again.',
+        );
+      }
+      if (signIn.phase !== 'error') {
+        lastToastedSignInError = null;
+      }
+    };
+    maybeToastSignInError();
+    return controller.subscribe(maybeToastSignInError);
+  }, [controller, t]);
+
   // Web: "Sign in with Oxy" auto-starts the instant the sign-in entry is
   // reached — no button tap needed. `signInWithOxy()` tries the shared
   // keychain first (silently, native-only) then falls to the QR handoff,
@@ -226,20 +260,28 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({ onComplete }) => {
       setSwitching(true);
       try {
         await controller.switchTo(accountId);
-        // A switch succeeds unless the controller recorded an error. On success
-        // reload the app's account graph and drop cached account-scoped data so
-        // the new active identity re-fetches — the same side effects the
-        // context's own `switchToAccount` performs.
-        if (!controller.getSnapshot().error) {
-          void refreshAccounts();
-          queryClient.invalidateQueries();
-          onComplete?.();
+        // `switchTo` never throws — it records a failure on the controller's
+        // snapshot. Read it back at the point the switch settles and surface it
+        // as a toast (event-driven, at the failure site — NOT an inline banner
+        // and NOT a snapshot-reaction). On success reload the app's account
+        // graph and drop cached account-scoped data so the new active identity
+        // re-fetches — the same side effects the context's own
+        // `switchToAccount` performs.
+        if (controller.getSnapshot().error) {
+          toast.error(
+            t('accountSwitcher.toasts.switchFailed') ||
+              'There was a problem switching accounts. Please try again.',
+          );
+          return;
         }
+        void refreshAccounts();
+        queryClient.invalidateQueries();
+        onComplete?.();
       } finally {
         setSwitching(false);
       }
     },
-    [controller, switching, snapshot.activeAccountId, onComplete, refreshAccounts, queryClient],
+    [controller, switching, snapshot.activeAccountId, onComplete, refreshAccounts, queryClient, t],
   );
 
   const handleManage = useCallback(() => {
@@ -274,9 +316,16 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({ onComplete }) => {
         t={t}
         onRetry={() => void controller.showQr()}
         passkeyAvailable={passkeyAvailable}
-        onSignInWithPasskey={() => void handleSignInWithPasskey()}
-        passkeyPending={signInPasskeyPending}
-        passkeyError={signInPasskeyError}
+        onSignInWithPasskey={
+          passkeyMode === 'direct'
+            ? () => void handleSignInWithPasskey()
+            : () => void controller.startPasskeyHubSignIn()
+        }
+        // The hub-popup flow's pending state is `snapshot.signIn` (already
+        // rendered elsewhere in this view) — only the DIRECT ceremony uses this
+        // component-local pending flag. A ceremony FAILURE is surfaced as a
+        // toast by `handleSignInWithPasskey`, never inline.
+        passkeyPending={passkeyMode === 'direct' ? signInPasskeyPending : false}
         onCreateAccount={() => controller.startSignup()}
       />
     );
@@ -289,10 +338,10 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({ onComplete }) => {
         theme={theme}
         t={t}
         oxyServices={oxyServices}
-        passkeyAvailable={passkeyAvailable}
+        passkeyMode={passkeyMode}
         onCreateWithPasskey={handleCreateWithPasskey}
         createPending={createPasskeyPending}
-        createError={createPasskeyError}
+        onOpenHub={() => void controller.startPasskeyHubSignIn()}
         onBackToSignIn={() => controller.setView('signin')}
       />
     );
@@ -315,22 +364,6 @@ const OxyAuthChooser: React.FC<OxyAuthChooserProps> = ({ onComplete }) => {
 // Accounts view
 // ---------------------------------------------------------------------------
 
-/**
- * Inline error banner for `snapshot.error` (the account-list / switch-failure
- * error — distinct from `snapshot.signIn.error`, which `QrView` already
- * renders). `AccountsView` and `SignInView` previously swallowed it: a
- * blocked/failed switch left the user with no feedback outside the QR view.
- */
-const ErrorBanner: React.FC<{ error: string | null; theme: Theme }> = ({ error, theme }) => {
-  if (!error) return null;
-  return (
-    <View style={[styles.errorBanner, { backgroundColor: theme.colors.negativeSubtle }]}>
-      <MaterialCommunityIcons name="alert-circle-outline" size={18} color={theme.colors.error} />
-      <Text style={[styles.errorBannerText, { color: theme.colors.error }]}>{error}</Text>
-    </View>
-  );
-};
-
 interface AccountsViewProps {
   snapshot: AccountDialogSnapshot;
   theme: Theme;
@@ -352,7 +385,6 @@ const AccountsView: React.FC<AccountsViewProps> = ({ snapshot, theme, t, handler
 
   return (
     <View style={styles.rows}>
-      <ErrorBanner error={snapshot.error} theme={theme} />
       {snapshot.accounts.map((account) => (
         <AccountRow
           key={account.accountId}
@@ -474,7 +506,6 @@ const SignInView: React.FC<SignInViewProps> = ({
   onCreateAccount,
 }) => (
   <View style={styles.signInBlock}>
-    <ErrorBanner error={snapshot.error} theme={theme} />
     {snapshot.accounts.length > 0 ? (
       <View style={styles.rows}>
         {snapshot.accounts.map((account) => (
@@ -555,7 +586,6 @@ interface QrViewProps {
   passkeyAvailable: boolean;
   onSignInWithPasskey: () => void;
   passkeyPending: boolean;
-  passkeyError: string | null;
   onCreateAccount: () => void;
 }
 
@@ -567,32 +597,28 @@ const QrView: React.FC<QrViewProps> = ({
   passkeyAvailable,
   onSignInWithPasskey,
   passkeyPending,
-  passkeyError,
   onCreateAccount,
 }) => {
   const { signIn, commonsAvailability } = snapshot;
   const [showQrAnyway, setShowQrAnyway] = useState(false);
 
+  // A ceremony FAILURE is surfaced as a toast by `handleSignInWithPasskey` — the
+  // link itself never renders an inline error (owner mandate).
   const passkeyLink =
     passkeyAvailable && signIn.phase !== 'authorized' ? (
-      <>
-        <Pressable
-          onPress={onSignInWithPasskey}
-          disabled={passkeyPending}
-          accessibilityRole="button"
-          style={styles.footerLink}
-          testID="passkey-signin-link"
-        >
-          <Text style={[styles.linkText, { color: theme.colors.textSecondary }]}>
-            {passkeyPending
-              ? t('accountSwitcher.passkeySigningIn') || 'Signing in…'
-              : t('accountSwitcher.useIdentityOnDevice') || 'No Commons? Use a passkey on this device instead'}
-          </Text>
-        </Pressable>
-        {passkeyError ? (
-          <Text style={[styles.errorText, { color: theme.colors.error }]}>{passkeyError}</Text>
-        ) : null}
-      </>
+      <Pressable
+        onPress={onSignInWithPasskey}
+        disabled={passkeyPending}
+        accessibilityRole="button"
+        style={styles.footerLink}
+        testID="passkey-signin-link"
+      >
+        <Text style={[styles.linkText, { color: theme.colors.textSecondary }]}>
+          {passkeyPending
+            ? t('accountSwitcher.passkeySigningIn') || 'Signing in…'
+            : t('accountSwitcher.useIdentityOnDevice') || 'No Commons? Use a passkey on this device instead'}
+        </Text>
+      </Pressable>
     ) : null;
 
   // Native, Commons confirmed NOT installed: a same-device QR is a dead
@@ -624,11 +650,10 @@ const QrView: React.FC<QrViewProps> = ({
   }
 
   if (signIn.phase === 'error') {
+    // The failure reason is toasted by the controller subscription above — no
+    // inline error copy here (owner mandate).
     return (
       <View style={styles.centeredBlock}>
-        <Text style={[styles.errorText, { color: theme.colors.error }]}>
-          {signIn.error || 'Sign-in failed. Please try again.'}
-        </Text>
         <Button variant="secondary" onPress={onRetry} style={styles.secondaryButton}>
           {t('common.actions.tryAgain') || 'Try again'}
         </Button>
@@ -674,7 +699,10 @@ const QrView: React.FC<QrViewProps> = ({
 type UsernameStatus = 'idle' | 'checking' | 'available' | 'taken';
 
 /** Debounced username-availability check over the existing SDK method. */
-function useUsernameAvailability(oxyServices: OxyServices): {
+function useUsernameAvailability(
+  oxyServices: OxyServices,
+  t: Translate,
+): {
   status: UsernameStatus;
   check: (value: string) => void;
 } {
@@ -700,11 +728,16 @@ function useUsernameAvailability(oxyServices: OxyServices): {
           })
           .catch(() => {
             if (seq !== requestSeqRef.current) return;
-            setStatus('idle'); // network/error — don't block on a stale verdict
+            // Reset the (now stale) verdict rather than block on it, and surface
+            // the failure as a toast — never an inline error inside the dialog.
+            setStatus('idle');
+            toast.error(
+              t('accounts.create.username.checkFailed') || 'Could not check availability',
+            );
           });
       }, 400);
     },
-    [oxyServices],
+    [oxyServices, t],
   );
 
   return { status, check };
@@ -742,10 +775,11 @@ interface SignUpViewProps {
   theme: Theme;
   t: Translate;
   oxyServices: OxyServices;
-  passkeyAvailable: boolean;
+  passkeyMode: 'direct' | 'hub' | 'none';
   onCreateWithPasskey: (username: string) => Promise<void>;
   createPending: boolean;
-  createError: string | null;
+  /** Open the auth.oxy.so hub popup (b2) — the 'hub' mode's only path. */
+  onOpenHub: () => void;
   onBackToSignIn: () => void;
 }
 
@@ -754,14 +788,14 @@ const SignUpView: React.FC<SignUpViewProps> = ({
   theme,
   t,
   oxyServices,
-  passkeyAvailable,
+  passkeyMode,
   onCreateWithPasskey,
   createPending,
-  createError,
+  onOpenHub,
   onBackToSignIn,
 }) => {
   const [username, setUsername] = useState('');
-  const { status: usernameStatus, check: checkUsername } = useUsernameAvailability(oxyServices);
+  const { status: usernameStatus, check: checkUsername } = useUsernameAvailability(oxyServices, t);
   const canSubmit = username.trim().length >= 3 && usernameStatus === 'available' && !createPending;
 
   // Native — Commons owns identity creation. Mirrors the QR view's own
@@ -794,7 +828,7 @@ const SignUpView: React.FC<SignUpViewProps> = ({
   // passkey creation is the de-emphasized alternative underneath for someone
   // who doesn't want to install anything — secondary button, introduced by
   // its own "No Commons?" framing, same subordination as the QR view's link.
-  if (passkeyAvailable) {
+  if (passkeyMode === 'direct') {
     return (
       <View style={styles.signInBlock}>
         <Text style={[styles.qrHeadline, { color: theme.colors.text }]}>
@@ -832,9 +866,6 @@ const SignUpView: React.FC<SignUpViewProps> = ({
           testID="signup-username-input"
         />
         <UsernameStatusText status={usernameStatus} theme={theme} t={t} />
-        {createError ? (
-          <Text style={[styles.errorText, { color: theme.colors.error }]}>{createError}</Text>
-        ) : null}
         <Button
           variant="secondary"
           onPress={() => void onCreateWithPasskey(username.trim())}
@@ -851,15 +882,20 @@ const SignUpView: React.FC<SignUpViewProps> = ({
     );
   }
 
-  // Web, non-Oxy origin: passkey creation here requires the cross-origin hub
-  // relay (b2), which has not shipped yet — an honest message beats a button
-  // that would fail.
+  // Web, non-Oxy origin (b2): passkey creation can't run locally here — the
+  // same WebAuthn RP-ID boundary as sign-in — so this opens the SAME
+  // auth.oxy.so passkey hub popup `QrView`'s "No Commons?" link uses.
+  // Completing EITHER a sign-in OR a fresh sign-up there relays the resulting
+  // session back via the SAME poll/socket engine `showQr` drives.
   return (
     <View style={styles.centeredBlock}>
       <Text style={[styles.mutedText, { color: theme.colors.textSecondary }]}>
-        {t('signup.notAvailableHere') ||
-          "Account creation isn't available in this app yet — create your identity with Commons, or visit oxy.so to sign up with a passkey."}
+        {t('signup.hubExplainer') ||
+          'Create your Oxy ID in a secure window, then come right back.'}
       </Text>
+      <Button variant="primary" onPress={onOpenHub} style={styles.primaryButton}>
+        {t('signup.continueInWindow') || 'Continue in a new window'}
+      </Button>
       <SignInFooterLink theme={theme} t={t} onPress={onBackToSignIn} />
     </View>
   );

package/src/ui/components/oxyAuthChooserStyles.ts

@@ -125,25 +125,6 @@ export const authChooserStyles = StyleSheet.create({
     fontWeight: '700',
     textAlign: 'center',
   },
-  errorText: {
-    fontSize: 14,
-    textAlign: 'center',
-  },
-  errorBanner: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: 8,
-    width: '100%',
-    borderRadius: 12,
-    paddingVertical: 10,
-    paddingHorizontal: 12,
-    marginBottom: 12,
-  },
-  errorBannerText: {
-    flex: 1,
-    fontSize: 13.5,
-    lineHeight: 18,
-  },
   qrPlate: {
     padding: 16,
     borderRadius: 16,

package/src/ui/components/passkeyHubPopup.ts

@@ -0,0 +1,28 @@
+/**
+ * Popup opener for the cross-origin passkey hub (b2).
+ *
+ * On a non-Oxy web origin (e.g. mention.earth) a WebAuthn ceremony can't run
+ * locally — the credential's RP ID is bound to `oxy.so`. Instead,
+ * `AccountDialogController.startPasskeyHubSignIn` opens a popup at the
+ * auth.oxy.so passkey hub, where the SAME ceremony IS a first-party operation.
+ *
+ * Kept in its own module (mirroring `oauthNavigation.ts`'s
+ * `redirectToAuthorize`) so `window.open` sits behind a plain function the
+ * controller wiring in `OxyContext` can inject without touching `window`
+ * itself, and so a test can substitute a fake opener.
+ */
+
+import type { PopupWindowHandle } from '@oxyhq/core';
+
+/**
+ * Open a new, EMPTY popup window. Must be called SYNCHRONOUSLY from within a
+ * user-gesture handler (before any `await`) — opening it after an async call
+ * loses the gesture attribution and the browser silently blocks it. Returns
+ * `null` when blocked, or when there is no DOM `window` (native/SSR — the
+ * hub-popup flow does not apply there).
+ */
+export function openPasskeyHubPopup(): PopupWindowHandle | null {
+    const win = (globalThis as { window?: Window }).window;
+    if (!win) return null;
+    return win.open('', '_blank', 'width=420,height=640');
+}

package/src/ui/context/OxyContext.tsx

@@ -32,6 +32,7 @@ import {
   notifyAccountDialogVisibility,
 } from '../navigation/accountDialogManager';
 import { redirectToAuthorize } from '../components/oauthNavigation';
+import { openPasskeyHubPopup } from '../components/passkeyHubPopup';
 import { isWebBrowser } from '../utils/isWebBrowser';
 import { runProviderColdBoot } from '../boot/runProviderColdBoot';
 import { loadPersistedDeviceCredential } from '../utils/deviceCredential';
@@ -668,6 +669,11 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       // controller short-circuits, so `redirectToAuthorize` never runs for the
       // `oxycommons://` payload.
       canOpenApp: isWebBrowser() ? undefined : (url) => Linking.canOpenURL(url),
+      // Web-only: lets `startPasskeyHubSignIn` open the auth.oxy.so passkey hub
+      // popup (b2) for a non-Oxy origin. `undefined` on native — there is no
+      // popup concept there, and off-origin passkey sign-in isn't reachable
+      // (Commons owns the native flow).
+      openPopup: isWebBrowser() ? openPasskeyHubPopup : undefined,
     });
   }
   const accountDialogController = accountDialogControllerRef.current;

package/src/ui/context/useOxyAccountGraph.ts

@@ -4,6 +4,7 @@ import type { OxyServices, AccountNode, CreateAccountInput, AccountDialogControl
 import { logger as loggerUtil } from '@oxyhq/core';
 import { useAuthStore } from '../stores/authStore';
 import { isUnauthorizedStatus } from './oxyContextHelpers';
+import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
 import type { CommitInput } from './oxyContextTypes';
 
 interface UseOxyAccountGraphParams {
@@ -61,6 +62,7 @@ export function useOxyAccountGraph({
   }, [isAuthenticated, initialized, tokenReady, refreshAccounts, accountDialogControllerRef]);
 
   const runPostAccountSwitchSideEffects = useCallback(async (): Promise<void> => {
+    resetSessionScopedStores();
     await refreshAccounts();
     queryClient.invalidateQueries();
   }, [refreshAccounts, queryClient]);

package/src/ui/hooks/useFollow.ts

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 import { useQuery } from '@tanstack/react-query';
 import { useFollowStore } from '../stores/followStore';
 import { useOxy } from '../context/OxyContext';
@@ -110,7 +110,7 @@ export const useFollow = (userId?: string | string[]) => {
   const fetchStatus = useCallback(async () => {
     if (!isSingleUser || !userId) throw new Error('fetchStatus is only available for single user mode');
     if (!canUsePrivateApi) return;
-    await useFollowStore.getState().fetchFollowStatus(userId, oxyServices);
+    useFollowStore.getState().resolveFollowStatuses([userId], oxyServices);
   }, [isSingleUser, userId, canUsePrivateApi, oxyServices]);
 
   const clearError = useCallback(() => {
@@ -170,13 +170,14 @@ export const useFollow = (userId?: string | string[]) => {
 
   const fetchStatusForUser = useCallback(async (targetUserId: string) => {
     if (!canUsePrivateApi) return;
-    await useFollowStore.getState().fetchFollowStatus(targetUserId, oxyServices);
+    useFollowStore.getState().resolveFollowStatuses([targetUserId], oxyServices);
   }, [canUsePrivateApi, oxyServices]);
 
+  // Resolve EVERY member's status in ONE micro-batched bulk call (never N
+  // single requests). Ids already known/seeded are skipped by the resolver.
   const fetchAllStatuses = useCallback(async () => {
     if (!canUsePrivateApi) return;
-    const store = useFollowStore.getState();
-    await Promise.all(userIds.map(uid => store.fetchFollowStatus(uid, oxyServices)));
+    useFollowStore.getState().resolveFollowStatuses(userIds, oxyServices);
   }, [canUsePrivateApi, userIds, oxyServices]);
 
   // Bulk follow — follows ALL users in ONE network call (never unfollows).
@@ -242,10 +243,32 @@ export const useFollow = (userId?: string | string[]) => {
  * - Only subscribes to the specific user's follow and loading state
  * - Returns only what FollowButton needs (no counts, no multi-user)
  */
-export const useFollowForButton = (userId: string, oxyServices: OxyServices) => {
+export const useFollowForButton = (userId: string, oxyServices: OxyServices, initiallyFollowing?: boolean) => {
+  // Seed the store synchronously on the FIRST render (before paint) when the
+  // caller provided a definite `initiallyFollowing` and the store has no entry
+  // yet. This makes the first paint show the correct label (no post-mount
+  // "Follow → Following" correction) and marks the id KNOWN so the batched
+  // resolver skips it. An OMITTED `initiallyFollowing` leaves the id UNKNOWN,
+  // so the batched resolver fetches its real status. The useState lazy
+  // initializer runs exactly once per mount; `setFollowStatuses` is
+  // seed-only-if-absent, so it never clobbers a live value.
+  useState(() => {
+    if (initiallyFollowing === undefined) return null;
+    const store = useFollowStore.getState();
+    if (!Object.prototype.hasOwnProperty.call(store.followingUsers, userId)) {
+      store.setFollowStatuses({ [userId]: initiallyFollowing });
+    }
+    return null;
+  });
+
   const isFollowing = useFollowStore(
     useCallback((s) => s.followingUsers[userId] ?? false, [userId])
   );
+  // Tri-state: a present key (seeded or fetched) is a DEFINITE status; a missing
+  // key is UNKNOWN. The button renders a neutral/disabled state while unknown.
+  const isKnown = useFollowStore(
+    useCallback((s) => Object.prototype.hasOwnProperty.call(s.followingUsers, userId), [userId])
+  );
   const isLoading = useFollowStore(
     useCallback((s) => s.loadingUsers[userId] ?? false, [userId])
   );
@@ -258,8 +281,12 @@ export const useFollowForButton = (userId: string, oxyServices: OxyServices) =>
     await useFollowStore.getState().toggleFollowUser(userId, oxyServices, currentlyFollowing);
   }, [userId, oxyServices]);
 
-  const fetchStatus = useCallback(async () => {
-    await useFollowStore.getState().fetchFollowStatus(userId, oxyServices);
+  // Enqueue this id into the micro-batched resolver — every button that enqueues
+  // in the same tick coalesces into ONE bulk `getFollowStatuses` call. Known /
+  // seeded / in-flight ids are skipped by the resolver, so this is a no-op for
+  // them.
+  const resolveStatus = useCallback(() => {
+    useFollowStore.getState().resolveFollowStatuses([userId], oxyServices);
   }, [userId, oxyServices]);
 
   const setFollowStatus = useCallback((following: boolean) => {
@@ -272,15 +299,30 @@ export const useFollowForButton = (userId: string, oxyServices: OxyServices) =>
 
   return {
     isFollowing,
+    isKnown,
     isLoading,
     error,
     toggleFollow,
-    fetchStatus,
+    resolveStatus,
     setFollowStatus,
     clearError,
   };
 };
 
+/**
+ * useSeedFollowStatuses — returns a stable callback that bulk-seeds follow
+ * statuses into the store (seed-only-if-absent; never clobbers a live value).
+ *
+ * Wire this at the app root to seed from `oxyServices.getViewerGraph()
+ * .followingIds` (map each followed id → `true`) so a page of `FollowButton`s
+ * paints the correct label on first render with ZERO follow-status network
+ * calls — the batched resolver then skips every seeded id.
+ */
+export const useSeedFollowStatuses = () =>
+  useCallback((statuses: Record<string, boolean>) => {
+    useFollowStore.getState().setFollowStatuses(statuses);
+  }, []);
+
 // Convenience hook for just follower counts
 export const useFollowerCounts = (userId: string) => {
   const { oxyServices } = useOxy();

package/src/ui/hooks/useSessionManagement.ts

@@ -10,6 +10,7 @@ import type { QueryClient } from '@tanstack/react-query';
 import { clearQueryCache } from './queryClient';
 import { isWebBrowser } from '../utils/isWebBrowser';
 import { clearCrossOriginRestoreGuards } from '../utils/crossOriginRestore';
+import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
 
 export interface UseSessionManagementOptions {
   oxyServices: OxyServices;
@@ -169,6 +170,7 @@ export const useSessionManagement = ({
     setSessions([]);
     setActiveSessionId(null);
     logoutStore();
+    resetSessionScopedStores();
 
     // Clear the access token on the client instance. Without this the
     // TokenStore retained the stale bearer until the next 401, leaving the

package/src/ui/index.ts

@@ -32,7 +32,7 @@ export { default as ProfileButton } from './components/ProfileButton';
 // Context + hooks
 export { useOxy } from './context/OxyContext';
 export { useAuth } from './hooks/useAuth';
-export { useFollow } from './hooks/useFollow';
+export { useFollow, useSeedFollowStatuses } from './hooks/useFollow';
 export { useStorage } from './hooks/useStorage';
 export type { UseStorageOptions, UseStorageResult } from './hooks/useStorage';