@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7d061845

package/src/build/generate-manifest.ts

@@ -11,11 +11,12 @@
 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";
 
 /**
  * Node in the prefix tree
@@ -57,6 +58,26 @@ 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.
  */
+// 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.
+function mergeIncludeNodes(
+  target: Record<string, PrefixTreeNode>,
+  includes: TrackedInclude[],
+  buildChild: (include: TrackedInclude) => PrefixTreeNode,
+): void {
+  for (const include of includes) {
+    const node = buildChild(include);
+    const existing = target[include.fullPrefix];
+    if (existing) {
+      existing.routes.push(...node.routes);
+      Object.assign(existing.children, node.children);
+    } else {
+      target[include.fullPrefix] = node;
+    }
+  }
+}
+
 function buildPrefixTreeNode(
   urlPrefix: string,
   namePrefix: string | undefined,
@@ -93,7 +114,7 @@ function buildPrefixTreeNode(
   const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns: patternsMap,
@@ -166,13 +187,9 @@ function buildPrefixTreeNode(
     }
   }
 
-  // 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(
+  mergeIncludeNodes(children, trackedIncludes, (include) =>
+    buildPrefixTreeNode(
       include.fullPrefix,
       include.namePrefix,
       include.patterns as UrlPatterns<any>,
@@ -186,16 +203,8 @@ function buildPrefixTreeNode(
       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;
-    }
-  }
+    ),
+  );
 
   // Remove from visited so sibling branches can reuse the same patterns
   // without false circular-include detection. Only ancestors in the current
@@ -282,7 +291,17 @@ export function generateManifest<TEnv>(
 export function generateManifestFull<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-  options?: { urlPrefix?: string },
+  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;
+  },
 ): FullManifest {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
@@ -296,7 +315,7 @@ export function generateManifestFull<TEnv>(
   const searchSchemasMap = new Map<string, Record<string, string>>();
   const trackedIncludes: TrackedInclude[] = [];
 
-  RSCRouterContext.run(
+  RangoContext.run(
     {
       manifest,
       patterns: patternsMap,
@@ -320,6 +339,22 @@ export function generateManifestFull<TEnv>(
     },
   );
 
+  // 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
   const routeTrailingSlash: Record<string, string> = {};
   for (const [name, pattern] of patternsMap.entries()) {
@@ -356,12 +391,10 @@ 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(
+  mergeIncludeNodes(prefixTree, trackedIncludes, (include) =>
+    buildPrefixTreeNode(
       include.fullPrefix,
       include.namePrefix,
       include.patterns as UrlPatterns<any>,
@@ -375,16 +408,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,

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

@@ -35,5 +35,7 @@ export {
   formatNestedRouterConflictError,
   findRouterFiles,
   writeCombinedRouteTypes,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "./route-types/router-processing.js";
 export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/src/build/index.ts

@@ -24,6 +24,8 @@ export {
 
 export { buildRouteTrie, type TrieNode, type TrieLeaf } from "./route-trie.js";
 
+export { collectFallbackClientRefs } from "./collect-fallback-refs.js";
+
 export {
   writePerModuleRouteTypes,
   extractRoutesFromSource,

package/src/build/route-trie.ts

@@ -20,7 +20,8 @@ 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) */
+  /** Optional param names declared on the route. Absent params are
+   * omitted from the matched params record (read as `undefined`). */
   op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, 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

@@ -376,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);

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

package/src/build/route-types/router-processing.ts

@@ -15,6 +15,7 @@ import {
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
 import type { ScanFilter } from "./scan-filter.js";
+import { firstCodeMatchIndex } from "./source-scan.js";
 import {
   resolveImportedVariable,
   resolveImportPath,
@@ -38,6 +39,8 @@ function countPublicRouteEntries(source: string): number {
 }
 
 const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+// Global variant for the code-region scan (firstCodeMatchIndex sets lastIndex).
+const ROUTER_CALL_PATTERN_G = /\bcreateRouter\s*[<(]/g;
 
 function isRoutableSourceFile(name: string): boolean {
   return (
@@ -61,7 +64,7 @@ function findRouterFilesRecursive(
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return;
   }
@@ -90,7 +93,17 @@ function findRouterFilesRecursive(
 
     try {
       const source = readFileSync(fullPath, "utf-8");
-      if (ROUTER_CALL_PATTERN.test(source)) {
+      // Fast path: most files contain no `createRouter(` at all, so the cheap
+      // raw regex short-circuits before the code-region scan. Only a file that
+      // mentions the token (real call OR a comment/string mention) is rescanned
+      // over code regions — allocation-free, never building a stripped copy —
+      // so a mention inside a comment or string is not mistaken for a real
+      // router file (which previously triggered a spurious "Multiple routers
+      // found" error).
+      if (
+        ROUTER_CALL_PATTERN.test(source) &&
+        firstCodeMatchIndex(source, ROUTER_CALL_PATTERN_G) >= 0
+      ) {
         routerFilesInDir.push(fullPath);
       }
     } catch {
@@ -142,7 +155,7 @@ export function findNestedRouterConflict(
 
 export function formatNestedRouterConflictError(
   conflict: { ancestor: string; nested: string },
-  prefix = "[rsc-router]",
+  prefix = "[rango]",
 ): string {
   return (
     `${prefix} Nested router roots are not supported.\n` +
@@ -339,6 +352,36 @@ function applyBasenameToRoutes(
   return { routes: prefixed, searchSchemas: result.searchSchemas };
 }
 
+// Filesystem path of the generated route-types file for a router source file.
+// Native separators — matches the self-gen-tracking Map key the watcher compares.
+export function genFileTsPath(sourceFile: string): string {
+  const base = pathBasename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
+  return join(dirname(sourceFile), `${base}.named-routes.gen.ts`);
+}
+
+// Search schemas for the gen file: prefer the runtime manifest's; when it omits
+// them (some module-runner flows) fall back to static parsing filtered to the
+// public route-name set. Returns the runtime value unchanged otherwise.
+export function resolveSearchSchemas(
+  publicRouteNames: string[],
+  runtimeSchemas: Record<string, Record<string, string>> | undefined,
+  sourceFile: string,
+): Record<string, Record<string, string>> | undefined {
+  if (runtimeSchemas && Object.keys(runtimeSchemas).length > 0) {
+    return runtimeSchemas;
+  }
+  const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
+  if (Object.keys(staticParsed.searchSchemas).length === 0) {
+    return runtimeSchemas;
+  }
+  const filtered: Record<string, Record<string, string>> = {};
+  for (const name of publicRouteNames) {
+    const schema = staticParsed.searchSchemas[name];
+    if (schema) filtered[name] = schema;
+  }
+  return Object.keys(filtered).length > 0 ? filtered : runtimeSchemas;
+}
+
 /**
  * Resolve routes and search schemas from a router source file by following the
  * variable passed to `.routes(...)` or `urls: ...` in createRouter options,
@@ -528,7 +571,10 @@ export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
 export function writeCombinedRouteTypes(
   root: string,
   knownRouterFiles?: string[],
-  opts?: { preserveIfLarger?: boolean },
+  opts?: {
+    preserveIfLarger?: boolean;
+    onWrite?: (outPath: string, content: string) => void;
+  },
 ): void {
   // Delete old combined named-routes.gen.ts if it exists (stale from older versions)
   try {
@@ -536,7 +582,7 @@ export function writeCombinedRouteTypes(
     if (existsSync(oldCombinedPath)) {
       unlinkSync(oldCombinedPath);
       console.log(
-        `[rsc-router] Removed stale combined route types: ${oldCombinedPath}`,
+        `[rango] Removed stale combined route types: ${oldCombinedPath}`,
       );
     }
   } catch {}
@@ -566,14 +612,7 @@ export function writeCombinedRouteTypes(
       if (!extractUrlsFromRouter(routerSource)) continue;
     }
 
-    const routerBasename = pathBasename(routerFilePath).replace(
-      /\.(tsx?|jsx?)$/,
-      "",
-    );
-    const outPath = join(
-      dirname(routerFilePath),
-      `${routerBasename}.named-routes.gen.ts`,
-    );
+    const outPath = genFileTsPath(routerFilePath);
     const existing = existsSync(outPath)
       ? readFileSync(outPath, "utf-8")
       : null;
@@ -584,6 +623,7 @@ export function writeCombinedRouteTypes(
     if (Object.keys(result.routes).length === 0) {
       if (!existing) {
         const emptySource = generateRouteTypesSource({});
+        opts?.onWrite?.(outPath, emptySource);
         writeFileSync(outPath, emptySource);
       }
       continue;
@@ -609,9 +649,10 @@ export function writeCombinedRouteTypes(
           continue;
         }
       }
+      opts?.onWrite?.(outPath, source);
       writeFileSync(outPath, source);
       console.log(
-        `[rsc-router] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
+        `[rango] Generated route types (${Object.keys(result.routes).length} routes) -> ${outPath}`,
       );
     }
   }

package/src/build/route-types/scan-filter.ts

@@ -54,7 +54,7 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return results;
   }

package/src/build/route-types/source-scan.ts

@@ -0,0 +1,118 @@
+// Allocation-light, linear-time source scanning for the build-time scanners.
+//
+// The router-file scanner, the HMR relevance check, and the unsupported-shape
+// warning all need to know whether a token like `createRouter(` / `createLoader(`
+// appears in REAL code versus inside a comment or string literal. Rather than
+// build a full comment/string-stripped copy of the source (which on a large
+// file allocates an O(n) string plus, naively, a per-char array), these helpers
+// run the regex over the whole source ONCE (the engine sweeps left-to-right,
+// O(n)) and classify each match's offset with a forward, O(1)-memory cursor that
+// advances monotonically across the source.
+//
+// Time: O(n) — one native regex sweep plus one forward classification pass.
+// Memory: O(1) for the boolean check; O(#matches) for the index list. No
+// stripped copy and no per-char array are ever materialized.
+//
+// Pragmatic scanner, not a full tokenizer: regex literals are not special-cased
+// (a target token inside one is implausible) and template interpolations are
+// treated as opaque string content. One intentional consequence: a token whose
+// match would only complete by treating an interleaved comment as whitespace
+// (e.g. `createRouter /* x */ (`) is not detected — real calls never interleave
+// a comment between the callee and its arguments.
+
+// JS line terminators end a `//` comment: LF, CR, LS (U+2028), PS (U+2029).
+function isLineTerminator(ch: string): boolean {
+  const c = ch.charCodeAt(0);
+  // LF, CR, LS (U+2028), PS (U+2029)
+  return c === 10 || c === 13 || c === 0x2028 || c === 0x2029;
+}
+
+/**
+ * Build a classifier that answers "is offset `q` in code (not a comment or
+ * string)?" for STRICTLY INCREASING `q`. The internal cursor only moves forward,
+ * so a full left-to-right sequence of queries costs O(n) total with O(1) memory.
+ */
+function makeCodeClassifier(code: string): (q: number) => boolean {
+  const n = code.length;
+  let i = 0; // forward cursor: everything before `i` is already classified
+  let skipStart = -1; // last detected comment/string region (cache)
+  let skipEnd = -1;
+
+  return (q: number): boolean => {
+    if (q >= skipStart && q < skipEnd) return false; // q in the cached region
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      }
+      if (end >= 0) {
+        // Comment/string region [i, end). `q >= i` here (loop condition).
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+      } else {
+        i++;
+      }
+    }
+    return true; // reached q in code mode
+  };
+}
+
+/**
+ * Index of the first match of `pattern` that occurs in code (not in a comment
+ * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
+ * regex sweep with early-exit; O(1) extra memory.
+ */
+export function firstCodeMatchIndex(code: string, pattern: RegExp): number {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+
+/**
+ * Byte offsets of every match of `pattern` that occurs in code (not in a
+ * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
+ * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
+ * time, O(#matches) memory.
+ */
+export function codeMatchIndices(code: string, pattern: RegExp): number[] {
+  const inCode = makeCodeClassifier(code);
+  const indices: number[] = [];
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}

package/src/build/runtime-discovery.ts

@@ -1,8 +1,9 @@
-import { dirname, join, basename, resolve } from "node:path";
+import { resolve } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import {
   generateRouteTypesSource,
-  buildCombinedRouteMapForRouterFile,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "./generate-route-types.ts";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
@@ -175,25 +176,13 @@ export async function discoverAndWriteRouteTypes(
         );
       }
 
-      // Search schema fallback: runtime manifest may omit search schema metadata
-      // in some module-runner flows. Fall back to static source parsing.
-      if (!routeSearchSchemas || Object.keys(routeSearchSchemas).length === 0) {
-        const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
-        if (Object.keys(staticParsed.searchSchemas).length > 0) {
-          const filtered: Record<string, Record<string, string>> = {};
-          for (const name of Object.keys(routeManifest)) {
-            const schema = staticParsed.searchSchemas[name];
-            if (schema) filtered[name] = schema;
-          }
-          if (Object.keys(filtered).length > 0) {
-            routeSearchSchemas = filtered;
-          }
-        }
-      }
+      routeSearchSchemas = resolveSearchSchemas(
+        Object.keys(routeManifest),
+        routeSearchSchemas,
+        sourceFile,
+      );
 
-      const routerDir = dirname(sourceFile);
-      const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-      const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+      const outPath = genFileTsPath(sourceFile);
 
       const source = generateRouteTypesSource(
         routeManifest,