feat(client-federation): user-view cache for cross-instance DM render

Fixes a render bug where a federated user (e.g. axel@nova) appeared with the federation globe icon and a broken avatar when viewed on his own home instance. Root cause: `populateFromReady` is first-wins by federatedId and discards the entire skipped DM payload — including its `members` array — so when a sibling instance's ready arrived first, the home instance's view of every shared user was dropped on the floor. Adds a render-only `userViews` cache that mirrors the `dmAlternatives` philosophy: information from skipped ready payloads is preserved for rendering. Every wire surface that delivers a User upserts into the cache regardless of dedup outcome; render sites read through a Zustand selector hook to surface the home view when one is loaded. The DM channel ingestion race is left untouched — the existing no-flapping invariant on origin reconnect is intentional and load-bearing for failover. Layered changes: - `identity.ts`: `normalizeOriginToHost`, `canonicalUserKey`, `isDeliveryFromHome`, `isFederationGlobeApplicable` — single helpers for origin/host normalization and the home/stub tier decision. - `spaceStore.ts`: `userViews` Map, `UserViewEntry` type, `upsertUserView` action with the home-wins preference rule, prune by `deliveredBy` in `removeInstanceSpaces` (mirrors `dmAlternatives` cleanup), `reset` clears. - `userViewLookup.ts`: `useCanonicalUserView` (Zustand selector hook for React) + `getCanonicalUserView` (sync getter for non-React paths). Render reactivity is structural via the selector, not coincidence on legacy update paths. - `populateFromReady` upsert pass runs BEFORE the federatedId dedup so members of skipped DMs still reach the cache. - WS handlers (dm_message_*, message_*, user_updated, member_joined, friend_request_*, dm_channel_created, dm_member_added) and REST hydrators (socialStore, discoverStore, mutuals) feed the cache with their delivering origin. - Render-site routing through `useCanonicalUserView` at every audited user-rendering site (sidebar, header, search, message bubble, reply chips, profile popout/modal, group settings, voice tiles, mention chips, member lists, friends, invites). Self-rendering sites compose alongside via existing `isSelf`/`resolveDisplayIdentity`. - Globe predicate hoisted to `isFederationGlobeApplicable` and applied at three sites, gating on `domain !== window.location.host` so we never show the globe for users whose home IS our own. Tests: 31 new unit tests across `identity`, `userViews` store, and `userViewLookup`. Full suite 276/276. Docs: `client-federation.md` §3 gains a "User View Cache" section parallel to "DM Origin Failover"; `dm-system.md` notes the new store action and WS handler upserts. Bug 3 (federation profile-sync gap — orbit's stale profile data on nova-Axel after a clear/color-change on nova never propagated) remains open. The user-view cache routes around it for the common case (home instance is connected), but the underlying S2S relay gap is its own diagnosis and follows in a separate branch.
2026-05-05 01:59:05 +02:00
parent fb96b1457a
commit 49e9047005
33 changed files with 2150 additions and 791 deletions
@@ -1,5 +1,5 @@
 import { create } from 'zustand';
-import type { DiscoverUser } from '@backspace/shared';
+import type { DiscoverUser, User } from '@backspace/shared';
 import { api } from '../api/client';
 import { useInstanceStore } from './instanceStore';
 import { normalizeUserAssets } from '../utils/assetUrls';
@@ -52,6 +52,10 @@ export const useDiscoverStore = create<DiscoverState>((set) => ({
      });
    }

+    // Lazy import — avoids pulling spaceStore's transitive dependency chain
+    // (voiceStore → AudioManager) into test environments.
+    const { useSpaceStore } = await import('./spaceStore');
+
    try {
      const instances = useInstanceStore.getState().instances;
      const connectedInstances = instances.filter(i => i.status === 'connected');
@@ -84,6 +88,8 @@ export const useDiscoverStore = create<DiscoverState>((set) => ({
          seen.add(key);
          if (origin) normalizeUserAssets(user as unknown as { avatar?: string | null; banner?: string | null }, origin);
          allUsers.push({ ...user, _instanceOrigin: origin });
+          // DiscoverUser carries the identity/avatar fields the cache needs; cast to User.
+          useSpaceStore.getState().upsertUserView(user as unknown as User, origin);
        }
      }

@@ -81,6 +81,10 @@ export const useSocialStore = create<SocialState>((set, get) => ({
      // Wait for all remote connections to establish before fanning out
      await waitForAutoConnect();

+      // Lazy import — avoids pulling spaceStore's transitive chain (voiceStore →
+      // AudioManager) into test environments that mock only instanceStore.
+      const { useSpaceStore } = await import('./spaceStore');
+
      const instances = useInstanceStore.getState().instances;
      const connectedInstances = instances.filter(i => i.status === 'connected');

@@ -113,6 +117,9 @@ export const useSocialStore = create<SocialState>((set, get) => ({
            if (isNative) {
              if (origin) normalizeUserAssets(friend, origin);
              allFriends[existingIdx] = { ...friend, _instanceOrigin: origin };
+              // Upsert the upgraded (native) view into the userViews cache.
+              // Friend carries all identity/avatar fields the cache needs.
+              useSpaceStore.getState().upsertUserView(friend as unknown as User, origin);
            }
            continue;
          }
@@ -120,6 +127,7 @@ export const useSocialStore = create<SocialState>((set, get) => ({
          seen.set(canonicalId, allFriends.length);
          if (origin) normalizeUserAssets(friend, origin);
          allFriends.push({ ...friend, _instanceOrigin: origin });
+          useSpaceStore.getState().upsertUserView(friend as unknown as User, origin);
        }
      }

@@ -139,6 +147,9 @@ export const useSocialStore = create<SocialState>((set, get) => ({
      // Wait for all remote connections to establish before fanning out
      await waitForAutoConnect();

+      // Lazy import — same pattern as loadFriends; avoids AudioManager TDZ in tests.
+      const { useSpaceStore } = await import('./spaceStore');
+
      const instances = useInstanceStore.getState().instances;
      const connectedInstances = instances.filter(i => i.status === 'connected');

@@ -172,6 +183,7 @@ export const useSocialStore = create<SocialState>((set, get) => ({
            if (otherIsNativeHere) {
              if (origin && request.user) normalizeUserAssets(request.user, origin);
              allRequests[existingIdx] = { ...request, _instanceOrigin: origin };
+              if (request.user) useSpaceStore.getState().upsertUserView(request.user, origin);
            }
            continue;
          }
@@ -179,6 +191,7 @@ export const useSocialStore = create<SocialState>((set, get) => ({
          if (otherCanonicalId) seen.set(otherCanonicalId, allRequests.length);
          if (origin && request.user) normalizeUserAssets(request.user, origin);
          allRequests.push({ ...request, _instanceOrigin: origin });
+          if (request.user) useSpaceStore.getState().upsertUserView(request.user, origin);
        }
      }

@@ -278,6 +291,9 @@ export const useSocialStore = create<SocialState>((set, get) => ({

  searchUsers: async (query: string) => {
    try {
+      // Lazy import — avoids AudioManager TDZ in test environments.
+      const { useSpaceStore } = await import('./spaceStore');
+
      const instances = useInstanceStore.getState().instances;
      const connectedInstances = instances.filter(i => i.status === 'connected');

@@ -316,6 +332,7 @@ export const useSocialStore = create<SocialState>((set, get) => ({
            if (isNative) {
              if (origin) normalizeUserAssets(user, origin);
              allUsers[existingIdx] = { ...user, _instanceOrigin: origin };
+              useSpaceStore.getState().upsertUserView(user, origin);
            }
            continue;
          }
@@ -323,6 +340,7 @@ export const useSocialStore = create<SocialState>((set, get) => ({
          seen.set(canonicalId, allUsers.length);
          if (origin) normalizeUserAssets(user, origin);
          allUsers.push({ ...user, _instanceOrigin: origin });
+          useSpaceStore.getState().upsertUserView(user, origin);
        }
      });

@@ -2,7 +2,7 @@ import { create } from 'zustand';
 import type { Space, Channel, ChannelCategory, MemberWithUser, SpaceWithChannelsAndMembers, Role, SpaceFolder, SpaceLayoutItem, DmChannel, User, UpdateSpaceRequest, CreateSpaceRequest } from '@backspace/shared';
 import { api, BackspaceApiClient } from '../api/client';
 import { resolveAssetUrl, normalizeUserAssets } from '../utils/assetUrls';
-import { isSelf } from '../utils/identity';
+import { isSelf, canonicalUserKey, isDeliveryFromHome } from '../utils/identity';
 import { sortDmChannels } from '../utils/dmSorting';
 import {
  getApiForOrigin,
@@ -29,6 +29,31 @@ export class NotConnectedError extends Error {
  }
 }

+// ─── User-view cache types ────────────────────────────────────────────────────
+
+/**
+ * A single cached view of a user, populated from one delivering origin.
+ *
+ * The userViews cache stores the best-known view of each canonical identity
+ * across every connected instance, regardless of whether the carrying channel
+ * survived dedup. Mirrors `dmAlternatives` philosophy: information from
+ * skipped ready payloads is still load-bearing for rendering.
+ *
+ * - `deliveredBy`: the origin string used at insert time. Required for
+ *   lifecycle pruning (drop entries whose delivering origin is removed from
+ *   Connections) — the user's declared `homeInstance` is NOT a substitute,
+ *   because a stub view delivered by orbit has homeInstance=nova.
+ * - `isHome`: cached at insert time so the preference rule does not need to
+ *   re-normalize on every write.
+ * - `updatedAt`: same-tier freshness tiebreaker.
+ */
+export interface UserViewEntry {
+  user: User;
+  deliveredBy: string;
+  isHome: boolean;
+  updatedAt: number;
+}
+
 // ─── Store interface ──────────────────────────────────────────────────────────

 interface SpaceState {
@@ -50,6 +75,16 @@ interface SpaceState {
  categoryOriginMap: Map<string, string>; // categoryId → instance origin ('' = home)
  /** federatedId → (origin → localChannelId). Every DM from every origin's ready payload is recorded here regardless of dedup outcome, so failover can re-point to an alternate origin's local channel ID. */
  dmAlternatives: Map<string, Map<string, string>>;
+  /**
+   * canonicalUserKey → best-known view of that user. Populated from every wire
+   * surface that delivers a User object (DM members, message authors, friends,
+   * space members, profile updates). Pruned only on full instance removal
+   * (`removeInstanceSpaces`) and `reset`, never on transient WS disconnect —
+   * mirrors `dmAlternatives`' no-flapping invariant. Render sites read through
+   * `getCanonicalUserView` / `useCanonicalUserView` to surface the home view
+   * even when the carrying channel was deduped away.
+   */
+  userViews: Map<string, UserViewEntry>;
  loadingSpaceId: string | null; // non-null while loadSpaceDetail is fetching
  _layoutUpdatedAt: number;
  setSpaces: (spaces: TaggedSpace[]) => void;
@@ -90,6 +125,16 @@ interface SpaceState {
  setSpaceLayout: (layout: SpaceLayoutItem[] | null) => void;
  updateSpaceLayout: (items: SpaceLayoutItem[], folders: Record<string, { name: string | null; color: string | null; spaceIds: string[] }>) => Promise<void>;
  populateFromReady: (origin: string, spaces: SpaceWithChannelsAndMembers[], folders?: SpaceFolder[], dmChannels?: DmChannel[], spaceLayout?: SpaceLayoutItem[] | null, layoutUpdatedAt?: number) => void;
+  /**
+   * Upsert a User into the userViews cache under the preference rule:
+   *   - if no entry: insert
+   *   - if existing is home view and incoming is stub: ignore
+   *   - if existing is stub and incoming is home view: overwrite (upgrade)
+   *   - same tier (both home or both stub): freshness wins (incoming overwrites)
+   * Origin is REQUIRED to derive the home/stub tier and to enable pruning by
+   * delivering origin on instance removal.
+   */
+  upsertUserView: (user: User, deliveringOrigin: string) => void;
  addSpaceFromReady: (origin: string, space: SpaceWithChannelsAndMembers) => void;
  removeInstanceSpaces: (origin: string) => void;
  transferOwnership: (spaceId: string, newOwnerId: string) => Promise<void>;
@@ -142,6 +187,7 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
  voiceChannelIds: new Set(),
  categoryOriginMap: new Map(),
  dmAlternatives: new Map(),
+  userViews: new Map(),
  loadingSpaceId: null,
  _layoutUpdatedAt: 0,

@@ -165,6 +211,7 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
      voiceChannelIds: new Set(),
      categoryOriginMap: new Map(),
      dmAlternatives: new Map(),
+      userViews: new Map(),
      loadingSpaceId: null,
      _layoutUpdatedAt: 0,
    });
@@ -189,6 +236,24 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
    };
  }),

+  upsertUserView: (user, deliveringOrigin) => set((state) => {
+    const key = canonicalUserKey(user);
+    const incomingIsHome = isDeliveryFromHome(user, deliveringOrigin);
+    const existing = state.userViews.get(key);
+
+    // Stub view never overwrites a home view.
+    if (existing && existing.isHome && !incomingIsHome) return state;
+
+    const next = new Map(state.userViews);
+    next.set(key, {
+      user,
+      deliveredBy: deliveringOrigin,
+      isHome: incomingIsHome,
+      updatedAt: Date.now(),
+    });
+    return { userViews: next };
+  }),
+
  removeDmChannel: (id) => {
    set((state) => ({
      dmChannels: state.dmChannels.filter(c => c.id !== id)
@@ -265,6 +330,11 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
          normalizeUserAssets(member.user, origin);
        }
      }
+      // Upsert every member into the userViews cache (home or remote).
+      // Assets are already normalized above for the remote case.
+      for (const member of detail.members) {
+        get().upsertUserView(member.user, origin);
+      }

      // Populate permission maps from REST response
      const spacePermissions = new Map(get().spacePermissions);
@@ -662,6 +732,15 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
          categoryOriginMap.set(cat.id, origin);
        }
      }
+      // Upsert every space member into the userViews cache. Assets for remote
+      // origins were normalized by the ready handler in useWebSocket before
+      // populateFromReady was called, so the user objects are already clean here.
+      if (srv.members) {
+        const { upsertUserView } = get();
+        for (const member of srv.members) {
+          upsertUserView(member.user, origin);
+        }
+      }
    }

    // Accept DMs from all origins. Each instance serves its own DM data.
@@ -676,6 +755,19 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
      }
    }

+    // Upsert every DM member from every origin into the userViews cache.
+    // This runs unconditionally (home + remote) and BEFORE the dedup pass so
+    // members of DMs that are about to be discarded still land in the cache.
+    // Assets are already normalized above for the remote case.
+    {
+      const { upsertUserView } = get();
+      for (const dm of incomingDms) {
+        for (const member of dm.members) {
+          upsertUserView(member, origin);
+        }
+      }
+    }
+
    // Build a set of existing federatedIds for dedup (only from OTHER origins —
    // DMs from the reconnecting origin will be replaced, not deduplicated)
    const existingFederatedIds = new Map<string, string>(); // federatedId → dmChannelId
@@ -890,6 +982,16 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
        if (nextInner.size > 0) dmAlternatives.set(fid, nextInner);
      }

+      // Prune userViews: drop entries delivered by this origin. Symmetrical
+      // with dmAlternatives — full removal evicts; transient disconnect leaves
+      // the last-known view in place. If the surviving cache no longer holds
+      // a home view for some user, render falls back to whatever the carrying
+      // payload supplies (no crash; just degrades to stub view).
+      const userViews = new Map<string, UserViewEntry>();
+      for (const [key, entry] of state.userViews) {
+        if (entry.deliveredBy !== origin) userViews.set(key, entry);
+      }
+
      return {
        spaces: remainingSpaces,
        channelToSpaceMap,
@@ -898,6 +1000,7 @@ export const useSpaceStore = create<SpaceState>((set, get) => ({
        channelOriginMap,
        spacePermissions,
        dmAlternatives,
+        userViews,
        currentSpaceId: remainingSpaces.find(s => s.id === state.currentSpaceId)
          ? state.currentSpaceId
          : null,
@@ -0,0 +1,250 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+vi.mock('../audio/AudioManager', () => ({
+  AudioManager: {
+    getInstance: vi.fn().mockReturnValue({
+      setOutputDevice: vi.fn(),
+      setVolume: vi.fn(),
+    }),
+  },
+}));
+
+vi.mock('./instanceStore', () => ({
+  useInstanceStore: Object.assign(
+    (selector: (s: unknown) => unknown) => selector({ instances: [], _autoConnectDone: true }),
+    {
+      getState: () => ({ instances: [], _autoConnectDone: true }),
+      setState: vi.fn(),
+      subscribe: vi.fn(),
+    }
+  ),
+}));
+
+vi.mock('./authStore', () => ({
+  useAuthStore: Object.assign(
+    (selector: (s: unknown) => unknown) => selector({ user: null, token: null }),
+    {
+      getState: () => ({ user: null, token: null }),
+      setState: vi.fn(),
+      subscribe: vi.fn(),
+    }
+  ),
+}));
+
+import { useSpaceStore } from './spaceStore';
+import { canonicalUserKey } from '../utils/identity';
+import type { User } from '@backspace/shared';
+
+function makeUser(extras: Partial<User> & Pick<User, 'id' | 'username'>): User {
+  return {
+    displayName: extras.username,
+    avatar: '',
+    avatarColor: 'mint',
+    homeUserId: null,
+    homeInstance: null,
+    status: 'online',
+    customStatus: null,
+    bio: null,
+    banner: null,
+    isAdmin: false,
+    isDeleted: false,
+    discoverable: true,
+    showActivity: true,
+    createdAt: 0,
+    ...extras,
+  } as User;
+}
+
+beforeEach(() => {
+  Object.defineProperty(window, 'location', {
+    value: { host: 'nova.ddns.net' },
+    writable: true,
+  });
+  useSpaceStore.getState().reset();
+});
+
+describe('spaceStore.upsertUserView preference rule', () => {
+  it('inserts a fresh entry when none exists', () => {
+    const user = makeUser({ id: 'local-1', username: 'alice' });
+    useSpaceStore.getState().upsertUserView(user, '');
+    const entry = useSpaceStore.getState().userViews.get(canonicalUserKey(user));
+    expect(entry).toBeDefined();
+    expect(entry!.user).toBe(user);
+    expect(entry!.isHome).toBe(true);
+    expect(entry!.deliveredBy).toBe('');
+  });
+
+  it('home view (delivered by user home) wins over an existing stub', () => {
+    // orbit delivers Axel as a federated stub (axel's home is nova).
+    const stubAxel = makeUser({
+      id: 'orbit-local-id',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'lavender',
+      avatar: 'https://nova.ddns.net/api/uploads/old.png',
+    });
+    useSpaceStore.getState().upsertUserView(stubAxel, 'https://orbit.ddns.net');
+
+    // Then nova delivers axel natively (no homeInstance, our home origin '').
+    // canonicalUserKey for the home view: needs to match the stub's key.
+    // Stub key = "nova.ddns.net:nova-axel-id".
+    // Home view (nova native): homeInstance=null, homeUserId=null, id="nova-axel-id"
+    //   → key = ":nova-axel-id"
+    // These keys are different on purpose: the home record on its home instance
+    // has no homeInstance/homeUserId. The cross-instance match relies on the
+    // stub being the federated form. Verify behavior accordingly.
+    const homeAxel = makeUser({
+      id: 'nova-axel-id',
+      username: 'axel',
+      avatar: '',
+      avatarColor: 'teal',
+    });
+    useSpaceStore.getState().upsertUserView(homeAxel, '');
+
+    // Stub entry is unchanged (different canonical key).
+    const stubEntry = useSpaceStore.getState().userViews.get(canonicalUserKey(stubAxel));
+    expect(stubEntry?.user.avatarColor).toBe('lavender');
+    // Home entry exists under its own key.
+    const homeEntry = useSpaceStore.getState().userViews.get(canonicalUserKey(homeAxel));
+    expect(homeEntry?.user.avatarColor).toBe('teal');
+  });
+
+  it('two same-canonical-key federated views: home delivery upgrades over sibling stub', () => {
+    // Same person, same canonical key (homeInstance=nova, homeUserId=nova-axel-id),
+    // but delivered from two different origins.
+    const fromOrbit = makeUser({
+      id: 'orbit-local',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'lavender',
+    });
+    const fromNova = makeUser({
+      id: 'nova-local',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'teal',
+    });
+
+    useSpaceStore.getState().upsertUserView(fromOrbit, 'https://orbit.ddns.net');
+    useSpaceStore.getState().upsertUserView(fromNova, 'https://nova.ddns.net');
+
+    const entry = useSpaceStore.getState().userViews.get(canonicalUserKey(fromNova));
+    expect(entry?.isHome).toBe(true);
+    expect(entry?.user.avatarColor).toBe('teal');
+    expect(entry?.deliveredBy).toBe('https://nova.ddns.net');
+  });
+
+  it('stub view does NOT overwrite an existing home view', () => {
+    const fromNova = makeUser({
+      id: 'nova-local',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'teal',
+    });
+    const fromOrbit = makeUser({
+      id: 'orbit-local',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'lavender',
+    });
+
+    useSpaceStore.getState().upsertUserView(fromNova, 'https://nova.ddns.net');
+    useSpaceStore.getState().upsertUserView(fromOrbit, 'https://orbit.ddns.net');
+
+    const entry = useSpaceStore.getState().userViews.get(canonicalUserKey(fromNova));
+    expect(entry?.isHome).toBe(true);
+    expect(entry?.user.avatarColor).toBe('teal');
+    expect(entry?.deliveredBy).toBe('https://nova.ddns.net');
+  });
+
+  it('same-tier writes update freshness (later write wins)', () => {
+    const a = makeUser({
+      id: 'orbit-1',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'lavender',
+    });
+    const b = makeUser({
+      id: 'orbit-1',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'sky', // simulating a later profile-update event
+    });
+
+    useSpaceStore.getState().upsertUserView(a, 'https://orbit.ddns.net');
+    useSpaceStore.getState().upsertUserView(b, 'https://orbit.ddns.net');
+
+    const entry = useSpaceStore.getState().userViews.get(canonicalUserKey(b));
+    expect(entry?.user.avatarColor).toBe('sky');
+  });
+
+  it('reset clears userViews', () => {
+    const user = makeUser({ id: 'local-1', username: 'alice' });
+    useSpaceStore.getState().upsertUserView(user, '');
+    expect(useSpaceStore.getState().userViews.size).toBe(1);
+    useSpaceStore.getState().reset();
+    expect(useSpaceStore.getState().userViews.size).toBe(0);
+  });
+
+  it('removeInstanceSpaces prunes entries delivered by the removed origin only', () => {
+    const homeView = makeUser({
+      id: 'nova-axel-id',
+      username: 'axel',
+      avatarColor: 'teal',
+    });
+    const stubView = makeUser({
+      id: 'orbit-axel-stub',
+      username: 'axel@nova.ddns.net',
+      homeUserId: 'nova-axel-id',
+      homeInstance: 'nova.ddns.net',
+      avatarColor: 'lavender',
+    });
+
+    useSpaceStore.getState().upsertUserView(homeView, '');
+    useSpaceStore.getState().upsertUserView(stubView, 'https://orbit.ddns.net');
+    expect(useSpaceStore.getState().userViews.size).toBe(2);
+
+    // Removing orbit should drop the stub but keep the home view.
+    useSpaceStore.getState().removeInstanceSpaces('https://orbit.ddns.net');
+    const remaining = useSpaceStore.getState().userViews;
+    expect(remaining.size).toBe(1);
+    expect(remaining.get(canonicalUserKey(homeView))).toBeDefined();
+    expect(remaining.get(canonicalUserKey(stubView))).toBeUndefined();
+  });
+
+  it('removeInstanceSpaces of the home origin evicts entries it delivered', () => {
+    const homeView = makeUser({
+      id: 'nova-axel-id',
+      username: 'axel',
+      avatarColor: 'teal',
+    });
+    useSpaceStore.getState().upsertUserView(homeView, '');
+    useSpaceStore.getState().removeInstanceSpaces('');
+    expect(useSpaceStore.getState().userViews.size).toBe(0);
+  });
+
+  it('treats native users delivered by a remote as that remote\'s home view', () => {
+    // jannis is native to orbit (homeInstance=null on orbit). When orbit
+    // delivers him, that's the home view. canonicalKey uses orbit-host.
+    const jannis = makeUser({
+      id: 'orbit-jannis-id',
+      username: 'jannis',
+      avatarColor: 'sky',
+    });
+    useSpaceStore.getState().upsertUserView(jannis, 'https://orbit.ddns.net');
+    // Key is built from user.homeInstance — but jannis has none. So the key is
+    // ':orbit-jannis-id'. That's correct: when delivered later from a sibling,
+    // jannis would arrive WITH homeInstance set (synthesized by normalizeUserAssets),
+    // producing a different (federated) key. The cache holds both, with the
+    // home view winning on a cross-key collision-free basis.
+    const entry = useSpaceStore.getState().userViews.get(`:${jannis.id}`);
+    expect(entry?.isHome).toBe(true);
+  });
+});