@rangojs/router 0.27.0 → 0.28.0

package/src/testing/e2e/page-helpers.ts

@@ -4,6 +4,7 @@
 
 import type { ConsoleMessage, Expect, Locator, Page } from "@playwright/test";
 import { PREFETCH_HEADER } from "../../prefetch-markers.js";
+import { WIRE } from "../../wire-params.js";
 
 // ============================================================================
 //  Standalone helpers (need only a page/locator)
@@ -177,8 +178,7 @@ export function isPrefetchRequest(req: {
 
 // Module-level matcher + handler so blockPrefetch/unblockPrefetch share
 // stable references — Playwright's unroute matches by identity.
-const rscPartialUrl = (url: URL): boolean =>
-  url.searchParams.has("_rsc_partial");
+const rscPartialUrl = (url: URL): boolean => url.searchParams.has(WIRE.partial);
 async function abortPrefetchRoute(
   route: import("@playwright/test").Route,
 ): Promise<void> {

package/src/testing/serve-shell-request.ts

@@ -53,16 +53,16 @@ import type { ExecutionContext } from "../types/request-scope.js";
 import type { HandlerCacheConfig, SSRModule } from "../rsc/types.js";
 import type { createRSCHandler } from "../rsc/handler.js";
 import { setDefaultSSRModuleLoaderForTests } from "../rsc/ssr-module-loader.js";
+import {
+  createPrerenderStore,
+  prerenderManifestEntries,
+} from "../prerender/store.js";
 import {
   POST_QUIESCE_TASK_HOPS,
   SHELL_CAPTURE_MAX_WAIT_MS,
 } from "../rsc/shell-capture-constants.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../segment-fragments.js";
-import {
-  FILL_PARAM,
-  PREFETCH_HEADER,
-  STALE_PARAM,
-} from "../prefetch-markers.js";
+import { PREFETCH_HEADER } from "../prefetch-markers.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
 import { withoutPushedBy } from "../handles/pushed-by.js";
 import type { HandleData } from "../server/handle-store.js";
@@ -76,6 +76,8 @@ import {
   type PprReplayStatus,
   type ShellStatus,
 } from "./shell-status.js";
+import { WIRE } from "../wire-params.js";
+import { writePartialParams } from "../browser/wire-protocol.js";
 
 /** Options for {@link serveShellRequest}. */
 export interface ServeShellRequestOptions<TEnv = any> {
@@ -485,29 +487,14 @@ async function servePrerenderArtifacts(
     const { hashParams } = await import("../prerender/param-hash.js");
     baked.add(pathname);
     if (result && !result.passthrough) {
-      const key = `${result.routeName}/${hashParams(result.params)}`;
-      payloads.set(
-        key,
-        JSON.stringify({ segments: result.segments, handles: result.handles }),
-      );
-      // The intercept variant, keyed and shaped as the build writes it
-      // (vite/discovery/prerender-collection.ts).
-      if (result.interceptSegments?.length) {
-        payloads.set(
-          `${key}/i`,
-          JSON.stringify({
-            segments: [...result.segments, ...result.interceptSegments],
-            handles: result.interceptHandles ?? "",
-          }),
-        );
+      const paramHash = hashParams(result.params);
+      for (const [key, value] of prerenderManifestEntries(result, paramHash)) {
+        payloads.set(key, value);
       }
     }
   }
-  const [{ createPrerenderStore }, { setPrerenderStoreForTests }] =
-    await Promise.all([
-      import("../prerender/store.js"),
-      import("../router/match-middleware/cache-lookup.js"),
-    ]);
+  const { setPrerenderStoreForTests } =
+    await import("../router/match-middleware/cache-lookup.js");
   const previousLoader = globalThis.__loadPrerenderManifestModule;
   globalThis.__loadPrerenderManifestModule = async () => ({
     default: Object.fromEntries([...payloads.keys()].map((key) => [key, key])),
@@ -585,12 +572,12 @@ async function buildActionRequest(
   const { encodeReply } =
     await import("@vitejs/plugin-rsc/vendor/react-server-dom/client.edge");
   registerTestAction(action.ref, action.id, "serveShellRequest");
-  const target = new URL(url);
-  target.searchParams.set("_rsc_action", action.id);
-  target.searchParams.set("_rsc_segments", (action.segments ?? []).join(","));
-  if (action.rewriteTarget) {
-    target.searchParams.set("_rsc_rt", action.rewriteTarget);
-  }
+  const target = writePartialParams(new URL(url), {
+    action: action.id,
+    segmentIds: action.segments ?? [],
+    emptySegments: "send",
+    rewriteTarget: action.rewriteTarget,
+  });
   headers.set("rsc-action", action.id);
   if (!headers.has("X-RSC-Router-Client-Path")) {
     headers.set("X-RSC-Router-Client-Path", url.href);
@@ -647,13 +634,13 @@ async function buildRequest(
     );
   }
   const target = new URL(url);
-  target.searchParams.set("_rsc_partial", "true");
-  target.searchParams.set("_rsc_segments", segments.join(","));
-  if (rewriteTarget) target.searchParams.set("_rsc_rt", rewriteTarget);
+  target.searchParams.set(WIRE.partial, "true");
+  target.searchParams.set(WIRE.segments, segments.join(","));
+  if (rewriteTarget) target.searchParams.set(WIRE.rewriteTarget, rewriteTarget);
   // As the browser sends them: browser/navigation-client.ts (fill, stale) and
   // browser/prefetch/fetch.ts (prefetch).
-  if (fill) target.searchParams.set(FILL_PARAM, "1");
-  if (stale) target.searchParams.set(STALE_PARAM, "true");
+  if (fill) target.searchParams.set(WIRE.fill, "1");
+  if (stale) target.searchParams.set(WIRE.stale, "true");
   if (prefetch && !headers.has(PREFETCH_HEADER)) {
     headers.set(PREFETCH_HEADER, "1");
   }

package/src/types/cache-types.ts

@@ -137,9 +137,12 @@ export interface CacheOptions<TEnv = unknown> {
   ) => boolean;
 
   /**
-   * Custom cache key function - FULL OVERRIDE.
-   * Bypasses default key generation AND store's keyGenerator. The result is
-   * stored namespaced (`key:` plus its URI encoding), so no value it returns
+   * Custom cache key function. Replaces the URL part of the default key
+   * (host, path, params, search) AND bypasses the store's keyGenerator. The
+   * request kind stays: a document request, a navigation and each intercept
+   * navigation keep their own record under one result, so the result decides
+   * which requests of one kind share a record. It is stored namespaced
+   * (`key:` plus its URI encoding, then the kind), so no value it returns
    * names another route's record; a nested cache() keys its records within
    * this partition.
    *

package/src/types/error-types.ts

@@ -83,7 +83,15 @@ export interface OnErrorContext<TEnv = any> {
   env?: TEnv;
   /** Duration from request start to error (milliseconds) */
   duration?: number;
-  /** Whether this is a partial/navigation request */
+  /**
+   * Whether this is a partial/navigation request, on an error the segment
+   * walk catches (a handler that throws, a DSL loader that rejects): `true`
+   * for a navigation, unset for a document. An error in the background
+   * re-render of a `cache()` record (a stale HIT's refresh, the write of a
+   * navigation that kept a layout mounted) reports the request that started
+   * it. A streamed (`loading()`) handler's rejection does not carry it, in
+   * either render; the `routing` phase reports `false`.
+   */
   isPartial?: boolean;
   /** Whether an error boundary caught the error */
   handledByBoundary?: boolean;

package/src/types/handler-context.ts

@@ -462,7 +462,7 @@ export type InternalHandlerContext<
   _reverseScope?: import("../server/context.js").ReverseScope;
   /**
    * @internal The on-demand overlay holds a "removed" marker for this request
-   * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On
+   * (readPrerenderSource, cache-lookup.ts); gateOnDemandProducer reads it. On
    * this context, not the request's: withCacheLookup documents that the
    * request ALS can be lost mid-pipeline on workerd.
    */
@@ -510,6 +510,17 @@ export type InternalHandlerContext<
    * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
    */
   _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+  /**
+   * @internal DSL loaders registered and not started, by `$$id`: a prefetch
+   * deferred them, or a pass that skips loaders (`skipLoaders`) did not run
+   * them. A reader's ctx.use() starts one through its registration
+   * (registerDeferredLoader, startDeferredLoader in
+   * router/segment-resolution/prefetch-deferral.ts).
+   */
+  _deferredLoaders?: Map<
+    string,
+    import("../router/segment-resolution/prefetch-deferral.js").DeferredLoader
+  >;
   /**
    * @internal Whether a loader was started in this request: a run of it (a
    * handler's or another loader's ctx.use()) or its cache() binding. A

package/src/types/segments.ts

@@ -165,7 +165,7 @@ export interface ResolvedSegment {
   loaderData?: any; // For loaders: the resolved data from loader execution
   /**
    * True when this loader was awaited before first flush
-   * (loader(Def, { ssr: false })). Stamped by resolveLoaders (fresh.ts) on
+   * (loader(Def, { ssr: false })). Stamped by resolveOwnerLoaders on
    * document AND shell-capture renders — capture bakes flagged loaders and
    * awaits the same lane. Feeds segment-system's settled-value delivery and
    * the dev SSR suspension warning (ssr-suspension-warning.ts).

package/src/vite/discovery/build-discovery-phase.ts

@@ -0,0 +1,204 @@
+/**
+ * Build discovery phase: the discovery plugin's buildStart, buildApp (post)
+ * and buildEnd hooks.
+ *
+ * buildStart discovers routers through a temp RSC server and writes the
+ * generated route types. When PPR shell candidates exist, it defers closing
+ * that server, and releasing the buildEnv, as a PAIR: the buildApp post hook
+ * releases them after the shell capture (success), buildEnd after an
+ * environment build failure (abort).
+ */
+
+import type { Rolldown, ViteBuilder } from "vite";
+import type { DiscoveryState } from "./state.js";
+import { createTempRscServer } from "../temp-rsc-server.js";
+import { acquireBuildEnv, releaseBuildEnv } from "./build-env.js";
+import { discoverRouters } from "./discover-routers.js";
+import { writeRouteTypesFiles } from "./route-types-writer.js";
+import { runShellPrerenderPhase } from "./shell-prerender-phase.js";
+import { runRouterVersionsPhase } from "./router-versions-phase.js";
+import { resetStagedBuildAssets } from "../utils/prerender-utils.js";
+import { createRangoDebugger, timed, timedSync, NS } from "../debug.js";
+
+const debugDiscovery = createRangoDebugger(NS.discovery);
+
+/**
+ * Reset the per-build prerender collection state. A helper (not inline
+ * assignments in buildStart) so TS's property narrowing does not pin
+ * `s.shellCandidates` to `null` across the discovery call that repopulates
+ * it — the finally block re-reads it to decide the temp-server keep-alive.
+ */
+function resetPrerenderCollection(s: DiscoveryState): void {
+  s.prerenderManifestEntries = null;
+  s.staticManifestEntries = null;
+  s.shellCandidates = null;
+  s.prerenderPayloadValues = null;
+  s.buildData = [];
+}
+
+/**
+ * buildStart. Build mode: create a temporary Vite dev server to access the
+ * RSC environment's module runner, then discover routers and generate
+ * manifests. The manifest data is stored for the virtual module's load hook.
+ */
+export async function buildDiscoveryPhase(
+  s: DiscoveryState,
+  context: Rolldown.PluginContext,
+): Promise<void> {
+  if (!s.isBuildMode) return;
+  // Only run once across environment builds
+  if (s.mergedRouteManifest !== null) {
+    debugDiscovery?.(
+      "build: skip (already discovered, env=%s)",
+      context.environment?.name ?? "?",
+    );
+    return;
+  }
+  const buildStartTime = performance.now();
+  debugDiscovery?.("build: start (env=%s)", context.environment?.name ?? "?");
+  resetStagedBuildAssets(s.projectRoot);
+  resetPrerenderCollection(s);
+
+  // Acquire build-time env bindings if configured
+  await timed(debugDiscovery, "build acquireBuildEnv", () =>
+    acquireBuildEnv(s, s.viteCommand, s.viteMode),
+  );
+
+  let tempServer: any = null;
+  // Signal to user-space code (e.g. reverse.ts) that build-time discovery
+  // is active. Uses globalThis because the temp server's module runner
+  // creates a separate module context — there is no shared import path
+  // between the vite plugin and user code loaded via runner.import().
+  (globalThis as any).__rscRouterDiscoveryActive = true;
+  try {
+    tempServer = await timed(debugDiscovery, "build createTempRscServer", () =>
+      createTempRscServer(s, { forceBuild: true }),
+    );
+
+    const rscEnv = (tempServer.environments as any)?.rsc;
+    if (!rscEnv?.runner) {
+      console.warn(
+        "[rango] RSC environment runner not available during build, skipping manifest generation",
+      );
+      return;
+    }
+
+    // Point resolvedStaticModules at the temp server's expose-internal-ids
+    // plugin so that discoverRouters() can access the static handler module
+    // map after the temp server's transforms populate it.
+    const tempIdsPlugin = (tempServer as any).config?.plugins?.find(
+      (p: any) => p.name === "@rangojs/router:expose-internal-ids",
+    );
+    if (tempIdsPlugin?.api?.staticHandlerModules) {
+      s.resolvedStaticModules = tempIdsPlugin.api.staticHandlerModules;
+    }
+
+    await timed(debugDiscovery, "build discoverRouters", () =>
+      discoverRouters(s, rscEnv, (tempServer.environments as any)?.ssr),
+    );
+    // Update named-routes.gen.ts from runtime discovery.
+    // The runtime manifest includes dynamically generated routes
+    // that the static parser cannot extract from source code.
+    timedSync(debugDiscovery, "build writeRouteTypesFiles", () =>
+      writeRouteTypesFiles(s),
+    );
+  } catch (err: any) {
+    // Extract the user source file from the stack trace (skip internal frames)
+    const sourceFile = err.stack
+      ?.split("\n")
+      .find(
+        (line: string) =>
+          line.includes(s.projectRoot) && !line.includes("node_modules"),
+      )
+      ?.match(/\(([^)]+)\)/)?.[1];
+    // Extract the route name from "Unknown route: <name>" errors
+    const routeName = err.message?.match(/Unknown route: (.+)/)?.[1];
+    const details = [
+      routeName ? `  Route name: ${routeName}` : null,
+      sourceFile ? `  File: ${sourceFile}` : null,
+      err.stack ? `  Stack:\n${err.stack}` : null,
+    ]
+      .filter(Boolean)
+      .join("\n");
+    throw new Error(`[rango] Build-time router discovery failed:\n${details}`, {
+      cause: err,
+    });
+  } finally {
+    delete (globalThis as any).__rscRouterDiscoveryActive;
+    if (tempServer && s.shellCandidates?.length) {
+      // Prerender+ppr candidates exist: keep the temp server (and its
+      // realm — tries installed, registry populated) alive for the
+      // post-build shell capture phase (buildApp post, producer B #699).
+      // The prelude embeds built client asset URLs, so the capture can
+      // only run after the client build; that phase closes the server.
+      // buildEnv release is deferred with it — a bake-lane loader
+      // executing during the capture may read ctx.env.
+      s.shellPhaseTempServer = tempServer;
+    } else {
+      if (tempServer) {
+        await timed(debugDiscovery, "build tempServer.close", () =>
+          tempServer.close(),
+        );
+      }
+      await releaseBuildEnv(s);
+    }
+    debugDiscovery?.(
+      "build discovery done (%sms)",
+      (performance.now() - buildStartTime).toFixed(1),
+    );
+  }
+}
+
+/**
+ * buildApp (post). Post-build phases, after EVERY environment bundle is
+ * written.
+ *
+ * 1. Cache versions (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
+ *    (buildEndPhase owns the aborted-build path) — the phase itself is a pure
+ *    producer and tears down only the globals it installs.
+ */
+export async function postBuildPhase(
+  s: DiscoveryState,
+  builder: ViteBuilder,
+): Promise<void> {
+  try {
+    await runShellPrerenderPhase(
+      s,
+      builder as any,
+      runRouterVersionsPhase(s, builder as any),
+    );
+  } finally {
+    if (s.isBuildMode) {
+      const tempServer = s.shellPhaseTempServer;
+      s.shellPhaseTempServer = null;
+      if (tempServer) await tempServer.close();
+      await releaseBuildEnv(s);
+    }
+  }
+}
+
+/**
+ * buildEnd. An environment build failure aborts the builder before the
+ * buildApp post hook — never leak the kept temp server (open handles hang
+ * the CLI) or the deferred buildEnv (a live miniflare proxy).
+ */
+export async function buildEndPhase(
+  s: DiscoveryState,
+  error: Error | undefined,
+): Promise<void> {
+  if (!error || !s.shellPhaseTempServer) return;
+  const tempServer = s.shellPhaseTempServer;
+  s.shellPhaseTempServer = null;
+  try {
+    await tempServer.close();
+  } finally {
+    await releaseBuildEnv(s);
+  }
+}

package/src/vite/discovery/build-env.ts

@@ -0,0 +1,148 @@
+/**
+ * Build-time env (rango({ buildEnv })): resolution of the option and the
+ * lifetime of the resolved bindings on DiscoveryState. Acquired by dev
+ * discovery (dev-server-phase.ts) and build discovery
+ * (build-discovery-phase.ts).
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { BUILD_ENV_GLOBAL_KEY } from "../plugins/cloudflare-protocol-stub.js";
+import type {
+  BuildEnvOption,
+  BuildEnvFactoryContext,
+  BuildEnvResult,
+} from "../plugin-types.js";
+import type { DiscoveryState } from "./state.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.
+ */
+export async function resolveBuildEnv(
+  option: BuildEnvOption | undefined,
+  factoryCtx: BuildEnvFactoryContext,
+): Promise<BuildEnvResult | null> {
+  if (!option) return null;
+
+  if (option === "auto") {
+    if (factoryCtx.preset !== "cloudflare") {
+      throw new Error(
+        '[rango] buildEnv: "auto" is only supported with preset: "cloudflare". ' +
+          "Use a factory function or plain object for other presets.",
+      );
+    }
+    try {
+      // Resolve wrangler from the user's project root (not the router package)
+      const userRequire = createRequire(
+        resolve(factoryCtx.root, "package.json"),
+      );
+      const wranglerPath = userRequire.resolve("wrangler");
+      const { getPlatformProxy } = (await import(
+        pathToFileURL(wranglerPath).href
+      )) as {
+        getPlatformProxy: (opts?: any) => Promise<any>;
+      };
+      const proxy = await getPlatformProxy(
+        wranglerProxyOptions(factoryCtx.root),
+      );
+      return {
+        env: proxy.env as Record<string, unknown>,
+        dispose: proxy.dispose,
+      };
+    } catch (err: any) {
+      throw new Error(
+        '[rango] buildEnv: "auto" requires wrangler to be installed.\n' +
+          `Install it with: pnpm add -D wrangler\n${err.message}`,
+      );
+    }
+  }
+
+  if (typeof option === "function") {
+    return await option(factoryCtx);
+  }
+
+  // Plain object
+  return { env: option };
+}
+
+/**
+ * Acquire build-time env bindings and store on discovery state.
+ * Returns true if env was acquired, false if buildEnv is disabled.
+ */
+export async function acquireBuildEnv(
+  s: DiscoveryState,
+  command: "serve" | "build",
+  mode: string,
+): Promise<boolean> {
+  const option = s.opts?.buildEnv;
+  if (!option) return false;
+
+  const result = await resolveBuildEnv(option, {
+    root: s.projectRoot,
+    mode,
+    command,
+    preset: s.opts?.preset ?? "node",
+  });
+  if (!result) return false;
+
+  s.resolvedBuildEnv = result.env;
+  s.buildEnvDispose = result.dispose ?? null;
+  // Bridge the resolved env into `cloudflare:workers`'s stubbed `env`
+  // export so user code that does `import { env } from "cloudflare:workers"`
+  // sees the real bindings proxy during discovery + prerender instead of
+  // an empty object. The stub reads this global at module-evaluation time.
+  (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY] = result.env;
+  return true;
+}
+
+/**
+ * Release build-time env resources and clear state.
+ */
+export async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
+  if (s.buildEnvDispose) {
+    try {
+      await s.buildEnvDispose();
+    } catch (err: any) {
+      console.warn(`[rango] buildEnv dispose failed: ${err.message}`);
+    }
+    s.buildEnvDispose = null;
+  }
+  s.resolvedBuildEnv = undefined;
+  delete (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY];
+}

package/src/vite/discovery/bundle-scan-phase.ts

@@ -0,0 +1,128 @@
+/**
+ * Bundle scan phase: the discovery plugin's generateBundle hook.
+ *
+ * Records the inputs of the per-router cache versions (build-versions.ts) for
+ * every environment and, during the RSC build, the RSC entry filename and the
+ * chunks holding Prerender/Static handler exports. closeBundle
+ * (bundle-postprocess.ts) uses them for handler code eviction and prerender
+ * data injection.
+ */
+
+import type { Rolldown } from "vite";
+import type { DiscoveryState } from "./state.js";
+import {
+  recordBundleFiles,
+  recordClientGraph,
+  recordServerGraph,
+  recordVersionModuleFiles,
+} from "./build-versions.js";
+import { extractHandlerExportsFromChunk } from "../utils/bundle-analysis.js";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debugBuild = createRangoDebugger(NS.build);
+
+export function bundleScanPhase(
+  s: DiscoveryState,
+  context: Rolldown.PluginContext,
+  bundle: any,
+): void {
+  // 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 = context.environment?.name;
+    if (envName) {
+      s.versionModuleFiles.set(envName, recordVersionModuleFiles(bundle));
+    }
+    if (envName === "rsc") {
+      s.serverBuildGraph = recordServerGraph(context, bundle);
+    } else if (envName === "client") {
+      s.clientBuildGraph = recordClientGraph(context, bundle);
+    } else if (envName === "ssr") {
+      s.ssrBundle = recordBundleFiles(bundle);
+    }
+  }
+  if (context.environment?.name !== "rsc") return;
+  const genStart = debugBuild ? performance.now() : 0;
+
+  // Record RSC entry chunk filename for closeBundle injection
+  for (const [fileName, chunk] of Object.entries(bundle) as [string, any][]) {
+    if (chunk.type === "chunk" && chunk.isEntry) {
+      s.rscEntryFileName = fileName;
+      break;
+    }
+  }
+
+  if (!s.resolvedPrerenderModules?.size && !s.resolvedStaticModules?.size) {
+    debugBuild?.(
+      "generateBundle (rsc): no handlers to scan (%sms)",
+      (performance.now() - genStart).toFixed(1),
+    );
+    return;
+  }
+
+  // Clear maps at the start of each RSC generateBundle pass.
+  // Vite 6 multi-environment builds run RSC twice (analysis + production);
+  // clearing prevents stale/duplicate records from the analysis pass.
+  s.handlerChunkInfoMap.clear();
+  s.staticHandlerChunkInfoMap.clear();
+
+  for (const [fileName, chunk] of Object.entries(bundle) as [string, any][]) {
+    if (chunk.type !== "chunk") continue;
+
+    // Scan all chunks for handler exports (handlers may land in any chunk)
+    if (s.resolvedPrerenderModules?.size) {
+      const handlers = extractHandlerExportsFromChunk(
+        chunk.code,
+        s.resolvedPrerenderModules,
+        "Prerender",
+        false,
+        // Mark onDemand exports (retained, not evicted) from the
+        // discovery-derived $$id set — the same evaluated source that sets
+        // the runtime od trie flag, so retention and serve can never
+        // disagree. Populated by discoverRouters (buildStart), which runs
+        // before this generateBundle pass.
+        s.onDemandHandlerIds,
+      );
+      if (handlers.length > 0) {
+        const existing = s.handlerChunkInfoMap.get(fileName);
+        if (existing) {
+          existing.exports.push(...handlers);
+        } else {
+          s.handlerChunkInfoMap.set(fileName, {
+            fileName,
+            exports: handlers,
+          });
+        }
+      }
+    }
+
+    if (s.resolvedStaticModules?.size) {
+      const handlers = extractHandlerExportsFromChunk(
+        chunk.code,
+        s.resolvedStaticModules,
+        "Static",
+        false,
+      );
+      if (handlers.length > 0) {
+        const existing = s.staticHandlerChunkInfoMap.get(fileName);
+        if (existing) {
+          existing.exports.push(...handlers);
+        } else {
+          s.staticHandlerChunkInfoMap.set(fileName, {
+            fileName,
+            exports: handlers,
+          });
+        }
+      }
+    }
+  }
+
+  debugBuild?.(
+    "generateBundle (rsc): scanned %d chunks, %d prerender chunk(s), %d static chunk(s) (%sms)",
+    Object.keys(bundle).length,
+    s.handlerChunkInfoMap.size,
+    s.staticHandlerChunkInfoMap.size,
+    (performance.now() - genStart).toFixed(1),
+  );
+}