@rangojs/router 0.0.0-experimental.8a4d0430 → 0.0.0-experimental.8bcfea43

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/plugins/expose-action-id.ts

@@ -278,9 +278,7 @@ export function exposeActionId(): Plugin {
       if (!rscPluginApi) {
         throw new Error(
           "[rsc-router] Could not find @vitejs/plugin-rsc. " +
-            "@rangojs/router requires the Vite RSC plugin.\n" +
-            "The RSC plugin should be included automatically. If you disabled it with\n" +
-            "rango({ rsc: false }), add rsc() before rango() in your config.",
+            "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
 

package/src/vite/plugins/expose-id-utils.ts

@@ -19,6 +19,18 @@ export function hashId(filePath: string, exportName: string): string {
   return `${hash.slice(0, 8)}#${exportName}`;
 }
 
+/**
+ * Build a stable ID for an export binding. Uses hashed IDs in production
+ * builds (short + opaque) and readable path#name IDs in dev.
+ */
+export function makeStubId(
+  filePath: string,
+  exportName: string,
+  isBuild: boolean,
+): string {
+  return isBuild ? hashId(filePath, exportName) : `${filePath}#${exportName}`;
+}
+
 /**
  * Generate an 8-char hex hash for an inline static handler call site.
  * Uses file path and line number (plus optional index for same-line collisions).

package/src/vite/plugins/expose-ids/handler-transform.ts

@@ -138,6 +138,36 @@ export function generateExprStubs(
   };
 }
 
+/**
+ * Replace handler call expressions with lightweight stub objects on an
+ * existing MagicString. Unlike generateExprStubs (which creates its own
+ * MagicString and returns the full result), this integrates into the
+ * unified transform pipeline so all transforms share one sourcemap.
+ */
+export function stubHandlerExprs(
+  cfg: HandlerTransformConfig,
+  bindings: CreateExportBinding[],
+  s: MagicString,
+  filePath: string,
+  isBuild: boolean,
+): boolean {
+  let hasChanges = false;
+  for (const binding of bindings) {
+    const exportName = binding.exportNames[0];
+    const handlerId = isBuild
+      ? hashId(filePath, exportName)
+      : `${filePath}#${exportName}`;
+
+    s.overwrite(
+      binding.callExprStart,
+      binding.callCloseParenPos + 1,
+      `{ __brand: "${cfg.brand}", $$id: "${handlerId}" }`,
+    );
+    hasChanges = true;
+  }
+  return hasChanges;
+}
+
 /**
  * Inject $$id into export const handler calls in RSC environments.
  */

package/src/vite/plugins/expose-internal-ids.ts

@@ -2,7 +2,12 @@ import type { Plugin, ResolvedConfig } from "vite";
 import { parseAst } from "vite";
 import MagicString from "magic-string";
 import path from "node:path";
-import { normalizePath, hashId, detectImports } from "./expose-id-utils.js";
+import {
+  normalizePath,
+  hashId,
+  makeStubId,
+  detectImports,
+} from "./expose-id-utils.js";
 import {
   transformInlineHandlers,
   type VirtualHandlerEntry,
@@ -23,6 +28,7 @@ import {
   getImportedFnNames,
   collectCreateExportBindings,
   buildUnsupportedShapeWarning,
+  isExportOnlyFile,
 } from "./expose-ids/export-analysis.js";
 import {
   hasCreateLoaderImport,
@@ -34,6 +40,7 @@ import {
   transformLocationState,
   generateWholeFileStubs,
   generateExprStubs,
+  stubHandlerExprs,
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
 
@@ -385,7 +392,9 @@ ${lazyImports.join(",\n")}
         if (stubResult) return stubResult;
       }
 
-      // --- PrerenderHandler: non-RSC stub replacement ---
+      // --- PrerenderHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Prerender() calls, replace the entire file.
+      // Mixed-export files are handled in the unified pipeline below.
       if (hasPrerenderHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -397,16 +406,6 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
-
-        const exprStubs = generateExprStubs(
-          PRERENDER_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
       }
 
       // --- PrerenderHandler: RSC build module tracking ---
@@ -467,7 +466,8 @@ ${lazyImports.join(",\n")}
         }
       }
 
-      // --- StaticHandler: non-RSC stub replacement ---
+      // --- StaticHandler: non-RSC whole-file stub replacement ---
+      // When ALL exports are Static() calls, replace the entire file.
       if (hasStaticHandlerCode && !isRscEnv) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
         const bindings = getBindings(code, fnNames);
@@ -479,16 +479,212 @@ ${lazyImports.join(",\n")}
           isBuild,
         );
         if (wholeFile) return wholeFile;
+      }
 
-        const exprStubs = generateExprStubs(
-          STATIC_CONFIG,
-          bindings,
-          code,
-          filePath,
-          id,
-          isBuild,
-        );
-        if (exprStubs) return exprStubs;
+      // --- Mixed-type whole-file stub replacement (non-RSC) ---
+      // When the individual whole-file checks above fail (each only checks
+      // one type), the file has mixed exports (e.g. createLoader + Prerender).
+      // Gather ALL stub-safe bindings and check if they cover every export.
+      // If yes, replace the entire file with stubs — this strips server-only
+      // imports (node:fs, DB clients, etc.) that would crash in the browser.
+      //
+      // Only applies when the file contains Prerender/Static (the handler
+      // types that bring server-only code). Files with only loaders, handles,
+      // or locationState are handled correctly by the unified pipeline below.
+      //
+      // Loader, Prerender, and Static exports become plain { __brand, $$id }
+      // stubs. createHandle and createLocationState need their create*()
+      // functions to execute (collect registration / __rsc_ls_key), so their
+      // call expressions are preserved with only a @rangojs/router import.
+      // This strips all server-only imports while keeping the correct
+      // client contract for every export type.
+      if (!isRscEnv && (hasPrerenderHandlerCode || hasStaticHandlerCode)) {
+        const prerenderFnNames = hasPrerenderHandlerCode
+          ? getFnNames(PRERENDER_CONFIG.fnName)
+          : [];
+        const staticFnNames = hasStaticHandlerCode
+          ? getFnNames(STATIC_CONFIG.fnName)
+          : [];
+        const loaderFnNames = hasLoaderCode ? getFnNames("createLoader") : [];
+        const handleFnNames = hasHandleCode ? getFnNames("createHandle") : [];
+        const lsFnNames = hasLocationStateCode
+          ? getFnNames("createLocationState")
+          : [];
+
+        // Collect ALL recognized bindings to check export coverage
+        const allBindings: CreateExportBinding[] = [];
+        for (const fnNames of [
+          prerenderFnNames,
+          staticFnNames,
+          loaderFnNames,
+          handleFnNames,
+          lsFnNames,
+        ]) {
+          if (fnNames.length > 0) {
+            allBindings.push(...getBindings(code, fnNames));
+          }
+        }
+
+        // Check if preserved createHandle/createLocationState calls
+        // reference non-exported locals (e.g. helper functions, constants).
+        // If so, the whole-file stub would strip those locals, breaking
+        // the call. Fall through to the unified pipeline instead.
+        let canStubWholeFile =
+          allBindings.length > 0 && isExportOnlyFile(code, allBindings);
+
+        if (
+          canStubWholeFile &&
+          (handleFnNames.length > 0 || lsFnNames.length > 0)
+        ) {
+          const exportedLocals = new Set(allBindings.map((b) => b.localName));
+          // Collect bindings that would be stripped by whole-file replacement:
+          // local declarations and imported bindings from non-@rangojs/router
+          // modules. This is a regex-based heuristic — it intentionally skips
+          // edge cases (class decls, destructured bindings, combined
+          // default+named imports) since those rarely appear in route files.
+          const strippedBindings: string[] = [];
+
+          // Skip React Fast Refresh temporaries (_c, _c2, ...) which are
+          // injected by @vitejs/plugin-react in the client environment and
+          // would falsely trigger the bailout.
+          const localDeclPattern =
+            /(?:^|;|\n)\s*(?:const|let|var|function)\s+(\w+)/g;
+          let declMatch: RegExpExecArray | null;
+          while ((declMatch = localDeclPattern.exec(code)) !== null) {
+            const name = declMatch[1];
+            if (!exportedLocals.has(name) && !/^_c\d*$/.test(name)) {
+              strippedBindings.push(name);
+            }
+          }
+
+          const importPattern =
+            /import\s*\{([^}]*)\}\s*from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          let importMatch: RegExpExecArray | null;
+          while ((importMatch = importPattern.exec(code)) !== null) {
+            for (const spec of importMatch[1].split(",")) {
+              const m = spec
+                .trim()
+                .match(/^[A-Za-z_$][\w$]*(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+              if (m) strippedBindings.push(m[1] || m[0].trim().split(/\s/)[0]);
+            }
+          }
+          const defaultImportPattern =
+            /import\s+([A-Za-z_$][\w$]*)\s+from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          while ((importMatch = defaultImportPattern.exec(code)) !== null) {
+            strippedBindings.push(importMatch[1]);
+          }
+          const nsImportPattern =
+            /import\s+\*\s+as\s+([A-Za-z_$][\w$]*)\s+from\s*["'](?!@rangojs\/router)[^"']*["']/g;
+          while ((importMatch = nsImportPattern.exec(code)) !== null) {
+            strippedBindings.push(importMatch[1]);
+          }
+
+          if (strippedBindings.length > 0) {
+            const preservedBindings = allBindings.filter((b) => {
+              const fc = code.slice(b.callExprStart, b.callOpenParenPos + 1);
+              return (
+                handleFnNames.some((n) => fc.includes(n)) ||
+                lsFnNames.some((n) => fc.includes(n))
+              );
+            });
+            const strippedRe = new RegExp(
+              `\\b(?:${strippedBindings.join("|")})\\b`,
+            );
+            canStubWholeFile = !preservedBindings.some((b) => {
+              const expr = code.slice(b.callExprStart, b.callCloseParenPos + 1);
+              return strippedRe.test(expr);
+            });
+          }
+        }
+
+        if (canStubWholeFile) {
+          const lines: string[] = [];
+          const neededImports: string[] = [];
+          if (handleFnNames.length > 0) neededImports.push("createHandle");
+          if (lsFnNames.length > 0) neededImports.push("createLocationState");
+          if (neededImports.length > 0) {
+            lines.push(
+              `import { ${neededImports.join(", ")} } from "@rangojs/router";`,
+            );
+          }
+
+          for (const binding of allBindings) {
+            const fnCall = code.slice(
+              binding.callExprStart,
+              binding.callOpenParenPos + 1,
+            );
+            const isHandle = handleFnNames.some((n) => fnCall.includes(n));
+            const isLocationState = lsFnNames.some((n) => fnCall.includes(n));
+
+            // Aliases share the primary name's ID (matches server transforms).
+            const primaryName = binding.exportNames[0];
+            const stubId = makeStubId(filePath, primaryName, isBuild);
+
+            if (isHandle || isLocationState) {
+              // Rewrite alias to canonical name since the stub file only
+              // imports canonical names from @rangojs/router.
+              // Strip React Fast Refresh `_c = ` wrappers from args
+              // (e.g. `_c = (segments) => ...` → `(segments) => ...`)
+              const rawArgs = code
+                .slice(binding.callOpenParenPos + 1, binding.callCloseParenPos)
+                .replace(/\b_c\d*\s*=\s*/g, "");
+              const canonicalName = isHandle
+                ? "createHandle"
+                : "createLocationState";
+              const activeFnNames = isHandle ? handleFnNames : lsFnNames;
+
+              // Reconstruct the function name (handling aliases + generics)
+              let rawCallee = code.slice(
+                binding.callExprStart,
+                binding.callOpenParenPos,
+              );
+              for (const alias of activeFnNames) {
+                if (alias !== canonicalName && rawCallee.startsWith(alias)) {
+                  rawCallee = canonicalName + rawCallee.slice(alias.length);
+                  break;
+                }
+              }
+
+              if (isHandle) {
+                // createHandle checks __injectedId DURING the call, so $$id
+                // must be a parameter, not a post-call property assignment.
+                const idParam =
+                  binding.argCount === 0
+                    ? `undefined, "${stubId}"`
+                    : `, "${stubId}"`;
+                lines.push(
+                  `export const ${primaryName} = ${rawCallee}(${rawArgs}${idParam});`,
+                );
+                lines.push(`${primaryName}.$$id = "${stubId}";`);
+              } else {
+                lines.push(
+                  `export const ${primaryName} = ${rawCallee}(${rawArgs});`,
+                );
+                lines.push(
+                  `${primaryName}.__rsc_ls_key = "__rsc_ls_${stubId}";`,
+                );
+              }
+              for (const name of binding.exportNames.slice(1)) {
+                lines.push(`export const ${name} = ${primaryName};`);
+              }
+            } else {
+              let brand = "loader";
+              if (prerenderFnNames.some((n) => fnCall.includes(n))) {
+                brand = PRERENDER_CONFIG.brand;
+              } else if (staticFnNames.some((n) => fnCall.includes(n))) {
+                brand = STATIC_CONFIG.brand;
+              }
+              lines.push(
+                `export const ${primaryName} = { __brand: "${brand}", $$id: "${stubId}" };`,
+              );
+              for (const name of binding.exportNames.slice(1)) {
+                lines.push(`export const ${name} = ${primaryName};`);
+              }
+            }
+          }
+
+          return { code: lines.join("\n") + "\n", map: null };
+        }
       }
 
       // --- StaticHandler: RSC build module tracking ---
@@ -535,27 +731,48 @@ ${lazyImports.join(",\n")}
             isBuild,
           ) || changed;
       }
-      if (hasPrerenderHandlerCode && isRscEnv) {
+      if (hasPrerenderHandlerCode) {
         const fnNames = getFnNames(PRERENDER_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            PRERENDER_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          // Non-RSC mixed-export file: replace Prerender() calls with stubs
+          // on the shared MagicString so sourcemaps stay accurate.
+          changed =
+            stubHandlerExprs(
+              PRERENDER_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        }
       }
-      if (hasStaticHandlerCode && isRscEnv) {
+      if (hasStaticHandlerCode) {
         const fnNames = getFnNames(STATIC_CONFIG.fnName);
-        changed =
-          transformHandlerIds(
-            STATIC_CONFIG,
-            getBindings(code, fnNames),
-            s,
-            filePath,
-            isBuild,
-          ) || changed;
+        const bindings = getBindings(code, fnNames);
+        if (isRscEnv) {
+          changed =
+            transformHandlerIds(
+              STATIC_CONFIG,
+              bindings,
+              s,
+              filePath,
+              isBuild,
+            ) || changed;
+        } else {
+          changed =
+            stubHandlerExprs(STATIC_CONFIG, bindings, s, filePath, isBuild) ||
+            changed;
+        }
       }
 
       if (!changed) return;