@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/vite/debug.ts

@@ -0,0 +1,184 @@
+/**
+ * Debug logging for the Rango Vite plugin.
+ *
+ * Thin wrapper over the `debug` package (the same one Vite uses for its
+ * own `vite:*` namespaces). Enable with either:
+ *
+ *     DEBUG='rango:*' vite dev
+ *     vite --debug rango:*          # vite prepends `vite:`, we bridge it
+ *
+ * Returns `undefined` when no matching namespace is enabled, so call sites
+ * can guard expensive diagnostics with a simple truthiness check:
+ *
+ *     const debug = createRangoDebugger(NS.routes);
+ *     if (debug) debug("built manifest (%d routes) in %dms", n, ms);
+ *
+ * Back-compat: INTERNAL_RANGO_DEBUG=1 still enables all rango namespaces.
+ *
+ * Vite CLI note: `vite --debug <feat>` rewrites to `DEBUG=vite:<feat>` — it
+ * always prefixes with `vite:` and cannot enable bare `rango:*` namespaces.
+ * We work around this by registering a shadow `vite:rango:*` instance for
+ * each debugger, so either invocation works.
+ */
+
+import debugFactory from "debug";
+
+/**
+ * Canonical debug namespaces. Import as `NS.xxx` instead of string literals
+ * so typos become type errors and the full set lives in one place.
+ */
+export const NS = {
+  config: "rango:config",
+  discovery: "rango:discovery",
+  routes: "rango:routes",
+  prerender: "rango:prerender",
+  build: "rango:build",
+  dev: "rango:dev",
+  transform: "rango:transform",
+} as const;
+
+// Back-compat: the legacy INTERNAL_RANGO_DEBUG env var enabled per-site
+// console.logs in this plugin. Map it to `rango:*` so those call sites can
+// be migrated to the `debug` pipeline without breaking existing setups.
+// Uses debug.enable() rather than mutating process.env because the `debug`
+// package already snapshotted DEBUG when it was imported above.
+if (process.env.INTERNAL_RANGO_DEBUG) {
+  const existing = debugFactory.disable();
+  debugFactory.enable(existing ? `${existing},rango:*` : "rango:*");
+}
+
+export type Debugger = (formatter: string, ...args: unknown[]) => void;
+
+export function createRangoDebugger(namespace: string): Debugger | undefined {
+  const primary = debugFactory(namespace);
+  // Shadow namespace so `vite --debug rango:*` (which expands to
+  // DEBUG=vite:rango:*) and `vite --debug` (DEBUG=vite:*) both pick us up.
+  const shadow = debugFactory(`vite:${namespace}`);
+  if (primary.enabled) return primary as Debugger;
+  if (shadow.enabled) return shadow as Debugger;
+  return undefined;
+}
+
+/**
+ * Measure an async block and log its duration via `debug`. No-ops (still
+ * runs `fn`) when the namespace is disabled, so production cost is a single
+ * `.enabled` check per call.
+ *
+ *     await timed(debug, "discover routers", () => discoverRouters(state));
+ */
+export async function timed<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T | Promise<T>,
+): Promise<T> {
+  if (!debug) return await fn();
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Synchronous variant of `timed`. Use for sync call sites — wrapping them
+ * with the async `timed` would create a floating promise that discards any
+ * throw, bypassing the surrounding try/catch.
+ */
+export function timedSync<T>(
+  debug: Debugger | undefined,
+  label: string,
+  fn: () => T,
+): T {
+  if (!debug) return fn();
+  const start = performance.now();
+  try {
+    return fn();
+  } finally {
+    debug("%s (%sms)", label, (performance.now() - start).toFixed(1));
+  }
+}
+
+/**
+ * Aggregate counter for high-frequency call sites (typically Vite
+ * `transform` hooks that run on many files). Per-call logging would
+ * drown real signal; this collects totals and reports once on flush.
+ *
+ *     const counter = createCounter(debug, "use-cache-transform");
+ *     // inside transform():
+ *     return counter?.time(id, () => doWork()) ?? doWork();
+ *     // or manually:
+ *     counter?.record(id, ms);
+ *     // flush on buildEnd (counter resets, so multi-env builds each get
+ *     // their own summary line):
+ *     counter?.flush();
+ *
+ * Returns `undefined` when the namespace is disabled so call sites pay
+ * nothing when off.
+ */
+export interface Counter {
+  record(file: string, ms: number): void;
+  /**
+   * Convenience: time a sync or async block and record it. Propagates
+   * throws; records regardless of outcome. Returns the function's result.
+   */
+  time<T>(file: string, fn: () => T): T;
+  time<T>(file: string, fn: () => Promise<T>): Promise<T>;
+  flush(): void;
+}
+
+export function createCounter(
+  debug: Debugger | undefined,
+  label: string,
+): Counter | undefined {
+  if (!debug) return undefined;
+  let n = 0;
+  let totalMs = 0;
+  let slowestMs = 0;
+  let slowestFile = "";
+  const record = (file: string, ms: number): void => {
+    n++;
+    totalMs += ms;
+    if (ms > slowestMs) {
+      slowestMs = ms;
+      slowestFile = file;
+    }
+  };
+  return {
+    record,
+    time<T>(file: string, fn: () => T | Promise<T>): T | Promise<T> {
+      const start = performance.now();
+      let out: T | Promise<T>;
+      try {
+        out = fn();
+      } catch (err) {
+        record(file, performance.now() - start);
+        throw err;
+      }
+      if (out && typeof (out as any).then === "function") {
+        return (out as Promise<T>).finally(() =>
+          record(file, performance.now() - start),
+        );
+      }
+      record(file, performance.now() - start);
+      return out;
+    },
+    flush(): void {
+      if (n === 0) return;
+      debug(
+        "%s: %d files, %sms total, slowest %sms %s",
+        label,
+        n,
+        totalMs.toFixed(1),
+        slowestMs.toFixed(1),
+        slowestFile,
+      );
+      // Reset so buildEnd firing once per environment (Vite 6+ multi-env)
+      // gives one log line per env rather than silently dropping later data.
+      n = 0;
+      totalMs = 0;
+      slowestMs = 0;
+      slowestFile = "";
+    },
+  };
+}

package/src/vite/discovery/bundle-postprocess.ts

@@ -6,9 +6,9 @@
  */
 
 import { resolve } from "node:path";
-import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { evictHandlerCode } from "../utils/bundle-analysis.js";
+import { copyStagedBuildAssets } from "../utils/prerender-utils.js";
 import type { DiscoveryState } from "./state.js";
 
 /**
@@ -17,11 +17,11 @@ import type { DiscoveryState } from "./state.js";
  */
 export function postprocessBundle(state: DiscoveryState): void {
   const hasPrerenderData =
-    state.prerenderCollectedData &&
-    Object.keys(state.prerenderCollectedData).length > 0;
+    state.prerenderManifestEntries &&
+    Object.keys(state.prerenderManifestEntries).length > 0;
   const hasStaticData =
-    state.staticCollectedData &&
-    Object.keys(state.staticCollectedData).length > 0;
+    state.staticManifestEntries &&
+    Object.keys(state.staticManifestEntries).length > 0;
   if (!hasPrerenderData && !hasStaticData) return;
 
   // Find RSC entry (recorded in generateBundle, fallback to dist/rsc/index.js)
@@ -31,25 +31,25 @@ export function postprocessBundle(state: DiscoveryState): void {
     state.rscEntryFileName ?? "index.js",
   );
 
-  // 1. Evict handler code from __prerender-handlers and __static-handlers chunks.
-  // handlerChunkInfo/staticHandlerChunkInfo are populated by generateBundle
+  // 1. Evict handler code from whichever chunks contain handler exports.
+  // handlerChunkInfoMap/staticHandlerChunkInfoMap are populated by generateBundle
   // after the production RSC build. In Vite 6 multi-environment builds, the
-  // RSC build runs twice (analysis + production). Chunk info is only available
-  // after the production pass, so we run eviction whenever it becomes available.
+  // RSC build runs twice (analysis + production). The maps are cleared at the
+  // start of each generateBundle pass so only production data is used here.
   const evictionTargets: Array<{
-    info: typeof state.handlerChunkInfo;
+    infos: Iterable<import("./state.js").ChunkInfo>;
     fnName: string;
     brand: string;
     label: string;
   }> = [
     {
-      info: state.handlerChunkInfo,
+      infos: state.handlerChunkInfoMap.values(),
       fnName: "Prerender",
       brand: "prerenderHandler",
       label: "handler code from RSC bundle",
     },
     {
-      info: state.staticHandlerChunkInfo,
+      infos: state.staticHandlerChunkInfoMap.values(),
       fnName: "Static",
       brand: "staticHandler",
       label: "static handler code",
@@ -57,67 +57,58 @@ export function postprocessBundle(state: DiscoveryState): void {
   ];
 
   for (const target of evictionTargets) {
-    if (!target.info) continue;
-    const chunkPath = resolve(
-      state.projectRoot,
-      "dist/rsc",
-      target.info.fileName,
-    );
-    try {
-      const code = readFileSync(chunkPath, "utf-8");
-      const result = evictHandlerCode(
-        code,
-        target.info.exports,
-        target.fnName,
-        target.brand,
-      );
-      if (result) {
-        writeFileSync(chunkPath, result.code);
-        const savedKB = (result.savedBytes / 1024).toFixed(1);
-        console.log(
-          `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${target.info.fileName}`,
+    for (const info of target.infos) {
+      const chunkPath = resolve(state.projectRoot, "dist/rsc", info.fileName);
+      try {
+        const code = readFileSync(chunkPath, "utf-8");
+        const result = evictHandlerCode(
+          code,
+          info.exports,
+          target.fnName,
+          target.brand,
+        );
+        if (result) {
+          writeFileSync(chunkPath, result.code);
+          const savedKB = (result.savedBytes / 1024).toFixed(1);
+          console.log(
+            `[rsc-router] Evicted ${target.label} (${savedKB} KB saved): ${info.fileName}`,
+          );
+        }
+      } catch (replaceErr: any) {
+        console.warn(
+          `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
         );
       }
-    } catch (replaceErr: any) {
-      console.warn(
-        `[rsc-router] Failed to evict ${target.label}: ${replaceErr.message}`,
-      );
     }
   }
-  state.handlerChunkInfo = null;
-  state.staticHandlerChunkInfo = null;
+  state.handlerChunkInfoMap.clear();
+  state.staticHandlerChunkInfoMap.clear();
 
   // 2. Write prerender data as separate importable asset modules
-  // and inject a manifest import into the RSC entry.
+  // and inject a lazy manifest loader into the RSC entry.
   if (hasPrerenderData && existsSync(rscEntryPath)) {
     const rscCode = readFileSync(rscEntryPath, "utf-8");
-    if (!rscCode.includes("__PRERENDER_MANIFEST")) {
+    // Check for the specific injection marker to avoid double-injection.
+    if (!rscCode.includes("__prerender-manifest.js")) {
       try {
-        const assetsDir = resolve(state.projectRoot, "dist/rsc/assets");
-        mkdirSync(assetsDir, { recursive: true });
-
-        const manifestEntries: string[] = [];
-        let totalBytes = 0;
+        let totalBytes = copyStagedBuildAssets(
+          state.projectRoot,
+          Object.values(state.prerenderManifestEntries!),
+        );
 
-        for (const [key, entry] of Object.entries(
-          state.prerenderCollectedData!,
+        const manifestMap: Record<string, string> = {};
+        for (const [key, assetFileName] of Object.entries(
+          state.prerenderManifestEntries!,
         )) {
-          const entryJson = JSON.stringify(entry);
-          const contentHash = createHash("sha256")
-            .update(entryJson)
-            .digest("hex")
-            .slice(0, 8);
-          const assetFileName = `__pr-${contentHash}.js`;
-          const assetPath = resolve(assetsDir, assetFileName);
-          const assetCode = `export default ${entryJson};\n`;
-          writeFileSync(assetPath, assetCode);
-          totalBytes += Buffer.byteLength(assetCode);
-          manifestEntries.push(
-            `${JSON.stringify(key)}:()=>import("./assets/${assetFileName}")`,
-          );
+          manifestMap[key] = `./assets/${assetFileName}`;
         }
 
-        const manifestCode = `const m={${manifestEntries.join(",")}};export default m;\n`;
+        const manifestCode = [
+          `const m=JSON.parse('${JSON.stringify(manifestMap).replace(/'/g, "\\'")}');`,
+          `export function loadPrerenderAsset(s){return import(s)}`,
+          `export default m;`,
+          "",
+        ].join("\n");
         const manifestPath = resolve(
           state.projectRoot,
           "dist/rsc/__prerender-manifest.js",
@@ -125,12 +116,12 @@ export function postprocessBundle(state: DiscoveryState): void {
         writeFileSync(manifestPath, manifestCode);
         totalBytes += Buffer.byteLength(manifestCode);
 
-        const injection = `import __pm from "./__prerender-manifest.js";\nglobalThis.__PRERENDER_MANIFEST = __pm;\n`;
+        const injection = `globalThis.__loadPrerenderManifestModule = () => import("./__prerender-manifest.js");\n`;
         writeFileSync(rscEntryPath, injection + rscCode);
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderCollectedData!).length} entries)`,
+          `[rsc-router] Wrote prerender assets (${totalKB} KB total, ${Object.keys(state.prerenderManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(
@@ -144,31 +135,17 @@ export function postprocessBundle(state: DiscoveryState): void {
   // and inject a __STATIC_MANIFEST import into the RSC entry.
   if (hasStaticData && existsSync(rscEntryPath)) {
     const rscCode = readFileSync(rscEntryPath, "utf-8");
-    if (!rscCode.includes("__STATIC_MANIFEST")) {
+    if (!rscCode.includes("__static-manifest.js")) {
       try {
-        const assetsDir = resolve(state.projectRoot, "dist/rsc/assets");
-        mkdirSync(assetsDir, { recursive: true });
-
         const manifestEntries: string[] = [];
-        let totalBytes = 0;
+        let totalBytes = copyStagedBuildAssets(
+          state.projectRoot,
+          Object.values(state.staticManifestEntries!),
+        );
 
-        for (const [handlerId, { encoded, handles }] of Object.entries(
-          state.staticCollectedData!,
+        for (const [handlerId, assetFileName] of Object.entries(
+          state.staticManifestEntries!,
         )) {
-          const contentHash = createHash("sha256")
-            .update(encoded)
-            .digest("hex")
-            .slice(0, 8);
-          const assetFileName = `__st-${contentHash}.js`;
-          const assetPath = resolve(assetsDir, assetFileName);
-          // Store both the Flight payload and handle data
-          const hasHandles = Object.keys(handles).length > 0;
-          const exportValue = hasHandles
-            ? JSON.stringify({ encoded, handles })
-            : JSON.stringify(encoded);
-          const assetCode = `export default ${exportValue};\n`;
-          writeFileSync(assetPath, assetCode);
-          totalBytes += Buffer.byteLength(assetCode);
           manifestEntries.push(
             `${JSON.stringify(handlerId)}:()=>import("./assets/${assetFileName}")`,
           );
@@ -192,7 +169,7 @@ export function postprocessBundle(state: DiscoveryState): void {
 
         const totalKB = (totalBytes / 1024).toFixed(1);
         console.log(
-          `[rsc-router] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticCollectedData!).length} entries)`,
+          `[rsc-router] Wrote static assets (${totalKB} KB total, ${Object.keys(state.staticManifestEntries!).length} entries)`,
         );
       } catch (err: any) {
         throw new Error(

package/src/vite/discovery/discover-routers.ts

@@ -6,7 +6,11 @@
  * router, and builds route tries for O(path_length) matching.
  */
 
-import { buildCombinedRouteMapForRouterFile } from "../../build/generate-route-types.js";
+import {
+  buildCombinedRouteMapForRouterFile,
+  formatNestedRouterConflictError,
+  findNestedRouterConflict,
+} from "../../build/generate-route-types.js";
 import {
   flattenLeafEntries,
   buildRouteToStaticPrefix,
@@ -16,6 +20,9 @@ import {
   expandPrerenderRoutes,
   renderStaticHandlers,
 } from "./prerender-collection.js";
+import { createRangoDebugger, timed, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.discovery);
 
 /**
  * Import the user's entry via RSC runner, generate manifests for each
@@ -34,19 +41,24 @@ export async function discoverRouters(
   // Import the entry file via RSC environment.
   // For node preset: this is the router file (createRouter() registers in RouterRegistry).
   // For cloudflare preset: this is the worker entry (which imports the router).
-  await rscEnv.runner.import(state.resolvedEntryPath);
+  await timed(debug, "inner: import entry", () =>
+    rscEnv.runner.import(state.resolvedEntryPath),
+  );
 
   // Import the router package to access the registry
-  const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+  const serverMod = await timed(
+    debug,
+    "inner: import @rangojs/router/server",
+    () => rscEnv.runner.import("@rangojs/router/server"),
+  );
   let registry: Map<string, any> = serverMod.RouterRegistry;
 
   if (!registry || registry.size === 0) {
     // No RSC routers found directly. Check for host routers with lazy handlers
     // that need to be resolved to trigger sub-app createRouter() calls.
     try {
-      const hostMod = await rscEnv.runner.import("@rangojs/router/host");
       const hostRegistry: Map<string, any> | undefined =
-        hostMod.HostRouterRegistry;
+        serverMod.HostRouterRegistry;
 
       if (hostRegistry && hostRegistry.size > 0) {
         console.log(
@@ -85,7 +97,7 @@ export async function discoverRouters(
         }
       }
     } catch {
-      // @rangojs/router/host not available or import failed, skip
+      // Host-router discovery is best-effort; skip if unavailable
     }
 
     // If still no routers after host router resolution, fail
@@ -97,15 +109,35 @@ export async function discoverRouters(
   }
 
   // Import build utilities for manifest generation
-  const buildMod = await rscEnv.runner.import("@rangojs/router/build");
-  const generateManifest = buildMod.generateManifest;
-
-  state.mergedRouteManifest = {};
-  state.mergedPrecomputedEntries = [];
-  state.perRouterManifests = [];
-  state.perRouterManifestDataMap = new Map();
-  state.perRouterPrecomputedMap = new Map();
-  state.perRouterTrieMap = new Map();
+  const buildMod = await timed(
+    debug,
+    "inner: import @rangojs/router/build",
+    () => rscEnv.runner.import("@rangojs/router/build"),
+  );
+  const generateManifestFull = buildMod.generateManifestFull;
+
+  debug?.("inner: found %d router(s) in registry", registry.size);
+
+  const nestedRouterConflict = findNestedRouterConflict(
+    [...registry.values()]
+      .map((router) => router.__sourceFile)
+      .filter(
+        (sourceFile): sourceFile is string => typeof sourceFile === "string",
+      ),
+  );
+  if (nestedRouterConflict) {
+    throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
+  }
+
+  // Build into local variables first. Only commit to state after the
+  // full pass succeeds, so a failed re-discovery preserves the last
+  // known-good state instead of leaving it partially wiped.
+  const newMergedRouteManifest: Record<string, string> = {};
+  const newMergedPrecomputedEntries: PrecomputedEntry[] = [];
+  const newPerRouterManifests: typeof state.perRouterManifests = [];
+  const newPerRouterManifestDataMap = new Map<string, any>();
+  const newPerRouterPrecomputedMap = new Map<string, PrecomputedEntry[]>();
+  const newPerRouterTrieMap = new Map<string, any>();
   let mergedRouteAncestry: Record<string, string[]> = {};
   let mergedRouteTrailingSlash: Record<string, string> = {};
 
@@ -113,12 +145,17 @@ export async function discoverRouters(
   // Collect all manifests for trie building (avoid re-running generateManifest)
   const allManifests: Array<{ id: string; manifest: any }> = [];
 
+  const manifestGenStart = debug ? performance.now() : 0;
   for (const [id, router] of registry) {
-    if (!router.urlpatterns || !generateManifest) {
+    if (!router.urlpatterns || !generateManifestFull) {
       continue;
     }
 
-    const manifest = generateManifest(router.urlpatterns, routerMountIndex);
+    const manifest = generateManifestFull(
+      router.urlpatterns,
+      routerMountIndex,
+      router.__basename ? { urlPrefix: router.__basename } : undefined,
+    );
     routerMountIndex++;
     allManifests.push({ id, manifest });
     const routeCount = Object.keys(manifest.routeManifest).length;
@@ -128,7 +165,7 @@ export async function discoverRouters(
     const dynamicRoutes = routeCount - staticRoutes;
 
     // Merge into the combined manifest
-    Object.assign(state.mergedRouteManifest, manifest.routeManifest);
+    Object.assign(newMergedRouteManifest, manifest.routeManifest);
 
     // Compute factory-only prefixes: dot-prefixed groups in the runtime
     // manifest that the static parser cannot see. These are routes created
@@ -152,7 +189,7 @@ export async function discoverRouters(
       if (factoryOnlyPrefixes.size === 0) factoryOnlyPrefixes = undefined;
     }
 
-    state.perRouterManifests.push({
+    newPerRouterManifests.push({
       id,
       routeManifest: manifest.routeManifest,
       routeSearchSchemas: manifest.routeSearchSchemas,
@@ -175,18 +212,18 @@ export async function discoverRouters(
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
-      state.mergedPrecomputedEntries,
+      newMergedPrecomputedEntries,
     );
 
     // Store per-router manifest and precomputed entries for isolated virtual modules.
-    state.perRouterManifestDataMap.set(id, manifest.routeManifest);
+    newPerRouterManifestDataMap.set(id, manifest.routeManifest);
     const routerPrecomputed: PrecomputedEntry[] = [];
     flattenLeafEntries(
       manifest.prefixTree,
       manifest.routeManifest,
       routerPrecomputed,
     );
-    state.perRouterPrecomputedMap.set(id, routerPrecomputed);
+    newPerRouterPrecomputedMap.set(id, routerPrecomputed);
 
     console.log(
       `[rsc-router] Router "${id}" -> ${routeCount} routes ` +
@@ -213,11 +250,16 @@ export async function discoverRouters(
     }
   }
 
+  debug?.(
+    "inner: generated manifests for %d router(s) (%sms)",
+    allManifests.length,
+    (performance.now() - manifestGenStart).toFixed(1),
+  );
+
   // Build route trie from merged manifest + ancestry
-  if (
-    state.mergedRouteManifest &&
-    Object.keys(state.mergedRouteManifest).length > 0
-  ) {
+  let newMergedRouteTrie: any = null;
+  const trieStart = debug ? performance.now() : 0;
+  if (Object.keys(newMergedRouteManifest).length > 0) {
     const buildRouteTrie = buildMod.buildRouteTrie;
     if (buildRouteTrie && mergedRouteAncestry) {
       // Build routeToStaticPrefix from saved manifests
@@ -252,8 +294,8 @@ export async function discoverRouters(
         }
       }
 
-      state.mergedRouteTrie = buildRouteTrie(
-        state.mergedRouteManifest,
+      newMergedRouteTrie = buildRouteTrie(
+        newMergedRouteManifest,
         mergedRouteAncestry,
         routeToStaticPrefix,
         Object.keys(mergedRouteTrailingSlash).length > 0
@@ -305,11 +347,27 @@ export async function discoverRouters(
             ? manifest.responseTypeRoutes
             : undefined,
         );
-        state.perRouterTrieMap.set(id, perRouterTrie);
+        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }
 
+  debug?.(
+    "inner: trie build done (%sms)",
+    (performance.now() - trieStart).toFixed(1),
+  );
+
+  // Commit all local state to the shared discovery state atomically.
+  // This ensures a failed re-discovery (e.g. from a transient module
+  // evaluation error) preserves the last known-good state.
+  state.mergedRouteManifest = newMergedRouteManifest;
+  state.mergedPrecomputedEntries = newMergedPrecomputedEntries;
+  state.perRouterManifests = newPerRouterManifests;
+  state.perRouterManifestDataMap = newPerRouterManifestDataMap;
+  state.perRouterPrecomputedMap = newPerRouterPrecomputedMap;
+  state.perRouterTrieMap = newPerRouterTrieMap;
+  state.mergedRouteTrie = newMergedRouteTrie;
+
   // Expand prerender routes and render static handlers (build mode only)
   await expandPrerenderRoutes(state, rscEnv, registry, allManifests);
   await renderStaticHandlers(state, rscEnv, registry);