@rangojs/router 0.0.0-experimental.e16b7c00 → 0.0.0-experimental.e9c0b2f2

package/src/vite/discovery/prerender-collection.ts

@@ -6,13 +6,14 @@
  * generation.
  */
 
-import { contextSet } from "../../context-var.js";
+import { contextSet, hasContextVars } from "../../context-var.js";
 import {
   encodePathParam,
   substituteRouteParams,
   runWithConcurrency,
   groupByConcurrency,
   notifyOnError,
+  resolvePrerenderError,
   stageBuildAssetModule,
 } from "../utils/prerender-utils.js";
 import type { DiscoveryState } from "./state.js";
@@ -135,9 +136,7 @@ export async function expandPrerenderRoutes(
                 (performance.now() - getParamsStart).toFixed(1),
               );
               const concurrency = def.options?.concurrency ?? 1;
-              const hasBuildVars =
-                Object.keys(buildVars).length > 0 ||
-                Object.getOwnPropertySymbols(buildVars).length > 0;
+              const hasBuildVars = hasContextVars(buildVars);
               for (const params of paramsList) {
                 let url = substituteRouteParams(
                   pattern,
@@ -233,6 +232,10 @@ export async function expandPrerenderRoutes(
   const manifestEntries: Record<string, string> = {};
   let doneCount = 0;
   let skipCount = 0;
+  // #587: a render error reaches here (matchForPrerender now re-throws it rather
+  // than baking the error boundary). Default "fail" fails the build; "warn" logs
+  // and skips baking the URL.
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
   const startTotal = performance.now();
 
   // Group entries by concurrency for batched rendering.
@@ -282,10 +285,9 @@ export async function expandPrerenderRoutes(
               const interceptKey = `${result.routeName}/${paramHash}/i`;
               const interceptValue = JSON.stringify({
                 segments: [...result.segments, ...result.interceptSegments],
-                handles: {
-                  ...result.handles,
-                  ...(result.interceptHandles || {}),
-                },
+                // interceptHandles is the pre-encoded MERGED (main + intercept)
+                // handle string (the producer merged before encoding).
+                handles: result.interceptHandles ?? "",
               });
               manifestEntries[interceptKey] = stageBuildAssetModule(
                 state.projectRoot,
@@ -300,35 +302,22 @@ export async function expandPrerenderRoutes(
             doneCount++;
             break;
           } catch (err: any) {
-            if (err.name === "Skip") {
-              const elapsed = (performance.now() - startUrl).toFixed(0);
-              console.log(
-                `[rango]   SKIP ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-              );
-              skipCount++;
-              notifyOnError(
-                registry,
-                err,
-                "prerender",
-                entry.routeName,
-                entry.urlPath,
-                true,
-              );
-              break;
-            }
-            // Regular error: log, notify, and fail the build
+            // Skip, or a render error under prerender.onError "warn": skip the
+            // URL (never bake the error page, #587). A render error under the
+            // default "fail" re-throws below to fail the build.
             const elapsed = (performance.now() - startUrl).toFixed(0);
-            console.error(
-              `[rango]   FAIL ${entry.urlPath.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            notifyOnError(
+            resolvePrerenderError(
               registry,
               err,
+              prerenderOnError,
+              entry.urlPath.padEnd(40),
+              elapsed,
               "prerender",
               entry.routeName,
               entry.urlPath,
             );
-            throw err;
+            skipCount++;
+            break;
           }
         }
       },
@@ -381,6 +370,7 @@ export async function renderStaticHandlers(
   let staticDone = 0;
   let staticSkip = 0;
   let totalStaticCount = 0;
+  const prerenderOnError = state.opts?.prerenderOnError ?? "fail";
 
   // Count handlers for the log header
   for (const [, exportNames] of state.resolvedStaticModules) {
@@ -420,7 +410,8 @@ export async function renderStaticHandlers(
             !state.isBuildMode,
           );
           if (result) {
-            const hasHandles = Object.keys(result.handles).length > 0;
+            // result.handles is the pre-encoded handle string ("" when none).
+            const hasHandles = result.handles !== "";
             const exportValue = hasHandles
               ? JSON.stringify(result)
               : JSON.stringify(result.encoded);
@@ -436,23 +427,19 @@ export async function renderStaticHandlers(
             break;
           }
         } catch (err: any) {
-          if (err.name === "Skip") {
-            const elapsed = (performance.now() - startHandler).toFixed(0);
-            console.log(
-              `[rango]   SKIP ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
-            );
-            staticSkip++;
-            notifyOnError(registry, err, "static", undefined, undefined, true);
-            handled = true;
-            break;
-          }
-          // Regular error: log, notify, and fail the build
+          // Same Skip/warn/fail policy as the prerender loop (shared helper).
           const elapsed = (performance.now() - startHandler).toFixed(0);
-          console.error(
-            `[rango]   FAIL ${name.padEnd(40)} (${elapsed}ms) - ${err.message}`,
+          resolvePrerenderError(
+            registry,
+            err,
+            prerenderOnError,
+            name.padEnd(40),
+            elapsed,
+            "static",
           );
-          notifyOnError(registry, err, "static");
-          throw err;
+          staticSkip++;
+          handled = true;
+          break;
         }
       }
       if (!handled) {

package/src/vite/discovery/state.ts

@@ -19,7 +19,18 @@ export interface PluginOptions {
   /** Build-time env option from rango() config. */
   buildEnv?: import("../plugin-types.js").BuildEnvOption;
   /** Deployment preset (needed for buildEnv "auto" resolution). */
-  preset?: "node" | "cloudflare";
+  preset?: "node" | "cloudflare" | "vercel";
+  /**
+   * Route-discovery scan filter (glob include/exclude) from rango() config.
+   * Compiled into `DiscoveryState.scanFilter` once `projectRoot` is known.
+   */
+  discovery?: { include?: string[]; exclude?: string[] };
+  /**
+   * What to do when a Prerender/Static render throws at build time, from
+   * rango({ prerender: { onError } }). "fail" (default) fails the build; "warn"
+   * logs and skips baking the URL. See {@link import("../plugin-types.js").RangoOptions}.
+   */
+  prerenderOnError?: "fail" | "warn";
   /**
    * Shared context the built-in clientChunks strategy reads. Discovery populates
    * it (registered fallback hashes + single-router name) before the client build

package/src/vite/discovery/virtual-module-codegen.ts

@@ -49,7 +49,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
         );
         genFileVars.push(varName);
       } else {
-        // Routers without sourceFile: inline their manifest data directly
         routersWithoutGenFile.push({
           id: entry.id,
           manifest: entry.routeManifest,
@@ -68,14 +67,12 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       `clearAllRouterData();`,
     ];
 
-    // Flatten NamedRoutes entries: search schema objects -> plain string paths
     if (genFileVars.length > 0) {
       lines.push(
         `function __flat(r) { const o = {}; for (const [k, v] of Object.entries(r)) o[k] = typeof v === "string" ? v : v.path; return o; }`,
       );
     }
 
-    // Build the merged manifest from gen file imports + inlined data
     if (genFileVars.length === 1 && routersWithoutGenFile.length === 0) {
       lines.push(`setCachedManifest(__flat(${genFileVars[0]}));`);
     } else {
@@ -86,7 +83,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
       lines.push(`setCachedManifest({ ${parts.join(", ")} });`);
     }
 
-    // Set per-router manifests
     let genVarIdx = 0;
     for (const entry of state.perRouterManifests) {
       if (entry.sourceFile) {
@@ -114,8 +110,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     // against live router.urlpatterns, which is always correct after a
     // program reload.
 
-    // Register lazy loaders for per-router manifest modules.
-    // Each import() uses a static string literal so Rollup creates separate chunks.
     for (const routerId of state.perRouterManifestDataMap.keys()) {
       lines.push(
         `registerRouterManifestLoader(${JSON.stringify(routerId)}, () => import(${JSON.stringify(VIRTUAL_ROUTES_MANIFEST_ID + "/" + routerId)}));`,
@@ -129,9 +123,6 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
     return lines.join("\n");
   }
 
-  // No manifest: either discovery hasn't completed or no runner (Cloudflare dev).
-  // Still inject __PRERENDER_DEV_URL so the prerender store can fetch on-demand.
-  // Re-resolve origin now since the server is listening by module load time.
   if (!state.isBuildMode) {
     const origin =
       state.devServerOrigin ||
@@ -160,7 +151,6 @@ export function generatePerRouterModule(
   const lines: string[] = [];
 
   if (routerEntry?.sourceFile) {
-    // Import manifest from the gen file so HMR auto-propagates
     const routerDir = dirname(routerEntry.sourceFile);
     const routerBasename = basename(routerEntry.sourceFile).replace(
       /\.(tsx?|jsx?)$/,
@@ -189,5 +179,5 @@ export function generatePerRouterModule(
       `export const precomputedEntries = ${jsonParseExpression(entries)};`,
     );
   }
-  return lines.join("\n") || "// empty router manifest";
+  return lines.join("\n") || "";
 }

package/src/vite/index.ts

@@ -12,6 +12,8 @@ export { poke } from "./plugins/refresh-cmd.js";
 export type {
   RangoNodeOptions,
   RangoCloudflareOptions,
+  RangoVercelOptions,
+  VercelPresetOptions,
   RangoOptions,
   ClientChunks,
   ClientChunkMeta,

package/src/vite/plugin-types.ts

@@ -12,7 +12,7 @@ export interface BuildEnvFactoryContext {
   /** Vite command ("serve" for dev, "build" for production). */
   command: "serve" | "build";
   /** Router deployment preset. */
-  preset: "node" | "cloudflare";
+  preset: "node" | "cloudflare" | "vercel";
 }
 
 /**
@@ -127,16 +127,43 @@ interface RangoBaseOptions {
   clientChunks?: ClientChunks;
 
   /**
-   * Environment bindings available to Prerender and Static handlers at build
-   * time via `ctx.env`. Applies to both production build and dev on-demand
-   * prerender (`/__rsc_prerender`).
+   * Filter which files route discovery scans, by glob. Paths are matched
+   * root-relative (e.g. `src/routes/**`). `include` restricts discovery to
+   * matching files; `exclude` removes matches (the defaults cover tests, dist,
+   * coverage, etc.). Mirrors the CLI's `--include`/`--exclude`.
    *
-   * This is the build-time env supplied by the Vite plugin, not the live
-   * request env. It is shared across all prerender invocations for the build.
+   * @example
+   * rango({ discovery: { include: ["src/routes/**"] } })
+   */
+  discovery?: {
+    include?: string[];
+    exclude?: string[];
+  };
+
+  /**
+   * What to do when a `Prerender` route's or `Static` handler's render throws at
+   * build time. Otherwise the route error boundary catches it and the rendered
+   * error page is baked as the artifact, then served as an HTTP 200 — a silent,
+   * user-visible breakage (issue #587). Independent of this setting, a render may
+   * `throw new Skip()` (from `@rangojs/router`) to skip a single URL/handler.
    *
-   * @default false
+   * - `"fail"` (**default**): fail the build, naming the URL/handler and the
+   *   original render error.
+   * - `"warn"`: log a warning and skip baking the artifact — it is never served as a
+   *   baked 200 error page. `"warn"` is a build-unblock, NOT a runtime contract for
+   *   the skipped entry: the route falls through to normal resolution, which may
+   *   render live (its handler is still bundled — e.g. when nothing else baked) or
+   *   404 (once prerender handler eviction has run for other baked entries), so the
+   *   outcome depends on the rest of the build, and a skipped `Static()` handler's
+   *   evicted code can surface as an error. For DEFINED runtime behavior use
+   *   `Passthrough()` (a live fallback) or `throw new Skip()` (an intentional skip);
+   *   otherwise prefer the default `"fail"`.
+   *
+   * @default "fail"
    */
-  buildEnv?: BuildEnvOption;
+  prerender?: {
+    onError?: "fail" | "warn";
+  };
 }
 
 /**
@@ -147,6 +174,31 @@ export interface RangoNodeOptions extends RangoBaseOptions {
    * Deployment preset. Defaults to 'node' when not specified.
    */
   preset?: "node";
+
+  /**
+   * Path to a host-router entry (a module that calls `createHostRouter()` and
+   * exports the instance) to serve instead of a single `createRouter()` app.
+   * Root-relative (e.g. `"./src/worker.rsc.tsx"`).
+   *
+   * Set this when the app is a multi-app host router: auto-discovery otherwise
+   * finds the sub-apps' multiple `createRouter()` files and cannot pick an entry.
+   * When omitted, rango auto-detects a single `createHostRouter()` file if the
+   * app has several `createRouter()` files. The host module must export the
+   * `HostRouter` instance (default export or a named `hostRouter`/`router`
+   * export), not a Cloudflare-style `{ fetch }` object.
+   */
+  hostRouter?: string;
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Shared across all prerender invocations for the build.
+   *
+   * `"auto"` is Cloudflare-only (it resolves the wrangler platform proxy), so it
+   * is not accepted on the Node preset — pass an object or a factory instead.
+   *
+   * @default false
+   */
+  buildEnv?: Exclude<BuildEnvOption, "auto">;
 }
 
 /**
@@ -156,15 +208,96 @@ export interface RangoCloudflareOptions extends RangoBaseOptions {
   /**
    * Deployment preset for Cloudflare Workers.
    * When using cloudflare preset:
-   * - @vitejs/plugin-rsc is NOT added (cloudflare plugin adds it)
+   * - @vitejs/plugin-rsc IS still added by rango(), but with `serverHandler: false`
+   *   (the cloudflare plugin owns the RSC worker/server entry); only `client` and
+   *   `ssr` virtual entries are configured, no rsc entry
    * - Your worker entry (e.g., worker.rsc.tsx) imports the router directly
    * - Browser and SSR use virtual entries
    * - Build-time manifest generation is auto-detected from the resolved RSC environment config
    */
   preset: "cloudflare";
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. Shared across all prerender invocations for the build.
+   *
+   * `"auto"` resolves the Cloudflare platform proxy via wrangler
+   * `getPlatformProxy()`.
+   *
+   * @default false
+   */
+  buildEnv?: BuildEnvOption;
+}
+
+/**
+ * Per-function knobs for the Vercel deployment, written into the generated
+ * `.vc-config.json` (and `config.json` for `functionName`).
+ */
+export interface VercelPresetOptions {
+  /** Node runtime for the function. @default "nodejs22.x" */
+  runtime?: string;
+  /** Max execution time in seconds. @default 30 */
+  maxDuration?: number;
+  /** Function memory in MB (platform default when omitted). */
+  memory?: number;
+  /** Regions to pin the function to (platform default when omitted). */
+  regions?: string[];
+  /**
+   * Function name — the `<name>.func` directory and the `config.json` route
+   * destination. @default "index"
+   */
+  functionName?: string;
+}
+
+/**
+ * Options for Vercel Functions deployment.
+ *
+ * Builds like the node preset (Vercel runs Node Functions, not Workers): rango
+ * owns the RSC entry, `process.env.NODE_ENV` is folded for the build, and after
+ * the build a `.vercel/output` directory (Build Output API v3) is assembled from
+ * `dist/` — a single streaming Node Function plus the static client assets. The
+ * app must install `@vercel/functions` (used by `VercelCacheStore` and the
+ * generated function launcher).
+ */
+export interface RangoVercelOptions extends RangoBaseOptions {
+  /**
+   * Deployment preset for Vercel Functions.
+   */
+  preset: "vercel";
+
+  /**
+   * Path to a host-router entry (a module that calls `createHostRouter()` and
+   * exports the instance) to serve instead of a single `createRouter()` app.
+   * Root-relative (e.g. `"./src/worker.rsc.tsx"`).
+   *
+   * Set this when the app is a multi-app host router: auto-discovery otherwise
+   * finds the sub-apps' multiple `createRouter()` files and cannot pick an entry.
+   * When omitted, rango auto-detects a single `createHostRouter()` file if the
+   * app has several `createRouter()` files. The host module must export the
+   * `HostRouter` instance (default export or a named `hostRouter`/`router`
+   * export), not a Cloudflare-style `{ fetch }` object. The Vercel function then
+   * runs `hostRouter.match()` for every request (single-function deploy).
+   */
+  hostRouter?: string;
+
+  /**
+   * Environment bindings available to Prerender and Static handlers at build
+   * time via `ctx.env`. `"auto"` is Cloudflare-only; pass an object or a factory.
+   *
+   * @default false
+   */
+  buildEnv?: Exclude<BuildEnvOption, "auto">;
+
+  /**
+   * Vercel function configuration written into the Build Output.
+   */
+  vercel?: VercelPresetOptions;
 }
 
 /**
  * Options for rango() Vite plugin
  */
-export type RangoOptions = RangoNodeOptions | RangoCloudflareOptions;
+export type RangoOptions =
+  | RangoNodeOptions
+  | RangoCloudflareOptions
+  | RangoVercelOptions;

package/src/vite/plugins/cjs-to-esm.ts

@@ -8,15 +8,21 @@ const debug = createRangoDebugger(NS.transform);
  * The react-server-dom vendor files are shipped as CJS which doesn't work in browsers.
  */
 export function createCjsToEsmPlugin(): Plugin {
+  // Picked from Vite's resolved mode, not process.env.NODE_ENV, so the dev vs
+  // production vendor variant tracks the build mode the user actually ran.
+  let isProduction = false;
+
   return {
     name: "@rangojs/router:cjs-to-esm",
     enforce: "pre",
+    configResolved(config) {
+      isProduction = config.isProduction;
+    },
     transform(code, id) {
       const cleanId = id.split("?")[0].replaceAll("\\", "/");
 
-      // Transform the client.browser.js entry point to re-export from CJS
       if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
-        const isProd = process.env.NODE_ENV === "production";
+        const isProd = isProduction;
         const cjsFile = isProd
           ? "./cjs/react-server-dom-webpack-client.browser.production.js"
           : "./cjs/react-server-dom-webpack-client.browser.development.js";
@@ -28,57 +34,47 @@ export function createCjsToEsmPlugin(): Plugin {
         };
       }
 
-      // Transform the actual CJS files to ESM
       if (
         cleanId.includes("vendor/react-server-dom/cjs/") &&
         cleanId.includes("client.browser")
       ) {
         let transformed = code;
 
-        // Extract the license comment to preserve it
         const licenseMatch = transformed.match(/^\/\*\*[\s\S]*?\*\//);
         const license = licenseMatch ? licenseMatch[0] : "";
         if (license) {
           transformed = transformed.slice(license.length);
         }
 
-        // Remove "use strict" (both dev and prod have this)
         transformed = transformed.replace(/^\s*["']use strict["'];\s*/, "");
 
-        // Remove the conditional IIFE wrapper (development only)
         transformed = transformed.replace(
           /^\s*["']production["']\s*!==\s*process\.env\.NODE_ENV\s*&&\s*\(function\s*\(\)\s*\{/,
           "",
         );
 
-        // Remove the closing of the conditional IIFE at the end (development only)
         transformed = transformed.replace(/\}\)\(\);?\s*$/, "");
 
-        // Replace require('react') and require('react-dom') with imports (development)
         transformed = transformed.replace(
           /var\s+React\s*=\s*require\s*\(\s*["']react["']\s*\)\s*,[\s\n]+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
           'import React from "react";\nimport ReactDOM from "react-dom";\nvar ',
         );
 
-        // Replace require('react-dom') only (production - doesn't import React)
         transformed = transformed.replace(
           /var\s+ReactDOM\s*=\s*require\s*\(\s*["']react-dom["']\s*\)\s*,/g,
           'import ReactDOM from "react-dom";\nvar ',
         );
 
-        // Transform exports.xyz = function() to export function xyz()
         transformed = transformed.replace(
           /exports\.(\w+)\s*=\s*function\s*\(/g,
           "export function $1(",
         );
 
-        // Transform exports.xyz = value to export const xyz = value
         transformed = transformed.replace(
           /exports\.(\w+)\s*=/g,
           "export const $1 =",
         );
 
-        // Reconstruct with license at the top
         transformed = license + "\n" + transformed;
 
         debug?.("cjs-to-esm body rewrite %s", id);

package/src/vite/plugins/client-ref-dedup.ts

@@ -73,8 +73,6 @@ export function clientRefDedup(): Plugin {
     apply: "serve",
 
     configResolved(config: ResolvedConfig) {
-      // Respect user's optimizeDeps.exclude — if a package is explicitly
-      // excluded from pre-bundling, we shouldn't redirect it there.
       const clientEnv = config.environments?.["client"];
       clientExclude =
         clientEnv?.optimizeDeps?.exclude ?? config.optimizeDeps?.exclude ?? [];
@@ -91,27 +89,19 @@ export function clientRefDedup(): Plugin {
     },
 
     resolveId(source, importer, options) {
-      // Only intercept in the client environment
       if (this.environment?.name !== "client") return;
 
-      // Only handle imports from client-in-server-package-proxy virtual modules
       if (!importer?.includes(CLIENT_IN_SERVER_PROXY_PREFIX)) return;
 
-      // Only handle absolute node_modules paths
       if (!source.includes("/node_modules/")) return;
 
-      // Must have an importer
-      if (!importer) return;
-
       const packageName = extractPackageName(source);
       if (!packageName) return;
 
-      // Don't redirect packages that are excluded from optimization
       if (clientExclude.includes(packageName)) return;
 
       if (debug) dedupedPackages.add(packageName);
 
-      // Return a virtual module that re-exports via bare specifier
       return `\0rango:dedup/${packageName}`;
     },
 
@@ -120,7 +110,6 @@ export function clientRefDedup(): Plugin {
 
       const packageName = id.slice("\0rango:dedup/".length);
 
-      // Re-export via bare specifier so Vite routes through pre-bundling
       return [
         `export * from ${JSON.stringify(packageName)};`,
         `import * as __all__ from ${JSON.stringify(packageName)};`,

package/src/vite/plugins/client-ref-hashing.ts

@@ -5,7 +5,6 @@ import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
 const debug = createRangoDebugger(NS.transform);
 
-// Dev-mode client-reference key prefixes emitted by @vitejs/plugin-rsc
 const CLIENT_PKG_PROXY_PREFIX =
   "/@id/__x00__virtual:vite-rsc/client-package-proxy/";
 const CLIENT_IN_SERVER_PKG_PROXY_PREFIX =
@@ -40,32 +39,24 @@ export function computeProductionHash(
   let toHash: string;
 
   if (refKey.startsWith(CLIENT_PKG_PROXY_PREFIX)) {
-    // /@id/__x00__virtual:vite-rsc/client-package-proxy/<pkg> -> hash("<pkg>")
     toHash = refKey.slice(CLIENT_PKG_PROXY_PREFIX.length);
   } else if (refKey.startsWith(CLIENT_IN_SERVER_PKG_PROXY_PREFIX)) {
-    // /@id/__x00__virtual:vite-rsc/client-in-server-package-proxy/<encodedAbsPath>
     const absPath = decodeURIComponent(
       refKey.slice(CLIENT_IN_SERVER_PKG_PROXY_PREFIX.length),
     );
     toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith(FS_PREFIX)) {
-    // /@fs/abs/path.tsx -> hash(relative(root, "/abs/path.tsx"))
     const absPath = refKey.slice(FS_PREFIX.length - 1); // keep leading /
     toHash = relative(projectRoot, absPath).replaceAll("\\", "/");
   } else if (refKey.startsWith("/")) {
-    // /src/Button.tsx -> hash("src/Button.tsx")
     toHash = refKey.slice(1);
   } else {
-    // Already hashed or unknown format — return unchanged
     return refKey;
   }
 
   return hashRefKey(toHash);
 }
 
-// Regex to match registerClientReference() calls as emitted by @vitejs/plugin-rsc.
-// Captures the reference key (second argument) from the call.
-// Handles two proxy forms: parenthesized expression `(expr)` and arrow-throw `() => { ... }`.
 const REGISTER_CLIENT_REF_RE =
   /registerClientReference\(\s*(?:(?:\([^)]*\))|(?:\(\)[\s\S]*?\}))\s*,\s*"([^"]+)"\s*,\s*"[^"]+"\s*\)/g;
 
@@ -106,7 +97,6 @@ export function hashClientRefs(projectRoot: string): Plugin {
   const counter = createCounter(debug, "hash-client-refs");
   return {
     name: "@rangojs/router:hash-client-refs",
-    // Run after the RSC plugin's transform (default enforce is normal)
     enforce: "post",
     applyToEnvironment(env) {
       return env.name === "rsc";

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

@@ -32,14 +32,6 @@ const IMPORT_NODE_TYPES = new Set([
   "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) {} }
@@ -65,15 +57,6 @@ 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 {
@@ -163,9 +146,6 @@ export function createCloudflareProtocolStubPlugin(): Plugin {
 
       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) {