@rangojs/router 0.20.0 → 0.21.0

package/src/vite/discovery/state.ts

@@ -10,6 +10,7 @@ import type { ScanFilter } from "../../build/generate-route-types.js";
 import type { ClientUrlProjection } from "../../client-urls/server-projection.js";
 
 export const VIRTUAL_ROUTES_MANIFEST_ID = "virtual:rsc-router/routes-manifest";
+export const VIRTUAL_LOADER_MANIFEST_ID = "virtual:rsc-router/loader-manifest";
 
 export interface PluginOptions {
   enableBuildPrerender?: boolean;
@@ -147,6 +148,19 @@ export interface DiscoveryState {
    * buildEnd (aborted build).
    */
   shellPhaseTempServer: import("vite").ViteDevServer | null;
+  /**
+   * Inputs of the per-router cache versions (build-versions.ts), recorded by
+   * generateBundle. plugin-rsc builds the RSC and SSR environments twice (a
+   * scan pass, then the real pass); each pass overwrites its slot, so the
+   * buildApp post hook reads the real pass.
+   */
+  serverBuildGraph: import("./build-versions.js").ServerBuildGraph | null;
+  clientBuildGraph: import("./build-versions.js").ClientBuildGraph | null;
+  ssrBundle: import("./build-versions.js").BundleFiles | null;
+  /** Per environment, the chunk files holding the version module. */
+  versionModuleFiles: Map<string, string[]>;
+  /** Prerender and Static payloads the build rendered, by content digest. */
+  buildData: import("./build-versions.js").BuildDataRecord[];
   handlerChunkInfoMap: Map<string, ChunkInfo>;
   staticHandlerChunkInfoMap: Map<string, ChunkInfo>;
   rscEntryFileName: string | null;
@@ -204,6 +218,11 @@ export function createDiscoveryState(
     shellCandidates: null,
     prerenderPayloadValues: null,
     shellPhaseTempServer: null,
+    serverBuildGraph: null,
+    clientBuildGraph: null,
+    ssrBundle: null,
+    versionModuleFiles: new Map(),
+    buildData: [],
     handlerChunkInfoMap: new Map(),
     staticHandlerChunkInfoMap: new Map(),
     rscEntryFileName: null,

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

@@ -8,6 +8,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, basename, join } from "node:path";
 import { jsonParseExpression } from "../utils/manifest-utils.js";
+import { compareStrings } from "../utils/compare-strings.js";
 import { VIRTUAL_ROUTES_MANIFEST_ID } from "./state.js";
 import type { DiscoveryState } from "./state.js";
 
@@ -111,8 +112,12 @@ export function generateRoutesManifestModule(state: DiscoveryState): string {
 
     if (hasClientUrlModules) {
       lines.push(`clearClientUrlProjections();`);
-      for (const [referenceId, projection] of state.clientUrlProjectionMap ??
-        []) {
+      // Sorted: the map fills in transform order, which varies between runs,
+      // and this module's bytes feed cache versions (build-versions.ts).
+      const projections = [...(state.clientUrlProjectionMap ?? [])].sort(
+        ([a], [b]) => compareStrings(a, b),
+      );
+      for (const [referenceId, projection] of projections) {
         lines.push(
           `setClientUrlProjection(${JSON.stringify(referenceId)}, ${jsonParseExpression(projection)});`,
         );

package/src/vite/encryption-key.ts

@@ -9,17 +9,104 @@ import { randomBytes } from "node:crypto";
 // via plugin-rsc's `defineEncryptionKey` so build-time-encrypted bound args
 // decrypt at runtime.
 //
-// Cached per process so the temp server (created during the main build's
-// buildStart) and the main build share one key. Overridable via
-// RANGO_ENCRYPTION_KEY for a stable key across builds/deploys; otherwise a fresh
-// key is generated per build (matching plugin-rsc's default posture, where the
-// key is emitted into the build output regardless).
-let cachedKey: string | undefined;
+// Resolved once per process so the temp server (created during the main
+// build's buildStart) and the main build share one key. Source order:
+// rango({ encryptionKey }), then RANGO_ENCRYPTION_KEY, then a key generated for
+// this build. Only the first two are stable across builds.
+//
+// The key is part of the cache version of every router whose server code
+// encrypts with it (discovery/build-versions.ts adds the emitted key file to
+// that router's hash): a payload cached under the old key carries bound args
+// the new build cannot decrypt. So a generated key gives those routers a new
+// version on every build, which is correct and also means their cache is
+// cleared on every deploy.
+
+/** AES key sizes Web Crypto imports for AES-GCM, in bytes. */
+const AES_KEY_BYTES: ReadonlySet<number> = new Set([16, 24, 32]);
+
+const EXPECTED =
+  "a base64-encoded AES key of 16, 24 or 32 bytes (openssl rand -base64 32)";
+
+interface ResolvedEncryptionKey {
+  key: string;
+  /** True when the consumer supplied the key (option or env variable). */
+  stable: boolean;
+}
+
+let resolvedKey: ResolvedEncryptionKey | undefined;
+
+/**
+ * Throws unless `value` is the base64 form of an AES key (16, 24 or 32 bytes).
+ * `source` names where the value came from, for the message.
+ */
+export function assertValidEncryptionKey(value: unknown, source: string): void {
+  if (typeof value !== "string") {
+    throw new Error(
+      `[rango] ${source} must be a string, received ${typeof value}. Expected ${EXPECTED}.`,
+    );
+  }
+  if (value === "") {
+    throw new Error(
+      `[rango] ${source} is an empty string. Unset it to generate a key per build, ` +
+        `or set it to ${EXPECTED}.`,
+    );
+  }
+  const bytes = /^[A-Za-z0-9+/]+={0,2}$/.test(value)
+    ? Buffer.from(value, "base64")
+    : undefined;
+  // Buffer.from tolerates malformed base64 by dropping what it cannot decode;
+  // the round-trip rejects those inputs instead of using a shorter key.
+  if (
+    !bytes ||
+    bytes.toString("base64").replace(/=+$/, "") !== value.replace(/=+$/, "")
+  ) {
+    throw new Error(
+      `[rango] ${source} is not valid base64. Expected ${EXPECTED}.`,
+    );
+  }
+  if (!AES_KEY_BYTES.has(bytes.length)) {
+    throw new Error(
+      `[rango] ${source} decodes to ${bytes.length} bytes. Expected ${EXPECTED}.`,
+    );
+  }
+}
+
+/**
+ * Resolve the build's encryption key from rango({ encryptionKey }) or the
+ * RANGO_ENCRYPTION_KEY fallback, validating whichever is set. Called by
+ * rango() at config time, before any plugin-rsc instance reads the key, so an
+ * invalid key fails the config load instead of the first encrypted action.
+ * A key generated earlier in the process is kept when neither source is set:
+ * the discovery temp server must encrypt with the main build's key.
+ */
+export function configureEncryptionKey(option: string | undefined): void {
+  if (option !== undefined) {
+    assertValidEncryptionKey(option, "rango({ encryptionKey })");
+    resolvedKey = { key: option, stable: true };
+    return;
+  }
+  const fromEnv = process.env.RANGO_ENCRYPTION_KEY;
+  if (fromEnv !== undefined) {
+    assertValidEncryptionKey(fromEnv, "RANGO_ENCRYPTION_KEY");
+    resolvedKey = { key: fromEnv, stable: true };
+    return;
+  }
+  if (resolvedKey && !resolvedKey.stable) return;
+  resolvedKey = { key: randomBytes(32).toString("base64"), stable: false };
+}
+
+function resolved(): ResolvedEncryptionKey {
+  if (!resolvedKey) configureEncryptionKey(undefined);
+  return resolvedKey!;
+}
 
 export function buildEncryptionKey(): string {
-  cachedKey ??=
-    process.env.RANGO_ENCRYPTION_KEY ?? randomBytes(32).toString("base64");
-  return cachedKey;
+  return resolved().key;
+}
+
+/** False when this build generated its own key (it differs on every build). */
+export function isEncryptionKeyStable(): boolean {
+  return resolved().stable;
 }
 
 // The value plugin-rsc inlines as `export default () => (<expr>)`. A JSON string
@@ -27,3 +114,8 @@ export function buildEncryptionKey(): string {
 export function defineEncryptionKeyExpr(): string {
   return JSON.stringify(buildEncryptionKey());
 }
+
+/** @internal Test seam: forget the process-wide key. */
+export function resetEncryptionKeyForTests(): void {
+  resolvedKey = undefined;
+}

package/src/vite/plugin-types.ts

@@ -239,6 +239,34 @@ interface RangoBaseOptions {
   prerender?: {
     onError?: "fail" | "warn";
   };
+
+  /**
+   * The key inline server actions encrypt their bound arguments with:
+   * base64-encoded 32 bytes (`openssl rand -base64 32`). Pass it from the
+   * environment, never as a literal in the config file:
+   *
+   * ```ts
+   * rango({ encryptionKey: process.env.RANGO_ENCRYPTION_KEY })
+   * ```
+   *
+   * Why set it: the key is part of the cache version of every router whose
+   * server code encrypts with it, because a payload cached under one key
+   * carries arguments another key cannot decrypt. Without a stable key rango
+   * generates one per build, so those routers get a new version, and a cleared
+   * cache, on every deploy. With a stable key their cache survives a deploy
+   * that does not change their server code. It also lets a build decrypt
+   * arguments an earlier build encrypted (a cached or prerendered payload, an
+   * open tab).
+   *
+   * Validated when `rango()` is called: a value that is not base64 or does not
+   * decode to an AES key size (16, 24 or 32 bytes) throws. `undefined` (the
+   * variable is unset) falls back to the `RANGO_ENCRYPTION_KEY` environment
+   * variable, then to a generated key. Rotating the key clears the cache of
+   * the routers that use it.
+   *
+   * @default process.env.RANGO_ENCRYPTION_KEY, else a key generated per build
+   */
+  encryptionKey?: string;
 }
 
 /**

package/src/vite/plugins/{version-injector.ts → entry-bootstrap-injector.ts}

@@ -5,11 +5,9 @@ import { resolveRscEntryFromConfig } from "../utils/shared-utils.js";
 import { RSC_ENTRY_BOOTSTRAP_IMPORTS } from "./virtual-entries.js";
 
 /**
- * Plugin that auto-injects VERSION, routes-manifest, and loader-manifest into
- * custom entry.rsc files. If a custom entry.rsc file uses createRSCHandler but
- * doesn't pass version, this transform adds the import and property
- * automatically. It also ensures the routes-manifest and loader-manifest
- * virtual modules are always imported.
+ * Plugin that auto-injects the routes-manifest and loader-manifest imports
+ * into a custom entry.rsc file (the Cloudflare preset, where the consumer owns
+ * the worker entry).
  *
  * The loader-manifest import is what makes fetchable loaders resolvable on a
  * custom worker entry. The virtual RSC entry (getVirtualEntryRSC) imports the
@@ -23,13 +21,13 @@ import { RSC_ENTRY_BOOTSTRAP_IMPORTS } from "./virtual-entries.js";
  * manifest, hence the production-only failure this fixes.
  * @internal
  */
-export function createVersionInjectorPlugin(
+export function createEntryBootstrapInjectorPlugin(
   rscEntryPath: string | undefined,
 ): Plugin {
   let resolvedEntryPath = "";
 
   return {
-    name: "@rangojs/router:version-injector",
+    name: "@rangojs/router:entry-bootstrap-injector",
     enforce: "pre",
 
     configResolved(config) {
@@ -54,21 +52,8 @@ export function createVersionInjectorPlugin(
       const prepend: string[] = RSC_ENTRY_BOOTSTRAP_IMPORTS.map(
         (id) => `import "${id}";`,
       );
-      let newCode = code;
-      const needsVersion =
-        code.includes("createRSCHandler") &&
-        !code.includes("@rangojs/router:version") &&
-        /createRSCHandler\s*\(\s*\{/.test(code);
 
-      if (needsVersion) {
-        prepend.push(`import { VERSION } from "@rangojs/router:version";`);
-        newCode = newCode.replace(
-          /createRSCHandler\s*\(\s*\{/,
-          "createRSCHandler({\n  version: VERSION,",
-        );
-      }
-
-      const lines = newCode.split("\n");
+      const lines = code.split("\n");
       let insertAt = 0;
       while (insertAt < lines.length) {
         const trimmed = lines[insertAt]!.trim();
@@ -78,7 +63,7 @@ export function createVersionInjectorPlugin(
           break;
         }
       }
-      newCode = [
+      const newCode = [
         ...lines.slice(0, insertAt),
         ...prepend,
         ...lines.slice(insertAt),

package/src/vite/plugins/expose-ids/export-analysis.ts

@@ -55,7 +55,7 @@ export function isExportOnlyFile(
 // (which may be nested, e.g. createLoader<A<B>>(...)) and the call paren are
 // resolved per match via findCallParenAfterGenerics, so a nested `>` no longer
 // defeats the scan the way `<[^>]*>` did (it stopped at the first `>`).
-function createCallPattern(fnNames: string[]): RegExp {
+export function createCallPattern(fnNames: string[]): RegExp {
   return new RegExp(`\\b(?:${fnNames.map(escapeRegExp).join("|")})\\b`, "g");
 }
 

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

@@ -8,10 +8,11 @@ import {
   findCallParenAfterGenerics,
   skipStringOrComment,
 } from "../expose-id-utils.js";
-import { escapeRegExp } from "../../../regex-escape.js";
 import {
   getImportedFnNames,
   buildUnsupportedShapeWarning,
+  createCallPattern,
+  offsetToLineColumn,
 } from "./export-analysis.js";
 import { codeMatchIndices } from "../../../build/route-types/source-scan.js";
 import { createRangoDebugger, createCounter, NS } from "../../debug.js";
@@ -42,6 +43,26 @@ function skipLeadingTrivia(code: string, start: number, end: number): number {
   return i;
 }
 
+/**
+ * A router's `$$id`: a hash of its root-relative file and of its position
+ * among the file's createRouter() calls.
+ *
+ * Not of the call's line. `code` is TS-transformed, and a dev server keeps
+ * comments there that a build drops, so a line of `code` gave build-time
+ * discovery and the bundle different ids for any router with a comment above
+ * it (e2e/test-app, tests/cloudflare-basic): the build registered the lazy
+ * route manifest under an id no running router had. And a line of the file as
+ * written changes with every blank line or comment added above the call,
+ * which renamed the state cookie, the route manifest chunk and the router's
+ * cache versions for an edit that changed nothing.
+ */
+export function routerId(filePath: string, callIndex: number): string {
+  return createHash("sha256")
+    .update(`${filePath}#${callIndex}`)
+    .digest("hex")
+    .slice(0, 8);
+}
+
 export function transformRouter(
   code: string,
   filePath: string,
@@ -53,14 +74,12 @@ export function transformRouter(
   // e.g. createRouter<Config<Env>>(...)) and the opening paren are located
   // separately via findCallParenAfterGenerics so a nested `>` does not defeat
   // the scan (a `<[^>]*>` regex stopped at the first `>`).
-  const pat = new RegExp(
-    `\\b(?:${routerFnNames.map(escapeRegExp).join("|")})\\b`,
-    "g",
-  );
+  const pat = createCallPattern(routerFnNames);
   let match: RegExpExecArray | null;
   const s = new MagicString(code);
   let changed = false;
   const unsupportedSites: Array<{ line: number; column: number }> = [];
+  let callIndex = -1;
 
   // Compute the import path for the generated route names file.
   // filePath is relative to project root (e.g., "src/router.tsx")
@@ -86,6 +105,7 @@ export function transformRouter(
     // type position) yields -1 and is skipped.
     const parenPos = findCallParenAfterGenerics(code, calleeEnd);
     if (parenPos === -1) continue;
+    callIndex++;
 
     const closeParen = findMatchingParen(code, parenPos + 1);
     const callArgs = code.slice(parenPos + 1, closeParen);
@@ -98,12 +118,7 @@ export function transformRouter(
     if (callArgs.includes(`$$routeNames: ${routeNamesVar}`)) continue;
 
     const sourceFilePath = absolutePath ?? filePath;
-    const lineNumber = code.slice(0, callStart).split("\n").length;
-    const hash = createHash("sha256")
-      .update(`${filePath}:${lineNumber}`)
-      .digest("hex")
-      .slice(0, 8);
-    const injected = ` $$id: "${hash}", $$sourceFile: "${sourceFilePath}", $$routeNames: ${routeNamesVar},`;
+    const injected = ` $$id: "${routerId(filePath, callIndex)}", $$sourceFile: "${sourceFilePath}", $$routeNames: ${routeNamesVar},`;
 
     // Skip a leading comment/whitespace run so `createRouter(/* c *\/ {...})`
     // and a newline-then-comment prefix still resolve to the object literal.
@@ -124,9 +139,7 @@ export function transformRouter(
       // stable $$id can be injected here. Record it so the plugin can warn —
       // and crucially do NOT mark changed, so a dead named-routes.gen import is
       // not prepended for a call we never touched.
-      const lastNl = code.lastIndexOf("\n", callStart - 1);
-      const column = callStart - (lastNl + 1) + 1;
-      unsupportedSites.push({ line: lineNumber, column });
+      unsupportedSites.push(offsetToLineColumn(code, callStart));
     }
   }
 
@@ -156,11 +169,19 @@ export function transformRouter(
  */
 export function exposeRouterId(): Plugin {
   let projectRoot = "";
+  // $$sourceFile is read by route discovery and the CLI, which run on a dev
+  // server (the build's discovery temp server included) and need the absolute
+  // path. Nothing reads it when serving, so a production build ships the
+  // root-relative path: an absolute one would put the build machine's checkout
+  // directory in every router's chunk and give the same source a different
+  // cache version per directory (discovery/build-versions.ts hashes the chunk).
+  let rootRelativeSourceFile = false;
   const counter = createCounter(debug, "expose-router-id");
   return {
     name: "@rangojs/router:expose-router-id",
     configResolved(config) {
       projectRoot = config.root;
+      rootRelativeSourceFile = config.command === "build";
     },
     buildEnd() {
       counter?.flush();
@@ -188,7 +209,7 @@ export function exposeRouterId(): Plugin {
           code,
           filePath,
           routerFnNames,
-          normalizePath(id),
+          rootRelativeSourceFile ? undefined : normalizePath(id),
           warn,
         );
       } finally {

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

@@ -45,6 +45,8 @@ import {
   transformHandlerIds,
 } from "./expose-ids/handler-transform.js";
 import { createRangoDebugger, createCounter, NS } from "../debug.js";
+import { compareStrings } from "../utils/compare-strings.js";
+import { VIRTUAL_LOADER_MANIFEST_ID } from "../discovery/state.js";
 
 const debug = createRangoDebugger(NS.transform);
 
@@ -56,7 +58,7 @@ export type { ExposeInternalIdsApi } from "./expose-ids/types.js";
 // Virtual module for loader manifest
 // ---------------------------------------------------------------------------
 
-const VIRTUAL_LOADER_MANIFEST = "virtual:rsc-router/loader-manifest";
+const VIRTUAL_LOADER_MANIFEST = VIRTUAL_LOADER_MANIFEST_ID;
 const RESOLVED_VIRTUAL_LOADER_MANIFEST = "\0" + VIRTUAL_LOADER_MANIFEST;
 
 // ---------------------------------------------------------------------------
@@ -245,10 +247,17 @@ setLoaderImports({});
 `;
       }
 
-      // Build mode: generate lazy import map
+      // Build mode: generate lazy import map. Sorted by id: the registry fills
+      // in directory-scan order (the pre-scan below) and transform order, both
+      // of which vary between machines and runs, and this module's bytes feed
+      // the cache version of every router bundled with it
+      // (discovery/build-versions.ts).
       const lazyImports: string[] = [];
+      const sortedLoaders = [...loaderRegistry].sort(([a], [b]) =>
+        compareStrings(a, b),
+      );
 
-      for (const [hashedId, { filePath, exportName }] of loaderRegistry) {
+      for (const [hashedId, { filePath, exportName }] of sortedLoaders) {
         lazyImports.push(
           `  "${hashedId}": () => import("/${filePath}").then(m => m.${exportName})`,
         );

package/src/vite/plugins/stable-rsc-output.ts

@@ -0,0 +1,147 @@
+import { parseAst, type Plugin } from "vite";
+import { escapeRegExp } from "../../regex-escape.js";
+import { compareStrings } from "../utils/compare-strings.js";
+import { SERVER_REFERENCES_MODULE_ID } from "../discovery/build-versions.js";
+
+/** One property of an object literal, by its position in the source. */
+export interface LiteralProperty {
+  readonly key: string;
+  /** Range of the whole property, key included. */
+  readonly start: number;
+  readonly end: number;
+  /** The value's AST node. */
+  readonly value: any;
+}
+
+/**
+ * The properties of an object-literal AST node, or undefined when it is not an
+ * object literal of plain keys (a spread, a computed key).
+ */
+export function literalProperties(object: any): LiteralProperty[] | undefined {
+  if (object?.type !== "ObjectExpression") return undefined;
+  const properties: LiteralProperty[] = [];
+  for (const property of object.properties ?? []) {
+    const key =
+      property?.type === "Property" && !property.computed
+        ? (property.key?.value ?? property.key?.name)
+        : undefined;
+    if (typeof key !== "string") return undefined;
+    properties.push({
+      key,
+      start: property.start,
+      end: property.end,
+      value: property.value,
+    });
+  }
+  return properties;
+}
+
+/**
+ * The properties of a module's `export default { ... }`, or undefined when
+ * the module does not parse or is not that shape. plugin-rsc generates its
+ * registries (the server-reference map, the assets manifest) in this form.
+ */
+export function defaultExportProperties(
+  code: string,
+): LiteralProperty[] | undefined {
+  let program: any;
+  try {
+    program = parseAst(code);
+  } catch {
+    return undefined;
+  }
+  return literalProperties(
+    (program.body ?? []).find(
+      (node: any) => node?.type === "ExportDefaultDeclaration",
+    )?.declaration,
+  );
+}
+
+/**
+ * Return `code` with the properties of its default-exported object literal
+ * sorted by key, or undefined when there is nothing to reorder (or the module
+ * is not that shape).
+ */
+export function sortDefaultExportProperties(code: string): string | undefined {
+  const properties = defaultExportProperties(code);
+  if (!properties || properties.length < 2) return undefined;
+  const sorted = [...properties].sort((a, b) => compareStrings(a.key, b.key));
+  if (sorted.every((property, index) => property === properties[index])) {
+    return undefined;
+  }
+  return (
+    code.slice(0, properties[0]!.start) +
+    sorted
+      .map((property) => code.slice(property.start, property.end))
+      .join(",\n") +
+    code.slice(properties[properties.length - 1]!.end)
+  );
+}
+
+const ASSETS_MANIFEST_ID = "virtual:vite-rsc/assets-manifest";
+const ASSETS_MANIFEST_IMPORT =
+  /import\s+([A-Za-z_$][\w$]*)\s+from\s*["']virtual:vite-rsc\/assets-manifest["']/;
+/** The local name plugin-rsc's own runtime modules import the manifest under. */
+const ASSETS_MANIFEST_BINDING = "assetsManifest";
+/**
+ * The names plugin-rsc's GENERATED code imports it under. Only these are
+ * renamed: the rename is textual, and a name an app author picked
+ * (`import manifest from ...`) can also be a word in that module's strings.
+ */
+const GENERATED_BINDINGS: ReadonlySet<string> = new Set([
+  "__vite_rsc_assets_manifest__",
+  "__vite_rsc_assets_manifest",
+]);
+
+function identifier(name: string): RegExp {
+  return new RegExp(`(?<![\\w$.])${escapeRegExp(name)}(?![\\w$])`, "g");
+}
+
+/**
+ * Return `code` with its default import of plugin-rsc's assets manifest
+ * renamed to {@link ASSETS_MANIFEST_BINDING}, or undefined when there is
+ * nothing to rename (no such import under a generated name, or the module
+ * uses the canonical name for something else).
+ */
+export function canonicalAssetsManifestBinding(
+  code: string,
+): string | undefined {
+  const local = code.match(ASSETS_MANIFEST_IMPORT)?.[1];
+  if (local === undefined || !GENERATED_BINDINGS.has(local)) return undefined;
+  if (identifier(ASSETS_MANIFEST_BINDING).test(code)) return undefined;
+  return code.replace(identifier(local), ASSETS_MANIFEST_BINDING);
+}
+
+/**
+ * Removes two run-to-run differences from plugin-rsc 0.5.35's build output.
+ * The cache versions hash these bytes (discovery/build-versions.ts).
+ *
+ * 1. Property order of the server-reference map. plugin-rsc writes it in the
+ *    order its transforms first saw each `"use server"` module
+ *    (`ServerReferencesManager.claimMap`), which varies with the concurrent
+ *    scan builds (e2e/test-app: 2 of 2 consecutive builds differed). Sorted
+ *    here so a minified server build, where stripServerReferenceMap finds no
+ *    region comments, still hashes the same bytes.
+ * 2. Local name of the assets-manifest import. plugin-rsc imports the manifest
+ *    under three names; the bundler merges them into one import per chunk and
+ *    keeps a different one from build to build (the cache-versions fixture:
+ *    1 of 10 concurrent builds). One name in, one name out.
+ * @internal
+ */
+export function stableRscOutput(): Plugin {
+  return {
+    name: "@rangojs/router:stable-rsc-output",
+    apply: "build",
+    // After plugin-rsc's transforms, which add the manifest import.
+    enforce: "post",
+    transform(code, id) {
+      const stable =
+        id === SERVER_REFERENCES_MODULE_ID
+          ? sortDefaultExportProperties(code)
+          : code.includes(ASSETS_MANIFEST_ID)
+            ? canonicalAssetsManifestBinding(code)
+            : undefined;
+      return stable === undefined ? null : { code: stable, map: null };
+    },
+  };
+}

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;
     },