rwsdk 1.0.9 → 1.2.0

package/dist/lib/e2e/testHarness.mjs

@@ -231,10 +231,15 @@ export function createDeployment() {
                     ? match[1]
                     : Math.random().toString(36).substring(2, 15);
                 const deployResult = await runRelease(projectDir, projectDir, resourceUniqueKey);
+                // A fresh *.workers.dev subdomain can return 200 with Cloudflare's
+                // "There is nothing here yet" placeholder before the worker code
+                // propagates globally. Wait until the response body contains the
+                // rwsdk-rendered marker so tests don't run against the placeholder.
                 await poll(async () => {
                     try {
                         const response = await fetch(deployResult.url);
-                        return response.status > 0;
+                        const body = await response.text();
+                        return body.includes("__RWSDK_CONTEXT");
                     }
                     catch (e) {
                         return false;

package/dist/lib/smokeTests/codeUpdates.mjs

@@ -75,9 +75,9 @@ export async function createSmokeTestStylesheets(targetDir) {
     const urlStylesPath = join(appDir, "smokeTestUrlStyles.css");
     log("Creating smokeTestUrlStyles.css at: %s", urlStylesPath);
     await fs.writeFile(urlStylesPath, smokeTestUrlStylesCssTemplate);
-    // Modify Document.tsx to include the URL stylesheet using CSS URL import
-    const documentPath = join(appDir, "Document.tsx");
-    log("Modifying Document.tsx to include URL stylesheet at: %s", documentPath);
+    // Modify document.tsx to include the URL stylesheet using CSS URL import
+    const documentPath = join(appDir, "document.tsx");
+    log("Modifying document.tsx to include URL stylesheet at: %s", documentPath);
     try {
         const documentContent = await fs.readFile(documentPath, "utf-8");
         const s = new MagicString(documentContent);
@@ -90,14 +90,14 @@ export async function createSmokeTestStylesheets(targetDir) {
         if (headTagEnd !== -1) {
             s.appendLeft(headTagEnd, '      <link rel="stylesheet" href={smokeTestUrlStyles} />\n');
             await fs.writeFile(documentPath, s.toString(), "utf-8");
-            log("Successfully modified Document.tsx with CSS URL import pattern");
+            log("Successfully modified document.tsx with CSS URL import pattern");
         }
         else {
-            log("Could not find </head> tag in Document.tsx");
+            log("Could not find </head> tag in document.tsx");
         }
     }
     catch (e) {
-        log("Could not modify Document.tsx: %s", e);
+        log("Could not modify document.tsx: %s", e);
     }
     log("Smoke test stylesheets created successfully");
 }

package/dist/lib/smokeTests/release.mjs

@@ -9,6 +9,35 @@ export { $expect, deleteD1Database, deleteWorker, isRelatedToTest, listD1Databas
 export async function runRelease(cwd, projectDir, resourceUniqueKey) {
     return runE2ERelease(cwd, projectDir, resourceUniqueKey);
 }
+async function waitForDeploymentContent(baseUrl, { timeoutMs = 60_000, intervalMs = 2_000, } = {}) {
+    const marker = "__RWSDK_CONTEXT";
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    let lastStatus;
+    let lastBytes = 0;
+    while (Date.now() < deadline) {
+        attempt += 1;
+        try {
+            const res = await fetch(baseUrl);
+            const body = await res.text();
+            lastStatus = res.status;
+            lastBytes = body.length;
+            if (body.includes(marker)) {
+                log("Deployment content verified at %s after %d attempt(s)", baseUrl, attempt);
+                console.log(`✅ Deployment content ready at ${baseUrl} (attempt ${attempt})`);
+                return;
+            }
+            log("Attempt %d: %s returned %d (%d bytes), no app marker yet", attempt, baseUrl, res.status, body.length);
+        }
+        catch (err) {
+            log("Attempt %d: fetch failed for %s: %O", attempt, baseUrl, err);
+        }
+        await setTimeout(intervalMs);
+    }
+    throw new Error(`Deployment at ${baseUrl} did not serve app content within ${timeoutMs}ms ` +
+        `(last status ${lastStatus ?? "n/a"}, ${lastBytes} bytes). ` +
+        `Likely Cloudflare *.workers.dev propagation still in progress.`);
+}
 /**
  * Runs tests against the production deployment
  */
@@ -23,6 +52,12 @@ export async function runReleaseTest(artifactDir, resources, browserPath, headle
         await setTimeout(1000);
         // DRY: check both root and custom path
         await checkServerUp(url, "/");
+        // A fresh *.workers.dev subdomain can return 200 with Cloudflare's
+        // "There is nothing here yet" placeholder before the worker code is
+        // globally propagated. Poll the URL until the response body contains
+        // an rwsdk-rendered marker so we don't run the browser tests against
+        // the placeholder.
+        await waitForDeploymentContent(url);
         // Now run the tests with the custom path
         const testUrl = new URL("/__smoke_test", url).toString();
         await checkUrl(testUrl, artifactDir, browserPath, headless, bail, skipClient, "Production", realtime, resources.targetDir, // Add target directory parameter

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/runtime/server.d.ts

@@ -11,6 +11,34 @@ type WrappedServerFunction<TArgs extends any[] = any[], TResult = any> = {
     (...args: TArgs): Promise<TResult>;
     method?: "GET" | "POST";
 };
+export type ServerFunctionWrap = (fn: Function, args: any[], type: "action" | "query") => Promise<any>;
+/**
+ * Register a wrapper that runs around every server action and query handler.
+ *
+ * Call this once in your worker entry point. The wrapper receives the main
+ * handler function, its arguments, and the type ("action" or "query").
+ * Interruptors run *outside* the wrapper.
+ *
+ * Throws if called more than once.
+ *
+ * @example
+ * ```ts
+ * import { registerServerFunctionWrap } from "rwsdk/worker";
+ * import * as Sentry from "@sentry/cloudflare";
+ *
+ * registerServerFunctionWrap((fn, args, type) =>
+ *   Sentry.startSpan(
+ *     { name: fn.name, op: `function.rsc_${type}` },
+ *     () => fn(...args)
+ *   )
+ * );
+ * ```
+ */
+export declare function registerServerFunctionWrap(wrap: ServerFunctionWrap): void;
+/**
+ * @internal Reset the global wrap — only for tests.
+ */
+export declare function __resetServerFunctionWrap(): void;
 /**
  * Wrap a function to be used as a server query.
  *

package/dist/runtime/server.js

@@ -1,4 +1,40 @@
 import { requestInfo } from "./requestInfo/worker";
+let globalWrap;
+/**
+ * Register a wrapper that runs around every server action and query handler.
+ *
+ * Call this once in your worker entry point. The wrapper receives the main
+ * handler function, its arguments, and the type ("action" or "query").
+ * Interruptors run *outside* the wrapper.
+ *
+ * Throws if called more than once.
+ *
+ * @example
+ * ```ts
+ * import { registerServerFunctionWrap } from "rwsdk/worker";
+ * import * as Sentry from "@sentry/cloudflare";
+ *
+ * registerServerFunctionWrap((fn, args, type) =>
+ *   Sentry.startSpan(
+ *     { name: fn.name, op: `function.rsc_${type}` },
+ *     () => fn(...args)
+ *   )
+ * );
+ * ```
+ */
+export function registerServerFunctionWrap(wrap) {
+    if (globalWrap) {
+        throw new Error("registerServerFunctionWrap() has already been called. " +
+            "Only one wrapper can be registered.");
+    }
+    globalWrap = wrap;
+}
+/**
+ * @internal Reset the global wrap — only for tests.
+ */
+export function __resetServerFunctionWrap() {
+    globalWrap = undefined;
+}
 function createServerFunction(fns, mainFn, options) {
     const wrapped = async (...args) => {
         const { request, ctx } = requestInfo;
@@ -11,6 +47,9 @@ function createServerFunction(fns, mainFn, options) {
                 return result;
             }
         }
+        if (globalWrap) {
+            return globalWrap(mainFn, args, options?.__type ?? "action");
+        }
         return mainFn(...args);
     };
     wrapped.method = options?.method ?? "POST";
@@ -45,7 +84,7 @@ export function serverQuery(fnsOrFn, options) {
         mainFn = fnsOrFn;
     }
     const method = options?.method ?? "GET"; // Default to GET for query
-    const wrapped = createServerFunction(fns, mainFn, { ...options, method });
+    const wrapped = createServerFunction(fns, mainFn, { ...options, method, __type: "query" });
     wrapped.method = method;
     return wrapped;
 }
@@ -78,7 +117,7 @@ export function serverAction(fnsOrFn, options) {
         mainFn = fnsOrFn;
     }
     const method = options?.method ?? "POST"; // Default to POST for action
-    const wrapped = createServerFunction(fns, mainFn, { ...options, method });
+    const wrapped = createServerFunction(fns, mainFn, { ...options, method, __type: "action" });
     wrapped.method = method;
     return wrapped;
 }

package/dist/runtime/server.test.d.ts

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

package/dist/runtime/server.test.js

@@ -0,0 +1,130 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+let mockRequestInfo;
+vi.mock("./requestInfo/worker", () => ({
+    get requestInfo() {
+        return mockRequestInfo;
+    },
+}));
+import { serverAction, serverQuery, registerServerFunctionWrap, __resetServerFunctionWrap, } from "./server";
+describe("registerServerFunctionWrap", () => {
+    beforeEach(() => {
+        __resetServerFunctionWrap();
+        mockRequestInfo = {
+            request: new Request("https://test.example/"),
+            ctx: {},
+        };
+    });
+    it("wraps serverAction handlers", async () => {
+        const wrapSpy = vi.fn((fn, args, _type) => fn(...args));
+        registerServerFunctionWrap(wrapSpy);
+        const action = serverAction(async function createThing(name) {
+            return `created ${name}`;
+        });
+        const result = await action("foo");
+        expect(wrapSpy).toHaveBeenCalledOnce();
+        expect(wrapSpy.mock.calls[0][2]).toBe("action");
+        expect(result).toBe("created foo");
+    });
+    it("wraps serverQuery handlers", async () => {
+        const wrapSpy = vi.fn((fn, args, _type) => fn(...args));
+        registerServerFunctionWrap(wrapSpy);
+        const query = serverQuery(async function getThings() {
+            return [1, 2, 3];
+        });
+        const result = await query();
+        expect(wrapSpy).toHaveBeenCalledOnce();
+        expect(wrapSpy.mock.calls[0][2]).toBe("query");
+        expect(result).toEqual([1, 2, 3]);
+    });
+    it("passes the main function and args to the wrapper", async () => {
+        const wrapSpy = vi.fn((fn, args, _type) => fn(...args));
+        registerServerFunctionWrap(wrapSpy);
+        const action = serverAction(async function multiply(a, b) {
+            return a * b;
+        });
+        await action(3, 7);
+        const [fn, args] = wrapSpy.mock.calls[0];
+        expect(fn.name).toBe("multiply");
+        expect(args).toEqual([3, 7]);
+    });
+    it("interruptors run outside the wrapper", async () => {
+        const order = [];
+        registerServerFunctionWrap((fn, args, _type) => {
+            order.push("wrap:start");
+            const result = fn(...args);
+            order.push("wrap:end");
+            return result;
+        });
+        const interruptor = async () => {
+            order.push("interruptor");
+        };
+        const action = serverAction([
+            interruptor,
+            async function doWork() {
+                order.push("handler");
+                return "done";
+            },
+        ]);
+        await action();
+        expect(order).toEqual([
+            "interruptor",
+            "wrap:start",
+            "handler",
+            "wrap:end",
+        ]);
+    });
+    it("wrapper is not called when an interruptor short-circuits", async () => {
+        const wrapSpy = vi.fn((fn, args, _type) => fn(...args));
+        registerServerFunctionWrap(wrapSpy);
+        const action = serverAction([
+            async () => new Response("blocked", { status: 403 }),
+            async function neverCalled() {
+                return "nope";
+            },
+        ]);
+        const result = await action();
+        expect(wrapSpy).not.toHaveBeenCalled();
+        expect(result).toBeInstanceOf(Response);
+    });
+    it("throws if called more than once", () => {
+        registerServerFunctionWrap(async (fn, args) => fn(...args));
+        expect(() => {
+            registerServerFunctionWrap(async (fn, args) => fn(...args));
+        }).toThrow("registerServerFunctionWrap() has already been called");
+    });
+    it("without registration, handlers work normally", async () => {
+        const action = serverAction(async function echo(msg) {
+            return msg;
+        });
+        const result = await action("hello");
+        expect(result).toBe("hello");
+    });
+    it("wrapper can transform the return value", async () => {
+        registerServerFunctionWrap(async (fn, args, _type) => {
+            const result = await fn(...args);
+            return { wrapped: true, result };
+        });
+        const action = serverAction(async function getValue() {
+            return 42;
+        });
+        const result = await action();
+        expect(result).toEqual({ wrapped: true, result: 42 });
+    });
+    it("works with array-style serverAction (interruptors + handler)", async () => {
+        const wrapSpy = vi.fn((fn, args, _type) => fn(...args));
+        registerServerFunctionWrap(wrapSpy);
+        const action = serverAction([
+            async ({ ctx }) => {
+                ctx.authed = true;
+            },
+            async function save(data) {
+                return `saved ${data}`;
+            },
+        ]);
+        const result = await action("test");
+        expect(result).toBe("saved test");
+        expect(wrapSpy).toHaveBeenCalledOnce();
+        const [fn] = wrapSpy.mock.calls[0];
+        expect(fn.name).toBe("save");
+    });
+});

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.0.9",
+  "version": "1.2.0",
   "description": "Build fast, server-driven webapps on Cloudflare with SSR, RSC, and realtime",
   "type": "module",
   "bin": {