rwsdk 1.1.0 → 1.2.0

package/dist/runtime/lib/router.d.ts

@@ -146,7 +146,7 @@ export declare const wrapHandlerToThrowResponses: <T extends RequestInfo = Reque
  *   route("/post/:id", ({ params }) => <BlogPost id={params.id} />),
  * ])
  */
-export declare function layout<T extends RequestInfo = RequestInfo, Routes extends readonly Route<T>[] = readonly Route<T>[]>(LayoutComponent: React.FC<LayoutProps<T>>, routes: Routes): Routes;
+export declare function layout<TLayout extends RequestInfo = RequestInfo, Routes extends readonly Route<any>[] = readonly Route<any>[]>(LayoutComponent: React.FC<LayoutProps<TLayout>>, routes: Routes): Routes;
 /**
  * Wraps routes with a Document component and configures rendering options.
  *

package/dist/runtime/lib/router.test.js

@@ -1,6 +1,6 @@
 import React from "react";
 import { describe, expect, it } from "vitest";
-import { defineRoutes, except, layout, matchPath, prefix, render, route, } from "./router";
+import { defineRoutes, except, index, layout, matchPath, prefix, render, route, } from "./router";
 describe("matchPath", () => {
     // Test case 1: Static paths
     it("should match static paths", () => {
@@ -793,6 +793,48 @@ describe("defineRoutes - Request Handling Behavior", () => {
             });
             expect(await response.text()).toBe("Rendered with layouts");
         });
+        it("should accept child routes whose params are a superset of the layout's params", async () => {
+            let capturedLayoutProps = null;
+            let capturedRouteParams = null;
+            // Layout only needs { orgId }
+            const AppLayout = (props) => {
+                capturedLayoutProps = props;
+                return React.createElement("div", { className: "app-layout" }, props.children);
+            };
+            const OrgIndex = () => {
+                return React.createElement("div", {}, "Org Index");
+            };
+            // Schedule needs { orgId, date } — a superset
+            const Schedule = (requestInfo) => {
+                capturedRouteParams = requestInfo.params;
+                return React.createElement("div", {}, `${requestInfo.params.orgId} / ${requestInfo.params.date}`);
+            };
+            const routes = prefix("/:orgId", [
+                layout(AppLayout, [
+                    index(OrgIndex),
+                    prefix("/schedule", [
+                        route("/:date", Schedule),
+                    ]),
+                ]),
+            ]);
+            const router = defineRoutes([...routes]);
+            const deps = createMockDependencies();
+            deps.mockRequestInfo.request = new Request("http://localhost:3000/acme/schedule/2025-01-15/");
+            const request = new Request("http://localhost:3000/acme/schedule/2025-01-15/");
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(response.status).toBe(200);
+            expect(deps.mockRequestInfo.params).toEqual({
+                orgId: "acme",
+                date: "2025-01-15",
+            });
+        });
     });
     describe("Parameter Extraction", () => {
         it("should extract path parameters and make them available in request info", async () => {

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,284 @@
+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";
+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", () => {
+        getSyncedStateClient("wss://test.example.com/__synced-state");
+        expect(mockClients).toHaveLength(1);
+        expect(mockClients[0].onRpcBroken).toHaveBeenCalledOnce();
+    });
+    it("creates a new client after connection breaks", () => {
+        getSyncedStateClient("wss://test.example.com/__synced-state");
+        expect(mockClients).toHaveLength(1);
+        // Simulate connection break
+        mockClients[0].simulateBreak();
+        // Reconnect happens after backoff timer fires
+        vi.runOnlyPendingTimers();
+        expect(mockClients).toHaveLength(2);
+    });
+    it("does not reconnect immediately — waits for backoff", () => {
+        getSyncedStateClient("wss://test.example.com/__synced-state");
+        mockClients[0].simulateBreak();
+        // Before the timer fires, no new session yet
+        expect(mockClients).toHaveLength(1);
+        // After timer fires, reconnect happens
+        vi.runOnlyPendingTimers();
+        expect(mockClients).toHaveLength(2);
+    });
+    it("re-subscribes active subscriptions after reconnect", async () => {
+        const client = getSyncedStateClient("wss://test.example.com/__synced-state");
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        // Simulate connection break
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        // 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("wss://test.example.com/__synced-state");
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        const newClient = mockClients[1];
+        expect(newClient.getState).toHaveBeenCalledWith("counter");
+    });
+    it("calls handler with fetched state when value is not undefined", async () => {
+        const client = getSyncedStateClient("wss://test.example.com/__synced-state");
+        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();
+        // 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("wss://test.example.com/__synced-state");
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        handler.mockClear();
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        // 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("wss://test.example.com/__synced-state");
+        const handler = vi.fn();
+        await client.subscribe("counter", handler);
+        await client.unsubscribe("counter", handler);
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        const newClient = mockClients[1];
+        expect(newClient.subscribe).not.toHaveBeenCalled();
+    });
+    it("does not schedule multiple reconnects for the same endpoint", () => {
+        getSyncedStateClient("wss://test.example.com/__synced-state");
+        // Fire broken twice rapidly
+        mockClients[0].simulateBreak();
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        // 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", () => {
+        const client1 = getSyncedStateClient("wss://test.example.com/__synced-state");
+        const client2 = getSyncedStateClient("wss://test.example.com/__synced-state");
+        expect(client1).toBe(client2);
+        expect(mockClients).toHaveLength(1);
+    });
+    it("re-subscribes multiple subscriptions after reconnect", async () => {
+        const client = getSyncedStateClient("wss://test.example.com/__synced-state");
+        const handler1 = vi.fn();
+        const handler2 = vi.fn();
+        await client.subscribe("counter", handler1);
+        await client.subscribe("score", handler2);
+        mockClients[0].simulateBreak();
+        vi.runOnlyPendingTimers();
+        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", () => {
+        const ENDPOINT = "wss://test.example.com/__synced-state";
+        it("fires 'disconnected' immediately when connection breaks", () => {
+            getSyncedStateClient(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);
+            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);
+            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", () => {
+            getSyncedStateClient(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", () => {
+            getSyncedStateClient(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", () => {
+            // 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);
+            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", () => {
+            const ENDPOINT = "wss://test.example.com/__synced-state";
+            getSyncedStateClient(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 ENDPOINT = "wss://test.example.com/__synced-state";
+            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/client-core.d.ts

@@ -1,12 +1,27 @@
+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.
+ * On connection failure, automatically reconnects and re-subscribes.
  * @param endpoint Endpoint to connect to.
  * @returns RPC client instance.
  */
@@ -27,3 +42,15 @@ 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;
+};
+export {};

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

@@ -1,8 +1,64 @@
 import { newWebSocketRpcSession } from "capnweb";
 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();
 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,18 +78,62 @@ 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.
+ * On connection failure, automatically reconnects and re-subscribes.
  * @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) {
@@ -73,6 +173,12 @@ export const getSyncedStateClient = (endpoint = DEFAULT_SYNCED_STATE_PATH) => {
             return target[prop];
         },
     });
+    // Listen for connection failure and trigger reconnection
+    if (typeof baseClient.onRpcBroken === "function") {
+        baseClient.onRpcBroken(() => {
+            reconnect(endpoint, wrappedClient);
+        });
+    }
     // Cache the client for this endpoint
     clientCache.set(endpoint, wrappedClient);
     return wrappedClient;
@@ -105,4 +211,21 @@ export const setSyncedStateClientForTesting = (client, endpoint = DEFAULT_SYNCED
         clientCache.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,
 };

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) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rwsdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Build fast, server-driven webapps on Cloudflare with SSR, RSC, and realtime",
   "type": "module",
   "bin": {