@rangojs/router 0.0.0-experimental.8874d8d2 → 0.0.0-experimental.89

package/src/vite/router-discovery.ts

@@ -10,14 +10,19 @@ import type { Plugin } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
+import { createRequire, register } from "node:module";
+import { pathToFileURL } from "node:url";
 import {
   formatNestedRouterConflictError,
   findNestedRouterConflict,
   findRouterFiles,
-  createScanFilter,
 } from "../build/generate-route-types.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
+import {
+  BUILD_ENV_GLOBAL_KEY,
+  createCloudflareProtocolStubPlugin,
+} from "./plugins/cloudflare-protocol-stub.js";
 import {
   exposeInternalIds,
   exposeRouterId,
@@ -43,9 +48,58 @@ import {
 } from "./discovery/virtual-module-codegen.js";
 import { postprocessBundle } from "./discovery/bundle-postprocess.js";
 import { resetStagedBuildAssets } from "./utils/prerender-utils.js";
+import { createRangoDebugger, timed, timedSync, NS } from "./debug.js";
+
+const debugDiscovery = createRangoDebugger(NS.discovery);
+const debugRoutes = createRangoDebugger(NS.routes);
+const debugBuild = createRangoDebugger(NS.build);
+const debugDev = createRangoDebugger(NS.dev);
 
 export { VIRTUAL_ROUTES_MANIFEST_ID };
 
+// ============================================================================
+// Node ESM Loader Hook Registration
+// ============================================================================
+
+/**
+ * Registers a Node ESM loader hook that resolves `cloudflare:*` specifiers
+ * to a data: URL stub. Defense-in-depth alongside the Vite transform in
+ * `cloudflare-protocol-stub.ts`:
+ *
+ * - The Vite transform catches `cloudflare:*` imports in modules that flow
+ *   through Vite's plugin pipeline. That's the vast majority of cases.
+ * - The Node loader catches imports in modules that Vite/Rollup externalize
+ *   (e.g. the `partyserver` package, which has a top-level
+ *   `import { DurableObject, env } from "cloudflare:workers"` and ships
+ *   shapes plugin-rsc marks as external). Externalized modules are loaded
+ *   via Node's native ESM loader, which rejects URL schemes.
+ *
+ * Registration is process-global and one-shot. The hook only intercepts
+ * `cloudflare:*` specifiers; everything else passes through via
+ * `nextResolve()`. It runs in a separate worker thread (Node ESM loader
+ * architecture), so it can't read the `globalThis[BUILD_ENV_GLOBAL_KEY]`
+ * bridge that the Vite transform uses — the stubs served here always
+ * return `env = {}`. That's fine because externalized libraries don't
+ * typically access `env` at module top level; user source (where real
+ * `env` matters at build time) flows through the Vite transform.
+ */
+let loaderHookRegistered = false;
+function ensureCloudflareProtocolLoaderRegistered(): void {
+  if (loaderHookRegistered) return;
+  loaderHookRegistered = true;
+  try {
+    register(
+      new URL("./plugins/cloudflare-protocol-loader-hook.mjs", import.meta.url),
+    );
+  } catch (err: any) {
+    // register() requires Node 18.19+ / 20.6+. Older Node still has the
+    // Vite transform as primary defense.
+    console.warn(
+      `[rsc-router] Could not register Node ESM loader hook for cloudflare:* imports (${err?.message ?? err}). Falling back to Vite transform only.`,
+    );
+  }
+}
+
 // ============================================================================
 // Temp Server Factory
 // ============================================================================
@@ -65,6 +119,11 @@ async function createTempRscServer(
   state: DiscoveryState,
   options: { forceBuild?: boolean; cacheDir?: string } = {},
 ) {
+  // Install the Node ESM loader hook before any module evaluation so
+  // `cloudflare:*` specifiers in externalized/loader-delegated modules
+  // (e.g. packages plugin-rsc marks as external) resolve to stubs
+  // instead of crashing Node's native loader.
+  ensureCloudflareProtocolLoaderRegistered();
   const { default: rsc } = await import("@vitejs/plugin-rsc");
   return createViteServer({
     root: state.projectRoot,
@@ -87,6 +146,7 @@ async function createTempRscServer(
       ...(options.forceBuild ? [hashClientRefs(state.projectRoot)] : []),
       createVersionPlugin(),
       createVirtualStubPlugin(),
+      createCloudflareProtocolStubPlugin(),
       // Dev prerender must use dev-mode IDs (path-based) to match the workerd
       // runtime. forceBuild produces hashed IDs for production bundle consistency.
       exposeInternalIds(options.forceBuild ? { forceBuild: true } : undefined),
@@ -95,6 +155,111 @@ async function createTempRscServer(
   });
 }
 
+// ============================================================================
+// Build-Time Env Resolution
+// ============================================================================
+
+import type {
+  BuildEnvOption,
+  BuildEnvFactoryContext,
+  BuildEnvResult,
+} from "./plugin-types.js";
+
+/**
+ * Resolve the buildEnv option into a concrete { env, dispose? } result.
+ * Handles all four input shapes: false, "auto", factory, plain object.
+ */
+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(
+        '[rsc-router] 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();
+      return {
+        env: proxy.env as Record<string, unknown>,
+        dispose: proxy.dispose,
+      };
+    } catch (err: any) {
+      throw new Error(
+        '[rsc-router] 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.
+ */
+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.
+ */
+async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
+  if (s.buildEnvDispose) {
+    try {
+      await s.buildEnvDispose();
+    } catch (err: any) {
+      console.warn(`[rsc-router] buildEnv dispose failed: ${err.message}`);
+    }
+    s.buildEnvDispose = null;
+  }
+  s.resolvedBuildEnv = undefined;
+  delete (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY];
+}
+
 /**
  * Plugin that discovers router instances at dev/build time via the RSC environment.
  *
@@ -112,6 +277,8 @@ export function createRouterDiscoveryPlugin(
   opts?: PluginOptions,
 ): Plugin {
   const s = createDiscoveryState(entryPath, opts);
+  let viteCommand: "serve" | "build" = "build";
+  let viteMode = "production";
 
   return {
     name: "@rangojs/router:discovery",
@@ -122,32 +289,20 @@ export function createRouterDiscoveryPlugin(
           __RANGO_DEBUG__: JSON.stringify(!!process.env.INTERNAL_RANGO_DEBUG),
         },
       };
-      if (opts?.enableBuildPrerender) {
-        config.environments = {
-          rsc: {
-            build: {
-              rollupOptions: {
-                output: {
-                  manualChunks(id: string) {
-                    if (s.resolvedPrerenderModules?.has(id)) {
-                      return "__prerender-handlers";
-                    }
-                    if (s.resolvedStaticModules?.has(id)) {
-                      return "__static-handlers";
-                    }
-                  },
-                },
-              },
-            },
-          },
-        };
-      }
+      // Prerender/static handler modules are bundled naturally with the
+      // rest of the RSC entry.  A previous design forced them into dedicated
+      // __prerender-handlers / __static-handlers chunks via manualChunks,
+      // but Rollup hoisted all shared dependencies into those chunks,
+      // inflating them to ~1 MB with active runtime code.  Handler code is
+      // evicted in closeBundle regardless of which chunk it lands in.
       return config;
     },
 
     configResolved(config) {
       s.projectRoot = config.root;
       s.isBuildMode = config.command === "build";
+      viteCommand = config.command as "serve" | "build";
+      viteMode = config.mode;
       // Capture user's resolve aliases for the temp server
       s.userResolveAlias = config.resolve.alias;
       // Node preset: pick up auto-discovered router path from the config() hook.
@@ -168,13 +323,6 @@ export function createRouterDiscoveryPlugin(
           s.resolvedEntryPath = entries[0];
         }
       }
-      // Compile include/exclude patterns into a scan filter
-      if (opts?.include || opts?.exclude) {
-        s.scanFilter = createScanFilter(s.projectRoot, {
-          include: opts.include,
-          exclude: opts.exclude,
-        });
-      }
       // Generate combined named-routes.gen.ts from static source parsing.
       // Runs before the dev server starts so the gen file exists immediately for IDE.
       // In build mode, the runtime discovery in buildStart produces the definitive
@@ -225,12 +373,13 @@ export function createRouterDiscoveryPlugin(
       let prerenderTempServer: any = null;
       let prerenderNodeRegistry: Map<string, any> | null = null;
 
-      // Clean up the temporary server when the dev server shuts down
+      // Clean up the temporary server and build env when the dev server shuts down
       server.httpServer?.on("close", () => {
         if (prerenderTempServer) {
           prerenderTempServer.close().catch(() => {});
           prerenderTempServer = null;
         }
+        releaseBuildEnv(s).catch(() => {});
       });
 
       async function getOrCreateTempServer(): Promise<any | null> {
@@ -260,20 +409,35 @@ export function createRouterDiscoveryPlugin(
       }
 
       const discover = async () => {
+        const discoverStart = performance.now();
         const rscEnv = (server.environments as any)?.rsc;
         if (!rscEnv?.runner) {
           // Cloudflare dev: no module runner available (workerd-based RSC env).
           // Set devServerOrigin so the virtual module can inject __PRERENDER_DEV_URL
           // for on-demand prerender via the /__rsc_prerender endpoint.
+          debugDiscovery?.("dev: no rsc runner (cloudflare path)");
           s.devServerOrigin = getDevServerOrigin();
 
           // Create a temp Node.js server to run runtime discovery and generate
           // named route types (static parser can't resolve factory calls).
           try {
-            const tempRscEnv = await getOrCreateTempServer();
+            // Acquire build-time env bindings for dev prerender
+            await timed(debugDiscovery, "acquireBuildEnv", () =>
+              acquireBuildEnv(s, viteCommand, viteMode),
+            );
+
+            const tempRscEnv = await timed(
+              debugDiscovery,
+              "getOrCreateTempServer",
+              () => getOrCreateTempServer(),
+            );
             if (tempRscEnv) {
-              await discoverRouters(s, tempRscEnv);
-              writeRouteTypesFiles(s);
+              await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
+                discoverRouters(s, tempRscEnv),
+              );
+              timedSync(debugDiscovery, "writeRouteTypesFiles", () =>
+                writeRouteTypesFiles(s),
+              );
             }
           } catch (err: any) {
             console.warn(
@@ -281,21 +445,35 @@ export function createRouterDiscoveryPlugin(
             );
           }
 
+          debugDiscovery?.(
+            "dev discovery done (%sms)",
+            (performance.now() - discoverStart).toFixed(1),
+          );
           resolveDiscovery!();
           return;
         }
 
         try {
+          // Acquire build-time env bindings for dev prerender (Node.js path)
+          debugDiscovery?.("dev: node path start");
+          await timed(debugDiscovery, "acquireBuildEnv", () =>
+            acquireBuildEnv(s, viteCommand, viteMode),
+          );
+
           // Set the readiness gate BEFORE discovery so early requests
           // block until manifest is populated
-          const serverMod = await rscEnv.runner.import(
-            "@rangojs/router/server",
+          const serverMod = await timed(
+            debugDiscovery,
+            "import @rangojs/router/server",
+            () => rscEnv.runner.import("@rangojs/router/server"),
           );
           if (serverMod?.setManifestReadyPromise) {
             serverMod.setManifestReadyPromise(discoveryPromise);
           }
 
-          await discoverRouters(s, rscEnv);
+          await timed(debugDiscovery, "discoverRouters", () =>
+            discoverRouters(s, rscEnv),
+          );
 
           // Store server origin for dev prerender endpoint (virtual module injection)
           s.devServerOrigin = getDevServerOrigin();
@@ -305,15 +483,23 @@ export function createRouterDiscoveryPlugin(
           // routes (e.g. Array.from loops) that the static parser cannot see.
           // writeRouteTypesFiles() only writes when content changes, so this
           // won't cause unnecessary HMR triggers.
-          writeRouteTypesFiles(s);
+          timedSync(debugDiscovery, "writeRouteTypesFiles", () =>
+            writeRouteTypesFiles(s),
+          );
 
           // Populate the route map and per-router data in the RSC env
-          await propagateDiscoveryState(rscEnv);
+          await timed(debugDiscovery, "propagateDiscoveryState", () =>
+            propagateDiscoveryState(rscEnv),
+          );
         } catch (err: any) {
           console.warn(
             `[rsc-router] Router discovery failed: ${err.message}\n${err.stack}`,
           );
         } finally {
+          debugDiscovery?.(
+            "dev discovery done (%sms)",
+            (performance.now() - discoverStart).toFixed(1),
+          );
           resolveDiscovery!();
         }
       };
@@ -380,6 +566,17 @@ export function createRouterDiscoveryPlugin(
       };
 
       server.middlewares.use("/__rsc_prerender", async (req: any, res: any) => {
+        const reqStart = debugDev ? performance.now() : 0;
+        const logResult = (status: number, note: string) => {
+          debugDev?.(
+            "/__rsc_prerender %s -> %d %s (%sms)",
+            req.url,
+            status,
+            note,
+            (performance.now() - reqStart).toFixed(1),
+          );
+        };
+
         if (s.discoveryDone) await s.discoveryDone;
 
         const url = new URL(req.url || "/", "http://localhost");
@@ -387,12 +584,36 @@ export function createRouterDiscoveryPlugin(
         if (!pathname) {
           res.statusCode = 400;
           res.end("Missing pathname");
+          logResult(400, "missing pathname");
           return;
         }
 
-        // Prefer the main server's registry (Node.js preset: module runner available).
-        // Fall back to a temp server for Cloudflare where the main RSC env uses workerd.
-        let registry = mainRegistry;
+        // Import the user's entry module to force re-evaluation of any
+        // HMR-invalidated modules in the chain (entry → router → urls → handlers).
+        // This ensures createRouter() re-runs with updated handler code before
+        // we read RouterRegistry. Without this, edits to prerender handler files
+        // produce stale content because the old router instance remains registered.
+        const rscEnv = (server.environments as any)?.rsc;
+        let registry: Map<string, any> | null = null;
+        if (rscEnv?.runner && s.resolvedEntryPath) {
+          try {
+            await rscEnv.runner.import(s.resolvedEntryPath);
+            const serverMod = await rscEnv.runner.import(
+              "@rangojs/router/server",
+            );
+            registry = serverMod.RouterRegistry ?? null;
+          } catch (err: any) {
+            console.warn(
+              `[rsc-router] Dev prerender module refresh failed: ${err.message}`,
+            );
+            res.statusCode = 500;
+            res.end(`Prerender handler error: ${err.message}`);
+            logResult(500, "module refresh failed");
+            return;
+          }
+        } else {
+          registry = mainRegistry;
+        }
 
         if (!registry) {
           // No main registry: the RSC env has no module runner (Cloudflare dev).
@@ -406,6 +627,7 @@ export function createRouterDiscoveryPlugin(
         if (!registry || registry.size === 0) {
           res.statusCode = 503;
           res.end("Prerender runner not available");
+          logResult(503, "no registry");
           return;
         }
 
@@ -421,6 +643,8 @@ export function createRouterDiscoveryPlugin(
               {},
               undefined,
               wantPassthrough,
+              s.resolvedBuildEnv,
+              true, // devMode: check getParams for passthrough routes
             );
             if (!result) continue;
             if (result.passthrough) continue;
@@ -442,6 +666,7 @@ export function createRouterDiscoveryPlugin(
               payload = { segments: result.segments, handles: result.handles };
             }
             res.end(JSON.stringify(payload));
+            logResult(200, `match ${result.routeName}`);
             return;
           } catch (err: any) {
             console.warn(
@@ -452,6 +677,7 @@ export function createRouterDiscoveryPlugin(
 
         res.statusCode = 404;
         res.end("No prerender match");
+        logResult(404, "no match");
       });
 
       // Watch url module and router files for changes and regenerate named-routes.gen.ts.
@@ -499,15 +725,26 @@ export function createRouterDiscoveryPlugin(
           const rscEnv = (server.environments as any)?.rsc;
           if (!rscEnv?.runner || runtimeRediscoveryInProgress) return;
           runtimeRediscoveryInProgress = true;
+          const hmrStart = performance.now();
           try {
-            await discoverRouters(s, rscEnv);
-            writeRouteTypesFiles(s);
-            await propagateDiscoveryState(rscEnv);
+            await timed(debugDiscovery, "hmr discoverRouters", () =>
+              discoverRouters(s, rscEnv),
+            );
+            timedSync(debugDiscovery, "hmr writeRouteTypesFiles", () =>
+              writeRouteTypesFiles(s),
+            );
+            await timed(debugDiscovery, "hmr propagateDiscoveryState", () =>
+              propagateDiscoveryState(rscEnv),
+            );
           } catch (err: any) {
             console.warn(
               `[rsc-router] Runtime re-discovery failed: ${err.message}`,
             );
           } finally {
+            debugDiscovery?.(
+              "hmr re-discovery done (%sms)",
+              (performance.now() - hmrStart).toFixed(1),
+            );
             runtimeRediscoveryInProgress = false;
           }
         };
@@ -516,6 +753,7 @@ export function createRouterDiscoveryPlugin(
           clearTimeout(routeChangeTimer);
           routeChangeTimer = setTimeout(() => {
             routeChangeTimer = undefined;
+            const regenStart = debugDiscovery ? performance.now() : 0;
             try {
               writeCombinedRouteTypesWithTracking(s);
               if (s.perRouterManifests.length > 0) {
@@ -526,6 +764,10 @@ export function createRouterDiscoveryPlugin(
                 `[rsc-router] Route regeneration error: ${err.message}`,
               );
             }
+            debugDiscovery?.(
+              "watcher: regenerated gen files (%sms)",
+              (performance.now() - regenStart).toFixed(1),
+            );
             // Async: re-run runtime discovery to refresh factory-generated
             // routes that the static parser cannot resolve.
             if (s.perRouterManifests.length > 0) {
@@ -560,6 +802,12 @@ export function createRouterDiscoveryPlugin(
             const hasUrls = source.includes("urls(");
             const hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
             if (!hasUrls && !hasCreateRouter) return;
+            debugDiscovery?.(
+              "watcher: %s matches (urls=%s, router=%s)",
+              filePath,
+              hasUrls,
+              hasCreateRouter,
+            );
             // Invalidate cache when a router file changes (new router added/removed)
             if (hasCreateRouter) {
               const nestedRouterConflict = findNestedRouterConflict([
@@ -604,11 +852,24 @@ export function createRouterDiscoveryPlugin(
     async buildStart() {
       if (!s.isBuildMode) return;
       // Only run once across environment builds
-      if (s.mergedRouteManifest !== null) return;
+      if (s.mergedRouteManifest !== null) {
+        debugDiscovery?.(
+          "build: skip (already discovered, env=%s)",
+          this.environment?.name ?? "?",
+        );
+        return;
+      }
+      const buildStartTime = performance.now();
+      debugDiscovery?.("build: start (env=%s)", this.environment?.name ?? "?");
       resetStagedBuildAssets(s.projectRoot);
       s.prerenderManifestEntries = null;
       s.staticManifestEntries = null;
 
+      // Acquire build-time env bindings if configured
+      await timed(debugDiscovery, "build acquireBuildEnv", () =>
+        acquireBuildEnv(s, viteCommand, 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
@@ -616,7 +877,11 @@ export function createRouterDiscoveryPlugin(
       // between the vite plugin and user code loaded via runner.import().
       (globalThis as any).__rscRouterDiscoveryActive = true;
       try {
-        tempServer = await createTempRscServer(s, { forceBuild: true });
+        tempServer = await timed(
+          debugDiscovery,
+          "build createTempRscServer",
+          () => createTempRscServer(s, { forceBuild: true }),
+        );
 
         const rscEnv = (tempServer.environments as any)?.rsc;
         if (!rscEnv?.runner) {
@@ -636,11 +901,15 @@ export function createRouterDiscoveryPlugin(
           s.resolvedStaticModules = tempIdsPlugin.api.staticHandlerModules;
         }
 
-        await discoverRouters(s, rscEnv);
+        await timed(debugDiscovery, "build discoverRouters", () =>
+          discoverRouters(s, rscEnv),
+        );
         // Update named-routes.gen.ts from runtime discovery.
         // The runtime manifest includes dynamically generated routes
         // that the static parser cannot extract from source code.
-        writeRouteTypesFiles(s);
+        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
@@ -665,8 +934,15 @@ export function createRouterDiscoveryPlugin(
       } finally {
         delete (globalThis as any).__rscRouterDiscoveryActive;
         if (tempServer) {
-          await tempServer.close();
+          await timed(debugDiscovery, "build tempServer.close", () =>
+            tempServer.close(),
+          );
         }
+        await releaseBuildEnv(s);
+        debugDiscovery?.(
+          "build discovery done (%sms)",
+          (performance.now() - buildStartTime).toFixed(1),
+        );
       }
     },
 
@@ -690,19 +966,38 @@ export function createRouterDiscoveryPlugin(
         // This is critical for Cloudflare dev where the worker runs in a separate
         // Miniflare process and can only receive manifest data via the virtual module.
         if (s.discoveryDone) {
-          await s.discoveryDone;
+          await timed(
+            debugRoutes,
+            "await discoveryDone (manifest)",
+            () => s.discoveryDone,
+          );
         }
-        return generateRoutesManifestModule(s);
+        const code = await timed(
+          debugRoutes,
+          "generateRoutesManifestModule",
+          () => generateRoutesManifestModule(s),
+        );
+        debugRoutes?.("manifest module emitted (%d bytes)", code?.length ?? 0);
+        return code;
       }
       // Per-router virtual modules: pure data exports (no side effects).
       // ensureRouterManifest() imports the module and stores the data.
       const perRouterPrefix = "\0" + VIRTUAL_ROUTES_MANIFEST_ID + "/";
       if (id.startsWith(perRouterPrefix)) {
         if (s.discoveryDone) {
-          await s.discoveryDone;
+          await timed(
+            debugRoutes,
+            "await discoveryDone (per-router)",
+            () => s.discoveryDone,
+          );
         }
         const routerId = id.slice(perRouterPrefix.length);
-        return generatePerRouterModule(s, routerId);
+        const code = await timed(
+          debugRoutes,
+          `generatePerRouterModule ${routerId}`,
+          () => generatePerRouterModule(s, routerId),
+        );
+        return code;
       }
       // virtual:rsc-router/prerender-paths load handler removed
       return null;
@@ -712,6 +1007,7 @@ export function createRouterDiscoveryPlugin(
     // Used by closeBundle for handler code eviction and prerender data injection.
     generateBundle(_options: any, bundle: any) {
       if (this.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 [
@@ -724,8 +1020,19 @@ export function createRouterDiscoveryPlugin(
         }
       }
 
-      if (!s.resolvedPrerenderModules?.size && !s.resolvedStaticModules?.size)
+      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,
@@ -733,27 +1040,28 @@ export function createRouterDiscoveryPlugin(
       ][]) {
         if (chunk.type !== "chunk") continue;
 
-        // Prerender handlers chunk
-        if (
-          fileName.includes("__prerender-handlers") &&
-          s.resolvedPrerenderModules?.size
-        ) {
+        // Scan all chunks for handler exports (handlers may land in any chunk)
+        if (s.resolvedPrerenderModules?.size) {
           const handlers = extractHandlerExportsFromChunk(
             chunk.code,
             s.resolvedPrerenderModules,
             "Prerender",
-            true,
+            false,
           );
           if (handlers.length > 0) {
-            s.handlerChunkInfo = { fileName, exports: handlers };
+            const existing = s.handlerChunkInfoMap.get(fileName);
+            if (existing) {
+              existing.exports.push(...handlers);
+            } else {
+              s.handlerChunkInfoMap.set(fileName, {
+                fileName,
+                exports: handlers,
+              });
+            }
           }
         }
 
-        // Static handlers chunk
-        if (
-          fileName.includes("__static-handlers") &&
-          s.resolvedStaticModules?.size
-        ) {
+        if (s.resolvedStaticModules?.size) {
           const handlers = extractHandlerExportsFromChunk(
             chunk.code,
             s.resolvedStaticModules,
@@ -761,10 +1069,26 @@ export function createRouterDiscoveryPlugin(
             false,
           );
           if (handlers.length > 0) {
-            s.staticHandlerChunkInfo = { fileName, exports: handlers };
+            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),
+      );
     },
 
     // Build-time pre-rendering: evict handler code and inject collected prerender data.
@@ -778,7 +1102,9 @@ export function createRouterDiscoveryPlugin(
         // Only run for the RSC environment — other environments (client, ssr) have
         // no prerender/static data to process and would just do redundant file I/O.
         if (this.environment && this.environment.name !== "rsc") return;
-        postprocessBundle(s);
+        timedSync(debugBuild, "closeBundle postprocessBundle", () =>
+          postprocessBundle(s),
+        );
       },
     },
   };