@drakkar.software/octospaces-sdk 0.1.0 → 0.4.3

package/src/sync/space-access.ts

@@ -1,136 +1,181 @@
 /**
- * Space access resolver — returns the right (client, encryptor) pair for any
- * space regardless of whether it is private (E2EE) or public (plaintext).
+ * Space and node access resolver.
  *
- * Replaces `space-encryptor.ts`. The key invariant: public spaces have
- * `encryptor: null`; private spaces always have a live `Encryptor`.
+ * Encryption is per-node (each node has an `enc` flag) but keyed under ONE
+ * space-wide keyring at `spaces/{spaceId}/_keyring`. All `enc` nodes in a space
+ * share the same CEK; `access` gates *fetching*, the keyring gates *decryption*.
  *
- * Resolution order (same semantics as the old `getSpaceEncryptor`):
- *   1. Link entry in the access store → sign requests as the ephemeral identity;
- *      no keyring, encryptor null.
- *   2. Member entry → open the keyring as a recipient with the stored cap.
- *   3. No entry + visibility === 'public' (from `reg`) → owner mode, no keyring.
- *   4. No entry, private → either owner (open/mint keyring) or SpaceAccessError
- *      if the space's roster shows we're a member but we're not holding a cap yet.
+ * Two entry points:
+ *   - `getSpaceClient`  — returns the right StarfishClient for member-gated
+ *     space docs (index, _access). No encryptor.
+ *   - `getNodeAccess`   — resolves the (client, encryptor) for a specific node's
+ *     CONTENT. Encryptor is null for plaintext nodes; for enc nodes the encryptor
+ *     opens the SPACE keyring (not a per-node keyring).
+ *
+ * Resolution order for `getNodeAccess`:
+ *   1. Per-node link entry  → sign as ephemeral identity; encryptor from space keyring.
+ *   2. Per-node member entry → open space keyring as recipient.
+ *   3. Space-level link entry → same client; open space keyring if enc.
+ *   4. Space-level member entry → open space keyring if enc.
+ *   5. No entry, owner        → mint space keyring if enc; plain client otherwise.
+ *   6. No entry, non-owner   → SpaceAccessError if enc; plain client otherwise.
  */
 import type { Encryptor, StarfishClient } from '@drakkar.software/starfish-client';
 
 import { buildEncryptor, makeClient, openEncryptor, ownerEnsureKeyring } from './client.js';
 import type { Session } from './identity.js';
 import { ownerTrustedAdders } from './identity.js';
-import { getSpaceAccessEntry } from './space-access-store.js';
+import { getNodeAccessEntry, getSpaceAccessEntry } from './space-access-store.js';
 import { SpaceAccessError } from '../core/space-access-error.js';
-import type { SpaceVisibility } from '../core/types.js';
+import { keyringPull, keyringPush } from './paths.js';
+import type { NodeAccess } from '../core/types.js';
 
 // Re-export so existing importers keep reaching SpaceAccessError through this module.
 export { SpaceAccessError };
 
-export interface SpaceAccessHandle {
+export interface NodeAccessHandle {
   encryptor: Encryptor | null;
   client: StarfishClient;
-  /** True when opened as the space OWNER (so the caller must seed the room doc). */
+  /** True when opened as the space OWNER (may seed / mint the space keyring). */
   isOwnerOpen: boolean;
 }
 
-const cache = new Map<string, Promise<SpaceAccessHandle>>();
+const cache = new Map<string, Promise<NodeAccessHandle>>();
 
 /** Drop every cached handle (on account switch — keys are per-identity). */
-export function clearSpaceAccessCache(): void {
+export function clearNodeAccessCache(): void {
   cache.clear();
 }
 
 /**
- * Resolve the right (client, encryptor) for a space, opening and caching on first use.
+ * Return the right StarfishClient for reading/writing member-gated space docs
+ * (e.g. the `_index`, `_access`). Spaces are always plaintext — no encryptor.
+ */
+export function getSpaceClient(spaceId: string, session: Session): StarfishClient {
+  const entry = getSpaceAccessEntry(spaceId);
+  if (entry?.kind === 'link') return makeClient(entry.cap, entry.key);
+  if (entry?.kind === 'member') {
+    const cap = JSON.parse(entry.cap) as { iss?: string };
+    return makeClient(cap, session.keys.edPriv);
+  }
+  return session.chatClient;
+}
+
+/**
+ * Resolve the right (client, encryptor) for a node's CONTENT, opening and
+ * caching on first use.
  *
- * `reg` is the space's `_rooms` access record if already known. Pass null when the
- * caller has not yet read the registry; the resolver will probe if needed.
+ * `node` carries `{ access?, enc? }` — the plaintext flags from the index.
+ * `reg` is the space's access record if already known; used to determine
+ * ownership. Pass null if unknown.
  */
-export function getSpaceAccess(
+export function getNodeAccess(
   spaceId: string,
+  nodeId: string,
+  node: { access?: NodeAccess; enc?: boolean },
   session: Session,
-  reg: { owner: string | null; members: string[]; visibility?: SpaceVisibility } | null,
-): Promise<SpaceAccessHandle> {
-  const hit = cache.get(spaceId);
+  reg?: { owner: string | null; members: string[] } | null,
+): Promise<NodeAccessHandle> {
+  const cacheKey = `${spaceId}:${nodeId}`;
+  const hit = cache.get(cacheKey);
   if (hit) return hit;
-  const p = (async (): Promise<SpaceAccessHandle> => {
-    const entry = getSpaceAccessEntry(spaceId);
-
-    // 1. Link entry — ephemeral identity; no keyring
-    if (entry?.kind === 'link') {
-      const cap = entry.cap;
-      const client = makeClient(cap, entry.key);
-      return { encryptor: null, client, isOwnerOpen: false };
+
+  const p = (async (): Promise<NodeAccessHandle> => {
+    // Prefer a per-node entry, fall back to the space-level entry for the client.
+    const nodeEntry = getNodeAccessEntry(spaceId, nodeId);
+    const spaceEntry = getSpaceAccessEntry(spaceId);
+    const activeEntry = nodeEntry ?? spaceEntry;
+
+    // Build the client.
+    let client: StarfishClient;
+    let capIss: string | undefined;
+    if (activeEntry?.kind === 'link') {
+      client = makeClient(activeEntry.cap, activeEntry.key);
+    } else if (activeEntry?.kind === 'member') {
+      const cap = JSON.parse(activeEntry.cap) as { iss?: string };
+      capIss = cap.iss;
+      client = makeClient(cap, session.keys.edPriv);
+    } else {
+      client = session.chatClient;
     }
 
-    // 2. Member entry — open as a keyring recipient
-    if (entry?.kind === 'member') {
-      const cap = JSON.parse(entry.cap) as { iss?: string };
-      const client = makeClient(cap, session.keys.edPriv);
-      const encryptor = await openEncryptor(client, session.keys, spaceId, cap.iss ? [cap.iss] : []);
-      return { encryptor, client, isOwnerOpen: false };
+    const isOwnerOpen =
+      reg != null ? reg.owner === session.userId : activeEntry == null;
+
+    // Plaintext node — no keyring needed.
+    if (!node.enc) {
+      return { encryptor: null, client, isOwnerOpen };
     }
 
-    // 3. No entry — branch on visibility
-    const visibility = reg?.visibility;
-    if (visibility === 'public') {
-      return { encryptor: null, client: session.chatClient, isOwnerOpen: reg!.owner === session.userId };
+    // E2EE node — resolve the SPACE-WIDE keyring.
+    const spacePullPath = keyringPull(spaceId);
+    const trustedAdders = capIss
+      ? [capIss]
+      : reg?.owner
+        ? [reg.owner]
+        : ownerTrustedAdders(session);
+
+    if (activeEntry?.kind === 'member' || activeEntry?.kind === 'link') {
+      const encryptor = await openEncryptor(client, session.keys, spacePullPath, trustedAdders);
+      return { encryptor, client, isOwnerOpen: false };
     }
 
-    // 4. No entry, private — owner or error
+    // No access entry — owner mints/opens the keyring; non-owner errors.
     const owner = reg?.owner ?? null;
     const members = reg?.members ?? [];
     if (owner !== null && owner !== session.userId) {
       throw new SpaceAccessError(
         members.includes(session.userId)
-          ? "You're a member of this space, but its key isn't on this device yet — reconnect, or ask the owner to re-invite."
-          : "You don't have access to this space.",
+          ? "You're a member of this space, but the space key isn't on this device yet — ask the owner to invite you."
+          : "You don't have access to this node.",
       );
     }
     const encryptor = await ownerEnsureKeyring(
       session.chatClient,
       session.keys,
-      spaceId,
+      spacePullPath,
+      keyringPush(spaceId),
       ownerTrustedAdders(session),
     );
     return { encryptor, client: session.chatClient, isOwnerOpen: true };
   })();
-  cache.set(spaceId, p);
-  p.catch(() => cache.delete(spaceId));
+
+  cache.set(cacheKey, p);
+  p.catch(() => cache.delete(cacheKey));
   return p;
 }
 
 /**
  * SOFT resolve — never mints a keyring, never throws on missing access.
- * Returns null when the identity has no usable access for the space yet.
+ * Returns null when the identity has no usable access for the node yet.
  */
-export async function buildSpaceAccess(
+export async function buildNodeAccess(
   session: Session,
   spaceId: string,
-  hint?: { visibility?: SpaceVisibility },
+  nodeId: string,
+  node: { enc?: boolean },
 ): Promise<{ client: StarfishClient; encryptor: Encryptor | null } | null> {
-  const entry = getSpaceAccessEntry(spaceId);
+  const nodeEntry = getNodeAccessEntry(spaceId, nodeId);
+  const spaceEntry = getSpaceAccessEntry(spaceId);
+  const activeEntry = nodeEntry ?? spaceEntry;
 
-  if (entry?.kind === 'link') {
-    const client = makeClient(entry.cap, entry.key);
-    return { client, encryptor: null };
-  }
-
-  let client = session.chatClient;
+  let client: StarfishClient;
   let trustedAdders = ownerTrustedAdders(session);
 
-  if (entry?.kind === 'member') {
-    const cap = JSON.parse(entry.cap) as { iss?: string };
+  if (activeEntry?.kind === 'link') {
+    client = makeClient(activeEntry.cap, activeEntry.key);
+  } else if (activeEntry?.kind === 'member') {
+    const cap = JSON.parse(activeEntry.cap) as { iss?: string };
     client = makeClient(cap, session.keys.edPriv);
     if (cap.iss) trustedAdders = [cap.iss];
-    const encryptor = await buildEncryptor(client, session.keys, spaceId, trustedAdders);
-    return encryptor ? { client, encryptor } : null;
+  } else {
+    client = session.chatClient;
   }
 
-  if (hint?.visibility === 'public') {
-    return { client, encryptor: null };
-  }
+  if (!node.enc) return { client, encryptor: null };
 
-  // No entry, no hint — try the keyring probe (owner path)
-  const encryptor = await buildEncryptor(client, session.keys, spaceId, trustedAdders);
+  // Soft-open the SPACE-WIDE keyring.
+  const spacePullPath = keyringPull(spaceId);
+  const encryptor = await buildEncryptor(client, session.keys, spacePullPath, trustedAdders);
   return encryptor ? { client, encryptor } : null;
 }

package/src/utils/invite-preview.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from 'vitest';
+import { previewInvite } from './invite-preview.js';
+import { encodeSpaceInviteLink } from '../spaces/members.js';
+import { encodeNodeInviteLink } from '../spaces/nodes.js';
+import type { SpaceInviteLinkToken } from '../spaces/members.js';
+import type { NodeInviteLinkToken } from '../spaces/nodes.js';
+
+const spaceToken: SpaceInviteLinkToken = {
+  v: 1,
+  spaceId: 'sp-abc123',
+  spaceName: 'My Space',
+  cap: { kind: 'member', iss: 'deadbeef', sub: 'cafecafe', scope: {} },
+  key: 'a1b2c3d4',
+  write: true,
+};
+
+const nodeToken: NodeInviteLinkToken = {
+  v: 1,
+  spaceId: 'sp-abc123',
+  nodeId: 'nd-xyz789',
+  nodeName: 'Secret Doc',
+  cap: { kind: 'member', iss: 'deadbeef', sub: 'cafecafe', scope: {} },
+  key: 'b2c3d4e5',
+  write: false,
+};
+
+const spaceLink = encodeSpaceInviteLink('https://app.example.com', spaceToken);
+const nodeLink = encodeNodeInviteLink('https://app.example.com', nodeToken);
+
+// ── space-link ────────────────────────────────────────────────────────────────
+
+describe('previewInvite — space-link', () => {
+  it('classifies a space invite link', () => {
+    const p = previewInvite(spaceLink);
+    expect(p.kind).toBe('space-link');
+  });
+
+  it('extracts spaceName and write flag', () => {
+    const p = previewInvite(spaceLink);
+    if (p.kind !== 'space-link') throw new Error('wrong kind');
+    expect(p.spaceName).toBe('My Space');
+    expect(p.write).toBe(true);
+  });
+
+  it('exposes the decoded token', () => {
+    const p = previewInvite(spaceLink);
+    if (p.kind !== 'space-link') throw new Error('wrong kind');
+    expect(p.token.spaceId).toBe('sp-abc123');
+  });
+
+  it('accepts a raw fragment (no origin prefix)', () => {
+    const fragment = spaceLink.slice(spaceLink.indexOf('#'));
+    const p = previewInvite(fragment);
+    expect(p.kind).toBe('space-link');
+  });
+
+  it('accepts a read-only (write:false) link', () => {
+    const readOnlyToken: SpaceInviteLinkToken = { ...spaceToken, write: false };
+    const link = encodeSpaceInviteLink('https://app.example.com', readOnlyToken);
+    const p = previewInvite(link);
+    if (p.kind !== 'space-link') throw new Error('wrong kind');
+    expect(p.write).toBe(false);
+  });
+});
+
+// ── node-link ─────────────────────────────────────────────────────────────────
+
+describe('previewInvite — node-link', () => {
+  it('classifies a node invite link', () => {
+    const p = previewInvite(nodeLink);
+    expect(p.kind).toBe('node-link');
+  });
+
+  it('extracts nodeTitle from nodeName', () => {
+    const p = previewInvite(nodeLink);
+    if (p.kind !== 'node-link') throw new Error('wrong kind');
+    expect(p.nodeTitle).toBe('Secret Doc');
+  });
+
+  it('exposes spaceId via spaceName fallback', () => {
+    const p = previewInvite(nodeLink);
+    if (p.kind !== 'node-link') throw new Error('wrong kind');
+    expect(p.spaceName).toContain('abc123'.slice(-6));
+  });
+
+  it('exposes the decoded token', () => {
+    const p = previewInvite(nodeLink);
+    if (p.kind !== 'node-link') throw new Error('wrong kind');
+    expect(p.token.nodeId).toBe('nd-xyz789');
+  });
+});
+
+// ── member-bundle ─────────────────────────────────────────────────────────────
+
+const bundle = JSON.stringify({
+  spaceId: 'sp-abc123',
+  spaceName: 'Team Space',
+  cap: { kind: 'member', iss: 'aabbccddee112233' },
+});
+
+describe('previewInvite — member-bundle', () => {
+  it('classifies a private member-bundle JSON', () => {
+    const p = previewInvite(bundle);
+    expect(p.kind).toBe('member-bundle');
+  });
+
+  it('extracts spaceName and spaceId', () => {
+    const p = previewInvite(bundle);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.spaceName).toBe('Team Space');
+    expect(p.spaceId).toBe('sp-abc123');
+  });
+
+  it('builds issuerKey fingerprint from iss', () => {
+    const p = previewInvite(bundle);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.issuerKey).toContain('aabbccdd');
+    expect(p.issuerKey).toContain('…');
+  });
+
+  it('issuerKey is null when iss is absent', () => {
+    const noIss = JSON.stringify({ spaceId: 'sp-abc123', cap: { kind: 'member' } });
+    const p = previewInvite(noIss);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.issuerKey).toBeNull();
+  });
+
+  it('falls back to id-derived spaceName when spaceName is absent', () => {
+    const noName = JSON.stringify({ spaceId: 'sp-abc123', cap: { kind: 'member' } });
+    const p = previewInvite(noName);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.spaceName).toBe('space-abc123');
+  });
+
+  it('preserves raw inviteJson verbatim', () => {
+    const p = previewInvite(bundle);
+    if (p.kind !== 'member-bundle') throw new Error('wrong kind');
+    expect(p.inviteJson).toBe(bundle);
+  });
+});
+
+// ── error cases ───────────────────────────────────────────────────────────────
+
+describe('previewInvite — errors', () => {
+  it('throws on empty input', () => {
+    expect(() => previewInvite('')).toThrow('Paste an invite');
+  });
+
+  it('throws on a whitespace-only input', () => {
+    expect(() => previewInvite('   ')).toThrow('Paste an invite');
+  });
+
+  it('throws on a malformed URL fragment', () => {
+    expect(() => previewInvite('#not-valid-base64!!!!')).toThrow();
+  });
+
+  it('throws on plain text (not JSON, not a link)', () => {
+    expect(() => previewInvite('hello world')).toThrow("doesn't look like an invite");
+  });
+
+  it('throws on JSON that is not a member bundle', () => {
+    expect(() => previewInvite(JSON.stringify({ foo: 'bar' }))).toThrow('not a valid space invite');
+  });
+
+  it('throws on a bundle whose cap.kind is not member', () => {
+    const bad = JSON.stringify({ spaceId: 'sp-1', cap: { kind: 'owner' } });
+    expect(() => previewInvite(bad)).toThrow('not a valid space invite');
+  });
+});

package/src/utils/invite-preview.ts

@@ -0,0 +1,101 @@
+/**
+ * Parse an invite (pasted text or a `#fragment` deep link) into a preview the
+ * join screen can show on a consent card — name, type, identifying fingerprint
+ * — WITHOUT joining. Actual join calls (`joinSpaceByLink`, `joinNodeByLink`,
+ * `acceptSpaceInvite`, `acceptNodeInvite`) only run after the user confirms.
+ *
+ * Accepts three input forms:
+ *   - A space invite link (URL fragment encoded by `createSpaceInviteLink`)
+ *   - A node invite link (URL fragment encoded by `createNodeInviteLink`)
+ *   - A private member-bundle JSON minted by `inviteToSpace`
+ */
+import { decodeSpaceInviteLink } from '../spaces/members.js';
+import { decodeNodeInviteLink } from '../spaces/nodes.js';
+import type { SpaceInviteLinkToken } from '../spaces/members.js';
+import type { NodeInviteLinkToken } from '../spaces/nodes.js';
+
+export type { SpaceInviteLinkToken, NodeInviteLinkToken };
+
+export type InvitePreview =
+  | {
+      kind: 'space-link';
+      spaceName: string;
+      /** True if the link grants write access, false for read-only. */
+      write: boolean;
+      token: SpaceInviteLinkToken;
+    }
+  | {
+      kind: 'node-link';
+      spaceName: string;
+      /** The node's display name, absent for legacy tokens that omit it. */
+      nodeTitle?: string;
+      token: NodeInviteLinkToken;
+    }
+  | {
+      kind: 'member-bundle';
+      spaceName: string;
+      spaceId: string;
+      /** Short hex fingerprint of the issuing owner's signing key, or null if absent. */
+      issuerKey: string | null;
+      /** The raw cap-bundle JSON — pass verbatim to `acceptSpaceInvite` on consent. */
+      inviteJson: string;
+    };
+
+/** Shape of the private invite bundle minted by `inviteToSpace`. */
+interface PrivateInviteShape {
+  spaceId?: string;
+  spaceName?: string;
+  cap?: { kind?: string; iss?: string };
+}
+
+/**
+ * Classify and decode an invite string into a typed {@link InvitePreview}.
+ * Throws a human-readable `Error` on invalid input (safe to surface verbatim
+ * in a toast or inline error message).
+ */
+export function previewInvite(raw: string): InvitePreview {
+  const text = raw.trim();
+  if (!text) throw new Error('Paste an invite link or code first.');
+
+  // Invite links carry their credential in a URL fragment.
+  if (text.includes('#')) {
+    const fragment = text.slice(text.indexOf('#'));
+    // Try node-invite link first — it has a `nodeId` field the space link lacks.
+    try {
+      const token = decodeNodeInviteLink(fragment);
+      return {
+        kind: 'node-link',
+        spaceName: `space-${token.spaceId.slice(-6)}`,
+        nodeTitle: token.nodeName,
+        token,
+      };
+    } catch {
+      // fall through to space link
+    }
+    try {
+      const token = decodeSpaceInviteLink(fragment);
+      return { kind: 'space-link', spaceName: token.spaceName, write: token.write, token };
+    } catch {
+      throw new Error('That invite link appears to be invalid or expired.');
+    }
+  }
+
+  // Private member-bundle JSON minted by `inviteToSpace`.
+  let parsed: PrivateInviteShape;
+  try {
+    parsed = JSON.parse(text) as PrivateInviteShape;
+  } catch {
+    throw new Error("That doesn't look like an invite. Paste the full invite code or link.");
+  }
+  if (!parsed?.spaceId || parsed.cap?.kind !== 'member') {
+    throw new Error('That is not a valid space invite.');
+  }
+  const iss = parsed.cap?.iss;
+  return {
+    kind: 'member-bundle',
+    spaceName: parsed.spaceName?.trim() || `space-${parsed.spaceId.slice(-6)}`,
+    spaceId: parsed.spaceId,
+    issuerKey: typeof iss === 'string' && iss.length >= 8 ? `${iss.slice(0, 8)}…${iss.slice(-8)}` : null,
+    inviteJson: text,
+  };
+}

package/src/utils/live-sync-bus.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import {
+  registerPull,
+  dispatchDocChange,
+  emitSseStatus,
+  onSseStatus,
+  clearLiveSyncBus,
+} from './live-sync-bus.js';
+
+beforeEach(() => clearLiveSyncBus());
+
+// ── registerPull / dispatchDocChange ──────────────────────────────────────────
+
+describe('registerPull / dispatchDocChange', () => {
+  it('returns false when no pull is registered for the path', () => {
+    expect(dispatchDocChange('spaces/sp-1/objects/_index')).toBe(false);
+  });
+
+  it('calls the registered pull and returns true', () => {
+    const pull = vi.fn();
+    registerPull('spaces/sp-1/objects/_index', pull);
+    const dispatched = dispatchDocChange('spaces/sp-1/objects/_index');
+    expect(dispatched).toBe(true);
+    expect(pull).toHaveBeenCalledOnce();
+  });
+
+  it('does not cross-fire — different paths are independent', () => {
+    const pull1 = vi.fn();
+    const pull2 = vi.fn();
+    registerPull('spaces/sp-1/objects/_index', pull1);
+    registerPull('spaces/sp-2/objects/_index', pull2);
+    dispatchDocChange('spaces/sp-1/objects/_index');
+    expect(pull1).toHaveBeenCalledOnce();
+    expect(pull2).not.toHaveBeenCalled();
+  });
+
+  it('unsubscribe removes the registration', () => {
+    const pull = vi.fn();
+    const unsub = registerPull('spaces/sp-1/objects/_index', pull);
+    unsub();
+    expect(dispatchDocChange('spaces/sp-1/objects/_index')).toBe(false);
+    expect(pull).not.toHaveBeenCalled();
+  });
+
+  it('stale unsubscribe is a no-op after re-registration', () => {
+    const pull1 = vi.fn();
+    const pull2 = vi.fn();
+    const unsub1 = registerPull('spaces/sp-1/objects/_index', pull1);
+    registerPull('spaces/sp-1/objects/_index', pull2); // overwrites
+    unsub1(); // should NOT remove pull2
+    dispatchDocChange('spaces/sp-1/objects/_index');
+    expect(pull2).toHaveBeenCalledOnce();
+  });
+});
+
+// ── emitSseStatus / onSseStatus ───────────────────────────────────────────────
+
+describe('emitSseStatus / onSseStatus', () => {
+  it('fires immediately with the current state (false by default)', () => {
+    const cb = vi.fn();
+    onSseStatus(cb);
+    expect(cb).toHaveBeenCalledWith(false);
+  });
+
+  it('fires on each status change', () => {
+    const cb = vi.fn();
+    onSseStatus(cb);
+    emitSseStatus(true);
+    emitSseStatus(false);
+    expect(cb).toHaveBeenNthCalledWith(1, false); // initial
+    expect(cb).toHaveBeenNthCalledWith(2, true);
+    expect(cb).toHaveBeenNthCalledWith(3, false);
+  });
+
+  it('unsubscribe stops receiving updates', () => {
+    const cb = vi.fn();
+    const unsub = onSseStatus(cb);
+    unsub();
+    emitSseStatus(true);
+    expect(cb).toHaveBeenCalledOnce(); // only the initial fire
+  });
+
+  it('new subscriber gets current state after emitSseStatus(true)', () => {
+    emitSseStatus(true);
+    const cb = vi.fn();
+    onSseStatus(cb);
+    expect(cb).toHaveBeenCalledWith(true);
+  });
+});
+
+// ── clearLiveSyncBus ──────────────────────────────────────────────────────────
+
+describe('clearLiveSyncBus', () => {
+  it('clears all registered pulls', () => {
+    const pull = vi.fn();
+    registerPull('spaces/sp-1/objects/_index', pull);
+    clearLiveSyncBus();
+    expect(dispatchDocChange('spaces/sp-1/objects/_index')).toBe(false);
+  });
+
+  it('resets SSE health to false', () => {
+    emitSseStatus(true);
+    clearLiveSyncBus();
+    const cb = vi.fn();
+    onSseStatus(cb);
+    expect(cb).toHaveBeenCalledWith(false);
+  });
+
+  it('leaves status listeners intact (they self-unsub on unmount)', () => {
+    const cb = vi.fn();
+    onSseStatus(cb);
+    clearLiveSyncBus();
+    emitSseStatus(true);
+    expect(cb).toHaveBeenCalledWith(true); // still fires
+  });
+});