@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

package/src/build/index.ts

@@ -17,16 +17,19 @@
 
 export {
   generateManifest,
+  generateManifestFull,
   generateManifestCode,
   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);
+  }
+}

package/src/build/route-trie.ts

@@ -6,7 +6,12 @@
  * shortCodes for layout pruning.
  */
 
-import { parsePattern, type ParsedSegment } from "../router/pattern-matching.js";
+import {
+  parsePattern,
+  type ParsedSegment,
+} from "../router/pattern-matching.js";
+import { buildRouteToStaticPrefix } from "./prefix-tree-utils.js";
+import type { FullManifest } from "./generate-manifest.js";
 
 // -- Trie data structures (compact keys for JSON serialization) --
 
@@ -17,10 +22,10 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names (absent params get empty string value) */
-  op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;
+  /** Ordered param names for this route (positional) */
+  pa?: string[];
   /** Trailing slash mode */
   ts?: string;
   /** Route has pre-rendered data available */
@@ -42,6 +47,8 @@ export interface TrieNode {
   s?: Record<string, TrieNode>;
   /** Param child: { n: paramName, c: child node } */
   p?: { n: string; c: TrieNode };
+  /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
+  xp?: Record<string, { n: string; c: TrieNode }>;
   /** Wildcard terminal: leaf + paramName */
   w?: TrieLeaf & { pn: string };
 }
@@ -53,6 +60,9 @@ export interface TrieNode {
  * @param routeAncestry - Map of route name to ancestry shortCodes
  * @param routeToStaticPrefix - Map of route name to its entry's staticPrefix
  * @param routeTrailingSlash - Optional map of route name to trailing slash mode
+ * @param prerenderRouteNames - Optional set of prerendered route names (sets leaf.pr)
+ * @param passthroughRouteNames - Optional set of passthrough route names (sets leaf.pt)
+ * @param responseTypeRoutes - Optional map of route name to response type (sets leaf.rt)
  */
 export function buildRouteTrie(
   routeManifest: Record<string, string>,
@@ -87,46 +97,126 @@ export function buildRouteTrie(
     });
   }
 
+  sortSuffixParams(root);
   return root;
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * Sort every node's suffix-param map (`node.xp`) by descending suffix length so
+ * the matcher tries the most specific suffix first. Overlapping suffixes like
+ * `.min.js` and `.js` must resolve by specificity, not route declaration order:
+ * a request for `/app.min.js` should match `:file.min.js`, not `:file.js`.
+ *
+ * This started as a bug — `walkTrie` iterates `node.xp` in object order and
+ * returns the first suffix the segment ends with, so the winner depended on
+ * which route was declared first. Sorting at build time fixes it allocation-free
+ * on the match hot path: the serialized production trie preserves this key order
+ * through JSON.parse, so dev (per-request rebuild) and production match
+ * identically. Array.prototype.sort is stable (ES2019+), so equal-length
+ * suffixes keep their declaration order — the router's existing tiebreak.
+ */
+function sortSuffixParams(node: TrieNode): void {
+  if (node.xp) {
+    const sorted: Record<string, { n: string; c: TrieNode }> = {};
+    for (const suffix of Object.keys(node.xp).sort(
+      (a, b) => b.length - a.length,
+    )) {
+      sorted[suffix] = node.xp[suffix];
+    }
+    node.xp = sorted;
+  }
+  if (node.s) {
+    for (const child of Object.values(node.s)) {
+      sortSuffixParams(child);
+    }
+  }
+  if (node.p) {
+    sortSuffixParams(node.p.c);
+  }
+  if (node.xp) {
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
+  }
+}
+
+/**
+ * Build a per-router trie from a generated manifest. This is the single
+ * construction path shared by build/discovery (discover-routers.ts, serialized
+ * into the production chunk) and the dev/HMR runtime rebuild
+ * (rsc/manifest-init.ts). Keeping one code path is what guarantees the dev
+ * runtime trie and the production serialized trie are byte-for-byte identical
+ * (modulo `leaf.a` ancestry, which embeds the mount index and is debug-only).
+ *
+ * Returns null when the manifest has no route ancestry (no routes), matching
+ * the prior guard at both call sites.
+ */
+export function buildPerRouterTrie(manifest: FullManifest): TrieNode | null {
+  const ancestry = manifest._routeAncestry;
+  if (!ancestry || Object.keys(ancestry).length === 0) {
+    return null;
+  }
+
+  // Seed every route to the root static prefix (""), then override with each
+  // route's include() scope prefix from the prefix tree so the trie returns the
+  // correct `sp` for lazy-entry lookup in find-match.
+  const routeToStaticPrefix: Record<string, string> = {};
+  for (const name of Object.keys(manifest.routeManifest)) {
+    routeToStaticPrefix[name] = "";
+  }
+  if (manifest.prefixTree) {
+    buildRouteToStaticPrefix(manifest.prefixTree, routeToStaticPrefix);
+  }
+
+  return buildRouteTrie(
+    manifest.routeManifest,
+    ancestry,
+    routeToStaticPrefix,
+    manifest.routeTrailingSlash,
+    manifest.prerenderRoutes ? new Set(manifest.prerenderRoutes) : undefined,
+    manifest.passthroughRoutes
+      ? new Set(manifest.passthroughRoutes)
+      : undefined,
+    manifest.responseTypeRoutes,
+  );
+}
+
+/**
+ * Insert a route into the trie. Optional params expand into two branches at
+ * registration time (skip-first, then present), so each terminal lives at the
+ * correct depth for its number of bound params and carries a branch-local
+ * `pa` listing only those names. The trie's single-slot `node.p` is reused
+ * across branches because matching ignores `node.p.n` — the leaf's `pa` is
+ * the source of truth for naming. Skip-first ordering lets `mergeLeaf`'s
+ * last-wins rule produce greedy-leftmost semantics for free at any shared
+ * terminal depth.
  */
 function insertRoute(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: Omit<TrieLeaf, "op" | "cv">,
+  leaf: Omit<TrieLeaf, "cv" | "pa">,
 ): void {
-  // Collect optional param names and constraints across all segments
-  const optionalParams: string[] = [];
+  // cv (full constraint map) is route-level and identical on every terminal,
+  // so compute it once on the shared base.
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
-    if (seg.type === "param" && seg.optional) {
-      optionalParams.push(seg.value);
-    }
-    if (seg.type === "param" && seg.constraint) {
-      constraints[seg.value] = seg.constraint;
+    if (seg.type === "param") {
+      if (seg.constraint) {
+        constraints[seg.value] = seg.constraint;
+      }
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 
-  insertSegments(node, segments, index, fullLeaf);
+  insertSegments(node, segments, index, leafBase, []);
 }
 
-/**
- * Recursively insert segments into the trie.
- * For optional params, we add a terminal at the current node (param absent)
- * AND continue inserting into the param child (param present).
- */
 /**
  * Extract ancestry map from a built trie by visiting all leaf nodes.
  * Returns { routeName: ancestryShortCodes[] } for every route in the trie.
@@ -148,6 +238,11 @@ export function extractAncestryFromTrie(
         visit(child);
       }
     }
+    if (node.xp) {
+      for (const child of Object.values(node.xp)) {
+        visit(child.c);
+      }
+    }
     if (node.p) {
       visit(node.p.c);
     }
@@ -201,15 +296,25 @@ function mergeLeaf(node: TrieNode, leaf: TrieLeaf): void {
   node.r = mergeLeaves(node.r, leaf);
 }
 
+function buildLeaf(
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
+): TrieLeaf {
+  return paramNames.length > 0
+    ? { ...leafBase, pa: [...paramNames] }
+    : { ...leafBase };
+}
+
 function insertSegments(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: TrieLeaf,
+  leafBase: Omit<TrieLeaf, "pa">,
+  paramNames: string[],
 ): void {
-  // Base case: all segments consumed, add terminal
+  // Base case: all segments consumed, add terminal with branch-local pa
   if (index >= segments.length) {
-    mergeLeaf(node, leaf);
+    mergeLeaf(node, buildLeaf(leafBase, paramNames));
     return;
   }
 
@@ -218,21 +323,47 @@ function insertSegments(
   if (segment.type === "static") {
     if (!node.s) node.s = {};
     if (!node.s[segment.value]) node.s[segment.value] = {};
-    insertSegments(node.s[segment.value], segments, index + 1, leaf);
+    insertSegments(
+      node.s[segment.value],
+      segments,
+      index + 1,
+      leafBase,
+      paramNames,
+    );
   } else if (segment.type === "param") {
     if (segment.optional) {
-      // Optional param: add terminal at current node (param absent)
-      mergeLeaf(node, leaf);
-      // AND continue with param child (param present)
+      // SKIP first: continue at the same node without binding this name.
+      // Skip-first ordering means the present-branch's TAKE overwrites any
+      // shared terminal later, giving greedy-leftmost semantics.
+      insertSegments(node, segments, index + 1, leafBase, paramNames);
     }
-    if (!node.p) {
-      node.p = { n: segment.value, c: {} };
+    if (segment.suffix) {
+      // Suffix param: keyed by suffix string (e.g., ".html")
+      if (!node.xp) node.xp = {};
+      if (!node.xp[segment.suffix]) {
+        node.xp[segment.suffix] = { n: segment.value, c: {} };
+      }
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
+    } else {
+      if (!node.p) {
+        node.p = { n: segment.value, c: {} };
+      }
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
-    insertSegments(node.p.c, segments, index + 1, leaf);
   } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments
-    const wildLeaf = { ...leaf, pn: "*" };
-    const existing = node.w ? { ...node.w } as TrieLeaf : undefined;
+    // Wildcard consumes all remaining segments. Carry any params bound before
+    // the wildcard in pa so they zip correctly against paramValues at match.
+    const wildLeaf: TrieLeaf & { pn: string } = {
+      ...buildLeaf(leafBase, paramNames),
+      pn: "*",
+    };
+    const existing = node.w ? ({ ...node.w } as TrieLeaf) : undefined;
     const merged = mergeLeaves(existing, wildLeaf);
     node.w = merged as TrieLeaf & { pn: string };
   }

package/src/build/route-types/ast-helpers.ts

@@ -0,0 +1,25 @@
+import ts from "typescript";
+
+export function getStringValue(node: ts.Node): string | null {
+  if (ts.isStringLiteral(node)) return node.text;
+  if (ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+  return null;
+}
+
+export function extractObjectStringProperties(
+  node: ts.ObjectLiteralExpression,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const prop of node.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const key = ts.isIdentifier(prop.name)
+      ? prop.name.text
+      : ts.isStringLiteral(prop.name)
+        ? prop.name.text
+        : null;
+    if (!key) continue;
+    const val = getStringValue(prop.initializer);
+    if (val !== null) result[key] = val;
+  }
+  return result;
+}

package/src/build/route-types/ast-route-extraction.ts

@@ -0,0 +1,98 @@
+import ts from "typescript";
+import {
+  getStringValue,
+  extractObjectStringProperties,
+} from "./ast-helpers.js";
+import { extractParamsFromPattern } from "./param-extraction.js";
+
+// ---------------------------------------------------------------------------
+// AST-based route extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract route definitions from source code by walking the TypeScript AST.
+ * Finds path() and path.json(), path.md(), etc. call expressions and extracts
+ * the pattern, name, params, and optional search schema from each.
+ * Skips unnamed paths (no { name: "..." }).
+ */
+export function extractRoutesFromSource(code: string): Array<{
+  name: string;
+  pattern: string;
+  params?: Record<string, string>;
+  search?: Record<string, string>;
+}> {
+  const sourceFile = ts.createSourceFile(
+    "input.tsx",
+    code,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  const routes: Array<{
+    name: string;
+    pattern: string;
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+  }> = [];
+
+  function visit(node: ts.Node) {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression;
+      const isPath =
+        (ts.isIdentifier(callee) && callee.text === "path") ||
+        (ts.isPropertyAccessExpression(callee) &&
+          ts.isIdentifier(callee.expression) &&
+          callee.expression.text === "path");
+
+      if (isPath && node.arguments.length >= 1) {
+        const route = extractRouteFromCallExpression(node);
+        if (route) routes.push(route);
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return routes;
+}
+
+function extractRouteFromCallExpression(node: ts.CallExpression): {
+  name: string;
+  pattern: string;
+  params?: Record<string, string>;
+  search?: Record<string, string>;
+} | null {
+  const patternNode = node.arguments[0];
+  const pattern = getStringValue(patternNode);
+  if (pattern === null) return null;
+
+  let name: string | null = null;
+  let search: Record<string, string> | undefined;
+
+  for (let i = 1; i < node.arguments.length; i++) {
+    const arg = node.arguments[i];
+    if (ts.isObjectLiteralExpression(arg)) {
+      for (const prop of arg.properties) {
+        if (!ts.isPropertyAssignment(prop)) continue;
+        const propName = ts.isIdentifier(prop.name) ? prop.name.text : null;
+        if (propName === "name") {
+          name = getStringValue(prop.initializer);
+        } else if (
+          propName === "search" &&
+          ts.isObjectLiteralExpression(prop.initializer)
+        ) {
+          search = extractObjectStringProperties(prop.initializer);
+        }
+      }
+    }
+  }
+
+  if (!name) return null;
+  const params = extractParamsFromPattern(pattern);
+  return {
+    name,
+    pattern,
+    ...(params ? { params } : {}),
+    ...(search && Object.keys(search).length > 0 ? { search } : {}),
+  };
+}

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

@@ -0,0 +1,113 @@
+import {
+  extractParamsFromPattern,
+  formatRouteEntry,
+} from "./param-extraction.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
+
+// ---------------------------------------------------------------------------
+// Code generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a per-module types file from extracted routes.
+ * Output has zero imports, preventing circular references.
+ */
+export function generatePerModuleTypesSource(
+  routes: Array<{
+    name: string;
+    pattern: string;
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+  }>,
+): string {
+  const valid = routes.filter(({ name }) => {
+    if (!name || /["'\\`\n\r]/.test(name)) {
+      console.warn(
+        `[rango] Skipping route with invalid name: ${JSON.stringify(name)}`,
+      );
+      return false;
+    }
+    return true;
+  });
+
+  // Deduplicate by name (first definition wins -- primary route before variants)
+  const deduped = new Map<
+    string,
+    {
+      pattern: string;
+      params?: Record<string, string>;
+      search?: Record<string, string>;
+    }
+  >();
+  for (const { name, pattern, params, search } of valid) {
+    if (deduped.has(name)) {
+      console.warn(
+        `[rango] Duplicate route name "${name}" — keeping first definition`,
+      );
+      continue;
+    }
+    deduped.set(name, { pattern, params, search });
+  }
+  const sorted = [...deduped.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const body = sorted
+    .map(([name, { pattern, params, search }]) => {
+      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+      return formatRouteEntry(key, pattern, params, search);
+    })
+    .join("\n");
+  return `// Auto-generated by @rangojs/router - do not edit\nexport const routes = {\n${body}\n} as const;\nexport type routes = typeof routes;\n`;
+}
+
+/**
+ * Generates a .ts file that augments Rango.GeneratedRouteMap
+ * with route name -> pattern mappings. This enables Handler<"routeName">
+ * without circular references since the file has no imports from the app.
+ */
+export function generateRouteTypesSource(
+  routeManifest: Record<string, string>,
+  searchSchemas?: Record<string, Record<string, string>>,
+): string {
+  const entries = Object.entries(routeManifest)
+    .filter(([name]) => !isAutoGeneratedRouteName(name))
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  const filteredSearchSchemas = searchSchemas
+    ? Object.fromEntries(
+        Object.entries(searchSchemas).filter(
+          ([name]) => !isAutoGeneratedRouteName(name),
+        ),
+      )
+    : undefined;
+
+  const objectBody = entries
+    .map(([name, pattern]) => {
+      const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
+      const params = extractParamsFromPattern(pattern);
+      const search = filteredSearchSchemas?.[name];
+      return formatRouteEntry(key, pattern, params, search);
+    })
+    .join("\n");
+
+  // The global augmentation extends an alias of `typeof NamedRoutes` rather than
+  // `Readonly<typeof NamedRoutes>`. `as const` already makes the members readonly,
+  // so the two are behaviour-identical, but `Readonly<>` is a homomorphic mapped
+  // type the compiler instantiates once per route at the augmentation site
+  // (~4 instantiations/route). An interface `extends` clause cannot name a bare
+  // `typeof` query, so the alias is what lets us drop the wrapper. Measured: ~35%
+  // fewer type instantiations on a 14k-route app; negligible (but free) on small.
+  return `// Auto-generated by @rangojs/router - do not edit
+export const NamedRoutes = {
+${objectBody}
+} as const;
+
+// Aliased so the augmentation below does not pay a homomorphic mapped-type
+// instantiation per route; \`as const\` already makes the members readonly.
+type NamedRoutesShape = typeof NamedRoutes;
+
+declare global {
+  namespace Rango {
+    interface GeneratedRouteMap extends NamedRoutesShape {}
+  }
+}
+`;
+}