@oxyhq/services 26.2.0 → 27.1.0

package/src/ui/hooks/useFollowTarget.ts

@@ -0,0 +1,194 @@
+/**
+ * `useFollowTarget` — the one hook every application uses to follow anything.
+ *
+ * Wraps the `/v2/follows` SDK methods with the store above, an optimistic
+ * update, and a rollback. Nothing in here knows what kind of thing it is
+ * following, which is the property that lets an application the SDK has never
+ * heard of use it without a release of this package.
+ *
+ * ## Optimism, and its one limit
+ *
+ * A follow flips the button immediately and rolls back if the server refuses,
+ * because the round trip is long enough to feel like a bug otherwise. But an
+ * optimistic follow has no relationship id until the server answers, and every
+ * other operation addresses the relationship — so those stay disabled for the
+ * width of one request rather than being sent with a guessed id.
+ */
+
+import { useCallback, useEffect } from 'react';
+import type { FollowStatus } from '@oxyhq/contracts';
+import { useOxy } from '../context/OxyContext';
+import {
+  isFollowedGlobally,
+  UNKNOWN_FOLLOW_STATUS,
+  useFollowTargetStore,
+  withApplicationMode,
+} from '../stores/followTargetStore';
+
+export interface UseFollowTargetResult {
+  status: FollowStatus;
+  /**
+   * Whether the user follows this at all — NOT `effectiveState`, which reports
+   * `not_following` for a follow merely switched off in this application.
+   */
+  isFollowing: boolean;
+  /** True until the first read settles. Distinct from "not following". */
+  isUnknown: boolean;
+  isPending: boolean;
+  error: string | undefined;
+  follow: (options?: { expiresIn?: number }) => Promise<void>;
+  unfollow: () => Promise<void>;
+  /** Stop acting on this follow HERE, without giving it up everywhere. */
+  disableHere: () => Promise<void>;
+  enableHere: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+export function useFollowTarget(
+  targetId: string | undefined,
+  options?: { initialStatus?: FollowStatus }
+): UseFollowTargetResult {
+  const { oxyServices, canUsePrivateApi } = useOxy();
+
+  const status = useFollowTargetStore(
+    useCallback((s) => (targetId ? s.statuses[targetId] : undefined), [targetId])
+  );
+  const isPending = useFollowTargetStore(
+    useCallback((s) => (targetId ? (s.pending[targetId] ?? false) : false), [targetId])
+  );
+  const error = useFollowTargetStore(
+    useCallback((s) => (targetId ? s.errors[targetId] : undefined), [targetId])
+  );
+
+  const initialStatus = options?.initialStatus;
+
+  // A caller that already knows the status — a follow list, a feed payload —
+  // seeds it rather than making this hook re-ask once per rendered row.
+  useEffect(() => {
+    if (!targetId || !initialStatus) return;
+    const store = useFollowTargetStore.getState();
+    if (!store.statuses[targetId]) store.setStatus(targetId, initialStatus);
+  }, [targetId, initialStatus]);
+
+  const refresh = useCallback(async () => {
+    // Gated on `canUsePrivateApi`, not on `isAuthenticated`: during the session
+    // cold boot the second is true well before the first, and a read sent in
+    // that window 401s and would leave the button stuck reporting an error the
+    // user cannot act on.
+    if (!targetId || !canUsePrivateApi) return;
+    try {
+      const next = await oxyServices.getFollowTargetStatus(targetId);
+      useFollowTargetStore.getState().setStatus(targetId, next);
+      useFollowTargetStore.getState().setError(targetId, undefined);
+    } catch (e) {
+      useFollowTargetStore
+        .getState()
+        .setError(targetId, e instanceof Error ? e.message : 'Could not read follow status');
+    }
+  }, [targetId, canUsePrivateApi, oxyServices]);
+
+  useEffect(() => {
+    if (!targetId || !canUsePrivateApi) return;
+    if (useFollowTargetStore.getState().statuses[targetId]) return;
+    void refresh();
+  }, [targetId, canUsePrivateApi, refresh]);
+
+  /**
+   * Run a mutation optimistically: show `optimistic` at once, keep the previous
+   * value, and put it back if the server refuses. Every mutation below goes
+   * through this so the rollback cannot be forgotten in one of them.
+   */
+  const mutate = useCallback(
+    async (
+      optimistic: FollowStatus,
+      run: () => Promise<FollowStatus | void>,
+      failureMessage: string
+    ) => {
+      if (!targetId) return;
+      const store = useFollowTargetStore.getState();
+      const previous = store.statuses[targetId];
+      store.setStatus(targetId, optimistic);
+      store.setPending(targetId, true);
+      store.setError(targetId, undefined);
+      try {
+        const settled = await run();
+        if (settled) useFollowTargetStore.getState().setStatus(targetId, settled);
+      } catch (e) {
+        const s = useFollowTargetStore.getState();
+        // Back to what was true, not to a guess. Clearing the entry instead
+        // would make the next render ask again and flash the wrong state.
+        if (previous) s.setStatus(targetId, previous);
+        s.setError(targetId, e instanceof Error ? e.message : failureMessage);
+      } finally {
+        useFollowTargetStore.getState().setPending(targetId, false);
+      }
+    },
+    [targetId]
+  );
+
+  const current = status ?? UNKNOWN_FOLLOW_STATUS;
+
+  const follow = useCallback(
+    async (opts?: { expiresIn?: number }) => {
+      if (!targetId) return;
+      await mutate(
+        {
+          ...withApplicationMode({ ...current, globalState: 'active' }, current.applicationMode),
+          ...(opts?.expiresIn
+            ? { expiresAt: new Date(Date.now() + opts.expiresIn * 1000).toISOString() }
+            : {}),
+        },
+        // The server returns the whole resulting status, so store it rather
+        // than reconstructing one: `effectiveState`'s derivation lives there,
+        // and a client recomputing it is a second implementation of one rule.
+        async () => (await oxyServices.followTarget(targetId, opts)).status,
+        'Could not follow'
+      );
+    },
+    [targetId, current, mutate, oxyServices]
+  );
+
+  const unfollow = useCallback(async () => {
+    const relationshipId = current.relationshipId;
+    if (!targetId || !relationshipId) return;
+    await mutate(
+      { ...UNKNOWN_FOLLOW_STATUS },
+      async () => {
+        await oxyServices.unfollowTarget(relationshipId);
+        return { ...UNKNOWN_FOLLOW_STATUS };
+      },
+      'Could not unfollow'
+    );
+  }, [targetId, current.relationshipId, mutate, oxyServices]);
+
+  const setMode = useCallback(
+    async (mode: 'enabled' | 'disabled') => {
+      const relationshipId = current.relationshipId;
+      if (!targetId || !relationshipId) return;
+      await mutate(
+        withApplicationMode(current, mode),
+        async () => {
+          await oxyServices.setFollowApplicationMode(relationshipId, mode);
+        },
+        'Could not change this app’s setting for this follow'
+      );
+    },
+    [targetId, current, mutate, oxyServices]
+  );
+
+  const disableHere = useCallback(() => setMode('disabled'), [setMode]);
+  const enableHere = useCallback(() => setMode('enabled'), [setMode]);
+
+  return {
+    status: current,
+    isFollowing: isFollowedGlobally(current),
+    isUnknown: status === undefined,
+    isPending,
+    error,
+    follow,
+    unfollow,
+    disableHere,
+    enableHere,
+    refresh,
+  };
+}

package/src/ui/screens/AccountMembersScreen.tsx

@@ -15,6 +15,7 @@ import { Button } from '@oxyhq/bloom/button';
 import { TextField, TextFieldInput } from '@oxyhq/bloom/text-field';
 import { Divider } from '@oxyhq/bloom/divider';
 import type { AccountMember, AccountRole } from '@oxyhq/core';
+import { getNormalizedUserHandle } from '@oxyhq/core';
 import type { BaseScreenProps } from '../types/navigation';
 import { useOxy } from '../context/OxyContext';
 import { useI18n } from '../hooks/useI18n';
@@ -86,10 +87,49 @@ const AccountMembersScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, acco
     enabled: canUsePrivateApi && id.length > 0 && canRead,
   });
   const members = useMemo<AccountMember[]>(() => membersQuery.data ?? [], [membersQuery.data]);
-  const ownerCount = useMemo(() => members.filter((m) => m.role === 'owner').length, [members]);
+  const memberUserIds = useMemo(
+    () => [...new Set(members.map((member) => member.memberUserId).filter((id) => id.length > 0))],
+    [members],
+  );
+  const memberProfilesQuery = useQuery({
+    queryKey: ['users', 'by-ids', memberUserIds],
+    queryFn: () => oxyServices.getUsersByIds(memberUserIds),
+    enabled: canUsePrivateApi && memberUserIds.length > 0,
+  });
+  const memberLabelByUserId = useMemo(() => {
+    const labels = new Map<string, string>();
+    for (const profile of memberProfilesQuery.data ?? []) {
+      // `getNormalizedUserHandle` answers null for an actor with no resolvable
+      // handle. Leaving that entry out is what lets `memberDisplayLabel`'s own
+      // fallback run, rather than storing a null the map is not typed to hold.
+      const handle = getNormalizedUserHandle(profile);
+      if (handle) labels.set(profile.id, handle);
+    }
+    return labels;
+  }, [memberProfilesQuery.data]);
+  const memberDisplayLabel = useCallback(
+    (memberUserId: string): string =>
+      memberLabelByUserId.get(memberUserId) ?? memberUserId,
+    [memberLabelByUserId],
+  );
+  // DIRECT owners only. The list also carries members whose row lives on an
+  // ancestor, and the last-owner rule this count feeds is about the rows on THIS
+  // account — the server's guard counts those. Including an inherited owner
+  // would make a child that has no owner of its own look like it has exactly
+  // one, and silently disable removing anybody.
+  const ownerCount = useMemo(
+    () =>
+      members.filter(
+        (m) => m.role === 'owner' && (m.source ?? 'direct') === 'direct',
+      ).length,
+    [members],
+  );
 
   const invalidateMembers = useCallback(() => {
-    queryClient.invalidateQueries({ queryKey: ['accounts', 'members', id] });
+    // Inherited rows on descendant rosters derive from ancestor membership
+    // tables — mirror the SDK's per-account prefix sweep so every cached member
+    // list refetches, not only the account that was mutated.
+    queryClient.invalidateQueries({ queryKey: ['accounts', 'members'] });
     queryClient.invalidateQueries({ queryKey: ['accounts', 'detail', id] });
   }, [queryClient, id]);
 
@@ -308,16 +348,25 @@ const AccountMembersScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, acco
                   {members.map((member, index) => {
                     const isOwner = member.role === 'owner';
                     const isLastOwner = isOwner && ownerCount <= 1;
-                    const canEditThisRole = canUpdate && !isOwner;
-                    const canRemoveThisMember = canRemove && !isLastOwner && (!isOwner || canTransfer);
-                    const canTransferToThis = canTransfer && !isOwner && member.status === 'active';
+                    // An INHERITED entry's row lives on an ancestor account, and
+                    // every member mutation is scoped to rows on the account in
+                    // the path — so offering to edit, remove or promote one would
+                    // be offering a request the server answers 404. The row is
+                    // changed where it lives, on that ancestor's own member
+                    // screen.
+                    const isEditableHere = (member.source ?? 'direct') === 'direct';
+                    const canEditThisRole = canUpdate && isEditableHere && !isOwner;
+                    const canRemoveThisMember =
+                      canRemove && isEditableHere && !isLastOwner && (!isOwner || canTransfer);
+                    const canTransferToThis =
+                      canTransfer && isEditableHere && !isOwner && member.status === 'active';
                     return (
                       <View key={member._id}>
                         {index > 0 ? <Divider color={colors.border} spacing={0} /> : null}
                         <View className="p-space-16 gap-space-8">
                           <View className="flex-row items-center gap-space-8">
                             <Text className="text-body font-bodyBold text-text flex-1" numberOfLines={1}>
-                              {member.memberUserId}
+                              {memberDisplayLabel(member.memberUserId)}
                             </Text>
                             {isOwner ? (
                               <View className="px-space-8 py-space-4 rounded-radius-full" style={{ backgroundColor: colors.primarySubtle }}>
@@ -326,6 +375,13 @@ const AccountMembersScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, acco
                                 </Text>
                               </View>
                             ) : null}
+                            {!isEditableHere ? (
+                              <View className="px-space-8 py-space-4 rounded-radius-full" style={{ backgroundColor: colors.card }}>
+                                <Text className="text-caption font-caption text-text-secondary">
+                                  {t('accounts.members.inherited') || 'Inherited'}
+                                </Text>
+                              </View>
+                            ) : null}
                             {member.status !== 'active' ? (
                               <View className="px-space-8 py-space-4 rounded-radius-full" style={{ backgroundColor: colors.card }}>
                                 <Text className="text-caption font-caption capitalize text-text-secondary">

package/src/ui/screens/AccountSettingsScreen.tsx

@@ -18,6 +18,10 @@ import { SettingsIcon } from '../components/SettingsIcon';
 import { useOxy } from '../context/OxyContext';
 import { useI18n } from '../hooks/useI18n';
 import { useSurfaceHeader } from '../hooks/useSurfaceHeader';
+import {
+  clearedFieldsFromAccountUpdate,
+  upsertCachedUser,
+} from '../hooks/queries/userCache';
 
 const DISPLAY_NAME_MAX = MAX_DISPLAY_NAME_LENGTH;
 const BIO_MAX = 160;
@@ -78,7 +82,11 @@ const AccountSettingsScreen: React.FC<BaseScreenProps> = ({ onClose, goBack, nav
   const updateMutation = useMutation({
     mutationKey: ['accounts', 'update', id],
     mutationFn: (input: UpdateAccountInput) => oxyServices.updateAccount(id, input),
-    onSuccess: () => {
+    onSuccess: (updatedNode, input) => {
+      const cleared = clearedFieldsFromAccountUpdate(input);
+      upsertCachedUser(queryClient, updatedNode.account, user?.id, {
+        cleared: cleared.length > 0 ? cleared : undefined,
+      });
       queryClient.invalidateQueries({ queryKey: ['accounts', 'detail', id] });
       queryClient.invalidateQueries({ queryKey: ['accounts'] });
       toast.success(t('accounts.settings.toasts.saved') || 'Account updated');

package/src/ui/screens/CreateAccountScreen.tsx

@@ -2,8 +2,8 @@ import type React from 'react';
 import { useState, useCallback, useRef, useEffect } from 'react';
 import { View, ActivityIndicator } from 'react-native';
 import Ionicons from '@expo/vector-icons/Ionicons';
-import type { AccountKind, CreateAccountInput, OrganizationCategory } from '@oxyhq/core';
-import { DISPLAY_NAME_INVALID_MESSAGE, isValidDisplayName, MAX_DISPLAY_NAME_LENGTH, ORGANIZATION_CATEGORIES } from '@oxyhq/core';
+import type { AccountCategoryId, AccountKind, CreateAccountInput } from '@oxyhq/core';
+import { DISPLAY_NAME_INVALID_MESSAGE, isValidDisplayName, MAX_ACCOUNT_CATEGORIES, MAX_DISPLAY_NAME_LENGTH, SELECTABLE_ACCOUNT_CATEGORY_IDS } from '@oxyhq/core';
 import type { BaseScreenProps } from '../types/navigation';
 import { useI18n } from '../hooks/useI18n';
 import { useSurfaceHeader } from '../hooks/useSurfaceHeader';
@@ -83,23 +83,25 @@ const kindDescription = (
   }
 };
 
-const organizationCategoryLabel = (
+/**
+ * The visible label for a category id.
+ *
+ * A lookup, deliberately not a `switch` with a `default`: a `default` would let
+ * an id with no translation render as some OTHER category's label, silently and
+ * only in the languages that are missing it. Falling back to the raw id is ugly
+ * and correct — it is visibly wrong, and it names the missing key.
+ */
+const accountCategoryLabel = (
   t: (key: string, vars?: Record<string, string | number>) => string,
-  category: OrganizationCategory,
-): string => {
-  switch (category) {
-    case 'agency':
-      return t('accounts.organizationCategory.agency');
-    case 'cooperative':
-      return t('accounts.organizationCategory.cooperative');
-    case 'landlord':
-      return t('accounts.organizationCategory.landlord');
-    default:
-      return t('accounts.organizationCategory.other');
-  }
-};
+  category: AccountCategoryId,
+): string => t(`accounts.accountCategory.${category}`) || category;
 
-const ORGANIZATION_CATEGORY_OPTIONS: OrganizationCategory[] = [...ORGANIZATION_CATEGORIES];
+/**
+ * Only the SELECTABLE ids are offered. The full `ACCOUNT_CATEGORY_IDS` still
+ * contains withdrawn ones so that accounts already carrying them keep working —
+ * offering them here would be how an account newly acquires one.
+ */
+const ACCOUNT_CATEGORY_OPTIONS: readonly AccountCategoryId[] = SELECTABLE_ACCOUNT_CATEGORY_IDS;
 
 /**
  * Create a new account in the unified account graph (an organization, project,
@@ -125,7 +127,12 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
   const parentId = typeof parentAccountId === 'string' ? parentAccountId : undefined;
 
   const [kind, setKind] = useState<CreatableAccountKind>('project');
-  const [organizationCategory, setOrganizationCategory] = useState<OrganizationCategory>('agency');
+  /**
+   * ORDER IS THE DATA: index 0 is the primary category. Selecting appends,
+   * de-selecting removes, and neither sorts — so the list the user assembles is
+   * the list that is sent, and the first one they picked stays the primary.
+   */
+  const [accountCategories, setAccountCategories] = useState<AccountCategoryId[]>([]);
   const [username, setUsername] = useState('');
   const [displayName, setDisplayName] = useState('');
   const [displayNameError, setDisplayNameError] = useState('');
@@ -215,6 +222,23 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
     );
   }, [t]);
 
+  /**
+   * Append on select, splice out on de-select. Never sorts — appending is what
+   * makes the FIRST category the user chose the primary one, and a sort would
+   * silently reassign that. De-selecting the primary promotes whatever the user
+   * picked next, which is the only interpretation that does not invent a choice
+   * on their behalf.
+   */
+  const toggleAccountCategory = useCallback((category: AccountCategoryId) => {
+    setAccountCategories((current) => {
+      if (current.includes(category)) {
+        return current.filter((entry) => entry !== category);
+      }
+      if (current.length >= MAX_ACCOUNT_CATEGORIES) return current;
+      return [...current, category];
+    });
+  }, []);
+
   const canCreate = usernameStatus === 'available'
     && displayName.trim().length > 0
     && !displayNameError
@@ -225,17 +249,14 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
 
     setIsCreating(true);
     try {
-      // Split display name into first/last
-      const nameParts = displayName.trim().split(/\s+/);
-      const firstName = nameParts[0] || '';
-      const lastName = nameParts.length > 1 ? nameParts.slice(1).join(' ') : undefined;
-
       const input: CreateAccountInput = {
         kind,
         username,
-        name: { first: firstName, last: lastName },
+        name: { displayName: displayName.trim() },
         bio: bio.trim() || undefined,
-        ...(kind === 'organization' ? { organizationCategory } : null),
+        // Sent in the user's own order, or omitted entirely when empty — the
+        // API distinguishes "no categories" from "not stated" only by absence.
+        ...(accountCategories.length > 0 ? { accountCategories } : null),
         ...(parentId ? { parentAccountId: parentId } : null),
       };
       const account = await createAccount(input);
@@ -265,7 +286,7 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
     } finally {
       setIsCreating(false);
     }
-  }, [canCreate, kind, organizationCategory, username, displayName, bio, parentId, createAccount, switchToAccount, onClose, t]);
+  }, [canCreate, kind, accountCategories, username, displayName, bio, parentId, createAccount, switchToAccount, onClose, t]);
 
   // Status icon + color shown alongside the username field message
   const usernameIsInvalid = usernameStatus === 'taken' || usernameStatus === 'invalid';
@@ -307,26 +328,35 @@ const CreateAccountScreen: React.FC<BaseScreenProps> = ({
         })}
       </SettingsListGroup>
 
-      {/* Organization category — grouped selection rows, shown only for organizations */}
-      {kind === 'organization' ? (
-        <SettingsListGroup title={t('accounts.create.organizationCategory.label')}>
-          {ORGANIZATION_CATEGORY_OPTIONS.map((option) => {
-            const selected = option === organizationCategory;
+      {/* Categories — multi-select, shown for every kind this screen can create
+          (they are all non-personal). The badge on a selected row is its
+          POSITION, so the primary is legible as "1" rather than being a rule the
+          user has to be told. */}
+      <View className="gap-space-4">
+        <SettingsListGroup title={t('accounts.create.accountCategory.label')}>
+          {ACCOUNT_CATEGORY_OPTIONS.map((option) => {
+            const position = accountCategories.indexOf(option);
+            const selected = position >= 0;
+            const label = accountCategoryLabel(t, option);
             return (
               <SettingsListItem
                 key={option}
-                title={organizationCategoryLabel(t, option)}
-                onPress={() => setOrganizationCategory(option)}
+                title={label}
+                disabled={!selected && accountCategories.length >= MAX_ACCOUNT_CATEGORIES}
+                onPress={() => toggleAccountCategory(option)}
                 showChevron={false}
                 rightElement={selected ? (
-                  <Ionicons name="checkmark-circle" size={20} color={bloomTheme.colors.primary} />
+                  <Text className="text-caption-1 font-semibold text-primary">{position + 1}</Text>
                 ) : undefined}
-                accessibilityLabel={organizationCategoryLabel(t, option)}
+                accessibilityLabel={label}
               />
             );
           })}
         </SettingsListGroup>
-      ) : null}
+        <Text className="text-caption font-caption text-text-tertiary px-space-4">
+          {t('accounts.create.accountCategory.hint', { max: MAX_ACCOUNT_CATEGORIES })}
+        </Text>
+      </View>
 
       {/* Details — a grouped section card hosting the form fields */}
       <SettingsListGroup title={t('accounts.create.detailsSection') || 'Details'}>

package/src/ui/stores/__tests__/resetSessionScopedStores.test.ts

@@ -0,0 +1,23 @@
+import { useFollowStore } from '../followStore';
+import { UNKNOWN_FOLLOW_STATUS, useFollowTargetStore } from '../followTargetStore';
+import { resetSessionScopedStores } from '../resetSessionScopedStores';
+
+describe('resetSessionScopedStores', () => {
+  beforeEach(() => {
+    useFollowStore.getState().resetFollowState();
+    useFollowTargetStore.getState().reset();
+  });
+
+  it('clears legacy follow state and the v2 follow-target cache', () => {
+    useFollowStore.getState().setFollowingStatus('user-1', true);
+    useFollowTargetStore.getState().setStatus('target-1', {
+      ...UNKNOWN_FOLLOW_STATUS,
+      effectiveState: 'following',
+    });
+
+    resetSessionScopedStores();
+
+    expect(useFollowStore.getState().followingUsers['user-1']).toBeUndefined();
+    expect(useFollowTargetStore.getState().statuses['target-1']).toBeUndefined();
+  });
+});

package/src/ui/stores/followTargetStore.ts

@@ -0,0 +1,119 @@
+/**
+ * The follow-graph store — the client's single cache authority for #809.
+ *
+ * The SDK caches none of these reads on purpose (a status cached across a write
+ * is the "follow reverts after navigating away and back" bug), which makes this
+ * store the one place a status lives between a write and the next read. If a
+ * second cache appears above it, the two will disagree the moment one is
+ * invalidated and the other is not.
+ *
+ * ## Keyed by target id, not by user id
+ *
+ * The legacy `followStore` is keyed by user id because the only followable
+ * thing was a user. Here a key is a target of any kind — a topic, a store, an
+ * artist, a channel — so nothing in this file may assume what it is looking at.
+ * That is the property that lets an application the SDK has never heard of use
+ * it without a release.
+ *
+ * ## Why the status is stored whole
+ *
+ * Not a boolean. `globalState`, `applicationMode` and `effectiveState` are
+ * three separate answers, and a UI that keeps only the last one cannot explain
+ * why a follow the user can see in their list does nothing in this app.
+ */
+
+import { create } from 'zustand';
+import type { FollowApplicationMode, FollowStatus } from '@oxyhq/contracts';
+
+/** The status of one target, or `undefined` when it has never been read. */
+type StatusMap = Record<string, FollowStatus | undefined>;
+
+interface FollowTargetState {
+  statuses: StatusMap;
+  /** In-flight writes, per target. Reads do not set this — only mutations do. */
+  pending: Record<string, boolean>;
+  errors: Record<string, string | undefined>;
+
+  setStatus: (targetId: string, status: FollowStatus) => void;
+  /**
+   * Seed many statuses at once — from a follow list, a feed payload, anything
+   * that already knows. Saves one request per rendered row, which is the
+   * difference between a list that paints and a list that flickers.
+   */
+  seed: (entries: Record<string, FollowStatus>) => void;
+  setPending: (targetId: string, pending: boolean) => void;
+  setError: (targetId: string, error: string | undefined) => void;
+  /** Drop everything. Called on identity change — see the note below. */
+  reset: () => void;
+}
+
+/**
+ * The state one target is in before the server has been asked. Distinct from
+ * "not following": a button that renders a follow action while the answer is
+ * unknown invites a follow the user did not intend, so callers check
+ * `isUnknown` rather than reading this as an answer.
+ */
+export const UNKNOWN_FOLLOW_STATUS: FollowStatus = {
+  globalState: 'none',
+  applicationMode: 'inherit',
+  effectiveState: 'not_following',
+};
+
+export const useFollowTargetStore = create<FollowTargetState>((set) => ({
+  statuses: {},
+  pending: {},
+  errors: {},
+
+  setStatus: (targetId, status) =>
+    set((s) => ({ statuses: { ...s.statuses, [targetId]: status } })),
+
+  seed: (entries) => set((s) => ({ statuses: { ...s.statuses, ...entries } })),
+
+  setPending: (targetId, pending) =>
+    set((s) => ({ pending: { ...s.pending, [targetId]: pending } })),
+
+  setError: (targetId, error) => set((s) => ({ errors: { ...s.errors, [targetId]: error } })),
+
+  // Every entry here is scoped to whoever was signed in when it was read. On an
+  // account switch the whole map is wrong, not stale — the next user's follows
+  // are a different set entirely, and showing one user their previous
+  // account's follow state is a privacy failure rather than a rendering one.
+  reset: () => set({ statuses: {}, pending: {}, errors: {} }),
+}));
+
+/**
+ * Whether the user follows this at all, anywhere.
+ *
+ * Deliberately NOT `effectiveState !== 'not_following'`: a follow switched off
+ * in this application reports `not_following` — correctly, since the question
+ * that field answers is "does this act here" — and a button that read it as
+ * "not followed" would offer to follow something already followed.
+ */
+export function isFollowedGlobally(status: FollowStatus): boolean {
+  return status.globalState === 'active' || status.globalState === 'requested';
+}
+
+/**
+ * Apply a mode change to a cached status without a round trip.
+ *
+ * Exported because the optimistic path and the settled path must agree on what
+ * `effectiveState` becomes; deriving it in two places is how they drift. Mirrors
+ * the server's own derivation, which is the authority.
+ */
+export function withApplicationMode(
+  status: FollowStatus,
+  mode: FollowApplicationMode
+): FollowStatus {
+  return {
+    ...status,
+    applicationMode: mode,
+    effectiveState:
+      mode === 'disabled'
+        ? 'not_following'
+        : status.globalState === 'active'
+          ? 'following'
+          : status.globalState === 'requested'
+            ? 'requested'
+            : 'not_following',
+  };
+}

package/src/ui/stores/resetSessionScopedStores.ts

@@ -1,4 +1,5 @@
 import { useFollowStore } from './followStore';
+import { useFollowTargetStore } from './followTargetStore';
 
 /**
  * Drop session-scoped Zustand slices so the next user/account never inherits
@@ -10,4 +11,5 @@ import { useFollowStore } from './followStore';
  */
 export function resetSessionScopedStores(): void {
   useFollowStore.getState().resetFollowState();
+  useFollowTargetStore.getState().reset();
 }

package/src/ui/utils/avatarUtils.ts

@@ -5,6 +5,10 @@ import { useAccountStore } from '../stores/accountStore';
 import { useAuthStore } from '../stores/authStore';
 import type { QueryClient } from '@tanstack/react-query';
 import { queryKeys, invalidateUserQueries, invalidateAccountQueries } from '../hooks/queries/queryKeys';
+import {
+  clearedFieldsFromProfileUpdate,
+  upsertCachedUser,
+} from '../hooks/queries/userCache';
 
 /**
  * Refreshes avatar in accountStore with cache-busted URL to force image reload.
@@ -60,6 +64,11 @@ export async function updateProfileWithAvatar(
   // Update authStore so frontend components see the changes immediately
   useAuthStore.getState().setUser(data);
 
+  const cleared = clearedFieldsFromProfileUpdate(updates);
+  upsertCachedUser(queryClient, data, data.id, {
+    cleared: cleared.length > 0 ? cleared : undefined,
+  });
+
   // If avatar was updated, refresh accountStore with a cache-busted URL. An
   // EMPTY avatar is a removal: clear both fields so the switcher falls back to
   // initials instead of pointing at a download URL for the empty file id.