@rangojs/router 0.27.0 → 0.28.0

package/src/vite/discovery/dev-server-phase.ts

@@ -0,0 +1,1776 @@
+/**
+ * Dev server phase: the discovery plugin's configureServer hook.
+ *
+ * Runs dev discovery (the Node RSC runner, or a temp Node server under
+ * Cloudflare, whose RSC env has no runner), serves the dev /__rsc_prerender
+ * and /__rsc_shell endpoints, and watches route files to regenerate the
+ * generated route types and re-run runtime discovery on HMR.
+ */
+
+import type { ViteDevServer } from "vite";
+import { normalizePath } from "vite";
+import { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import {
+  formatNestedRouterConflictError,
+  findNestedRouterConflict,
+  isInSkippedScanDir,
+} from "../../build/generate-route-types.js";
+import { firstCodeMatchIndex } from "../../build/route-types/source-scan.js";
+import {
+  DEV_DISCOVERY_EPOCH_HEADER,
+  DEV_DISCOVERY_PROBE_HEADER,
+  DEV_DISCOVERY_QUERY_EVENT,
+  DEV_DISCOVERY_READY_EVENT,
+} from "../../dev-discovery-protocol.js";
+import {
+  DEV_SHELL_PROBE_TIMEOUT_MS,
+  normalizeCaptureTimeout,
+} from "../../rsc/shell-serve.js";
+import { internalDebugNoCacheMiddleware } from "../inject-client-debug.js";
+import { uniformVersions } from "../../router-versions.js";
+import { VIRTUAL_IDS } from "../plugins/virtual-entries.js";
+import {
+  canRefreshRuntimeDiscovery,
+  recordDiscoveryFailure,
+  VIRTUAL_ROUTES_MANIFEST_ID,
+  type DiscoveryState,
+} from "./state.js";
+import { consumeSelfGenWrite } from "./self-gen-tracking.js";
+import { discoverRouters } from "./discover-routers.js";
+import {
+  componentUseSignature,
+  refreshRecordedClientUrlProjections,
+} from "./client-urls-projection.js";
+import { describeDiscoveryFailure } from "./discovery-errors.js";
+import { findTransitionWhenError } from "../../transition-when-ref.js";
+import {
+  createDevPrerenderCache,
+  devPrerenderCacheKey,
+  payloadBodiesFromResult,
+} from "./dev-prerender-cache.js";
+import {
+  writeCombinedRouteTypesWithTracking,
+  writeRouteTypesFiles,
+  supplementGenFilesWithRuntimeRoutes,
+} from "./route-types-writer.js";
+import { createDiscoveryGate } from "./gate-state.js";
+import { acquireBuildEnv, releaseBuildEnv } from "./build-env.js";
+import { createTempRscServer } from "../temp-rsc-server.js";
+import { createRangoDebugger, timed, timedSync, NS } from "../debug.js";
+
+const debugDiscovery = createRangoDebugger(NS.discovery);
+const debugDev = createRangoDebugger(NS.dev);
+
+/** The slice of a Vite environment module graph the route-file watcher reads. */
+interface ModulesByFileGraph {
+  getModulesByFile(file: string): ReadonlySet<unknown> | undefined;
+}
+
+/** Modules a Vite graph holds for `file`; Vite keys its file index by normalized path. */
+function modulesForFile(
+  graph: ModulesByFileGraph,
+  file: string,
+): ReadonlySet<unknown> | undefined {
+  return graph.getModulesByFile(normalizePath(file));
+}
+
+/**
+ * Whether the dev route-file watcher ignores `file`: it sits in a directory
+ * every discovery scan skips (isInSkippedScanDir) and the RSC graph has not
+ * loaded it. See docs/manifests.md, "A reload no file of the app asked for".
+ */
+export function isFileOutsideApp(
+  root: string,
+  file: string,
+  rscGraph: ModulesByFileGraph | undefined,
+): boolean {
+  return (
+    isInSkippedScanDir(root, file) &&
+    !(rscGraph && modulesForFile(rscGraph, file)?.size)
+  );
+}
+
+/**
+ * Outcome of getOrCreateTempServer. `env` is the temp RSC environment on
+ * success, else null with `error` carrying WHY the create/import failed — or
+ * null when createServer resolved cleanly but attached no runner (terminal, but
+ * not an exception). The dev /__rsc_shell endpoint runs `error` through the
+ * SAME reoptimization classifier the import sites use: only a transient Vite
+ * re-optimization is signalled NOT-READY (client re-polls); every terminal
+ * failure fails fast so the read-through MISSes immediately instead of
+ * re-polling a permanently-broken realm for the full readiness deadline
+ * (issue #719 P2).
+ */
+type TempServerResult = { env: any; error: unknown };
+
+/**
+ * Test-only one-shot boot-race injection (issue #719 P3). When
+ * RANGO_E2E_INJECT_SHELL_NOTREADY=1, the dev /__rsc_shell endpoint emits a
+ * single reoptimization-class NOT-READY per pathname before serving, so an e2e
+ * can drive the REAL endpoint + real client re-poll deterministically — a
+ * natural cold race settles too fast on quick machines to guard the regression.
+ * Keyed per pathname so the read-through's re-poll finds it already fired and
+ * gets the HIT. Never engaged without the env flag.
+ */
+const injectedShellNotReadyPaths = new Set<string>();
+
+// Dev: an invalid transition({ when }) is a definition error the user must
+// see in the browser too, as the Vite error overlay. The overlay does not
+// survive on its own: a reload clears it, and plugin-rsc closes every
+// overlay on each "rsc:update" (the edit's own, the gen-file write's), each
+// followed by the client's RSC refetch. So until a discovery succeeds the
+// pending error (s.transitionWhenOverlay) is re-sent to every client that
+// connects and after every request the dev server answers (devServerPhase).
+function sendTransitionWhenOverlay(s: DiscoveryState): void {
+  if (!s.transitionWhenOverlay) return;
+  (s.devServer?.environments as any)?.client?.hot?.send({
+    type: "error",
+    err: s.transitionWhenOverlay,
+  });
+}
+
+function showTransitionWhenError(
+  s: DiscoveryState,
+  err: unknown,
+): Error | undefined {
+  const whenError = findTransitionWhenError(err);
+  if (!whenError) return undefined;
+  s.transitionWhenOverlay = {
+    message: whenError.message,
+    stack: whenError.stack ?? "",
+    plugin: "@rangojs/router",
+  };
+  sendTransitionWhenOverlay(s);
+  return whenError;
+}
+
+/**
+ * configureServer. Dev mode: discover routers and populate manifest in
+ * memory. Skipped in build mode (buildDiscoveryPhase handles it).
+ */
+export function devServerPhase(s: DiscoveryState, server: ViteDevServer): void {
+  if (s.isBuildMode) return;
+  // Skip if this is a temp server created by buildStart
+  if ((globalThis as any).__rscRouterDiscoveryActive) return;
+  s.devServer = server;
+
+  (server.environments as any)?.client?.hot?.on?.(
+    "vite:client:connect",
+    (_payload: unknown, client: any) => {
+      if (s.transitionWhenOverlay) {
+        client?.send?.({ type: "error", err: s.transitionWhenOverlay });
+      }
+    },
+  );
+  // The http server's "request" event, not a middleware: plugin-rsc
+  // answers page and RSC requests before a middleware added here runs.
+  let overlayResendQueued = false;
+  server.httpServer?.on("request", (req, res) => {
+    // Documents and RSC fetches only (the refetch that follows each
+    // "rsc:update"), one send per burst.
+    const isPage =
+      req.url?.includes("_rsc") === true ||
+      req.headers.accept?.includes("text/html") === true;
+    if (s.transitionWhenOverlay && isPage && !overlayResendQueued) {
+      overlayResendQueued = true;
+      res.once("close", () => {
+        overlayResendQueued = false;
+        sendTransitionWhenOverlay(s);
+      });
+    }
+  });
+
+  let workerReadyEpoch: number | undefined;
+  const publishDevDiscoveryReady = (epoch: number) => {
+    if (epoch <= (workerReadyEpoch ?? -1)) return;
+    workerReadyEpoch = epoch;
+    (server.environments as any)?.client?.hot?.send({
+      type: "custom",
+      event: DEV_DISCOVERY_READY_EVENT,
+      data: { epoch },
+    });
+    debugDiscovery?.("hmr: workerd ready at epoch %d", epoch);
+  };
+  if (s.opts?.preset === "cloudflare") {
+    const registeredClientHotChannels = new Set<any>();
+    const registerDevDiscoveryHotChannels = () => {
+      const clientHot = (server.environments as any)?.client?.hot;
+      if (clientHot && !registeredClientHotChannels.has(clientHot)) {
+        registeredClientHotChannels.add(clientHot);
+        clientHot.on(
+          DEV_DISCOVERY_QUERY_EVENT,
+          (_payload: unknown, client: any) => {
+            if (workerReadyEpoch === undefined) return;
+            client.send(DEV_DISCOVERY_READY_EVENT, {
+              epoch: workerReadyEpoch,
+            });
+          },
+        );
+      }
+      debugDiscovery?.(
+        "hmr: dev discovery browser channel registered (client=%s)",
+        !!clientHot,
+      );
+    };
+
+    registerDevDiscoveryHotChannels();
+    if (server.httpServer && !server.httpServer.listening) {
+      server.httpServer.once("listening", registerDevDiscoveryHotChannels);
+    }
+  }
+
+  // Serve the internal-debug module no-cache: consumers resolve it into
+  // node_modules, where dev's immutable `?v=` caching pinned browsers to a
+  // stale baked INTERNAL_RANGO_DEBUG. See internalDebugNoCacheMiddleware.
+  server.middlewares.use(internalDebugNoCacheMiddleware());
+
+  // Discovery promise that the handler can await if requests arrive
+  // before discovery completes
+  let resolveDiscovery: () => void;
+  const discoveryPromise = new Promise<void>((resolve) => {
+    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
+  // ./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 = () =>
+    server.resolvedUrls?.local?.[0]?.replace(/\/$/, "") ||
+    `http://localhost:${server.config.server.port || 5173}`;
+  let devServerClosed = false;
+
+  // Shared temp server for Cloudflare dev (no module runner in workerd).
+  // Used by both discover() (route type generation) and the prerender
+  // middleware (on-demand prerender evaluation). Created lazily, closed on
+  // server shutdown.
+  let prerenderTempServer: any = null;
+  let prerenderNodeRegistry: Map<string, any> | null = null;
+
+  // Clean up the temporary server and build env when the dev server shuts down
+  server.httpServer?.on("close", () => {
+    devServerClosed = true;
+    if (prerenderTempServer) {
+      prerenderTempServer.close().catch(() => {});
+      prerenderTempServer = null;
+    }
+    releaseBuildEnv(s).catch(() => {});
+  });
+
+  // Mirror the build-path contract (buildDiscoveryPhase in
+  // build-discovery-phase.ts, which sets
+  // __rscRouterDiscoveryActive before running user modules):
+  // 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<TempServerResult> {
+    // 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 { env: existingEnv, error: null };
+        }
+        // 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 { env: existingEnv, error: null };
+        } 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)",
+    );
+    // Surface the create/import cause to the caller (issue #719 P2): a
+    // transient re-optimization is re-pollable, a terminal fault is not. A
+    // clean createServer that yields no runner leaves this null — terminal,
+    // but not an exception.
+    let createError: unknown = null;
+    try {
+      prerenderTempServer = await createTempRscServer(s, {
+        cacheDir: "node_modules/.vite_prerender",
+        // The dev /__rsc_shell endpoint drives captureShellHTML in this
+        // server's SSR realm; the entry is only imported when a shell
+        // capture runs, so discovery cost is unchanged.
+        realSsrEntry: true,
+      });
+
+      const tempRscEnv = (prerenderTempServer.environments as any)?.rsc;
+      if (tempRscEnv?.runner) {
+        await importEntryAndRegistry(tempRscEnv);
+        return { env: tempRscEnv, error: null };
+      }
+      debugDiscovery?.("getOrCreateTempServer: tempRscEnv.runner unavailable");
+    } catch (err: any) {
+      createError = err;
+      debugDiscovery?.("getOrCreateTempServer: FAILED message=%s", err.message);
+      console.warn(`[rango] Failed to create temp runner: ${err.message}`);
+    }
+    // Reached only on failure (runner unavailable, or create/import threw
+    // AFTER the server was created). Close the just-created server so a
+    // failed discovery does not leak it until the next call or dev shutdown,
+    // and null the refs so the reuse path above starts clean. Mirrors the
+    // close pattern used when an existing server is discarded (above).
+    await prerenderTempServer?.close().catch(() => {});
+    prerenderTempServer = null;
+    prerenderNodeRegistry = null;
+    return { env: null, error: createError };
+  }
+
+  // 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> {
+    const tempRscEnv = (await getOrCreateTempServer()).env;
+    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()).env;
+    }
+
+    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;
+  }
+
+  // Surface a discovery failure on either dev path (Node RSC runner or the
+  // Cloudflare temp Node server). `hashBefore`/`hashAfter` are the discovering
+  // environment's dep-optimizer browserHash snapshots: a change across the
+  // attempt means a reload-causing re-optimization landed mid-flight, so an
+  // empty registry was the transient race (downgraded to a warning) rather
+  // than a genuine misconfig (loud, actionable error). Shared so both catch
+  // sites frame the same failure identically.
+  const emitDiscoveryFailure = (
+    err: unknown,
+    hashBefore: string | undefined,
+    hashAfter: string | undefined,
+  ): void => {
+    const reoptimizeObserved =
+      hashBefore !== undefined &&
+      hashAfter !== undefined &&
+      hashBefore !== hashAfter;
+    const report = describeDiscoveryFailure(err, { reoptimizeObserved });
+    if (report.level === "warn") {
+      console.warn(report.message);
+    } else {
+      console.error(report.message);
+    }
+    showTransitionWhenError(s, err);
+  };
+
+  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();
+      // The temp Node realm below shares this globalThis and runs the dev
+      // /__rsc_shell capture, which must replay the prerender store as
+      // the worker's HIT does: a capture that renders the Prerender
+      // handler live stores a doc record the HIT never reads, and the
+      // HIT loses the loader pushes its prelude rendered (#1057). That
+      // realm never evaluates the virtual module that sets this on the
+      // Node preset.
+      globalThis.__PRERENDER_DEV_URL = s.devServerOrigin;
+
+      // Create a temp Node.js server to run runtime discovery and generate
+      // named route types (static parser can't resolve factory calls).
+      // The temp server is a separate Vite instance with its own dep
+      // optimizer; snapshot ITS browserHash (hoisted so the catch can tell a
+      // transient re-optimization apart from a genuine empty registry, the
+      // same way the Node path below does).
+      let tempRscEnv: any;
+      let optimizerHashBefore: string | undefined;
+      try {
+        // Acquire build-time env bindings for dev prerender
+        await timed(debugDiscovery, "acquireBuildEnv", () =>
+          acquireBuildEnv(s, s.viteCommand, s.viteMode),
+        );
+
+        const temp = await timed(debugDiscovery, "getOrCreateTempServer", () =>
+          getOrCreateTempServer(),
+        );
+        tempRscEnv = temp.env;
+        if (!tempRscEnv) {
+          // Recovery mode, as in the catch below. getOrCreateTempServer
+          // already logged why the temp runner failed.
+          recordDiscoveryFailure(
+            s,
+            temp.error ?? "temp runner unavailable for discovery",
+          );
+        } else {
+          optimizerHashBefore = tempRscEnv.depsOptimizer?.metadata?.browserHash;
+          await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
+            discoverRouters(
+              s,
+              tempRscEnv,
+              (prerenderTempServer?.environments as any)?.ssr,
+            ),
+          );
+          timedSync(debugDiscovery, "writeRouteTypesFiles", () =>
+            writeRouteTypesFiles(s),
+          );
+        }
+      } catch (err: any) {
+        recordDiscoveryFailure(s, err);
+        emitDiscoveryFailure(
+          err,
+          optimizerHashBefore,
+          tempRscEnv?.depsOptimizer?.metadata?.browserHash,
+        );
+      }
+
+      debugDiscovery?.(
+        "dev discovery done (%sms)",
+        (performance.now() - discoverStart).toFixed(1),
+      );
+      resolveDiscovery!();
+      return;
+    }
+
+    // Snapshot the dep-optimizer hash before discovery so the catch can tell
+    // a transient re-optimization race apart from a genuine empty registry.
+    // A reload-causing re-optimization regenerates browserHash; if it changed
+    // across the attempt, an empty read was almost certainly the race below.
+    const optimizerHashBefore: string | undefined =
+      rscEnv.depsOptimizer?.metadata?.browserHash;
+
+    try {
+      // Acquire build-time env bindings for dev prerender (Node.js path)
+      debugDiscovery?.("dev: node path start");
+      await timed(debugDiscovery, "acquireBuildEnv", () =>
+        acquireBuildEnv(s, s.viteCommand, s.viteMode),
+      );
+
+      // Discover routers FIRST, then arm the manifest-readiness gate on the
+      // server module discovery actually read the registry from.
+      //
+      // We deliberately do NOT pre-import "@rangojs/router/server" here to
+      // arm the gate early. During a Vite dependency re-optimization (dev
+      // boot after a lockfile change, or `vite dev --force`) or any runner
+      // full reload, a module imported before the entry can be a stale copy
+      // of the runner's module graph: createRouter() populates RouterRegistry
+      // on the fresh copy and the stale one reads an empty Map, a spurious
+      // "No routers found" (#637). discoverRouters returns the instance it
+      // read the registry from and verified the runner still serves (it
+      // redoes a pass that a reload split). The virtual manifest module's
+      // own gate (s.discoveryDone, armed by beginDiscoveryGate) already
+      // blocks early requests during discovery on the Node path, so arming
+      // manifestReadyPromise after discovery is sufficient here.
+      const serverMod = await timed(debugDiscovery, "discoverRouters", () =>
+        discoverRouters(s, rscEnv, (server.environments as any)?.ssr),
+      );
+      if (serverMod?.setManifestReadyPromise) {
+        serverMod.setManifestReadyPromise(discoveryPromise);
+      }
+
+      // Store server origin for dev prerender endpoint (virtual module injection)
+      s.devServerOrigin = getDevServerOrigin();
+
+      // Update named-routes.gen.ts from runtime discovery.
+      // The runtime manifest is the source of truth: it evaluates dynamic
+      // 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.
+      timedSync(debugDiscovery, "writeRouteTypesFiles", () =>
+        writeRouteTypesFiles(s),
+      );
+
+      // Populate the route map and per-router data in the RSC env
+      await timed(debugDiscovery, "propagateDiscoveryState", () =>
+        propagateDiscoveryState(rscEnv),
+      );
+    } catch (err: any) {
+      // Recovery mode: the next in-scan source change re-runs discovery
+      // (canRefreshRuntimeDiscovery) instead of waiting for a restart.
+      recordDiscoveryFailure(s, err);
+      emitDiscoveryFailure(
+        err,
+        optimizerHashBefore,
+        rscEnv.depsOptimizer?.metadata?.browserHash,
+      );
+    } finally {
+      debugDiscovery?.(
+        "dev discovery done (%sms)",
+        (performance.now() - discoverStart).toFixed(1),
+      );
+      resolveDiscovery!();
+    }
+  };
+
+  // Schedule after all plugins have finished configureServer.
+  // 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
+  // trying to run node:fs-dependent handlers in the Cloudflare environment.
+  //
+  // Node.js preset: uses the main server's RSC environment directly (router
+  // instances are already discovered and have matchForPrerender).
+  // Cloudflare preset: lazily creates a Node.js temp server because the main
+  // RSC environment uses workerd where node:fs can't access the host filesystem.
+
+  // Registry from the main server's RSC environment (populated by discoverRouters)
+  let mainRegistry: Map<string, any> | null = null;
+
+  // Memoized /__rsc_prerender render results, keyed by router-instance
+  // identity (#654). The per-request entry re-import below is what makes
+  // identity a valid freshness key: an HMR-invalidated chain re-runs
+  // createRouter() and replaces the registry instance, so cached bodies
+  // for the old instance become unreachable; an untouched chain returns
+  // the same instance and the cached body is byte-identical to a fresh
+  // render. See dev-prerender-cache.ts for the full invariant.
+  const devPrerenderCache = createDevPrerenderCache();
+
+  // Push discovery state (manifest, trie, precomputed entries) to the
+  // server module so runtime request handling uses the current routes.
+  // Shared by initial discovery and HMR-triggered re-discovery.
+  const propagateDiscoveryState = async (rscEnv: any) => {
+    const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+    if (!serverMod) return;
+    // Clear stale per-router and global route data before repopulating.
+    // Without this, removed routers/routes survive in the per-router maps
+    // and shrunk precomputed entries or tries are never purged.
+    if (serverMod.clearAllRouterData) {
+      serverMod.clearAllRouterData();
+    }
+    mainRegistry = serverMod.RouterRegistry ?? null;
+    if (s.mergedRouteManifest && serverMod.setCachedManifest) {
+      serverMod.setCachedManifest(s.mergedRouteManifest);
+    }
+    const perRouterSetters: Array<[Map<string, any>, string]> = [
+      [s.perRouterManifestDataMap, "setRouterManifest"],
+      [s.perRouterTrieMap, "setRouterTrie"],
+      [s.perRouterPrecomputedMap, "setRouterPrecomputedEntries"],
+    ];
+    for (const [map, fn] of perRouterSetters) {
+      const setter = serverMod[fn];
+      if (typeof setter !== "function") continue;
+      for (const [routerId, value] of map) setter(routerId, value);
+    }
+  };
+
+  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");
+    const pathname = url.searchParams.get("pathname");
+    if (!pathname) {
+      res.statusCode = 400;
+      res.end("Missing pathname");
+      logResult(400, "missing pathname");
+      return;
+    }
+
+    // Import the user's entry module to force re-evaluation of any
+    // HMR-invalidated modules in the chain (entry → router → urls → handlers).
+    // This ensures createRouter() re-runs with updated handler code before
+    // we read RouterRegistry. Without this, edits to prerender handler files
+    // produce stale content because the old router instance remains registered.
+    const rscEnv = (server.environments as any)?.rsc;
+    let registry: Map<string, any> | null = null;
+    if (rscEnv?.runner && s.resolvedEntryPath) {
+      try {
+        await rscEnv.runner.import(s.resolvedEntryPath);
+        const serverMod = await rscEnv.runner.import("@rangojs/router/server");
+        registry = serverMod.RouterRegistry ?? null;
+      } catch (err: any) {
+        console.warn(
+          `[rango] Dev prerender module refresh failed: ${err.message}`,
+        );
+        res.statusCode = 500;
+        res.end(`Prerender handler error: ${err.message}`);
+        logResult(500, "module refresh failed");
+        return;
+      }
+    } else {
+      registry = mainRegistry;
+    }
+
+    if (!registry) {
+      // No main registry: the RSC env has no module runner (Cloudflare dev).
+      // Lazily create a Node.js temp server for prerender evaluation, and
+      // re-import the entry through it on EVERY request — the temp server
+      // has its own file watcher, so a handler-only edit (a file without
+      // urls()/createRouter() that the main watcher's route-file sniff
+      // ignores) invalidates its module graph; the re-import re-evaluates
+      // exactly the dirty subgraph and re-registers fresh router
+      // instances. Before #654 the cached registry was only refreshed on
+      // route-file edits, so handler-only edits served stale prerender
+      // content on this path. Warm-cache re-imports are module-cache hits.
+      const tempRscEnv = (await getOrCreateTempServer()).env;
+      if (tempRscEnv) {
+        try {
+          await importEntryAndRegistry(tempRscEnv);
+        } catch (err: any) {
+          console.warn(
+            `[rango] Dev prerender module refresh failed: ${err.message}`,
+          );
+          res.statusCode = 500;
+          res.end(`Prerender handler error: ${err.message}`);
+          logResult(500, "temp module refresh failed");
+          return;
+        }
+      }
+      registry = prerenderNodeRegistry;
+    }
+
+    if (!registry || registry.size === 0) {
+      res.statusCode = 503;
+      res.end("Prerender runner not available");
+      logResult(503, "no registry");
+      return;
+    }
+
+    const wantIntercept = url.searchParams.get("intercept") === "1";
+    const wantRouteName = url.searchParams.get("routeName");
+    const wantPassthrough = url.searchParams.get("passthrough") === "1";
+
+    // One render warms BOTH variant keys (matchForPrerender computes the
+    // intercept segments unconditionally), so a route's main and modal
+    // variants cost a single render per HMR generation.
+    const variantDims = {
+      passthrough: wantPassthrough,
+      routeName: wantRouteName,
+    };
+    const keyMain = devPrerenderCacheKey(pathname, {
+      intercept: false,
+      ...variantDims,
+    });
+    const keyIntercept = devPrerenderCacheKey(pathname, {
+      intercept: true,
+      ...variantDims,
+    });
+    const requestedKey = wantIntercept ? keyIntercept : keyMain;
+
+    for (const [, routerInstance] of registry) {
+      if (!routerInstance.matchForPrerender) continue;
+      // Cache is consulted per router IN LOOP ORDER so multi-router
+      // fall-through semantics are identical to the uncached path: a
+      // router that never produced a payload for this key still runs
+      // its matchForPrerender (cheap trie miss / intentionally-uncached
+      // error retry) before the next router is considered.
+      const cached = devPrerenderCache.get(routerInstance, requestedKey);
+      if (cached !== undefined) {
+        res.setHeader("content-type", "application/json");
+        res.setHeader("x-rango-prerender-cache", "HIT");
+        res.end(cached);
+        logResult(200, "cache hit");
+        return;
+      }
+      try {
+        const result = await routerInstance.matchForPrerender(
+          pathname,
+          {},
+          undefined,
+          wantPassthrough,
+          s.resolvedBuildEnv,
+          true, // devMode: check getParams for passthrough routes
+        );
+        if (!result) continue;
+        if (result.passthrough) continue;
+        // When routeName is specified, only accept a match for that route.
+        // This prevents returning the wrong entry when multiple routers
+        // have prerenderable routes sharing the same pathname.
+        if (wantRouteName && result.routeName !== wantRouteName) continue;
+        // The pre-encoded handle string in the intercept body comes
+        // from the producer (handles are Flight-encoded so
+        // Promise/ReactNode values survive the wire).
+        const bodies = payloadBodiesFromResult(result);
+        devPrerenderCache.set(routerInstance, keyMain, bodies.main);
+        devPrerenderCache.set(routerInstance, keyIntercept, bodies.intercept);
+        res.setHeader("content-type", "application/json");
+        res.setHeader("x-rango-prerender-cache", "MISS");
+        res.end(wantIntercept ? bodies.intercept : bodies.main);
+        logResult(200, `match ${result.routeName}`);
+        return;
+      } catch (err: any) {
+        // matchForPrerender now re-throws render failures instead of baking
+        // an error page (issue #587). In dev there is no frozen artifact, so
+        // we fall through (404 -> live handler). A `throw new Skip()` is the
+        // expected "skip this URL" signal, not a failure, so it stays quiet.
+        if (err?.name !== "Skip") {
+          console.warn(
+            `[rango] Dev prerender error for ${pathname} (serving live instead): ${err.message}`,
+          );
+        }
+      }
+    }
+
+    res.statusCode = 404;
+    res.end("No prerender match");
+    logResult(404, "no match");
+  });
+
+  // Dev on-demand PPR shell production (producer B, #699). There is no
+  // build manifest in dev, so the serve path's read-through
+  // (rsc/shell-build-manifest.ts) fetches the shell entry from here on a
+  // Prerender+ppr route's first request — dev serves x-rango-shell: HIT
+  // from request one, mirroring production. Memoized per router HMR
+  // generation AND per caller version (a client-module edit bumps the
+  // version without rotating the router instance; the stale entry would
+  // fail the serve gate forever). The endpoint is policy-free: the caller
+  // (the serve gate, which resolved the route's ppr option) sends
+  // ttl/swr/tags/version. Only prerender-backed routes produce entries —
+  // the /__rsc_prerender pre-flight below both warms the payload memo the
+  // capture's dev store fetch will hit AND refuses non-prerenderable
+  // routes (a live-handler render must never be served as a baked shell).
+  server.middlewares.use("/__rsc_shell", async (req: any, res: any) => {
+    await s.discoveryDone;
+    const url = new URL(req.url ?? "", "http://localhost");
+    const pathname = url.searchParams.get("pathname");
+    const routeName = url.searchParams.get("routeName");
+    const version = url.searchParams.get("version");
+    // ttl is required like the identifiers: the endpoint is policy-free
+    // (the serve gate resolved the route's ppr option and always sends
+    // it), so there is deliberately no default to drift from
+    // resolvePprConfig's.
+    const ttlRaw = url.searchParams.get("ttl");
+    if (!pathname || !routeName || !version || !ttlRaw) {
+      res.statusCode = 400;
+      res.end("Missing pathname/routeName/version/ttl");
+      return;
+    }
+
+    // Boot-race readiness signal (issue #719): the capture realm is stood
+    // up lazily on the first hit (temp server, registry import, and a Vite
+    // dep re-optimization the first shell-capture import can trigger). All
+    // are TRANSIENT — a retry seconds later succeeds. Tagging them 503 +
+    // x-rango-shell-dev: NOT-READY lets the read-through re-poll ONLY these
+    // (a bounded await of readiness) instead of mapping the boot window to
+    // a hard first-request MISS. Genuine negatives (404) stay untagged so a
+    // non-baked route never stalls the foreground.
+    const sendNotReady = (detail: string): void => {
+      res.statusCode = 503;
+      res.setHeader("x-rango-shell-dev", "NOT-READY");
+      res.end(detail);
+    };
+    // A Vite dependency re-optimization surfaces as ERR_OUTDATED_OPTIMIZED_DEP
+    // (import throws once, then re-imports clean) — retryable, unlike a real
+    // module fault (syntax error, missing export), which stays a hard 500.
+    // The message-regex fallback is NOT gratuitous: err.code is stripped when
+    // the error serializes across the module-runner/workerd RPC boundary (the
+    // message survives), so under the Cloudflare preset .code alone misses it.
+    const isReoptimizing = (err: any): boolean =>
+      err?.code === "ERR_OUTDATED_OPTIMIZED_DEP" ||
+      /Outdated Optimize Dep|optimized dependency|new dependencies optimized/i.test(
+        String(err?.message ?? ""),
+      );
+    // Fold the reoptimize-guard pasted at all three import/capture catch
+    // sites: emit NOT-READY + report handled for a transient re-optimization,
+    // else leave the caller to send its own terminal (500 for an entry
+    // import, 404 for a mid-capture failure that keeps runtime capture).
+    const handledAsReoptimizing = (err: any): boolean => {
+      if (!isReoptimizing(err)) return false;
+      sendNotReady(`Shell capture re-optimizing: ${err.message}`);
+      return true;
+    };
+    // Both entry-import sites (main-server rsc env, temp Node server) fail
+    // identically: reoptimize → NOT-READY, else → hard 500.
+    const handleShellImportError = (err: any): void => {
+      if (handledAsReoptimizing(err)) return;
+      res.statusCode = 500;
+      res.end(`Shell capture module refresh failed: ${err.message}`);
+    };
+    // Deterministic boot-race injection for e2e (issue #719 P3): fire ONE
+    // reopt-class NOT-READY per pathname through the REAL classifier so the
+    // read-through's re-poll path is exercised end-to-end (not just the
+    // unit-mocked fetch), then serve normally on the re-poll. Env-gated —
+    // inert in every non-test run.
+    if (
+      process.env.RANGO_E2E_INJECT_SHELL_NOTREADY === "1" &&
+      !injectedShellNotReadyPaths.has(pathname)
+    ) {
+      injectedShellNotReadyPaths.add(pathname);
+      const injected = Object.assign(
+        new Error("Outdated Optimize Dep (injected boot-race)"),
+        { code: "ERR_OUTDATED_OPTIMIZED_DEP" },
+      );
+      if (handledAsReoptimizing(injected)) return;
+    }
+    const ttl = Number(ttlRaw);
+    const swrRaw = url.searchParams.get("swr");
+    const swr = swrRaw === null ? undefined : Number(swrRaw);
+    const tagsRaw = url.searchParams.get("tags");
+    const tags = tagsRaw ? tagsRaw.split(",") : undefined;
+    const maxSnapshotBytesRaw = url.searchParams.get("maxSnapshotBytes");
+    const maxSnapshotBytes =
+      maxSnapshotBytesRaw === null ? undefined : Number(maxSnapshotBytesRaw);
+    // Boundary revalidation via the SHARED normalizer (shell-serve.ts):
+    // the param crossed an HTTP query string, and a garbage value must
+    // fall back to the capture default, never reach setTimeout as NaN
+    // (which Node clamps to ~1ms — an instant abort).
+    const captureTimeout = normalizeCaptureTimeout(
+      Number(url.searchParams.get("captureTimeout")),
+    );
+
+    // Resolve the capture realms: main-server envs (Node preset) or the
+    // shared temp Node server (Cloudflare preset — no main RSC runner).
+    // Entry re-import per request picks up HMR edits, exactly like the
+    // prerender endpoint above.
+    const rscEnvMain = (server.environments as any)?.rsc;
+    let rscRealm: any = null;
+    let ssrRealm: any = null;
+    let ssrEntryId: string;
+    // Why the temp-server path returned no runner, if it did: a transient
+    // re-optimization is re-pollable (NOT-READY), a terminal create/import
+    // fault is not. Carried from getOrCreateTempServer to the readiness
+    // check below so only reopt re-polls (issue #719 P2).
+    let tempServerError: unknown = null;
+    if (rscEnvMain?.runner && s.resolvedEntryPath) {
+      try {
+        await rscEnvMain.runner.import(s.resolvedEntryPath);
+      } catch (err: any) {
+        handleShellImportError(err);
+        return;
+      }
+      rscRealm = rscEnvMain;
+      ssrRealm = (server.environments as any)?.ssr;
+      ssrEntryId =
+        (server.environments as any)?.ssr?.config?.build?.rollupOptions?.input
+          ?.index ?? VIRTUAL_IDS.ssr;
+    } else {
+      const tempResult = await getOrCreateTempServer();
+      if (tempResult.env) {
+        try {
+          await importEntryAndRegistry(tempResult.env);
+        } catch (err: any) {
+          handleShellImportError(err);
+          return;
+        }
+      } else {
+        tempServerError = tempResult.error;
+      }
+      rscRealm = tempResult.env;
+      ssrRealm = (prerenderTempServer?.environments as any)?.ssr;
+      ssrEntryId = "virtual:entry-ssr";
+    }
+    if (!rscRealm?.runner || !ssrRealm?.runner) {
+      // Reoptimization is the ONLY transient class: re-poll it (NOT-READY).
+      // A terminal temp-server create/import fault, or an SSR runner absent
+      // after a clean createServer, fails fast with a plain 503 (no
+      // NOT-READY header) so the read-through MISSes on its first attempt
+      // instead of re-polling a permanently-broken realm for the full
+      // readiness deadline (issue #719 P2).
+      if (tempServerError && handledAsReoptimizing(tempServerError)) return;
+      res.statusCode = 503;
+      res.end("Shell capture runners not available");
+      return;
+    }
+    let registry: Map<string, any> | null = null;
+    let registryError: unknown = null;
+    try {
+      const serverMod = await rscRealm.runner.import("@rangojs/router/server");
+      registry = serverMod.RouterRegistry ?? null;
+    } catch (err: any) {
+      registryError = err;
+      registry = null;
+    }
+    if (!registry || registry.size === 0) {
+      // Same rule as the runner check: a re-optimization mid-import is
+      // re-pollable (NOT-READY); a terminal import fault or a genuinely
+      // empty registry (no routers registered) fails fast (issue #719 P2).
+      if (registryError && handledAsReoptimizing(registryError)) return;
+      res.statusCode = 503;
+      res.end("Shell capture registry not available");
+      return;
+    }
+
+    // Memo sweep FIRST: after request one the common case is a memo HIT
+    // (this fetch blocks a foreground document request), and the memoized
+    // body needs neither the pre-flight round-trip nor a capture. Keyed
+    // per router instance (= HMR generation) like the prerender memo.
+    const cacheKey = `shell|${pathname}|r=${routeName}|t=${ttl}|s=${swr ?? ""}|g=${(tags ?? []).join("+")}|c=${captureTimeout ?? ""}|v=${version}`;
+    for (const [, routerInstance] of registry) {
+      if (typeof routerInstance.match !== "function") continue;
+      const cached = devPrerenderCache.get(routerInstance, cacheKey);
+      if (cached !== undefined) {
+        res.setHeader("content-type", "application/json");
+        res.setHeader("x-rango-shell-dev", "HIT");
+        res.end(cached);
+        return;
+      }
+    }
+
+    // Pre-flight: the route must be prerender-backed. Warms the payload
+    // memo the capture's dev prerender store will fetch, and closes the
+    // live-handler-bake hole (a non-pr route 404s here).
+    if (s.devServerOrigin) {
+      try {
+        const probe = await fetch(
+          `${s.devServerOrigin}/__rsc_prerender?pathname=${encodeURIComponent(pathname)}&routeName=${encodeURIComponent(routeName)}`,
+          { signal: AbortSignal.timeout(DEV_SHELL_PROBE_TIMEOUT_MS) },
+        );
+        if (!probe.ok) {
+          res.statusCode = 404;
+          res.end("Route is not prerenderable");
+          return;
+        }
+      } catch {
+        res.statusCode = 404;
+        res.end("Prerender pre-flight failed");
+        return;
+      }
+    }
+
+    for (const [, routerInstance] of registry) {
+      if (typeof routerInstance.match !== "function") continue;
+      try {
+        const ssrModule = await ssrRealm.runner.import(ssrEntryId);
+        if (typeof ssrModule?.captureShellHTML !== "function") {
+          res.statusCode = 404;
+          res.end("SSR entry has no captureShellHTML");
+          return;
+        }
+        const captureMod = await rscRealm.runner.import(
+          "@rangojs/router/build/shell-capture",
+        );
+        const result = await captureMod.captureShellForBuild({
+          router: routerInstance,
+          urlPath: pathname,
+          routeName,
+          key: `${pathname}:shell`,
+          ttl,
+          swr,
+          tags,
+          maxSnapshotBytes,
+          captureTimeout,
+          buildEnv: s.resolvedBuildEnv,
+          versions: uniformVersions(version),
+          captureShellHTML: ssrModule.captureShellHTML,
+          debug: !!debugDiscovery,
+        });
+        if (result.outcome === "route-mismatch") continue;
+        if (result.outcome !== "stored" || !result.entry) {
+          res.statusCode = 404;
+          res.end(`Shell capture ${result.outcome}`);
+          return;
+        }
+        const body = JSON.stringify({
+          entry: result.entry,
+          ttl,
+          tags: result.tags,
+        });
+        devPrerenderCache.set(routerInstance, cacheKey, body);
+        res.setHeader("content-type", "application/json");
+        res.setHeader("x-rango-shell-dev", "MISS");
+        res.end(body);
+        return;
+      } catch (err: any) {
+        // A dep re-optimization mid-capture is a boot-race, not a capture
+        // failure: signal NOT-READY so the read-through re-polls instead of
+        // conceding a first-request MISS (issue #719).
+        if (handledAsReoptimizing(err)) return;
+        console.warn(
+          `[rango] Dev shell capture error for ${pathname} (route keeps runtime capture): ${err.message}`,
+        );
+        res.statusCode = 404;
+        res.end(`Shell capture error: ${err.message}`);
+        return;
+      }
+    }
+    res.statusCode = 404;
+    res.end("No router matched");
+  });
+
+  // Watch url module and router files for changes and regenerate named-routes.gen.ts.
+  // Process files containing urls( or createRouter( to update the combined route map.
+  if (s.opts?.staticRouteTypesGeneration !== false) {
+    const isGeneratedRouteFile = (filePath: string): boolean =>
+      filePath.endsWith(".gen.ts") &&
+      (filePath.includes("named-routes.gen.ts") ||
+        filePath.includes("urls.gen.ts"));
+
+    // Files no discovery scan reaches are ignored unless the RSC graph
+    // loaded them (docs/manifests.md, "A reload no file of the app asked for").
+    const isOutsideApp = (filePath: string): boolean =>
+      isFileOutsideApp(
+        s.projectRoot,
+        filePath,
+        (server.environments as any)?.rsc?.moduleGraph,
+      );
+
+    const regenerateGeneratedRouteFiles = () => {
+      if (s.perRouterManifests.length > 0) {
+        writeRouteTypesFiles(s);
+      } else {
+        writeCombinedRouteTypesWithTracking(s);
+      }
+    };
+    const routeShapeSignature = () =>
+      JSON.stringify(
+        s.perRouterManifests.map(
+          ({ id, routeManifest, routeTrailingSlash, routeSearchSchemas }) => ({
+            id,
+            routeManifest,
+            routeTrailingSlash,
+            routeSearchSchemas,
+          }),
+        ),
+      );
+
+    const maybeHandleGeneratedRouteFileMutation = (
+      filePath: string,
+    ): boolean => {
+      if (!isGeneratedRouteFile(filePath)) return false;
+      if (consumeSelfGenWrite(s, filePath)) return true;
+      // In Cloudflare dev (no module runner), perRouterManifests is never
+      // refreshed after HMR so regenerateGeneratedRouteFiles() would use
+      // stale data and revert user edits. Source files own route state;
+      // gen files are derived output. Skip regeneration and let the next
+      // source-file change rebuild them from the static parser.
+      const hasRunner = !!(server.environments as any)?.rsc?.runner;
+      if (!hasRunner) return true;
+      regenerateGeneratedRouteFiles();
+      return true;
+    };
+
+    // Debounce timer for batching rapid route-file changes (e.g. afterEach
+    // restoring two files in quick succession). The cheap checks (extension,
+    // scanFilter, content sniff) run synchronously to gate non-route files;
+    // only the expensive regeneration is debounced.
+    let routeChangeTimer: ReturnType<typeof setTimeout> | undefined;
+
+    // Drop the routes-manifest virtual module's cached transform so the
+    // next runner evaluation regenerates it from current state.
+    const invalidateRoutesManifestModule = (rscEnv: any) => {
+      for (const virtualId of [
+        VIRTUAL_ROUTES_MANIFEST_ID,
+        `\0${VIRTUAL_ROUTES_MANIFEST_ID}`,
+      ]) {
+        const virtualMod = rscEnv.moduleGraph?.getModuleById?.(virtualId);
+        if (virtualMod) rscEnv.moduleGraph.invalidateModule(virtualMod);
+      }
+    };
+
+    // Re-run runtime discovery so factory-generated routes that the
+    // static parser cannot see are refreshed after source changes.
+    // The state-machine concerns (queued/pending/gatePending) are
+    // owned by the gate created above (./gate-state.ts).
+    // Here we provide just the env-specific work.
+    const refreshRuntimeDiscovery = async () => {
+      const rscEnv = (server.environments as any)?.rsc;
+      const hasMainRunner = !!rscEnv?.runner;
+      let previousRouteShape = routeShapeSignature();
+      await gate.runRefreshCycle(async () => {
+        const hmrStart = performance.now();
+        try {
+          if (hasMainRunner) {
+            const recoveringColdStart = s.perRouterManifests.length === 0;
+            await timed(debugDiscovery, "hmr discoverRouters", () =>
+              discoverRouters(s, rscEnv, (server.environments as any)?.ssr),
+            );
+            timedSync(debugDiscovery, "hmr writeRouteTypesFiles", () =>
+              writeRouteTypesFiles(s),
+            );
+            await timed(debugDiscovery, "hmr propagateDiscoveryState", () =>
+              propagateDiscoveryState(rscEnv),
+            );
+            // The manifest module emitted after a failed cold discovery has
+            // no gen-file import, so no gen write ever invalidates it.
+            if (recoveringColdStart) invalidateRoutesManifestModule(rscEnv);
+          } else {
+            // Cloudflare HMR has no main RSC runner (workerd is a separate
+            // runtime): re-discover on the temp Node runner. Invalidate its
+            // 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. After
+            // a cold start whose temp runner failed there is none, and
+            // getOrCreateTempServer creates one. A recovering cycle needs
+            // no routes-manifest invalidation here: the worker reload below
+            // invalidates its whole module graph.
+            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,
+                  (prerenderTempServer?.environments as any)?.ssr,
+                ),
+            );
+            timedSync(debugDiscovery, "hmr writeRouteTypesFiles", () =>
+              writeRouteTypesFiles(s),
+            );
+          }
+          if (s.lastDiscoveryError) {
+            debugDiscovery?.(
+              "hmr: cleared lastDiscoveryError (%s) after successful rediscovery",
+              s.lastDiscoveryError.message,
+            );
+            s.lastDiscoveryError = null;
+          }
+          s.transitionWhenOverlay = null;
+          // Cloudflare dev: on a successful cycle drop the workerd runner's
+          // cached worker-entry chain so the next request re-evaluates
+          // createRouter() with the new routes. Fired here in the work path
+          // (not the caller's .then()) so a queued follow-up cycle that
+          // succeeds after an earlier failed cycle still reloads:
+          // runRefreshCycle recurses queued work without awaiting it, so the
+          // original call already resolved on the failed cycle. A failed
+          // cycle throws above and never reaches here, so a broken edit
+          // never reloads the worker onto bad source.
+          if (rscEnv && !rscEnv.runner) {
+            const nextRouteShape = routeShapeSignature();
+            let expectedEpoch: number | undefined;
+            if (nextRouteShape !== previousRouteShape) {
+              expectedEpoch = Math.max(
+                Date.now(),
+                (s.devDiscoveryEpoch ?? 0) + 1,
+              );
+              s.devDiscoveryEpoch = expectedEpoch;
+            }
+            previousRouteShape = nextRouteShape;
+            forceCloudflareWorkerReload(rscEnv, expectedEpoch);
+          }
+        } catch (err: any) {
+          recordDiscoveryFailure(s, err);
+          // An invalid transition({ when }) is a definition error the
+          // user must see: terminal error plus the browser's Vite overlay,
+          // not a warning while the last-good route tree keeps serving.
+          const whenError = showTransitionWhenError(s, err);
+          if (whenError) {
+            console.error(whenError.message);
+          } else {
+            console.warn(`[rango] Runtime re-discovery failed: ${err.message}`);
+          }
+          debugDiscovery?.(
+            "hmr: lastDiscoveryError set (%s) — manifest preserved at last-good; recovery mode active (any in-scan source change will trigger rediscovery)",
+            err?.message,
+          );
+        } finally {
+          debugDiscovery?.(
+            "hmr re-discovery done (%sms)",
+            (performance.now() - hmrStart).toFixed(1),
+          );
+        }
+      });
+    };
+
+    // Cloudflare dev only. workerd serves every request through the
+    // runner-worker singleton, which re-resolves the worker entry per
+    // request via runner.import("virtual:cloudflare/worker-entry"). The
+    // route table lives in the user's createRouter() instance, captured
+    // when that entry chain (entry -> router -> urls) was last evaluated
+    // and then cached in the runner's evaluatedModules. The route-file
+    // watcher refreshes discovery + types on the Node side, but the worker
+    // keeps serving the cached (stale) router: route-definition modules
+    // have no import.meta.hot boundary, so Vite never sends the worker an
+    // HMR update for them and the entry chain is never evicted.
+    //
+    // Fix: after discovery completes, (1) invalidate the worker env's
+    // Node-side module graph, (2) send a full-reload to the worker, then
+    // (3) probe until the active router reports the new discovery epoch.
+    // Step (2) alone is insufficient: the full-reload handler clears the
+    // runner's evaluatedModules and re-imports entrypoints, but each
+    // re-import fetches the module back through this Node-side graph, which
+    // still holds the pre-edit transform of urls.tsx — so createRouter()
+    // rebuilds the stale route table and the new route 404s/hits the
+    // catch-all. Invalidating the graph forces a fresh transform on
+    // re-fetch (the same mechanism refreshTempRscEnv uses for discovery),
+    // so the re-import re-runs createRouter() with the new routes. The probe
+    // is detached because the refresh callback still holds the discovery
+    // gate; awaiting it here would deadlock the request that proves the new
+    // router is active. Once it succeeds, the client hot channel broadcasts
+    // readiness to open and newly-booted stale documents.
+    const forceCloudflareWorkerReload = (
+      rscEnv: any,
+      expectedEpoch: number | undefined,
+    ) => {
+      if (!rscEnv?.hot) return;
+
+      const graph = rscEnv.moduleGraph;
+      const reloadWorkerd = () => {
+        if (graph?.invalidateAll) {
+          graph.invalidateAll();
+          debugDiscovery?.("hmr: invalidated workerd rsc module graph");
+        }
+        rscEnv.hot.send({ type: "full-reload" });
+        debugDiscovery?.("hmr: forced workerd rsc env reload (full-reload)");
+      };
+      reloadWorkerd();
+
+      if (expectedEpoch === undefined) return;
+      void (async () => {
+        const deadline = Date.now() + 15_000;
+        let reloadBackoffMs = 100;
+        let nextReloadAt = Date.now() + reloadBackoffMs;
+        do {
+          if (devServerClosed || expectedEpoch !== s.devDiscoveryEpoch) {
+            return;
+          }
+          await new Promise<void>((resolve) => setTimeout(resolve, 25));
+          if (devServerClosed || expectedEpoch !== s.devDiscoveryEpoch) {
+            return;
+          }
+          try {
+            const response = await fetch(getDevServerOrigin() + "/", {
+              cache: "no-store",
+              headers: {
+                [DEV_DISCOVERY_PROBE_HEADER]: String(expectedEpoch),
+              },
+              signal: AbortSignal.timeout(1_000),
+            });
+            if (
+              !devServerClosed &&
+              expectedEpoch === s.devDiscoveryEpoch &&
+              response.headers.get(DEV_DISCOVERY_EPOCH_HEADER) ===
+                String(expectedEpoch)
+            ) {
+              publishDevDiscoveryReady(expectedEpoch);
+              return;
+            }
+            await response.body?.cancel().catch(() => {});
+            // A response without the expected epoch proves an older worker
+            // evaluation won the race after the initial invalidation. Clear
+            // that completed evaluation and retry the reload. Back off the
+            // retries: reloading faster than workerd can evaluate prevents
+            // convergence and retains overlapping module generations.
+            const now = Date.now();
+            if (now >= nextReloadAt) {
+              reloadWorkerd();
+              reloadBackoffMs = Math.min(reloadBackoffMs * 2, 1_000);
+              nextReloadAt = now + reloadBackoffMs;
+            }
+          } catch {}
+        } while (Date.now() < deadline);
+
+        debugDiscovery?.(
+          "hmr: workerd readiness probe timed out at epoch %d",
+          expectedEpoch,
+        );
+      })();
+    };
+
+    const scheduleRouteRegeneration = () => {
+      clearTimeout(routeChangeTimer);
+      routeChangeTimer = setTimeout(async () => {
+        routeChangeTimer = undefined;
+        const regenStart = debugDiscovery ? performance.now() : 0;
+        const rscEnv = (server.environments as any)?.rsc;
+        const skipStaticWrite =
+          !rscEnv?.runner && s.perRouterManifests.length > 0;
+        // Refresh clientUrls projections + state BEFORE any gen-file
+        // write below: the write invalidates the routes-manifest virtual
+        // module, whose regenerated code replays state.clientUrlProjectionMap
+        // (clear + set). A stale map at that moment bakes stale literals
+        // that clobber the runtime registry before the re-discovery entry
+        // import materializes the client mount (node HMR served old
+        // client-urls patterns until restart). Lenient: import failures
+        // keep last-known state; discoverRouters' strict pass reports.
+        if (rscEnv?.runner && s.clientUrlSourceByReferenceId?.size) {
+          try {
+            const serverMod = await rscEnv.runner.import(
+              "@rangojs/router/server",
+            );
+            await refreshRecordedClientUrlProjections(
+              s,
+              (server.environments as any)?.ssr,
+              serverMod,
+              rscEnv,
+            );
+            // Force the routes-manifest virtual module to re-transform:
+            // its generated code REPLAYS projections (clear + set) on
+            // every rsc program reload, and self-gen-write suppression
+            // keeps its cached transform alive through this cycle — a
+            // stale replay after propagateDiscoveryState would clobber
+            // the refreshed registry as the realm's last write and the
+            // next router evaluation would materialize the old mount.
+            invalidateRoutesManifestModule(rscEnv);
+          } catch (err: any) {
+            debugDiscovery?.(
+              "watcher: clientUrls projection pre-refresh failed: %s",
+              err?.message,
+            );
+          }
+        }
+        try {
+          // 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(`[rango] 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. Resolves the
+        // discovery gate when complete.
+        if (canRefreshRuntimeDiscovery(s)) {
+          // The cloudflare workerd reload fires inside refreshRuntimeDiscovery
+          // on the successful cycle (see forceCloudflareWorkerReload call
+          // there) so queued follow-up cycles also trigger it.
+          refreshRuntimeDiscovery().catch((err: any) => {
+            console.warn(`[rango] 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);
+    };
+
+    // The `.use` signature of each component-use module at its last
+    // save: a save that keeps it (markup, hooks) re-projects nothing.
+    const componentUseSignatures = new Map<string, string>();
+    const componentUseChanged = (file: string, source: string) => {
+      const next = componentUseSignature(source, file);
+      const changed = next !== componentUseSignatures.get(file);
+      if (next === undefined) componentUseSignatures.delete(file);
+      else componentUseSignatures.set(file, next);
+      return changed;
+    };
+
+    const handleRouteFileChange = (filePath: string) => {
+      if (isOutsideApp(filePath)) {
+        debugDiscovery?.(
+          "watcher: skip %s (outside the discovery scan)",
+          filePath,
+        );
+        return;
+      }
+      if (maybeHandleGeneratedRouteFileMutation(filePath)) return;
+      if (
+        !filePath.endsWith(".ts") &&
+        !filePath.endsWith(".tsx") &&
+        !filePath.endsWith(".js") &&
+        !filePath.endsWith(".jsx")
+      ) {
+        if (s.lastDiscoveryError) {
+          debugDiscovery?.(
+            "watcher: skip non-source %s [LASTERR %s]",
+            filePath,
+            s.lastDiscoveryError.message,
+          );
+        }
+        return;
+      }
+      // Apply scan filter as early-exit before reading file
+      if (s.scanFilter && !s.scanFilter(filePath)) {
+        if (s.lastDiscoveryError) {
+          debugDiscovery?.(
+            "watcher: skip scan-filter %s [LASTERR %s]",
+            filePath,
+            s.lastDiscoveryError.message,
+          );
+        }
+        return;
+      }
+      // Recovery mode: when the previous HMR re-discovery failed, the
+      // import graph is incomplete and the manifest is stuck at the
+      // last-good state. The fix may land in a non-route file (e.g. a
+      // helper imported by the router, a missing module being created,
+      // or a "use client" component) that the narrow content sniff
+      // would otherwise filter out. While in recovery, treat any
+      // in-scan source change as a candidate for rediscovery; the
+      // tighter filter resumes once discovery succeeds again.
+      const inRecoveryMode = !!s.lastDiscoveryError;
+      try {
+        const source = readFileSync(filePath, "utf-8");
+        const trimmed = source.trimStart();
+        const isUseClient =
+          trimmed.startsWith('"use client"') ||
+          trimmed.startsWith("'use client'");
+        // clientUrls() modules are "use client" by contract yet define
+        // routes: their edits must re-run discovery (server projection +
+        // generated types), so only bail on use-client files WITHOUT a
+        // clientUrls() definition. Scar: before this carve-out, editing a
+        // clientUrls module's route shape in dev left the serving router on
+        // the stale projection — the old pattern kept matching and the new
+        // one 404ed until a full restart.
+        let hasClientUrls = source.includes("clientUrls(");
+        if (hasClientUrls) {
+          hasClientUrls = firstCodeMatchIndex(source, /\bclientUrls\(/g) >= 0;
+        }
+        // A component whose `.use` a group reads changes the group's
+        // projection too (its loaders, loading(), revalidate() keys):
+        // on its first save, and when a `.use` changed, came or went.
+        const hasComponentUse = componentUseChanged(filePath, source);
+        if (
+          !inRecoveryMode &&
+          isUseClient &&
+          !hasClientUrls &&
+          !hasComponentUse
+        ) {
+          return;
+        }
+        // Cheap raw pre-check first; only when a candidate token is present
+        // do we confirm it occurs in real code (not a comment/string) via a
+        // single allocation-free code-region scan. Most saved files contain
+        // neither token and skip the scan entirely. This avoids a comment or
+        // string mention spuriously marking a file relevant and triggering an
+        // unnecessary re-discovery on save.
+        let hasUrls = source.includes("urls(");
+        let hasCreateRouter = /\bcreateRouter\s*[<(]/.test(source);
+        if (hasUrls) hasUrls = firstCodeMatchIndex(source, /urls\(/g) >= 0;
+        if (hasCreateRouter) {
+          hasCreateRouter =
+            firstCodeMatchIndex(source, /\bcreateRouter\s*[<(]/g) >= 0;
+        }
+        // hasClientUrls counts here too: in a clientUrls() module the only
+        // `urls(` token sits INSIDE the `clientUrls(` identifier, which the
+        // code scan correctly rejects as a sub-identifier match — so
+        // without this the file would silently fail the sniff.
+        if (
+          !inRecoveryMode &&
+          !hasUrls &&
+          !hasCreateRouter &&
+          !hasClientUrls &&
+          !hasComponentUse
+        ) {
+          return;
+        }
+        if (inRecoveryMode) {
+          debugDiscovery?.(
+            "watcher: recovery rediscovery for %s (urls=%s, router=%s, clientUrls=%s, useClient=%s) [LASTERR %s]",
+            filePath,
+            hasUrls,
+            hasCreateRouter,
+            hasClientUrls,
+            isUseClient,
+            s.lastDiscoveryError!.message,
+          );
+        } else {
+          debugDiscovery?.(
+            "watcher: %s matches (urls=%s, router=%s, clientUrls=%s, componentUse=%s)",
+            filePath,
+            hasUrls,
+            hasCreateRouter,
+            hasClientUrls,
+            hasComponentUse,
+          );
+        }
+        // A "use client" clientUrls module is an HMR-accepted client
+        // boundary in the rsc graph: its edit never invalidates the router
+        // module that materialized its projection, so the re-discovery
+        // entry import would cache-hit and keep serving the stale mount
+        // (old patterns 200, new patterns 404 until restart). Invalidate
+        // the entry + router sources so the import re-creates the routers
+        // against the refreshed projection (installed by the pre-entry
+        // refresh in discover-routers.ts).
+        const mainRscEnv = (server.environments as any)?.rsc;
+        if (
+          ((isUseClient && hasClientUrls) || hasComponentUse) &&
+          mainRscEnv?.runner
+        ) {
+          const rscGraph = mainRscEnv.moduleGraph;
+          if (rscGraph?.getModulesByFile) {
+            // Importers must be invalidated too: the virtual RSC entry
+            // holds a live `import { router }` binding, and re-evaluating
+            // router.tsx alone leaves that binding on the OLD instance —
+            // the request pipeline would keep serving the stale mount.
+            // Vite's invalidateModule already walks importers. Share its
+            // seen set across roots instead of recursively starting a new
+            // traversal at every importer (quadratic on a large graph).
+            // Vite's walk skips HMR-accepting importers and soft-invalidates
+            // static ones (vs the old unconditional hard walk) — safe here:
+            // the entry and every router source are invalidated directly as
+            // roots, and ancestors get the exact treatment Vite's own
+            // file-change propagation applies on a server urls edit.
+            // Cloudflare has no local runner and skips this block: its temp
+            // discovery graph and workerd graph are invalidated wholesale
+            // by refreshRuntimeDiscovery() after this watcher event.
+            const routerSourceFiles = new Set<string>();
+            if (s.resolvedEntryPath) {
+              routerSourceFiles.add(resolve(s.resolvedEntryPath));
+            }
+            for (const entry of s.perRouterManifests) {
+              if (entry.sourceFile) {
+                routerSourceFiles.add(resolve(entry.sourceFile));
+              }
+            }
+            const seen = new Set<any>();
+            for (const file of routerSourceFiles) {
+              const mods = modulesForFile(rscGraph, file);
+              if (!mods) {
+                debugDiscovery?.(
+                  "watcher: clientUrls invalidation found no rsc modules for %s",
+                  file,
+                );
+                continue;
+              }
+              for (const mod of mods) {
+                rscGraph.invalidateModule(mod, seen);
+              }
+            }
+            debugDiscovery?.(
+              "watcher: clientUrls edit invalidated %d rsc module(s) for %d router file(s)",
+              seen.size,
+              routerSourceFiles.size,
+            );
+          }
+        }
+        // Invalidate cache when a router file changes (new router added/removed)
+        if (hasCreateRouter) {
+          const nestedRouterConflict = findNestedRouterConflict([
+            ...(s.cachedRouterFiles ?? []),
+            resolve(filePath),
+          ]);
+          if (nestedRouterConflict) {
+            server.config.logger.error(
+              formatNestedRouterConflictError(nestedRouterConflict),
+            );
+            return;
+          }
+          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, which runs
+        // under the same predicate.
+        if (canRefreshRuntimeDiscovery(s)) {
+          gate.noteRouteEvent();
+        }
+        scheduleRouteRegeneration();
+      } catch (readErr: any) {
+        if (s.lastDiscoveryError) {
+          debugDiscovery?.(
+            "watcher: read error %s: %s [LASTERR %s]",
+            filePath,
+            readErr?.message,
+            s.lastDiscoveryError.message,
+          );
+        }
+        // Ignore read errors for deleted/moved files
+      }
+    };
+
+    // Handle both "add" and "change" events: editors with atomic saves
+    // (unlink + rename) emit "add" instead of "change", and chokidar's
+    // polling mode on CI Linux can also emit "add" for overwrites.
+    server.watcher.on("add", handleRouteFileChange);
+    server.watcher.on("change", handleRouteFileChange);
+
+    // Regenerate gen files when they are deleted (e.g. manual cleanup).
+    // Same no-runner guard as change/add: stale perRouterManifests would
+    // reintroduce reverted content.
+    server.watcher.on("unlink", (filePath) => {
+      if (!isGeneratedRouteFile(filePath) || isOutsideApp(filePath)) return;
+      const hasRunner = !!(server.environments as any)?.rsc?.runner;
+      if (!hasRunner) return;
+      regenerateGeneratedRouteFiles();
+    });
+  }
+}