@rangojs/router 0.0.0-experimental.97 → 0.0.0-experimental.98914650

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";
 }
 
 /**
@@ -47,6 +47,64 @@ export type BuildEnvOption =
   | Record<string, unknown>
   | BuildEnvFactory;
 
+// -- Client chunking --------------------------------------------------------
+
+/**
+ * Metadata for one client ("use client") module, passed to a {@link ClientChunks}
+ * function. Mirrors the shape `@vitejs/plugin-rsc` passes to its own
+ * `clientChunks` option.
+ */
+export interface ClientChunkMeta {
+  /** Absolute module id of the "use client" file. */
+  id: string;
+  /** Normalized (posix) module id — convenient for path-based matching. */
+  normalizedId: string;
+  /**
+   * The RSC/server chunk that statically imports this client reference. This is
+   * the key used for the default grouping when no override is supplied: a single
+   * router that statically imports every route yields ONE `serverChunk`, hence
+   * one client chunk for all routes.
+   */
+  serverChunk: string;
+}
+
+/**
+ * Controls how client ("use client") components are grouped into browser
+ * chunks, i.e. per-route / per-feature code splitting of the client bundle.
+ *
+ * Without splitting, a single router ships ONE client chunk containing every
+ * route's client components (and their CSS) — navigating to one route downloads
+ * every other route's client code. (Host sub-apps loaded via a dynamic `import()`
+ * are the exception: each forms its own chunk.) This option controls how that
+ * monolith is split.
+ *
+ * Behavior branches:
+ * - `true` / omitted (**default**, pre-1.0): Rango's built-in **directory
+ *   strategy**. It splits app `"use client"` modules by **route id** — the segment
+ *   after a route-root directory (`routes`, `app`, `pages`, `features`, `handlers`,
+ *   …) — so `routes/dashboard/**` becomes `app-dashboard` at any nesting depth.
+ *   Where it finds NO route structure (a flat `src/components/`, or host sub-apps
+ *   already split by a dynamic `import()`), it inherits the default grouping
+ *   unchanged — so the shared `src/components` chunk stays shared and host apps do
+ *   not leak across each other. Shared runtime (React, the router, `node_modules`)
+ *   is never split.
+ * - `false`: opt out — inherit `@vitejs/plugin-rsc`'s default grouping everywhere
+ *   (one chunk per router / per host sub-app).
+ * - function: full override. Return a chunk group name, or `undefined` to fall
+ *   back to the default grouping for that one module. Forwarded directly to
+ *   `@vitejs/plugin-rsc`'s `clientChunks`.
+ *
+ * Every module maps to exactly one group, so there is no byte duplication: a
+ * component used by two routes lives in one group and is fetched whenever it
+ * renders. Put genuinely shared client components OUTSIDE route directories so
+ * they land in the shared group rather than one route's chunk.
+ *
+ * @default true
+ */
+export type ClientChunks =
+  | boolean
+  | ((meta: ClientChunkMeta) => string | undefined);
+
 // -- Plugin options ---------------------------------------------------------
 
 /**
@@ -60,16 +118,27 @@ interface RangoBaseOptions {
   banner?: boolean;
 
   /**
-   * 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`).
+   * Group client ("use client") components into browser chunks for per-route /
+   * per-feature code splitting. On by default (pre-1.0); pass `false` to opt out.
+   * See {@link ClientChunks}.
    *
-   * 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.
+   * @default true
+   */
+  clientChunks?: ClientChunks;
+
+  /**
+   * 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`.
    *
-   * @default false
+   * @example
+   * rango({ discovery: { include: ["src/routes/**"] } })
    */
-  buildEnv?: BuildEnvOption;
+  discovery?: {
+    include?: string[];
+    exclude?: string[];
+  };
 }
 
 /**
@@ -80,6 +149,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.
+   */
+  host?: 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">;
 }
 
 /**
@@ -89,15 +183,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).
+   */
+  host?: 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

@@ -12,13 +12,9 @@ export function createCjsToEsmPlugin(): Plugin {
     name: "@rangojs/router:cjs-to-esm",
     enforce: "pre",
     transform(code, id) {
-      const cleanId = id.split("?")[0];
+      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") ||
-        cleanId.includes("vendor\\react-server-dom\\client.browser.js")
-      ) {
+      if (cleanId.includes("vendor/react-server-dom/client.browser.js")) {
         const isProd = process.env.NODE_ENV === "production";
         const cjsFile = isProd
           ? "./cjs/react-server-dom-webpack-client.browser.production.js"
@@ -31,58 +27,47 @@ export function createCjsToEsmPlugin(): Plugin {
         };
       }
 
-      // Transform the actual CJS files to ESM
       if (
-        (cleanId.includes("vendor/react-server-dom/cjs/") ||
-          cleanId.includes("vendor\\react-server-dom\\cjs\\")) &&
+        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 =
@@ -22,6 +21,17 @@ const FS_PREFIX = "/@fs/";
  * Returns the input unchanged if it doesn't match a known dev-mode pattern
  * (e.g., already a production hash).
  */
+/**
+ * The production client-reference key hash: `sha256(relativeId).slice(0,12)`,
+ * matching @vitejs/plugin-rsc's `hashString`. Exported so the client-chunks
+ * strategy can hash a `clientChunks` callback's `meta.normalizedId` (already the
+ * project-root-relative id) and compare it against fallback hashes collected
+ * during discovery.
+ */
+export function hashRefKey(relativeId: string): string {
+  return createHash("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+
 export function computeProductionHash(
   projectRoot: string,
   refKey: string,
@@ -29,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 createHash("sha256").update(toHash).digest("hex").slice(0, 12);
+  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;
 
@@ -95,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 {
@@ -139,7 +122,7 @@ export function createCloudflareProtocolStubPlugin(): Plugin {
 
       let ast: AstNode;
       try {
-        ast = this.parse(code) as unknown as AstNode;
+        ast = this.parse(code, { lang: "tsx" }) as unknown as AstNode;
       } catch {
         // Malformed source — let a downstream plugin surface the parse error.
         return null;
@@ -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) {

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

@@ -7,9 +7,6 @@ import { createRangoDebugger, createCounter, NS } from "../debug.js";
 
 const debug = createRangoDebugger(NS.transform);
 
-/**
- * Type for the RSC plugin's manager API
- */
 interface RscPluginManager {
   serverReferenceMetaMap: Record<
     string,
@@ -26,14 +23,9 @@ interface RscPluginApi {
   manager: RscPluginManager;
 }
 
-/**
- * Get the RSC plugin's API from Vite config
- */
 function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
-  // Try by name first
   let plugin = config.plugins.find((p) => p.name === "rsc:minimal");
 
-  // Fallback: find by API structure if name lookup fails
   if (!plugin) {
     plugin = config.plugins.find(
       (p) =>
@@ -42,7 +34,7 @@ function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
     );
     if (plugin) {
       console.warn(
-        `[rsc-router:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
+        `[rango:expose-action-id] RSC plugin found by API structure (name: "${plugin.name}"). ` +
           `Consider updating the name lookup if the plugin was renamed.`,
       );
     }
@@ -62,13 +54,11 @@ function getRscPluginApi(config: ResolvedConfig): RscPluginApi | undefined {
 function isUseServerModule(filePath: string): boolean {
   try {
     const content = fs.readFileSync(filePath, "utf-8");
-    // Remove leading comments and whitespace to find the first meaningful content
     const trimmed = content
-      .replace(/^\s*\/\/[^\n]*\n/gm, "") // Remove single-line comments
-      .replace(/^\s*\/\*[\s\S]*?\*\/\s*/gm, "") // Remove multi-line comments
+      .replace(/^\s*\/\/[^\n]*\n/gm, "")
+      .replace(/^\s*\/\*[\s\S]*?\*\/\s*/gm, "")
       .trimStart();
 
-    // Check if the file starts with "use server" directive
     return (
       trimmed.startsWith('"use server"') || trimmed.startsWith("'use server'")
     );
@@ -77,18 +67,6 @@ function isUseServerModule(filePath: string): boolean {
   }
 }
 
-/**
- * Transform code to expose action IDs on createServerReference calls.
- * Wraps each call with an IIFE that attaches $id to the returned function.
- *
- * @param code - The source code to transform
- * @param sourceId - The source file identifier (for sourcemap)
- * @param hashToFileMap - Optional mapping from hash to file path (for server bundles)
- */
-/**
- * Apply createServerReference wrapping to a MagicString instance.
- * Returns true if any changes were made.
- */
 function applyServerReferenceWrapping(
   code: string,
   s: MagicString,
@@ -98,11 +76,6 @@ function applyServerReferenceWrapping(
     return false;
   }
 
-  // Match: createServerReference("hash#actionName", ...) or $$ReactClient.createServerReference(...)
-  // The RSC plugin uses $$ReactClient namespace in transformed code.
-  // Note: [^)]* cannot handle nested parens in trailing args. This is safe in practice
-  // because the RSC plugin always generates simple variable references (e.g., callServer)
-  // as the second argument, never nested function calls.
   const pattern =
     /((?:\$\$\w+\.)?createServerReference)\(("[^"]+#[^"]+")([^)]*)\)/g;
 
@@ -115,23 +88,19 @@ function applyServerReferenceWrapping(
     const start = match.index;
     const end = start + fullMatch.length;
 
-    // Parse the ID to potentially replace hash with file path
     let finalIdArg = idArg;
     if (hashToFileMap) {
-      // idArg is like '"hash#actionName"', extract the parts
       const idValue = idArg.slice(1, -1); // Remove quotes
       const hashMatch = idValue.match(/^([^#]+)#(.+)$/);
       if (hashMatch) {
         const [, hash, actionName] = hashMatch;
         const filePath = hashToFileMap.get(hash);
         if (filePath) {
-          // Replace hash with file path for server-side
           finalIdArg = `"${filePath}#${actionName}"`;
         }
       }
     }
 
-    // Wrap the createServerReference call to attach $$id to the returned function
     const replacement = `(function(fn) { fn.$$id = ${finalIdArg}; return fn; })(${fnCall}(${idArg}${rest}))`;
     s.overwrite(start, end, replacement);
   }
@@ -155,29 +124,6 @@ function transformServerReferences(
   };
 }
 
-/**
- * Transform registerServerReference calls in server bundles to use file paths instead of hashes.
- * Pattern: registerServerReference(fn, "hash", "exportName")
- * React's registerServerReference sets $$id = hash + "#" + exportName
- * By replacing the hash with file path, $$id will contain the file path for revalidation matching.
- *
- * Only actions from module-level "use server" files are transformed.
- * Inline actions (defined in RSC components with "use server" inside a function) are NOT in
- * hashToFileMap and keep their hashed IDs. This is intentional for client security:
- * - Module-level "use server" files: shared action modules, file path helps revalidation
- * - Inline actions: one-off actions in RSC, hash ID prevents file path exposure to client
- *
- * @param code - The source code to transform
- * @param sourceId - The source file identifier (for sourcemap)
- * @param hashToFileMap - Mapping from hash to file path (only module-level "use server" files)
- */
-/**
- * Apply registerServerReference wrapping to a MagicString instance.
- * Returns true if any changes were made.
- *
- * Only actions from module-level "use server" files are transformed.
- * Inline actions keep their hashed IDs for client security.
- */
 function applyRegisterReferenceWrapping(
   code: string,
   s: MagicString,
@@ -187,8 +133,6 @@ function applyRegisterReferenceWrapping(
     return false;
   }
 
-  // Match: registerServerReference(fn, "hash", "exportName")
-  // The hash is the second argument, exportName is the third
   const pattern =
     /registerServerReference\(([^,]+),\s*"([^"]+)",\s*"([^"]+)"\)/g;
 
@@ -200,15 +144,9 @@ function applyRegisterReferenceWrapping(
     const start = match.index;
     const end = start + fullMatch.length;
 
-    // Look up the file path for this hash
     const filePath = hashToFileMap.get(hash);
     if (filePath) {
       hasChanges = true;
-      // WRAP the call to add $id property with file path
-      // Keep the original hash for React's action registry (so loadServerAction works)
-      // Add $id (single dollar) with file path for revalidation matching
-      // Note: We use $id instead of $$id because React's registerServerReference
-      // sets $$id as a non-writable property
       const filePathId = `${filePath}#${exportName}`;
       const replacement = `(function(fn) { fn.$id = "${filePathId}"; return fn; })(registerServerReference(${fnArg}, "${hash}", "${exportName}"))`;
       s.overwrite(start, end, replacement);
@@ -287,7 +225,7 @@ export function exposeActionId(): Plugin {
 
       if (!rscPluginApi) {
         throw new Error(
-          "[rsc-router] Could not find @vitejs/plugin-rsc. " +
+          "[rango] Could not find @vitejs/plugin-rsc. " +
             "@rangojs/router requires the Vite RSC plugin, which is included automatically by rango().",
         );
       }
@@ -336,27 +274,19 @@ export function exposeActionId(): Plugin {
 
       const start = counterTransform ? performance.now() : 0;
       try {
-        // Dev mode: no hash-to-file mapping needed (IDs are already file paths)
         return transformServerReferences(code, id);
       } finally {
         counterTransform?.record(id, performance.now() - start);
       }
     },
 
-    // Build mode: renderChunk runs after all transforms and bundling complete
     renderChunk(code, chunk) {
       const start = counterRender ? performance.now() : 0;
       try {
-        // Only RSC bundle should get file paths for revalidation matching
-        // SSR bundle must NOT use file paths because client components run there
-        // and need to match the client bundle during hydration (otherwise: error #418)
         const isRscEnv = this.environment?.name === "rsc";
 
-        // Only use file path mapping for RSC environment
         const effectiveMap = isRscEnv ? hashToFileMap : undefined;
 
-        // For RSC bundles, both createServerReference and registerServerReference
-        // may need transforming. Use a single MagicString for correct sourcemaps.
         if (isRscEnv && hashToFileMap) {
           const s = new MagicString(code);
           const changed1 = applyServerReferenceWrapping(code, s, effectiveMap);
@@ -377,7 +307,6 @@ export function exposeActionId(): Plugin {
           return null;
         }
 
-        // Non-RSC environments: only transform createServerReference calls
         return transformServerReferences(code, chunk.fileName, effectiveMap);
       } finally {
         counterRender?.record(chunk.fileName, performance.now() - start);