rwsdk 1.1.0 → 1.2.1

package/dist/use-synced-state/__tests__/client-core.test.js

@@ -0,0 +1,303 @@
+import { afterEach, beforeEach, describe, expect, it, vi, } from "vitest";
+const mockClients = [];
+const { newWebSocketRpcSession } = vi.hoisted(() => {
+    return {
+        newWebSocketRpcSession: vi.fn(),
+    };
+});
+vi.mock("capnweb", () => ({
+    newWebSocketRpcSession,
+}));
+function makeMockClient() {
+    let brokenCb = null;
+    const client = {
+        getState: vi.fn().mockResolvedValue(undefined),
+        setState: vi.fn().mockResolvedValue(undefined),
+        subscribe: vi.fn().mockResolvedValue(undefined),
+        unsubscribe: vi.fn().mockResolvedValue(undefined),
+        onRpcBroken: vi.fn((cb) => {
+            brokenCb = cb;
+        }),
+        // Helper to simulate a connection break from tests
+        simulateBreak(error = new Error("connection lost")) {
+            brokenCb?.(error);
+        },
+    };
+    mockClients.push(client);
+    return client;
+}
+import { getSyncedStateClient, onStatusChange, __testing, } from "../client-core";
+const ENDPOINT = "wss://test.example.com/__synced-state";
+describe("client-core reconnection", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        mockClients.length = 0;
+        newWebSocketRpcSession.mockReset();
+        newWebSocketRpcSession.mockImplementation(() => makeMockClient());
+        // Clear all internal state between tests
+        __testing.clientCache.clear();
+        __testing.activeSubscriptions.clear();
+        for (const [, state] of __testing.backoffState) {
+            if (state.timer !== null)
+                clearTimeout(state.timer);
+        }
+        __testing.backoffState.clear();
+    });
+    afterEach(() => {
+        __testing.clientCache.clear();
+        __testing.activeSubscriptions.clear();
+        __testing.backoffState.clear();
+        __testing.statusListeners.clear();
+        vi.useRealTimers();
+    });
+    it("registers onRpcBroken callback when creating a client", async () => {
+        getSyncedStateClient(ENDPOINT);
+        await __testing.warmUp(ENDPOINT);
+        expect(mockClients).toHaveLength(1);
+        expect(mockClients[0].onRpcBroken).toHaveBeenCalledOnce();
+    });
+    it("creates a new client after connection breaks", async () => {
+        getSyncedStateClient(ENDPOINT);
+        await __testing.warmUp(ENDPOINT);
+        expect(mockClients).toHaveLength(1);
+        // Simulate connection break
+        mockClients[0].simulateBreak();
+        // Reconnect happens after backoff timer fires
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        expect(mockClients).toHaveLength(2);
+    });
+    it("does not reconnect immediately — waits for backoff", async () => {
+        getSyncedStateClient(ENDPOINT);
+        await __testing.warmUp(ENDPOINT);
+        mockClients[0].simulateBreak();
+        // Before the timer fires, no new session yet
+        expect(mockClients).toHaveLength(1);
+        // After timer fires, reconnect happens
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        expect(mockClients).toHaveLength(2);
+    });
+    it("re-subscribes active subscriptions after reconnect", async () => {
+        const client = getSyncedStateClient(ENDPOINT);
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        // Simulate connection break
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        // The new client should have subscribe called with the same key and handler
+        const newClient = mockClients[1];
+        expect(newClient.subscribe).toHaveBeenCalledWith("counter", handler);
+    });
+    it("fetches latest state for each subscription after reconnect", async () => {
+        const client = getSyncedStateClient(ENDPOINT);
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        const newClient = mockClients[1];
+        expect(newClient.getState).toHaveBeenCalledWith("counter");
+    });
+    it("calls handler with fetched state when value is not undefined", async () => {
+        const client = getSyncedStateClient(ENDPOINT);
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        // Next client will return a value for getState
+        newWebSocketRpcSession.mockImplementationOnce(() => {
+            const c = makeMockClient();
+            c.getState.mockResolvedValue(42);
+            return c;
+        });
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        // Allow the getState promise to resolve
+        await vi.runAllTimersAsync();
+        expect(handler).toHaveBeenCalledWith(42);
+    });
+    it("does not call handler when fetched state is undefined", async () => {
+        const client = getSyncedStateClient(ENDPOINT);
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        handler.mockClear();
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        // Default mock returns undefined for getState
+        await vi.runAllTimersAsync();
+        expect(handler).not.toHaveBeenCalled();
+    });
+    it("does not re-subscribe keys that were unsubscribed before reconnect", async () => {
+        const client = getSyncedStateClient(ENDPOINT);
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        await client.unsubscribe("counter", handler);
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        const newClient = mockClients[1];
+        expect(newClient.subscribe).not.toHaveBeenCalled();
+    });
+    it("does not schedule multiple reconnects for the same endpoint", async () => {
+        getSyncedStateClient(ENDPOINT);
+        await __testing.warmUp(ENDPOINT);
+        // Fire broken twice rapidly
+        mockClients[0].simulateBreak();
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        // Should only have created one new session
+        expect(mockClients).toHaveLength(2);
+    });
+    it("uses exponential backoff with jitter and a 30s cap", () => {
+        // Backoff is base * (0.75..1.25) due to ±25% jitter, so we check ranges
+        const inRange = (val, min, max) => val >= min && val <= max;
+        expect(inRange(__testing.getBackoffMs(0), 750, 1250)).toBe(true); // base 1000
+        expect(inRange(__testing.getBackoffMs(1), 1500, 2500)).toBe(true); // base 2000
+        expect(inRange(__testing.getBackoffMs(2), 3000, 5000)).toBe(true); // base 4000
+        expect(inRange(__testing.getBackoffMs(3), 6000, 10000)).toBe(true); // base 8000
+        expect(inRange(__testing.getBackoffMs(5), 22500, 30000)).toBe(true); // capped at 30000
+        expect(inRange(__testing.getBackoffMs(10), 22500, 30000)).toBe(true); // still capped
+    });
+    it("returns cached client on second call for same endpoint", async () => {
+        const client1 = getSyncedStateClient(ENDPOINT);
+        const client2 = getSyncedStateClient(ENDPOINT);
+        expect(client1).toBe(client2);
+        await __testing.warmUp(ENDPOINT);
+        expect(mockClients).toHaveLength(1);
+    });
+    it("re-subscribes multiple subscriptions after reconnect", async () => {
+        const client = getSyncedStateClient(ENDPOINT);
+        const handler1 = vi.fn();
+        const handler2 = vi.fn();
+        await client.subscribe("counter", handler1);
+        await client.subscribe("score", handler2);
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        await __testing.warmUp(ENDPOINT);
+        const newClient = mockClients[1];
+        expect(newClient.subscribe).toHaveBeenCalledWith("counter", handler1);
+        expect(newClient.subscribe).toHaveBeenCalledWith("score", handler2);
+        expect(newClient.getState).toHaveBeenCalledWith("counter");
+        expect(newClient.getState).toHaveBeenCalledWith("score");
+    });
+    describe("onStatusChange", () => {
+        it("fires 'disconnected' immediately when connection breaks", async () => {
+            getSyncedStateClient(ENDPOINT);
+            await __testing.warmUp(ENDPOINT);
+            const statusCb = vi.fn();
+            onStatusChange(ENDPOINT, statusCb);
+            mockClients[0].simulateBreak();
+            expect(statusCb).toHaveBeenCalledWith("disconnected");
+        });
+        it("fires 'reconnecting' then 'connected' when reconnect completes", async () => {
+            getSyncedStateClient(ENDPOINT);
+            await __testing.warmUp(ENDPOINT);
+            const statusCb = vi.fn();
+            onStatusChange(ENDPOINT, statusCb);
+            mockClients[0].simulateBreak();
+            statusCb.mockClear();
+            vi.runOnlyPendingTimers();
+            await vi.runAllTimersAsync();
+            expect(statusCb).toHaveBeenCalledTimes(2);
+            expect(statusCb).toHaveBeenNthCalledWith(1, "reconnecting");
+            expect(statusCb).toHaveBeenNthCalledWith(2, "connected");
+        });
+        it("fires full lifecycle: disconnected → reconnecting → connected", async () => {
+            getSyncedStateClient(ENDPOINT);
+            await __testing.warmUp(ENDPOINT);
+            const statuses = [];
+            onStatusChange(ENDPOINT, (s) => statuses.push(s));
+            mockClients[0].simulateBreak();
+            vi.runOnlyPendingTimers();
+            await vi.runAllTimersAsync();
+            expect(statuses).toEqual(["disconnected", "reconnecting", "connected"]);
+        });
+        it("returns an unsubscribe function that stops notifications", async () => {
+            getSyncedStateClient(ENDPOINT);
+            await __testing.warmUp(ENDPOINT);
+            const statusCb = vi.fn();
+            const unsub = onStatusChange(ENDPOINT, statusCb);
+            unsub();
+            mockClients[0].simulateBreak();
+            expect(statusCb).not.toHaveBeenCalled();
+        });
+        it("supports multiple listeners on the same endpoint", async () => {
+            getSyncedStateClient(ENDPOINT);
+            await __testing.warmUp(ENDPOINT);
+            const cb1 = vi.fn();
+            const cb2 = vi.fn();
+            onStatusChange(ENDPOINT, cb1);
+            onStatusChange(ENDPOINT, cb2);
+            mockClients[0].simulateBreak();
+            expect(cb1).toHaveBeenCalledWith("disconnected");
+            expect(cb2).toHaveBeenCalledWith("disconnected");
+        });
+    });
+    // ============================================================
+    // REPRODUCTIONS: Failing tests demonstrating Copilot-flagged bugs
+    // ============================================================
+    describe("REPRO: bug reproductions", () => {
+        it("BUG: status listener registered with relative URL never fires because reconnect uses the normalized absolute URL", async () => {
+            // Stub window so relative URLs get normalized inside getSyncedStateClient
+            vi.stubGlobal("window", {
+                location: { protocol: "https:", host: "example.com" },
+                addEventListener: () => { },
+            });
+            const RELATIVE = "/__synced-state";
+            const statusCb = vi.fn();
+            // This mirrors what useSyncedState.ts does: register listener with
+            // the same (relative) string it passes to getSyncedStateClient.
+            onStatusChange(RELATIVE, statusCb);
+            getSyncedStateClient(RELATIVE);
+            await __testing.warmUp(RELATIVE);
+            mockClients[0].simulateBreak();
+            vi.runOnlyPendingTimers();
+            // Expected: full lifecycle fires. Actual: nothing fires because
+            // reconnect notifies using "wss://example.com/__synced-state"
+            // but the listener is stored under "/__synced-state".
+            expect(statusCb).toHaveBeenCalledWith("disconnected");
+            vi.unstubAllGlobals();
+        });
+        it("BUG: unsubscribing one of two instances of the same callback removes it for all", async () => {
+            getSyncedStateClient(ENDPOINT);
+            await __testing.warmUp(ENDPOINT);
+            // Simulate two React components sharing the same onStatusChange
+            // callback (the case when createSyncedStateHook({ onStatusChange })
+            // is used by multiple component instances).
+            const sharedCallback = vi.fn();
+            const unsubA = onStatusChange(ENDPOINT, sharedCallback);
+            const unsubB = onStatusChange(ENDPOINT, sharedCallback);
+            // Component A unmounts
+            unsubA();
+            // Component B is still mounted and should still receive updates
+            mockClients[0].simulateBreak();
+            // Expected: callback fires once (for B). Actual: fires zero times
+            // because Set.delete removed the single shared entry.
+            expect(sharedCallback).toHaveBeenCalledWith("disconnected");
+            unsubB();
+        });
+        it("BUG: reconnect emits 'connected' and resets backoff even when subscribe() rejects", async () => {
+            const client = getSyncedStateClient(ENDPOINT);
+            const handler = vi.fn();
+            await client.subscribe("counter", handler);
+            // Next client's subscribe will reject
+            newWebSocketRpcSession.mockImplementationOnce(() => {
+                const c = makeMockClient();
+                c.subscribe.mockRejectedValue(new Error("subscribe failed"));
+                return c;
+            });
+            const statuses = [];
+            onStatusChange(ENDPOINT, (s) => statuses.push(s));
+            mockClients[0].simulateBreak();
+            vi.runOnlyPendingTimers();
+            await vi.runAllTimersAsync();
+            // Expected: on failure, we should NOT claim connected and NOT reset backoff.
+            // Actual: "connected" fires and backoff resets to 0 despite the failure.
+            expect(statuses).not.toContain("connected");
+            expect(__testing.backoffState.get(ENDPOINT)?.attempt ?? 0).toBeGreaterThan(0);
+        });
+    });
+});

package/dist/use-synced-state/capnweb-loader.d.mts

@@ -0,0 +1 @@
+export declare function loadCapnweb(): Promise<typeof import("capnweb")>;

package/dist/use-synced-state/capnweb-loader.mjs

@@ -0,0 +1,11 @@
+let capnwebPromise = null;
+export function loadCapnweb() {
+    if (!capnwebPromise) {
+        capnwebPromise = import("capnweb").catch(() => {
+            throw new Error('The "use-synced-state" feature requires the "capnweb" package, ' +
+                'which is not installed. Install it with your package manager ' +
+                '(e.g. `npm install capnweb` or `pnpm add capnweb`).');
+        });
+    }
+    return capnwebPromise;
+}

package/dist/use-synced-state/client-core.d.ts

@@ -1,12 +1,28 @@
+export type SyncedStateStatus = "connected" | "disconnected" | "reconnecting";
+export type StatusChangeCallback = (status: SyncedStateStatus) => void;
 export type SyncedStateClient = {
     getState(key: string): Promise<unknown>;
     setState(value: unknown, key: string): Promise<void>;
     subscribe(key: string, handler: (value: unknown) => void): Promise<void>;
     unsubscribe(key: string, handler: (value: unknown) => void): Promise<void>;
 };
+type Subscription = {
+    key: string;
+    handler: (value: unknown) => void;
+    client: SyncedStateClient;
+};
+/**
+ * Registers a callback that fires when the connection status changes for an endpoint.
+ * Returns an unsubscribe function.
+ */
+export declare const onStatusChange: (endpoint: string, callback: StatusChangeCallback) => (() => void);
+declare function getBackoffMs(attempt: number): number;
+declare function reconnect(endpoint: string, deadClient: SyncedStateClient): void;
 /**
  * Returns a cached client for the provided endpoint, creating it when necessary.
- * The client is wrapped to track subscriptions for cleanup on page reload.
+ * The returned client is a proxy that loads `capnweb` lazily on first method
+ * call — consumers that never hit `use-synced-state` pay no import cost and
+ * don't need `capnweb` installed.
  * @param endpoint Endpoint to connect to.
  * @returns RPC client instance.
  */
@@ -27,3 +43,16 @@ export declare const initSyncedStateClient: (options?: {
  * @param endpoint Endpoint associated with the injected client.
  */
 export declare const setSyncedStateClientForTesting: (client: SyncedStateClient | null, endpoint?: string) => void;
+export declare const __testing: {
+    activeSubscriptions: Set<Subscription>;
+    clientCache: Map<string, SyncedStateClient>;
+    backoffState: Map<string, {
+        attempt: number;
+        timer: ReturnType<typeof setTimeout> | null;
+    }>;
+    statusListeners: Map<string, StatusChangeCallback[]>;
+    reconnect: typeof reconnect;
+    getBackoffMs: typeof getBackoffMs;
+    warmUp(endpoint?: string): Promise<void>;
+};
+export {};

package/dist/use-synced-state/client-core.js

@@ -1,8 +1,67 @@
-import { newWebSocketRpcSession } from "capnweb";
+import { loadCapnweb } from "./capnweb-loader.mjs";
 import { DEFAULT_SYNCED_STATE_PATH } from "./constants.mjs";
+// Converts a relative endpoint like "/__synced-state" to an absolute
+// ws:// or wss:// URL so the same key is used by getSyncedStateClient,
+// onStatusChange, and reconnect notifications.
+function normalizeEndpoint(endpoint) {
+    if (endpoint.startsWith("/") && typeof window !== "undefined") {
+        const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+        return `${protocol}//${window.location.host}${endpoint}`;
+    }
+    return endpoint;
+}
 // Map of endpoint URLs to their respective clients
 const clientCache = new Map();
+// Tracks the promise of the underlying capnweb session per endpoint, exposed
+// for tests so they can `await` the lazy load before making assertions.
+const baseClientPromiseByEndpoint = new Map();
 const activeSubscriptions = new Set();
+// Status change listeners per endpoint. Uses an array rather than a Set so
+// that two components passing the same callback reference (e.g. via
+// createSyncedStateHook({ onStatusChange })) are tracked as two separate
+// registrations — unsubscribing one must not cancel the other.
+const statusListeners = new Map();
+function notifyStatusChange(endpoint, status) {
+    const listeners = statusListeners.get(endpoint);
+    if (listeners) {
+        // Snapshot so unsubscribes fired by callbacks don't skip entries.
+        for (const cb of [...listeners]) {
+            cb(status);
+        }
+    }
+}
+/**
+ * Registers a callback that fires when the connection status changes for an endpoint.
+ * Returns an unsubscribe function.
+ */
+export const onStatusChange = (endpoint, callback) => {
+    const normalized = normalizeEndpoint(endpoint);
+    let listeners = statusListeners.get(normalized);
+    if (!listeners) {
+        listeners = [];
+        statusListeners.set(normalized, listeners);
+    }
+    listeners.push(callback);
+    return () => {
+        const idx = listeners.indexOf(callback);
+        if (idx !== -1) {
+            listeners.splice(idx, 1);
+        }
+        if (listeners.length === 0) {
+            statusListeners.delete(normalized);
+        }
+    };
+};
+// Tracks per-endpoint reconnection backoff state
+const backoffState = new Map();
+const BASE_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30000;
+function getBackoffMs(attempt) {
+    const base = Math.min(BASE_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+    // Add ±25% jitter to avoid thundering herd on server restart
+    const jittered = base * (0.75 + Math.random() * 0.5);
+    return Math.round(Math.min(jittered, MAX_BACKOFF_MS));
+}
 // Set up beforeunload handler to unsubscribe all active subscriptions
 if (typeof window !== "undefined") {
     const handleBeforeUnload = () => {
@@ -22,28 +81,87 @@ if (typeof window !== "undefined") {
     };
     window.addEventListener("beforeunload", handleBeforeUnload);
 }
+function reconnect(endpoint, deadClient) {
+    // Don't schedule multiple reconnects for the same endpoint
+    const state = backoffState.get(endpoint) ?? { attempt: 0, timer: null };
+    if (state.timer !== null) {
+        return;
+    }
+    notifyStatusChange(endpoint, "disconnected");
+    const delayMs = getBackoffMs(state.attempt);
+    state.timer = setTimeout(() => {
+        state.timer = null;
+        state.attempt++;
+        backoffState.set(endpoint, state);
+        notifyStatusChange(endpoint, "reconnecting");
+        // Evict the dead client so getSyncedStateClient creates a fresh one
+        clientCache.delete(endpoint);
+        const newClient = getSyncedStateClient(endpoint);
+        // Re-subscribe everything that was on the dead client. Kick off both
+        // subscribe() and getState() synchronously so callers see the calls
+        // happen inside the timer tick, but only confirm "connected" once the
+        // subscribe promises resolve — otherwise a rejected resubscription
+        // would be masked as a successful reconnect.
+        const subscribePromises = [];
+        for (const sub of activeSubscriptions) {
+            if (sub.client === deadClient) {
+                sub.client = newClient;
+                subscribePromises.push(newClient.subscribe(sub.key, sub.handler));
+                void newClient.getState(sub.key).then((val) => {
+                    if (val !== undefined) {
+                        sub.handler(val);
+                    }
+                });
+            }
+        }
+        Promise.all(subscribePromises).then(() => {
+            backoffState.set(endpoint, { attempt: 0, timer: null });
+            notifyStatusChange(endpoint, "connected");
+        }, () => {
+            // Resubscription failed — leave the attempt counter elevated so
+            // the next reconnect uses a longer backoff, and emit disconnected
+            // again. A subsequent onRpcBroken from the new (likely dead)
+            // client will drive the next retry.
+            notifyStatusChange(endpoint, "disconnected");
+        });
+    }, delayMs);
+    backoffState.set(endpoint, state);
+}
 /**
  * Returns a cached client for the provided endpoint, creating it when necessary.
- * The client is wrapped to track subscriptions for cleanup on page reload.
+ * The returned client is a proxy that loads `capnweb` lazily on first method
+ * call — consumers that never hit `use-synced-state` pay no import cost and
+ * don't need `capnweb` installed.
  * @param endpoint Endpoint to connect to.
  * @returns RPC client instance.
  */
 export const getSyncedStateClient = (endpoint = DEFAULT_SYNCED_STATE_PATH) => {
     // Convert relative endpoint to absolute URL for environments like WKWebView
-    if (endpoint.startsWith("/") && typeof window !== "undefined") {
-        const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-        endpoint = `${protocol}//${window.location.host}${endpoint}`;
-    }
+    endpoint = normalizeEndpoint(endpoint);
     // Return existing client if already cached for this endpoint
     const existingClient = clientCache.get(endpoint);
     if (existingClient) {
         return existingClient;
     }
-    const baseClient = newWebSocketRpcSession(endpoint);
-    // Wrap the client using a Proxy to track subscriptions
-    // The RPC client uses dynamic property access, so we can't use .bind()
-    const wrappedClient = new Proxy(baseClient, {
-        get(target, prop) {
+    let baseClientPromise = null;
+    let wrappedClient;
+    const getBaseClient = () => {
+        if (!baseClientPromise) {
+            baseClientPromise = loadCapnweb().then((mod) => {
+                const session = mod.newWebSocketRpcSession(endpoint);
+                if (typeof session.onRpcBroken === "function") {
+                    session.onRpcBroken(() => {
+                        reconnect(endpoint, wrappedClient);
+                    });
+                }
+                return session;
+            });
+            baseClientPromiseByEndpoint.set(endpoint, baseClientPromise);
+        }
+        return baseClientPromise;
+    };
+    wrappedClient = new Proxy({}, {
+        get(_target, prop) {
             if (prop === "subscribe") {
                 return async (key, handler) => {
                     const subscription = {
@@ -52,7 +170,8 @@ export const getSyncedStateClient = (endpoint = DEFAULT_SYNCED_STATE_PATH) => {
                         client: wrappedClient,
                     };
                     activeSubscriptions.add(subscription);
-                    return target[prop](key, handler);
+                    const base = await getBaseClient();
+                    return base[prop](key, handler);
                 };
             }
             if (prop === "unsubscribe") {
@@ -66,15 +185,26 @@ export const getSyncedStateClient = (endpoint = DEFAULT_SYNCED_STATE_PATH) => {
                             break;
                         }
                     }
-                    return target[prop](key, handler);
+                    const base = await getBaseClient();
+                    return base[prop](key, handler);
                 };
             }
             // Pass through all other properties/methods
-            return target[prop];
+            return async (...args) => {
+                const base = await getBaseClient();
+                return base[prop](...args);
+            };
         },
     });
     // Cache the client for this endpoint
     clientCache.set(endpoint, wrappedClient);
+    // Eagerly kick off the capnweb load so the underlying session (and its
+    // onRpcBroken handler) is ready as soon as possible, and reconnect flows
+    // that don't call methods on the new client still create the replacement
+    // session. Errors are swallowed here to avoid unhandled rejections — they
+    // still surface through subsequent method calls because the rejected
+    // promise remains cached.
+    void getBaseClient().catch(() => { });
     return wrappedClient;
 };
 /**
@@ -104,5 +234,34 @@ export const setSyncedStateClientForTesting = (client, endpoint = DEFAULT_SYNCED
     else {
         clientCache.delete(endpoint);
     }
+    baseClientPromiseByEndpoint.delete(endpoint);
     activeSubscriptions.clear();
+    statusListeners.clear();
+    // Clear any pending reconnection timers
+    for (const [, state] of backoffState) {
+        if (state.timer !== null) {
+            clearTimeout(state.timer);
+        }
+    }
+    backoffState.clear();
+};
+// Exported for testing only
+export const __testing = {
+    activeSubscriptions,
+    clientCache,
+    backoffState,
+    statusListeners,
+    reconnect,
+    getBackoffMs,
+    // Awaits the eagerly-kicked-off capnweb load for a cached client. Tests
+    // should `await __testing.warmUp(endpoint)` after `getSyncedStateClient`
+    // (or after a reconnect) when they need the underlying session to exist
+    // before asserting on it.
+    async warmUp(endpoint = DEFAULT_SYNCED_STATE_PATH) {
+        const normalized = normalizeEndpoint(endpoint);
+        const promise = baseClientPromiseByEndpoint.get(normalized);
+        if (promise) {
+            await promise.catch(() => { });
+        }
+    },
 };

package/dist/use-synced-state/client.d.ts

@@ -1,3 +1,3 @@
 export { getSyncedStateClient, initSyncedStateClient, setSyncedStateClientForTesting, } from "./client-core.js";
-export type { SyncedStateClient } from "./client-core.js";
-export { useSyncedState } from "./useSyncedState.js";
+export type { SyncedStateClient, SyncedStateStatus, StatusChangeCallback, } from "./client-core.js";
+export { useSyncedState, createSyncedStateHook } from "./useSyncedState.js";

package/dist/use-synced-state/client.js

@@ -1,4 +1,4 @@
 // Re-export everything from client-core to maintain the public API
 export { getSyncedStateClient, initSyncedStateClient, setSyncedStateClientForTesting, } from "./client-core.js";
 // Re-export useSyncedState (no circular dependency since useSyncedState imports from client-core, not client)
-export { useSyncedState } from "./useSyncedState.js";
+export { useSyncedState, createSyncedStateHook } from "./useSyncedState.js";

package/dist/use-synced-state/useSyncedState.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import { type StatusChangeCallback } from "./client-core.js";
 type HookDeps = {
     useState: typeof React.useState;
     useEffect: typeof React.useEffect;
@@ -10,6 +11,7 @@ export type CreateSyncedStateHookOptions = {
     url?: string;
     roomId?: string;
     hooks?: HookDeps;
+    onStatusChange?: StatusChangeCallback;
 };
 /**
  * Builds a `useSyncedState` hook configured with optional endpoint and hook overrides.

package/dist/use-synced-state/useSyncedState.js

@@ -1,5 +1,5 @@
 import React from "react";
-import { getSyncedStateClient } from "./client-core.js";
+import { getSyncedStateClient, onStatusChange, } from "./client-core.js";
 import { DEFAULT_SYNCED_STATE_PATH } from "./constants.mjs";
 const defaultDeps = {
     useState: React.useState,
@@ -48,8 +48,12 @@ export const createSyncedStateHook = (options = {}) => {
                 }
             });
             void client.subscribe(key, handleUpdate);
+            const unsubscribeStatus = options.onStatusChange
+                ? onStatusChange(resolvedUrl, options.onStatusChange)
+                : undefined;
             return () => {
                 isActive = false;
+                unsubscribeStatus?.();
                 // Call unsubscribe when component unmounts
                 // Page reloads are handled by the beforeunload event listener in client-core.ts
                 void client.unsubscribe(key, handleUpdate).catch((error) => {