@pylonsync/sync 0.3.215 → 0.3.218

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.215",
+  "version": "0.3.218",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -17,6 +17,12 @@ import { LocalStore } from "./local-store";
 import { MutationQueue, type PendingMutation } from "./mutation-queue";
 import { MultiTabOrchestrator } from "./multi-tab-orchestrator";
 import { OpQueue } from "./op-queue";
+import {
+  RoomSubscriptions,
+  type RoomError,
+  type RoomMember,
+  type RoomSubscriber,
+} from "./room-subscriptions";
 import { ServerSubscriptions } from "./server-subscriptions";
 import { SessionResolver } from "./session-resolver";
 import { SubscriptionCoordinator } from "./subscription-coordinator";
@@ -27,6 +33,13 @@ import {
   type TransportKind,
 } from "./transports";
 import { generateClientId, generateId } from "./ids";
+export {
+  RoomSubscriptions,
+  type RoomError,
+  type RoomErrorCode,
+  type RoomMember,
+  type RoomSubscriber,
+} from "./room-subscriptions";
 export { IndexedDBPersistence, persistChange } from "./persistence";
 export {
   buildRequest,
@@ -335,6 +348,27 @@ export class SyncEngine {
    *  serverSubs isn't built until then. */
   private subscriptions!: SubscriptionCoordinator;
 
+  /** Room presence subscriptions. Replaces the per-component
+   *  setInterval(GET /api/rooms/<room>, 5s) polling loop the `useRoom`
+   *  hook used to run for every channel. New server protocol
+   *  (v0.3.214+): the client sends `room-subscribe` / `room-unsubscribe`
+   *  over the existing WS, and the server pushes `room-snapshot` /
+   *  `room-update` whenever membership changes.
+   *
+   *  This engine field is leader-only (followers forward register /
+   *  unregister calls over the multi-tab channel — the leader's
+   *  registry is the single source of truth on the wire). Constructed
+   *  lazily in start() so SSR-only callers don't pay for it. */
+  private rooms!: RoomSubscriptions;
+
+  /** Per-room set of follower tabIds that have forwarded a
+   *  `room-sub-register`. Leader-only. Mirrors `crdtForwarders` in the
+   *  SubscriptionCoordinator — the WS room sub stays alive until both
+   *  the local refcount AND this set are empty. A separate map on the
+   *  engine (instead of inside RoomSubscriptions) because the registry
+   *  is leader-local and forwarder bookkeeping is multi-tab specific. */
+  private roomForwarders: Map<string, Set<string>> = new Map();
+
   /**
    * Listeners notified when the server signals a per-subscriber row
    * revocation (`row-revoked` envelope). Used by `@pylonsync/loro`
@@ -404,6 +438,16 @@ export class SyncEngine {
       isLeader: () => this.isMultiTabLeader,
       broadcastToTabs: (payload) => this.broadcastToTabs(payload),
     });
+    this.rooms = new RoomSubscriptions((msg) => {
+      // Leader: send over the WS. Followers don't open a transport;
+      // the leader-side WS is the only path to the server.
+      if (!this.isMultiTabLeader) return false;
+      if (this.transport?.isOpen()) {
+        this.transport.send(msg);
+        return true;
+      }
+      return false;
+    });
     // When multi-tab coordination is explicitly disabled, this engine
     // is always its own sole leader — even before start(). Tests that
     // construct an engine and call reconcile()/pull() directly without
@@ -746,14 +790,108 @@ export class SyncEngine {
           }
         }
       },
-      onPeerLeft: (_tabId: string) => {
-        // Orchestrator already scrubbed subscription state for the
-        // departed tab. The engine has no additional cleanup, but the
-        // hook exists for future needs (e.g., per-peer presence).
+      onPeerLeft: (tabId: string) => {
+        // Orchestrator already scrubbed CRDT / reactive sub state for
+        // the departed tab. Engine cleans up room forwarder sets —
+        // a follower that crashed without sending `room-sub-unregister`
+        // would otherwise keep the leader's hold (and therefore the WS
+        // sub) alive for a room nobody actually wants.
+        if (!this.isMultiTabLeader) return;
+        for (const [room, set] of [...this.roomForwarders]) {
+          if (!set.delete(tabId)) continue;
+          if (set.size === 0) {
+            this.roomForwarders.delete(room);
+            const release = this.leaderForwarderHolds.get(room);
+            if (release) {
+              this.leaderForwarderHolds.delete(room);
+              release();
+            }
+          }
+        }
+      },
+      onRoomSubRegister: (roomId: string, fromTabId: string) => {
+        let set = this.roomForwarders.get(roomId);
+        if (!set) {
+          set = new Set();
+          this.roomForwarders.set(roomId, set);
+        }
+        const wasFirst = set.size === 0;
+        set.add(fromTabId);
+        // First forwarder for this room: acquire a leader-internal
+        // hold on the registry so the WS sub stays alive as long as
+        // any tab (leader or follower) still cares. The hold is a
+        // refcount increment with a noop callback — it doesn't fire
+        // on snapshots / updates (the leader's own subscribers, if
+        // any, get the pulse; the forwarded tab gets the snapshot via
+        // the `room-fanout-*` channel). Without this hold, a leader
+        // with no local subscribers would never enter the registry
+        // and inbound `room-snapshot` for forwarded rooms would drop
+        // on the floor.
+        if (wasFirst) {
+          const noop: RoomSubscriber = () => {};
+          const release = this.rooms.register(roomId, noop);
+          this.leaderForwarderHolds.set(roomId, release);
+        }
+      },
+      onRoomSubUnregister: (roomId: string, fromTabId: string) => {
+        const set = this.roomForwarders.get(roomId);
+        if (!set) return;
+        set.delete(fromTabId);
+        if (set.size > 0) return;
+        this.roomForwarders.delete(roomId);
+        // Release the leader-internal hold IF no local subscriber on
+        // this tab cares either. The registry's refcount will then
+        // drop to zero and `room-unsubscribe` ships.
+        const release = this.leaderForwarderHolds.get(roomId);
+        if (release) {
+          this.leaderForwarderHolds.delete(roomId);
+          release();
+        }
+      },
+      onRoomFanoutSnapshot: (roomId: string, members: unknown) => {
+        if (Array.isArray(members)) {
+          this.rooms.applySnapshot(roomId, members as RoomMember[]);
+        }
+      },
+      onRoomFanoutUpdate: (
+        roomId: string,
+        action: "join" | "leave" | "presence" | "broadcast",
+        member: unknown,
+        data: unknown,
+      ) => {
+        this.rooms.applyUpdate(
+          roomId,
+          action,
+          (member ?? undefined) as RoomMember | undefined,
+          data,
+        );
+      },
+      onRoomFanoutError: (roomId: string, error: unknown) => {
+        const err = (error ?? { code: "UNKNOWN" }) as RoomError;
+        this.rooms.applyError(roomId, err);
+      },
+      onReplayRoomSubs: () => {
+        // Follower path: re-broadcast `room-sub-register` for every
+        // room we still care about. New leader rebuilds its forwarder
+        // set and resends `room-subscribe` on its WS.
+        if (this.isMultiTabLeader) return;
+        for (const roomId of this.rooms.roomIds()) {
+          this.broadcastToTabs({
+            type: "room-sub-register",
+            room: roomId,
+          });
+        }
       },
     };
   }
 
+  /** Leader-side hold tokens for room subs forwarded by followers. The
+   *  leader subscribes via its own registry with a no-op callback so
+   *  the registry's first-add gate ships `room-subscribe` exactly
+   *  once; the release tokens here let us undo that hold when the
+   *  last follower stops caring. */
+  private leaderForwarderHolds: Map<string, () => void> = new Map();
+
   /** Seed serverSubs with every subscription this tab currently wants.
    *  Called from both the initial-leader path (subscribes that
    *  happened before start() took the follower branch and broadcast
@@ -2158,6 +2296,126 @@ export class SyncEngine {
     this.transport?.send(msg);
   }
 
+  // -----------------------------------------------------------------------
+  // Room presence subscriptions
+  //
+  // Replaces the SDK's per-component `setInterval(GET /api/rooms/<room>,
+  // 5s)` polling loop. Wire shape (server v0.3.214+):
+  //
+  //   client → server:
+  //     { type: "room-subscribe",   room: "channel:foo" }
+  //     { type: "room-unsubscribe", room: "channel:foo" }
+  //   server → client:
+  //     { type: "room-snapshot", room, members: [...] }
+  //     { type: "room-update",   room, action: "join"|"leave"|"presence"|"broadcast",
+  //                                          member?, data? }
+  //     { type: "error", code: "NOT_IN_ROOM", room }   // server gate
+  //
+  // The actual `POST /api/rooms/join` still happens over HTTP (it carries
+  // initial presence + identity, returns the snapshot). This API only
+  // moves the "stay subscribed to membership deltas" loop off polling
+  // and onto the WS push channel. setPresence + broadcast also stay on
+  // HTTP for now — the WS-RPC envelope for those lands in v0.3.217.
+  // -----------------------------------------------------------------------
+
+  /**
+   * Subscribe to a room's membership over WebSocket. The callback fires
+   * whenever the room's `members` list OR `error` state changes — read
+   * the current snapshot via `getRoomMembers(roomId)` and the latest
+   * error via `getRoomError(roomId)` inside the callback.
+   *
+   * Refcounted: multiple subscribers for the same `roomId` share one
+   * `room-subscribe` on the wire. Returns an unsubscribe function;
+   * the last unsubscribe ships `room-unsubscribe`.
+   *
+   * Follower tabs forward the register / unregister over the multi-tab
+   * channel so the leader's WS carries one subscribe per room across
+   * the whole origin. Inbound snapshot / update / error envelopes land
+   * on the leader's WS and the leader fans them out cross-tab so each
+   * follower's local registry routes to its own subscribers.
+   *
+   * Idempotent w.r.t. wire frames: a re-subscribe with no intervening
+   * full unsubscribe doesn't re-send `room-subscribe`. ServerSubscriptions-
+   * style replay on reconnect is built in — the registry resends
+   * `room-subscribe` for every active room on WS reopen.
+   */
+  subscribeRoom(roomId: string, callback: RoomSubscriber): () => void {
+    if (this.isMultiTabLeader) {
+      // Leader path: register against the local registry which owns
+      // the wire. If a follower had already forwarded this room, the
+      // WS sub is already alive — `register()` short-circuits the
+      // re-send via the registry's first-add gate.
+      return this.rooms.register(roomId, callback);
+    }
+    // Follower path: register locally for callback routing, then ask
+    // the leader to subscribe on our behalf (only on first local
+    // subscriber for the room — multiple mounts in the same follower
+    // tab share one `room-sub-register`, mirroring the leader-side
+    // ServerSubscriptions first-add gate). The leader echoes snapshots
+    // / updates / errors back over the broadcast channel and our local
+    // registry's notify() fires our callback.
+    const hadRoomBefore = this.rooms.has(roomId);
+    const unsubscribe = this.rooms.register(roomId, callback);
+    if (!hadRoomBefore) {
+      this.broadcastToTabs({
+        type: "room-sub-register",
+        room: roomId,
+      });
+    }
+    return () => {
+      unsubscribe();
+      // If this was the LAST subscriber on this tab for the room,
+      // tell the leader so it can drop us from the forwarder set.
+      if (!this.rooms.has(roomId)) {
+        this.broadcastToTabs({
+          type: "room-sub-unregister",
+          room: roomId,
+        });
+      }
+    };
+  }
+
+  /** Force-unsubscribe every local subscriber of a room and ship a
+   *  `room-unsubscribe`. Used by the `useRoom` hook's manual `leave()`
+   *  action so a deliberate exit propagates to the server immediately. */
+  unsubscribeRoom(roomId: string): void {
+    this.rooms.unregisterRoom(roomId);
+    if (!this.isMultiTabLeader) {
+      this.broadcastToTabs({
+        type: "room-sub-unregister",
+        room: roomId,
+      });
+    }
+  }
+
+  /** Read the current cached members snapshot for `roomId`. Returns
+   *  `null` when no snapshot has landed yet (distinct from `[]` for
+   *  an empty room). */
+  getRoomMembers(roomId: string): RoomMember[] | null {
+    return this.rooms?.members(roomId) ?? null;
+  }
+
+  /** Read the latest error for `roomId` (e.g. NOT_IN_ROOM). null when
+   *  none. */
+  getRoomError(roomId: string): RoomError | null {
+    return this.rooms?.error(roomId) ?? null;
+  }
+
+  /** Active transport kind. Used by the `useRoom` hook to decide
+   *  between WS push and HTTP polling fallback — only the WS transport
+   *  supports the room-subscribe push protocol; SSE and polling fall
+   *  back to the legacy 5s GET /api/rooms/<room>. */
+  getActiveTransportType(): TransportType {
+    return this.transportKind();
+  }
+
+  /** True when the active transport is a WebSocket AND the socket is
+   *  currently open. The `useRoom` hook gates its WS-push path on this
+   *  — when false, fall back to polling. */
+  isWebSocketConnected(): boolean {
+    return this.transportKind() === "websocket" && this.connected;
+  }
+
   /** Resolved transport kind, with the websocket default applied. */
   private transportKind(): TransportKind {
     return this.config.transport ?? "websocket";
@@ -2188,6 +2446,12 @@ export class SyncEngine {
         // so without this resync the subscriber's first event would
         // never arrive.
         this.serverSubs.replay();
+        // Room subscriptions live in their own registry (not under
+        // serverSubs) because they carry per-room state (members
+        // snapshot, error). Replay them on the same beat so the
+        // server starts pushing room-snapshot/room-update again for
+        // every room the user is still subscribed to.
+        this.rooms.replay();
         // Pull-on-open catches every event broadcast in the gap
         // between the prior pull() returning and the socket actually
         // opening. Reconcile fires after the pull since pull is the
@@ -2286,6 +2550,77 @@ export class SyncEngine {
       return;
     }
 
+    // Room push: snapshot / update / error envelopes from the WS.
+    // Leader receives them on its socket and routes through the local
+    // registry; if any follower forwarded a sub for the room, fan the
+    // envelope out cross-tab so follower-local registries pick up the
+    // same state. The followers receive `room-fanout-*` envelopes
+    // through the orchestrator and apply them to their own registries.
+    if (msg.type === "room-snapshot" && typeof msg.room === "string") {
+      const room = msg.room;
+      const members = Array.isArray(msg.members)
+        ? (msg.members as RoomMember[])
+        : [];
+      this.rooms.applySnapshot(room, members);
+      if ((this.roomForwarders.get(room)?.size ?? 0) > 0) {
+        this.broadcastToTabs({
+          type: "room-fanout-snapshot",
+          room,
+          members,
+        });
+      }
+      return;
+    }
+    if (msg.type === "room-update" && typeof msg.room === "string") {
+      const room = msg.room;
+      const action = msg.action as
+        | "join"
+        | "leave"
+        | "presence"
+        | "broadcast"
+        | undefined;
+      if (!action) return;
+      const member = (msg.member as RoomMember | undefined) ?? undefined;
+      const data = msg.data;
+      this.rooms.applyUpdate(room, action, member, data);
+      if ((this.roomForwarders.get(room)?.size ?? 0) > 0) {
+        this.broadcastToTabs({
+          type: "room-fanout-update",
+          room,
+          action,
+          member,
+          data,
+        });
+      }
+      return;
+    }
+    if (
+      msg.type === "error" &&
+      typeof msg.room === "string" &&
+      typeof msg.code === "string"
+    ) {
+      // Server-side gate failure on a room subscribe. Surface to the
+      // hook via the registry so the React side can render an error
+      // state. Server only emits this in the `room-subscribe` reject
+      // path right now, but the dispatch is keyed by `code` so future
+      // error codes (rate-limited, room-full, etc.) route here too.
+      const room = msg.room;
+      const code = msg.code === "NOT_IN_ROOM" ? "NOT_IN_ROOM" : "UNKNOWN";
+      const error: RoomError = {
+        code,
+        message: typeof msg.message === "string" ? msg.message : undefined,
+      };
+      this.rooms.applyError(room, error);
+      if ((this.roomForwarders.get(room)?.size ?? 0) > 0) {
+        this.broadcastToTabs({
+          type: "room-fanout-error",
+          room,
+          error,
+        });
+      }
+      return;
+    }
+
     // Reactive query push: the server-side ReactiveRegistry re-ran a
     // subscribed handler and the result hash changed. Route to the
     // local handler if we own the subscription AND forward to follower

package/src/multi-tab-orchestrator.ts

@@ -87,6 +87,31 @@ export interface MultiTabOrchestratorHooks {
   /** A peer tab disappeared (broker observed `bye`). Engine and
    *  SubscriptionCoordinator both clean up state for the departed tab. */
   onPeerLeft(tabId: string): void;
+
+  /** Follower → leader: a follower wants to subscribe to a room.
+   *  Leader-only. Engine increments the per-room forwarder set and
+   *  sends `room-subscribe` to the server if no one else owned it. */
+  onRoomSubRegister?(roomId: string, fromTabId: string): void;
+  /** Follower → leader: a follower's last room subscriber unmounted.
+   *  Leader-only. Engine decrements the forwarder set and sends
+   *  `room-unsubscribe` when both the local refcount and the forwarder
+   *  set are empty. */
+  onRoomSubUnregister?(roomId: string, fromTabId: string): void;
+  /** Leader → followers: a room-snapshot landed on the WS. Followers
+   *  apply it to their local room registry so their subscribers fire. */
+  onRoomFanoutSnapshot?(roomId: string, members: unknown): void;
+  /** Leader → followers: a room-update landed. */
+  onRoomFanoutUpdate?(
+    roomId: string,
+    action: "join" | "leave" | "presence" | "broadcast",
+    member: unknown,
+    data: unknown,
+  ): void;
+  /** Leader → followers: the server rejected a room-subscribe. */
+  onRoomFanoutError?(roomId: string, error: unknown): void;
+  /** New leader → followers: re-forward your locally-wanted room subs.
+   *  Triggered alongside CRDT/reactive replay after a leader change. */
+  onReplayRoomSubs?(): void;
 }
 
 export interface MultiTabOrchestratorConfig {
@@ -359,6 +384,61 @@ export class MultiTabOrchestrator {
         // already has the bundle.
         if (this._isLeader) return;
         this.subscriptions.replayForwardedSubs();
+        // Followers also re-forward their active room subscriptions
+        // so the new leader can rebuild its forwarder sets and resend
+        // `room-subscribe` on the WS.
+        this.hooks.onReplayRoomSubs?.();
+        break;
+      }
+      case "room-sub-register": {
+        // Follower → leader. Leaders only — a follower receiving this
+        // (own broadcast echo, or stale leader transition) ignores.
+        if (!this._isLeader) return;
+        const room = msg.room as string | undefined;
+        if (typeof room === "string") {
+          this.hooks.onRoomSubRegister?.(room, fromTabId);
+        }
+        break;
+      }
+      case "room-sub-unregister": {
+        if (!this._isLeader) return;
+        const room = msg.room as string | undefined;
+        if (typeof room === "string") {
+          this.hooks.onRoomSubUnregister?.(room, fromTabId);
+        }
+        break;
+      }
+      case "room-fanout-snapshot": {
+        // Leader → follower. Leader ignores its own echo.
+        if (this._isLeader) return;
+        const room = msg.room as string | undefined;
+        const members = msg.members;
+        if (typeof room === "string") {
+          this.hooks.onRoomFanoutSnapshot?.(room, members);
+        }
+        break;
+      }
+      case "room-fanout-update": {
+        if (this._isLeader) return;
+        const room = msg.room as string | undefined;
+        const action = msg.action as
+          | "join"
+          | "leave"
+          | "presence"
+          | "broadcast"
+          | undefined;
+        if (typeof room === "string" && action) {
+          this.hooks.onRoomFanoutUpdate?.(room, action, msg.member, msg.data);
+        }
+        break;
+      }
+      case "room-fanout-error": {
+        if (this._isLeader) return;
+        const room = msg.room as string | undefined;
+        const error = msg.error;
+        if (typeof room === "string") {
+          this.hooks.onRoomFanoutError?.(room, error);
+        }
         break;
       }
     }

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);
+      }
+    }
+  }
+}

package/src/test-harness/env.ts

@@ -62,6 +62,11 @@ export interface CreateTestEnvOptions {
    *  "poll" to disable the WS-onopen reconcile race in scenarios
    *  that only want to pin the in-start pipeline. */
   transport?: "websocket" | "poll" | "sse";
+  /** Base delay (ms) for WS reconnect backoff. The default value used
+   *  inside the harness (`undefined` → 1000) introduces seconds of
+   *  wall-clock waiting on every reconnect scenario; pass a small
+   *  value when the test specifically exercises the reconnect path. */
+  reconnectDelay?: number;
 }
 
 export interface TestEnv {
@@ -116,6 +121,7 @@ export function createTestEnv(opts: CreateTestEnvOptions = {}): TestEnv {
     persist: false,
     storage,
     transport: opts.transport ?? "websocket",
+    reconnectDelay: opts.reconnectDelay,
     // Tight timings so scenarios don't have to sleep seconds. The
     // engine's reconcile debounce is also relaxed so back-to-back
     // visibility-change triggers don't get coalesced away in tests.

package/src/test-harness/transport.ts

@@ -19,6 +19,10 @@ export interface TransportHandle {
   fetchCount: () => number;
   /** Number of WS connections opened so far. */
   wsConnectCount: () => number;
+  /** Close the most-recently-opened mock WS so the engine sees a
+   *  disconnect and schedules reconnect via its backoff. Returns
+   *  true if a socket was actually closed, false otherwise. */
+  closeLatestWs: () => boolean;
   /** Tear down the global stubs. */
   restore: () => void;
 }
@@ -33,6 +37,12 @@ export function installTransport(server: TestServer): TransportHandle {
   let token: string | undefined;
   let fetchCount = 0;
   let wsConnectCount = 0;
+  // Track open mock sockets so a test that needs to simulate a
+  // server-side disconnect (cluster bounce, autostop) can grab the
+  // latest connection and close it. The engine's reconnect loop
+  // builds a fresh MockWebSocket on the next attempt; each shows up
+  // here in order so the list maps 1:1 to actual connect attempts.
+  const openSockets: MockWebSocket[] = [];
 
   const originalFetch = globalThis.fetch;
   const originalWS = (globalThis as { WebSocket?: unknown }).WebSocket;
@@ -87,6 +97,7 @@ export function installTransport(server: TestServer): TransportHandle {
       super();
       this.url = url;
       wsConnectCount += 1;
+      openSockets.push(this);
       // The engine encodes the token as `bearer.<percent-encoded>` in
       // the WS subprotocol when one is set. Decode it so the harness
       // can route this connection to the right subscriber bucket
@@ -144,6 +155,18 @@ export function installTransport(server: TestServer): TransportHandle {
     },
     fetchCount: () => fetchCount,
     wsConnectCount: () => wsConnectCount,
+    closeLatestWs: () => {
+      // Walk back from the most recent socket to find one that's
+      // still open. Older closed sockets get skipped silently.
+      for (let i = openSockets.length - 1; i >= 0; i--) {
+        const s = openSockets[i];
+        if (s.readyState !== 3) {
+          s.close();
+          return true;
+        }
+      }
+      return false;
+    },
     restore: () => {
       globalThis.fetch = originalFetch;
       if (originalWS) {