@rangojs/router 0.0.0-experimental.139 → 0.0.0-experimental.140

package/src/ssr/ssr-root.tsx

@@ -0,0 +1,228 @@
+import React from "react";
+import { renderSegments } from "../segment-system.js";
+import {
+  filterSegmentOrder,
+  filterRouteSegmentIds,
+} from "../browser/react/filter-segment-order.js";
+import { ThemeProvider } from "../theme/ThemeProvider.js";
+import { NonceContext } from "../browser/react/nonce-context.js";
+import { NavigationStoreContext } from "../browser/react/context.js";
+import type { NavigationStoreContextValue } from "../browser/react/context.js";
+import type { HandleData } from "../browser/types.js";
+import type { ResolvedSegment } from "../types.js";
+import type { ResolvedThemeConfig, Theme } from "../theme/types.js";
+import type {
+  EventController,
+  DerivedNavigationState,
+} from "../browser/event-controller.js";
+
+/**
+ * createFromReadableStream from @rangojs/router/internal/deps/ssr.
+ * Deserializes the Flight branch used to build the SSR VDOM.
+ */
+export type CreateFromReadableStream = <T>(
+  stream: ReadableStream<Uint8Array>,
+) => Promise<T>;
+
+/**
+ * RSC payload type (minimal interface for SSR)
+ */
+export interface RscPayload {
+  metadata?: {
+    segments?: ResolvedSegment[];
+    rootLayout?: React.ComponentType<{ children: React.ReactNode }>;
+    handles?: AsyncGenerator<HandleData, void, unknown>;
+    matched?: string[];
+    pathname?: string;
+    params?: Record<string, string>;
+    basename?: string;
+    themeConfig?: ResolvedThemeConfig | null;
+    initialTheme?: Theme;
+    version?: string;
+  };
+}
+
+/**
+ * Consume an async generator and return a Promise that resolves with the final value.
+ * Used for SSR where we need to await all handle data before rendering.
+ */
+async function consumeAsyncGenerator(
+  generator: AsyncGenerator<HandleData, void, unknown>,
+): Promise<HandleData> {
+  let lastData: HandleData = {};
+  for await (const data of generator) {
+    lastData = data;
+  }
+  return lastData;
+}
+
+/**
+ * Create a minimal event controller for SSR.
+ * This provides the correct pathname so useNavigation returns the right value during SSR.
+ */
+function createSsrEventController(opts: {
+  pathname: string;
+  params?: Record<string, string>;
+  handleData?: HandleData;
+  matched?: string[];
+}): EventController {
+  const location = new URL(opts.pathname, "http://localhost");
+  let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
+  const handleState = {
+    data: opts.handleData ?? {},
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: filterRouteSegmentIds(rawMatched),
+  };
+  const state: DerivedNavigationState = {
+    state: "idle",
+    isStreaming: false,
+    isNavigating: false,
+    location,
+    pendingUrl: null,
+    inflightActions: [],
+  };
+
+  return {
+    getState: () => state,
+    getLocation: () => location,
+    subscribe: () => () => {},
+    getActionState: () => ({
+      state: "idle",
+      actionId: null,
+      payload: null,
+      error: null,
+      result: null,
+    }),
+    subscribeToAction: () => () => {},
+    subscribeToHandles: () => () => {},
+    setHandleData: () => {},
+    getHandleState: () => handleState,
+    setRouteSegmentIds: () => {},
+    setParams: (nextParams) => {
+      params = nextParams;
+    },
+    getParams: () => params,
+    setLocation: () => {},
+    startNavigation: () => {
+      throw new Error("Navigation not supported during SSR");
+    },
+    abortNavigation: () => {},
+    startAction: () => {
+      throw new Error("Actions not supported during SSR");
+    },
+    abortAllActions: () => {},
+    getCurrentNavigation: () => null,
+    getInflightActions: () => new Map(),
+    hadAnyConcurrentActions: () => false,
+  };
+}
+
+/**
+ * Options for {@link createSsrRootComponent}.
+ */
+export interface SsrRootOptions {
+  /** createFromReadableStream for the SSR branch of the Flight stream. */
+  createFromReadableStream: CreateFromReadableStream;
+  /** The Flight stream branch to deserialize into the SSR VDOM. */
+  rscStream: ReadableStream<Uint8Array>;
+  /** Nonce for CSP; propagated to NonceContext. */
+  nonce?: string;
+}
+
+/**
+ * Build the closure component that deserializes the Flight payload, consumes
+ * handles to completion, builds the segment tree, and wraps it in the
+ * NavigationStore / Nonce / Theme providers.
+ *
+ * The full-fizz path (renderHTML), the shell prerender pass (capture), and the
+ * shell resume pass all render this identical tree. `resume` requires the tree
+ * above the postponed holes to match the prerendered tree; rendering the same
+ * builder over the same replayed segments is what makes that hold. A fresh
+ * component instance per pass is fine — replay matches structure, not function
+ * identity.
+ *
+ * The memo slots (payload/handles/context/root) are closure-scoped to the
+ * returned instance, so each render pass memoizes independently. renderSegments
+ * is async: React.use() on a fresh promise would suspend and replay SsrRoot,
+ * re-running the whole segment-tree build unless the promise is memoized.
+ */
+export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
+  const { createFromReadableStream, rscStream, nonce } = opts;
+
+  let payload: Promise<RscPayload> | undefined;
+  let handlesPromise: Promise<HandleData> | undefined;
+  let ssrContextValue: NavigationStoreContextValue | undefined;
+  let rootPromise: Promise<React.ReactNode> | undefined;
+
+  return function SsrRoot() {
+    payload ??= createFromReadableStream<RscPayload>(rscStream);
+    const resolved = React.use(payload);
+
+    const themeConfig = resolved.metadata?.themeConfig ?? null;
+    const pathname = resolved.metadata?.pathname ?? "/";
+
+    // Await handles before creating SSR event controller so hooks can
+    // read request-local handle data via NavigationStoreContext.
+    // The handles property is an async generator that yields on each push
+    // Memoize the promise since async generators can only be iterated once
+    let handleData: HandleData = {};
+    if (resolved.metadata?.handles) {
+      handlesPromise ??= consumeAsyncGenerator(resolved.metadata.handles);
+      handleData = React.use(handlesPromise);
+    }
+
+    // Create SSR context with request-local pathname/params/handles.
+    ssrContextValue ??= {
+      store: null as any,
+      eventController: createSsrEventController({
+        pathname,
+        params: resolved.metadata?.params,
+        handleData,
+        matched: resolved.metadata?.matched,
+      }),
+      navigate: async () => {},
+      refresh: async () => {},
+      version: resolved.metadata?.version,
+      basename: resolved.metadata?.basename,
+    };
+
+    // Build content tree from segments.
+    // Order must match NavigationProvider: NavigationStoreContext > NonceContext > ThemeProvider > content
+    // Memoize like payload/handles above: renderSegments is async, so
+    // React.use() on a fresh promise suspends and replays SsrRoot, which
+    // would re-run the entire segment-tree build on every initial render.
+    rootPromise ??= Promise.resolve(
+      renderSegments(resolved.metadata?.segments ?? [], {
+        rootLayout: resolved.metadata?.rootLayout,
+      }),
+    );
+    let content: React.ReactNode = React.use(rootPromise);
+
+    // Wrap content with ThemeProvider if theme is enabled
+    if (themeConfig) {
+      content = (
+        <ThemeProvider
+          config={themeConfig}
+          initialTheme={resolved.metadata?.initialTheme}
+        >
+          {content}
+        </ThemeProvider>
+      );
+    }
+
+    // Wrap with NonceContext so client components (e.g. MetaTags) can
+    // apply CSP nonces to inline scripts during SSR. Always present to
+    // match the browser-side NavigationProvider tree shape for hydration.
+    content = (
+      <NonceContext.Provider value={nonce}>{content}</NonceContext.Provider>
+    );
+
+    // Wrap with NavigationStoreContext for useNavigation hook
+    return (
+      <NavigationStoreContext.Provider value={ssrContextValue!}>
+        {content}
+      </NavigationStoreContext.Provider>
+    );
+  };
+}

package/src/testing/render-route.tsx

@@ -51,7 +51,10 @@ import type { NavigationStore, NavigationBridge } from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
 import { NavigationProvider } from "../browser/react/NavigationProvider.js";
-import { compilePattern } from "../router/pattern-matching.js";
+import {
+  compilePattern,
+  buildParamsFromMatch,
+} from "../router/pattern-matching.js";
 import { normalizeBasename } from "../router/basename.js";
 import type { LoaderDefinition } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
@@ -303,14 +306,9 @@ function matchLeaf(
   const compiled = compilePattern(pattern);
   const match = compiled.regex.exec(pathname);
   if (!match) return null;
-  const params: Record<string, string> = {};
-  compiled.paramNames.forEach((name, index) => {
-    const value = match[index + 1];
-    if (value !== undefined) {
-      params[name] = decodeURIComponent(value);
-    }
-  });
-  return params;
+  // Reuse the production param builder so the harness matches the real matcher
+  // exactly (named catch-all "" binding, decoding) instead of forking it.
+  return buildParamsFromMatch(match, compiled.paramNames, compiled.catchAll);
 }
 
 function staticPrefix(pattern: string): string {

package/src/types/route-config.ts

@@ -10,20 +10,29 @@ export type DocumentProps = {
 type ParseConstraint<T extends string> =
   T extends `${infer First}|${infer Rest}` ? First | ParseConstraint<Rest> : T;
 
+// Named catch-all (`:name*` / `:name+`) is matched BEFORE the `?`/suffix
+// branches. Its modifier is anchored to the END of the token (no trailing
+// `${string}`) so it is a true suffix and never mis-splits a constraint body
+// such as `id(\d+)`. Both are a required `string`: a matched catch-all always
+// binds a value (possibly ""), so the key is always present.
 type ExtractParamInfo<T extends string> =
   T extends `${infer Name}(${infer Constraint})?${string}`
     ? { name: Name; optional: true; type: ParseConstraint<Constraint> }
     : T extends `${infer Name}(${infer Constraint})${string}`
       ? { name: Name; optional: false; type: ParseConstraint<Constraint> }
-      : T extends `${infer Name}?${string}`
-        ? { name: Name; optional: true; type: string }
-        : T extends `${infer Name}.${string}`
+      : T extends `${infer Name}*`
+        ? { name: Name; optional: false; type: string }
+        : T extends `${infer Name}+`
           ? { name: Name; optional: false; type: string }
-          : T extends `${infer Name}-${string}`
-            ? { name: Name; optional: false; type: string }
-            : T extends `${infer Name}~${string}`
+          : T extends `${infer Name}?${string}`
+            ? { name: Name; optional: true; type: string }
+            : T extends `${infer Name}.${string}`
               ? { name: Name; optional: false; type: string }
-              : { name: T; optional: false; type: string };
+              : T extends `${infer Name}-${string}`
+                ? { name: Name; optional: false; type: string }
+                : T extends `${infer Name}~${string}`
+                  ? { name: Name; optional: false; type: string }
+                  : { name: T; optional: false; type: string };
 
 type ParamFromInfo<Info> = Info extends {
   name: infer N extends string;
@@ -51,12 +60,15 @@ type MergeParams<A, B> = Pick<A, keyof A> & Pick<B, keyof B> extends infer O
  * - Optional params: /:locale? -> { locale?: string }
  * - Constrained params: /:locale(en|gb) -> { locale: "en" | "gb" }
  * - Optional + constrained: /:locale(en|gb)? -> { locale?: "en" | "gb" }
+ * - Named catch-all: /:path+ (one-or-more), /:slug* (zero-or-more) -> string
  *
  * @example
  * ExtractParams<"/products/:id"> // { id: string }
  * ExtractParams<"/:locale?/blog/:slug"> // { locale?: string; slug: string }
  * ExtractParams<"/:locale(en|gb)/blog"> // { locale: "en" | "gb" }
  * ExtractParams<"/:locale(en|gb)?/blog/:slug"> // { locale?: "en" | "gb"; slug: string }
+ * ExtractParams<"/docs/:slug*"> // { slug: string }
+ * ExtractParams<"/shop/:path+"> // { path: string }
  */
 export type ExtractParams<
   T extends string,

package/src/urls/type-extraction.ts

@@ -81,16 +81,26 @@ type ExtractRoutesFromItem<T> =
   // When search schema is non-empty, value becomes { path, search } object
   T extends TypedRouteItem<infer TName, infer TPattern, any, infer TSearch>
     ? TName extends string
-      ? TName extends UnnamedRoute
-        ? {} // Exclude unnamed routes from type map
-        : {} extends TSearch
-          ? { [K in TName]: TPattern }
-          : {
-              [K in TName]: {
-                readonly path: TPattern;
-                readonly search: TSearch;
-              };
-            }
+      ? // Widened-name guard (#642): some name-less call forms — notably the
+        // 3-arg children-fn overload path(pattern, component, () => [...]) —
+        // let TName infer to the bare `string` constraint instead of the
+        // UnnamedRoute sentinel, because the children-fn argument structurally
+        // satisfies the all-optional PathOptions<TName> union member. Mapping
+        // over a bare `string` key would emit `{ [K in string]: TPattern }`, an
+        // index signature that poisons the whole sibling map (Rango.Path
+        // collapses to never). Treat an unresolved name as unnamed.
+        string extends TName
+        ? {}
+        : TName extends UnnamedRoute
+          ? {} // Exclude unnamed routes from type map
+          : {} extends TSearch
+            ? { [K in TName]: TPattern }
+            : {
+                [K in TName]: {
+                  readonly path: TPattern;
+                  readonly search: TSearch;
+                };
+              }
       : {}
     : // TypedIncludeItem: extract prefixed routes (both name and URL prefix)
       T extends TypedIncludeItem<
@@ -128,9 +138,15 @@ type ExtractRoutesFromItems<T extends readonly any[]> = T extends readonly any[]
   ? UnionToIntersection<
       { [K in keyof T]: ExtractRoutesFromItem<T[K]> }[number]
     > extends infer R
-    ? R extends Record<string, any>
-      ? R
-      : {}
+    ? // Blast-radius guard: never let a single malformed item collapse the
+      // whole map. A `never` intersection satisfies `extends Record<string,any>`
+      // (never extends everything), so check it explicitly first and fall back
+      // to `{}` rather than propagating `never`. See #642.
+      [R] extends [never]
+      ? {}
+      : R extends Record<string, any>
+        ? R
+        : {}
     : {}
   : {};
 
@@ -169,9 +185,15 @@ type PrefixKeys<
 type ExtractResponsesFromItem<T> =
   T extends TypedRouteItem<infer TName, any, infer TData>
     ? TName extends string
-      ? TName extends UnnamedRoute
+      ? // Widened-name guard (#642), parallels ExtractRoutesFromItem. A name-less
+        // children-fn path.json(pattern, handler, () => [...]) infers TName as
+        // bare `string`; without this the response map picks up an index
+        // signature { [K in string]: TData } that wipes named siblings.
+        string extends TName
         ? {}
-        : { [K in TName]: TData }
+        : TName extends UnnamedRoute
+          ? {}
+          : { [K in TName]: TData }
       : {}
     : T extends TypedIncludeItem<any, infer TNamePrefix, any, infer TResponses>
       ? TNamePrefix extends LocalOnlyInclude
@@ -206,9 +228,12 @@ type ExtractResponsesFromItems<T extends readonly any[]> =
     ? UnionToIntersection<
         { [K in keyof T]: ExtractResponsesFromItem<T[K]> }[number]
       > extends infer R
-      ? R extends Record<string, unknown>
-        ? R
-        : {}
+      ? // Blast-radius guard (parallels ExtractRoutesFromItems). See #642.
+        [R] extends [never]
+        ? {}
+        : R extends Record<string, unknown>
+          ? R
+          : {}
       : {}
     : {};
 

package/src/vite/discovery/discovery-errors.ts

@@ -192,3 +192,64 @@ export class DiscoveryError extends Error {
     Object.setPrototypeOf(this, DiscoveryError.prototype);
   }
 }
+
+/** How the dev caller should surface a discovery failure. */
+export interface DiscoveryFailureReport {
+  level: "error" | "warn";
+  message: string;
+}
+
+/**
+ * Decide how to surface a dev-boot discovery failure in the terminal.
+ *
+ * The bare "no routers found" case (a DiscoveryError with no caught host-handler
+ * failures) is ambiguous. It is either:
+ *   - a genuine misconfiguration — the entry never calls createRouter(), or the
+ *     configured entry path is wrong; or
+ *   - a transient artifact of a Vite dependency re-optimization racing with boot
+ *     discovery (a module read before the entry import resolves to the
+ *     pre-optimize copy of the runner graph while createRouter() populated the
+ *     post-optimize copy — see router-discovery.ts).
+ *
+ * We can only tell them apart when the caller observed the dep optimizer's
+ * `browserHash` change across the discovery attempt (`reoptimizeObserved`): a
+ * reload-causing re-optimization landed mid-flight, so the empty read was
+ * transient and the app self-heals per-request (handler.ts builds the trie from
+ * the router's live urlpatterns) with discovery re-running on the next boot.
+ *
+ * A DiscoveryError that DOES carry caught host-handler failures already embeds
+ * the real cause in its message, and any non-DiscoveryError is a hard failure;
+ * both stay loud with full detail.
+ */
+export function describeDiscoveryFailure(
+  err: unknown,
+  opts: { reoptimizeObserved?: boolean } = {},
+): DiscoveryFailureReport {
+  if (err instanceof DiscoveryError && err.caught.length === 0) {
+    const entry = err.entryPath ?? "the router entry";
+    if (opts.reoptimizeObserved) {
+      return {
+        level: "warn",
+        message:
+          `[rango] No routers found while Vite was re-optimizing dependencies on ` +
+          `dev boot. This is transient: routes are served per-request and ` +
+          `discovery re-runs automatically, so it clears on the next boot. If ` +
+          `routes still 404, confirm ${entry} calls createRouter().`,
+      };
+    }
+    return {
+      level: "error",
+      message:
+        `${err.message}\n` +
+        `  Ensure ${entry} calls createRouter() at module top level and that the ` +
+        `configured router entry path is correct.`,
+    };
+  }
+
+  const e = err as { stack?: string; message?: string };
+  const detail = e?.stack ?? e?.message ?? String(err);
+  return {
+    level: "error",
+    message: `[rango] Router discovery failed: ${detail}`,
+  };
+}

package/src/vite/plugins/virtual-entries.ts

@@ -38,9 +38,14 @@ initializeApp().catch(console.error);
 
 export const VIRTUAL_ENTRY_SSR: string = `
 import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
-import { renderToReadableStream } from "react-dom/server.edge";
+import { renderToReadableStream, resume } from "react-dom/server.edge";
+import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
-import { createSSRHandler } from "@rangojs/router/ssr";
+import {
+  createSSRHandler,
+  createShellCaptureHandler,
+  createShellResumeHandler,
+} from "@rangojs/router/ssr";
 
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
@@ -49,6 +54,26 @@ export const renderHTML = createSSRHandler({
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
+
+export const captureShellHTML = createShellCaptureHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
+
+export const resumeShellHTML = createShellResumeHandler({
+  createFromReadableStream,
+  renderToReadableStream,
+  injectRSCPayload,
+  prerender,
+  resume,
+  loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+});
 `.trim();
 
 /**

package/src/vite/router-discovery.ts

@@ -43,6 +43,7 @@ import {
   peekSelfGenWrite,
 } from "./discovery/self-gen-tracking.js";
 import { discoverRouters } from "./discovery/discover-routers.js";
+import { describeDiscoveryFailure } from "./discovery/discovery-errors.js";
 import {
   writeCombinedRouteTypesWithTracking,
   writeRouteTypesFiles,
@@ -653,6 +654,30 @@ export function createRouterDiscoveryPlugin(
         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);
+        }
+      };
+
       const discover = async () => {
         const discoverStart = performance.now();
         const rscEnv = (server.environments as any)?.rsc;
@@ -668,18 +693,26 @@ export function createRouterDiscoveryPlugin(
 
           // 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, viteCommand, viteMode),
             );
 
-            const tempRscEnv = await timed(
+            tempRscEnv = await timed(
               debugDiscovery,
               "getOrCreateTempServer",
               () => getOrCreateTempServer(),
             );
             if (tempRscEnv) {
+              optimizerHashBefore =
+                tempRscEnv.depsOptimizer?.metadata?.browserHash;
               await timed(debugDiscovery, "discoverRouters (cloudflare)", () =>
                 discoverRouters(s, tempRscEnv),
               );
@@ -688,8 +721,10 @@ export function createRouterDiscoveryPlugin(
               );
             }
           } catch (err: any) {
-            console.warn(
-              `[rango] Cloudflare dev discovery failed: ${err.message}\n${err.stack}`,
+            emitDiscoveryFailure(
+              err,
+              optimizerHashBefore,
+              tempRscEnv?.depsOptimizer?.metadata?.browserHash,
             );
           }
 
@@ -701,6 +736,13 @@ export function createRouterDiscoveryPlugin(
           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");
@@ -708,21 +750,31 @@ export function createRouterDiscoveryPlugin(
             acquireBuildEnv(s, viteCommand, viteMode),
           );
 
-          // Set the readiness gate BEFORE discovery so early requests
-          // block until manifest is populated
-          const serverMod = await timed(
-            debugDiscovery,
-            "import @rangojs/router/server",
-            () => rscEnv.runner.import("@rangojs/router/server"),
+          // 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" before the
+          // entry to arm the gate early. During a Vite dependency re-optimization
+          // (dev boot after a lockfile change, or `vite dev --force`), a module
+          // imported here before the entry resolves to the pre-optimize copy of
+          // the runner's module graph, while discoverRouters' entry import — which
+          // awaits the in-flight re-optimization — resolves to the post-optimize
+          // copy. createRouter() then populates RouterRegistry on the fresh copy,
+          // but a stale pre-imported "@rangojs/router/server" reads the other
+          // copy's empty Map and discovery throws a spurious "No routers found"
+          // even though the app is configured correctly. discoverRouters imports
+          // the entry first and reads the registry off the same instance, keeping
+          // read and write on one copy. 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),
           );
           if (serverMod?.setManifestReadyPromise) {
             serverMod.setManifestReadyPromise(discoveryPromise);
           }
 
-          await timed(debugDiscovery, "discoverRouters", () =>
-            discoverRouters(s, rscEnv),
-          );
-
           // Store server origin for dev prerender endpoint (virtual module injection)
           s.devServerOrigin = getDevServerOrigin();
 
@@ -740,8 +792,10 @@ export function createRouterDiscoveryPlugin(
             propagateDiscoveryState(rscEnv),
           );
         } catch (err: any) {
-          console.warn(
-            `[rango] Router discovery failed: ${err.message}\n${err.stack}`,
+          emitDiscoveryFailure(
+            err,
+            optimizerHashBefore,
+            rscEnv.depsOptimizer?.metadata?.browserHash,
           );
         } finally {
           debugDiscovery?.(