@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

package/src/build/generate-manifest.ts

@@ -11,11 +11,17 @@
 import type { UrlPatterns } from "../urls.js";
 import type { AllUseItems } from "../route-types.js";
 import { extractStaticPrefix } from "../router/pattern-matching.js";
-import { RSCRouterContext, runWithPrefixes } from "../server/context.js";
+import { RangoContext, runWithPrefixes } from "../server/context.js";
 import type { EntryData, TrackedInclude } from "../server/context.js";
 import type { TrailingSlashMode } from "../types.js";
 import { createRouteHelpers } from "../route-definition.js";
 import MapRootLayout from "../server/root-layout.js";
+import { collectFallbackClientRefs } from "./collect-fallback-refs.js";
+import {
+  isIncludeProvider,
+  resolveIncludeModule,
+  type IncludeProvider,
+} from "../urls/include-provider.js";
 
 /**
  * Node in the prefix tree
@@ -45,7 +51,7 @@ export interface GeneratedManifest {
   routeTrailingSlash?: Record<string, string>;
   /** Route names using Prerender (for dev-mode Node.js delegation) */
   prerenderRoutes?: string[];
-  /** Route names with passthrough: true (handler kept in bundle for live fallback) */
+  /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
   passthroughRoutes?: string[];
   /** Route name → response type for non-RSC routes */
   responseTypeRoutes?: Record<string, string>;
@@ -57,10 +63,49 @@ export interface GeneratedManifest {
  * Build prefix tree node by running the patterns with proper context.
  * Uses a visited set to detect circular includes and prevent infinite recursion.
  */
-function buildPrefixTreeNode(
+// Merge tracked nested includes into `target`. Multiple includes can share a
+// fullPrefix (e.g. include("/", a), include("/", b)) — concat their routes and
+// Object.assign children rather than overwrite.
+async function mergeIncludeNodes(
+  target: Record<string, PrefixTreeNode>,
+  includes: TrackedInclude[],
+  buildChild: (include: TrackedInclude) => Promise<PrefixTreeNode>,
+): Promise<void> {
+  for (const include of includes) {
+    let node: PrefixTreeNode;
+    try {
+      node = await buildChild(include);
+    } catch (err) {
+      // Discovery (build-time, and the dev trie-rebuild) populates the
+      // manifest / trie / generated types for the WHOLE app. A failing async
+      // include provider here — a broken import, a module that throws at eval —
+      // must HARD-FAIL, not be swallowed: swallowing produces a green build with
+      // the entire route group silently absent from the manifest/trie/types, so
+      // CI passes, the deploy ships, and every one of that group's URLs then
+      // 404s/500s in production. On main an eager include that threw failed the
+      // build loudly; the async form must keep that contract. Rethrow with the
+      // offending prefix so the failure is actionable. (Sibling isolation
+      // belongs at PER-REQUEST runtime — see find-match.ts — not at discovery.)
+      throw new Error(
+        `[@rangojs/router] Failed to resolve include at prefix "${include.fullPrefix}" ` +
+          `during route discovery: ${(err as Error)?.message ?? String(err)}`,
+        { cause: err },
+      );
+    }
+    const existing = target[include.fullPrefix];
+    if (existing) {
+      existing.routes.push(...node.routes);
+      Object.assign(existing.children, node.children);
+    } else {
+      target[include.fullPrefix] = node;
+    }
+  }
+}
+
+async function buildPrefixTreeNode(
   urlPrefix: string,
   namePrefix: string | undefined,
-  patterns: UrlPatterns<any>,
+  patternsOrProvider: UrlPatterns<any> | IncludeProvider<any>,
   routeManifest: Record<string, string>,
   routeAncestry: Record<string, string[]>, // internal: feeds trie building, not exported
   mountIndex: number,
@@ -71,7 +116,14 @@ function buildPrefixTreeNode(
   passthroughRoutes?: string[],
   responseTypeRoutes?: Record<string, string>,
   routeSearchSchemas?: Record<string, Record<string, string>>,
-): PrefixTreeNode {
+): Promise<PrefixTreeNode> {
+  // Resolve an async include provider (`() => import("./routes")`) so its routes
+  // are walked into the build-time manifest/types/href. Runtime matching still
+  // defers the import via lazy-includes; this only runs during build/dev
+  // discovery, which is async.
+  const patterns: UrlPatterns<any> = isIncludeProvider(patternsOrProvider)
+    ? resolveIncludeModule(await patternsOrProvider(), urlPrefix)
+    : patternsOrProvider;
   if (visited.has(patterns)) {
     console.warn(
       `[@rangojs/router] Circular include detected at prefix "${urlPrefix}". Skipping.`,
@@ -85,133 +137,117 @@ function buildPrefixTreeNode(
     };
   }
   visited.add(patterns);
-  // Create context for running patterns with include tracking
-  const manifest = new Map<string, EntryData>();
-  const patternsMap = new Map<string, string>();
-  const patternsByPrefix = new Map<string, Map<string, string>>();
-  const trailingSlashMap = new Map<string, TrailingSlashMode>();
-  const searchSchemasMap = new Map<string, Record<string, string>>();
-  const trackedIncludes: TrackedInclude[] = [];
+  try {
+    // Create context for running patterns with include tracking
+    const manifest = new Map<string, EntryData>();
+    const patternsMap = new Map<string, string>();
+    const patternsByPrefix = new Map<string, Map<string, string>>();
+    const trailingSlashMap = new Map<string, TrailingSlashMode>();
+    const searchSchemasMap = new Map<string, Record<string, string>>();
+    const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
-    {
-      manifest,
-      patterns: patternsMap,
-      patternsByPrefix,
-      trailingSlash: trailingSlashMap,
-      searchSchemas: searchSchemasMap,
-      namespace: "build",
-      parent: null,
-      counters: {},
-      mountIndex,
-      trackedIncludes, // Enable nested include tracking
-    },
-    () => {
-      const helpers = createRouteHelpers();
-      // Wrap in root layout for correct parent hierarchy (matches runtime)
-      helpers.layout(MapRootLayout, () => {
-        if (urlPrefix || namePrefix) {
-          return runWithPrefixes(urlPrefix, namePrefix, () => {
-            return patterns.handler() as AllUseItems[];
-          });
-        }
-        return patterns.handler() as AllUseItems[];
-      });
-    },
-  );
+    RangoContext.run(
+      {
+        manifest,
+        patterns: patternsMap,
+        patternsByPrefix,
+        trailingSlash: trailingSlashMap,
+        searchSchemas: searchSchemasMap,
+        namespace: "build",
+        parent: null,
+        counters: {},
+        mountIndex,
+        trackedIncludes, // Enable nested include tracking
+      },
+      () => {
+        const helpers = createRouteHelpers();
+        // Wrap in root layout for correct parent hierarchy (matches runtime)
+        helpers.layout(MapRootLayout, () => {
+          if (urlPrefix || namePrefix) {
+            return runWithPrefixes(urlPrefix, namePrefix, () => {
+              return patterns.handler() as AllUseItems[];
+            });
+          }
+          return patterns.handler() as AllUseItems[];
+        });
+      },
+    );
 
-  // Collect route names defined in this include (routes have prefixes applied)
-  const routes: string[] = [];
-  for (const [name, pattern] of patternsMap.entries()) {
-    routes.push(name);
-    routeManifest[name] = pattern;
-  }
+    // Collect route names defined in this include (routes have prefixes applied)
+    const routes = [...patternsMap.keys()];
+    Object.assign(routeManifest, Object.fromEntries(patternsMap));
 
-  // Collect trailing slash config
-  if (routeTrailingSlash) {
-    for (const [name, mode] of trailingSlashMap.entries()) {
-      routeTrailingSlash[name] = mode;
+    // Collect trailing slash config
+    if (routeTrailingSlash) {
+      for (const [name, mode] of trailingSlashMap.entries()) {
+        routeTrailingSlash[name] = mode;
+      }
     }
-  }
-  if (routeSearchSchemas) {
-    for (const [name, schema] of searchSchemasMap.entries()) {
-      routeSearchSchemas[name] = schema;
+    if (routeSearchSchemas) {
+      for (const [name, schema] of searchSchemasMap.entries()) {
+        routeSearchSchemas[name] = schema;
+      }
     }
-  }
 
-  // Capture ancestry from manifest entries' parent chains
-  captureAncestry(manifest, routeAncestry);
+    // Capture ancestry from manifest entries' parent chains
+    captureAncestry(manifest, routeAncestry);
 
-  // Collect prerender route names and handler definitions from manifest entries
-  if (prerenderRoutes) {
-    for (const [name, entry] of manifest) {
-      if (entry.type === "route" && entry.isPrerender) {
-        prerenderRoutes.push(name);
-        if (prerenderDefs && entry.prerenderDef) {
-          prerenderDefs[name] = entry.prerenderDef;
-        }
-        if (
-          passthroughRoutes &&
-          entry.prerenderDef?.options?.passthrough === true
-        ) {
-          passthroughRoutes.push(name);
+    // Collect prerender route names and handler definitions from manifest entries
+    if (prerenderRoutes) {
+      for (const [name, entry] of manifest) {
+        if (entry.type === "route" && entry.isPrerender) {
+          prerenderRoutes.push(name);
+          if (prerenderDefs && entry.prerenderDef) {
+            prerenderDefs[name] = entry.prerenderDef;
+          }
+          if (passthroughRoutes && entry.isPassthrough === true) {
+            passthroughRoutes.push(name);
+          }
         }
       }
     }
-  }
 
-  // Collect response type routes from manifest entries
-  if (responseTypeRoutes) {
-    for (const [name, entry] of manifest) {
-      if (entry.type === "route" && entry.responseType) {
-        responseTypeRoutes[name] = entry.responseType;
+    // Collect response type routes from manifest entries
+    if (responseTypeRoutes) {
+      for (const [name, entry] of manifest) {
+        if (entry.type === "route" && entry.responseType) {
+          responseTypeRoutes[name] = entry.responseType;
+        }
       }
     }
-  }
-
-  // Build children from tracked nested includes.
-  // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
-  // include("/", patternsB)). Merge their routes instead of overwriting.
-  const children: Record<string, PrefixTreeNode> = {};
 
-  for (const include of trackedIncludes) {
-    const childNode = buildPrefixTreeNode(
-      include.fullPrefix,
-      include.namePrefix,
-      include.patterns as UrlPatterns<any>,
-      routeManifest,
-      routeAncestry,
-      mountIndex,
-      visited,
-      routeTrailingSlash,
-      prerenderRoutes,
-      prerenderDefs,
-      passthroughRoutes,
-      responseTypeRoutes,
-      routeSearchSchemas,
+    const children: Record<string, PrefixTreeNode> = {};
+    await mergeIncludeNodes(children, trackedIncludes, (include) =>
+      buildPrefixTreeNode(
+        include.fullPrefix,
+        include.namePrefix,
+        include.patterns as UrlPatterns<any> | IncludeProvider<any>,
+        routeManifest,
+        routeAncestry,
+        mountIndex,
+        visited,
+        routeTrailingSlash,
+        prerenderRoutes,
+        prerenderDefs,
+        passthroughRoutes,
+        responseTypeRoutes,
+        routeSearchSchemas,
+      ),
     );
 
-    const existing = children[include.fullPrefix];
-    if (existing) {
-      existing.routes.push(...childNode.routes);
-      Object.assign(existing.children, childNode.children);
-    } else {
-      children[include.fullPrefix] = childNode;
-    }
+    return {
+      staticPrefix: extractStaticPrefix(urlPrefix),
+      fullPrefix: urlPrefix,
+      namePrefix: namePrefix || undefined,
+      children,
+      routes,
+    };
+  } finally {
+    // Remove from visited so sibling branches can reuse the same patterns without
+    // false circular-include detection — and so a throwing handler (caught by the
+    // parent mergeIncludeNodes) does not leak this entry into the shared set.
+    visited.delete(patterns);
   }
-
-  // Remove from visited so sibling branches can reuse the same patterns
-  // without false circular-include detection. Only ancestors in the current
-  // recursion path should trigger the cycle guard.
-  visited.delete(patterns);
-
-  return {
-    staticPrefix: extractStaticPrefix(urlPrefix),
-    fullPrefix: urlPrefix,
-    namePrefix: namePrefix || undefined,
-    children,
-    routes,
-  };
 }
 
 /**
@@ -255,7 +291,8 @@ export interface FullManifest extends GeneratedManifest {
  * import { generateManifest } from "@rangojs/router/build";
  * import { urlpatterns } from "./urls";
  *
- * const manifest = generateManifest(urlpatterns);
+ * // Async: awaits async include() providers (`() => import("./routes")`).
+ * const manifest = await generateManifest(urlpatterns);
  * // Write to file for runtime use
  * fs.writeFileSync(
  *   "src/generated/route-manifest.json",
@@ -263,15 +300,12 @@ export interface FullManifest extends GeneratedManifest {
  * );
  * ```
  */
-export function generateManifest<TEnv>(
+export async function generateManifest<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-): GeneratedManifest {
-  const {
-    _routeAncestry: _,
-    _prerenderDefs: __,
-    ...publicManifest
-  } = generateManifestFull(urlpatterns, mountIndex);
+): Promise<GeneratedManifest> {
+  const { _routeAncestry, _prerenderDefs, ...publicManifest } =
+    await generateManifestFull(urlpatterns, mountIndex);
   return publicManifest;
 }
 
@@ -282,10 +316,21 @@ export function generateManifest<TEnv>(
  * @rangojs/router/build), manifest-init (direct import), and trie
  * building. Not intended for external use.
  */
-export function generateManifestFull<TEnv>(
+export async function generateManifestFull<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-): FullManifest {
+  options?: {
+    urlPrefix?: string;
+    /**
+     * Called once per `"use client"` component registered as an
+     * errorBoundary/notFoundBoundary fallback, with its client-reference key
+     * (`$$id`). Lets the build collect fallback module ids for dedicated
+     * chunking without exposing the otherwise-discarded EntryData tree. The
+     * EntryData map built below is local; this is the only seam that surfaces it.
+     */
+    collectClientFallbackRef?: (refKey: string) => void;
+  },
+): Promise<FullManifest> {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
   const prefixTree: Record<string, PrefixTreeNode> = {};
@@ -298,7 +343,7 @@ export function generateManifestFull<TEnv>(
   const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns: patternsMap,
@@ -310,6 +355,8 @@ export function generateManifestFull<TEnv>(
       counters: {},
       mountIndex,
       trackedIncludes, // Enable include tracking
+      // basename sets the initial URL prefix for all path() registrations
+      ...(options?.urlPrefix ? { urlPrefix: options.urlPrefix } : {}),
     },
     () => {
       const helpers = createRouteHelpers();
@@ -320,19 +367,31 @@ export function generateManifestFull<TEnv>(
     },
   );
 
-  // Collect root-level routes and trailing slash config
-  const routeTrailingSlash: Record<string, string> = {};
-  for (const [name, pattern] of patternsMap.entries()) {
-    routeManifest[name] = pattern;
-  }
-  for (const [name, mode] of trailingSlashMap.entries()) {
-    routeTrailingSlash[name] = mode;
-  }
-  const routeSearchSchemas: Record<string, Record<string, string>> = {};
-  for (const [name, schema] of searchSchemasMap.entries()) {
-    routeSearchSchemas[name] = schema;
+  // Surface the "use client" components registered as error/notFound fallbacks
+  // (route-tree errorBoundary()/notFoundBoundary() helpers, stored on EntryData).
+  // The boundary may be a handler function and/or wrap the client boundary in
+  // server providers, so walk the whole tree (see collectFallbackClientRefs).
+  if (options?.collectClientFallbackRef) {
+    const report = options.collectClientFallbackRef;
+    const collect = (boundary: unknown[] | undefined) => {
+      for (const item of boundary ?? [])
+        collectFallbackClientRefs(item, report);
+    };
+    for (const entry of manifest.values()) {
+      collect(entry.errorBoundary);
+      collect(entry.notFoundBoundary);
+    }
   }
 
+  // Collect root-level routes and trailing slash config
+  Object.assign(routeManifest, Object.fromEntries(patternsMap));
+  const routeTrailingSlash: Record<string, string> =
+    Object.fromEntries(trailingSlashMap);
+  const routeSearchSchemas: Record<
+    string,
+    Record<string, string>
+  > = Object.fromEntries(searchSchemasMap);
+
   // Capture ancestry from manifest entries' parent chains
   captureAncestry(manifest, routeAncestry);
 
@@ -347,7 +406,7 @@ export function generateManifestFull<TEnv>(
       if (entry.prerenderDef) {
         prerenderDefs[name] = entry.prerenderDef;
       }
-      if (entry.prerenderDef?.options?.passthrough === true) {
+      if (entry.isPassthrough === true) {
         passthroughRoutes.push(name);
       }
     }
@@ -356,15 +415,13 @@ export function generateManifestFull<TEnv>(
     }
   }
 
-  // Build prefix tree from tracked includes (shared visited set for cycle detection).
-  // Multiple includes can share the same fullPrefix (e.g., include("/", patternsA),
-  // include("/", patternsB)). Merge their routes instead of overwriting.
+  // Shared visited set for cycle detection across all root-level includes.
   const visited = new Set<unknown>();
-  for (const include of trackedIncludes) {
-    const node = buildPrefixTreeNode(
+  await mergeIncludeNodes(prefixTree, trackedIncludes, (include) =>
+    buildPrefixTreeNode(
       include.fullPrefix,
       include.namePrefix,
-      include.patterns as UrlPatterns<any>,
+      include.patterns as UrlPatterns<any> | IncludeProvider<any>,
       routeManifest,
       routeAncestry,
       mountIndex,
@@ -375,16 +432,8 @@ export function generateManifestFull<TEnv>(
       passthroughRoutes,
       responseTypeRoutes,
       routeSearchSchemas,
-    );
-
-    const existing = prefixTree[include.fullPrefix];
-    if (existing) {
-      existing.routes.push(...node.routes);
-      Object.assign(existing.children, node.children);
-    } else {
-      prefixTree[include.fullPrefix] = node;
-    }
-  }
+    ),
+  );
 
   return {
     prefixTree,
@@ -416,14 +465,14 @@ export function generateManifestFull<TEnv>(
  *
  * @example
  * ```typescript
- * const code = generateManifestCode(urlpatterns);
+ * const code = await generateManifestCode(urlpatterns);
  * fs.writeFileSync("src/generated/route-manifest.ts", code);
  * ```
  */
-export function generateManifestCode<TEnv>(
+export async function generateManifestCode<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
-): string {
-  const manifest = generateManifest(urlpatterns);
+): Promise<string> {
+  const manifest = await generateManifest(urlpatterns);
 
   return `/**
  * Auto-generated route manifest

package/src/build/generate-route-types.ts

@@ -24,13 +24,18 @@ export {
   extractIncludesWithDiagnostics,
 } from "./route-types/include-resolution.js";
 export {
-  extractUrlsVariableFromRouter,
+  extractUrlsFromRouter,
+  extractBasenameFromRouter,
+  type UrlsExtractionResult,
   buildCombinedRouteMapForRouterFile,
   detectUnresolvableIncludes,
   detectUnresolvableIncludesForUrlsFile,
   findNestedRouterConflict,
   formatNestedRouterConflictError,
   findRouterFiles,
+  findHostRouterFiles,
   writeCombinedRouteTypes,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "./route-types/router-processing.js";
 export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/src/build/index.ts

@@ -10,7 +10,9 @@
  * import { generateManifest } from "@rangojs/router/build";
  * import { urlpatterns } from "./urls";
  *
- * const manifest = generateManifest(urlpatterns);
+ * // Async: generateManifest awaits any async include() providers
+ * // (`() => import("./routes")`) so the split groups appear in the manifest.
+ * const manifest = await generateManifest(urlpatterns);
  * console.log(manifest.routeManifest); // { home: "/", about: "/about", ... }
  * ```
  */
@@ -22,8 +24,14 @@ export {
   type GeneratedManifest,
 } from "./generate-manifest.js";
 
-export { buildRouteTrie, type TrieNode, type TrieLeaf } from "./route-trie.js";
-
+// buildRouteTrie / buildPerRouterTrie / collectFallbackClientRefs and the
+// TrieNode/TrieLeaf types are NOT exported here: they are build-pipeline
+// internals, not public API. Their only build-time consumer (the Vite
+// discovery pass) imports them directly from source via a relative path
+// (vite/discovery/discover-routers.ts), and the runtime RSC realm likewise
+// imports route-trie.js directly (rsc/manifest-init.ts). Keeping them off the
+// public ./build surface (#569 decision 6) means consumers can't mistake them
+// for intended API. generateManifest* / route-types / hashParams stay public.
 export {
   writePerModuleRouteTypes,
   extractRoutesFromSource,

package/src/build/prefix-tree-utils.ts

@@ -0,0 +1,123 @@
+/**
+ * Pure prefix-tree walks shared by the build/discovery layer and the runtime
+ * trie builder. Kept in `build/` (not `vite/utils`) so runtime code
+ * (rsc/manifest-init via build/route-trie) can consume them without importing
+ * from the vite layer. `vite/utils/manifest-utils` re-exports them so existing
+ * vite-side imports stay unchanged.
+ */
+
+/**
+ * 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());
+  }
+}
+
+/**
+ * Build the staticPrefix -> routes lookup the runtime shortcut consumes from a
+ * flat precomputed-entry array.
+ *
+ * A staticPrefix owned by MORE THAN ONE leaf include cannot be collapsed to a
+ * single routes object: `new Map(entries.map(e => [e.staticPrefix, e.routes]))`
+ * is last-wins, so one include's routes are silently dropped and mis-assigned
+ * to whichever entry evaluates first. Two distinct includes legitimately share a
+ * staticPrefix when a dynamic param collapses their literal prefixes onto the
+ * same value (e.g. `include("/shop/:cat", ...)` and a nested
+ * `include("/shop/:brand", ...)` both extract "/shop/"). Merging them is also
+ * wrong — assigning the merged set to the first matching entry makes findMatch
+ * pick the wrong handler for routes belonging to the other include, which then
+ * fails its `Store.manifest.has(routeKey)` invariant at render (500 on a valid
+ * route, dev/prod identical).
+ *
+ * So any shared staticPrefix is OMITTED from the shortcut entirely. Those
+ * includes fall through to the handler path in evaluateLazyEntry(), which is the
+ * ground truth (identical to pre-precomputed behavior). The shortcut is purely an
+ * optimization, so dropping a prefix can only cost a handler run, never change a
+ * result.
+ */
+export function buildPrecomputedByPrefix(
+  entries: Array<{ staticPrefix: string; routes: Record<string, string> }>,
+): Map<string, Record<string, string>> {
+  const byPrefix = new Map<string, Record<string, string>>();
+  const shared = new Set<string>();
+  for (const e of entries) {
+    if (byPrefix.has(e.staticPrefix)) {
+      shared.add(e.staticPrefix);
+    } else {
+      byPrefix.set(e.staticPrefix, e.routes);
+    }
+  }
+  for (const sp of shared) {
+    byPrefix.delete(sp);
+  }
+  return byPrefix;
+}
+
+/**
+ * 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);
+  }
+}