@rangojs/router 0.0.0-experimental.b02a2fec → 0.0.0-experimental.b30bbf02

package/src/vite/router-discovery.ts

@@ -10,7 +10,7 @@ import type { Plugin } from "vite";
 import { createServer as createViteServer } from "vite";
 import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire, register } from "node:module";
 import { pathToFileURL } from "node:url";
 import {
   formatNestedRouterConflictError,
@@ -19,6 +19,10 @@ import {
 } 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,
@@ -31,7 +35,10 @@ import {
   type DiscoveryState,
   type PluginOptions,
 } from "./discovery/state.js";
-import { consumeSelfGenWrite } from "./discovery/self-gen-tracking.js";
+import {
+  consumeSelfGenWrite,
+  peekSelfGenWrite,
+} from "./discovery/self-gen-tracking.js";
 import { discoverRouters } from "./discovery/discover-routers.js";
 import {
   writeCombinedRouteTypesWithTracking,
@@ -43,10 +50,60 @@ import {
   generatePerRouterModule,
 } from "./discovery/virtual-module-codegen.js";
 import { postprocessBundle } from "./discovery/bundle-postprocess.js";
+import { createDiscoveryGate } from "./discovery/gate-state.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
 // ============================================================================
@@ -66,6 +123,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,
@@ -88,6 +150,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),
@@ -177,6 +240,11 @@ async function acquireBuildEnv(
 
   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;
 }
 
@@ -193,6 +261,7 @@ async function releaseBuildEnv(s: DiscoveryState): Promise<void> {
     s.buildEnvDispose = null;
   }
   s.resolvedBuildEnv = undefined;
+  delete (globalThis as Record<string, unknown>)[BUILD_ENV_GLOBAL_KEY];
 }
 
 /**
@@ -295,6 +364,17 @@ export function createRouterDiscoveryPlugin(
         resolveDiscovery = resolve;
       });
 
+      // Manifest-readiness gate + rediscovery scheduler.
+      // The virtual:rsc-router/routes-manifest module's `load()` hook
+      // awaits `s.discoveryDone`; the gate is reset on each discovery
+      // cycle so workerd's HMR reloads block until the new gen file is
+      // written. State machine + transitions are extracted into
+      // ./discovery/gate-state.ts and unit-tested there — see the
+      // module's JSDoc for the four-flag contract.
+      const gate = createDiscoveryGate(s, debugDiscovery);
+      const beginDiscoveryGate = gate.beginGate;
+      const resolveDiscoveryGate = gate.resolveGate;
+
       // Compute dev server origin from resolved URLs (preferred) or config port (fallback).
       // Called after discovery (or in the load hook) when the server may be listening.
       const getDevServerOrigin = () =>
@@ -317,10 +397,103 @@ export function createRouterDiscoveryPlugin(
         releaseBuildEnv(s).catch(() => {});
       });
 
+      // Mirror the build-path contract (router-discovery.ts ~line 878):
+      // set __rscRouterDiscoveryActive before running user modules so any
+      // module-level router.reverse() calls return a placeholder instead
+      // of throwing. The temp Vite server's module runner has its own
+      // module context; the flag must be on globalThis to cross that
+      // boundary. Cleared in finally so the dev request handlers run with
+      // strict reverse() semantics afterwards.
+      async function importEntryAndRegistry(tempRscEnv: any): Promise<void> {
+        const flagAlreadySet = !!(globalThis as any).__rscRouterDiscoveryActive;
+        if (!flagAlreadySet) {
+          (globalThis as any).__rscRouterDiscoveryActive = true;
+        }
+        try {
+          debugDiscovery?.(
+            "importEntryAndRegistry: importing entry (flag=%s)",
+            (globalThis as any).__rscRouterDiscoveryActive ?? false,
+          );
+          await tempRscEnv.runner.import(s.resolvedEntryPath!);
+          debugDiscovery?.(
+            "importEntryAndRegistry: entry import OK, fetching RouterRegistry",
+          );
+          const serverMod = await tempRscEnv.runner.import(
+            "@rangojs/router/server",
+          );
+          prerenderNodeRegistry = serverMod.RouterRegistry;
+          debugDiscovery?.(
+            "importEntryAndRegistry: registry size=%d",
+            prerenderNodeRegistry?.size ?? 0,
+          );
+        } finally {
+          if (!flagAlreadySet) {
+            delete (globalThis as any).__rscRouterDiscoveryActive;
+            debugDiscovery?.(
+              "importEntryAndRegistry: cleared __rscRouterDiscoveryActive",
+            );
+          }
+        }
+      }
+
       async function getOrCreateTempServer(): Promise<any | null> {
-        if (prerenderNodeRegistry) {
-          return (prerenderTempServer.environments as any)?.rsc ?? null;
+        // Reuse path: if a temp server is already alive, prefer reusing
+        // it over orphaning the existing instance and spinning up a new
+        // one. This handles two cases:
+        //
+        //   1. Steady-state cache hit (cold-start completed, registry
+        //      cached) — return the env immediately.
+        //   2. Recovery from a failed refresh: refreshTempRscEnv() may
+        //      have invalidated and nulled the registry, then thrown
+        //      during importEntryAndRegistry. Without reuse, the next
+        //      call would `createTempRscServer` and overwrite the
+        //      handle, leaking the previous server. Try to re-import on
+        //      the existing runner first; only if THAT fails do we
+        //      close the orphan and create new.
+        if (prerenderTempServer) {
+          const existingEnv = (prerenderTempServer.environments as any)?.rsc;
+          if (existingEnv?.runner) {
+            if (prerenderNodeRegistry) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: cached temp runner reused",
+              );
+              return existingEnv;
+            }
+            // Server alive but registry missing — likely after a prior
+            // refresh's invalidate + import threw. Try to re-import.
+            debugDiscovery?.(
+              "getOrCreateTempServer: server alive but registry missing — re-importing",
+            );
+            try {
+              await importEntryAndRegistry(existingEnv);
+              return existingEnv;
+            } catch (err: any) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: reuse import failed (%s) — closing orphan and creating fresh",
+                err?.message ?? String(err),
+              );
+              await prerenderTempServer.close().catch(() => {});
+              prerenderTempServer = null;
+              prerenderNodeRegistry = null;
+              // Fall through to create-new path below.
+            }
+          } else {
+            // Server reference exists but its rsc env is unhealthy
+            // (no runner). Close and recreate.
+            debugDiscovery?.(
+              "getOrCreateTempServer: existing server has no rsc.runner — closing and recreating",
+            );
+            await prerenderTempServer.close().catch(() => {});
+            prerenderTempServer = null;
+            prerenderNodeRegistry = null;
+          }
         }
+
+        // Create path: no existing temp server (or just nullified above).
+        debugDiscovery?.(
+          "getOrCreateTempServer: creating new temp server, entry=%s",
+          s.resolvedEntryPath ?? "(unset)",
+        );
         try {
           prerenderTempServer = await createTempRscServer(s, {
             cacheDir: "node_modules/.vite_prerender",
@@ -328,14 +501,17 @@ export function createRouterDiscoveryPlugin(
 
           const tempRscEnv = (prerenderTempServer.environments as any)?.rsc;
           if (tempRscEnv?.runner) {
-            await tempRscEnv.runner.import(s.resolvedEntryPath!);
-            const serverMod = await tempRscEnv.runner.import(
-              "@rangojs/router/server",
-            );
-            prerenderNodeRegistry = serverMod.RouterRegistry;
+            await importEntryAndRegistry(tempRscEnv);
             return tempRscEnv;
           }
+          debugDiscovery?.(
+            "getOrCreateTempServer: tempRscEnv.runner unavailable",
+          );
         } catch (err: any) {
+          debugDiscovery?.(
+            "getOrCreateTempServer: FAILED message=%s",
+            err.message,
+          );
           console.warn(
             `[rsc-router] Failed to create temp runner: ${err.message}`,
           );
@@ -343,24 +519,137 @@ export function createRouterDiscoveryPlugin(
         return null;
       }
 
+      // Clear the package-level singleton registries that survive a Vite
+      // moduleGraph.invalidateAll(). createRouter() / createHostRouter()
+      // call .set(id, ...) on these Maps; for "router removed" or
+      // "router id changed" edits, the OLD entry would persist after
+      // re-import without an explicit .clear(), leaving ghost routes
+      // in discoverRouters' output.
+      //
+      // We import the same module the runner imports, so the .clear()
+      // here mutates the same Map the freshly re-imported entry will
+      // populate.
+      async function clearTempRegistries(tempRscEnv: any): Promise<void> {
+        try {
+          const serverMod = await tempRscEnv.runner.import(
+            "@rangojs/router/server",
+          );
+          if (typeof serverMod?.RouterRegistry?.clear === "function") {
+            serverMod.RouterRegistry.clear();
+          }
+          if (typeof serverMod?.HostRouterRegistry?.clear === "function") {
+            serverMod.HostRouterRegistry.clear();
+          }
+          debugDiscovery?.(
+            "clearTempRegistries: cleared RouterRegistry + HostRouterRegistry",
+          );
+        } catch (err: any) {
+          // Non-fatal: if the import fails here, importEntryAndRegistry
+          // below will fail loudly with the same root cause and the
+          // caller will surface it.
+          debugDiscovery?.(
+            "clearTempRegistries: import @rangojs/router/server failed (%s)",
+            err?.message ?? String(err),
+          );
+        }
+      }
+
+      // HMR refresh: keep the temp Vite server alive across HMR cycles and
+      // invalidate its module graph instead of close+recreate. Closing the
+      // temp server during workerd's first post-cold-start module-fetch
+      // window disrupted the main dev server's transport — the user-visible
+      // symptom was a `transport was disconnected, cannot call "fetchModule"`
+      // error on the first urls.tsx edit (workerd's cache was cold, so its
+      // eval was still in flight when our close() ran). Module-graph
+      // invalidation is the architecturally cleaner refresh: same Vite
+      // instance, same transport, fresh source.
+      //
+      // Falls back to close+recreate when neither the env-level nor
+      // server-level moduleGraph exposes invalidateAll() (defensive — Vite
+      // versions / preset configurations may differ in which graph carries
+      // the module-runner cache).
+      async function refreshTempRscEnv(): Promise<any | null> {
+        let tempRscEnv = await getOrCreateTempServer();
+        if (!tempRscEnv) return null;
+
+        // Module-runner cache is on the per-environment graph in Vite 6+;
+        // older / non-environments setups carry it on the server graph.
+        // Try env first, server second.
+        const envGraph = (tempRscEnv as any).moduleGraph;
+        const serverGraph = (prerenderTempServer as any)?.moduleGraph;
+        const target = envGraph?.invalidateAll
+          ? envGraph
+          : serverGraph?.invalidateAll
+            ? serverGraph
+            : null;
+
+        if (!target) {
+          // No invalidate method available — fall back to close+recreate.
+          // This preserves the previous behavior in case a Vite version
+          // doesn't expose invalidateAll on either graph.
+          debugDiscovery?.(
+            "refreshTempRscEnv: invalidateAll unavailable on env+server graphs, falling back to close+recreate",
+          );
+          if (prerenderTempServer) {
+            await prerenderTempServer.close().catch(() => {});
+            prerenderTempServer = null;
+            prerenderNodeRegistry = null;
+          }
+          return await getOrCreateTempServer();
+        }
+
+        debugDiscovery?.(
+          "refreshTempRscEnv: invalidating module graph (%s)",
+          envGraph?.invalidateAll ? "env" : "server",
+        );
+        target.invalidateAll();
+        // Drop the cached registry so importEntryAndRegistry re-reads it
+        // through the now-invalidated module runner.
+        prerenderNodeRegistry = null;
+        // Clear singleton Maps that Vite's moduleGraph invalidation can't
+        // reach (RouterRegistry / HostRouterRegistry). Without this, an
+        // edit that REMOVES a createRouter() call or CHANGES a router id
+        // would leave the old entry in the registry, and discoverRouters
+        // would still emit its routes alongside whatever the new source
+        // declares.
+        await clearTempRegistries(tempRscEnv);
+        await importEntryAndRegistry(tempRscEnv);
+        return tempRscEnv;
+      }
+
       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: cloudflare path start, __rscRouterDiscoveryActive=%s",
+            (globalThis as any).__rscRouterDiscoveryActive ?? false,
+          );
           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 {
             // Acquire build-time env bindings for dev prerender
-            await acquireBuildEnv(s, viteCommand, viteMode);
+            await timed(debugDiscovery, "acquireBuildEnv", () =>
+              acquireBuildEnv(s, viteCommand, viteMode),
+            );
 
-            const tempRscEnv = await getOrCreateTempServer();
+            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(
@@ -368,24 +657,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)
-          await acquireBuildEnv(s, viteCommand, viteMode);
+          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();
@@ -395,24 +695,36 @@ 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!();
         }
       };
 
       // Schedule after all plugins have finished configureServer.
-      // Store the promise so the virtual module's load hook can await it.
-      s.discoveryDone = new Promise<void>((resolve) => {
-        setTimeout(() => discover().then(resolve, resolve), 0);
-      });
+      // The gate (s.discoveryDone) is reset via beginDiscoveryGate() and
+      // resolved when discover() finishes, so the virtual manifest module's
+      // load() awaits the populated state.
+      beginDiscoveryGate();
+      setTimeout(
+        () => discover().then(resolveDiscoveryGate, resolveDiscoveryGate),
+        0,
+      );
 
       // Dev-mode on-demand prerender endpoint.
       // When workerd hits a prerender route, it fetches this endpoint instead of
@@ -470,6 +782,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");
@@ -477,6 +800,7 @@ export function createRouterDiscoveryPlugin(
         if (!pathname) {
           res.statusCode = 400;
           res.end("Missing pathname");
+          logResult(400, "missing pathname");
           return;
         }
 
@@ -500,6 +824,7 @@ export function createRouterDiscoveryPlugin(
             );
             res.statusCode = 500;
             res.end(`Prerender handler error: ${err.message}`);
+            logResult(500, "module refresh failed");
             return;
           }
         } else {
@@ -518,6 +843,7 @@ export function createRouterDiscoveryPlugin(
         if (!registry || registry.size === 0) {
           res.statusCode = 503;
           res.end("Prerender runner not available");
+          logResult(503, "no registry");
           return;
         }
 
@@ -556,6 +882,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(
@@ -566,6 +893,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.
@@ -608,45 +936,117 @@ export function createRouterDiscoveryPlugin(
 
         // Re-run runtime discovery so factory-generated routes that the
         // static parser cannot see are refreshed after source changes.
-        let runtimeRediscoveryInProgress = false;
+        // The state-machine concerns (queued/pending/gatePending) are
+        // owned by the gate created above (./discovery/gate-state.ts).
+        // Here we provide just the env-specific work.
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = (server.environments as any)?.rsc;
-          if (!rscEnv?.runner || runtimeRediscoveryInProgress) return;
-          runtimeRediscoveryInProgress = true;
-          try {
-            await discoverRouters(s, rscEnv);
-            writeRouteTypesFiles(s);
-            await propagateDiscoveryState(rscEnv);
-          } catch (err: any) {
-            console.warn(
-              `[rsc-router] Runtime re-discovery failed: ${err.message}`,
-            );
-          } finally {
-            runtimeRediscoveryInProgress = false;
-          }
+          const hasMainRunner = !!rscEnv?.runner;
+          // Cloudflare HMR has no main RSC runner (workerd is a separate
+          // runtime). When we have a populated runtime manifest from cold
+          // start, we can re-discover via the temp Node runner — the same
+          // mechanism getOrCreateTempServer() uses at startup. Without a
+          // populated manifest there's nothing useful to do, so bail
+          // before involving the gate machine at all.
+          if (!hasMainRunner && s.perRouterManifests.length === 0) return;
+          await gate.runRefreshCycle(async () => {
+            const hmrStart = performance.now();
+            try {
+              if (hasMainRunner) {
+                await timed(debugDiscovery, "hmr discoverRouters", () =>
+                  discoverRouters(s, rscEnv),
+                );
+                timedSync(debugDiscovery, "hmr writeRouteTypesFiles", () =>
+                  writeRouteTypesFiles(s),
+                );
+                await timed(debugDiscovery, "hmr propagateDiscoveryState", () =>
+                  propagateDiscoveryState(rscEnv),
+                );
+              } else {
+                // Cloudflare HMR: invalidate the temp server's RSC module
+                // graph (or close+recreate as a fallback) so the runner
+                // re-reads the freshly edited source. Keeping the same
+                // Vite instance alive avoids disrupting workerd's transport
+                // during the first post-cold-start module-fetch window.
+                const tempRscEnv = await timed(
+                  debugDiscovery,
+                  "hmr refreshTempRscEnv (cloudflare)",
+                  () => refreshTempRscEnv(),
+                );
+                if (!tempRscEnv) {
+                  throw new Error(
+                    "temp runner unavailable for cloudflare HMR rediscovery",
+                  );
+                }
+                await timed(
+                  debugDiscovery,
+                  "hmr discoverRouters (cloudflare)",
+                  () => discoverRouters(s, tempRscEnv),
+                );
+                timedSync(debugDiscovery, "hmr writeRouteTypesFiles", () =>
+                  writeRouteTypesFiles(s),
+                );
+              }
+            } 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),
+              );
+            }
+          });
         };
 
         const scheduleRouteRegeneration = () => {
           clearTimeout(routeChangeTimer);
           routeChangeTimer = setTimeout(() => {
             routeChangeTimer = undefined;
+            const regenStart = debugDiscovery ? performance.now() : 0;
+            const rscEnv = (server.environments as any)?.rsc;
+            const skipStaticWrite =
+              !rscEnv?.runner && s.perRouterManifests.length > 0;
             try {
-              writeCombinedRouteTypesWithTracking(s);
-              if (s.perRouterManifests.length > 0) {
-                supplementGenFilesWithRuntimeRoutes(s);
+              // In cloudflare dev with a populated runtime manifest, the
+              // static parser produces a strictly smaller (and actively
+              // wrong) gen file — supplementGenFilesWithRuntimeRoutes can
+              // only restore factory-only prefixes, and apps with mixed
+              // static+factory routes under shared prefixes (cf-stress)
+              // collapse to the 19-route static view. Skip the static
+              // write entirely; runtime rediscovery below will overwrite
+              // the gen file with the authoritative manifest.
+              if (skipStaticWrite) {
+                debugDiscovery?.(
+                  "watcher: skipping static write (cloudflare HMR — runtime rediscovery owns gen file)",
+                );
+              } else {
+                writeCombinedRouteTypesWithTracking(s);
+                if (s.perRouterManifests.length > 0) {
+                  supplementGenFilesWithRuntimeRoutes(s);
+                }
               }
             } catch (err: any) {
               console.error(
                 `[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.
+            // routes that the static parser cannot resolve. Resolves the
+            // discovery gate when complete.
             if (s.perRouterManifests.length > 0) {
               refreshRuntimeDiscovery().catch((err: any) => {
                 console.warn(
                   `[rsc-router] Runtime re-discovery error: ${err.message}`,
                 );
+                // Even on error, unblock the gate so workerd's reload
+                // doesn't hang indefinitely against the previous manifest.
+                resolveDiscoveryGate();
               });
             }
           }, 100);
@@ -674,6 +1074,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([
@@ -688,6 +1094,17 @@ export function createRouterDiscoveryPlugin(
               }
               s.cachedRouterFiles = undefined;
             }
+            // Note the event in the gate machine IMMEDIATELY (before the
+            // 100ms debounce and any downstream HMR fanout). This sets
+            // both `pendingEvents` (so refresh's finally holds the gate
+            // through the tail window even if no rediscovery is queued)
+            // and resets `discoveryDone` to a fresh pending promise (so
+            // workerd reloads triggered by the same source change can't
+            // observe a stale resolved gate from cold-start). Resolved
+            // by the trailing refreshRuntimeDiscovery() cycle.
+            if (s.perRouterManifests.length > 0) {
+              gate.noteRouteEvent();
+            }
             scheduleRouteRegeneration();
           } catch {
             // Ignore read errors for deleted/moved files
@@ -718,13 +1135,23 @@ 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 acquireBuildEnv(s, viteCommand, viteMode);
+      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
@@ -733,7 +1160,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) {
@@ -753,11 +1184,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
@@ -782,9 +1217,44 @@ 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),
+        );
+      }
+    },
+
+    // Suppress vite's HMR cascade for our own gen-file writes.
+    //
+    // After every cf HMR cycle, refreshTempRscEnv → writeRouteTypesFiles
+    // writes the configured gen files (default `router.named-routes.gen.ts`,
+    // but the source filenames and gen suffix are user-configurable). The
+    // chokidar watcher then fires twice independently: our
+    // `handleRouteFileChange` (already short-circuited by
+    // `consumeSelfGenWrite` inside `maybeHandleGeneratedRouteFileMutation`),
+    // AND vite's own HMR pipeline (which invalidates the gen file's
+    // importers and triggers a second workerd full reload — visible to the
+    // user as a duplicate "[RSCRouter] HMR: version changed" on the client).
+    //
+    // `peekSelfGenWrite` is the authoritative filter: its map only contains
+    // paths that `markSelfGenWrite` has registered, so it natively works
+    // for any configured gen-file name. It is non-consuming so the chokidar
+    // handler that fires later can still consume the same entry. Returning
+    // [] tells vite "no modules invalidated by this change" — safe because
+    // `s.perRouterManifests` is already up-to-date (the write that just
+    // happened is the consequence of our just-completed rediscovery).
+    handleHotUpdate(ctx) {
+      if (peekSelfGenWrite(s, ctx.file)) {
+        debugDiscovery?.(
+          "handleHotUpdate: suppressing self-write HMR cascade for %s",
+          ctx.file,
+        );
+        return [];
       }
     },
 
@@ -808,19 +1278,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;
@@ -830,6 +1319,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 [
@@ -842,8 +1332,13 @@ 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);
@@ -898,6 +1393,14 @@ export function createRouterDiscoveryPlugin(
           }
         }
       }
+
+      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.
@@ -911,7 +1414,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),
+        );
       },
     },
   };