@rangojs/router 0.19.1 → 0.21.0

package/src/vite/plugins/version-plugin.ts

@@ -1,5 +1,9 @@
 import { parseAst, type Plugin } from "vite";
-import { VIRTUAL_IDS, getVirtualVersionContent } from "./virtual-entries.js";
+import {
+  VIRTUAL_IDS,
+  getVirtualBuildVersionContent,
+  getVirtualVersionContent,
+} from "./virtual-entries.js";
 import { hasUseClientDirective } from "../utils/directive-prologue.js";
 
 interface ClientModuleSignature {
@@ -100,25 +104,22 @@ function getClientModuleSignature(
 }
 
 /**
- * Plugin providing rsc-router:version virtual module.
- * Exports VERSION that changes when RSC modules change (dev) or at build time (production).
+ * Plugin providing the `@rangojs/router:version` virtual module.
  *
- * The version is used for:
- * 1. Cache invalidation - CFCacheStore uses VERSION to invalidate stale cache
- * 2. Version mismatch detection - client sends version, server reloads on mismatch
+ * Dev: exports a VERSION stamp used for both versions of every router. It
+ * updates when the server starts and when an RSC module changes via HMR (the
+ * version module is invalidated). Client-only HMR changes do not update it:
+ * they do not affect server-rendered content or cached RSC payloads.
  *
- * In dev mode, the version updates when:
- * - Server starts (initial version)
- * - RSC modules change via HMR (triggers version module invalidation)
- *
- * Client-only HMR changes don't update the version since they don't affect
- * server-rendered content or cached RSC payloads.
+ * Build: exports a placeholder for the per-router versions table. The module
+ * holds nothing that varies between builds; the table is written into the
+ * built chunk after the server output is hashed (the buildApp post hook in
+ * router-discovery.ts). See docs/design/per-app-cache-version.md.
  * @internal
  */
 export function createVersionPlugin(): Plugin {
-  // Generate version at plugin creation time (build/server start)
-  const buildVersion = Date.now().toString(16);
-  let currentVersion = buildVersion;
+  // Dev stamp, generated at plugin creation (server start).
+  let currentVersion = Date.now().toString(16);
   let isDev = false;
   let server: any = null;
   let resolvedCacheDir: string | undefined;
@@ -142,14 +143,6 @@ export function createVersionPlugin(): Plugin {
     name: "@rangojs/router:version",
     enforce: "pre",
 
-    // The build-time shell capture phase (producer B, #699) stamps entries
-    // with THIS instance's version — the value folded into the shipped worker
-    // — never the discovery temp server's own version-plugin value (a
-    // different Date.now() stamp that would fail the serve-side gate).
-    api: {
-      getBuildVersion: (): string => currentVersion,
-    },
-
     configResolved(config) {
       isDev = config.command === "serve";
       resolvedCacheDir = config.cacheDir
@@ -177,7 +170,9 @@ export function createVersionPlugin(): Plugin {
 
     load(id) {
       if (id === "\0" + VIRTUAL_IDS.version) {
-        return getVirtualVersionContent(currentVersion);
+        return isDev
+          ? getVirtualVersionContent(currentVersion)
+          : getVirtualBuildVersionContent();
       }
       return null;
     },

package/src/vite/plugins/version.d.ts

@@ -5,8 +5,23 @@
 
 declare module "@rangojs/router:version" {
   /**
-   * Auto-generated version string for cache invalidation.
-   * Changes on server restart (dev) or build (prod).
+   * The build's version string.
+   *
+   * - Dev: a stamp that changes on server start and on every RSC module edit.
+   * - Production: the whole-build document version, a hash of the server
+   *   output and the client asset names. The same source builds to the same
+   *   value; any change to any router changes it.
+   *
+   * A router serves with its own versions (`ROUTER_VERSIONS`), not this one.
    */
   export const VERSION: string;
+
+  /**
+   * Per-router cache versions computed at build time: router id to
+   * `[data, document]`, with `"*"` holding the whole-build pair.
+   * `undefined` in dev, where `VERSION` is used for both.
+   */
+  export const ROUTER_VERSIONS:
+    | Readonly<Record<string, readonly [data: string, document: string]>>
+    | undefined;
 }

package/src/vite/plugins/virtual-entries.ts

@@ -1,4 +1,5 @@
 import type { HeadScriptsOption } from "../plugin-types.js";
+import { DEFAULT_ROUTER_VERSIONS_KEY } from "../../router-versions.js";
 
 export const VIRTUAL_ENTRY_BROWSER: string = `
 import {
@@ -65,13 +66,20 @@ function emitProgressiveChunkSize(value: number): string {
  * option: "preinit" (default) installs the client-reference preinit hook and
  * threads `getClientEntryUrl` so Fizz emits `bootstrapModules`;
  * "preload" omits the hook and uses the deprecated inline
- * `loadBootstrapScriptContent` bootstrap.
+ * `loadBootstrapScriptContent` bootstrap. Any other value throws: an unknown
+ * string such as "prenit" used to run as "preinit" silently
+ * (`headScripts !== "preload"` since #694).
  */
 export function getVirtualEntrySSR(
   headScripts: HeadScriptsOption = "preinit",
   progressiveChunkSize?: number,
 ): string {
-  const preinit = headScripts !== "preload";
+  if (headScripts !== "preinit" && headScripts !== "preload") {
+    throw new Error(
+      `rango({ headScripts }) must be "preinit" or "preload", received ${JSON.stringify(headScripts)}`,
+    );
+  }
+  const preinit = headScripts === "preinit";
   // The preload variant drops the preinit-only imports/install and swaps the
   // bootstrap dep, all built here so the template below stays a single
   // unconditional shape.
@@ -157,7 +165,7 @@ export const resumeShellHTML = createShellResumeHandler({
  *   registered for the _rsc_loader endpoint and fail in production.
  *
  * Single source of truth: both the generated virtual RSC entry below and the
- * custom-entry injector (version-injector) consume this list, so a new
+ * custom-entry injector (entry-bootstrap-injector) consume this list, so a new
  * bootstrap manifest cannot be added to one path and forgotten on the other.
  * That exact drift (loader-manifest present here but missing from the injector)
  * is what left fetchable loaders unresolved on custom worker entries.
@@ -190,12 +198,11 @@ import {
 // consults them at router-module evaluation. Router-first would silently push
 // every clientUrls() app onto the deferred-subscription path and change mount
 // registration order with no error. The custom-entry injector keeps the same
-// guarantee by PREPENDING this list at file top (version-injector.ts).
+// guarantee by PREPENDING this list at file top (entry-bootstrap-injector.ts).
 ${bootstrapImports}
 
 import { router } from "${routerPath}";
 import { createRSCHandler } from "@rangojs/router/internal/rsc-handler";
-import { VERSION } from "@rangojs/router:version";
 
 // Lazily create the handler on first request so that ESM live bindings
 // have resolved by the time we read \`router\`. During HMR the module may
@@ -205,7 +212,6 @@ export default function handler(request, env) {
   if (!_handler) {
     _handler = createRSCHandler({
       router,
-      version: VERSION,
       // Forward the router's CSP nonce provider. createRSCHandler reads the
       // provider only from options.nonce; without this, createRouter({ nonce })
       // is silently dropped on the Node preset (the Cloudflare path wires it via
@@ -307,6 +313,33 @@ export const VIRTUAL_IDS = {
   version: "@rangojs/router:version",
 } as const;
 
+/** Dev: one stamp for both versions of every router, bumped on RSC edits. */
 export function getVirtualVersionContent(version: string): string {
-  return `export const VERSION = ${JSON.stringify(version)};`;
+  return [
+    `export const VERSION = ${JSON.stringify(version)};`,
+    `export const ROUTER_VERSIONS = undefined;`,
+  ].join("\n");
+}
+
+/**
+ * Free identifier the production version module ships in place of the table.
+ * The versions are hashes of the built server code, so they cannot be part of
+ * it: the buildApp post hook (router-discovery.ts) replaces this token in the
+ * written chunk once the hashes are final (runRouterVersionsPhase,
+ * discovery/router-versions-phase.ts). An unreplaced token throws a ReferenceError
+ * when the module evaluates, so a build that skipped the step cannot serve
+ * with a constant version.
+ */
+export const ROUTER_VERSIONS_PLACEHOLDER = "__RANGO_ROUTER_VERSIONS__";
+
+/**
+ * Production: byte-identical in every build, so it never moves the hashes it
+ * is later filled with. VERSION is the whole-build document version (the
+ * table's "*" entry).
+ */
+export function getVirtualBuildVersionContent(): string {
+  return [
+    `export const ROUTER_VERSIONS = ${ROUTER_VERSIONS_PLACEHOLDER};`,
+    `export const VERSION = ROUTER_VERSIONS[${JSON.stringify(DEFAULT_ROUTER_VERSIONS_KEY)}][1];`,
+  ].join("\n");
 }

package/src/vite/rango.ts

@@ -2,7 +2,10 @@ import { type PluginOption } from "vite";
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { exposeActionId } from "./plugins/expose-action-id.js";
-import { defineEncryptionKeyExpr } from "./encryption-key.js";
+import {
+  configureEncryptionKey,
+  defineEncryptionKeyExpr,
+} from "./encryption-key.js";
 import {
   createLoaderDirectiveGuardPlugin,
   createLoaderScanStubPlugin,
@@ -12,6 +15,7 @@ import {
 import { useCacheTransform } from "./plugins/use-cache-transform.js";
 import { transitionWhenHoistPlugin } from "./plugins/transition-when-hoist.js";
 import { clientRefDedup } from "./plugins/client-ref-dedup.js";
+import { stableRscOutput } from "./plugins/stable-rsc-output.js";
 import { VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import {
   getExcludeDeps,
@@ -32,6 +36,7 @@ import {
   getManualChunks,
 } from "./utils/shared-utils.js";
 import {
+  clientChunksReport,
   resolveClientChunks,
   type ClientChunkContext,
 } from "./utils/client-chunks.js";
@@ -42,7 +47,7 @@ import type {
 } from "./plugin-types.js";
 import { createVercelOutputPlugin } from "./plugins/vercel-output.js";
 import { printBanner, rangoVersion } from "./utils/banner.js";
-import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
+import { createEntryBootstrapInjectorPlugin } from "./plugins/entry-bootstrap-injector.js";
 import { createCjsToEsmPlugin } from "./plugins/cjs-to-esm.js";
 import { createRouterDiscoveryPlugin } from "./router-discovery.js";
 import { performanceTracksPlugin } from "./plugins/performance-tracks.js";
@@ -75,6 +80,20 @@ const debugConfig = createRangoDebugger(NS.config);
  */
 const SERVER_BUILD_TARGET = "esnext";
 
+/**
+ * Entry-signature mode for the node/vercel RSC build, the one
+ * `@cloudflare/vite-plugin` forces on its worker entry.
+ *
+ * Vite's default for a server build, "allow-extension", lets the bundler park
+ * modules shared with lazy chunks in the entry chunk. Under a host router that
+ * put the router runtime (80 modules, measured on e2e/test-app/.host-fixture
+ * and examples/vercel-multi-router) and every sub-app's route names into
+ * `index.js`, which every sub-app chunk imported back and which names each
+ * sub-app chunk by its content hash: no router's cache version was independent
+ * of the others (discovery/build-versions.ts hashes a router's chunks).
+ */
+const RSC_ENTRY_SIGNATURES = "strict";
+
 // The leading-directive 'use client' sniff is shared with version-plugin's
 // getClientModuleSignature so the two cannot drift. Imported for local use by the
 // HMR transform below and re-exported because the E8 sniff test imports it from
@@ -110,6 +129,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const rangoStart = performance.now();
   const resolvedOptions: RangoOptions = options ?? { preset: "node" };
   const preset = resolvedOptions.preset ?? "node";
+  // Before any plugin-rsc instance (this build's, the discovery temp server's)
+  // reads the key, and so an invalid key fails the config load.
+  configureEncryptionKey(resolvedOptions.encryptionKey);
   const showBanner = resolvedOptions.banner ?? true;
   const clientChunksOption = resolvedOptions.clientChunks ?? true;
   const useBuiltInClientChunks = clientChunksOption === true;
@@ -466,6 +488,9 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
               ...(vercelServerEnv ?? {}),
               build: {
                 target: SERVER_BUILD_TARGET,
+                rollupOptions: {
+                  preserveEntrySignatures: RSC_ENTRY_SIGNATURES,
+                },
               },
               optimizeDeps: {
                 entries: [VIRTUAL_IDS.rsc],
@@ -537,6 +562,8 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
     );
     plugins.push(clientRefDedup());
   }
+  plugins.push(clientChunksReport());
+  plugins.push(stableRscOutput());
 
   plugins.push({
     name: "@rangojs/router:client-component-hmr",
@@ -581,7 +608,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   const discoveryRouterRef = preset !== "cloudflare" ? routerRef : undefined;
 
   if (preset === "cloudflare") {
-    plugins.push(createVersionInjectorPlugin(undefined));
+    plugins.push(createEntryBootstrapInjectorPlugin(undefined));
   }
 
   plugins.push(createCjsToEsmPlugin());

package/src/vite/router-discovery.ts

@@ -8,8 +8,8 @@
 
 import type { Plugin, ViteDevServer } from "vite";
 import { createServer as createViteServer } from "vite";
-import { resolve } from "node:path";
-import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
 import { createRequire, register } from "node:module";
 import { pathToFileURL } from "node:url";
 import {
@@ -34,6 +34,7 @@ import {
   internalDebugNoCacheMiddleware,
 } from "./inject-client-debug.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
+import { uniformVersions } from "../router-versions.js";
 import { getVirtualEntrySSR, VIRTUAL_IDS } from "./plugins/virtual-entries.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -64,6 +65,13 @@ import {
   refreshRecordedClientUrlProjections,
 } from "./discovery/client-urls-projection.js";
 import { runShellPrerenderPhase } from "./discovery/shell-prerender-phase.js";
+import { runRouterVersionsPhase } from "./discovery/router-versions-phase.js";
+import {
+  recordBundleFiles,
+  recordClientGraph,
+  recordServerGraph,
+  recordVersionModuleFiles,
+} from "./discovery/build-versions.js";
 import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
 import { findTransitionWhenError } from "../transition-when-ref.js";
 import { transitionWhenHoistPlugin } from "./plugins/transition-when-hoist.js";
@@ -320,11 +328,44 @@ import type {
   BuildEnvResult,
 } from "./plugin-types.js";
 
+const WRANGLER_CONFIG_NAMES: readonly string[] = [
+  "wrangler.json",
+  "wrangler.jsonc",
+  "wrangler.toml",
+];
+
+/**
+ * getPlatformProxy() looks for the wrangler config from process.cwd() and
+ * resolves its default persist path against cwd, so building from another
+ * directory dropped the app's bindings (#1037). Search upward from the Vite
+ * root with wrangler's own file names and order. Persisted state goes under
+ * the Vite root, where @cloudflare/vite-plugin reads it in dev and preview
+ * (its getPersistenceRoot), also when the config sits above the root. No
+ * config found: no options, wrangler's own lookup.
+ */
+function wranglerProxyOptions(
+  root: string,
+): Record<string, unknown> | undefined {
+  const viteRoot = resolve(root);
+  for (let dir = viteRoot; ; dir = dirname(dir)) {
+    for (const name of WRANGLER_CONFIG_NAMES) {
+      const configPath = join(dir, name);
+      if (existsSync(configPath)) {
+        return {
+          configPath,
+          persist: { path: join(viteRoot, ".wrangler", "state", "v3") },
+        };
+      }
+    }
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
 /**
  * Resolve the buildEnv option into a concrete { env, dispose? } result.
  * Handles all four input shapes: false, "auto", factory, plain object.
  */
-async function resolveBuildEnv(
+export async function resolveBuildEnv(
   option: BuildEnvOption | undefined,
   factoryCtx: BuildEnvFactoryContext,
 ): Promise<BuildEnvResult | null> {
@@ -348,7 +389,9 @@ async function resolveBuildEnv(
       )) as {
         getPlatformProxy: (opts?: any) => Promise<any>;
       };
-      const proxy = await getPlatformProxy();
+      const proxy = await getPlatformProxy(
+        wranglerProxyOptions(factoryCtx.root),
+      );
       return {
         env: proxy.env as Record<string, unknown>,
         dispose: proxy.dispose,
@@ -410,6 +453,7 @@ function resetPrerenderCollection(s: DiscoveryState): void {
   s.staticManifestEntries = null;
   s.shellCandidates = null;
   s.prerenderPayloadValues = null;
+  s.buildData = [];
 }
 
 /**
@@ -1533,7 +1577,7 @@ export function createRouterDiscoveryPlugin(
               maxSnapshotBytes,
               captureTimeout,
               buildEnv: s.resolvedBuildEnv,
-              buildVersion: version,
+              versions: uniformVersions(version),
               captureShellHTML: ssrModule.captureShellHTML,
               debug: !!debugDiscovery,
             });
@@ -2261,18 +2305,27 @@ export function createRouterDiscoveryPlugin(
       }
     },
 
-    // Post-build PPR shell capture (producer B, #699): runs after EVERY
-    // environment bundle is written — the shell prelude embeds built client
-    // asset URLs (bootstrap entry), which do not exist at buildStart. The
-    // kept temp server and the buildEnv were deferred AS A PAIR in
-    // buildStart's finally; this finally is the pair's success-path owner
-    // (buildEnd below owns the aborted-build path) — the phase itself is a
-    // pure producer and tears down only the globals it installs.
+    // Post-build phases, after EVERY environment bundle is written.
+    //
+    // 1. Cache versions (discovery/router-versions-phase.ts): hashes the
+    //    server output as postprocessBundle left it and writes the per-router
+    //    table into the built version module. First, because phase 2 stamps
+    //    its entries with these versions and reads the same RSC out dir.
+    // 2. PPR shell capture (producer B, #699): the shell prelude embeds built
+    //    client asset URLs (bootstrap entry), which do not exist at
+    //    buildStart. The kept temp server and the buildEnv were deferred AS A
+    //    PAIR in buildStart's finally; this finally is the pair's success-path
+    //    owner (buildEnd below owns the aborted-build path) — the phase itself
+    //    is a pure producer and tears down only the globals it installs.
     buildApp: {
       order: "post",
       async handler(builder) {
         try {
-          await runShellPrerenderPhase(s, builder as any);
+          await runShellPrerenderPhase(
+            s,
+            builder as any,
+            runRouterVersionsPhase(s, builder as any),
+          );
         } finally {
           if (s.isBuildMode) {
             const tempServer = s.shellPhaseTempServer;
@@ -2387,6 +2440,22 @@ export function createRouterDiscoveryPlugin(
     // Record handler chunk metadata and RSC entry filename during RSC build.
     // Used by closeBundle for handler code eviction and prerender data injection.
     generateBundle(_options: any, bundle: any) {
+      // Inputs of the per-router cache versions (discovery/build-versions.ts).
+      // Each pass overwrites its slot: plugin-rsc runs the RSC and SSR builds
+      // twice, and the real pass comes last.
+      if (s.isBuildMode) {
+        const envName = this.environment?.name;
+        if (envName) {
+          s.versionModuleFiles.set(envName, recordVersionModuleFiles(bundle));
+        }
+        if (envName === "rsc") {
+          s.serverBuildGraph = recordServerGraph(this, bundle);
+        } else if (envName === "client") {
+          s.clientBuildGraph = recordClientGraph(this, bundle);
+        } else if (envName === "ssr") {
+          s.ssrBundle = recordBundleFiles(bundle);
+        }
+      }
       if (this.environment?.name !== "rsc") return;
       const genStart = debugBuild ? performance.now() : 0;
 

package/src/vite/utils/client-chunks.ts

@@ -1,5 +1,7 @@
+import type { Plugin } from "vite";
+import { gzipSync } from "node:zlib";
 import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
-import { createRangoDebugger, NS } from "../debug.js";
+import { createRangoDebugger, NS, type Debugger } from "../debug.js";
 import { hashRefKey } from "../plugins/client-ref-hashing.js";
 
 /** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
@@ -97,6 +99,20 @@ const ROUTE_ROOT_DIRS = new Set([
   "sections",
 ]);
 
+/**
+ * Markers that double as a conventional source root. `app/` is both a Next-style
+ * route root (`app/<segment>/…`) and the source root of many apps
+ * (`app/components`, `app/routes/<id>`). Keying on the segment after it put every
+ * route under `app/routes/` into one `app-routes` group, and a group is the
+ * loading unit, so rendering any one member downloaded every route's client code
+ * (#1022). A source-root marker therefore defers to a marker that IMMEDIATELY
+ * follows it when that inner marker has a route directory after it
+ * (`app/routes/<id>/…` -> `app-<id>`). Anything else after `app/` (including
+ * `app/components/`) is still the Next-style route id. Only these markers defer:
+ * `routes/view/<sub>/…` keeps `view` as the route id.
+ */
+const SOURCE_ROOT_DIRS = new Set(["app"]);
+
 /**
  * Built-in strategy used when `clientChunks: true` (also the default). Splits app
  * client components by route/feature identity ONLY where it can recognize a route
@@ -116,8 +132,11 @@ const ROUTE_ROOT_DIRS = new Set([
  * 1. Shared runtime (React / router / node_modules) -> `undefined` (never split).
  * 2. A registered error/notFound fallback (`ctx.fallbackRefs`) -> `app-fallback`,
  *    regardless of location, so the error UI is decoupled from the happy path.
- * 3. A {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on that
- *    next segment (the route id), robust to any nesting depth.
+ * 3. The first {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on
+ *    that next segment (the route id), robust to any nesting depth. A
+ *    {@link SOURCE_ROOT_DIRS} marker (`app`) directly followed by another marker
+ *    with a directory after it defers to that inner marker:
+ *    `app/routes/<id>/…` -> `app-<id>`, while `app/<segment>/…` -> `app-<segment>`.
  * 4. Otherwise `undefined` (inherit the default `serverChunk` grouping).
  */
 export function directoryClientChunks(
@@ -140,17 +159,21 @@ export function directoryClientChunks(
   }
   const segments = meta.normalizedId.split("/").filter(Boolean);
   const dirCount = segments.length - 1; // exclude the filename
-  if (dirCount >= 1) {
-    // Route-root marker -> the segment after it is the route id. First marker
-    // wins, so a top-level route owns its whole subtree. The `< dirCount - 1`
-    // bound guarantees the segment after the marker is a directory, not the file.
-    for (let i = 0; i < dirCount - 1; i++) {
-      if (ROUTE_ROOT_DIRS.has(segments[i].toLowerCase())) {
-        const group = `app-${sanitizeGroup(segments[i + 1])}`;
-        debugChunks?.("split %s -> %s", meta.normalizedId, group);
-        return group;
-      }
-    }
+  // Route-root marker -> the segment after it is the route id. First marker wins,
+  // so a top-level route owns its whole subtree. The `< dirCount - 1` bound
+  // guarantees the segment after the marker is a directory, not the file.
+  const isMarkerAt = (i: number) =>
+    i < dirCount - 1 && ROUTE_ROOT_DIRS.has(segments[i].toLowerCase());
+  for (let i = 0; i < dirCount - 1; i++) {
+    if (!isMarkerAt(i)) continue;
+    // A source root (`app/`) yields to an inner marker right after it.
+    const marker =
+      SOURCE_ROOT_DIRS.has(segments[i].toLowerCase()) && isMarkerAt(i + 1)
+        ? i + 1
+        : i;
+    const group = `app-${sanitizeGroup(segments[marker + 1])}`;
+    debugChunks?.("split %s -> %s", meta.normalizedId, group);
+    return group;
   }
   // No recognized route structure -> inherit the default serverChunk grouping.
   // This is the actionable "silent" case: app code that did NOT split by route.
@@ -182,3 +205,50 @@ export function resolveClientChunks(
   if (option === true) return (meta) => directoryClientChunks(meta, ctx);
   return option;
 }
+
+/** @vitejs/plugin-rsc's client-reference map; its group modules sit under it. */
+export const CLIENT_REFERENCES_MODULE_ID =
+  "\0virtual:vite-rsc/client-references";
+
+/** Module-id prefix of the per-group virtual module @vitejs/plugin-rsc emits. */
+const CLIENT_GROUP_PREFIX = `${CLIENT_REFERENCES_MODULE_ID}/group/`;
+
+/**
+ * Build-end group report under `DEBUG=rango:chunks`: one line per client
+ * reference group with its client-reference count and the size of the group's
+ * own chunk (code split into shared chunks such as `react`/`router` is not
+ * counted). A group is the loading unit (plugin-rsc imports the group's virtual
+ * module to resolve any one member), so a large group that an always-rendered
+ * component belongs to is downloaded on every route; this line makes that
+ * visible. Covers every group, including ones named by a custom `clientChunks`
+ * function or by plugin-rsc's default `serverChunk` grouping. `undefined` when
+ * the namespace is off, so a normal build does not register it. Group names are
+ * printed with NUL escaped: plugin-rsc's default group is named
+ * `facade:\0virtual:…`, and a raw NUL makes `grep` treat the output as binary
+ * and drop that line, usually the largest group. `log` is injectable for tests.
+ */
+export function clientChunksReport(
+  log: Debugger | undefined = debugChunks,
+): Plugin | undefined {
+  if (!log) return undefined;
+  return {
+    name: "@rangojs/router:client-chunks-report",
+    apply: "build",
+    applyToEnvironment: (env) => env.name === "client",
+    generateBundle(_options, bundle) {
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== "chunk") continue;
+        const facade = chunk.facadeModuleId;
+        if (!facade?.startsWith(CLIENT_GROUP_PREFIX)) continue;
+        log(
+          "group %s: %d client reference(s), %d B (%d B gzip) -> %s",
+          facade.slice(CLIENT_GROUP_PREFIX.length).replaceAll("\0", "\\0"),
+          this.getModuleInfo(facade)?.importedIds.length ?? 0,
+          Buffer.byteLength(chunk.code),
+          gzipSync(chunk.code).length,
+          chunk.fileName,
+        );
+      }
+    },
+  };
+}

package/src/vite/utils/compare-strings.ts

@@ -0,0 +1,9 @@
+/**
+ * Code-unit order, the same on every machine. Generated modules and the cache
+ * version inputs are sorted with it: `localeCompare` depends on the build
+ * machine's ICU data, and build output has to be byte-identical across machines
+ * (discovery/build-versions.ts hashes it).
+ */
+export function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}

package/src/vite/utils/package-resolution.ts

@@ -72,11 +72,20 @@ export function getPackageAliases(): Record<string, string> {
   return aliases;
 }
 
+/**
+ * @vitejs/plugin-rsc puts these vendor specifiers in `optimizeDeps.include`,
+ * and Vite resolves them from the app root, where pnpm's strict layout does
+ * not link the plugin unless the app lists it (#1050). Aliased to the copy
+ * the router resolves, which therefore also wins over an app's own
+ * @vitejs/plugin-rsc. Must hold every vendor entry the plugin includes:
+ * optimize-deps-vendor-resolution.test.ts checks the resolved config.
+ */
 export function getVendorAliases(): Record<string, string> {
   const specs = [
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.browser",
     "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge",
     "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge",
+    "@vitejs/plugin-rsc/vendor/react-server-dom/static.edge",
   ];
   const aliases: Record<string, string> = {};
   for (const spec of specs) {

package/src/vite/utils/prerender-utils.ts

@@ -199,8 +199,11 @@ export function resolvePrerenderError(
   throw error;
 }
 
+/** Build scratch space, relative to the project root. Never shipped. */
+export const RANGO_BUILD_DIR = "node_modules/.rangojs-router-build";
+
 function getStagedAssetDir(projectRoot: string): string {
-  return resolve(projectRoot, "node_modules/.rangojs-router-build/rsc-assets");
+  return resolve(projectRoot, RANGO_BUILD_DIR, "rsc-assets");
 }
 
 export function resetStagedBuildAssets(projectRoot: string): void {

package/src/vite/utils/shared-utils.ts

@@ -15,7 +15,7 @@ import type { HeadScriptsOption } from "../plugin-types.js";
 
 // Cloudflare preset: @cloudflare/vite-plugin sets optimizeDeps.entries (string
 // or array) on the rsc environment. Single source for both the discovery plugin
-// and the version injector so they target the same entry.
+// and the entry bootstrap injector so they target the same entry.
 export function resolveRscEntryFromConfig(
   config: ResolvedConfig,
 ): string | undefined {