@pylonsync/react 0.21.0 → 0.22.0

package/dist/hooks.d.ts

@@ -19,6 +19,15 @@ export interface QueryOptions {
 export interface UseQueryReturn<T> {
     data: T[];
     loading: boolean;
+    /**
+     * True once the engine has completed a pull against the server in this
+     * session (since the last replica reset). While false, `data` may be a
+     * stale or partial copy loaded from the local cache, or the server is
+     * unreachable. `loading` is false as soon as cached rows exist, so use
+     * `synced` when an incomplete list would mislead (counts, "no results",
+     * billing state).
+     */
+    synced: boolean;
     error: Error | null;
     /** Re-fetch from the server. Rarely needed — data is live. */
     refetch: () => void;
@@ -26,6 +35,9 @@ export interface UseQueryReturn<T> {
 export interface UseQueryOneReturn<T> {
     data: T | null;
     loading: boolean;
+    /** See `UseQueryReturn.synced`. A `null` row with `synced: false` may
+     *  still exist on the server. */
+    synced: boolean;
     error: Error | null;
     refetch: () => void;
 }

package/dist/index.d.ts

@@ -22,6 +22,7 @@ export type { AgentRunRow, AgentMessageRow, UseAgentRunReturn, } from "./useAgen
 export { useRoom, useRoomMessages } from "./useRoom";
 export type { RoomPeer, RoomSnapshot, UseRoomOptions, UseRoomReturn, } from "./useRoom";
 export type { RoomMessage } from "@pylonsync/sync";
+export { MutationRejectedError } from "@pylonsync/sync";
 export { useShard, connectShard } from "./useShard";
 export type { UseShardOptions, UseShardReturn, ShardClient, } from "./useShard";
 export { SHARD_PROTOCOL_VERSION, ShardCodec, ShardFrameKind, parseShardFrame, decodeShardPayload, encodeShardInput, EntityTable, ReplicationError, connectShardGame, ShardClock, EntityInterpolator, Predictor, } from "./shardWire";
@@ -156,8 +157,8 @@ export declare function callFn<T = unknown>(name: string, args?: Record<string,
  * to survive the window closing).
  *
  * The call returns as soon as the request is recorded. A live
- * generation stops at its next turn boundary — between tool calls
- * within seconds, or after the current model response finishes.
+ * generation stops within a few seconds: a model response in progress
+ * is aborted, and a running tool sees `ctx.signal` abort.
  * `run.cancelRequested` is true in that window; drive the stop
  * button's pending state from it and treat `run.status === "cancelled"`
  * as the confirmation.

package/dist/useRoom.d.ts

@@ -77,10 +77,28 @@ interface SharedRoom {
     /** Connection-status unsubscribe — fires whenever the engine's
      *  transport state changes so we can flip between push and polling. */
     connectionStatusUnsubscribe: (() => void) | null;
+    /** A `POST /api/rooms/join` is in flight. */
+    joining: boolean;
+    /** Keepalive timer (`POST /api/rooms/heartbeat`), set once joined. */
+    keepalive: ReturnType<typeof setInterval> | null;
+    /** Pending rejoin after `NOT_IN_ROOM` / a failed join. */
+    rejoinTimer: ReturnType<typeof setTimeout> | null;
+    /** Rejoins since the last good snapshot or join. */
+    rejoinAttempts: number;
+    /** The caller left with `leave()`: no keepalive, no rejoin. */
+    left: boolean;
 }
 declare function releaseRoom(room: SharedRoom): void;
 export declare const __roomRegistryInternals: {
     reset(): void;
+    /** Shorten the keepalive / rejoin timings for a test. `reset()` restores
+     *  the defaults. */
+    setTimings(t: {
+        keepaliveMs?: number;
+        rejoinBaseMs?: number;
+    }): void;
+    /** Diagnostic: the caller's manual leave() for tests. */
+    markLeft(room: SharedRoom): void;
     acquire(baseUrl: string, roomId: string, userId: string, token: string | undefined, initialPresence: Record<string, any>, heartbeatInterval: number, engine?: SyncEngine | null): SharedRoom;
     release: typeof releaseRoom;
     size(): number;

package/dist/useRouter.d.ts

@@ -73,6 +73,15 @@ export declare function useRouteSeed<T = unknown>(): T | null;
  * ```
  */
 export declare function useRouteData<T>(loader: () => Promise<T> | T, deps: readonly unknown[]): T | null;
+interface LoaderEntry {
+    source: string;
+    deps: readonly unknown[];
+    promise: Promise<unknown>;
+}
+/** Find or create the cached promise for this loader call. A synchronous
+ *  loader result becomes an already-fulfilled thenable, which `use()` reads
+ *  without suspending. */
+declare function loaderEntry(source: string, deps: readonly unknown[], loader: () => unknown): LoaderEntry;
 /**
  * Client-side redirect — replaces the current history entry with `href`.
  * Drop-in for Next's `redirect` when called from a client component
@@ -118,3 +127,10 @@ export interface PylonRouter {
  * ```
  */
 export declare function useRouter(): PylonRouter;
+/** Test hooks for the useRouteData promise cache. */
+export declare const __routeDataCacheInternals: {
+    lookup: typeof loaderEntry;
+    size: () => number;
+    clear: () => void;
+};
+export {};

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,9 +14,9 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/realtime": "0.21.0",
-    "@pylonsync/sdk": "0.21.0",
-    "@pylonsync/sync": "0.21.0"
+    "@pylonsync/realtime": "0.22.0",
+    "@pylonsync/sdk": "0.22.0",
+    "@pylonsync/sync": "0.22.0"
   },
   "peerDependencies": {
     "react": ">=19.0.0"
@@ -25,6 +25,7 @@
     "@happy-dom/global-registrator": "^20.10.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

package/src/hooks.ts

@@ -31,6 +31,15 @@ export interface QueryOptions {
 export interface UseQueryReturn<T> {
   data: T[];
   loading: boolean;
+  /**
+   * True once the engine has completed a pull against the server in this
+   * session (since the last replica reset). While false, `data` may be a
+   * stale or partial copy loaded from the local cache, or the server is
+   * unreachable. `loading` is false as soon as cached rows exist, so use
+   * `synced` when an incomplete list would mislead (counts, "no results",
+   * billing state).
+   */
+  synced: boolean;
   error: Error | null;
   /** Re-fetch from the server. Rarely needed — data is live. */
   refetch: () => void;
@@ -39,6 +48,9 @@ export interface UseQueryReturn<T> {
 export interface UseQueryOneReturn<T> {
   data: T | null;
   loading: boolean;
+  /** See `UseQueryReturn.synced`. A `null` row with `synced: false` may
+   *  still exist on the server. */
+  synced: boolean;
   error: Error | null;
   refetch: () => void;
 }
@@ -159,6 +171,12 @@ export function useQuery<T = Row>(
   // instead of flashing "nothing here" over data that is on its way back.
   const loading = refetching || (!settled && data.length === 0);
 
+  const synced = useSyncExternalStore(
+    subscribe,
+    useCallback(() => sync.isSynced(), [sync]),
+    FALSE_SNAPSHOT,
+  );
+
   // Register interest so the reconcile safety net sweeps this entity
   // even when the local replica has zero rows for it. Without this, a
   // server row in a never-cached entity (created on another surface, a
@@ -184,7 +202,7 @@ export function useQuery<T = Row>(
       .finally(() => setRefetching(false));
   }, [sync]);
 
-  return { data, loading, error, refetch };
+  return { data, loading, synced, error, refetch };
 }
 
 /**
@@ -248,6 +266,12 @@ export function useQueryOne<T = Row>(
   // server-side from flashing "not found" while it is still in flight.
   const loading = refetching || (!settled && data === null);
 
+  const synced = useSyncExternalStore(
+    subscribe,
+    useCallback(() => sync.isSynced(), [sync]),
+    FALSE_SNAPSHOT,
+  );
+
   // Register interest so reconcile sweeps this entity even with zero
   // local rows. See SyncEngine.observeEntity.
   useEffect(() => {
@@ -265,7 +289,7 @@ export function useQueryOne<T = Row>(
       .finally(() => setRefetching(false));
   }, [sync]);
 
-  return { data, loading, error, refetch };
+  return { data, loading, synced, error, refetch };
 }
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -134,6 +134,9 @@ export type {
   UseRoomReturn,
 } from "./useRoom";
 export type { RoomMessage } from "@pylonsync/sync";
+// Thrown by db.insert / update / delete (and useEntity's) when the server
+// rejects a write.
+export { MutationRejectedError } from "@pylonsync/sync";
 
 // Shard hook for real-time sims (games, MMO, live docs, etc.)
 export { useShard, connectShard } from "./useShard";
@@ -625,8 +628,8 @@ export async function callFn<T = unknown>(
  * to survive the window closing).
  *
  * The call returns as soon as the request is recorded. A live
- * generation stops at its next turn boundary — between tool calls
- * within seconds, or after the current model response finishes.
+ * generation stops within a few seconds: a model response in progress
+ * is aborted, and a running tool sees `ctx.signal` abort.
  * `run.cancelRequested` is true in that window; drive the stop
  * button's pending state from it and treat `run.status === "cancelled"`
  * as the confirmation.
@@ -1048,8 +1051,22 @@ export async function uploadFile(
           body,
           headers: { "Content-Type": contentType },
         });
+  // Read the response body to the end, even an empty 204. Chrome cancels a
+  // fetch whose body is never read once the Response is dropped, and
+  // DevTools then lists the upload as failed (net::ERR_ABORTED) although
+  // the server stored the bytes.
+  const putBody = await put.text().catch(() => "");
   if (!put.ok) {
-    throw new PylonHttpError(`Upload of ${filename} failed: ${put.status}`, put.status);
+    let message = `Upload of ${filename} failed: ${put.status}`;
+    let code: string | undefined;
+    try {
+      const err = JSON.parse(putBody) as { error?: { code?: string; message?: string } };
+      if (err.error?.message) message = err.error.message;
+      code = err.error?.code;
+    } catch {
+      // Not JSON (storage provider XML, proxy page): keep the status text.
+    }
+    throw new PylonHttpError(message, put.status, code);
   }
 
   return pylonFetch<UploadedFile>(transport, "/api/files/confirm", {

package/src/uploadFile.test.ts

@@ -65,6 +65,43 @@ describe("uploadFile", () => {
     expect(seen[1].headers.Authorization).toBeUndefined();
   });
 
+  // Chrome cancels a fetch whose response body is never read once the
+  // Response is dropped: DevTools listed every upload's PUT as
+  // net::ERR_ABORTED even though the server answered 204 and stored the
+  // bytes. Reproduced in headless Chrome over CDP (loadingFailed,
+  // canceled: true); reading the body gives loadingFinished.
+  test("reads the PUT response body to the end (local and presigned)", async () => {
+    const puts: Response[] = [];
+    const inner = globalThis.fetch;
+    globalThis.fetch = (async (input: any, init: any = {}) => {
+      const res = await inner(input, init);
+      if ((init.method ?? "GET") === "PUT") {
+        const r = new Response(null, { status: 204 });
+        puts.push(r);
+        return r;
+      }
+      return res;
+    }) as typeof fetch;
+    await uploadFile(new Blob(["hi"]), { token: "tok" });
+    uploadUrl = "https://bucket.s3.example/f_1?X-Amz-Signature=abc";
+    await uploadFile(new Blob(["hi"]), { token: "tok" });
+    expect(puts).toHaveLength(2);
+    expect(puts.every((r) => r.bodyUsed)).toBe(true);
+  });
+
+  test("a refused PUT surfaces the server's error message", async () => {
+    globalThis.fetch = (async (input: any) => {
+      const url = String(input?.url ?? input);
+      if (url.endsWith("/api/files/init")) return new Response(JSON.stringify({ uploadUrl, assetId: "f_1" }), { status: 200 });
+      return new Response(JSON.stringify({ error: { code: "PAYLOAD_TOO_LARGE", message: "Body exceeds upload max" } }), { status: 413 });
+    }) as typeof fetch;
+    await expect(uploadFile(new Uint8Array([1]), { token: "tok" })).rejects.toMatchObject({
+      status: 413,
+      code: "PAYLOAD_TOO_LARGE",
+      message: "Body exceeds upload max",
+    });
+  });
+
   test("a refused PUT throws before confirm", async () => {
     globalThis.fetch = (async (input: any, init: any = {}) => {
       const url = String(input?.url ?? input);

package/src/useQuery.synced.test.tsx

@@ -0,0 +1,70 @@
+// `useQuery` / `useQueryOne` expose `synced`: false until the engine has
+// completed a server pull in this session. Without it an app could not tell
+// a warm but incomplete local replica from a complete one — `loading` is
+// false as soon as cached rows exist (saas template showed stale partial
+// data briefly).
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { act, cleanup, render, screen, waitFor } from "@testing-library/react";
+import type { SyncEngine } from "@pylonsync/sync";
+import { createTestEnv, type TestEnv } from "@pylonsync/sync/src/test-harness";
+
+import { useQuery, useQueryOne } from "./hooks";
+
+const asEngine = (e: TestEnv["engine"]): SyncEngine => e as unknown as SyncEngine;
+
+let env: TestEnv | null = null;
+afterEach(async () => {
+  cleanup();
+  if (env) {
+    await env.dispose();
+    env = null;
+  }
+});
+
+function Probe({ engine }: { engine: SyncEngine }) {
+  const list = useQuery<{ id: string }>(engine, "Todo");
+  const one = useQueryOne<{ id: string }>(engine, "Todo", "t1");
+  return (
+    <div>
+      <span data-testid="list">{`${list.data.length}:${list.loading}:${list.synced}`}</span>
+      <span data-testid="one">{`${one.data ? "row" : "none"}:${one.synced}`}</span>
+    </div>
+  );
+}
+
+describe("useQuery synced", () => {
+  test("cached rows render with synced false until the pull confirms them", async () => {
+    let release!: () => void;
+    const gate = new Promise<void>((r) => (release = r));
+    env = createTestEnv({ transport: "poll", beforePull: () => gate });
+    env.signIn({ userId: "u1" });
+    env.server.seed("Todo", [{ id: "t1" }, { id: "t2" }]);
+    // A row the local replica already holds (what a warm cache provides).
+    env.engine.store.applyChange({
+      seq: 0,
+      entity: "Todo",
+      row_id: "t1",
+      kind: "insert",
+      data: { id: "t1" },
+      timestamp: "",
+    });
+
+    render(<Probe engine={asEngine(env.engine)} />);
+    expect(screen.getByTestId("list").textContent).toBe("1:false:false");
+    expect(screen.getByTestId("one").textContent).toBe("row:false");
+
+    let started!: Promise<void>;
+    act(() => {
+      started = env!.engine.start();
+    });
+    release();
+    await act(async () => {
+      await started;
+    });
+    await waitFor(() =>
+      expect(screen.getByTestId("list").textContent).toBe("2:false:true"),
+    );
+    expect(screen.getByTestId("one").textContent).toBe("row:true");
+  });
+});

package/src/useRoom.push.test.ts

@@ -31,21 +31,34 @@ interface RecordedRequest {
 
 let recorded: RecordedRequest[];
 let originalFetch: typeof globalThis.fetch;
+/** Per-test override: return a body (or a promise of one) for a request,
+ *  or undefined for the default room response. */
+let respond: ((url: string, method: string) => unknown) | null = null;
 
 function installFetchStub(): void {
   recorded = [];
+  respond = null;
   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: [] }), {
+    const custom = respond ? await respond(url, method) : undefined;
+    const body = custom ?? { snapshot: { peers: [] }, members: [] };
+    return new Response(JSON.stringify(body), {
       status: 200,
       headers: { "content-type": "application/json" },
     });
   }) as typeof fetch;
 }
 
+function isJoin(r: RecordedRequest): boolean {
+  return r.method === "POST" && r.url.endsWith("/api/rooms/join");
+}
+function isKeepalive(r: RecordedRequest): boolean {
+  return r.method === "POST" && r.url.endsWith("/api/rooms/heartbeat");
+}
+
 function restoreFetch(): void {
   globalThis.fetch = originalFetch;
 }
@@ -69,6 +82,7 @@ interface FakeEngine {
     | Array<{ user_id: string; joined_at: string; data?: any }>
     | null;
   getRoomError: (roomId: string) => { code: string; message?: string } | null;
+  resubscribeRoom: (roomId: string) => void;
   isWebSocketConnected: () => boolean;
   connectionStatus: () => string;
   // The store.subscribe surface — useRoom subscribes to connection-status
@@ -83,6 +97,7 @@ interface FakeEngine {
   _rooms: Map<string, FakeRoomEntry>;
   _subscribeCalls: string[];
   _unsubscribeCalls: string[];
+  _resubscribeCalls: string[];
   setWsConnected(open: boolean): void;
   pushSnapshot(roomId: string, members: any[]): void;
   pushUpdate(
@@ -100,7 +115,13 @@ function makeFakeEngine(): FakeEngine {
     _rooms: new Map(),
     _subscribeCalls: [],
     _unsubscribeCalls: [],
+    _resubscribeCalls: [],
 
+    resubscribeRoom: (roomId) => {
+      engine._resubscribeCalls.push(roomId);
+      const entry = engine._rooms.get(roomId);
+      if (entry) entry.error = null;
+    },
     isWebSocketConnected: () => engine._wsOpen,
     connectionStatus: () => (engine._wsOpen ? "connected" : "reconnecting"),
     store: {
@@ -208,6 +229,8 @@ describe("useRoom WS push path", () => {
       25, // would tick every 25ms IF polling were active
       engine as any,
     );
+    // The room subscribes only after the HTTP join lands.
+    await flush();
     expect(engine._subscribeCalls).toEqual([ROOM]);
     expect(__roomRegistryInternals.isWsAttached(room)).toBe(true);
     expect(__roomRegistryInternals.isPolling(room)).toBe(false);
@@ -251,7 +274,7 @@ describe("useRoom WS push path", () => {
     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 () => {
+  test("NOT_IN_ROOM → rejoin over HTTP, then resubscribe; the snapshot restores presence", async () => {
     const engine = makeFakeEngine();
     const room = __roomRegistryInternals.acquire(
       BASE,
@@ -262,20 +285,132 @@ describe("useRoom WS push path", () => {
       1_000,
       engine as any,
     );
-    // Let the HTTP join settle first so its success doesn't clobber
-    // the WS-pushed error state.
     await flush();
+    expect(recorded.filter(isJoin)).toHaveLength(1);
+
+    // E.g. the socket reconnected and the server had dropped us when the
+    // old socket closed; the replayed subscribe is refused.
     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).
+    expect(recorded.filter(isJoin)).toHaveLength(2);
+    expect(engine._resubscribeCalls).toEqual([ROOM]);
+    expect(room.error).toBeNull();
+
+    engine.pushSnapshot(ROOM, [{ user_id: "alice", joined_at: "t1" }]);
+    await flush();
+    expect(room.isConnected).toBe(true);
+    expect(room.peers.map((p) => p.user_id)).toEqual(["alice"]);
+    // Snapshot-timeout fallback never engaged.
     await flush(80);
     expect(__roomRegistryInternals.isPolling(room)).toBe(false);
   });
 
+  test("NOT_IN_ROOM that keeps coming back surfaces the error after bounded retries", async () => {
+    __roomRegistryInternals.setTimings({ rejoinBaseMs: 1 });
+    const engine = makeFakeEngine();
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    await flush();
+    for (let i = 0; i < 8; i++) {
+      engine.pushError(ROOM, "NOT_IN_ROOM", "not a member");
+      await flush(40);
+    }
+    // 1 initial join + 5 rejoins, then the error reaches the hook.
+    expect(recorded.filter(isJoin)).toHaveLength(6);
+    expect(room.error ?? "").toContain("not a member");
+    expect(room.isConnected).toBe(false);
+  });
+
+  test("first mount: room-subscribe waits for the HTTP join (no NOT_IN_ROOM race)", async () => {
+    let releaseJoin!: () => void;
+    const joinGate = new Promise<void>((r) => (releaseJoin = r));
+    respond = async (url, method) => {
+      if (method === "POST" && url.endsWith("/api/rooms/join")) {
+        await joinGate;
+      }
+      return undefined;
+    };
+    const engine = makeFakeEngine();
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    await flush(20);
+    expect(engine._subscribeCalls).toEqual([]);
+    releaseJoin();
+    await flush();
+    expect(engine._subscribeCalls).toEqual([ROOM]);
+    expect(__roomRegistryInternals.isWsAttached(room)).toBe(true);
+  });
+
+  test("keepalive heartbeats while joined; alive:false rejoins", async () => {
+    __roomRegistryInternals.setTimings({ keepaliveMs: 20 });
+    let alive = true;
+    respond = (url, method) =>
+      method === "POST" && url.endsWith("/api/rooms/heartbeat")
+        ? { alive, ...(alive ? {} : { reason: "not_in_room" }) }
+        : undefined;
+    const engine = makeFakeEngine();
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    await flush(70);
+    expect(recorded.filter(isKeepalive).length).toBeGreaterThanOrEqual(2);
+    expect(recorded.filter(isJoin)).toHaveLength(1);
+
+    // The idle sweep dropped us: the next heartbeat reports it and the
+    // registry rejoins and resubscribes.
+    alive = false;
+    await flush(40);
+    alive = true;
+    expect(recorded.filter(isJoin).length).toBeGreaterThanOrEqual(2);
+    expect(engine._resubscribeCalls.length).toBeGreaterThanOrEqual(1);
+
+    // Manual leave stops the keepalive and any rejoin.
+    __roomRegistryInternals.markLeft(room);
+    const before = recorded.filter(isKeepalive).length;
+    await flush(60);
+    expect(recorded.filter(isKeepalive).length).toBe(before);
+  });
+
+  test("teardown stops the keepalive", async () => {
+    __roomRegistryInternals.setTimings({ keepaliveMs: 20 });
+    const engine = makeFakeEngine();
+    const room = __roomRegistryInternals.acquire(
+      BASE,
+      ROOM,
+      USER,
+      TOKEN,
+      {},
+      1_000,
+      engine as any,
+    );
+    await flush(30);
+    __roomRegistryInternals.release(room);
+    await flush(10);
+    const before = recorded.filter(isKeepalive).length;
+    await flush(60);
+    expect(recorded.filter(isKeepalive).length).toBe(before);
+  });
+
   test("WS down → polling fallback fires; reconnect promotes back to push", async () => {
     const engine = makeFakeEngine();
     engine.setWsConnected(false);
@@ -317,6 +452,7 @@ describe("useRoom WS push path", () => {
       25,
       engine as any,
     );
+    await flush();
     expect(__roomRegistryInternals.isWsAttached(room)).toBe(true);
     expect(__roomRegistryInternals.isPolling(room)).toBe(false);
 
@@ -349,6 +485,7 @@ describe("useRoom WS push path", () => {
       engine as any,
     );
     expect(r1).toBe(r2);
+    await flush();
     // Registry dedup → only one acquire path → only one subscribe.
     expect(engine._subscribeCalls).toEqual([ROOM]);
     __roomRegistryInternals.release(r1);

package/src/useRoom.ts

@@ -108,6 +108,23 @@ export interface UseRoomReturn {
  *  setup recovers without the user noticing. */
 const PUSH_SNAPSHOT_TIMEOUT_MS = 2_000;
 
+/** How often a joined room sends `POST /api/rooms/heartbeat`. The server
+ *  drops a member after 120 s without activity; 45 s leaves room for two
+ *  lost heartbeats. */
+const ROOM_KEEPALIVE_MS = 45_000;
+
+/** Backoff base for rejoining after `NOT_IN_ROOM` or a failed join. The
+ *  first rejoin runs at once; later ones wait 1 s, 2 s, 4 s, ... up to
+ *  30 s. After `MAX_REJOIN_ATTEMPTS` the error is surfaced to the hook. */
+const REJOIN_BASE_MS = 1_000;
+const MAX_REJOIN_ATTEMPTS = 5;
+
+/** Test overrides for the timings above. */
+const timing = {
+  keepaliveMs: ROOM_KEEPALIVE_MS,
+  rejoinBaseMs: REJOIN_BASE_MS,
+};
+
 interface SharedRoom {
   /** Number of live React hooks holding this room. */
   refs: number;
@@ -148,6 +165,16 @@ interface SharedRoom {
   /** Connection-status unsubscribe — fires whenever the engine's
    *  transport state changes so we can flip between push and polling. */
   connectionStatusUnsubscribe: (() => void) | null;
+  /** A `POST /api/rooms/join` is in flight. */
+  joining: boolean;
+  /** Keepalive timer (`POST /api/rooms/heartbeat`), set once joined. */
+  keepalive: ReturnType<typeof setInterval> | null;
+  /** Pending rejoin after `NOT_IN_ROOM` / a failed join. */
+  rejoinTimer: ReturnType<typeof setTimeout> | null;
+  /** Rejoins since the last good snapshot or join. */
+  rejoinAttempts: number;
+  /** The caller left with `leave()`: no keepalive, no rejoin. */
+  left: boolean;
 }
 
 const rooms = new Map<string, SharedRoom>();
@@ -225,6 +252,22 @@ function startWsPush(room: SharedRoom): void {
         clearTimeout(room.pushSnapshotTimer);
         room.pushSnapshotTimer = null;
       }
+      // The server no longer counts us as a member: our socket closed
+      // (reconnect), the idle sweep dropped us, or the subscribe beat the
+      // join. Rejoin over HTTP, then resubscribe. Surface the error only
+      // when rejoining keeps failing.
+      if (
+        err.code === 'NOT_IN_ROOM' &&
+        !room.left &&
+        room.rejoinAttempts < MAX_REJOIN_ATTEMPTS
+      ) {
+        if (room.isConnected) {
+          room.isConnected = false;
+          notify(room);
+        }
+        scheduleRejoin(room);
+        return;
+      }
       room.error =
         err.code === 'NOT_IN_ROOM'
           ? 'You are not a member of this room.'
@@ -238,6 +281,7 @@ function startWsPush(room: SharedRoom): void {
         clearTimeout(room.pushSnapshotTimer);
         room.pushSnapshotTimer = null;
       }
+      room.rejoinAttempts = 0;
       room.peers = members
         .filter((m) => m.user_id !== room.userId)
         .map(memberToPeer);
@@ -302,6 +346,13 @@ function evaluateDelivery(room: SharedRoom): void {
     return;
   }
   if (engine.isWebSocketConnected()) {
+    // The server answers `room-subscribe` with NOT_IN_ROOM unless the
+    // HTTP join already landed. Subscribe only after it has; the join's
+    // success path calls back in here.
+    if (!room.joined) {
+      stopHeartbeat(room);
+      return;
+    }
     startWsPush(room);
   } else {
     stopWsPush(room);
@@ -314,6 +365,8 @@ function joinRoom(room: SharedRoom): void {
   // and notifies all subscribers. Late subscribers either pick up the
   // already-resolved snapshot from `room.peers` or the next push /
   // heartbeat.
+  if (room.joining || room.left) return;
+  room.joining = true;
   pylonFetch<{ snapshot?: { peers?: RoomPeer[] } }>(
     transportFor(room),
     '/api/rooms/join',
@@ -326,6 +379,7 @@ function joinRoom(room: SharedRoom): void {
       // The room may have been torn down before join landed (mount →
       // unmount → no remount). In that case the entry is gone from the
       // registry; bail and let the leave path (if it ran) do its thing.
+      room.joining = false;
       if (!rooms.has(roomKeyFor(room))) return;
       room.joined = true;
       room.isConnected = true;
@@ -334,14 +388,80 @@ function joinRoom(room: SharedRoom): void {
         room.peers = body.snapshot.peers.filter((p) => p.user_id !== room.userId);
       }
       notify(room);
+      startKeepalive(room);
+      if (room.wsUnsubscribe && room.engine) {
+        // Rejoin after NOT_IN_ROOM: the engine still holds the room's
+        // subscription, so ask it to resend `room-subscribe`.
+        room.engine.resubscribeRoom(room.roomId);
+      } else {
+        evaluateDelivery(room);
+      }
     })
     .catch((e: any) => {
+      room.joining = false;
       if (!rooms.has(roomKeyFor(room))) return;
+      if (room.rejoinAttempts < MAX_REJOIN_ATTEMPTS && !room.left) {
+        scheduleRejoin(room);
+        return;
+      }
       room.error = e?.message ?? 'Failed to join room';
       notify(room);
     });
 }
 
+/** Rejoin with backoff: at once for the first attempt, then 1 s, 2 s, 4 s,
+ *  ... capped at 30 s. One pending rejoin at a time. */
+function scheduleRejoin(room: SharedRoom): void {
+  if (room.rejoinTimer || room.joining || room.left) return;
+  const attempt = room.rejoinAttempts;
+  room.rejoinAttempts += 1;
+  const delay =
+    attempt === 0 ? 0 : Math.min(30_000, timing.rejoinBaseMs * 2 ** (attempt - 1));
+  room.rejoinTimer = setTimeout(() => {
+    room.rejoinTimer = null;
+    if (!rooms.has(roomKeyFor(room))) return;
+    joinRoom(room);
+  }, delay);
+}
+
+/** Keep the server-side membership alive. The server drops a member after
+ *  120 s without activity; a heartbeat refreshes it without emitting an
+ *  event. `alive: false` means the server already dropped us: rejoin. */
+function startKeepalive(room: SharedRoom): void {
+  if (room.keepalive || room.left) return;
+  room.keepalive = setInterval(() => {
+    if (!rooms.has(roomKeyFor(room)) || room.left) return;
+    pylonFetch<{ alive?: boolean }>(transportFor(room), '/api/rooms/heartbeat', {
+      method: 'POST',
+      json: { room: room.roomId, user_id: room.userId },
+    })
+      .then((body) => {
+        if (body?.alive === false && rooms.has(roomKeyFor(room))) {
+          if (room.isConnected) {
+            room.isConnected = false;
+            notify(room);
+          }
+          scheduleRejoin(room);
+        }
+      })
+      .catch(() => {
+        // Offline or an older server without the endpoint: the next
+        // heartbeat retries, and a reconnect's NOT_IN_ROOM rejoins.
+      });
+  }, timing.keepaliveMs);
+}
+
+function stopKeepalive(room: SharedRoom): void {
+  if (room.keepalive) {
+    clearInterval(room.keepalive);
+    room.keepalive = null;
+  }
+  if (room.rejoinTimer) {
+    clearTimeout(room.rejoinTimer);
+    room.rejoinTimer = null;
+  }
+}
+
 function leaveRoom(room: SharedRoom): void {
   // Only ship leave if join actually landed — matches the original
   // StrictMode race-fix. Server leave is idempotent now, but skipping
@@ -395,6 +515,11 @@ function acquireRoom(
     wsUnsubscribe: null,
     pushSnapshotTimer: null,
     connectionStatusUnsubscribe: null,
+    joining: false,
+    keepalive: null,
+    rejoinTimer: null,
+    rejoinAttempts: 0,
+    left: false,
   };
   rooms.set(key, room);
   joinRoom(room);
@@ -429,6 +554,7 @@ function releaseRoom(room: SharedRoom): void {
     }
     stopHeartbeat(room);
     stopWsPush(room);
+    stopKeepalive(room);
     if (room.connectionStatusUnsubscribe) {
       room.connectionStatusUnsubscribe();
       room.connectionStatusUnsubscribe = null;
@@ -479,12 +605,26 @@ export const __roomRegistryInternals = {
       if (room.pendingTeardown) clearTimeout(room.pendingTeardown);
       stopHeartbeat(room);
       stopWsPush(room);
+      stopKeepalive(room);
       if (room.connectionStatusUnsubscribe) {
         room.connectionStatusUnsubscribe();
         room.connectionStatusUnsubscribe = null;
       }
     }
     rooms.clear();
+    timing.keepaliveMs = ROOM_KEEPALIVE_MS;
+    timing.rejoinBaseMs = REJOIN_BASE_MS;
+  },
+  /** Shorten the keepalive / rejoin timings for a test. `reset()` restores
+   *  the defaults. */
+  setTimings(t: { keepaliveMs?: number; rejoinBaseMs?: number }): void {
+    if (t.keepaliveMs !== undefined) timing.keepaliveMs = t.keepaliveMs;
+    if (t.rejoinBaseMs !== undefined) timing.rejoinBaseMs = t.rejoinBaseMs;
+  },
+  /** Diagnostic: the caller's manual leave() for tests. */
+  markLeft(room: SharedRoom): void {
+    room.left = true;
+    stopKeepalive(room);
   },
   acquire(
     baseUrl: string,
@@ -669,7 +809,13 @@ export function useRoom(
     // Manual leave — bypasses the shared lifecycle and tells the server
     // we're gone immediately. The next effect cleanup will still try to
     // release the refcount; the join-guard means a duplicate leave is
-    // skipped if needed, and the server is idempotent anyway.
+    // skipped if needed, and the server is idempotent anyway. Stop the
+    // keepalive and any rejoin so the room stays left.
+    const room = roomRef.current;
+    if (room) {
+      room.left = true;
+      stopKeepalive(room);
+    }
     pylonFetch(
       { baseUrl, token },
       '/api/rooms/leave',

package/src/useRouteData.test.tsx

@@ -0,0 +1,206 @@
+// useRouteData must hand React's `use()` the same promise on every render
+// attempt. It called `use(Promise.resolve(loader()))`, which minted a new
+// promise per render: React logged "A component was suspended by an
+// uncached promise" on listing pages and the loader ran again on every
+// retry.
+//
+// Mounted with react-dom/client directly, outside the act() environment:
+// under act, React 19 does not retry a suspended render when its promise
+// resolves in this test runtime, so every Suspense test would hang.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { Component, Suspense, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+
+import { __routeDataCacheInternals, useRouteData } from "./useRouter";
+
+let root: Root | null = null;
+let host: HTMLElement | null = null;
+let prevActEnv: unknown;
+
+beforeEach(() => {
+  prevActEnv = (globalThis as { IS_REACT_ACT_ENVIRONMENT?: unknown }).IS_REACT_ACT_ENVIRONMENT;
+  (globalThis as { IS_REACT_ACT_ENVIRONMENT?: unknown }).IS_REACT_ACT_ENVIRONMENT = false;
+  host = document.createElement("div");
+  document.body.appendChild(host);
+  root = createRoot(host);
+});
+
+afterEach(() => {
+  root?.unmount();
+  host?.remove();
+  root = null;
+  host = null;
+  (globalThis as { IS_REACT_ACT_ENVIRONMENT?: unknown }).IS_REACT_ACT_ENVIRONMENT = prevActEnv;
+});
+
+function mount(node: ReactNode) {
+  root!.render(<Suspense fallback={<p>loading</p>}>{node}</Suspense>);
+}
+
+async function until(text: string): Promise<void> {
+  for (let i = 0; i < 100; i++) {
+    if (host!.textContent === text) return;
+    await new Promise((r) => setTimeout(r, 5));
+  }
+  throw new Error(`expected "${text}", saw "${host!.textContent}"`);
+}
+
+function captureConsoleError(): { messages: string[]; restore: () => void } {
+  const original = console.error;
+  const messages: string[] = [];
+  console.error = (...args: unknown[]) => {
+    messages.push(args.map(String).join(" "));
+  };
+  return { messages, restore: () => (console.error = original) };
+}
+
+describe("useRouteData", () => {
+  test("suspends on one cached promise and runs the loader once", async () => {
+    let calls = 0;
+    const load = (slug: string) => {
+      calls += 1;
+      return new Promise<string>((r) => setTimeout(() => r(`item:${slug}`), 5));
+    };
+    function Item({ slug }: { slug: string }) {
+      const v = useRouteData(() => load(slug), [slug]);
+      return <p>{v}</p>;
+    }
+    const logs = captureConsoleError();
+    try {
+      mount(<Item slug="a" />);
+      await until("item:a");
+    } finally {
+      logs.restore();
+    }
+    expect(calls).toBe(1);
+    expect(logs.messages.some((m) => m.includes("uncached promise"))).toBe(false);
+  });
+
+  test("a synchronous loader value renders without a fallback", async () => {
+    let calls = 0;
+    function Item() {
+      const v = useRouteData(() => {
+        calls += 1;
+        return "ready";
+      }, ["sync"]);
+      return <p>{v}</p>;
+    }
+    mount(<Item />);
+    await until("ready");
+    expect(calls).toBe(1);
+  });
+
+  test("new deps load again; two loaders with the same deps keep their own results", async () => {
+    const seen: string[] = [];
+    function Pair({ id }: { id: string }) {
+      const a = useRouteData(async () => {
+        seen.push(`a:${id}`);
+        return `A-${id}`;
+      }, [id]);
+      const b = useRouteData(async () => {
+        seen.push(`b:${id}`);
+        return `B-${id}`;
+      }, [id]);
+      return <p>{`${a} ${b}`}</p>;
+    }
+    mount(<Pair id="1" />);
+    await until("A-1 B-1");
+    mount(<Pair id="2" />);
+    await until("A-2 B-2");
+    expect(seen.filter((s) => s === "a:1")).toHaveLength(1);
+    expect(seen.filter((s) => s === "a:2")).toHaveLength(1);
+    expect(seen.filter((s) => s === "b:2")).toHaveLength(1);
+  });
+});
+
+describe("useRouteData promise cache", () => {
+  test("a server render shares a promise only within one request", () => {
+    __routeDataCacheInternals.clear();
+    const g = globalThis as { window?: unknown };
+    const saved = g.window;
+    delete g.window;
+    try {
+      let calls = 0;
+      const loader = () => {
+        calls += 1;
+        return Promise.resolve(`user-${calls}`);
+      };
+      const serverData = () => ({
+        get: () => {}, list: () => {}, queryGraph: () => {}, paginate: () => {},
+      });
+      const requestA = serverData();
+      const requestB = serverData();
+      const a1 = __routeDataCacheInternals.lookup("src", [requestA, "slug"], loader);
+      const a2 = __routeDataCacheInternals.lookup("src", [requestA, "slug"], loader);
+      const b = __routeDataCacheInternals.lookup("src", [requestB, "slug"], loader);
+      expect(a1).toBe(a2);
+      expect(b).not.toBe(a1);
+      expect(calls).toBe(2);
+      // A module-level object (an API client) is not a request scope.
+      const api = { me: () => {} };
+      const m1 = __routeDataCacheInternals.lookup("src", [api, "me"], loader);
+      const m2 = __routeDataCacheInternals.lookup("src", [api, "me"], loader);
+      expect(m1).not.toBe(m2);
+      // No object at all: never cached on the server.
+      const p1 = __routeDataCacheInternals.lookup("src", ["slug"], loader);
+      const p2 = __routeDataCacheInternals.lookup("src", ["slug"], loader);
+      expect(p1).not.toBe(p2);
+      expect(__routeDataCacheInternals.size()).toBe(0);
+    } finally {
+      g.window = saved;
+    }
+  });
+
+  test("a rejected load stays long enough for the error boundary, then leaves", async () => {
+    __routeDataCacheInternals.clear();
+    let calls = 0;
+    const loader = () => {
+      calls += 1;
+      return Promise.reject(new Error("boom"));
+    };
+    const first = __routeDataCacheInternals.lookup("src-err", ["x"], loader);
+    await first.promise.catch(() => {});
+    // React's re-render after the rejection sees the same promise.
+    expect(__routeDataCacheInternals.lookup("src-err", ["x"], loader)).toBe(first);
+    expect(calls).toBe(1);
+    await new Promise((r) => setTimeout(r, 1_100));
+    __routeDataCacheInternals.lookup("src-err", ["x"], loader).promise.catch(() => {});
+    expect(calls).toBe(2);
+    __routeDataCacheInternals.clear();
+  });
+
+  test("a failing loader renders the error boundary without a retry loop", async () => {
+    let calls = 0;
+    class Boundary extends Component<{ children: ReactNode }, { error: string | null }> {
+      state = { error: null as string | null };
+      static getDerivedStateFromError(e: Error) {
+        return { error: e.message };
+      }
+      render() {
+        return this.state.error ? <p>{`error:${this.state.error}`}</p> : this.props.children;
+      }
+    }
+    function Item() {
+      const v = useRouteData(() => {
+        calls += 1;
+        return new Promise<string>((_, reject) => setTimeout(() => reject(new Error("boom")), 5));
+      }, ["failing"]);
+      return <p>{v}</p>;
+    }
+    const logs = captureConsoleError();
+    try {
+      root!.render(
+        <Boundary>
+          <Suspense fallback={<p>loading</p>}>
+            <Item />
+          </Suspense>
+        </Boundary>,
+      );
+      await until("error:boom");
+    } finally {
+      logs.restore();
+    }
+    expect(calls).toBe(1);
+  });
+});

package/src/useRouter.ts

@@ -205,15 +205,140 @@ export function useRouteData<T>(
     // loader is intentionally excluded; `deps` are the reload trigger.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, deps);
-  if (!optimistic) {
+  // Hooks run in both modes so their order never changes.
+  const committed = useRef<LoaderEntry | null>(null);
+  const source = optimistic ? "" : loader.toString();
+  const entry = optimistic
+    ? null
+    : committed.current && sameLoader(committed.current, source, deps)
+      ? committed.current
+      : loaderEntry(source, deps, loader);
+  useEffect(() => {
+    if (!entry) return;
+    // Once mounted, the ref keeps the promise; the shared cache only has to
+    // bridge renders that suspended before the first commit.
+    committed.current = entry;
+    releaseLoaderEntry(entry);
+  });
+  if (entry) {
     // SSR + hard load + non-seeded nav: suspend so the server streams the real
     // content and the client hydrates it synchronously from the pre-fulfilled
-    // serverData cache (matches the server HTML — no mismatch).
-    return use(Promise.resolve(loader())) as T;
+    // serverData cache (matches the server HTML — no mismatch). `use()` must
+    // get the SAME promise on every attempt: a render that suspends before its
+    // first commit keeps no state, so the promise lives in a shared cache
+    // keyed by the loader's source and `deps`.
+    return use(entry.promise) as T;
   }
   return data ?? seed;
 }
 
+interface LoaderEntry {
+  source: string;
+  deps: readonly unknown[];
+  promise: Promise<unknown>;
+}
+
+/** Promises for loaders whose component has not committed yet. Bounded so
+ *  renders that suspend and are then abandoned cannot grow it forever. */
+const pendingLoaders: LoaderEntry[] = [];
+const PENDING_LOADERS_MAX = 64;
+
+function sameLoader(e: LoaderEntry, source: string, deps: readonly unknown[]): boolean {
+  if (e.source !== source || e.deps.length !== deps.length) return false;
+  for (let i = 0; i < deps.length; i++) {
+    if (!Object.is(e.deps[i], deps[i])) return false;
+  }
+  return true;
+}
+
+/** Server renders: entries keyed by the page's `serverData` found in
+ *  `deps`. The SSR runtime builds a new `serverData` for every request,
+ *  so a render's retries share one promise and nothing is shared between
+ *  requests. Loaders whose deps hold no `serverData` are not cached on
+ *  the server (a module-level object in deps would be shared by every
+ *  request). */
+const serverLoaders = new WeakMap<object, LoaderEntry[]>();
+
+/** True for the SSR `serverData` object (see `ServerData` in ./ssr). */
+function isServerData(d: unknown): d is object {
+  if (d === null || typeof d !== "object") return false;
+  const o = d as Record<string, unknown>;
+  return (
+    typeof o.get === "function" &&
+    typeof o.list === "function" &&
+    typeof o.queryGraph === "function" &&
+    typeof o.paginate === "function"
+  );
+}
+
+/** How long a rejected load stays cached. React re-renders the suspended
+ *  component once the promise rejects; that render must see the same
+ *  rejected promise so the error reaches the error boundary. A retry
+ *  after this window runs the loader again. */
+const REJECTED_ENTRY_TTL_MS = 1_000;
+
+function makeEntry(source: string, deps: readonly unknown[], loader: () => unknown): LoaderEntry {
+  const value = loader();
+  let promise: Promise<unknown>;
+  if (value != null && typeof (value as { then?: unknown }).then === "function") {
+    promise = value as Promise<unknown>;
+  } else {
+    promise = Promise.resolve(value);
+    // React reads `status` / `value` on a thenable to skip suspending.
+    Object.assign(promise, { status: "fulfilled", value });
+  }
+  return { source, deps: [...deps], promise };
+}
+
+/** Find or create the cached promise for this loader call. A synchronous
+ *  loader result becomes an already-fulfilled thenable, which `use()` reads
+ *  without suspending. */
+function loaderEntry(
+  source: string,
+  deps: readonly unknown[],
+  loader: () => unknown,
+): LoaderEntry {
+  if (typeof window === "undefined") {
+    // The module is shared by every request; the key must include the
+    // request (see `serverLoaders`).
+    const scope = deps.find(isServerData);
+    if (!scope) return makeEntry(source, deps, loader);
+    let list = serverLoaders.get(scope);
+    if (!list) {
+      list = [];
+      serverLoaders.set(scope, list);
+    }
+    const hit = list.find((e) => sameLoader(e, source, deps));
+    if (hit) return hit;
+    const entry = makeEntry(source, deps, loader);
+    list.push(entry);
+    const scoped = list;
+    entry.promise.then(undefined, () => {
+      setTimeout(() => {
+        const i = scoped.indexOf(entry);
+        if (i !== -1) scoped.splice(i, 1);
+      }, REJECTED_ENTRY_TTL_MS);
+    });
+    return entry;
+  }
+  const hit = pendingLoaders.find((e) => sameLoader(e, source, deps));
+  if (hit) return hit;
+  const entry = makeEntry(source, deps, loader);
+  pendingLoaders.push(entry);
+  // A failed load must not stay cached forever: an error-boundary retry
+  // has to run the loader again.
+  entry.promise.then(undefined, () => {
+    setTimeout(() => releaseLoaderEntry(entry), REJECTED_ENTRY_TTL_MS);
+  });
+  if (pendingLoaders.length > PENDING_LOADERS_MAX) pendingLoaders.shift();
+  return entry;
+}
+
+function releaseLoaderEntry(entry: LoaderEntry): void {
+  const i = pendingLoaders.indexOf(entry);
+  if (i !== -1) pendingLoaders.splice(i, 1);
+}
+
 /**
  * Client-side redirect — replaces the current history entry with `href`.
  * Drop-in for Next's `redirect` when called from a client component
@@ -300,3 +425,12 @@ export function useRouter(): PylonRouter {
     [],
   );
 }
+
+/** Test hooks for the useRouteData promise cache. */
+export const __routeDataCacheInternals = {
+  lookup: loaderEntry,
+  size: (): number => pendingLoaders.length,
+  clear: (): void => {
+    pendingLoaders.length = 0;
+  },
+};