@pylonsync/sync 0.3.213 → 0.3.216

package/src/room-push.test.ts

@@ -0,0 +1,197 @@
+// Integration tests for the engine's WS room subscription path.
+// Exercises subscribeRoom / unsubscribeRoom against the in-process
+// TestServer:
+//   - subscribeRoom emits `room-subscribe` over the WS exactly once,
+//     refcounted across multiple subscribers
+//   - inbound `room-snapshot` populates the local registry + fires
+//     subscriber callbacks
+//   - inbound `room-update` action:join mutates the cached members
+//   - WS reconnect resends `room-subscribe` for every active room
+//   - last unsubscribe emits `room-unsubscribe`
+//   - inbound `error { code: NOT_IN_ROOM, room }` surfaces via the
+//     registry's error slot
+//
+// All harness-level — no real network. The TestServer's `pushToUser`
+// + WS subprotocol bearer threading do the work.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { createTestEnv, type TestEnv } from "./test-harness";
+
+function isRoomSubscribe(msg: unknown, room: string): boolean {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    (msg as Record<string, unknown>).type === "room-subscribe" &&
+    (msg as Record<string, unknown>).room === room
+  );
+}
+
+function isRoomUnsubscribe(msg: unknown, room: string): boolean {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    (msg as Record<string, unknown>).type === "room-unsubscribe" &&
+    (msg as Record<string, unknown>).room === room
+  );
+}
+
+function countWs(env: TestEnv, predicate: (msg: unknown) => boolean): number {
+  return env.server.receivedWsMessages.filter((m) => predicate(m.msg)).length;
+}
+
+describe("engine WS room subscriptions", () => {
+  let env: TestEnv;
+
+  beforeEach(() => {
+    env = createTestEnv();
+  });
+
+  afterEach(async () => {
+    await env.dispose();
+  });
+
+  test("first subscribeRoom emits room-subscribe; second is dedup'd", async () => {
+    env.signIn({ userId: "u1" });
+    await env.start();
+    env.engine.subscribeRoom("channel:foo", () => {});
+    env.engine.subscribeRoom("channel:foo", () => {});
+    await env.flush();
+    expect(countWs(env, (m) => isRoomSubscribe(m, "channel:foo"))).toBe(1);
+  });
+
+  test("inbound room-snapshot fires subscriber callback with members", async () => {
+    env.signIn({ userId: "u1" });
+    await env.start();
+    let callbackCount = 0;
+    env.engine.subscribeRoom("channel:foo", () => {
+      callbackCount += 1;
+    });
+    await env.flush();
+    env.server.pushToUser("u1", {
+      type: "room-snapshot",
+      room: "channel:foo",
+      members: [
+        { user_id: "alice", joined_at: "t0" },
+        { user_id: "bob", joined_at: "t1" },
+      ],
+    });
+    await env.flush();
+    expect(callbackCount).toBeGreaterThanOrEqual(1);
+    const members = env.engine.getRoomMembers("channel:foo");
+    expect(members).toHaveLength(2);
+  });
+
+  test("inbound room-update action:join mutates cached members", async () => {
+    env.signIn({ userId: "u1" });
+    await env.start();
+    env.engine.subscribeRoom("channel:foo", () => {});
+    await env.flush();
+    env.server.pushToUser("u1", {
+      type: "room-snapshot",
+      room: "channel:foo",
+      members: [{ user_id: "alice", joined_at: "t0" }],
+    });
+    env.server.pushToUser("u1", {
+      type: "room-update",
+      room: "channel:foo",
+      action: "join",
+      member: { user_id: "bob", joined_at: "t1" },
+    });
+    await env.flush();
+    const members = env.engine.getRoomMembers("channel:foo");
+    expect(members?.map((m) => m.user_id).sort()).toEqual(["alice", "bob"]);
+  });
+
+  test("last unsubscribeRoom emits room-unsubscribe + clears registry entry", async () => {
+    env.signIn({ userId: "u1" });
+    await env.start();
+    const unsub1 = env.engine.subscribeRoom("channel:foo", () => {});
+    const unsub2 = env.engine.subscribeRoom("channel:foo", () => {});
+    await env.flush();
+    unsub1();
+    expect(countWs(env, (m) => isRoomUnsubscribe(m, "channel:foo"))).toBe(0);
+    unsub2();
+    await env.flush();
+    expect(countWs(env, (m) => isRoomUnsubscribe(m, "channel:foo"))).toBe(1);
+    expect(env.engine.getRoomMembers("channel:foo")).toBeNull();
+  });
+
+  test("inbound error { code: NOT_IN_ROOM } surfaces via getRoomError", async () => {
+    env.signIn({ userId: "u1" });
+    await env.start();
+    let callbackFired = false;
+    env.engine.subscribeRoom("channel:foo", () => {
+      callbackFired = true;
+    });
+    await env.flush();
+    env.server.pushToUser("u1", {
+      type: "error",
+      code: "NOT_IN_ROOM",
+      room: "channel:foo",
+      message: "not a member",
+    });
+    await env.flush();
+    expect(callbackFired).toBe(true);
+    expect(env.engine.getRoomError("channel:foo")).toEqual({
+      code: "NOT_IN_ROOM",
+      message: "not a member",
+    });
+  });
+
+  test("isWebSocketConnected reflects WS open state", async () => {
+    env.signIn({ userId: "u1" });
+    await env.start();
+    expect(env.engine.isWebSocketConnected()).toBe(true);
+    expect(env.engine.getActiveTransportType()).toBe("websocket");
+  });
+
+  test("WS reconnect resends room-subscribe for every active room", async () => {
+    // Tight reconnect budget so the test runs in a couple hundred ms
+    // rather than seconds. Picks a short base delay; the full-jitter
+    // formula caps the first attempt at random(0, 50ms).
+    const reconnectEnv = createTestEnv({ reconnectDelay: 50 });
+    try {
+      reconnectEnv.signIn({ userId: "u1" });
+      await reconnectEnv.start();
+      reconnectEnv.engine.subscribeRoom("channel:a", () => {});
+      reconnectEnv.engine.subscribeRoom("channel:b", () => {});
+      await reconnectEnv.flush();
+      expect(
+        countWs(reconnectEnv, (m) => isRoomSubscribe(m, "channel:a")),
+      ).toBe(1);
+      expect(
+        countWs(reconnectEnv, (m) => isRoomSubscribe(m, "channel:b")),
+      ).toBe(1);
+      // Force the WS to drop. The engine schedules a reconnect via its
+      // backoff, opens a new socket, fires onConnected → rooms.replay().
+      const closed = reconnectEnv.transport.closeLatestWs();
+      expect(closed).toBe(true);
+      await reconnectEnv.flush(200);
+      expect(reconnectEnv.transport.wsConnectCount()).toBeGreaterThanOrEqual(2);
+      // Replay: each active room got a fresh room-subscribe.
+      expect(
+        countWs(reconnectEnv, (m) => isRoomSubscribe(m, "channel:a")),
+      ).toBe(2);
+      expect(
+        countWs(reconnectEnv, (m) => isRoomSubscribe(m, "channel:b")),
+      ).toBe(2);
+    } finally {
+      await reconnectEnv.dispose();
+    }
+  });
+
+  test("StrictMode-style double-subscribe to same room only ships one wire frame", async () => {
+    env.signIn({ userId: "u1" });
+    await env.start();
+    // Simulate StrictMode: mount, mount again, unmount, unmount.
+    const u1 = env.engine.subscribeRoom("channel:foo", () => {});
+    const u2 = env.engine.subscribeRoom("channel:foo", () => {});
+    await env.flush();
+    expect(countWs(env, (m) => isRoomSubscribe(m, "channel:foo"))).toBe(1);
+    u1();
+    u2();
+    await env.flush();
+    expect(countWs(env, (m) => isRoomUnsubscribe(m, "channel:foo"))).toBe(1);
+  });
+});

package/src/room-subscriptions.test.ts

@@ -0,0 +1,189 @@
+// Unit tests for RoomSubscriptions. Pins the contract the engine
+// depends on:
+//   - register/unregister refcount → first add sends room-subscribe,
+//     last remove sends room-unsubscribe
+//   - applySnapshot / applyUpdate / applyError mutate cached state and
+//     pulse subscribers
+//   - replay() resends room-subscribe for every active room (used by
+//     the engine's onConnected hook so reconnect resyncs membership)
+//   - sendWs returning false (no WS) doesn't break refcount semantics
+//
+// The engine integration (multi-tab forwarding, fanout) is covered in
+// the scenarios suite — these tests pin the registry in isolation so
+// regressions surface at the layer they originated.
+
+import { describe, expect, test } from "bun:test";
+
+import { RoomSubscriptions } from "./room-subscriptions";
+
+function makeHarness() {
+  const sent: unknown[] = [];
+  // Default to "ws is open" so the refcount path actually ships
+  // subscribe / unsubscribe frames; individual tests override.
+  let wsOpen = true;
+  const rooms = new RoomSubscriptions((msg) => {
+    sent.push(msg);
+    return wsOpen;
+  });
+  return {
+    rooms,
+    sent,
+    setWsOpen(v: boolean) {
+      wsOpen = v;
+    },
+  };
+}
+
+describe("RoomSubscriptions: refcount + wire frames", () => {
+  test("first register ships room-subscribe; second is a no-op", () => {
+    const h = makeHarness();
+    h.rooms.register("channel:foo", () => {});
+    expect(h.sent).toEqual([{ type: "room-subscribe", room: "channel:foo" }]);
+    h.rooms.register("channel:foo", () => {});
+    expect(h.sent.length).toBe(1); // no second subscribe
+  });
+
+  test("last unregister ships room-unsubscribe; mid-stream calls are no-ops on wire", () => {
+    const h = makeHarness();
+    const unsub1 = h.rooms.register("channel:foo", () => {});
+    const unsub2 = h.rooms.register("channel:foo", () => {});
+    unsub1();
+    expect(h.sent.length).toBe(1); // still just the initial subscribe
+    unsub2();
+    expect(h.sent).toEqual([
+      { type: "room-subscribe", room: "channel:foo" },
+      { type: "room-unsubscribe", room: "channel:foo" },
+    ]);
+  });
+
+  test("unregisterRoom force-tears-down regardless of refcount", () => {
+    const h = makeHarness();
+    h.rooms.register("channel:foo", () => {});
+    h.rooms.register("channel:foo", () => {});
+    h.rooms.unregisterRoom("channel:foo");
+    expect(h.sent).toEqual([
+      { type: "room-subscribe", room: "channel:foo" },
+      { type: "room-unsubscribe", room: "channel:foo" },
+    ]);
+    expect(h.rooms.has("channel:foo")).toBe(false);
+  });
+
+  test("sendWs returning false (WS closed / follower) still refcounts correctly", () => {
+    const h = makeHarness();
+    h.setWsOpen(false);
+    const unsub = h.rooms.register("channel:foo", () => {});
+    // The send happened (registry doesn't care if it landed); it just
+    // didn't reach the wire. Engine's replay() on reconnect handles the
+    // catch-up.
+    expect(h.sent.length).toBe(1);
+    unsub();
+    expect(h.sent.length).toBe(2); // unsubscribe still queued
+  });
+});
+
+describe("RoomSubscriptions: snapshot / update / error", () => {
+  test("applySnapshot stores members and pulses every subscriber", () => {
+    const h = makeHarness();
+    let calls = 0;
+    h.rooms.register("channel:foo", () => {
+      calls += 1;
+    });
+    h.rooms.applySnapshot("channel:foo", [
+      { user_id: "u1", joined_at: "t1" },
+      { user_id: "u2", joined_at: "t2" },
+    ]);
+    expect(h.rooms.members("channel:foo")).toHaveLength(2);
+    expect(calls).toBe(1);
+  });
+
+  test("members() returns null before any snapshot lands", () => {
+    const h = makeHarness();
+    h.rooms.register("channel:foo", () => {});
+    expect(h.rooms.members("channel:foo")).toBeNull();
+  });
+
+  test("applyUpdate join inserts a member; idempotent on duplicate user_id", () => {
+    const h = makeHarness();
+    h.rooms.register("channel:foo", () => {});
+    h.rooms.applySnapshot("channel:foo", []);
+    h.rooms.applyUpdate(
+      "channel:foo",
+      "join",
+      { user_id: "u1", joined_at: "t1" },
+      undefined,
+    );
+    h.rooms.applyUpdate(
+      "channel:foo",
+      "join",
+      { user_id: "u1", joined_at: "t1" },
+      undefined,
+    );
+    expect(h.rooms.members("channel:foo")).toHaveLength(1);
+  });
+
+  test("applyUpdate leave removes the matching user", () => {
+    const h = makeHarness();
+    h.rooms.register("channel:foo", () => {});
+    h.rooms.applySnapshot("channel:foo", [
+      { user_id: "u1", joined_at: "t1" },
+      { user_id: "u2", joined_at: "t2" },
+    ]);
+    h.rooms.applyUpdate(
+      "channel:foo",
+      "leave",
+      { user_id: "u1", joined_at: "t1" },
+      undefined,
+    );
+    expect(h.rooms.members("channel:foo")).toEqual([
+      { user_id: "u2", joined_at: "t2" },
+    ]);
+  });
+
+  test("applyError stores the error code and surfaces via error()", () => {
+    const h = makeHarness();
+    let calls = 0;
+    h.rooms.register("channel:foo", () => {
+      calls += 1;
+    });
+    h.rooms.applyError("channel:foo", { code: "NOT_IN_ROOM" });
+    expect(h.rooms.error("channel:foo")).toEqual({ code: "NOT_IN_ROOM" });
+    expect(calls).toBe(1);
+  });
+
+  test("late register on an already-snapshotted room pulses the new sub immediately", () => {
+    const h = makeHarness();
+    h.rooms.register("channel:foo", () => {});
+    h.rooms.applySnapshot("channel:foo", [
+      { user_id: "u1", joined_at: "t1" },
+    ]);
+    let latePulseCount = 0;
+    h.rooms.register("channel:foo", () => {
+      latePulseCount += 1;
+    });
+    expect(latePulseCount).toBe(1); // fired synchronously
+  });
+});
+
+describe("RoomSubscriptions: replay on reconnect", () => {
+  test("replay() resends room-subscribe for every active room", () => {
+    const h = makeHarness();
+    h.rooms.register("channel:a", () => {});
+    h.rooms.register("channel:b", () => {});
+    h.sent.length = 0;
+    h.rooms.replay();
+    expect(h.sent).toEqual([
+      { type: "room-subscribe", room: "channel:a" },
+      { type: "room-subscribe", room: "channel:b" },
+    ]);
+  });
+
+  test("replay() skips fully-unregistered rooms", () => {
+    const h = makeHarness();
+    const unsub = h.rooms.register("channel:a", () => {});
+    h.rooms.register("channel:b", () => {});
+    unsub();
+    h.sent.length = 0;
+    h.rooms.replay();
+    expect(h.sent).toEqual([{ type: "room-subscribe", room: "channel:b" }]);
+  });
+});

package/src/room-subscriptions.ts

@@ -0,0 +1,301 @@
+// RoomSubscriptions — client-side registry for WS-pushed room membership.
+//
+// The server (>=v0.3.214) accepts `{ type: "room-subscribe", room }` and
+// `{ type: "room-unsubscribe", room }` control frames, and pushes back
+// `room-snapshot` (members list) + `room-update` (join/leave/presence/
+// broadcast deltas). This registry owns the client-side bookkeeping:
+//
+//   - refcount per roomId so N `useRoom` mounts of the same channel
+//     produce exactly one `room-subscribe` on the wire (the first add)
+//     and one `room-unsubscribe` (the last remove). Mirrors the dedup
+//     story `useRoom`'s `__roomRegistryInternals` already enforced at
+//     the React layer — but moved INTO the engine because the WS sub
+//     is the engine's connection, not React's.
+//
+//   - per-room subscriber callbacks. Server pushes are O(rooms), but
+//     each push has to fan out to every component that subscribed to
+//     that room. We notify them all when the snapshot or update lands.
+//
+//   - cached `members` snapshot so a late subscriber (mounting after
+//     the initial snapshot already landed) gets the current state on
+//     `register()` without waiting for the next push.
+//
+//   - replay-on-reconnect. Server clears its per-client room
+//     subscription state on disconnect; on reconnect, we resend a
+//     `room-subscribe` for every roomId that still has subscribers.
+//
+// Why a separate registry from ServerSubscriptions:
+//   ServerSubscriptions is a write-only replay registry — it remembers
+//   the SUBSCRIBE message and re-sends it on reconnect. Rooms need
+//   more than that: per-room state (the members snapshot), per-room
+//   callbacks, and per-room error surfacing. Mixing those concerns
+//   into ServerSubscriptions would dilute its single responsibility.
+//   Both are used together by the engine: ServerSubscriptions handles
+//   the replay primitive; RoomSubscriptions is the consumer that
+//   keys into it for rooms.
+//
+// Multi-tab note: only the leader tab opens a WS, so only the leader
+// runs this registry against a real socket. Follower tabs broadcast
+// `room-sub-register` envelopes to the leader, the leader keeps a
+// per-room follower set so the WS sub stays alive while any tab in
+// the origin still wants it, and inbound `room-snapshot`/`room-update`
+// land on the leader's WS and get fanned out cross-tab so each
+// follower's local registry routes to its own React subscribers.
+// The leader-side fanout / follower-side mirror plumbing lives on
+// the engine + orchestrator; this module is leader-local state.
+
+export interface RoomMember {
+  user_id: string;
+  joined_at: string;
+  data?: Record<string, unknown>;
+}
+
+/** Reason codes the SDK exposes on a room subscription error. */
+export type RoomErrorCode = "NOT_IN_ROOM" | "UNKNOWN";
+
+export interface RoomError {
+  code: RoomErrorCode;
+  message?: string;
+}
+
+/** Callback fired when a room's membership snapshot OR error state
+ *  changes. The same callback receives every transition for the room —
+ *  snapshots overwrite state, updates mutate it, and errors set the
+ *  `error` slot. Subscribers read the latest values via the getters on
+ *  the entry; this fires purely as a "something changed" pulse so
+ *  React hooks can re-render. */
+export type RoomSubscriber = () => void;
+
+interface RoomEntry {
+  roomId: string;
+  /** Current members snapshot (post-snapshot/update). `null` until the
+   *  first snapshot lands — distinct from "empty room" which is `[]`.
+   *  React hooks distinguish loading vs empty using this. */
+  members: RoomMember[] | null;
+  /** Latest error from the server (NOT_IN_ROOM). Cleared when a fresh
+   *  snapshot lands. */
+  error: RoomError | null;
+  /** Number of `register()` calls that haven't been balanced by
+   *  `unregister()`. The first add ships `room-subscribe`; the last
+   *  remove ships `room-unsubscribe`. */
+  refs: number;
+  /** Subscriber callbacks — one per mounted React hook. */
+  subs: Set<RoomSubscriber>;
+}
+
+export class RoomSubscriptions {
+  private readonly rooms: Map<string, RoomEntry> = new Map();
+
+  /** Caller-supplied uplink to the WS. The engine routes through its
+   *  active transport; this module stays transport-agnostic.
+   *  Returns true when the message reached the wire (transport is open),
+   *  false otherwise — RoomSubscriptions uses this to decide whether
+   *  to surface "not connected yet" to the registry's callers.
+   *  No-op transports (followers, no WS yet) return false; the engine
+   *  hides the broadcast/leader split behind this hook. */
+  constructor(private readonly sendWs: (msg: unknown) => boolean) {}
+
+  /** Register a subscriber for `roomId`. First add ships the WS
+   *  `room-subscribe`; subsequent adds just bump the refcount and
+   *  deliver the cached snapshot to the new subscriber's callback.
+   *
+   *  Returns an unsubscribe function that decrements the refcount on
+   *  call. The last unsubscribe ships `room-unsubscribe`, clears the
+   *  entry, and the next register() for the same room is a fresh
+   *  start.
+   *
+   *  Idempotent w.r.t. wire frames: a re-subscribe with no intervening
+   *  full unsubscribe doesn't re-send `room-subscribe` to the server. */
+  register(roomId: string, subscriber: RoomSubscriber): () => void {
+    let entry = this.rooms.get(roomId);
+    const isFirst = !entry;
+    if (!entry) {
+      entry = {
+        roomId,
+        members: null,
+        error: null,
+        refs: 0,
+        subs: new Set(),
+      };
+      this.rooms.set(roomId, entry);
+    }
+    entry.refs += 1;
+    entry.subs.add(subscriber);
+
+    if (isFirst) {
+      // First subscriber — ask the server to start pushing updates.
+      // `sendWs` returns false when the transport isn't open yet (or
+      // we're a follower); that's fine — `replay()` on reconnect /
+      // promotion will re-send the subscribe.
+      this.sendWs({ type: "room-subscribe", room: roomId });
+    } else if (entry.members !== null || entry.error !== null) {
+      // Late subscriber on an already-active room. Fire one tick so
+      // the new callback observes the cached snapshot / error
+      // immediately instead of waiting for the next push.
+      try {
+        subscriber();
+      } catch (err) {
+        console.warn("[sync] room subscriber threw on initial notify:", err);
+      }
+    }
+
+    return () => this.unregisterOne(roomId, subscriber);
+  }
+
+  /** Decrement the refcount for one subscriber. Internal — the
+   *  `register()` returned unsubscribe routes here. Last out ships
+   *  `room-unsubscribe`. */
+  private unregisterOne(roomId: string, subscriber: RoomSubscriber): void {
+    const entry = this.rooms.get(roomId);
+    if (!entry) return;
+    entry.subs.delete(subscriber);
+    entry.refs -= 1;
+    if (entry.refs > 0) return;
+    this.rooms.delete(roomId);
+    this.sendWs({ type: "room-unsubscribe", room: roomId });
+  }
+
+  /** Force a full teardown of one room regardless of refcount. Used by
+   *  the engine's leader-handoff and the hook's manual `leave()` path.
+   *  Notifies every remaining subscriber via the standard pulse (so
+   *  they observe `members === null` and re-render as disconnected). */
+  unregisterRoom(roomId: string): void {
+    const entry = this.rooms.get(roomId);
+    if (!entry) return;
+    this.rooms.delete(roomId);
+    this.sendWs({ type: "room-unsubscribe", room: roomId });
+  }
+
+  /** Snapshot push from the server: full membership for the room.
+   *  Overwrites any cached state, clears any prior error, and pulses
+   *  every subscriber callback. */
+  applySnapshot(roomId: string, members: RoomMember[]): void {
+    const entry = this.rooms.get(roomId);
+    if (!entry) return;
+    entry.members = members;
+    entry.error = null;
+    this.notify(entry);
+  }
+
+  /** Incremental update from the server. `action` mirrors the server's
+   *  RoomEvent variants — join / leave / presence / broadcast. The
+   *  registry mutates the cached `members` snapshot in-place so a
+   *  re-render after the update sees the right shape without waiting
+   *  for the next snapshot. `broadcast` updates don't touch members
+   *  (no peer joined/left) but still fan out to listeners — Future
+   *  work: expose a separate broadcast channel. For now the React
+   *  hook only needs the membership delta. */
+  applyUpdate(
+    roomId: string,
+    action: "join" | "leave" | "presence" | "broadcast",
+    member: RoomMember | undefined,
+    _data: unknown,
+  ): void {
+    const entry = this.rooms.get(roomId);
+    if (!entry) return;
+    // If we haven't received a snapshot yet, seed an empty list so
+    // the in-place mutation paths below have something to mutate.
+    if (entry.members === null) entry.members = [];
+    switch (action) {
+      case "join": {
+        if (!member) break;
+        // Idempotent insert: server may re-send a join on flapping
+        // connections; collapse by user_id.
+        const filtered = entry.members.filter(
+          (m) => m.user_id !== member.user_id,
+        );
+        filtered.push(member);
+        entry.members = filtered;
+        break;
+      }
+      case "leave": {
+        if (!member) break;
+        entry.members = entry.members.filter(
+          (m) => m.user_id !== member.user_id,
+        );
+        break;
+      }
+      case "presence": {
+        if (!member) break;
+        // Swap the matching member's data while preserving join order.
+        entry.members = entry.members.map((m) =>
+          m.user_id === member.user_id ? { ...m, ...member } : m,
+        );
+        break;
+      }
+      case "broadcast": {
+        // No membership delta. Still pulse subscribers so apps that
+        // want to react to broadcast traffic can read it via a future
+        // dedicated callback. The current React hook ignores this.
+        break;
+      }
+    }
+    entry.error = null;
+    this.notify(entry);
+  }
+
+  /** Server pushed `{ type: "error", code, room }` after a subscribe.
+   *  Record the error on the room and pulse subscribers — the React
+   *  hook surfaces it via the `error` return slot. We do NOT
+   *  unregister automatically: the user genuinely isn't in the room
+   *  and the SDK shouldn't retry, but the registry entry stays so
+   *  React unmount still ships a `room-unsubscribe` (server is
+   *  idempotent for unknown subs). */
+  applyError(roomId: string, error: RoomError): void {
+    const entry = this.rooms.get(roomId);
+    if (!entry) return;
+    entry.error = error;
+    this.notify(entry);
+  }
+
+  /** Read the cached snapshot for a room without subscribing. The
+   *  React hook uses this in its initial-state effect so a re-mount
+   *  inside the same registry lifecycle picks up the current members
+   *  on tick zero. Returns `null` when the snapshot hasn't landed
+   *  yet — DISTINCT from `[]` ("empty room"). */
+  members(roomId: string): RoomMember[] | null {
+    return this.rooms.get(roomId)?.members ?? null;
+  }
+
+  /** Latest error for a room (null if none). */
+  error(roomId: string): RoomError | null {
+    return this.rooms.get(roomId)?.error ?? null;
+  }
+
+  /** Is there at least one local subscriber for `roomId`. Used by the
+   *  hook's polling-fallback path to decide whether to keep polling. */
+  has(roomId: string): boolean {
+    return this.rooms.has(roomId);
+  }
+
+  /** Every room currently tracked. Used by `replay()` and by the
+   *  multi-tab seed-on-promotion. */
+  roomIds(): string[] {
+    return Array.from(this.rooms.keys());
+  }
+
+  /** Resend `room-subscribe` for every active room. Called by the
+   *  engine's `onConnected` hook after the WS reopens — the server
+   *  forgets per-client subs across disconnects, so without this
+   *  resync the first push would never arrive. */
+  replay(): void {
+    for (const roomId of this.rooms.keys()) {
+      this.sendWs({ type: "room-subscribe", room: roomId });
+    }
+  }
+
+  /** Test/diagnostics: total active rooms. */
+  size(): number {
+    return this.rooms.size;
+  }
+
+  private notify(entry: RoomEntry): void {
+    for (const cb of entry.subs) {
+      try {
+        cb();
+      } catch (err) {
+        console.warn("[sync] room subscriber threw:", err);
+      }
+    }
+  }
+}