@rangojs/router 0.0.0-experimental.80 → 0.0.0-experimental.81

package/dist/vite/index.js

@@ -1864,7 +1864,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.80",
+  version: "0.0.0-experimental.81",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -1997,7 +1997,7 @@ var package_default = {
     tag: "experimental"
   },
   scripts: {
-    build: "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    build: "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
     prepublishOnly: "pnpm build",
     typecheck: "tsc --noEmit",
     test: "playwright test",
@@ -3260,7 +3260,7 @@ function createCjsToEsmPlugin() {
 import { createServer as createViteServer } from "vite";
 import { resolve as resolve8 } from "node:path";
 import { readFileSync as readFileSync6 } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire, register } from "node:module";
 import { pathToFileURL } from "node:url";
 
 // src/vite/plugins/virtual-stub-plugin.ts
@@ -3287,6 +3287,113 @@ function createVirtualStubPlugin() {
   };
 }
 
+// src/vite/plugins/cloudflare-protocol-stub.ts
+var VIRTUAL_PREFIX = "virtual:rango-cloudflare-stub-";
+var NULL_PREFIX = "\0" + VIRTUAL_PREFIX;
+var CF_PREFIX = "cloudflare:";
+var BUILD_ENV_GLOBAL_KEY = "__rango_build_env__";
+var SOURCE_EXT_RE = /\.[mc]?[jt]sx?$/;
+var IMPORT_NODE_TYPES = /* @__PURE__ */ new Set([
+  "ImportDeclaration",
+  "ImportExpression",
+  "ExportNamedDeclaration",
+  "ExportAllDeclaration"
+]);
+var STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = globalThis[${JSON.stringify(BUILD_ENV_GLOBAL_KEY)}] ?? {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`
+};
+var FALLBACK_STUB = `export default {};
+`;
+function createCloudflareProtocolStubPlugin() {
+  return {
+    name: "@rangojs/router:cloudflare-protocol-stub",
+    transform(code, id) {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!SOURCE_EXT_RE.test(cleanId)) return null;
+      if (!code.includes(CF_PREFIX)) return null;
+      let ast;
+      try {
+        ast = this.parse(code);
+      } catch {
+        return null;
+      }
+      const hits = [];
+      walk(ast, (node) => {
+        if (!IMPORT_NODE_TYPES.has(node.type)) return;
+        const source = node.source;
+        if (!source || source.type !== "Literal") return;
+        if (typeof source.value !== "string") return;
+        if (!source.value.startsWith(CF_PREFIX)) return;
+        if (typeof source.start !== "number" || typeof source.end !== "number")
+          return;
+        hits.push({
+          start: source.start,
+          end: source.end,
+          value: source.value
+        });
+      });
+      if (hits.length === 0) return null;
+      hits.sort((a, b) => b.start - a.start);
+      let out = code;
+      for (const hit of hits) {
+        const submodule = hit.value.slice(CF_PREFIX.length);
+        const quote = code[hit.start] === "'" ? "'" : '"';
+        out = out.slice(0, hit.start) + quote + VIRTUAL_PREFIX + submodule + quote + out.slice(hit.end);
+      }
+      return { code: out, map: null };
+    },
+    resolveId(id) {
+      if (id.startsWith(VIRTUAL_PREFIX)) {
+        return "\0" + id;
+      }
+      return null;
+    },
+    load(id) {
+      if (!id.startsWith(NULL_PREFIX)) return null;
+      const submodule = id.slice(NULL_PREFIX.length);
+      const specifier = CF_PREFIX + submodule;
+      return STUBS[specifier] ?? FALLBACK_STUB;
+    }
+  };
+}
+function walk(node, visit) {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit);
+    return;
+  }
+  const n = node;
+  if (typeof n.type !== "string") return;
+  visit(n);
+  for (const key in n) {
+    if (key === "loc" || key === "start" || key === "end" || key === "range") {
+      continue;
+    }
+    walk(n[key], visit);
+  }
+}
+
 // src/vite/plugins/client-ref-hashing.ts
 import { relative } from "node:path";
 import { createHash as createHash2 } from "node:crypto";
@@ -4682,7 +4789,22 @@ function postprocessBundle(state) {
 }
 
 // src/vite/router-discovery.ts
+var loaderHookRegistered = false;
+function ensureCloudflareProtocolLoaderRegistered() {
+  if (loaderHookRegistered) return;
+  loaderHookRegistered = true;
+  try {
+    register(
+      new URL("./plugins/cloudflare-protocol-loader-hook.mjs", import.meta.url)
+    );
+  } catch (err) {
+    console.warn(
+      `[rsc-router] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`
+    );
+  }
+}
 async function createTempRscServer(state, options = {}) {
+  ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
   return createViteServer({
     root: state.projectRoot,
@@ -4705,6 +4827,7 @@ async function createTempRscServer(state, options = {}) {
       ...options.forceBuild ? [hashClientRefs(state.projectRoot)] : [],
       createVersionPlugin(),
       createVirtualStubPlugin(),
+      createCloudflareProtocolStubPlugin(),
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : void 0),
@@ -4756,6 +4879,7 @@ async function acquireBuildEnv(s, command, mode) {
   if (!result) return false;
   s.resolvedBuildEnv = result.env;
   s.buildEnvDispose = result.dispose ?? null;
+  globalThis[BUILD_ENV_GLOBAL_KEY] = result.env;
   return true;
 }
 async function releaseBuildEnv(s) {
@@ -4768,6 +4892,7 @@ async function releaseBuildEnv(s) {
     s.buildEnvDispose = null;
   }
   s.resolvedBuildEnv = void 0;
+  delete globalThis[BUILD_ENV_GLOBAL_KEY];
 }
 function createRouterDiscoveryPlugin(entryPath, opts) {
   const s = createDiscoveryState(entryPath, opts);

package/dist/vite/plugins/cloudflare-protocol-loader-hook.mjs

@@ -0,0 +1,76 @@
+// Node ESM loader hook that resolves `cloudflare:*` imports to the same
+// stub ESM the Vite transform produces for rewritten specifiers.
+//
+// Why both? The Vite transform (cloudflare-protocol-stub.ts) catches
+// imports in modules that flow through Vite's plugin pipeline — covers
+// user source and any node_modules package Vite fetches and transforms.
+// But Vite/Rollup externalize certain packages (e.g. `partyserver`,
+// which has `import { DurableObject, env } from "cloudflare:workers"`
+// at its top level, and similar "workerd-native" libraries). Externalized
+// modules bypass the transform: Rollup hands their resolution to Node's
+// native ESM loader, which rejects URL-scheme specifiers. This loader
+// hook registers via `module.register()` from `createTempRscServer` and
+// intercepts `cloudflare:*` at Node's resolve layer — before the default
+// loader throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+//
+// Lifecycle: the hook runs in a dedicated worker thread (Node ESM loader
+// architecture) with its own globalThis. It cannot see the main thread's
+// `__rango_build_env__` bridge, so the `env` export here is always `{}`.
+// That's fine in practice — externalized libraries don't typically touch
+// `env` at module top level; they read it at request time in workerd
+// where the real module exists. Build-time prerender handlers in user
+// source DO read `env`, but they flow through the Vite transform (which
+// does bridge `env` from `getPlatformProxy()`), not through this loader.
+//
+// Keep STUBS in sync with cloudflare-protocol-stub.ts — both paths need
+// to hand out the same base classes.
+
+const CF_PREFIX = "cloudflare:";
+
+const STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively to an
+// empty default export rather than throwing. Same reasoning as
+// cloudflare-protocol-stub.ts's FALLBACK_STUB — we prioritize
+// dependency-graph resilience over strict validation, because third-party
+// packages can pull `cloudflare:*` modules we haven't curated.
+const FALLBACK_STUB = `export default {};\n`;
+
+function dataUrlFor(specifier) {
+  const body = STUBS[specifier] ?? FALLBACK_STUB;
+  return "data:text/javascript;base64," + Buffer.from(body).toString("base64");
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(CF_PREFIX)) {
+    return {
+      shortCircuit: true,
+      url: dataUrlFor(specifier),
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.80",
+  "version": "0.0.0-experimental.81",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -132,15 +132,6 @@
     "access": "public",
     "tag": "experimental"
   },
-  "scripts": {
-    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc --noEmit",
-    "test": "playwright test",
-    "test:ui": "playwright test --ui",
-    "test:unit": "vitest run",
-    "test:unit:watch": "vitest"
-  },
   "dependencies": {
     "@vitejs/plugin-rsc": "^0.5.23",
     "magic-string": "^0.30.17",
@@ -150,12 +141,12 @@
   "devDependencies": {
     "@playwright/test": "^1.49.1",
     "@types/node": "^24.10.1",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "esbuild": "^0.27.0",
     "jiti": "^2.6.1",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "tinyexec": "^0.3.2",
     "typescript": "^5.3.0",
     "vitest": "^4.0.0"
@@ -173,5 +164,13 @@
     "vite": {
       "optional": true
     }
+  },
+  "scripts": {
+    "build": "pnpm dlx esbuild src/vite/index.ts --bundle --format=esm --outfile=dist/vite/index.js --platform=node --packages=external && mkdir -p dist/vite/plugins && cp src/vite/plugins/cloudflare-protocol-loader-hook.mjs dist/vite/plugins/cloudflare-protocol-loader-hook.mjs && pnpm dlx esbuild src/bin/rango.ts --bundle --format=esm --outfile=dist/bin/rango.js --platform=node --packages=external --banner:js='#!/usr/bin/env node' && chmod +x dist/bin/rango.js",
+    "typecheck": "tsc --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest"
   }
-}
+}

package/skills/hooks/SKILL.md

@@ -593,6 +593,12 @@ function ProductPage() {
   return <h1>Product {params.productId}</h1>;
 }
 
+// Annotate the expected shape via a generic
+function ProductPageTyped() {
+  const { productId } = useParams<{ productId: string }>();
+  return <h1>Product {productId}</h1>;
+}
+
 // With selector for performance (re-renders only when selected value changes)
 function ProductId() {
   const productId = useParams((p) => p.productId);
@@ -600,7 +606,7 @@ function ProductId() {
 }
 ```
 
-Returns merged params from all matched route segments. Updates on navigation commit (not during pending navigation).
+Returns merged params from all matched route segments as a `Readonly<T>` map. Updates on navigation commit (not during pending navigation).
 
 ### usePathname()
 
@@ -685,20 +691,20 @@ See `/links` for full URL generation guide including server-side `ctx.reverse`.
 
 ## Hook Summary
 
-| Hook                 | Purpose                           | Returns                                         |
-| -------------------- | --------------------------------- | ----------------------------------------------- |
-| `useParams()`        | Route params                      | `Record<string, string>` or selected value      |
-| `usePathname()`      | Current pathname                  | `string`                                        |
-| `useSearchParams()`  | URL search params                 | `ReadonlyURLSearchParams`                       |
-| `useHref()`          | Mount-aware href                  | `(path) => string`                              |
-| `useMount()`         | Current include() mount path      | `string`                                        |
-| `useNavigation()`    | Reactive navigation state         | state, location, isStreaming                    |
-| `useRouter()`        | Stable router actions             | push, replace, refresh, prefetch, back, forward |
-| `useSegments()`      | URL path & segment IDs            | path, segmentIds, location                      |
-| `useLinkStatus()`    | Link pending state                | { pending }                                     |
-| `useLoader()`        | Loader data (strict)              | data, isLoading, error                          |
-| `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                           |
-| `useHandle()`        | Accumulated handle data           | T (handle type)                                 |
-| `useAction()`        | Server action state               | state, error, result                            |
-| `useLocationState()` | History state (persists or flash) | T \| undefined                                  |
-| `useClientCache()`   | Cache control                     | { clear }                                       |
+| Hook                 | Purpose                           | Returns                                                            |
+| -------------------- | --------------------------------- | ------------------------------------------------------------------ |
+| `useParams()`        | Route params                      | `Readonly<T>` (default `Record<string, string>`) or selected value |
+| `usePathname()`      | Current pathname                  | `string`                                                           |
+| `useSearchParams()`  | URL search params                 | `ReadonlyURLSearchParams`                                          |
+| `useHref()`          | Mount-aware href                  | `(path) => string`                                                 |
+| `useMount()`         | Current include() mount path      | `string`                                                           |
+| `useNavigation()`    | Reactive navigation state         | state, location, isStreaming                                       |
+| `useRouter()`        | Stable router actions             | push, replace, refresh, prefetch, back, forward                    |
+| `useSegments()`      | URL path & segment IDs            | path, segmentIds, location                                         |
+| `useLinkStatus()`    | Link pending state                | { pending }                                                        |
+| `useLoader()`        | Loader data (strict)              | data, isLoading, error                                             |
+| `useFetchLoader()`   | Loader with on-demand fetch       | data, load, isLoading                                              |
+| `useHandle()`        | Accumulated handle data           | T (handle type)                                                    |
+| `useAction()`        | Server action state               | state, error, result                                               |
+| `useLocationState()` | History state (persists or flash) | T \| undefined                                                     |
+| `useClientCache()`   | Cache control                     | { clear }                                                          |

package/skills/migrate-react-router/SKILL.md

@@ -635,6 +635,7 @@ layout(<ShopLayout />, () => [
 | `useLocation().pathname`                  | `usePathname()` from `@rangojs/router/client`                                    |
 | `useSearchParams()`                       | `useSearchParams()` from `@rangojs/router/client`                                |
 | `useParams()`                             | `useParams()` from `@rangojs/router/client` (or `ctx.params` in server handlers) |
+| `useParams<T>()`                          | `useParams<T>()` — same generic annotation pattern                               |
 | `<NavLink>`                               | `<Link>` with `usePathname()` for active state                                   |
 
 ### useNavigate → useRouter

package/src/browser/react/NavigationProvider.tsx

@@ -345,8 +345,12 @@ export function NavigationProvider({
         metadata: update.metadata,
       });
 
-      // Update route params
-      eventController.setParams(update.metadata.params ?? {});
+      // Update route params. Only reset when the server actually sends a params
+      // map — an absent `params` field means "no change" (e.g., legacy action
+      // responses that omitted params). Explicit `{}` still clears correctly.
+      if (update.metadata.params !== undefined) {
+        eventController.setParams(update.metadata.params);
+      }
 
       // Update handle data progressively as it streams in
       if (update.metadata.handles) {

package/src/browser/react/use-params.ts

@@ -16,11 +16,21 @@ import { shallowEqual } from "./shallow-equal.js";
  * const params = useParams();
  * // { productId: "123" }
  *
+ * // Annotate the expected shape via a generic
+ * const { productId } = useParams<{ productId: string }>();
+ *
  * // With selector
  * const productId = useParams(p => p.productId);
  * ```
  */
-export function useParams(): Record<string, string>;
+// `T extends object` (not `Record<string, string | undefined>`) so that
+// interface shapes pass the constraint — interfaces lack an implicit
+// index signature and would otherwise be rejected. The generic is a
+// shape annotation, not a runtime check; the body always returns the
+// underlying params map unchanged.
+export function useParams<
+  T extends object = Record<string, string>,
+>(): Readonly<T>;
 export function useParams<T>(
   selector: (params: Record<string, string>) => T,
 ): T;

package/src/rsc/progressive-enhancement.ts

@@ -248,6 +248,7 @@ export async function handleProgressiveEnhancement<TEnv>(
         segments: match.segments,
         matched: match.matched,
         diff: match.diff,
+        params: match.params,
         isPartial: false,
         rootLayout: ctx.router.rootLayout,
         handles: handleStore.stream(),
@@ -353,6 +354,7 @@ async function renderPeErrorBoundary<TEnv>(
       segments: errorResult.segments,
       matched: errorResult.matched,
       diff: errorResult.diff,
+      params: errorResult.params,
       isPartial: false,
       isError: true,
       rootLayout: ctx.router.rootLayout,

package/src/rsc/server-action.ts

@@ -213,6 +213,7 @@ export async function executeServerAction<TEnv>(
           isPartial: true,
           matched: errorResult.matched,
           diff: errorResult.diff,
+          params: errorResult.params,
           isError: true,
           handles: handleStore.stream(),
           version: ctx.version,
@@ -323,6 +324,7 @@ export async function revalidateAfterAction<TEnv>(
       isPartial: true,
       matched: matchResult.matched,
       diff: matchResult.diff,
+      params: matchResult.params,
       slots: matchResult.slots,
       handles: handleStore.stream(),
       version: ctx.version,

package/src/vite/plugins/cloudflare-protocol-loader-hook.d.mts

@@ -0,0 +1,23 @@
+export interface LoaderResolveContext {
+  parentURL?: string;
+  conditions?: readonly string[];
+  importAttributes?: Record<string, string>;
+}
+
+export interface LoaderResolveResult {
+  shortCircuit?: boolean;
+  url: string;
+  format?: "module" | "commonjs" | "json" | "wasm" | null;
+  importAttributes?: Record<string, string>;
+}
+
+export type NextResolve = (
+  specifier: string,
+  context?: LoaderResolveContext,
+) => Promise<LoaderResolveResult>;
+
+export function resolve(
+  specifier: string,
+  context: LoaderResolveContext,
+  nextResolve: NextResolve,
+): Promise<LoaderResolveResult>;

package/src/vite/plugins/cloudflare-protocol-loader-hook.mjs

@@ -0,0 +1,76 @@
+// Node ESM loader hook that resolves `cloudflare:*` imports to the same
+// stub ESM the Vite transform produces for rewritten specifiers.
+//
+// Why both? The Vite transform (cloudflare-protocol-stub.ts) catches
+// imports in modules that flow through Vite's plugin pipeline — covers
+// user source and any node_modules package Vite fetches and transforms.
+// But Vite/Rollup externalize certain packages (e.g. `partyserver`,
+// which has `import { DurableObject, env } from "cloudflare:workers"`
+// at its top level, and similar "workerd-native" libraries). Externalized
+// modules bypass the transform: Rollup hands their resolution to Node's
+// native ESM loader, which rejects URL-scheme specifiers. This loader
+// hook registers via `module.register()` from `createTempRscServer` and
+// intercepts `cloudflare:*` at Node's resolve layer — before the default
+// loader throws ERR_UNSUPPORTED_ESM_URL_SCHEME.
+//
+// Lifecycle: the hook runs in a dedicated worker thread (Node ESM loader
+// architecture) with its own globalThis. It cannot see the main thread's
+// `__rango_build_env__` bridge, so the `env` export here is always `{}`.
+// That's fine in practice — externalized libraries don't typically touch
+// `env` at module top level; they read it at request time in workerd
+// where the real module exists. Build-time prerender handlers in user
+// source DO read `env`, but they flow through the Vite transform (which
+// does bridge `env` from `getPlatformProxy()`), not through this loader.
+//
+// Keep STUBS in sync with cloudflare-protocol-stub.ts — both paths need
+// to hand out the same base classes.
+
+const CF_PREFIX = "cloudflare:";
+
+const STUBS = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively to an
+// empty default export rather than throwing. Same reasoning as
+// cloudflare-protocol-stub.ts's FALLBACK_STUB — we prioritize
+// dependency-graph resilience over strict validation, because third-party
+// packages can pull `cloudflare:*` modules we haven't curated.
+const FALLBACK_STUB = `export default {};\n`;
+
+function dataUrlFor(specifier) {
+  const body = STUBS[specifier] ?? FALLBACK_STUB;
+  return "data:text/javascript;base64," + Buffer.from(body).toString("base64");
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith(CF_PREFIX)) {
+    return {
+      shortCircuit: true,
+      url: dataUrlFor(specifier),
+      format: "module",
+    };
+  }
+  return nextResolve(specifier, context);
+}

package/src/vite/plugins/cloudflare-protocol-stub.ts

@@ -0,0 +1,214 @@
+import type { Plugin } from "vite";
+
+const VIRTUAL_PREFIX = "virtual:rango-cloudflare-stub-";
+const NULL_PREFIX = "\0" + VIRTUAL_PREFIX;
+const CF_PREFIX = "cloudflare:";
+
+/**
+ * `globalThis` key the `cloudflare:workers` stub reads to populate its
+ * `env` export. Router discovery sets this to the resolved `buildEnv`
+ * proxy (from `wrangler.getPlatformProxy()` when `buildEnv: "auto"` is
+ * configured, or a user-supplied object otherwise) before importing the
+ * worker entry, and clears it after discovery disposes the proxy. When
+ * unset, the stub's `env` falls back to `{}`.
+ *
+ * Using `globalThis` is the only cross-module bridge that works here:
+ * the stub's `load` hook returns source text, not a live closure, but
+ * the stub module is evaluated in the same Node process as the
+ * discovery plugin — so reading a global at module-evaluation time
+ * reaches whatever the plugin assigned there. A symbol key would be
+ * cleaner in-process but awkward to name from the stub source.
+ *
+ * @internal
+ */
+export const BUILD_ENV_GLOBAL_KEY = "__rango_build_env__";
+
+const SOURCE_EXT_RE = /\.[mc]?[jt]sx?$/;
+
+const IMPORT_NODE_TYPES = new Set([
+  "ImportDeclaration",
+  "ImportExpression",
+  "ExportNamedDeclaration",
+  "ExportAllDeclaration",
+]);
+
+// Keep in sync with `STUBS` in cloudflare-protocol-loader-hook.mjs —
+// both paths (Vite transform and Node loader) need to hand out the same
+// classes. Unknown `cloudflare:*` modules fall back to an empty default
+// export so third-party packages (e.g. the Cloudflare Agents SDK) can
+// pull them into the graph without crashing discovery. Discovery only
+// evaluates module top-level code — no handlers run — so missing named
+// exports only fail if something does `class X extends Missing {}` at
+// module scope, which is rare outside the already-stubbed classes.
+const STUBS: Record<string, string> = {
+  "cloudflare:workers": `
+export class DurableObject { constructor(_ctx, _env) {} }
+export class WorkerEntrypoint { constructor(_ctx, _env) {} }
+export class WorkflowEntrypoint { constructor(_ctx, _env) {} }
+export class RpcTarget {}
+export const env = globalThis[${JSON.stringify(BUILD_ENV_GLOBAL_KEY)}] ?? {};
+export default {};
+`,
+  "cloudflare:email": `
+export class EmailMessage { constructor(_from, _to, _raw) {} }
+export default {};
+`,
+  "cloudflare:sockets": `
+export function connect() { return {}; }
+export default {};
+`,
+  "cloudflare:workflows": `
+export class NonRetryableError extends Error {
+  constructor(message, name) { super(message); this.name = name ?? "NonRetryableError"; }
+}
+export default {};
+`,
+};
+
+// Policy: unknown `cloudflare:*` specifiers resolve permissively (empty
+// default export) rather than throwing. We prioritize dependency-graph
+// resilience over strict validation of user imports because third-party
+// packages can pull `cloudflare:*` modules we haven't curated, and
+// discovery should not fail just because those modules appear in the graph.
+// Tradeoff: unsupported user-authored `cloudflare:*` imports may fail later
+// with a generic JS/module error instead of a tailored rango-branded hint.
+// The test below pins this behavior so dependency compatibility is not
+// regressed accidentally.
+const FALLBACK_STUB = `export default {};\n`;
+
+interface AstNode {
+  type: string;
+  start?: number;
+  end?: number;
+  source?: AstNode | null;
+  value?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * Stubs `cloudflare:*` imports for the discovery-time Node Vite server.
+ *
+ * Discovery only evaluates user module top-level code — it never invokes
+ * DurableObject / WorkerEntrypoint / Workflow handlers — so empty base
+ * classes are enough for `class X extends DurableObject {}` declarations
+ * to load in Node, where `cloudflare:*` is otherwise unresolvable.
+ *
+ * Interception point: a transform hook parses source with Rollup's
+ * plugin-context parser (`this.parse`) and rewrites only real import
+ * specifier spans (`import ... from "cloudflare:xxx"`,
+ * `import("cloudflare:xxx")`, `export ... from "cloudflare:xxx"`) to a
+ * plain virtual module name (`virtual:rango-cloudflare-stub-xxx`).
+ * This must be done in transform because Vite's module runner routes
+ * URL-scheme specifiers straight to Node's native ESM loader without
+ * consulting plugin `resolveId` hooks. Using the AST (instead of a
+ * text regex or a permissive lexer) guarantees that strings,
+ * comments, and template literals that merely contain import-like
+ * text are never mutated — the walker only looks at the four import
+ * node types.
+ *
+ * The transform runs on user source AND on compiled node_modules
+ * output: real-world CF packages (e.g. the Cloudflare Agents SDK)
+ * ship compiled JS that contains `import ... from "cloudflare:email"`
+ * and similar, so excluding node_modules would leave those imports
+ * unrewritten. Cost is small because the early exit (`code.includes`)
+ * skips files with no cloudflare: mention.
+ *
+ * The plugin intentionally runs at Vite's default ordering (no
+ * `enforce: "pre"`) so TS/JSX has already been compiled to plain JS
+ * by the time `this.parse` runs — acorn doesn't understand
+ * non-standard syntax.
+ *
+ * `cloudflare:workers`, `cloudflare:email`, `cloudflare:sockets`, and
+ * `cloudflare:workflows` each get curated stubs with the well-known
+ * symbols that appear in top-level `extends` positions. Any other
+ * `cloudflare:*` specifier falls back to an empty default export —
+ * discovery never executes the handlers, so an empty module is safe
+ * for anything the graph pulls in transitively.
+ *
+ * Only registered in the discovery temp server, not the user's runtime
+ * config.
+ * @internal
+ */
+export function createCloudflareProtocolStubPlugin(): Plugin {
+  return {
+    name: "@rangojs/router:cloudflare-protocol-stub",
+    transform(code, id) {
+      const cleanId = id.split("?")[0] ?? id;
+      if (!SOURCE_EXT_RE.test(cleanId)) return null;
+      if (!code.includes(CF_PREFIX)) return null;
+
+      let ast: AstNode;
+      try {
+        ast = this.parse(code) as unknown as AstNode;
+      } catch {
+        // Malformed source — let a downstream plugin surface the parse error.
+        return null;
+      }
+
+      const hits: Array<{ start: number; end: number; value: string }> = [];
+      walk(ast, (node) => {
+        if (!IMPORT_NODE_TYPES.has(node.type)) return;
+        const source = node.source;
+        if (!source || source.type !== "Literal") return;
+        if (typeof source.value !== "string") return;
+        if (!source.value.startsWith(CF_PREFIX)) return;
+        if (typeof source.start !== "number" || typeof source.end !== "number")
+          return;
+        hits.push({
+          start: source.start,
+          end: source.end,
+          value: source.value,
+        });
+      });
+
+      if (hits.length === 0) return null;
+
+      // Rewrite from last to first so earlier offsets stay valid. `start`/
+      // `end` span the full literal including quotes, so we re-emit the
+      // same quote character around the new specifier.
+      hits.sort((a, b) => b.start - a.start);
+      let out = code;
+      for (const hit of hits) {
+        const submodule = hit.value.slice(CF_PREFIX.length);
+        const quote = code[hit.start] === "'" ? "'" : '"';
+        out =
+          out.slice(0, hit.start) +
+          quote +
+          VIRTUAL_PREFIX +
+          submodule +
+          quote +
+          out.slice(hit.end);
+      }
+      return { code: out, map: null };
+    },
+    resolveId(id) {
+      if (id.startsWith(VIRTUAL_PREFIX)) {
+        return "\0" + id;
+      }
+      return null;
+    },
+    load(id) {
+      if (!id.startsWith(NULL_PREFIX)) return null;
+      const submodule = id.slice(NULL_PREFIX.length);
+      const specifier = CF_PREFIX + submodule;
+      return STUBS[specifier] ?? FALLBACK_STUB;
+    },
+  };
+}
+
+function walk(node: unknown, visit: (n: AstNode) => void): void {
+  if (!node || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    for (const child of node) walk(child, visit);
+    return;
+  }
+  const n = node as AstNode;
+  if (typeof n.type !== "string") return;
+  visit(n);
+  for (const key in n) {
+    if (key === "loc" || key === "start" || key === "end" || key === "range") {
+      continue;
+    }
+    walk(n[key], visit);
+  }
+}

package/src/vite/router-discovery.ts

@@ -10,7 +10,7 @@ import type { Plugin } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire, register } from "node:module";
 import { pathToFileURL } from "node:url";
 import {
   formatNestedRouterConflictError,
@@ -19,6 +19,10 @@ import {
 } from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
+import {
+  BUILD_ENV_GLOBAL_KEY,
+  createCloudflareProtocolStubPlugin,
+} from "./plugins/cloudflare-protocol-stub.js";
 import {
   exposeInternalIds,
   exposeRouterId,
@@ -47,6 +51,49 @@ import { resetStagedBuildAssets } from "./utils/prerender-utils.js";
 
 export { VIRTUAL_ROUTES_MANIFEST_ID };
 
+// ============================================================================
+// Node ESM Loader Hook Registration
+// ============================================================================
+
+/**
+ * Registers a Node ESM loader hook that resolves `cloudflare:*` specifiers
+ * to a data: URL stub. Defense-in-depth alongside the Vite transform in
+ * `cloudflare-protocol-stub.ts`:
+ *
+ * - The Vite transform catches `cloudflare:*` imports in modules that flow
+ *   through Vite's plugin pipeline. That's the vast majority of cases.
+ * - The Node loader catches imports in modules that Vite/Rollup externalize
+ *   (e.g. the `partyserver` package, which has a top-level
+ *   `import { DurableObject, env } from "cloudflare:workers"` and ships
+ *   shapes plugin-rsc marks as external). Externalized modules are loaded
+ *   via Node's native ESM loader, which rejects URL schemes.
+ *
+ * Registration is process-global and one-shot. The hook only intercepts
+ * `cloudflare:*` specifiers; everything else passes through via
+ * `nextResolve()`. It runs in a separate worker thread (Node ESM loader
+ * architecture), so it can't read the `globalThis[BUILD_ENV_GLOBAL_KEY]`
+ * bridge that the Vite transform uses — the stubs served here always
+ * return `env = {}`. That's fine because externalized libraries don't
+ * typically access `env` at module top level; user source (where real
+ * `env` matters at build time) flows through the Vite transform.
+ */
+let loaderHookRegistered = false;
+function ensureCloudflareProtocolLoaderRegistered(): void {
+  if (loaderHookRegistered) return;
+  loaderHookRegistered = true;
+  try {
+    register(
+      new URL("./plugins/cloudflare-protocol-loader-hook.mjs", import.meta.url),
+    );
+  } catch (err: any) {
+    // register() requires Node 18.19+ / 20.6+. Older Node still has the
+    // Vite transform as primary defense.
+    console.warn(
+      `[rsc-router] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`,
+    );
+  }
+}
+
 // ============================================================================
 // Temp Server Factory
 // ============================================================================
@@ -66,6 +113,11 @@ async function createTempRscServer(
   state: DiscoveryState,
   options: { forceBuild?: boolean; cacheDir?: string } = {},
 ) {
+  // Install the Node ESM loader hook before any module evaluation so
+  // `cloudflare:*` specifiers in externalized/loader-delegated modules
+  // (e.g. packages plugin-rsc marks as external) resolve to stubs
+  // instead of crashing Node's native loader.
+  ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
   return createViteServer({
     root: state.projectRoot,
@@ -88,6 +140,7 @@ async function createTempRscServer(
       ...(options.forceBuild ? [hashClientRefs(state.projectRoot)] : []),
       createVersionPlugin(),
       createVirtualStubPlugin(),
+      createCloudflareProtocolStubPlugin(),
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : undefined),
@@ -177,6 +230,11 @@ async function acquireBuildEnv(
 
   s.resolvedBuildEnv = result.env;
   s.buildEnvDispose = result.dispose ?? null;
+  // Bridge the resolved env into `cloudflare:workers`'s stubbed `env`
+  // export so user code that does `import { env } from "cloudflare:workers"`
+  // sees the real bindings proxy during discovery + prerender instead of
+  // an empty object. The stub reads this global at module-evaluation time.
+  (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY] = result.env;
   return true;
 }
 
@@ -193,6 +251,7 @@ async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
     s.buildEnvDispose = null;
   }
   s.resolvedBuildEnv = undefined;
+  delete (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY];
 }
 
 /**