@rangojs/router 0.0.0-experimental.92 → 0.0.0-experimental.93

package/dist/vite/index.js

@@ -2040,7 +2040,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.92",
+  version: "0.0.0-experimental.93",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3376,11 +3376,10 @@ function createVersionInjectorPlugin(rscEntryPath) {
       if (normalizedId !== normalizedEntry) {
         return null;
       }
-      const prepend = [];
+      const prepend = [
+        `import "virtual:rsc-router/routes-manifest";`
+      ];
       let newCode = code;
-      if (!code.includes("virtual:rsc-router/routes-manifest")) {
-        prepend.push(`import "virtual:rsc-router/routes-manifest";`);
-      }
       const needsVersion = code.includes("createRSCHandler") && !code.includes("@rangojs/router:version") && /createRSCHandler\s*\(\s*\{/.test(code);
       if (needsVersion) {
         prepend.push(`import { VERSION } from "@rangojs/router:version";`);
@@ -3389,8 +3388,21 @@ function createVersionInjectorPlugin(rscEntryPath) {
           "createRSCHandler({\n  version: VERSION,"
         );
       }
-      if (prepend.length === 0 && newCode === code) return null;
-      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      const lines = newCode.split("\n");
+      let insertAt = 0;
+      while (insertAt < lines.length) {
+        const trimmed = lines[insertAt].trim();
+        if (trimmed === "" || /^\/\/\/\s*<reference\b/.test(trimmed)) {
+          insertAt++;
+        } else {
+          break;
+        }
+      }
+      newCode = [
+        ...lines.slice(0, insertAt),
+        ...prepend,
+        ...lines.slice(insertAt)
+      ].join("\n");
       return {
         code: newCode,
         map: null
@@ -3784,6 +3796,12 @@ function markSelfGenWrite(state, filePath, content) {
   state.selfWrittenGenFiles.set(filePath, { at: Date.now(), hash });
 }
 function consumeSelfGenWrite(state, filePath) {
+  return checkSelfGenWrite(state, filePath, true);
+}
+function peekSelfGenWrite(state, filePath) {
+  return checkSelfGenWrite(state, filePath, false);
+}
+function checkSelfGenWrite(state, filePath, consume) {
   const info = state.selfWrittenGenFiles.get(filePath);
   if (!info) return false;
   if (Date.now() - info.at > state.SELF_WRITE_WINDOW_MS) {
@@ -3794,7 +3812,7 @@ function consumeSelfGenWrite(state, filePath) {
     const current = readFileSync3(filePath, "utf-8");
     const currentHash = createHash3("sha256").update(current).digest("hex");
     if (currentHash === info.hash) {
-      state.selfWrittenGenFiles.delete(filePath);
+      if (consume) state.selfWrittenGenFiles.delete(filePath);
       return true;
     }
     return false;
@@ -5067,6 +5085,80 @@ function postprocessBundle(state) {
   }
 }
 
+// src/vite/discovery/gate-state.ts
+function createDiscoveryGate(s, debug11) {
+  let gatePending = false;
+  let gateResolver = () => {
+  };
+  let inProgress = false;
+  let queued = false;
+  let pendingEvents = false;
+  const beginGate = () => {
+    if (gatePending) return;
+    s.discoveryDone = new Promise((resolve10) => {
+      gateResolver = resolve10;
+    });
+    gatePending = true;
+  };
+  const resolveGate = () => {
+    if (!gatePending) return;
+    if (inProgress || queued || pendingEvents) {
+      debug11?.(
+        "hmr: resolveGate deferred \u2014 work in flight (inProgress=%s queued=%s pendingEvents=%s)",
+        inProgress,
+        queued,
+        pendingEvents
+      );
+      return;
+    }
+    gatePending = false;
+    debug11?.("hmr: discoveryDone resolved");
+    gateResolver();
+  };
+  const noteRouteEvent = () => {
+    pendingEvents = true;
+    beginGate();
+  };
+  const runRefreshCycle = async (work) => {
+    if (inProgress) {
+      queued = true;
+      debug11?.("hmr: rediscovery in flight \u2014 queued for a follow-up cycle");
+      return;
+    }
+    pendingEvents = false;
+    inProgress = true;
+    try {
+      await work();
+    } finally {
+      inProgress = false;
+      if (queued) {
+        queued = false;
+        debug11?.("hmr: consuming queued rediscovery");
+        runRefreshCycle(work).catch((err) => {
+          debug11?.(
+            "hmr: queued cycle rejected \u2014 releasing gate (%s)",
+            err instanceof Error ? err.message : String(err)
+          );
+          resolveGate();
+        });
+      } else if (pendingEvents) {
+        debug11?.(
+          "hmr: holding gate for pending events (debounce not yet fired)"
+        );
+      } else {
+        resolveGate();
+      }
+    }
+  };
+  return {
+    beginGate,
+    resolveGate,
+    noteRouteEvent,
+    runRefreshCycle,
+    state: () => ({ gatePending, inProgress, queued, pendingEvents })
+  };
+}
+
 // src/vite/router-discovery.ts
 var debugDiscovery = createRangoDebugger(NS.discovery);
 var debugRoutes = createRangoDebugger(NS.routes);
@@ -5231,6 +5323,9 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
       const discoveryPromise = new Promise((resolve10) => {
         resolveDiscovery = resolve10;
       });
+      const gate = createDiscoveryGate(s, debugDiscovery);
+      const beginDiscoveryGate = gate.beginGate;
+      const resolveDiscoveryGate = gate.resolveGate;
       const getDevServerOrigin = () => server.resolvedUrls?.local?.[0]?.replace(/\/$/, "") || `http://localhost:${server.config.server.port || 5173}`;
       let prerenderTempServer = null;
       let prerenderNodeRegistry = null;
@@ -5243,35 +5338,157 @@ function createRouterDiscoveryPlugin(entryPath, opts) {
         releaseBuildEnv(s).catch(() => {
         });
       });
+      async function importEntryAndRegistry(tempRscEnv) {
+        const flagAlreadySet = !!globalThis.__rscRouterDiscoveryActive;
+        if (!flagAlreadySet) {
+          globalThis.__rscRouterDiscoveryActive = true;
+        }
+        try {
+          debugDiscovery?.(
+            "importEntryAndRegistry: importing entry (flag=%s)",
+            globalThis.__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.__rscRouterDiscoveryActive;
+            debugDiscovery?.(
+              "importEntryAndRegistry: cleared __rscRouterDiscoveryActive"
+            );
+          }
+        }
+      }
       async function getOrCreateTempServer() {
-        if (prerenderNodeRegistry) {
-          return prerenderTempServer.environments?.rsc ?? null;
+        if (prerenderTempServer) {
+          const existingEnv = prerenderTempServer.environments?.rsc;
+          if (existingEnv?.runner) {
+            if (prerenderNodeRegistry) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: cached temp runner reused"
+              );
+              return existingEnv;
+            }
+            debugDiscovery?.(
+              "getOrCreateTempServer: server alive but registry missing \u2014 re-importing"
+            );
+            try {
+              await importEntryAndRegistry(existingEnv);
+              return existingEnv;
+            } catch (err) {
+              debugDiscovery?.(
+                "getOrCreateTempServer: reuse import failed (%s) \u2014 closing orphan and creating fresh",
+                err?.message ?? String(err)
+              );
+              await prerenderTempServer.close().catch(() => {
+              });
+              prerenderTempServer = null;
+              prerenderNodeRegistry = null;
+            }
+          } else {
+            debugDiscovery?.(
+              "getOrCreateTempServer: existing server has no rsc.runner \u2014 closing and recreating"
+            );
+            await prerenderTempServer.close().catch(() => {
+            });
+            prerenderTempServer = null;
+            prerenderNodeRegistry = null;
+          }
         }
+        debugDiscovery?.(
+          "getOrCreateTempServer: creating new temp server, entry=%s",
+          s.resolvedEntryPath ?? "(unset)"
+        );
         try {
           prerenderTempServer = await createTempRscServer(s, {
             cacheDir: "node_modules/.vite_prerender"
           });
           const tempRscEnv = prerenderTempServer.environments?.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) {
+          debugDiscovery?.(
+            "getOrCreateTempServer: FAILED message=%s",
+            err.message
+          );
           console.warn(
             `[rsc-router] Failed to create temp runner: ${err.message}`
           );
         }
         return null;
       }
+      async function clearTempRegistries(tempRscEnv) {
+        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) {
+          debugDiscovery?.(
+            "clearTempRegistries: import @rangojs/router/server failed (%s)",
+            err?.message ?? String(err)
+          );
+        }
+      }
+      async function refreshTempRscEnv() {
+        let tempRscEnv = await getOrCreateTempServer();
+        if (!tempRscEnv) return null;
+        const envGraph = tempRscEnv.moduleGraph;
+        const serverGraph = prerenderTempServer?.moduleGraph;
+        const target = envGraph?.invalidateAll ? envGraph : serverGraph?.invalidateAll ? serverGraph : null;
+        if (!target) {
+          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();
+        prerenderNodeRegistry = null;
+        await clearTempRegistries(tempRscEnv);
+        await importEntryAndRegistry(tempRscEnv);
+        return tempRscEnv;
+      }
       const discover = async () => {
         const discoverStart = performance.now();
         const rscEnv = server.environments?.rsc;
         if (!rscEnv?.runner) {
-          debugDiscovery?.("dev: no rsc runner (cloudflare path)");
+          debugDiscovery?.(
+            "dev: cloudflare path start, __rscRouterDiscoveryActive=%s",
+            globalThis.__rscRouterDiscoveryActive ?? false
+          );
           s.devServerOrigin = getDevServerOrigin();
           try {
             await timed(
@@ -5353,9 +5570,11 @@ ${err.stack}`
           resolveDiscovery();
         }
       };
-      s.discoveryDone = new Promise((resolve10) => {
-        setTimeout(() => discover().then(resolve10, resolve10), 0);
-      });
+      beginDiscoveryGate();
+      setTimeout(
+        () => discover().then(resolveDiscoveryGate, resolveDiscoveryGate),
+        0
+      );
       let mainRegistry = null;
       const propagateDiscoveryState = async (rscEnv) => {
         const serverMod = await rscEnv.runner.import("@rangojs/router/server");
@@ -5504,49 +5723,80 @@ ${err.stack}`
           return true;
         };
         let routeChangeTimer;
-        let runtimeRediscoveryInProgress = false;
         const refreshRuntimeDiscovery = async () => {
           const rscEnv = server.environments?.rsc;
-          if (!rscEnv?.runner || runtimeRediscoveryInProgress) return;
-          runtimeRediscoveryInProgress = true;
-          const hmrStart = performance.now();
-          try {
-            await timed(
-              debugDiscovery,
-              "hmr discoverRouters",
-              () => discoverRouters(s, rscEnv)
-            );
-            timedSync(
-              debugDiscovery,
-              "hmr writeRouteTypesFiles",
-              () => writeRouteTypesFiles(s)
-            );
-            await timed(
-              debugDiscovery,
-              "hmr propagateDiscoveryState",
-              () => propagateDiscoveryState(rscEnv)
-            );
-          } catch (err) {
-            console.warn(
-              `[rsc-router] Runtime re-discovery failed: ${err.message}`
-            );
-          } finally {
-            debugDiscovery?.(
-              "hmr re-discovery done (%sms)",
-              (performance.now() - hmrStart).toFixed(1)
-            );
-            runtimeRediscoveryInProgress = false;
-          }
+          const hasMainRunner = !!rscEnv?.runner;
+          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 {
+                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) {
+              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 = void 0;
             const regenStart = debugDiscovery ? performance.now() : 0;
+            const rscEnv = server.environments?.rsc;
+            const skipStaticWrite = !rscEnv?.runner && s.perRouterManifests.length > 0;
             try {
-              writeCombinedRouteTypesWithTracking(s);
-              if (s.perRouterManifests.length > 0) {
-                supplementGenFilesWithRuntimeRoutes(s);
+              if (skipStaticWrite) {
+                debugDiscovery?.(
+                  "watcher: skipping static write (cloudflare HMR \u2014 runtime rediscovery owns gen file)"
+                );
+              } else {
+                writeCombinedRouteTypesWithTracking(s);
+                if (s.perRouterManifests.length > 0) {
+                  supplementGenFilesWithRuntimeRoutes(s);
+                }
               }
             } catch (err) {
               console.error(
@@ -5562,6 +5812,7 @@ ${err.stack}`
                 console.warn(
                   `[rsc-router] Runtime re-discovery error: ${err.message}`
                 );
+                resolveDiscoveryGate();
               });
             }
           }, 100);
@@ -5598,6 +5849,9 @@ ${err.stack}`
               }
               s.cachedRouterFiles = void 0;
             }
+            if (s.perRouterManifests.length > 0) {
+              gate.noteRouteEvent();
+            }
             scheduleRouteRegeneration();
           } catch {
           }
@@ -5696,6 +5950,34 @@ ${details}`
         );
       }
     },
+    // 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 [];
+      }
+    },
     // Virtual module: provides the pre-generated route manifest as a JS module
     // that calls setCachedManifest() at import time.
     resolveId(id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.92",
+  "version": "0.0.0-experimental.93",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/vite/discovery/gate-state.ts

@@ -0,0 +1,171 @@
+import type { Debugger } from "../debug.js";
+
+/**
+ * Manifest-readiness gate + rediscovery scheduler.
+ *
+ * Owns the four pieces of state that cooperate to keep
+ * `s.discoveryDone` (the promise the manifest virtual module's `load()`
+ * hook awaits) consistent across HMR fan-out:
+ *
+ *   - **gatePending**: a Promise has been issued and not yet resolved.
+ *     Workerd's manifest virtual module load() is blocked on it.
+ *   - **inProgress**: a refresh's work callback is currently executing.
+ *   - **queued**: a refresh was attempted while one was already in
+ *     flight; the active run consumes this in its `finally` and
+ *     recurses.
+ *   - **pendingEvents**: a route-file event has been received (gate
+ *     already reset) but the corresponding refresh's work hasn't started
+ *     yet — i.e. the debounce hasn't fired. Set in `noteRouteEvent`,
+ *     cleared at the start of each refresh cycle. Refresh's finally MUST
+ *     hold the gate if this is true even when `queued` is false,
+ *     otherwise an event whose debounce fires AFTER the active refresh
+ *     completes (the "tail-race" window) would observe a resolved gate.
+ *
+ * The HMR-event flow (cloudflare-stress repro):
+ *
+ *   t=0    Touch 1  → noteRouteEvent  → pendingEvents=true, beginGate
+ *                                      (gate1 pending)
+ *          → debounce 100ms
+ *   t=100  runRefreshCycle(work)      → clear pendingEvents, work starts
+ *   t=750  Touch 2  → noteRouteEvent  → pendingEvents=true (no-op gate)
+ *                                      → debounce fires at t=850
+ *   t=800  refresh A's finally        → queued=false, pendingEvents=true
+ *                                      → HOLD gate (don't resolve)
+ *   t=850  runRefreshCycle (debounce) → clear pendingEvents, work starts
+ *   t=1500 refresh B's finally        → queued=false, pendingEvents=false
+ *                                      → resolveGate (gate1 resolves)
+ *
+ * @internal Exported only for unit tests.
+ */
+export interface DiscoveryGate {
+  /**
+   * Reset the gate to a fresh pending Promise via `s.discoveryDone`.
+   * No-op when a gate is already pending — file watchers can fire
+   * multiple events for one save, and replacing the resolver would
+   * orphan the original promise (workerd's manifest load() would hang).
+   */
+  beginGate(): void;
+  /**
+   * Resolve the current pending gate. No-op when no gate is pending.
+   * Called at the tail of the last refresh cycle in a burst.
+   */
+  resolveGate(): void;
+  /**
+   * Record that a route-file event has arrived. Sets `pendingEvents`
+   * and begins the gate. Idempotent for both flags.
+   */
+  noteRouteEvent(): void;
+  /**
+   * Run one refresh cycle, managing queue + pending state around it.
+   * If a cycle is already in flight, sets `queued=true` and returns.
+   * Otherwise clears `pendingEvents`, runs `work`, and in `finally`:
+   *
+   *   - queued        → recurse, gate stays pending
+   *   - pendingEvents → hold gate (next debounced cycle resolves)
+   *   - neither       → resolveGate
+   */
+  runRefreshCycle(work: () => Promise<void>): Promise<void>;
+  /** Snapshot of internal state. Test-only. */
+  readonly state: () => Readonly<{
+    gatePending: boolean;
+    inProgress: boolean;
+    queued: boolean;
+    pendingEvents: boolean;
+  }>;
+}
+
+/** State container the gate writes `discoveryDone` into. */
+export interface GateOwner {
+  discoveryDone: Promise<void> | null | undefined;
+}
+
+export function createDiscoveryGate(
+  s: GateOwner,
+  debug?: Debugger,
+): DiscoveryGate {
+  let gatePending = false;
+  let gateResolver: () => void = () => {};
+  let inProgress = false;
+  let queued = false;
+  let pendingEvents = false;
+
+  const beginGate = (): void => {
+    if (gatePending) return;
+    s.discoveryDone = new Promise<void>((resolve) => {
+      gateResolver = resolve;
+    });
+    gatePending = true;
+  };
+
+  const resolveGate = (): void => {
+    if (!gatePending) return;
+    // Defer resolution while a refresh cycle is in flight or queued, or
+    // while an unprocessed route-file event is pending its debounce.
+    // Without this guard, cold-start's `discover().then(resolveGate)`
+    // could fire while an HMR-triggered runRefreshCycle is mid-flight,
+    // prematurely unblocking workerd's manifest load() against the
+    // stale cold-start gen. The active cycle's `finally` calls
+    // resolveGate again at the tail and finishes the resolution then.
+    if (inProgress || queued || pendingEvents) {
+      debug?.(
+        "hmr: resolveGate deferred — work in flight (inProgress=%s queued=%s pendingEvents=%s)",
+        inProgress,
+        queued,
+        pendingEvents,
+      );
+      return;
+    }
+    gatePending = false;
+    debug?.("hmr: discoveryDone resolved");
+    gateResolver();
+  };
+
+  const noteRouteEvent = (): void => {
+    pendingEvents = true;
+    beginGate();
+  };
+
+  const runRefreshCycle = async (work: () => Promise<void>): Promise<void> => {
+    if (inProgress) {
+      queued = true;
+      debug?.("hmr: rediscovery in flight — queued for a follow-up cycle");
+      return;
+    }
+    // Snapshot the current pendingEvents into "we're about to process";
+    // events arriving from now on re-set it.
+    pendingEvents = false;
+    inProgress = true;
+    try {
+      await work();
+    } finally {
+      inProgress = false;
+      if (queued) {
+        queued = false;
+        debug?.("hmr: consuming queued rediscovery");
+        runRefreshCycle(work).catch((err: unknown) => {
+          debug?.(
+            "hmr: queued cycle rejected — releasing gate (%s)",
+            err instanceof Error ? err.message : String(err),
+          );
+          // Belt-and-suspenders: even if the queued cycle's own try/catch
+          // missed something, ensure workerd doesn't hang.
+          resolveGate();
+        });
+      } else if (pendingEvents) {
+        debug?.(
+          "hmr: holding gate for pending events (debounce not yet fired)",
+        );
+      } else {
+        resolveGate();
+      }
+    }
+  };
+
+  return {
+    beginGate,
+    resolveGate,
+    noteRouteEvent,
+    runRefreshCycle,
+    state: () => ({ gatePending, inProgress, queued, pendingEvents }),
+  };
+}

package/src/vite/discovery/self-gen-tracking.ts

@@ -22,6 +22,32 @@ export function markSelfGenWrite(
 export function consumeSelfGenWrite(
   state: DiscoveryState,
   filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, true);
+}
+
+/**
+ * Non-consuming variant. Used by the `handleHotUpdate` plugin hook to
+ * suppress vite's HMR cascade for our own gen-file writes WITHOUT
+ * consuming the entry — `consumeSelfGenWrite` (called later from the
+ * chokidar `change` handler in `handleRouteFileChange`) still needs to
+ * see and consume the same entry to short-circuit our regen path.
+ *
+ * Both hooks fire for the same file change event:
+ *   - `handleHotUpdate` runs first (vite's HMR pipeline).
+ *   - chokidar `change` callback runs after (filesystem watcher).
+ */
+export function peekSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+): boolean {
+  return checkSelfGenWrite(state, filePath, false);
+}
+
+function checkSelfGenWrite(
+  state: DiscoveryState,
+  filePath: string,
+  consume: boolean,
 ): boolean {
   const info = state.selfWrittenGenFiles.get(filePath);
   if (!info) return false;
@@ -33,7 +59,7 @@ export function consumeSelfGenWrite(
     const current = readFileSync(filePath, "utf-8");
     const currentHash = createHash("sha256").update(current).digest("hex");
     if (currentHash === info.hash) {
-      state.selfWrittenGenFiles.delete(filePath);
+      if (consume) state.selfWrittenGenFiles.delete(filePath);
       return true;
     }
     // Hash mismatch: file was changed externally. Keep the entry so a

package/src/vite/plugins/version-injector.ts

@@ -47,16 +47,26 @@ export function createVersionInjectorPlugin(
         return null;
       }
 
-      // Prepend imports at the top of the file. ES imports are hoisted
-      // by the module system, so source position is irrelevant.
-      const prepend: string[] = [];
-      let newCode = code;
-
-      if (!code.includes("virtual:rsc-router/routes-manifest")) {
-        prepend.push(`import "virtual:rsc-router/routes-manifest";`);
-      }
+      // Always prepend `import "virtual:rsc-router/routes-manifest"` as the
+      // first side-effect import. The manifest virtual module's `load()` hook
+      // awaits `s.discoveryDone` so that, by the time the rest of the entry
+      // including any module-level `router.reverse()` calls under `./router.js`
+      // evaluates, runtime discovery has rewritten `router.named-routes.gen.ts`
+      // with the full route table.
+      //
+      // ES module evaluation order matters here: while imports are *parsed*
+      // hoisted, side-effect imports are evaluated in source order in the
+      // dependency graph. A user-authored `import "virtual:rsc-router/..."`
+      // placed after `import "./router.js"` runs too late: the manifest
+      // gate fires after router.tsx has already crashed on a stale gen file.
+      // We always prepend; ESM dedups any user-written duplicate, so module
+      // initialization still runs once.
+      const prepend: string[] = [
+        `import "virtual:rsc-router/routes-manifest";`,
+      ];
 
       // Auto-inject VERSION if file uses createRSCHandler without version
+      let newCode = code;
       const needsVersion =
         code.includes("createRSCHandler") &&
         !code.includes("@rangojs/router:version") &&
@@ -70,9 +80,25 @@ export function createVersionInjectorPlugin(
         );
       }
 
-      if (prepend.length === 0 && newCode === code) return null;
-
-      newCode = prepend.join("\n") + (prepend.length > 0 ? "\n" : "") + newCode;
+      // Insert after any leading `/// <reference ... />` triple-slash
+      // directives (and surrounding blank lines). TypeScript requires those
+      // directives to precede all other code; putting our imports above
+      // them silently demotes the directives to plain comments.
+      const lines = newCode.split("\n");
+      let insertAt = 0;
+      while (insertAt < lines.length) {
+        const trimmed = lines[insertAt]!.trim();
+        if (trimmed === "" || /^\/\/\/\s*<reference\b/.test(trimmed)) {
+          insertAt++;
+        } else {
+          break;
+        }
+      }
+      newCode = [
+        ...lines.slice(0, insertAt),
+        ...prepend,
+        ...lines.slice(insertAt),
+      ].join("\n");
 
       return {
         code: newCode,

package/src/vite/router-discovery.ts

@@ -35,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,
@@ -47,6 +50,7 @@ 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";
 
@@ -360,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 = () =>
@@ -382,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",
@@ -393,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}`,
           );
@@ -408,6 +519,104 @@ 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;
@@ -415,7 +624,10 @@ export function createRouterDiscoveryPlugin(
           // 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)");
+          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
@@ -505,10 +717,14 @@ export function createRouterDiscoveryPlugin(
       };
 
       // 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
@@ -720,33 +936,68 @@ 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;
-          const hmrStart = performance.now();
-          try {
-            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;
-          }
+          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 = () => {
@@ -754,10 +1005,27 @@ export function createRouterDiscoveryPlugin(
           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(
@@ -769,12 +1037,16 @@ export function createRouterDiscoveryPlugin(
               (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);
@@ -822,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
@@ -946,6 +1229,35 @@ export function createRouterDiscoveryPlugin(
       }
     },
 
+    // 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 [];
+      }
+    },
+
     // Virtual module: provides the pre-generated route manifest as a JS module
     // that calls setCachedManifest() at import time.
     resolveId(id) {