@pylonsync/react 0.3.213 → 0.3.216

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.213",
+  "version": "0.3.216",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,8 +12,8 @@
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.213",
-    "@pylonsync/sync": "0.3.213"
+    "@pylonsync/sdk": "0.3.216",
+    "@pylonsync/sync": "0.3.216"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/db.ts

@@ -75,7 +75,11 @@ export function init(config?: Partial<SyncEngineConfig> & { baseUrl?: string })
   });
 }
 
-function getSync(): SyncEngine {
+/** Module-internal accessor for the global sync engine. Exported so
+ *  hooks living outside this file (e.g. `useRoom`) can share the same
+ *  engine instance and benefit from the same lazy-start / lazy-init
+ *  semantics — without re-implementing the resolution rules. */
+export function getSync(): SyncEngine {
   if (!_sync) {
     // Lazy fallback for callers that never invoked init(). Same
     // resolution rules as init: browser → window.location.origin,

package/src/useRoom.push.test.ts

@@ -0,0 +1,360 @@
+// useRoom — WebSocket push path coverage.
+//
+// The legacy polling-only path is covered in `useRoom.test.ts`; this
+// file focuses on the v0.3.216 push protocol integration:
+//
+//   - WS connected + engine wired in → registry attaches to
+//     engine.subscribeRoom AND does NOT start a polling interval
+//   - inbound room-snapshot via the engine flows through to subscriber
+//     callbacks
+//   - inbound room-update action:join updates peers in the registry
+//   - WS not connected → polling fallback fires (existing behaviour
+//     preserved when the engine reports the WS down)
+//   - StrictMode double-mount with WS → still one engine subscription
+//
+// We drive the registry directly via `__roomRegistryInternals` and feed
+// in a controllable fake engine — no React renderer involved, no real
+// network. The fake engine matches the surface the hook actually
+// consumes (subscribeRoom, getRoomMembers, getRoomError,
+// isWebSocketConnected, connectionStatus, store.subscribe).
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { __roomRegistryInternals } from "./useRoom";
+
+// --- fetch stub (mirrors useRoom.test.ts) ------------------------------
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+}
+
+let recorded: RecordedRequest[];
+let originalFetch: typeof globalThis.fetch;
+
+function installFetchStub(): void {
+  recorded = [];
+  originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    const method = (init?.method ?? "GET").toUpperCase();
+    recorded.push({ url, method });
+    return new Response(JSON.stringify({ snapshot: { peers: [] }, members: [] }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as typeof fetch;
+}
+
+function restoreFetch(): void {
+  globalThis.fetch = originalFetch;
+}
+
+function isHeartbeat(r: RecordedRequest): boolean {
+  return r.method === "GET" && /\/api\/rooms\/[^/]+$/.test(r.url);
+}
+
+// --- fake engine -------------------------------------------------------
+
+interface FakeRoomEntry {
+  callbacks: Set<() => void>;
+  members: Array<{ user_id: string; joined_at: string; data?: any }> | null;
+  error: { code: string; message?: string } | null;
+}
+
+interface FakeEngine {
+  // Surface that useRoom actually pokes:
+  subscribeRoom: (roomId: string, cb: () => void) => () => void;
+  getRoomMembers: (roomId: string) =>
+    | Array<{ user_id: string; joined_at: string; data?: any }>
+    | null;
+  getRoomError: (roomId: string) => { code: string; message?: string } | null;
+  isWebSocketConnected: () => boolean;
+  connectionStatus: () => string;
+  // The store.subscribe surface — useRoom subscribes to connection-status
+  // changes via it.
+  store: {
+    subscribe: (fn: () => void) => () => void;
+  };
+
+  // Test helpers — not on the real engine.
+  _wsOpen: boolean;
+  _statusListeners: Set<() => void>;
+  _rooms: Map<string, FakeRoomEntry>;
+  _subscribeCalls: string[];
+  _unsubscribeCalls: string[];
+  setWsConnected(open: boolean): void;
+  pushSnapshot(roomId: string, members: any[]): void;
+  pushUpdate(
+    roomId: string,
+    action: "join" | "leave" | "presence" | "broadcast",
+    member?: any,
+  ): void;
+  pushError(roomId: string, code: string, message?: string): void;
+}
+
+function makeFakeEngine(): FakeEngine {
+  const engine: FakeEngine = {
+    _wsOpen: true,
+    _statusListeners: new Set(),
+    _rooms: new Map(),
+    _subscribeCalls: [],
+    _unsubscribeCalls: [],
+
+    isWebSocketConnected: () => engine._wsOpen,
+    connectionStatus: () => (engine._wsOpen ? "connected" : "reconnecting"),
+    store: {
+      subscribe: (fn) => {
+        engine._statusListeners.add(fn);
+        return () => engine._statusListeners.delete(fn);
+      },
+    },
+    subscribeRoom: (roomId, cb) => {
+      engine._subscribeCalls.push(roomId);
+      let entry = engine._rooms.get(roomId);
+      if (!entry) {
+        entry = { callbacks: new Set(), members: null, error: null };
+        engine._rooms.set(roomId, entry);
+      }
+      entry.callbacks.add(cb);
+      // Fire one tick if there's already cached state (registry late-
+      // subscriber path).
+      if (entry.members !== null || entry.error !== null) cb();
+      return () => {
+        const e = engine._rooms.get(roomId);
+        if (!e) return;
+        e.callbacks.delete(cb);
+        if (e.callbacks.size === 0) {
+          engine._rooms.delete(roomId);
+          engine._unsubscribeCalls.push(roomId);
+        }
+      };
+    },
+    getRoomMembers: (roomId) => engine._rooms.get(roomId)?.members ?? null,
+    getRoomError: (roomId) => engine._rooms.get(roomId)?.error ?? null,
+
+    setWsConnected: (open) => {
+      engine._wsOpen = open;
+      for (const fn of engine._statusListeners) fn();
+    },
+    pushSnapshot: (roomId, members) => {
+      const entry = engine._rooms.get(roomId);
+      if (!entry) return;
+      entry.members = members;
+      entry.error = null;
+      for (const cb of entry.callbacks) cb();
+    },
+    pushUpdate: (roomId, action, member) => {
+      const entry = engine._rooms.get(roomId);
+      if (!entry) return;
+      if (entry.members === null) entry.members = [];
+      if (action === "join" && member) {
+        const filtered = entry.members.filter(
+          (m) => m.user_id !== member.user_id,
+        );
+        filtered.push(member);
+        entry.members = filtered;
+      } else if (action === "leave" && member) {
+        entry.members = entry.members.filter(
+          (m) => m.user_id !== member.user_id,
+        );
+      }
+      for (const cb of entry.callbacks) cb();
+    },
+    pushError: (roomId, code, message) => {
+      const entry = engine._rooms.get(roomId);
+      if (!entry) return;
+      entry.error = { code, message };
+      for (const cb of entry.callbacks) cb();
+    },
+  };
+  return engine;
+}
+
+// --- harness -----------------------------------------------------------
+
+const BASE = "http://stub.invalid";
+const ROOM = "channel:foo";
+const USER = "user-1";
+const TOKEN = "tok-1";
+
+async function flush(ms = 5): Promise<void> {
+  for (let i = 0; i < 5; i++) await Promise.resolve();
+  if (ms > 0) await new Promise((res) => setTimeout(res, ms));
+  for (let i = 0; i < 5; i++) await Promise.resolve();
+}
+
+beforeEach(() => {
+  installFetchStub();
+  __roomRegistryInternals.reset();
+});
+
+afterEach(() => {
+  __roomRegistryInternals.reset();
+  restoreFetch();
+});
+
+// --- tests -------------------------------------------------------------
+
+describe("useRoom WS push path", () => {
+  test("WS connected + engine wired → subscribeRoom called, no polling interval", async () => {
+    const engine = makeFakeEngine();
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      25, // would tick every 25ms IF polling were active
+      engine as any,
+    );
+    expect(engine._subscribeCalls).toEqual([ROOM]);
+    expect(__roomRegistryInternals.isWsAttached(room)).toBe(true);
+    expect(__roomRegistryInternals.isPolling(room)).toBe(false);
+
+    // Wait through what WOULD have been multiple polling ticks. No
+    // GET /api/rooms/<room> should ever land.
+    await flush(80);
+    expect(recorded.filter(isHeartbeat).length).toBe(0);
+
+    // Engine pushes a snapshot — the hook's local cache should reflect
+    // it once the registry's pulse runs.
+    engine.pushSnapshot(ROOM, [
+      { user_id: "alice", joined_at: "t1" },
+      { user_id: USER, joined_at: "t2" },
+    ]);
+    await flush();
+    // The registry filters out the current user → only alice should
+    // remain.
+    expect(room.peers.map((p) => p.user_id)).toEqual(["alice"]);
+  });
+
+  test("inbound room-update action:join updates peers", async () => {
+    const engine = makeFakeEngine();
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    // Let the HTTP join settle first so its (empty) snapshot doesn't
+    // race the WS-pushed members. In production the WS snapshot
+    // typically lands shortly AFTER the join HTTP response — this
+    // ordering matches that.
+    await flush();
+    engine.pushSnapshot(ROOM, []);
+    engine.pushUpdate(ROOM, "join", { user_id: "bob", joined_at: "t3" });
+    await flush();
+    expect(room.peers.map((p) => p.user_id)).toEqual(["bob"]);
+  });
+
+  test("server pushes NOT_IN_ROOM error → surfaces via room.error, isConnected false, no retry", async () => {
+    const engine = makeFakeEngine();
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    // Let the HTTP join settle first so its success doesn't clobber
+    // the WS-pushed error state.
+    await flush();
+    engine.pushError(ROOM, "NOT_IN_ROOM", "not a member");
+    await flush();
+    expect(typeof room.error).toBe("string");
+    expect(room.error ?? "").toContain("not a member");
+    expect(room.isConnected).toBe(false);
+    // Snapshot-timeout fallback should NOT have engaged (error path
+    // cancels the backwards-compat timer).
+    await flush(80);
+    expect(__roomRegistryInternals.isPolling(room)).toBe(false);
+  });
+
+  test("WS down → polling fallback fires; reconnect promotes back to push", async () => {
+    const engine = makeFakeEngine();
+    engine.setWsConnected(false);
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      25,
+      engine as any,
+    );
+    // No WS — no subscribeRoom call, polling active.
+    expect(engine._subscribeCalls).toEqual([]);
+    expect(__roomRegistryInternals.isPolling(room)).toBe(true);
+
+    await flush(80);
+    expect(recorded.filter(isHeartbeat).length).toBeGreaterThan(0);
+
+    // Flip to connected → registry promotes to push, polling stops.
+    engine.setWsConnected(true);
+    await flush();
+    expect(__roomRegistryInternals.isWsAttached(room)).toBe(true);
+    expect(__roomRegistryInternals.isPolling(room)).toBe(false);
+    expect(engine._subscribeCalls).toEqual([ROOM]);
+  });
+
+  test("backwards-compat: WS connected but no snapshot in 2s → fall back to polling", async () => {
+    const engine = makeFakeEngine();
+    // Crucial: engine.subscribeRoom returns successfully but never
+    // pushes a snapshot. That mirrors talking to a pre-v0.3.214 server
+    // which silently drops the room-subscribe frame.
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      25,
+      engine as any,
+    );
+    expect(__roomRegistryInternals.isWsAttached(room)).toBe(true);
+    expect(__roomRegistryInternals.isPolling(room)).toBe(false);
+
+    // The push-snapshot timeout is 2s in the implementation. Wait
+    // long enough for it to fire AND let one polling tick happen.
+    await flush(2_100);
+    expect(__roomRegistryInternals.isWsAttached(room)).toBe(false);
+    expect(__roomRegistryInternals.isPolling(room)).toBe(true);
+    expect(recorded.filter(isHeartbeat).length).toBeGreaterThan(0);
+  });
+
+  test("StrictMode double-mount on WS path: still one engine.subscribeRoom call", async () => {
+    const engine = makeFakeEngine();
+    const r1 = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    const r2 = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    expect(r1).toBe(r2);
+    // Registry dedup → only one acquire path → only one subscribe.
+    expect(engine._subscribeCalls).toEqual([ROOM]);
+    __roomRegistryInternals.release(r1);
+    __roomRegistryInternals.release(r2);
+    await flush(20);
+    // One subscribe, one unsubscribe — no fanout.
+    expect(engine._unsubscribeCalls).toEqual([ROOM]);
+  });
+});

package/src/useRoom.ts

@@ -1,8 +1,20 @@
 "use client";
 
 import { useState, useEffect, useCallback, useRef } from 'react';
-import { pylonFetch } from '@pylonsync/sync';
+import { pylonFetch, type RoomMember, type SyncEngine } from '@pylonsync/sync';
 import { getBaseUrl, getReactStorage, storageKey } from './index';
+import { getSync } from './db';
+
+/** Project an engine RoomMember (data optional) into a RoomPeer (data
+ *  required). The wire frame always carries a `data` slot — empty objects
+ *  are valid — so the normalization is purely a type contract. */
+function memberToPeer(m: RoomMember): RoomPeer {
+  return {
+    user_id: m.user_id,
+    joined_at: m.joined_at,
+    data: m.data ?? {},
+  };
+}
 
 // ---------------------------------------------------------------------------
 // Room types
@@ -26,7 +38,12 @@ export interface UseRoomOptions {
   token?: string;
   /** Initial presence data sent on join. */
   initialPresence?: Record<string, any>;
-  /** How often to poll for peer updates (ms). Defaults to 5 000. */
+  /**
+   * How often (ms) to poll for peer updates WHEN the WebSocket
+   * push channel is unavailable. With a connected WebSocket the SDK
+   * uses `room-subscribe` push and the polling timer never fires.
+   * Defaults to 5_000.
+   */
   heartbeatInterval?: number;
 }
 
@@ -54,7 +71,8 @@ export interface UseRoomReturn {
 // composer, …). Without deduping that explodes into N joins on mount, N
 // leaves on unmount, and N×interval heartbeat polls every tick. This
 // registry collapses all calls with the same identity tuple into a single
-// network footprint: one join, one interval, one leave.
+// network footprint: one join, one interval (polling-fallback only),
+// one leave.
 //
 // Identity key includes everything that would change the network shape:
 // baseUrl + token (different server / auth) + roomId + userId.
@@ -63,9 +81,27 @@ export interface UseRoomReturn {
 // teardown is scheduled on a microtask. If the same hook re-mounts
 // synchronously in the same tick (StrictMode double-mount, fast tab
 // switch, parent re-key), the pending teardown is cancelled and the room
-// stays alive. The existing `joined` race-fix from the in-effect
-// implementation is preserved here too: leave only fires once the
-// original join has actually landed on the server.
+// stays alive. The `joined` race-fix from the in-effect implementation
+// is preserved: leave only fires once the original join has actually
+// landed on the server.
+//
+// WS-push integration (v0.3.216): when the sync engine's transport is
+// websocket AND currently connected, the registry attaches to
+// `engine.subscribeRoom(roomId, cb)` and stops the polling interval.
+// The engine's room registry handles the wire-level refcount
+// independently. When the WS isn't available (SSE transport, polling
+// transport, OR WS not yet connected), the registry runs the legacy 5s
+// polling loop. We re-evaluate on connection-status changes so a tab
+// that mounts while offline polls until the WS comes up, then quietly
+// switches to push.
+
+/** Window (ms) we wait for a `room-snapshot` after sending the first
+ *  `room-subscribe`. If nothing lands by then we assume the server is
+ *  pre-v0.3.214 and doesn't speak the push protocol — fall back to
+ *  polling. Sized generously enough to absorb a slow link + the
+ *  server's RoomManager lookup; short enough that a misconfigured
+ *  setup recovers without the user noticing. */
+const PUSH_SNAPSHOT_TIMEOUT_MS = 2_000;
 
 interface SharedRoom {
   /** Number of live React hooks holding this room. */
@@ -78,7 +114,7 @@ interface SharedRoom {
   error: string | null;
   /** Last presence data the caller pushed via setPresence. */
   presence: Record<string, any>;
-  /** Active heartbeat poll. */
+  /** Active heartbeat poll (only set when polling fallback is active). */
   interval: ReturnType<typeof setInterval> | null;
   /** Pending teardown — set when refcount hit 0 but we haven't actually
    *  fired leave yet, to absorb StrictMode mount/unmount/mount races. */
@@ -91,6 +127,22 @@ interface SharedRoom {
   roomId: string;
   userId: string;
   heartbeatInterval: number;
+  /** Sync engine instance the room is attached to (for WS push).
+   *  `null` when none provided / running in SSR or test harness that
+   *  never invoked init(). */
+  engine: SyncEngine | null;
+  /** Unsubscribe handle returned by engine.subscribeRoom. `null` when
+   *  we're polling. Mutually exclusive with `interval` — exactly one
+   *  is set whenever the room is live. */
+  wsUnsubscribe: (() => void) | null;
+  /** Timer that fires PUSH_SNAPSHOT_TIMEOUT_MS after we send the first
+   *  room-subscribe. If a snapshot lands first we cancel it; if it
+   *  fires we assume the server doesn't speak the push protocol and
+   *  fall back to polling. */
+  pushSnapshotTimer: ReturnType<typeof setTimeout> | null;
+  /** Connection-status unsubscribe — fires whenever the engine's
+   *  transport state changes so we can flip between push and polling. */
+  connectionStatusUnsubscribe: (() => void) | null;
 }
 
 const rooms = new Map<string, SharedRoom>();
@@ -112,6 +164,12 @@ function transportFor(room: SharedRoom) {
   return { baseUrl: room.baseUrl, token: room.token };
 }
 
+function roomKeyFor(room: SharedRoom): string {
+  return roomKey(room.baseUrl, room.roomId, room.userId, room.token);
+}
+
+/** Begin the 5s GET /api/rooms/<room> polling loop. Idempotent — if
+ *  a polling timer is already running, no-op. */
 function startHeartbeat(room: SharedRoom): void {
   if (room.interval) return;
   room.interval = setInterval(async () => {
@@ -133,14 +191,124 @@ function startHeartbeat(room: SharedRoom): void {
   }, room.heartbeatInterval);
 }
 
-function roomKeyFor(room: SharedRoom): string {
-  return roomKey(room.baseUrl, room.roomId, room.userId, room.token);
+/** Stop the polling timer if running. */
+function stopHeartbeat(room: SharedRoom): void {
+  if (room.interval) {
+    clearInterval(room.interval);
+    room.interval = null;
+  }
+}
+
+/** Attach to the engine's WS room subscription. Pulls in the current
+ *  snapshot (or, when one lands, replaces the cached peers). If the
+ *  initial subscribe doesn't surface a snapshot within
+ *  PUSH_SNAPSHOT_TIMEOUT_MS, fall back to polling — that's the
+ *  backwards-compat path for pre-v0.3.214 servers. */
+function startWsPush(room: SharedRoom): void {
+  const engine = room.engine;
+  if (!engine) return;
+  if (room.wsUnsubscribe) return; // already attached
+  stopHeartbeat(room);
+  room.wsUnsubscribe = engine.subscribeRoom(room.roomId, () => {
+    if (!rooms.has(roomKeyFor(room))) return;
+    const members = engine.getRoomMembers(room.roomId);
+    const err = engine.getRoomError(room.roomId);
+    if (err) {
+      // Snapshot landing implies the server speaks the push protocol.
+      // Cancel the backwards-compat timer; we're staying on push.
+      if (room.pushSnapshotTimer) {
+        clearTimeout(room.pushSnapshotTimer);
+        room.pushSnapshotTimer = null;
+      }
+      room.error =
+        err.code === 'NOT_IN_ROOM'
+          ? 'You are not a member of this room.'
+          : (err.message ?? err.code);
+      room.isConnected = false;
+      notify(room);
+      return;
+    }
+    if (members !== null) {
+      if (room.pushSnapshotTimer) {
+        clearTimeout(room.pushSnapshotTimer);
+        room.pushSnapshotTimer = null;
+      }
+      room.peers = members
+        .filter((m) => m.user_id !== room.userId)
+        .map(memberToPeer);
+      room.isConnected = true;
+      room.error = null;
+      notify(room);
+    }
+  });
+  // Cached state inside the engine's registry may already be populated
+  // (we are a late subscriber to an existing engine-level sub). Pull
+  // it once so the hook re-renders immediately without waiting for the
+  // next push.
+  const cachedMembers = engine.getRoomMembers(room.roomId);
+  if (cachedMembers !== null) {
+    room.peers = cachedMembers
+      .filter((m) => m.user_id !== room.userId)
+      .map(memberToPeer);
+    room.isConnected = true;
+    notify(room);
+  } else if (!room.pushSnapshotTimer) {
+    // Arm the backwards-compat timer. If no snapshot lands in 2s, the
+    // server is presumed pre-v0.3.214 and we revert to polling. The
+    // timer is cancelled the moment a real snapshot OR a real error
+    // lands (both paths above clear it).
+    room.pushSnapshotTimer = setTimeout(() => {
+      room.pushSnapshotTimer = null;
+      if (!rooms.has(roomKeyFor(room))) return;
+      // No snapshot — tear down the WS sub and fall back to polling.
+      // The engine's room-unsubscribe ships harmlessly even on old
+      // servers (unknown frames are ignored).
+      if (room.wsUnsubscribe) {
+        room.wsUnsubscribe();
+        room.wsUnsubscribe = null;
+      }
+      startHeartbeat(room);
+    }, PUSH_SNAPSHOT_TIMEOUT_MS);
+  }
+}
+
+/** Detach the engine WS sub if attached. */
+function stopWsPush(room: SharedRoom): void {
+  if (room.wsUnsubscribe) {
+    room.wsUnsubscribe();
+    room.wsUnsubscribe = null;
+  }
+  if (room.pushSnapshotTimer) {
+    clearTimeout(room.pushSnapshotTimer);
+    room.pushSnapshotTimer = null;
+  }
+}
+
+/** Pick the right delivery channel for the room based on the engine's
+ *  current transport state. Called on initial acquire AND whenever the
+ *  engine's connection status changes — a room that started on polling
+ *  promotes to push the moment the WS opens, and vice versa. */
+function evaluateDelivery(room: SharedRoom): void {
+  const engine = room.engine;
+  if (!engine) {
+    // No engine wired in — pure HTTP polling mode. Idempotent.
+    stopWsPush(room);
+    startHeartbeat(room);
+    return;
+  }
+  if (engine.isWebSocketConnected()) {
+    startWsPush(room);
+  } else {
+    stopWsPush(room);
+    startHeartbeat(room);
+  }
 }
 
 function joinRoom(room: SharedRoom): void {
   // Fire-and-forget — the join promise resolves into the shared state
   // and notifies all subscribers. Late subscribers either pick up the
-  // already-resolved snapshot from `room.peers` or the next heartbeat.
+  // already-resolved snapshot from `room.peers` or the next push /
+  // heartbeat.
   pylonFetch<{ snapshot?: { peers?: RoomPeer[] } }>(
     transportFor(room),
     '/api/rooms/join',
@@ -188,6 +356,7 @@ function acquireRoom(
   token: string | undefined,
   initialPresence: Record<string, any>,
   heartbeatInterval: number,
+  engine: SyncEngine | null,
 ): SharedRoom {
   const key = roomKey(baseUrl, roomId, userId, token);
   let room = rooms.get(key);
@@ -217,10 +386,23 @@ function acquireRoom(
     roomId,
     userId,
     heartbeatInterval,
+    engine,
+    wsUnsubscribe: null,
+    pushSnapshotTimer: null,
+    connectionStatusUnsubscribe: null,
   };
   rooms.set(key, room);
   joinRoom(room);
-  startHeartbeat(room);
+  // Watch connection-status so the room flips from polling to push (or
+  // back) as the WS opens / drops. Only useful when an engine is wired
+  // in; without one, the hook is HTTP-only and the status never matters.
+  if (engine) {
+    room.connectionStatusUnsubscribe = subscribeConnectionStatus(engine, () => {
+      const r = rooms.get(roomKeyFor(room!));
+      if (r) evaluateDelivery(r);
+    });
+  }
+  evaluateDelivery(room);
   return room;
 }
 
@@ -240,9 +422,11 @@ function releaseRoom(room: SharedRoom): void {
       room.pendingTeardown = null;
       return;
     }
-    if (room.interval) {
-      clearInterval(room.interval);
-      room.interval = null;
+    stopHeartbeat(room);
+    stopWsPush(room);
+    if (room.connectionStatusUnsubscribe) {
+      room.connectionStatusUnsubscribe();
+      room.connectionStatusUnsubscribe = null;
     }
     rooms.delete(roomKeyFor(room));
     room.pendingTeardown = null;
@@ -250,6 +434,37 @@ function releaseRoom(room: SharedRoom): void {
   }, 0);
 }
 
+/**
+ * Best-effort subscription to the engine's connection-status stream.
+ * The sync engine notifies via `store.notify()` on every status change;
+ * we listen on the LocalStore's subscribe surface and poll the status
+ * inside the callback. Returns an unsubscribe.
+ *
+ * This module deliberately doesn't import `useSyncStatus` (a React
+ * hook) — the registry runs outside React, and the only thing we need
+ * is a notify-on-change pulse. The store's subscribe method gives us
+ * exactly that without pulling in another dep.
+ */
+function subscribeConnectionStatus(
+  engine: SyncEngine,
+  cb: () => void,
+): () => void {
+  // The engine's LocalStore notify() fires on every status flip
+  // (setConnectionStatus calls store.notify). Subscribing to that is
+  // a cheap way to observe transport transitions.
+  const store = (engine as unknown as { store?: { subscribe: (fn: () => void) => () => void } }).store;
+  if (!store?.subscribe) {
+    return () => {};
+  }
+  let lastStatus = engine.connectionStatus();
+  return store.subscribe(() => {
+    const nextStatus = engine.connectionStatus();
+    if (nextStatus === lastStatus) return;
+    lastStatus = nextStatus;
+    cb();
+  });
+}
+
 // Exported for tests — lets the regression test reset registry state
 // between cases so leaked rooms from one test can't bleed into the next,
 // and drive the refcount through the same code path the hook uses.
@@ -257,15 +472,46 @@ export const __roomRegistryInternals = {
   reset(): void {
     for (const room of rooms.values()) {
       if (room.pendingTeardown) clearTimeout(room.pendingTeardown);
-      if (room.interval) clearInterval(room.interval);
+      stopHeartbeat(room);
+      stopWsPush(room);
+      if (room.connectionStatusUnsubscribe) {
+        room.connectionStatusUnsubscribe();
+        room.connectionStatusUnsubscribe = null;
+      }
     }
     rooms.clear();
   },
-  acquire: acquireRoom,
+  acquire(
+    baseUrl: string,
+    roomId: string,
+    userId: string,
+    token: string | undefined,
+    initialPresence: Record<string, any>,
+    heartbeatInterval: number,
+    engine: SyncEngine | null = null,
+  ): SharedRoom {
+    return acquireRoom(
+      baseUrl,
+      roomId,
+      userId,
+      token,
+      initialPresence,
+      heartbeatInterval,
+      engine,
+    );
+  },
   release: releaseRoom,
   size(): number {
     return rooms.size;
   },
+  /** Diagnostic: is this room currently on the WS push path? */
+  isWsAttached(room: SharedRoom): boolean {
+    return room.wsUnsubscribe !== null;
+  },
+  /** Diagnostic: is the polling timer running for this room? */
+  isPolling(room: SharedRoom): boolean {
+    return room.interval !== null;
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -274,12 +520,16 @@ export const __roomRegistryInternals = {
 
 /**
  * Subscribe to a real-time room. Joins on mount, leaves on unmount, and
- * polls for peer updates on a configurable interval.
+ * receives peer updates over the sync engine's WebSocket push channel
+ * (server v0.3.214+). When the WS isn't available (SSE transport, polling
+ * transport, OR WS not yet connected) the hook automatically falls back
+ * to a 5s `GET /api/rooms/<room>` polling loop — same behaviour as
+ * v0.3.213 and earlier.
  *
  * Multiple components calling `useRoom` with the same `(roomId, userId,
- * baseUrl, token)` tuple share a single underlying join + heartbeat —
+ * baseUrl, token)` tuple share a single underlying join + subscription —
  * mounting it from 5 components costs one POST /api/rooms/join, one
- * heartbeat poll, and one POST /api/rooms/leave.
+ * room-subscribe on the wire, and one POST /api/rooms/leave.
  *
  * ```tsx
  * const { peers, isConnected, setPresence, broadcast, leave, error } = useRoom(
@@ -300,6 +550,17 @@ function readStoredToken(): string | undefined {
   return getReactStorage().get(storageKey('token')) ?? undefined;
 }
 
+/** Best-effort engine accessor. SSR / test-harness use-cases that
+ *  never invoked `init()` end up here with a null engine and the
+ *  hook silently runs in HTTP-only polling mode. */
+function tryGetSync(): SyncEngine | null {
+  try {
+    return getSync();
+  } catch {
+    return null;
+  }
+}
+
 export function useRoom(
   roomId: string,
   userId: string,
@@ -328,6 +589,7 @@ export function useRoom(
   const roomRef = useRef<SharedRoom | null>(null);
 
   useEffect(() => {
+    const engine = tryGetSync();
     const room = acquireRoom(
       baseUrl,
       roomId,
@@ -335,6 +597,7 @@ export function useRoom(
       token,
       initialPresence,
       heartbeatInterval,
+      engine,
     );
     roomRef.current = room;