rwsdk 1.2.0 → 1.2.2

package/dist/runtime/client/navigation.d.ts

@@ -1,7 +1,7 @@
 import { type NavigationCache, type NavigationCacheStorage } from "./navigationCache.js";
 export type { NavigationCache, NavigationCacheStorage };
 export interface ClientNavigationOptions {
-    onNavigate?: () => void;
+    onNavigate?: () => Promise<void> | void;
     scrollToTop?: boolean;
     scrollBehavior?: "auto" | "smooth" | "instant";
     cacheStorage?: NavigationCacheStorage;
@@ -9,6 +9,7 @@ export interface ClientNavigationOptions {
 export declare function validateClickEvent(event: MouseEvent, target: HTMLElement): boolean;
 export interface NavigateOptions {
     history?: "push" | "replace";
+    onNavigate?: () => Promise<void> | void;
     info?: {
         scrollToTop?: boolean;
         scrollBehavior?: "auto" | "smooth" | "instant";

package/dist/runtime/client/navigation.js

@@ -32,6 +32,10 @@ export function validateClickEvent(event, target) {
     return true;
 }
 let IS_CLIENT_NAVIGATION = false;
+// Scroll intent recorded at navigation time and applied post-commit in
+// onHydrated, so the new scroll position aligns with the new DOM rather
+// than flashing on top of the old one.
+let pendingScroll = null;
 export async function navigate(href, options = { history: "push" }) {
     if (!IS_CLIENT_NAVIGATION) {
         window.location.href = href;
@@ -45,17 +49,14 @@ export async function navigate(href, options = { history: "push" }) {
     else {
         window.history.replaceState({ path: href }, "", url);
     }
-    await globalThis.__rsc_callServer(null, null, "navigation");
     const scrollToTop = options.info?.scrollToTop ?? true;
-    const scrollBehavior = options.info?.scrollBehavior ?? "instant";
-    if (scrollToTop && history.scrollRestoration === "auto") {
-        window.scrollTo({
-            top: 0,
-            left: 0,
-            behavior: scrollBehavior,
-        });
-        saveScrollPosition(0, 0);
+    const scrollBehavior = (options.info?.scrollBehavior ??
+        "instant");
+    if (scrollToTop) {
+        pendingScroll = { x: 0, y: 0, behavior: scrollBehavior };
     }
+    await options.onNavigate?.();
+    await globalThis.__rsc_callServer(null, null, "navigation");
 }
 function saveScrollPosition(x, y) {
     window.history.replaceState({
@@ -64,6 +65,14 @@ function saveScrollPosition(x, y) {
         scrollY: y,
     }, "", window.location.href);
 }
+function applyPendingScroll() {
+    if (!pendingScroll)
+        return;
+    const { x, y, behavior } = pendingScroll;
+    pendingScroll = null;
+    window.scrollTo({ top: y, left: x, behavior });
+    saveScrollPosition(x, y);
+}
 /**
  * Initializes client-side navigation for Single Page App (SPA) behavior.
  *
@@ -107,7 +116,23 @@ function saveScrollPosition(x, y) {
  */
 export function initClientNavigation(opts = {}) {
     IS_CLIENT_NAVIGATION = true;
-    history.scrollRestoration = "auto";
+    // Take manual control of scroll restoration. With "auto", the browser
+    // restores scroll immediately on popstate — before the RSC payload has
+    // committed — which causes the old DOM to flash at the new scroll offset.
+    history.scrollRestoration = "manual";
+    // If we're booting onto an entry that already has a saved scroll (e.g.
+    // a reload after scrolling, or a back-forward cache restore), queue that
+    // position so the first commit lands us where the user left off.
+    const bootState = window.history.state;
+    if (bootState &&
+        (typeof bootState.scrollX === "number" ||
+            typeof bootState.scrollY === "number")) {
+        pendingScroll = {
+            x: bootState.scrollX ?? 0,
+            y: bootState.scrollY ?? 0,
+            behavior: "instant",
+        };
+    }
     document.addEventListener("click", async function handleClickEvent(event) {
         if (!validateClickEvent(event, event.target)) {
             return;
@@ -116,11 +141,31 @@ export function initClientNavigation(opts = {}) {
         const el = event.target;
         const a = el.closest("a");
         const href = a?.getAttribute("href");
-        await navigate(href);
+        await navigate(href, { history: "push", onNavigate: opts.onNavigate });
     }, true);
     window.addEventListener("popstate", async function handlePopState() {
+        const state = window.history.state ?? {};
+        pendingScroll = {
+            x: typeof state.scrollX === "number" ? state.scrollX : 0,
+            y: typeof state.scrollY === "number" ? state.scrollY : 0,
+            behavior: "instant",
+        };
+        await opts.onNavigate?.();
         await globalThis.__rsc_callServer(null, null, "navigation");
     });
+    // Persist the user's scroll position on the current history entry so
+    // that back/forward navigation can restore it accurately once the new
+    // RSC payload commits. Coalesced via rAF to avoid thrashing replaceState.
+    let scrollSaveScheduled = false;
+    window.addEventListener("scroll", () => {
+        if (scrollSaveScheduled)
+            return;
+        scrollSaveScheduled = true;
+        requestAnimationFrame(() => {
+            scrollSaveScheduled = false;
+            saveScrollPosition(window.scrollX, window.scrollY);
+        });
+    }, { passive: true });
     function handleResponse(response) {
         if (response.status >= 300 && response.status < 400) {
             const location = response.headers.get("Location");
@@ -142,6 +187,10 @@ export function initClientNavigation(opts = {}) {
         globalThis.__rsc_cacheStorage = opts.cacheStorage;
     }
     function onHydrated() {
+        // Apply any pending scroll intent now that React has committed the new
+        // DOM — this is what prevents the scroll flash on both link-click and
+        // popstate navigations.
+        applyPendingScroll();
         // After each RSC hydration/update, increment generation and evict old caches,
         // then warm the navigation cache based on any <link rel="x-prefetch"> tags
         // rendered for the current location.

package/dist/runtime/client/navigation.test.js

@@ -75,6 +75,113 @@ describe("clientNavigation", () => {
         })).toBe(true);
     });
 });
+// Regression tests for issue #1123: onNavigate callback was never called
+// Root cause: commit c543ef7 extracted navigate() but dropped onNavigate wiring
+describe("onNavigate callback (issue #1123 regression)", () => {
+    let capturedClickHandler = null;
+    let capturedPopstateHandler = null;
+    beforeEach(() => {
+        capturedClickHandler = null;
+        capturedPopstateHandler = null;
+        vi.clearAllMocks();
+        // Capture registered event listeners so we can invoke them manually
+        vi.stubGlobal("document", {
+            addEventListener: vi.fn((event, handler) => {
+                if (event === "click")
+                    capturedClickHandler = handler;
+            }),
+        });
+        vi.stubGlobal("window", {
+            location: { href: "http://localhost/" },
+            addEventListener: vi.fn((event, handler) => {
+                if (event === "popstate")
+                    capturedPopstateHandler = handler;
+            }),
+            history: {
+                scrollRestoration: "auto",
+                pushState: vi.fn(),
+                replaceState: vi.fn(),
+                state: {},
+            },
+            scrollTo: vi.fn(),
+        });
+        vi.stubGlobal("history", {
+            scrollRestoration: "auto",
+            pushState: vi.fn(),
+            replaceState: vi.fn(),
+            state: {},
+        });
+        vi.stubGlobal("URL", class {
+            constructor(path, base) {
+                this.href = base.replace(/\/$/, "") + path;
+            }
+        });
+        // Assign directly to globalThis without replacing it (avoids breaking Vitest internals)
+        globalThis.__rsc_callServer = vi.fn().mockResolvedValue(undefined);
+    });
+    it("onNavigate is called during link click navigation", async () => {
+        const onNavigate = vi.fn();
+        initClientNavigation({ onNavigate });
+        expect(capturedClickHandler).not.toBeNull();
+        const fakeAnchor = {
+            getAttribute: (attr) => (attr === "href" ? "/about" : null),
+            hasAttribute: () => false,
+            target: "",
+            closest: (sel) => (sel === "a" ? fakeAnchor : null),
+        };
+        const fakeTarget = {
+            closest: (sel) => (sel === "a" ? fakeAnchor : null),
+        };
+        const fakeClickEvent = {
+            button: 0,
+            ctrlKey: false,
+            metaKey: false,
+            shiftKey: false,
+            altKey: false,
+            target: fakeTarget,
+            preventDefault: vi.fn(),
+        };
+        await capturedClickHandler(fakeClickEvent);
+        expect(onNavigate).toHaveBeenCalled();
+    });
+    it("onNavigate is called during popstate navigation", async () => {
+        const onNavigate = vi.fn();
+        initClientNavigation({ onNavigate });
+        expect(capturedPopstateHandler).not.toBeNull();
+        await capturedPopstateHandler();
+        expect(onNavigate).toHaveBeenCalled();
+    });
+    it("onNavigate fires after pushState but before RSC fetch", async () => {
+        const callOrder = [];
+        const onNavigate = vi.fn(() => { callOrder.push("onNavigate"); });
+        globalThis.__rsc_callServer = vi.fn(() => {
+            callOrder.push("rscCallServer");
+            return Promise.resolve();
+        });
+        initClientNavigation({ onNavigate });
+        const fakeAnchor = {
+            getAttribute: (attr) => (attr === "href" ? "/about" : null),
+            hasAttribute: () => false,
+            target: "",
+            closest: (sel) => (sel === "a" ? fakeAnchor : null),
+        };
+        const fakeTarget = {
+            closest: (sel) => (sel === "a" ? fakeAnchor : null),
+        };
+        const fakeClickEvent = {
+            button: 0,
+            ctrlKey: false,
+            metaKey: false,
+            shiftKey: false,
+            altKey: false,
+            target: fakeTarget,
+            preventDefault: vi.fn(),
+        };
+        await capturedClickHandler(fakeClickEvent);
+        expect(callOrder).toEqual(["onNavigate", "rscCallServer"]);
+        expect(window.history.pushState).toHaveBeenCalled();
+    });
+});
 describe("initClientNavigation", () => {
     beforeEach(() => {
         window.location.href = "http://localhost/";
@@ -101,4 +208,9 @@ describe("initClientNavigation", () => {
         expect(result).toBe(false);
         expect(window.location.href).toBe("http://localhost/");
     });
+    it("sets history.scrollRestoration to manual so the browser does not restore scroll before the RSC payload commits", () => {
+        history.scrollRestoration = "auto";
+        initClientNavigation();
+        expect(history.scrollRestoration).toBe("manual");
+    });
 });

package/dist/runtime/entries/types/client.d.ts

@@ -1,6 +1,6 @@
 import "./shared";
 export interface ClientNavigationOptions {
-    onNavigate?: () => void;
+    onNavigate?: () => Promise<void> | void;
     scrollToTop?: boolean;
     scrollBehavior?: "auto" | "smooth" | "instant";
 }

package/dist/runtime/lib/router.js

@@ -171,7 +171,10 @@ export function defineRoutes(routes) {
                 return renderPage(requestInfo, Element, onError);
             }
             async function handleMiddlewareResult(result) {
-                if (result instanceof Response) {
+                // NOTE: instanceof fails for cross-realm Responses (e.g. Response.json()
+                // in Cloudflare's vite dev mode constructs from a different realm's
+                // prototype). Fall back to constructor.name check.
+                if (result instanceof Response || result?.constructor?.name === 'Response') {
                     return result;
                 }
                 if (result && React.isValidElement(result)) {

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

@@ -1097,6 +1097,157 @@ describe("defineRoutes - Request Handling Behavior", () => {
             expect(await response.text()).toBe("GET Response");
         });
     });
+    describe("Cross-realm Response.json() handling", () => {
+        // In Cloudflare's vite dev mode, Response.json() constructs from a
+        // different realm's prototype, so `instanceof Response` fails.
+        // handleMiddlewareResult must recognize these as valid Responses.
+        //
+        // We simulate this by calling Response.json() and then stripping the
+        // prototype, which is exactly what a cross-realm boundary does: the
+        // object is a real Response but its [[Prototype]] comes from a different
+        // global, so `instanceof` against the local `Response` returns false.
+        function crossRealmResponseJson(data, init) {
+            // In workerd/vite dev mode, Response.json() constructs from a different
+            // realm's Response. The resulting object has constructor.name === "Response"
+            // but fails instanceof against the local Response global.
+            //
+            // We can't just swap the prototype in Node because V8's brand checks on
+            // Response internal slots would throw. Instead, wrap a real Response.json()
+            // result in a Proxy that fakes a foreign prototype chain — matching exactly
+            // what workerd produces: instanceof false, constructor.name "Response",
+            // all properties/methods functional.
+            const real = Response.json(data, init);
+            const foreignProto = { constructor: { name: "Response" } };
+            const proxy = new Proxy(real, {
+                get(target, prop, _receiver) {
+                    if (prop === "constructor")
+                        return foreignProto.constructor;
+                    const val = Reflect.get(target, prop, target);
+                    if (typeof val === "function")
+                        return val.bind(target);
+                    return val;
+                },
+                getPrototypeOf() {
+                    return foreignProto;
+                },
+            });
+            // Sanity: must match the real workerd behavior
+            if (proxy instanceof Response) {
+                throw new Error("Test setup broken: cross-realm response should not pass instanceof");
+            }
+            // TS narrows proxy to `never` after the instanceof check above (it
+            // assumes non-Response means no constructor), but the whole point is
+            // that this object IS a Response from a foreign realm.
+            if (proxy.constructor?.name !== "Response") {
+                throw new Error("Test setup broken: constructor.name should be 'Response'");
+            }
+            return proxy;
+        }
+        it("should return cross-realm Response.json() from a POST route handler", async () => {
+            const router = defineRoutes([
+                route("/api/users/", {
+                    post: () => crossRealmResponseJson({ created: true }, { status: 201 }),
+                }),
+            ]);
+            const deps = createMockDependencies();
+            const request = new Request("http://localhost:3000/api/users/", {
+                method: "POST",
+            });
+            deps.mockRequestInfo.request = request;
+            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(201);
+            expect(await response.json()).toEqual({ created: true });
+        });
+        it("should short-circuit global middleware returning cross-realm Response.json()", async () => {
+            const executionOrder = [];
+            const authMiddleware = () => {
+                executionOrder.push("authMiddleware");
+                return crossRealmResponseJson({ error: "forbidden" }, { status: 403 });
+            };
+            const PageComponent = () => {
+                executionOrder.push("PageComponent");
+                return React.createElement("div", {}, "Page");
+            };
+            const router = defineRoutes([
+                authMiddleware,
+                route("/test/", PageComponent),
+            ]);
+            const deps = createMockDependencies();
+            const request = new Request("http://localhost:3000/test/");
+            deps.mockRequestInfo.request = request;
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(executionOrder).toEqual(["authMiddleware"]);
+            expect(response.status).toBe(403);
+            expect(await response.json()).toEqual({ error: "forbidden" });
+        });
+        it("should short-circuit route-specific middleware returning cross-realm Response.json()", async () => {
+            const executionOrder = [];
+            const checkRole = () => {
+                executionOrder.push("checkRole");
+                return crossRealmResponseJson({ error: "unauthorized" }, { status: 401 });
+            };
+            const PageComponent = () => {
+                executionOrder.push("PageComponent");
+                return React.createElement("div", {}, "Page");
+            };
+            const router = defineRoutes([
+                route("/admin/", [checkRole, PageComponent]),
+            ]);
+            const deps = createMockDependencies();
+            const request = new Request("http://localhost:3000/admin/");
+            deps.mockRequestInfo.request = request;
+            const response = await router.handle({
+                request,
+                renderPage: deps.mockRenderPage,
+                getRequestInfo: deps.getRequestInfo,
+                onError: deps.onError,
+                runWithRequestInfoOverrides: deps.mockRunWithRequestInfoOverrides,
+                rscActionHandler: deps.mockRscActionHandler,
+            });
+            expect(executionOrder).toEqual(["checkRole"]);
+            expect(response.status).toBe(401);
+            expect(await response.json()).toEqual({ error: "unauthorized" });
+        });
+        it("should handle cross-realm Response.json() from an except handler", async () => {
+            const errorHandler = except(() => {
+                return crossRealmResponseJson({ error: "internal" }, { status: 500 });
+            });
+            const PageComponent = () => {
+                throw new Error("boom");
+            };
+            const router = defineRoutes([
+                errorHandler,
+                route("/test/", PageComponent),
+            ]);
+            const deps = createMockDependencies();
+            const request = new Request("http://localhost:3000/test/");
+            deps.mockRequestInfo.request = request;
+            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(500);
+            expect(await response.json()).toEqual({ error: "internal" });
+        });
+    });
     describe("Edge Cases", () => {
         it("should handle middleware-only apps with RSC actions", async () => {
             const executionOrder = [];

package/dist/use-synced-state/SyncedStateServer.d.mts

@@ -1,4 +1,4 @@
-import { RpcStub } from "capnweb";
+import type { RpcStub } from "capnweb";
 import { DurableObject } from "cloudflare:workers";
 import type { RequestInfo } from "../runtime/requestInfo/types";
 export type SyncedStateValue = unknown;

package/dist/use-synced-state/SyncedStateServer.mjs

@@ -9,9 +9,46 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _SyncedStateServer_instances, _a, _SyncedStateServer_keyHandler, _SyncedStateServer_roomHandler, _SyncedStateServer_setStateHandler, _SyncedStateServer_getStateHandler, _SyncedStateServer_subscribeHandler, _SyncedStateServer_unsubscribeHandler, _SyncedStateServer_namespace, _SyncedStateServer_durableObjectName, _SyncedStateServer_stub, _SyncedStateServer_stateStore, _SyncedStateServer_subscriptions, _SyncedStateServer_subscriptionRefs, _SyncedStateServer_getStubForHandlers, _CoordinatorApi_coordinator, _CoordinatorApi_stub;
-import { RpcTarget, newWorkersRpcResponse } from "capnweb";
+var _SyncedStateServer_instances, _a, _SyncedStateServer_keyHandler, _SyncedStateServer_roomHandler, _SyncedStateServer_setStateHandler, _SyncedStateServer_getStateHandler, _SyncedStateServer_subscribeHandler, _SyncedStateServer_unsubscribeHandler, _SyncedStateServer_namespace, _SyncedStateServer_durableObjectName, _SyncedStateServer_stub, _SyncedStateServer_stateStore, _SyncedStateServer_subscriptions, _SyncedStateServer_subscriptionRefs, _SyncedStateServer_getStubForHandlers;
 import { DurableObject } from "cloudflare:workers";
+import { loadCapnweb } from "./capnweb-loader.mjs";
+let CoordinatorApiClass = null;
+async function getCoordinatorApi() {
+    var _CoordinatorApi_coordinator, _CoordinatorApi_stub, _b;
+    const { RpcTarget, newWorkersRpcResponse } = await loadCapnweb();
+    if (!CoordinatorApiClass) {
+        CoordinatorApiClass = (_b = class CoordinatorApi extends RpcTarget {
+                constructor(coordinator, stub) {
+                    super();
+                    _CoordinatorApi_coordinator.set(this, void 0);
+                    _CoordinatorApi_stub.set(this, void 0);
+                    __classPrivateFieldSet(this, _CoordinatorApi_coordinator, coordinator, "f");
+                    __classPrivateFieldSet(this, _CoordinatorApi_stub, stub, "f");
+                    coordinator.setStub(stub);
+                }
+                _setStub(stub) {
+                    __classPrivateFieldSet(this, _CoordinatorApi_stub, stub, "f");
+                    __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").setStub(stub);
+                }
+                getState(key) {
+                    return __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").getState(key);
+                }
+                setState(value, key) {
+                    __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").setState(value, key);
+                }
+                subscribe(key, client) {
+                    __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").subscribe(key, client);
+                }
+                unsubscribe(key, client) {
+                    __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").unsubscribe(key, client);
+                }
+            },
+            _CoordinatorApi_coordinator = new WeakMap(),
+            _CoordinatorApi_stub = new WeakMap(),
+            _b);
+    }
+    return { CoordinatorApi: CoordinatorApiClass, newWorkersRpcResponse };
+}
 /**
  * Durable Object that keeps shared state for multiple clients and notifies subscribers.
  */
@@ -141,6 +178,7 @@ export class SyncedStateServer extends DurableObject {
         }
     }
     async fetch(request) {
+        const { CoordinatorApi, newWorkersRpcResponse } = await getCoordinatorApi();
         // Create a placeholder stub - it will be set by the worker via _setStub
         const api = new CoordinatorApi(this, __classPrivateFieldGet(this, _SyncedStateServer_stub, "f") || {});
         return newWorkersRpcResponse(request, api);
@@ -166,31 +204,3 @@ _SyncedStateServer_subscribeHandler = { value: null };
 _SyncedStateServer_unsubscribeHandler = { value: null };
 _SyncedStateServer_namespace = { value: null };
 _SyncedStateServer_durableObjectName = { value: "syncedState" };
-class CoordinatorApi extends RpcTarget {
-    constructor(coordinator, stub) {
-        super();
-        _CoordinatorApi_coordinator.set(this, void 0);
-        _CoordinatorApi_stub.set(this, void 0);
-        __classPrivateFieldSet(this, _CoordinatorApi_coordinator, coordinator, "f");
-        __classPrivateFieldSet(this, _CoordinatorApi_stub, stub, "f");
-        coordinator.setStub(stub);
-    }
-    // Internal method to set the stub - called from worker
-    _setStub(stub) {
-        __classPrivateFieldSet(this, _CoordinatorApi_stub, stub, "f");
-        __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").setStub(stub);
-    }
-    getState(key) {
-        return __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").getState(key);
-    }
-    setState(value, key) {
-        __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").setState(value, key);
-    }
-    subscribe(key, client) {
-        __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").subscribe(key, client);
-    }
-    unsubscribe(key, client) {
-        __classPrivateFieldGet(this, _CoordinatorApi_coordinator, "f").unsubscribe(key, client);
-    }
-}
-_CoordinatorApi_coordinator = new WeakMap(), _CoordinatorApi_stub = new WeakMap();

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

@@ -27,6 +27,7 @@ function makeMockClient() {
     return client;
 }
 import { getSyncedStateClient, onStatusChange, __testing, } from "../client-core";
+const ENDPOINT = "wss://test.example.com/__synced-state";
 describe("client-core reconnection", () => {
     beforeEach(() => {
         vi.useFakeTimers();
@@ -49,51 +50,58 @@ describe("client-core reconnection", () => {
         __testing.statusListeners.clear();
         vi.useRealTimers();
     });
-    it("registers onRpcBroken callback when creating a client", () => {
-        getSyncedStateClient("wss://test.example.com/__synced-state");
+    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", () => {
-        getSyncedStateClient("wss://test.example.com/__synced-state");
+    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", () => {
-        getSyncedStateClient("wss://test.example.com/__synced-state");
+    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("wss://test.example.com/__synced-state");
+        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("wss://test.example.com/__synced-state");
+        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("wss://test.example.com/__synced-state");
+        const client = getSyncedStateClient(ENDPOINT);
         const handler = vi.fn();
         await client.subscribe("counter", handler);
         // Next client will return a value for getState
@@ -104,37 +112,42 @@ describe("client-core reconnection", () => {
         });
         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("wss://test.example.com/__synced-state");
+        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("wss://test.example.com/__synced-state");
+        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", () => {
-        getSyncedStateClient("wss://test.example.com/__synced-state");
+    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);
     });
@@ -148,20 +161,22 @@ describe("client-core reconnection", () => {
         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");
+    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("wss://test.example.com/__synced-state");
+        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);
@@ -169,9 +184,9 @@ describe("client-core reconnection", () => {
         expect(newClient.getState).toHaveBeenCalledWith("score");
     });
     describe("onStatusChange", () => {
-        const ENDPOINT = "wss://test.example.com/__synced-state";
-        it("fires 'disconnected' immediately when connection breaks", () => {
+        it("fires 'disconnected' immediately when connection breaks", async () => {
             getSyncedStateClient(ENDPOINT);
+            await __testing.warmUp(ENDPOINT);
             const statusCb = vi.fn();
             onStatusChange(ENDPOINT, statusCb);
             mockClients[0].simulateBreak();
@@ -179,6 +194,7 @@ describe("client-core reconnection", () => {
         });
         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();
@@ -191,6 +207,7 @@ describe("client-core reconnection", () => {
         });
         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();
@@ -198,16 +215,18 @@ describe("client-core reconnection", () => {
             await vi.runAllTimersAsync();
             expect(statuses).toEqual(["disconnected", "reconnecting", "connected"]);
         });
-        it("returns an unsubscribe function that stops notifications", () => {
+        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", () => {
+        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);
@@ -221,7 +240,7 @@ describe("client-core reconnection", () => {
     // 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", () => {
+        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" },
@@ -233,6 +252,7 @@ describe("client-core reconnection", () => {
             // 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
@@ -241,9 +261,9 @@ describe("client-core reconnection", () => {
             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";
+        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).
@@ -260,7 +280,6 @@ describe("client-core reconnection", () => {
             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);

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

@@ -20,8 +20,9 @@ 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.
+ * 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.
  */
@@ -52,5 +53,6 @@ export declare const __testing: {
     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,4 +1,4 @@
-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,
@@ -12,6 +12,9 @@ function normalizeEndpoint(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
@@ -126,8 +129,9 @@ function reconnect(endpoint, deadClient) {
 }
 /**
  * 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.
+ * 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.
  */
@@ -139,11 +143,25 @@ export const getSyncedStateClient = (endpoint = DEFAULT_SYNCED_STATE_PATH) => {
     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 = {
@@ -152,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") {
@@ -166,21 +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);
+            };
         },
     });
-    // 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);
+    // 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;
 };
 /**
@@ -210,6 +234,7 @@ export const setSyncedStateClientForTesting = (client, endpoint = DEFAULT_SYNCED
     else {
         clientCache.delete(endpoint);
     }
+    baseClientPromiseByEndpoint.delete(endpoint);
     activeSubscriptions.clear();
     statusListeners.clear();
     // Clear any pending reconnection timers
@@ -228,4 +253,15 @@ export const __testing = {
     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/worker.mjs

@@ -9,91 +9,107 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
-var _SyncedStateProxy_instances, _SyncedStateProxy_stub, _SyncedStateProxy_keyHandler, _SyncedStateProxy_requestInfo, _SyncedStateProxy_transformKey, _SyncedStateProxy_callHandler;
-import { RpcTarget, newWorkersRpcResponse } from "capnweb";
 import { env } from "cloudflare:workers";
 import { route } from "../runtime/entries/router";
 import { runWithRequestInfo } from "../runtime/requestInfo/worker";
+import { loadCapnweb } from "./capnweb-loader.mjs";
 import { SyncedStateServer, } from "./SyncedStateServer.mjs";
 import { DEFAULT_SYNCED_STATE_PATH } from "./constants.mjs";
 export { SyncedStateServer };
 const DEFAULT_SYNC_STATE_NAME = "syncedState";
-class SyncedStateProxy extends RpcTarget {
-    constructor(stub, keyHandler, requestInfo) {
-        super();
-        _SyncedStateProxy_instances.add(this);
-        _SyncedStateProxy_stub.set(this, void 0);
-        _SyncedStateProxy_keyHandler.set(this, void 0);
-        _SyncedStateProxy_requestInfo.set(this, void 0);
-        __classPrivateFieldSet(this, _SyncedStateProxy_stub, stub, "f");
-        __classPrivateFieldSet(this, _SyncedStateProxy_keyHandler, keyHandler, "f");
-        __classPrivateFieldSet(this, _SyncedStateProxy_requestInfo, requestInfo, "f");
-        // Set stub in DO instance so handlers can access it
-        if (stub && typeof stub._setStub === "function") {
-            void stub._setStub(stub);
-        }
-    }
-    async getState(key) {
-        const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
-        return __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").getState(transformedKey);
-    }
-    async setState(value, key) {
-        const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
-        return __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").setState(value, transformedKey);
-    }
-    async subscribe(key, client) {
-        const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
-        const subscribeHandler = SyncedStateServer.getSubscribeHandler();
-        if (subscribeHandler) {
-            __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_callHandler).call(this, subscribeHandler, transformedKey, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f"));
-        }
-        // dup the client if it is a function; otherwise, pass it as is;
-        // this is because the client is a WebSocketRpcSession, and we need to pass a new instance of the client to the DO;
-        const clientToPass = typeof client.dup === "function" ? client.dup() : client;
-        return __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").subscribe(transformedKey, clientToPass);
-    }
-    async unsubscribe(key, client) {
-        const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
-        // Call unsubscribe handler before unsubscribe, similar to subscribe handler
-        // This ensures the handler is called even if the unsubscribe doesn't find a match
-        // or if the RPC call fails
-        const unsubscribeHandler = SyncedStateServer.getUnsubscribeHandler();
-        if (unsubscribeHandler) {
-            __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_callHandler).call(this, unsubscribeHandler, transformedKey, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f"));
-        }
-        try {
-            await __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").unsubscribe(transformedKey, client);
-        }
-        catch (error) {
-            // Ignore errors during unsubscribe - handler has already been called
-            // This prevents RPC stub disposal errors from propagating
-        }
+let SyncedStateProxyClass = null;
+async function getSyncedStateProxy() {
+    var _SyncedStateProxy_instances, _SyncedStateProxy_stub, _SyncedStateProxy_keyHandler, _SyncedStateProxy_requestInfo, _SyncedStateProxy_transformKey, _SyncedStateProxy_callHandler, _a;
+    const { RpcTarget, newWorkersRpcResponse } = await loadCapnweb();
+    if (!SyncedStateProxyClass) {
+        SyncedStateProxyClass = (_a = class SyncedStateProxy extends RpcTarget {
+                constructor(stub, keyHandler, requestInfo) {
+                    super();
+                    _SyncedStateProxy_instances.add(this);
+                    _SyncedStateProxy_stub.set(this, void 0);
+                    _SyncedStateProxy_keyHandler.set(this, void 0);
+                    _SyncedStateProxy_requestInfo.set(this, void 0);
+                    __classPrivateFieldSet(this, _SyncedStateProxy_stub, stub, "f");
+                    __classPrivateFieldSet(this, _SyncedStateProxy_keyHandler, keyHandler, "f");
+                    __classPrivateFieldSet(this, _SyncedStateProxy_requestInfo, requestInfo, "f");
+                    // Set stub in DO instance so handlers can access it
+                    if (stub && typeof stub._setStub === "function") {
+                        void stub._setStub(stub);
+                    }
+                }
+                async getState(key) {
+                    const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
+                    return __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").getState(transformedKey);
+                }
+                async setState(value, key) {
+                    const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
+                    return __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").setState(value, transformedKey);
+                }
+                async subscribe(key, client) {
+                    const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
+                    const subscribeHandler = SyncedStateServer.getSubscribeHandler();
+                    if (subscribeHandler) {
+                        __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_callHandler).call(this, subscribeHandler, transformedKey, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f"));
+                    }
+                    // dup the client if it is a function; otherwise, pass it as is;
+                    // this is because the client is a WebSocketRpcSession, and we need to pass a new instance of the client to the DO;
+                    const clientToPass = typeof client.dup === "function" ? client.dup() : client;
+                    return __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").subscribe(transformedKey, clientToPass);
+                }
+                async unsubscribe(key, client) {
+                    const transformedKey = await __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_transformKey).call(this, key);
+                    // Call unsubscribe handler before unsubscribe, similar to subscribe handler
+                    // This ensures the handler is called even if the unsubscribe doesn't find a match
+                    // or if the RPC call fails
+                    const unsubscribeHandler = SyncedStateServer.getUnsubscribeHandler();
+                    if (unsubscribeHandler) {
+                        __classPrivateFieldGet(this, _SyncedStateProxy_instances, "m", _SyncedStateProxy_callHandler).call(this, unsubscribeHandler, transformedKey, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f"));
+                    }
+                    try {
+                        await __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f").unsubscribe(transformedKey, client);
+                    }
+                    catch (error) {
+                        // Ignore errors during unsubscribe - handler has already been called
+                        // This prevents RPC stub disposal errors from propagating
+                    }
+                }
+            },
+            _SyncedStateProxy_stub = new WeakMap(),
+            _SyncedStateProxy_keyHandler = new WeakMap(),
+            _SyncedStateProxy_requestInfo = new WeakMap(),
+            _SyncedStateProxy_instances = new WeakSet(),
+            _SyncedStateProxy_transformKey = 
+            /**
+             * Transforms a key using the keyHandler, preserving async context so requestInfo.ctx is available.
+             */
+            async function _SyncedStateProxy_transformKey(key) {
+                if (!__classPrivateFieldGet(this, _SyncedStateProxy_keyHandler, "f")) {
+                    return key;
+                }
+                if (__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f")) {
+                    // Preserve async context when calling keyHandler so requestInfo.ctx is available
+                    return await runWithRequestInfo(__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f"), async () => await __classPrivateFieldGet(this, _SyncedStateProxy_keyHandler, "f")(key, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f")));
+                }
+                return await __classPrivateFieldGet(this, _SyncedStateProxy_keyHandler, "f").call(this, key, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f"));
+            },
+            _SyncedStateProxy_callHandler = function _SyncedStateProxy_callHandler(handler, key, stub) {
+                if (__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f")) {
+                    // Preserve async context when calling handler so requestInfo.ctx is available
+                    runWithRequestInfo(__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f"), () => {
+                        handler(key, stub);
+                    });
+                }
+                else {
+                    handler(key, stub);
+                }
+            },
+            _a);
     }
+    return {
+        SyncedStateProxy: SyncedStateProxyClass,
+        newWorkersRpcResponse,
+    };
 }
-_SyncedStateProxy_stub = new WeakMap(), _SyncedStateProxy_keyHandler = new WeakMap(), _SyncedStateProxy_requestInfo = new WeakMap(), _SyncedStateProxy_instances = new WeakSet(), _SyncedStateProxy_transformKey = 
-/**
- * Transforms a key using the keyHandler, preserving async context so requestInfo.ctx is available.
- */
-async function _SyncedStateProxy_transformKey(key) {
-    if (!__classPrivateFieldGet(this, _SyncedStateProxy_keyHandler, "f")) {
-        return key;
-    }
-    if (__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f")) {
-        // Preserve async context when calling keyHandler so requestInfo.ctx is available
-        return await runWithRequestInfo(__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f"), async () => await __classPrivateFieldGet(this, _SyncedStateProxy_keyHandler, "f")(key, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f")));
-    }
-    return await __classPrivateFieldGet(this, _SyncedStateProxy_keyHandler, "f").call(this, key, __classPrivateFieldGet(this, _SyncedStateProxy_stub, "f"));
-}, _SyncedStateProxy_callHandler = function _SyncedStateProxy_callHandler(handler, key, stub) {
-    if (__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f")) {
-        // Preserve async context when calling handler so requestInfo.ctx is available
-        runWithRequestInfo(__classPrivateFieldGet(this, _SyncedStateProxy_requestInfo, "f"), () => {
-            handler(key, stub);
-        });
-    }
-    else {
-        handler(key, stub);
-    }
-};
 /**
  * Registers routes that forward sync state requests to the configured Durable Object namespace.
  * @param getNamespace Function that returns the Durable Object namespace from the Worker env.
@@ -125,6 +141,7 @@ export const syncedStateRoutes = (getNamespace, options = {}) => {
         }
         const id = namespace.idFromName(resolvedRoomName);
         const coordinator = namespace.get(id);
+        const { SyncedStateProxy, newWorkersRpcResponse } = await getSyncedStateProxy();
         const proxy = new SyncedStateProxy(coordinator, keyHandler, requestInfo);
         return newWorkersRpcResponse(request, proxy);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rwsdk",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Build fast, server-driven webapps on Cloudflare with SSR, RSC, and realtime",
   "type": "module",
   "bin": {
@@ -201,6 +201,11 @@
     "vite": "^6.2.6 || 7.x",
     "wrangler": "^4.77.0"
   },
+  "peerDependenciesMeta": {
+    "capnweb": {
+      "optional": true
+    }
+  },
   "packageManager": "pnpm@10.31.0",
   "devDependencies": {
     "@cloudflare/vite-plugin": "1.31.0",