rwsdk 1.0.0-beta.5 → 1.0.0-beta.50

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

@@ -0,0 +1,29 @@
+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>;
+};
+/**
+ * Returns a cached client for the provided endpoint, creating it when necessary.
+ * The client is wrapped to track subscriptions for cleanup on page reload.
+ * @param endpoint Endpoint to connect to.
+ * @returns RPC client instance.
+ */
+export declare const getSyncedStateClient: (endpoint?: string) => SyncedStateClient;
+/**
+ * Initializes and caches an RPC client instance for the sync state endpoint.
+ * The client is wrapped to track subscriptions for cleanup on page reload.
+ * @param options Optional endpoint override.
+ * @returns Cached client instance or `null` when running without `window`.
+ */
+export declare const initSyncedStateClient: (options?: {
+    endpoint?: string;
+}) => SyncedStateClient | null;
+/**
+ * Injects a client instance for tests and updates the cached endpoint.
+ * Also clears the subscription registry for test isolation.
+ * @param client Stub client instance or `null` to clear the cache.
+ * @param endpoint Endpoint associated with the injected client.
+ */
+export declare const setSyncedStateClientForTesting: (client: SyncedStateClient | null, endpoint?: string) => void;

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

@@ -0,0 +1,103 @@
+import { newWebSocketRpcSession } from "capnweb";
+import { DEFAULT_SYNCED_STATE_PATH } from "./constants.mjs";
+// Map of endpoint URLs to their respective clients
+const clientCache = new Map();
+const activeSubscriptions = new Set();
+// Set up beforeunload handler to unsubscribe all active subscriptions
+if (typeof window !== "undefined") {
+    const handleBeforeUnload = () => {
+        if (activeSubscriptions.size === 0) {
+            return;
+        }
+        // Unsubscribe all active subscriptions
+        // Use a synchronous approach where possible, but don't block page unload
+        const subscriptions = Array.from(activeSubscriptions);
+        activeSubscriptions.clear();
+        // Fire-and-forget unsubscribe calls - we can't await during beforeunload
+        for (const { key, handler, client } of subscriptions) {
+            void client.unsubscribe(key, handler).catch(() => {
+                // Ignore errors during page unload - the connection will be closed anyway
+            });
+        }
+    };
+    window.addEventListener("beforeunload", handleBeforeUnload);
+}
+/**
+ * Returns a cached client for the provided endpoint, creating it when necessary.
+ * The client is wrapped to track subscriptions for cleanup on page reload.
+ * @param endpoint Endpoint to connect to.
+ * @returns RPC client instance.
+ */
+export const getSyncedStateClient = (endpoint = DEFAULT_SYNCED_STATE_PATH) => {
+    // Return existing client if already cached for this endpoint
+    const existingClient = clientCache.get(endpoint);
+    if (existingClient) {
+        return existingClient;
+    }
+    const baseClient = newWebSocketRpcSession(endpoint);
+    // Wrap the client using a Proxy to track subscriptions
+    // The RPC client uses dynamic property access, so we can't use .bind()
+    const wrappedClient = new Proxy(baseClient, {
+        get(target, prop) {
+            if (prop === "subscribe") {
+                return async (key, handler) => {
+                    const subscription = {
+                        key,
+                        handler,
+                        client: wrappedClient,
+                    };
+                    activeSubscriptions.add(subscription);
+                    return target[prop](key, handler);
+                };
+            }
+            if (prop === "unsubscribe") {
+                return async (key, handler) => {
+                    // Find and remove the subscription
+                    for (const sub of activeSubscriptions) {
+                        if (sub.key === key &&
+                            sub.handler === handler &&
+                            sub.client === wrappedClient) {
+                            activeSubscriptions.delete(sub);
+                            break;
+                        }
+                    }
+                    return target[prop](key, handler);
+                };
+            }
+            // Pass through all other properties/methods
+            return target[prop];
+        },
+    });
+    // Cache the client for this endpoint
+    clientCache.set(endpoint, wrappedClient);
+    return wrappedClient;
+};
+/**
+ * Initializes and caches an RPC client instance for the sync state endpoint.
+ * The client is wrapped to track subscriptions for cleanup on page reload.
+ * @param options Optional endpoint override.
+ * @returns Cached client instance or `null` when running without `window`.
+ */
+export const initSyncedStateClient = (options = {}) => {
+    const endpoint = options.endpoint ?? DEFAULT_SYNCED_STATE_PATH;
+    if (typeof window === "undefined") {
+        return null;
+    }
+    // Use getSyncedStateClient which now handles caching via Map
+    return getSyncedStateClient(endpoint);
+};
+/**
+ * Injects a client instance for tests and updates the cached endpoint.
+ * Also clears the subscription registry for test isolation.
+ * @param client Stub client instance or `null` to clear the cache.
+ * @param endpoint Endpoint associated with the injected client.
+ */
+export const setSyncedStateClientForTesting = (client, endpoint = DEFAULT_SYNCED_STATE_PATH) => {
+    if (client) {
+        clientCache.set(endpoint, client);
+    }
+    else {
+        clientCache.delete(endpoint);
+    }
+    activeSubscriptions.clear();
+};

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

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

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

@@ -0,0 +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";

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

@@ -0,0 +1 @@
+export declare const DEFAULT_SYNCED_STATE_PATH = "/__synced-state";

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

@@ -0,0 +1 @@
+export const DEFAULT_SYNCED_STATE_PATH = "/__synced-state";

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

@@ -0,0 +1,21 @@
+import React from "react";
+type HookDeps = {
+    useState: typeof React.useState;
+    useEffect: typeof React.useEffect;
+    useRef: typeof React.useRef;
+    useCallback: typeof React.useCallback;
+};
+type Setter<T> = (value: T | ((previous: T) => T)) => void;
+export type CreateSyncedStateHookOptions = {
+    url?: string;
+    roomId?: string;
+    hooks?: HookDeps;
+};
+/**
+ * Builds a `useSyncedState` hook configured with optional endpoint and hook overrides.
+ * @param options Optional overrides for endpoint and React primitives.
+ * @returns Hook that syncs state through the sync state service.
+ */
+export declare const createSyncedStateHook: (options?: CreateSyncedStateHookOptions) => <T>(initialValue: T, key: string, roomId?: string | undefined) => [T, Setter<T>];
+export declare const useSyncedState: <T>(initialValue: T, key: string, roomId?: string | undefined) => [T, Setter<T>];
+export {};

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

@@ -0,0 +1,64 @@
+import React from "react";
+import { getSyncedStateClient } from "./client-core.js";
+import { DEFAULT_SYNCED_STATE_PATH } from "./constants.mjs";
+const defaultDeps = {
+    useState: React.useState,
+    useEffect: React.useEffect,
+    useRef: React.useRef,
+    useCallback: React.useCallback,
+};
+/**
+ * Builds a `useSyncedState` hook configured with optional endpoint and hook overrides.
+ * @param options Optional overrides for endpoint and React primitives.
+ * @returns Hook that syncs state through the sync state service.
+ */
+export const createSyncedStateHook = (options = {}) => {
+    const basePath = options.url ?? DEFAULT_SYNCED_STATE_PATH;
+    const deps = options.hooks ?? defaultDeps;
+    const { useState, useEffect, useRef, useCallback } = deps;
+    return function useSyncedState(initialValue, key, roomId = options.roomId) {
+        if (typeof window === "undefined" && !options.hooks) {
+            return [initialValue, () => { }];
+        }
+        const resolvedUrl = roomId ? `${basePath}/${roomId}` : basePath;
+        const client = getSyncedStateClient(resolvedUrl);
+        const [value, setValue] = useState(initialValue);
+        const valueRef = useRef(value);
+        valueRef.current = value;
+        const setSyncValue = useCallback((nextValue) => {
+            const resolved = typeof nextValue === "function"
+                ? nextValue(valueRef.current)
+                : nextValue;
+            setValue(resolved);
+            valueRef.current = resolved;
+            void client.setState(resolved, key);
+        }, [client, key, setValue, valueRef]);
+        useEffect(() => {
+            let isActive = true;
+            const handleUpdate = (next) => {
+                if (isActive) {
+                    setValue(next);
+                    valueRef.current = next;
+                }
+            };
+            void client.getState(key).then((existing) => {
+                if (existing !== undefined && isActive) {
+                    setValue(existing);
+                    valueRef.current = existing;
+                }
+            });
+            void client.subscribe(key, handleUpdate);
+            return () => {
+                isActive = false;
+                // 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) => {
+                    // Log but don't throw - cleanup should not prevent unmounting
+                    console.error("[useSyncedState] Error during unsubscribe:", error);
+                });
+            };
+        }, [client, key, setValue, valueRef]);
+        return [value, setSyncValue];
+    };
+};
+export const useSyncedState = createSyncedStateHook();

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

@@ -0,0 +1,14 @@
+import type { RequestInfo } from "../runtime/requestInfo/types";
+import { SyncedStateServer } from "./SyncedStateServer.mjs";
+export { SyncedStateServer };
+export type SyncedStateRouteOptions = {
+    basePath?: string;
+    durableObjectName?: string;
+};
+/**
+ * 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.
+ * @param options Optional overrides for base path and object name.
+ * @returns Router entries for the sync state API.
+ */
+export declare const syncedStateRoutes: (getNamespace: (env: Cloudflare.Env) => DurableObjectNamespace<SyncedStateServer>, options?: SyncedStateRouteOptions) => import("../runtime/lib/router.js").RouteDefinition<`/${string}`, RequestInfo<any, import("../runtime/requestInfo/types").DefaultAppContext>>[];

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

@@ -0,0 +1,135 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    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 { 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
+        }
+    }
+}
+_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.
+ * @param options Optional overrides for base path and object name.
+ * @returns Router entries for the sync state API.
+ */
+export const syncedStateRoutes = (getNamespace, options = {}) => {
+    const basePath = options.basePath ?? DEFAULT_SYNCED_STATE_PATH;
+    const durableObjectName = options.durableObjectName ?? DEFAULT_SYNC_STATE_NAME;
+    const forwardRequest = async (request, requestInfo) => {
+        const namespace = getNamespace(env);
+        // Register the namespace and DO name so handlers can access it
+        SyncedStateServer.registerNamespace(namespace, durableObjectName);
+        const keyHandler = SyncedStateServer.getKeyHandler();
+        const roomHandler = SyncedStateServer.getRoomHandler();
+        // Get the room ID from the URL parameter, or undefined if not present
+        const idParam = requestInfo.params?.id;
+        // Resolve the room name using the roomHandler if present, otherwise use the param or default
+        let resolvedRoomName;
+        if (roomHandler) {
+            resolvedRoomName = await runWithRequestInfo(requestInfo, async () => await roomHandler(idParam, requestInfo));
+        }
+        else {
+            resolvedRoomName = idParam ?? durableObjectName;
+        }
+        if (!keyHandler) {
+            const id = namespace.idFromName(resolvedRoomName);
+            return namespace.get(id).fetch(request);
+        }
+        const id = namespace.idFromName(resolvedRoomName);
+        const coordinator = namespace.get(id);
+        const proxy = new SyncedStateProxy(coordinator, keyHandler, requestInfo);
+        return newWorkersRpcResponse(request, proxy);
+    };
+    return [
+        route(basePath, (requestInfo) => forwardRequest(requestInfo.request, requestInfo)),
+        route(basePath + "/:id", (requestInfo) => forwardRequest(requestInfo.request, requestInfo)),
+    ];
+};

package/dist/vite/buildApp.mjs

@@ -1,5 +1,8 @@
 import debug from "debug";
-import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { INTERMEDIATES_OUTPUT_DIR } from "../lib/constants.mjs";
 import { runDirectivesScan } from "./runDirectivesScan.mjs";
 const log = debug("rwsdk:vite:build-app");
 /**
@@ -10,7 +13,36 @@ const log = debug("rwsdk:vite:build-app");
  * @see docs/architecture/productionBuildProcess.md
  */
 export async function buildApp({ builder, clientEntryPoints, clientFiles, serverFiles, projectRootDir, workerEntryPathname, }) {
+    await rm(resolve(projectRootDir, "dist"), { recursive: true, force: true });
     const workerEnv = builder.environments.worker;
+    // Run a pre-scan build pass to allow plugins to set up and generate code
+    // before scanning.
+    console.log("Running plugin setup pass...");
+    process.env.RWSDK_BUILD_PASS = "plugin-setup";
+    const tempEntryPath = resolve(INTERMEDIATES_OUTPUT_DIR, "temp-entry.js");
+    try {
+        if (!existsSync(dirname(tempEntryPath))) {
+            await mkdir(dirname(tempEntryPath), { recursive: true });
+        }
+        await writeFile(tempEntryPath, "");
+        const originalWorkerBuildConfig = workerEnv.config.build;
+        workerEnv.config.build = {
+            ...originalWorkerBuildConfig,
+            write: false,
+            rollupOptions: {
+                ...originalWorkerBuildConfig?.rollupOptions,
+                input: {
+                    index: tempEntryPath,
+                },
+            },
+        };
+        await builder.build(workerEnv);
+        // Restore the original config
+        workerEnv.config.build = originalWorkerBuildConfig;
+    }
+    finally {
+        await rm(tempEntryPath, { force: true });
+    }
     await runDirectivesScan({
         rootConfig: builder.config,
         environments: builder.environments,
@@ -18,7 +50,7 @@ export async function buildApp({ builder, clientEntryPoints, clientFiles, server
         serverFiles,
         entries: [workerEntryPathname],
     });
-    console.log("Building worker to discover used client components...");
+    console.log("Building worker...");
     process.env.RWSDK_BUILD_PASS = "worker";
     await builder.build(workerEnv);
     log("Used client files after worker build & filtering: %O", Array.from(clientFiles));

package/dist/vite/cloudflarePreInitPlugin.d.mts

@@ -0,0 +1,11 @@
+import type { Plugin } from "vite";
+/**
+ * Plugin that performs initialization workarounds that must run before
+ * the Cloudflare plugin's `configureServer` hook executes.
+ *
+ * Cloudflare plugin v1.15.0 executes the worker entry file during
+ * `configureServer` to detect exports, which triggers SSR code evaluation
+ * before normal server initialization completes. This plugin ensures
+ * required systems are initialized beforehand.
+ */
+export declare const cloudflarePreInitPlugin: () => Plugin;

package/dist/vite/cloudflarePreInitPlugin.mjs

@@ -0,0 +1,40 @@
+/**
+ * Plugin that performs initialization workarounds that must run before
+ * the Cloudflare plugin's `configureServer` hook executes.
+ *
+ * Cloudflare plugin v1.15.0 executes the worker entry file during
+ * `configureServer` to detect exports, which triggers SSR code evaluation
+ * before normal server initialization completes. This plugin ensures
+ * required systems are initialized beforehand.
+ */
+export const cloudflarePreInitPlugin = () => {
+    return {
+        name: "rwsdk:cloudflare-pre-init",
+        // context(justinvdm, 20 Jan 2025): This plugin must run before the
+        // Cloudflare plugin's `configureServer` hook. The Cloudflare plugin
+        // executes the worker entry file during `configureServer` to detect
+        // exports, and blocks the rest of the configureServer plugins until the
+        // request is complete. We must initialize required systems (SSR dependency
+        // optimizer + our own plugins to them, as well as CSS plugin's moduleCache)
+        // before this happens to prevent errors.
+        enforce: "pre",
+        async configureServer(server) {
+            // context(justinvdm, 20 Jan 2025): Initialize SSR dependency optimizer before
+            // Cloudflare plugin triggers SSR code evaluation. This ensures dependencies
+            // in `optimizeDeps.include` (like `react-dom/server.edge`) are correctly
+            // registered before they are discovered lazily.
+            if (server.environments.ssr?.depsOptimizer) {
+                await server.environments.ssr.depsOptimizer.init();
+            }
+            // context(justinvdm, 20 Jan 2025): Initialize CSS plugin's shared moduleCache
+            // before CSS modules are processed. The Cloudflare plugin's export detection
+            // can trigger CSS module processing in the SSR environment during `configureServer`,
+            // which happens before `initServer` runs. Vite's CSS plugin uses a shared
+            // `moduleCache` that is initialized in the client environment's `buildStart` hook.
+            // By calling `buildStart` here (which is idempotent), we ensure the CSS plugin's
+            // cache is initialized before CSS modules are processed, preventing "Cannot read
+            // properties of undefined (reading 'set')" errors.
+            await server.environments.client.pluginContainer.buildStart();
+        },
+    };
+};

package/dist/vite/configPlugin.mjs

@@ -3,6 +3,7 @@ import path, { resolve } from "node:path";
 import { INTERMEDIATE_SSR_BRIDGE_PATH } from "../lib/constants.mjs";
 import { buildApp } from "./buildApp.mjs";
 import { externalModules } from "./constants.mjs";
+import { ssrBridgeWrapPlugin } from "./ssrBridgeWrapPlugin.mjs";
 export const configPlugin = ({ silent, projectRootDir, workerEntryPathname, clientFiles, serverFiles, clientEntryPoints, }) => ({
     name: "rwsdk:config",
     config: async (_, { command }) => {
@@ -55,6 +56,7 @@ export const configPlugin = ({ silent, projectRootDir, workerEntryPathname, clie
             build: {
                 outDir: resolve(projectRootDir, "dist", "worker"),
                 emitAssets: true,
+                ssrManifest: true,
                 emptyOutDir: false,
                 ssr: true,
             },
@@ -93,6 +95,7 @@ export const configPlugin = ({ silent, projectRootDir, workerEntryPathname, clie
                             "rwsdk/constants",
                             "rwsdk/debug",
                             "rwsdk/realtime/client",
+                            "rwsdk/router",
                             "rwsdk/turnstile",
                         ],
                         entries: [],
@@ -161,22 +164,14 @@ export const configPlugin = ({ silent, projectRootDir, workerEntryPathname, clie
                                 // causes a redeclaration error. To solve this, we wrap the SSR
                                 // bundle in an exporting IIFE. This creates a scope boundary,
                                 // preventing symbol collisions while producing a valid,
-                                // tree-shakeable ES module. The inline plugin below removes the
-                                // original `export` statement from the bundle to prevent syntax
-                                // errors.
+                                // tree-shakeable ES module.
+                                //
+                                // context(justinvdm, 19 Nov 2025): We use a custom plugin
+                                // (ssrBridgeWrapPlugin) to intelligently inject the IIFE *after*
+                                // any top-level external imports, ensuring they remain valid.
                                 inlineDynamicImports: true,
-                                banner: `export const { renderHtmlStream, ssrLoadModule, ssrWebpackRequire, ssrGetModuleExport, createThenableFromReadableStream } = (function() {`,
-                                footer: `return { renderHtmlStream, ssrLoadModule, ssrWebpackRequire, ssrGetModuleExport, createThenableFromReadableStream };\n})();`,
                             },
-                            plugins: [
-                                {
-                                    name: "rwsdk:ssr-bridge-exports",
-                                    renderChunk(code) {
-                                        // Remove the original export statement as it's now handled by the banner/footer
-                                        return code.replace(/export\s*{[^}]+};?/, "");
-                                    },
-                                },
-                            ],
+                            plugins: [ssrBridgeWrapPlugin()],
                         },
                     },
                 },

package/dist/vite/constants.d.mts

@@ -1,2 +1,3 @@
 export declare const cloudflareBuiltInModules: string[];
 export declare const externalModules: string[];
+export declare const externalModulesSet: Set<string>;

package/dist/vite/constants.mjs

@@ -10,3 +10,4 @@ export const externalModules = [
     ...builtinModules,
     ...builtinModules.map((m) => `node:${m}`),
 ];
+export const externalModulesSet = new Set(externalModules);

package/dist/vite/createDirectiveLookupPlugin.mjs

@@ -42,6 +42,10 @@ export const createDirectiveLookupPlugin = async ({ projectRootDir, files, confi
             log("Development mode: %s", isDev);
         },
         configureServer(server) {
+            // context(justinvdm, 19 Nov 2025): This hook simply saves a reference
+            // to the dev server instance for use in other hooks. Unlike plugins that
+            // must run before the Cloudflare plugin to prevent startup deadlocks,
+            // its execution order is not critical, so `enforce: 'pre'` is not needed.
             devServer = server;
         },
         configEnvironment(env, viteConfig) {
@@ -97,9 +101,12 @@ export const createDirectiveLookupPlugin = async ({ projectRootDir, files, confi
                 log("Skipping optimizeDeps and aliasing for environment: %s", env);
             }
         },
-        resolveId(source) {
-            // Skip during directive scanning to avoid performance issues
-            if (process.env.RWSDK_DIRECTIVE_SCAN_ACTIVE) {
+        resolveId(source, _importer, options) {
+            // Skip during our directive scanning to avoid performance issues
+            // context(justinvdm, 20 Jan 2025): We check options.custom?.rwsdk?.directiveScan to distinguish
+            // between our directive scan (which should skip) and external calls like Cloudflare's early
+            // dispatch (which should be handled normally).
+            if (options?.custom?.rwsdk?.directiveScan === true) {
                 return;
             }
             if (source !== `${config.virtualModuleName}.js`) {
@@ -140,10 +147,6 @@ export const createDirectiveLookupPlugin = async ({ projectRootDir, files, confi
             return source;
         },
         async load(id) {
-            // Skip during directive scanning to avoid performance issues
-            if (process.env.RWSDK_DIRECTIVE_SCAN_ACTIVE) {
-                return;
-            }
             if (id === config.virtualModuleName + ".js") {
                 log("Loading %s module with %d files", config.virtualModuleName, files.size);
                 const environment = this.environment?.name || "client";

package/dist/vite/devServerTimingPlugin.mjs

@@ -6,6 +6,10 @@ export const devServerTimingPlugin = () => {
     return {
         name: "rwsdk:dev-server-timing",
         configureServer(server) {
+            // context(justinvdm, 19 Nov 2025): This hook adds a middleware for
+            // logging the time to first response. Unlike other plugins that must
+            // run before the Cloudflare plugin to prevent startup deadlocks, its
+            // execution order is not critical, so `enforce: 'pre'` is not needed.
             server.middlewares.use((_req, res, next) => {
                 if (!hasLoggedFirstResponse) {
                     res.on("finish", () => {

package/dist/vite/diagnosticAssetGraphPlugin.d.mts

@@ -0,0 +1,4 @@
+import { Plugin } from "vite";
+export declare const diagnosticAssetGraphPlugin: ({ rootDir, }: {
+    rootDir: string;
+}) => Plugin;