@rangojs/router 0.0.0-experimental.32 → 0.0.0-experimental.3232cd17

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

@@ -10,6 +10,8 @@ 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) --
 
@@ -20,8 +22,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) */
@@ -60,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>,
@@ -94,51 +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" | "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.
@@ -218,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;
   }
 
@@ -235,12 +323,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 +343,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/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.
  */
@@ -94,7 +94,7 @@ ${objectBody}
 } as const;
 
 declare global {
-  namespace RSCRouter {
+  namespace Rango {
     interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
   }
 }

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

@@ -357,12 +357,17 @@ function buildRouteMapFromBlock(
 /**
  * Build route map and search schemas together.
  * Internal helper used by the include resolution path.
+ *
+ * @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.
  */
 export function buildCombinedRouteMapWithSearch(
   filePath: string,
   variableName?: string,
   visited?: Set<string>,
   diagnosticsOut?: UnresolvableInclude[],
+  inlineBlock?: string,
 ): {
   routes: Record<string, string>;
   searchSchemas: Record<string, Record<string, string>>;
@@ -371,7 +376,7 @@ export function buildCombinedRouteMapWithSearch(
   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);
@@ -384,7 +389,9 @@ export function buildCombinedRouteMapWithSearch(
   }
 
   let block: string;
-  if (variableName) {
+  if (inlineBlock) {
+    block = inlineBlock;
+  } else if (variableName) {
     const extracted = extractUrlsBlockForVariable(source, variableName);
     if (!extracted) return { routes: {}, searchSchemas: {} };
     block = extracted;

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} } },`;
 }

package/src/build/route-types/per-module-writer.ts

@@ -97,7 +97,10 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       routes = extractRoutesFromSource(source);
     }
 
-    const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+    // Match .ts/.tsx/.js/.jsx (same as router-processing.ts / router-transform.ts).
+    // Without the jsx? branch a .jsx/.js source produced genPath === filePath,
+    // overwriting the source file instead of writing a sibling .gen.ts.
+    const genPath = filePath.replace(/\.(tsx?|jsx?)$/, ".gen.ts");
 
     // When a urls() variable was found but static resolution yields zero
     // routes, write an empty placeholder so generated imports stay
@@ -106,7 +109,7 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       if (varNames.length > 0 && !existsSync(genPath)) {
         writeFileSync(genPath, generatePerModuleTypesSource([]));
         console.log(
-          `[rsc-router] Generated route types (placeholder) -> ${genPath}`,
+          `[rango] Generated route types (placeholder) -> ${genPath}`,
         );
       }
       return;
@@ -118,11 +121,11 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       : null;
     if (existing !== genSource) {
       writeFileSync(genPath, genSource);
-      console.log(`[rsc-router] Generated route types -> ${genPath}`);
+      console.log(`[rango] Generated route types -> ${genPath}`);
     }
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
+      `[rango] Failed to generate route types for ${filePath}: ${(err as Error).message}`,
     );
   }
 }