@rangojs/router 0.0.0-experimental.dfdb0387 → 0.0.0-experimental.e9c0b2f2

package/src/build/route-trie.ts

@@ -10,9 +10,24 @@ 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) --
 
+/**
+ * A response-type variant folded into a primary leaf's negotiate list. `pa` is
+ * the variant's own positional param-name array, carried so the runtime can
+ * re-key the matched params under the variant's names when it wins negotiation
+ * (the trie match extracts params under the PRIMARY leaf's pa). Omitted when the
+ * variant has no params; absent/identical pa means no re-key is needed.
+ */
+export interface NegotiateVariant {
+  routeKey: string;
+  responseType: string;
+  pa?: string[];
+}
+
 export interface TrieLeaf {
   /** Route name (e.g., "site.l1_500") */
   n: string;
@@ -20,8 +35,6 @@ 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) */
@@ -35,7 +48,7 @@ export interface TrieLeaf {
   /** Response type for non-RSC routes (json, text, image, any) */
   rt?: string;
   /** Negotiate variants: response-type routes sharing this path */
-  nv?: Array<{ routeKey: string; responseType: string }>;
+  nv?: NegotiateVariant[];
   /** RSC-first: RSC route was defined before response-type variants */
   rf?: true;
 }
@@ -60,6 +73,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>,
@@ -94,51 +110,124 @@ 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;
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
+  }
+  if (node.s) {
+    for (const child of Object.values(node.s)) {
+      sortSuffixParams(child);
+    }
+  }
+  if (node.p) {
+    sortSuffixParams(node.p.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" | "pa">,
+  leaf: Omit<TrieLeaf, "cv" | "pa">,
 ): void {
-  // Collect param names, optional param names, and constraints across all segments
-  const paramNames: string[] = [];
-  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") {
-      paramNames.push(seg.value);
-      if (seg.optional) {
-        optionalParams.push(seg.value);
-      }
       if (seg.constraint) {
         constraints[seg.value] = seg.constraint;
       }
     }
   }
 
-  const fullLeaf: TrieLeaf = {
+  const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(paramNames.length > 0 ? { pa: paramNames } : {}),
-    ...(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.
@@ -181,6 +270,19 @@ export function extractAncestryFromTrie(
  * appended to the nv (negotiate variants) array.
  * Multiple response types on the same path are supported (json + text + xml).
  */
+/**
+ * Build a negotiate-variant entry from a leaf being folded into another leaf's
+ * nv list. Carries the variant's positional param names (`pa`) so the runtime
+ * can re-key matched params under the variant's names; omitted when the variant
+ * has none (the common case where primary and variant share the same names is a
+ * no-op re-key regardless).
+ */
+function toVariant(leaf: TrieLeaf, responseType: string): NegotiateVariant {
+  return leaf.pa
+    ? { routeKey: leaf.n, responseType, pa: leaf.pa }
+    : { routeKey: leaf.n, responseType };
+}
+
 function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
   if (!existing) return leaf;
 
@@ -188,7 +290,7 @@ function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
     // Both are response-type: preserve old as variant
     const merged = leaf;
     merged.nv = existing.nv || [];
-    merged.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    merged.nv.push(toVariant(existing, existing.rt));
     return merged;
   }
   if (leaf.rt && !existing.rt) {
@@ -198,7 +300,7 @@ function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
       existing.nv = [];
       existing.rf = true;
     }
-    existing.nv.push({ routeKey: leaf.n, responseType: leaf.rt });
+    existing.nv.push(toVariant(leaf, leaf.rt));
     return existing;
   }
   if (!leaf.rt && existing.rt) {
@@ -206,7 +308,7 @@ function mergeLeaves(existing: TrieLeaf | undefined, leaf: TrieLeaf): TrieLeaf {
     // RSC was defined second (response-type was already the existing leaf)
     if (!leaf.nv) leaf.nv = [];
     if (existing.nv) leaf.nv.push(...existing.nv);
-    leaf.nv.push({ routeKey: existing.n, responseType: existing.rt });
+    leaf.nv.push(toVariant(existing, existing.rt));
     // rf intentionally not set — RSC came after response-type variants
     return leaf;
   }
@@ -218,15 +320,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;
   }
 
@@ -235,12 +347,19 @@ 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 (segment.suffix) {
       // Suffix param: keyed by suffix string (e.g., ".html")
@@ -248,16 +367,26 @@ function insertSegments(
       if (!node.xp[segment.suffix]) {
         node.xp[segment.suffix] = { n: segment.value, c: {} };
       }
-      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+      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, leaf);
+      insertSegments(node.p.c, segments, index + 1, leafBase, [
+        ...paramNames,
+        segment.value,
+      ]);
     }
   } else if (segment.type === "wildcard") {
-    // Wildcard consumes all remaining segments
-    const wildLeaf = { ...leaf, pn: "*" };
+    // 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-route-extraction.ts

@@ -15,19 +15,26 @@ import { extractParamsFromPattern } from "./param-extraction.js";
  * the pattern, name, params, and optional search schema from each.
  * Skips unnamed paths (no { name: "..." }).
  */
-export function extractRoutesFromSource(code: string): Array<{
+export function extractRoutesFromSource(
+  code: string,
+  sourceFileArg?: ts.SourceFile,
+): 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,
-  );
+  // Reuse a caller-provided SourceFile (parsed once per scan) when given;
+  // otherwise parse the block here. The walk does not mutate the tree.
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   const routes: Array<{
     name: string;
     pattern: string;

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

@@ -23,7 +23,7 @@ export function generatePerModuleTypesSource(
   const valid = routes.filter(({ name }) => {
     if (!name || /["'\\`\n\r]/.test(name)) {
       console.warn(
-        `[rsc-router] Skipping route with invalid name: ${JSON.stringify(name)}`,
+        `[rango] Skipping route with invalid name: ${JSON.stringify(name)}`,
       );
       return false;
     }
@@ -42,7 +42,7 @@ export function generatePerModuleTypesSource(
   for (const { name, pattern, params, search } of valid) {
     if (deduped.has(name)) {
       console.warn(
-        `[rsc-router] Duplicate route name "${name}" — keeping first definition`,
+        `[rango] Duplicate route name "${name}" — keeping first definition`,
       );
       continue;
     }
@@ -59,7 +59,7 @@ export function generatePerModuleTypesSource(
 }
 
 /**
- * Generates a .ts file that augments RSCRouter.GeneratedRouteMap
+ * 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.
  */
@@ -88,14 +88,25 @@ export function generateRouteTypesSource(
     })
     .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 RSCRouter {
-    interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
+  namespace Rango {
+    interface GeneratedRouteMap extends NamedRoutesShape {}
   }
 }
 `;

package/src/build/route-types/include-resolution.ts

@@ -22,6 +22,61 @@ export interface UnresolvableInclude {
   detail: string;
 }
 
+// ---------------------------------------------------------------------------
+// Per-scan memo
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-scan memo shared across the include-resolution recursion. Keys are
+ * absolute file paths; values cache the readFileSync result and the
+ * ts.SourceFile parsed from the FULL file source. A separate blockSources map
+ * caches parses of extracted sub-blocks (urls() call text), keyed by the exact
+ * block string, so the two extractors (routes + includes) for the same block
+ * share a single parse.
+ *
+ * The memo is purely a performance accelerator: same input -> same parse, so
+ * generated output is identical to the un-memoized path. A fresh memo is
+ * created per top-level scan entry, so stale file edits between scans are never
+ * served.
+ */
+export interface ScanMemo {
+  files: Map<string, string>;
+  blockSourceFiles: Map<string, ts.SourceFile>;
+}
+
+export function createScanMemo(): ScanMemo {
+  return { files: new Map(), blockSourceFiles: new Map() };
+}
+
+function parseBlock(memo: ScanMemo | undefined, block: string): ts.SourceFile {
+  if (memo) {
+    const cached = memo.blockSourceFiles.get(block);
+    if (cached) return cached;
+  }
+  const sf = ts.createSourceFile(
+    "input.tsx",
+    block,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  if (memo) memo.blockSourceFiles.set(block, sf);
+  return sf;
+}
+
+function readSourceMemoized(
+  memo: ScanMemo | undefined,
+  realPath: string,
+): string {
+  if (memo) {
+    const cached = memo.files.get(realPath);
+    if (cached !== undefined) return cached;
+  }
+  const source = readFileSync(realPath, "utf-8");
+  if (memo) memo.files.set(realPath, source);
+  return source;
+}
+
 // ---------------------------------------------------------------------------
 // AST-based include() parsing
 // ---------------------------------------------------------------------------
@@ -47,7 +102,10 @@ function extractNamePrefixFromInclude(node: ts.CallExpression): string | null {
  * Returns both resolved includes (identifier second args) and unresolvable
  * includes (factory calls, etc.) with reasons.
  */
-export function extractIncludesWithDiagnostics(code: string): {
+export function extractIncludesWithDiagnostics(
+  code: string,
+  sourceFileArg?: ts.SourceFile,
+): {
   resolved: Array<{
     pathPrefix: string;
     variableName: string;
@@ -60,13 +118,16 @@ export function extractIncludesWithDiagnostics(code: string): {
     detail: string;
   }>;
 } {
-  const sourceFile = ts.createSourceFile(
-    "input.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
+  // Reuse a caller-provided SourceFile (parsed once per scan) when given.
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   const resolved: Array<{
     pathPrefix: string;
     variableName: string;
@@ -140,7 +201,13 @@ export function resolveImportedVariable(
   code: string,
   localName: string,
 ): { specifier: string; exportedName: string } | null {
-  const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
+  // Allow an optional leading default binding before the named-import brace so
+  // a combined `import Foo, { bar } from "..."` is matched (the named members
+  // are the only part we resolve; the default binding is skipped). Without the
+  // optional `(?:[\w$]+\s*,\s*)?` segment, the `Foo, ` prefix breaks the match
+  // and a legitimate static named import surfaces as `unresolvable-import`.
+  const importRegex =
+    /import\s*(?:[\w$]+\s*,\s*)?\{([^}]+)\}\s*from\s*["']([^"']+)["']/g;
   let match;
 
   while ((match = importRegex.exec(code)) !== null) {
@@ -206,14 +273,18 @@ export function resolveImportPath(
 function extractUrlsBlockForVariable(
   code: string,
   varName: string,
+  sourceFileArg?: ts.SourceFile,
 ): string | null {
-  const sourceFile = ts.createSourceFile(
-    "input.tsx",
-    code,
-    ts.ScriptTarget.Latest,
-    true,
-    ts.ScriptKind.TSX,
-  );
+  // Reuse a caller-provided full-source SourceFile (parsed once per scan).
+  const sourceFile =
+    sourceFileArg ??
+    ts.createSourceFile(
+      "input.tsx",
+      code,
+      ts.ScriptTarget.Latest,
+      true,
+      ts.ScriptKind.TSX,
+    );
   let result: string | null = null;
 
   function visit(node: ts.Node) {
@@ -249,11 +320,15 @@ function buildRouteMapFromBlock(
   visited: Set<string>,
   searchSchemasOut?: Record<string, Record<string, string>>,
   diagnosticsOut?: UnresolvableInclude[],
+  memo?: ScanMemo,
 ): Record<string, string> {
   const routeMap: Record<string, string> = {};
 
+  // Parse the block once and share the SourceFile between both extractors.
+  const blockSourceFile = parseBlock(memo, block);
+
   // Extract local path() routes
-  const localRoutes = extractRoutesFromSource(block);
+  const localRoutes = extractRoutesFromSource(block, blockSourceFile);
   for (const { name, pattern, search } of localRoutes) {
     routeMap[name] = pattern;
     if (search && searchSchemasOut) {
@@ -262,8 +337,10 @@ function buildRouteMapFromBlock(
   }
 
   // Extract include() calls with diagnostics for unresolvable ones
-  const { resolved: includes, unresolvable } =
-    extractIncludesWithDiagnostics(block);
+  const { resolved: includes, unresolvable } = extractIncludesWithDiagnostics(
+    block,
+    blockSourceFile,
+  );
 
   if (diagnosticsOut) {
     for (const entry of unresolvable) {
@@ -298,12 +375,17 @@ function buildRouteMapFromBlock(
         imported.exportedName,
         visited,
         diagnosticsOut,
+        undefined,
+        memo,
       );
     } else {
-      // Check if variable exists as a same-file urls() definition
+      // Check if variable exists as a same-file urls() definition. Share the
+      // full-source SourceFile parse via the memo (block === fullSource hits the
+      // same cache entry already used above).
       const sameFileBlock = extractUrlsBlockForVariable(
         fullSource,
         variableName,
+        parseBlock(memo, fullSource),
       );
       if (!sameFileBlock) {
         if (diagnosticsOut) {
@@ -322,6 +404,8 @@ function buildRouteMapFromBlock(
         variableName,
         visited,
         diagnosticsOut,
+        undefined,
+        memo,
       );
     }
 
@@ -361,6 +445,9 @@ function buildRouteMapFromBlock(
  * @param inlineBlock - Optional pre-extracted code block (e.g. from an inline
  *   builder function). When provided, variableName is ignored and the block
  *   is parsed directly for path()/include() calls.
+ * @param memo - Per-scan readFileSync/parse memo. A fresh one is created at the
+ *   top-level entry and threaded through the recursion so each file is read and
+ *   parsed once per scan. Behavior-preserving (same input -> same output).
  */
 export function buildCombinedRouteMapWithSearch(
   filePath: string,
@@ -368,22 +455,24 @@ export function buildCombinedRouteMapWithSearch(
   visited?: Set<string>,
   diagnosticsOut?: UnresolvableInclude[],
   inlineBlock?: string,
+  memo?: ScanMemo,
 ): {
   routes: Record<string, string>;
   searchSchemas: Record<string, Record<string, string>>;
 } {
   visited = visited ?? new Set();
+  memo = memo ?? createScanMemo();
   const realPath = resolve(filePath);
   const key = variableName ? `${realPath}:${variableName}` : realPath;
   if (visited.has(key)) {
-    console.warn(`[rsc-router] Circular include detected, skipping: ${key}`);
+    console.warn(`[rango] Circular include detected, skipping: ${key}`);
     return { routes: {}, searchSchemas: {} };
   }
   visited.add(key);
 
   let source: string;
   try {
-    source = readFileSync(realPath, "utf-8");
+    source = readSourceMemoized(memo, realPath);
   } catch {
     return { routes: {}, searchSchemas: {} };
   }
@@ -392,7 +481,11 @@ export function buildCombinedRouteMapWithSearch(
   if (inlineBlock) {
     block = inlineBlock;
   } else if (variableName) {
-    const extracted = extractUrlsBlockForVariable(source, variableName);
+    const extracted = extractUrlsBlockForVariable(
+      source,
+      variableName,
+      parseBlock(memo, source),
+    );
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;
   } else {
@@ -407,6 +500,7 @@ export function buildCombinedRouteMapWithSearch(
     visited,
     searchSchemas,
     diagnosticsOut,
+    memo,
   );
 
   // Remove from visited so sibling branches can include the same variable

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

@@ -37,12 +37,15 @@ export function formatRouteEntry(
 ): string {
   const hasSearch = search && Object.keys(search).length > 0;
 
+  // JSON.stringify the pattern and search values so backslashes and quotes in a
+  // route pattern (e.g. a custom regex constraint) survive interpolation into
+  // both the type-level string and the runtime NamedRoutes value.
   if (!hasSearch) {
-    return `  ${key}: "${pattern}",`;
+    return `  ${key}: ${JSON.stringify(pattern)},`;
   }
 
   const searchBody = Object.entries(search!)
-    .map(([k, v]) => `${k}: "${v}"`)
+    .map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
     .join(", ");
-  return `  ${key}: { path: "${pattern}", search: { ${searchBody} } },`;
+  return `  ${key}: { path: ${JSON.stringify(pattern)}, search: { ${searchBody} } },`;
 }