@rangojs/router 0.0.0-experimental.115 → 0.0.0-experimental.116

package/src/rsc/response-error.ts

@@ -1,37 +1,104 @@
 /**
- * Response Error Payload Builder
+ * Problem Details (RFC 9457) Builder
  *
- * Builds a ResponseError object from a caught error, controlling
- * what information is exposed based on error type and environment.
+ * Builds a problem+json error body from a caught error, controlling what
+ * information is exposed based on error type and environment.
  */
 
 import { RouterError } from "../errors.js";
-import type { ResponseError } from "../urls.js";
+import type { ProblemDetails } from "../urls.js";
 
 /**
- * Build a ResponseError payload from a caught error.
- * RouterError messages are always exposed (developer-crafted).
+ * HTTP reason phrases for the problem `title` member. Inlined because the
+ * router targets edge/worker runtimes without node's `http.STATUS_CODES`;
+ * covers the full standard 4xx/5xx range, with a generic fallback for any
+ * non-standard status a handler might set.
+ */
+const STATUS_PHRASES: Record<number, string> = {
+  400: "Bad Request",
+  401: "Unauthorized",
+  402: "Payment Required",
+  403: "Forbidden",
+  404: "Not Found",
+  405: "Method Not Allowed",
+  406: "Not Acceptable",
+  407: "Proxy Authentication Required",
+  408: "Request Timeout",
+  409: "Conflict",
+  410: "Gone",
+  411: "Length Required",
+  412: "Precondition Failed",
+  413: "Payload Too Large",
+  414: "URI Too Long",
+  415: "Unsupported Media Type",
+  416: "Range Not Satisfiable",
+  417: "Expectation Failed",
+  418: "I'm a Teapot",
+  421: "Misdirected Request",
+  422: "Unprocessable Entity",
+  423: "Locked",
+  424: "Failed Dependency",
+  425: "Too Early",
+  426: "Upgrade Required",
+  428: "Precondition Required",
+  429: "Too Many Requests",
+  431: "Request Header Fields Too Large",
+  451: "Unavailable For Legal Reasons",
+  500: "Internal Server Error",
+  501: "Not Implemented",
+  502: "Bad Gateway",
+  503: "Service Unavailable",
+  504: "Gateway Timeout",
+  505: "HTTP Version Not Supported",
+  506: "Variant Also Negotiates",
+  507: "Insufficient Storage",
+  508: "Loop Detected",
+  510: "Not Extended",
+  511: "Network Authentication Required",
+};
+
+function statusPhrase(status: number): string {
+  return STATUS_PHRASES[status] ?? "Error";
+}
+
+/**
+ * Build an RFC 9457 problem+json body from a caught error.
+ * RouterError messages/codes are always exposed (developer-crafted).
  * Standard Error messages are hidden in production.
+ *
+ * The `type` member is omitted in this phase: per RFC 9457 an absent `type` is
+ * treated as `"about:blank"` (no semantics beyond the HTTP status), so emitting
+ * it adds nothing. Per-route problem-type URIs arrive with the declared-errors
+ * map later. `code` is always present so consumers can branch on it
+ * (`"INTERNAL"` for non-RouterError failures).
  */
-export function createResponseErrorPayload(
+export function createProblemDetails(
   error: unknown,
+  status: number,
   isDev: boolean,
-): ResponseError {
+): ProblemDetails {
   if (error instanceof RouterError) {
     return {
-      message: error.message,
+      title: statusPhrase(status),
+      status,
+      detail: error.message,
       code: error.code,
-      ...(error.type ? { type: error.type } : {}),
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   if (error instanceof Error) {
     return {
-      message: isDev ? error.message : "Internal Server Error",
+      title: statusPhrase(status),
+      status,
+      detail: isDev ? error.message : "Internal Server Error",
+      code: "INTERNAL",
       ...(isDev && error.stack ? { stack: error.stack } : {}),
     };
   }
   return {
-    message: isDev ? String(error) : "Internal Server Error",
+    title: statusPhrase(status),
+    status,
+    detail: isDev ? String(error) : "Internal Server Error",
+    code: "INTERNAL",
   };
 }

package/src/rsc/response-route-handler.ts

@@ -21,7 +21,7 @@ import {
 import type { MiddlewareFn } from "../router/middleware.js";
 import type { EntryData } from "../server/context.js";
 import type { HandlerContext } from "./handler-context.js";
-import { createResponseErrorPayload } from "./response-error.js";
+import { createProblemDetails } from "./response-error.js";
 import {
   createResponseWithMergedHeaders,
   finalizeResponse,
@@ -131,13 +131,10 @@ export async function handleResponseRoute<TEnv>(
 
       // Handled before the MIME lookup (json is also a RESPONSE_TYPE_MIME key).
       if (preview.responseType === "json") {
-        return createResponseWithMergedHeaders(
-          JSON.stringify({ data: result }),
-          {
-            status: 200,
-            headers: { "content-type": "application/json;charset=utf-8" },
-          },
-        );
+        return createResponseWithMergedHeaders(JSON.stringify(result), {
+          status: 200,
+          headers: { "content-type": "application/json;charset=utf-8" },
+        });
       }
 
       // Object.hasOwn (not truthiness) so prototype names like "toString" are not
@@ -157,16 +154,22 @@ export async function handleResponseRoute<TEnv>(
     } catch (error) {
       handlerCtx.callOnError(error, "handler", errorCtx);
       const isDev = process.env.NODE_ENV !== "production";
-      const status = error instanceof RouterError ? error.status : 500;
+      const derivedStatus = error instanceof RouterError ? error.status : 500;
+      // Resolve the effective status the same way createResponseWithMergedHeaders
+      // will (ctx.res.status override) so the problem body's status/title match
+      // the actual HTTP status — e.g. when a handler called ctx.setStatus()
+      // before throwing.
+      const status =
+        reqCtx.res.status !== 200 ? reqCtx.res.status : derivedStatus;
 
       if (preview.responseType === "json") {
         return createResponseWithMergedHeaders(
-          JSON.stringify({
-            error: createResponseErrorPayload(error, isDev),
-          }),
+          JSON.stringify(createProblemDetails(error, status, isDev)),
           {
             status,
-            headers: { "content-type": "application/json;charset=utf-8" },
+            headers: {
+              "content-type": "application/problem+json;charset=utf-8",
+            },
           },
         );
       }

package/src/urls/index.ts

@@ -21,8 +21,7 @@ export type {
 export type {
   ExtractRoutes,
   ExtractResponses,
-  ResponseError,
-  ResponseEnvelope,
+  ProblemDetails,
   RouteResponse,
 } from "./type-extraction.js";
 

package/src/urls/type-extraction.ts

@@ -220,44 +220,53 @@ export type ExtractResponses<T extends readonly any[]> =
   ExtractResponsesFromItems<T>;
 
 // ============================================================================
-// Response Envelope Types
+// Response Error (RFC 9457 problem+json) Type
 // ============================================================================
 
 /**
- * Error shape returned in the `{ error }` side of a JSON response envelope.
- */
-export interface ResponseError {
-  message: string;
-  code?: string;
-  type?: string;
-  stack?: string;
-}
-
-/**
- * Discriminated union envelope for JSON response routes.
- * Consumers check `result.error` to discriminate between success and failure.
+ * RFC 9457 (problem+json) error body returned by JSON response routes on a
+ * non-2xx status. Sent verbatim as the response body (not wrapped) with
+ * content-type `application/problem+json`.
  *
  * @example
  * ```typescript
- * const result: ResponseEnvelope<Product> = await fetch(url).then(r => r.json());
- * if (result.error) {
- *   console.log(result.error.message, result.error.code);
+ * const res = await fetch(url);
+ * if (!res.ok) {
+ *   const problem: ProblemDetails = await res.json();
+ *   console.log(problem.code, problem.detail); // "NOT_FOUND", "Product not found"
  *   return;
  * }
- * result.data.name // fully typed
+ * const product = await res.json(); // bare value, no envelope
  * ```
  */
-export type ResponseEnvelope<T> =
-  | { data: T; error?: undefined }
-  | { data?: undefined; error: ResponseError };
+export interface ProblemDetails {
+  /**
+   * URI reference identifying the problem type. Omitted in this phase (per RFC
+   * 9457 an absent `type` is treated as `"about:blank"` — no semantics beyond
+   * the HTTP status); per-route problem-type URIs arrive with the
+   * declared-errors map later.
+   */
+  type?: string;
+  /** Short, human-readable summary (the HTTP status reason phrase). */
+  title: string;
+  /** The HTTP status code. */
+  status: number;
+  /** Human-readable explanation specific to this occurrence (the error message). */
+  detail: string;
+  /** Stable machine-readable error code (`RouterError.code`, else `"INTERNAL"`). */
+  code: string;
+  /** Stack trace, included in development only. */
+  stack?: string;
+}
 
 // ============================================================================
 // Response Type Consumer Utilities
 // ============================================================================
 
 /**
- * Extract the response data type for a named route from a UrlPatterns instance.
- * Wraps in ResponseEnvelope since JSON response routes return enveloped data.
+ * Extract the JSON response payload type for a named route from a UrlPatterns
+ * instance. JSON response routes send the handler's return value verbatim
+ * (bare), so this resolves to the wire value a consumer receives — no envelope.
  *
  * @example
  * ```typescript
@@ -266,7 +275,7 @@ export type ResponseEnvelope<T> =
  * ]);
  *
  * type HealthData = RouteResponse<typeof apiPatterns, "health">;
- * // ResponseEnvelope<{ status: string; timestamp: number }>
+ * // { status: string; timestamp: number }
  * ```
  *
  * The payload is the JSON wire shape (via `Rango.JsonSerialize`), matching
@@ -277,6 +286,6 @@ export type RouteResponse<TPatterns, TName extends string> = TPatterns extends {
   readonly _responses?: infer R;
 }
   ? TName extends keyof R
-    ? ResponseEnvelope<JsonSerialize<Exclude<R[TName], Response>>>
+    ? JsonSerialize<Exclude<R[TName], Response>>
     : never
   : never;

package/src/vite/discovery/discover-routers.ts

@@ -26,6 +26,7 @@ import {
   type CaughtDiscoveryError,
 } from "./discovery-errors.js";
 import { createRangoDebugger, timed, NS } from "../debug.js";
+import { computeProductionHash } from "../plugins/client-ref-hashing.js";
 
 const debug = createRangoDebugger(NS.discovery);
 
@@ -143,6 +144,28 @@ export async function discoverRouters(
   // Collect all manifests for trie building (avoid re-running generateManifest)
   const allManifests: Array<{ id: string; manifest: any }> = [];
 
+  // Built-in clientChunks context (present only when the built-in strategy is
+  // active). Collect the production hashes of "use client" error/notFound
+  // fallback modules so the strategy can route them into app-fallback.
+  const clientChunkCtx = state.opts?.clientChunkCtx;
+  const collectClientFallbackRef = clientChunkCtx
+    ? (refKey: string) =>
+        clientChunkCtx.fallbackRefs.add(
+          computeProductionHash(state.projectRoot, refKey),
+        )
+    : undefined;
+  // Router-level boundary defaults (`createRouter({ defaultErrorBoundary, ... })`)
+  // are NOT in EntryData, so generateManifestFull's walk misses them. Collect any
+  // "use client" default boundary directly off the router instance. The value is
+  // commonly a handler function wrapping the client boundary in server providers,
+  // so collectFallbackClientRefs invokes + walks the tree. Routed through buildMod
+  // so it runs in the same RSC runner realm the boundary value came from.
+  const collectFromBoundaryNode = (node: unknown): void => {
+    if (collectClientFallbackRef && buildMod.collectFallbackClientRefs) {
+      buildMod.collectFallbackClientRefs(node, collectClientFallbackRef);
+    }
+  };
+
   const manifestGenStart = debug ? performance.now() : 0;
   for (const [id, router] of registry) {
     if (!router.urlpatterns || !generateManifestFull) {
@@ -152,10 +175,23 @@ export async function discoverRouters(
     const manifest = generateManifestFull(
       router.urlpatterns,
       routerMountIndex,
-      router.__basename ? { urlPrefix: router.__basename } : undefined,
+      {
+        ...(router.__basename ? { urlPrefix: router.__basename } : {}),
+        ...(collectClientFallbackRef ? { collectClientFallbackRef } : {}),
+      },
     );
     routerMountIndex++;
     allManifests.push({ id, manifest });
+
+    // Router-level "use client" boundary defaults -> app-fallback (the
+    // route-tree errorBoundary()/notFoundBoundary() helpers are already
+    // collected inside generateManifestFull via collectClientFallbackRef).
+    if (collectClientFallbackRef) {
+      collectFromBoundaryNode(router.__defaultErrorBoundary);
+      collectFromBoundaryNode(router.__defaultNotFoundBoundary);
+      collectFromBoundaryNode(router.__notFound);
+    }
+
     const routeCount = Object.keys(manifest.routeManifest).length;
     const staticRoutes = Object.values(manifest.routeManifest).filter(
       (p: any) => !p.includes(":") && !p.includes("*"),
@@ -304,36 +340,17 @@ export async function discoverRouters(
         mergedResponseTypeRoutes,
       );
 
-      // Build per-router tries for multi-router isolation.
+      // Build per-router tries for multi-router isolation. Uses the single
+      // shared buildPerRouterTrie so the production serialized trie is built by
+      // exactly the same code as the dev/HMR runtime rebuild (manifest-init.ts).
+      const buildPerRouterTrie = buildMod.buildPerRouterTrie;
       for (const { id, manifest } of allManifests) {
-        if (
-          !manifest._routeAncestry ||
-          Object.keys(manifest._routeAncestry).length === 0
-        )
-          continue;
-        const perRouterStaticPrefix: Record<string, string> = {};
-        for (const name of Object.keys(manifest.routeManifest)) {
-          perRouterStaticPrefix[name] = "";
+        const perRouterTrie = buildPerRouterTrie
+          ? buildPerRouterTrie(manifest)
+          : null;
+        if (perRouterTrie) {
+          newPerRouterTrieMap.set(id, perRouterTrie);
         }
-        buildRouteToStaticPrefix(manifest.prefixTree, perRouterStaticPrefix);
-
-        const perRouterPrerenderNames = manifest.prerenderRoutes
-          ? new Set<string>(manifest.prerenderRoutes)
-          : undefined;
-        const perRouterPassthroughNames = manifest.passthroughRoutes
-          ? new Set<string>(manifest.passthroughRoutes)
-          : undefined;
-
-        const perRouterTrie = buildRouteTrie(
-          manifest.routeManifest,
-          manifest._routeAncestry,
-          perRouterStaticPrefix,
-          manifest.routeTrailingSlash,
-          perRouterPrerenderNames,
-          perRouterPassthroughNames,
-          manifest.responseTypeRoutes,
-        );
-        newPerRouterTrieMap.set(id, perRouterTrie);
       }
     }
   }

package/src/vite/discovery/state.ts

@@ -20,6 +20,13 @@ export interface PluginOptions {
   buildEnv?: import("../plugin-types.js").BuildEnvOption;
   /** Deployment preset (needed for buildEnv "auto" resolution). */
   preset?: "node" | "cloudflare";
+  /**
+   * Shared context the built-in clientChunks strategy reads. Discovery populates
+   * it (registered fallback hashes + single-router name) before the client build
+   * invokes the strategy. Present only when the built-in strategy is active
+   * (`clientChunks: true`/default); undefined for `false` or a custom function.
+   */
+  clientChunkCtx?: import("../utils/client-chunks.js").ClientChunkContext;
 }
 
 export interface PrecomputedEntry {

package/src/vite/plugins/client-ref-hashing.ts

@@ -22,6 +22,17 @@ const FS_PREFIX = "/@fs/";
  * Returns the input unchanged if it doesn't match a known dev-mode pattern
  * (e.g., already a production hash).
  */
+/**
+ * The production client-reference key hash: `sha256(relativeId).slice(0,12)`,
+ * matching @vitejs/plugin-rsc's `hashString`. Exported so the client-chunks
+ * strategy can hash a `clientChunks` callback's `meta.normalizedId` (already the
+ * project-root-relative id) and compare it against fallback hashes collected
+ * during discovery.
+ */
+export function hashRefKey(relativeId: string): string {
+  return createHash("sha256").update(relativeId).digest("hex").slice(0, 12);
+}
+
 export function computeProductionHash(
   projectRoot: string,
   refKey: string,
@@ -49,7 +60,7 @@ export function computeProductionHash(
     return refKey;
   }
 
-  return createHash("sha256").update(toHash).digest("hex").slice(0, 12);
+  return hashRefKey(toHash);
 }
 
 // Regex to match registerClientReference() calls as emitted by @vitejs/plugin-rsc.

package/src/vite/rango.ts

@@ -23,7 +23,10 @@ import {
   onwarn,
   getManualChunks,
 } from "./utils/shared-utils.js";
-import { resolveClientChunks } from "./utils/client-chunks.js";
+import {
+  resolveClientChunks,
+  type ClientChunkContext,
+} from "./utils/client-chunks.js";
 import type { RangoOptions } from "./plugin-types.js";
 import { printBanner, rangoVersion } from "./utils/banner.js";
 import { createVersionInjectorPlugin } from "./plugins/version-injector.js";
@@ -69,9 +72,17 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
   // @vitejs/plugin-rsc in both presets. The built-in strategy only splits where it
   // recognizes a route structure, so this default is a no-op for flat / host-split
   // apps and never duplicates the shared runtime.
-  const clientChunks = resolveClientChunks(
-    resolvedOptions.clientChunks ?? true,
-  );
+  const clientChunksOption = resolvedOptions.clientChunks ?? true;
+  // Shared context the built-in strategy reads at build time: the production
+  // hashes of registered error/notFound fallback modules (-> app-fallback).
+  // Populated by the discovery plugin in buildStart, before the client build
+  // invokes the strategy. Only wired when the built-in strategy is active; a
+  // custom function owns its own grouping.
+  const useBuiltInClientChunks = clientChunksOption === true;
+  const clientChunkCtx: ClientChunkContext | undefined = useBuiltInClientChunks
+    ? { fallbackRefs: new Set<string>() }
+    : undefined;
+  const clientChunks = resolveClientChunks(clientChunksOption, clientChunkCtx);
   debugConfig?.("rango(%s) setup start", preset);
 
   const plugins: PluginOption[] = [];
@@ -157,6 +168,14 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             client: {
               build: {
                 rollupOptions: {
+                  // FILE_NAME_CONFLICT (and any other client-build warning) is
+                  // emitted by the CLIENT environment build, which consults THIS
+                  // env's onwarn -- Vite 8's environment builds do NOT propagate
+                  // the top-level build.rollupOptions.onwarn into the client env.
+                  // Wire it here so the suppression runs where the conflicts
+                  // originate (the top-level handler is invoked 0x for these; the
+                  // client-env handler is invoked for all of them).
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks,
                   },
@@ -317,6 +336,14 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
             client: {
               build: {
                 rollupOptions: {
+                  // FILE_NAME_CONFLICT (and any other client-build warning) is
+                  // emitted by the CLIENT environment build, which consults THIS
+                  // env's onwarn -- Vite 8's environment builds do NOT propagate
+                  // the top-level build.rollupOptions.onwarn into the client env.
+                  // Wire it here so the suppression runs where the conflicts
+                  // originate (the top-level handler is invoked 0x for these; the
+                  // client-env handler is invoked for all of them).
+                  onwarn,
                   output: {
                     manualChunks: getManualChunks,
                   },
@@ -508,6 +535,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       enableBuildPrerender: prerenderEnabled,
       buildEnv: options?.buildEnv,
       preset,
+      clientChunkCtx,
     }),
   );
 

package/src/vite/utils/client-chunks.ts

@@ -6,10 +6,28 @@
 
 import type { ClientChunkMeta, ClientChunks } from "../plugin-types.js";
 import { createRangoDebugger, NS } from "../debug.js";
+import { hashRefKey } from "../plugins/client-ref-hashing.js";
 
 /** The callback shape @vitejs/plugin-rsc's `clientChunks` option accepts. */
 export type RscClientChunksFn = (meta: ClientChunkMeta) => string | undefined;
 
+/**
+ * Build-time context the discovery pass populates and the built-in strategy
+ * reads. It refines how the catch-all (no route-root marker) modules are grouped
+ * without touching marker splits or the shared runtime:
+ *
+ * - `fallbackRefs`: production hashes of the `"use client"` modules a consumer
+ *   registered as `errorBoundary`/`notFoundBoundary` fallbacks. Pulled into a
+ *   dedicated `app-fallback` chunk so the error UI is not co-bundled with the
+ *   very route code it exists to catch failures for (resilience), and so the
+ *   chunk it would otherwise sit in gets named after a real module rather than
+ *   the boundary. Populated by reading each fallback element's client-reference
+ *   `$$id` during discovery (see discover-routers).
+ */
+export interface ClientChunkContext {
+  fallbackRefs: Set<string>;
+}
+
 /**
  * Opt-in observability for the built-in strategy. The route-root marker list is
  * intentionally finite (see {@link ROUTE_ROOT_DIRS}); a consumer whose layout
@@ -101,18 +119,31 @@ const ROUTE_ROOT_DIRS = new Set([
  *   `app-components`), re-introducing cross-app leakage.
  *
  * Resolution order:
- * 1. If the path passes through a {@link ROUTE_ROOT_DIRS} marker that has a
- *    directory after it, key on that next segment (the route id) — robust to any
- *    nesting depth below it (`routes/foo/components/ui/X.tsx` -> `app-foo`).
- * 2. Otherwise return `undefined` (inherit the default `serverChunk` grouping).
+ * 1. Shared runtime (React / router / node_modules) -> `undefined` (never split).
+ * 2. A registered error/notFound fallback (`ctx.fallbackRefs`) -> `app-fallback`,
+ *    regardless of location, so the error UI is decoupled from the happy path.
+ * 3. A {@link ROUTE_ROOT_DIRS} marker with a directory after it -> key on that
+ *    next segment (the route id), robust to any nesting depth.
+ * 4. Otherwise `undefined` (inherit the default `serverChunk` grouping).
  */
 export function directoryClientChunks(
   meta: ClientChunkMeta,
+  ctx?: ClientChunkContext,
 ): string | undefined {
   if (isSharedRuntime(meta)) {
     // React / router runtime / node_modules: always shared, expected, uninteresting.
     return undefined;
   }
+  // Registered error/notFound fallbacks -> a dedicated chunk. The error UI must
+  // not co-bundle with the code it catches failures for, and removing it lets the
+  // chunk it would otherwise anchor be named after a real module, not the boundary.
+  if (
+    ctx?.fallbackRefs.size &&
+    ctx.fallbackRefs.has(hashRefKey(meta.normalizedId))
+  ) {
+    debugChunks?.("fallback %s -> app-fallback", meta.normalizedId);
+    return "app-fallback";
+  }
   const segments = meta.normalizedId.split("/").filter(Boolean);
   const dirCount = segments.length - 1; // exclude the filename
   if (dirCount >= 1) {
@@ -144,13 +175,16 @@ export function directoryClientChunks(
  * grouping.
  *
  * - `false` / `undefined` -> `undefined` (no override).
- * - `true`               -> the built-in {@link directoryClientChunks} strategy.
- * - function             -> the user's function, used verbatim.
+ * - `true`               -> the built-in {@link directoryClientChunks} strategy,
+ *   bound to the discovery-populated {@link ClientChunkContext} (fallback chunk).
+ * - function             -> the user's function, used verbatim (full control; the
+ *   fallback refinement does not apply — the consumer owns the grouping).
  */
 export function resolveClientChunks(
   option: ClientChunks | undefined,
+  ctx?: ClientChunkContext,
 ): RscClientChunksFn | undefined {
   if (!option) return undefined;
-  if (option === true) return directoryClientChunks;
+  if (option === true) return (meta) => directoryClientChunks(meta, ctx);
   return option;
 }

package/src/vite/utils/manifest-utils.ts

@@ -1,78 +1,11 @@
-/**
- * Flatten prefix tree leaf nodes into precomputed route entries.
- * Leaf nodes have no children (no nested includes), so their routes can be
- * used directly by evaluateLazyEntry() without running the handler.
- * Non-leaf nodes are skipped because they have nested lazy includes that
- * require the handler to run for discovery.
- *
- * A leaf is also skipped when its staticPrefix collides with an ancestor
- * include node's staticPrefix. That happens when a dynamic param collapses the
- * staticPrefix of nested includes onto the parent's (e.g. `/m/:id/edit` -> sp
- * `/m`): precomputing such a leaf under the collapsed prefix would let the
- * ancestor's lazy entry claim a route it cannot register (the route is behind
- * further nested lazy includes), producing a RouteNotFoundError at request time
- * (issue #506). Those routes are resolved via the handler chain instead.
- */
-export function flattenLeafEntries(
-  prefixTree: Record<string, any>,
-  routeManifest: Record<string, string>,
-  result: Array<{ staticPrefix: string; routes: Record<string, string> }>,
-): void {
-  function visit(node: any, ancestorStaticPrefixes: Set<string>): void {
-    const children = node.children || {};
-    if (
-      Object.keys(children).length === 0 &&
-      node.routes &&
-      node.routes.length > 0
-    ) {
-      // Leaf node. Skip if its staticPrefix collides with an ancestor include
-      // node's staticPrefix (dynamic-param collapse) — see doc comment above.
-      if (ancestorStaticPrefixes.has(node.staticPrefix)) {
-        return;
-      }
-      // Collect its routes from the manifest
-      const routes: Record<string, string> = {};
-      for (const name of node.routes) {
-        if (name in routeManifest) {
-          routes[name] = routeManifest[name];
-        }
-      }
-      result.push({ staticPrefix: node.staticPrefix, routes });
-    } else {
-      // Non-leaf: recurse into children, tracking this node's staticPrefix as
-      // an ancestor so a collapsed nested leaf below it is not over-claimed.
-      const nextAncestors = new Set(ancestorStaticPrefixes);
-      nextAncestors.add(node.staticPrefix);
-      for (const child of Object.values(children)) {
-        visit(child, nextAncestors);
-      }
-    }
-  }
-  for (const node of Object.values(prefixTree)) {
-    visit(node, new Set());
-  }
-}
-
-/**
- * Walk prefix tree to map each route name to its scope's staticPrefix.
- */
-export function buildRouteToStaticPrefix(
-  prefixTree: Record<string, any>,
-  result: Record<string, string>,
-): void {
-  function visit(node: any): void {
-    const sp = node.staticPrefix || "";
-    for (const name of node.routes || []) {
-      result[name] = sp;
-    }
-    for (const child of Object.values(node.children || {})) {
-      visit(child);
-    }
-  }
-  for (const node of Object.values(prefixTree)) {
-    visit(node);
-  }
-}
+// Pure prefix-tree walks live in the build layer so runtime code can consume
+// them without importing from vite/. Re-exported here for the vite-side
+// callers (discover-routers, virtual-module-codegen) that already import them
+// from this module.
+export {
+  flattenLeafEntries,
+  buildRouteToStaticPrefix,
+} from "../../build/prefix-tree-utils.js";
 
 /**
  * Wrap a value as `JSON.parse('...')` instead of a JS object literal.