@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.df410dd5

package/src/browser/types.ts

@@ -32,10 +32,19 @@ export type HandleData = Record<string, Record<string, unknown[]>>;
 export interface RscMetadata {
   pathname: string;
   segments: ResolvedSegment[];
+  /** Router instance ID. When this changes between navigations, the client
+   *  forces a full tree replacement (app switch via host router). */
+  routerId?: string;
   isPartial?: boolean;
   isError?: boolean;
   matched?: string[];
   diff?: string[];
+  /**
+   * All segment ids re-resolved on the server, including null-component
+   * ones excluded from `segments`/`diff`. Drives client-side handle-bucket
+   * cleanup. Superset of `diff`. See MatchResult.resolvedIds.
+   */
+  resolvedIds?: string[];
   /** Merged route params from the matched route */
   params?: Record<string, string>;
   /**
@@ -70,6 +79,8 @@ export interface RscMetadata {
    * Included when theme is enabled in router config.
    */
   initialTheme?: Theme;
+  /** URL prefix for all routes (from createRouter({ basename })). */
+  basename?: string;
   /** Whether connection warmup is enabled */
   warmupEnabled?: boolean;
   /** Server-side redirect with optional state (for partial requests) */
@@ -341,7 +352,13 @@ export type ReadonlyURLSearchParams = Omit<
 export interface RscBrowserDependencies {
   createFromFetch: <T>(
     response: Promise<Response>,
-    options?: { temporaryReferences?: any },
+    options?: {
+      temporaryReferences?: any;
+      findSourceMapURL?: (
+        filename: string,
+        environmentName: string,
+      ) => string | null;
+    },
   ) => Promise<T>;
   createFromReadableStream: <T>(stream: ReadableStream) => Promise<T>;
   encodeReply: (
@@ -403,16 +420,25 @@ export interface NavigationStore {
     segments: ResolvedSegment[],
     handleData?: HandleData,
   ): void;
-  getCachedSegments(
-    historyKey: string,
-  ):
-    | { segments: ResolvedSegment[]; stale: boolean; handleData?: HandleData }
+  getCachedSegments(historyKey: string):
+    | {
+        segments: ResolvedSegment[];
+        stale: boolean;
+        handleData?: HandleData;
+        routerId?: string;
+      }
     | undefined;
   hasHistoryCache(historyKey: string): boolean;
   updateCacheHandleData(historyKey: string, handleData: HandleData): void;
   markCacheAsStale(): void;
   markCacheAsStaleAndBroadcast(): void;
   clearHistoryCache(): void;
+  /**
+   * Clear this tab's nav + prefetch caches without broadcasting or rotating
+   * shared state. Intended for app-switch transitions that affect only this
+   * tab's session.
+   */
+  clearHistoryCacheLocal(): void;
   broadcastCacheInvalidation(): void;
 
   // Cross-tab refresh callback (set by navigation bridge)
@@ -422,6 +448,10 @@ export interface NavigationStore {
   getInterceptSourceUrl(): string | null;
   setInterceptSourceUrl(url: string | null): void;
 
+  // Router identity tracking (for cross-app navigation detection)
+  getRouterId?(): string | undefined;
+  setRouterId?(id: string): void;
+
   // UI update notifications
   onUpdate(callback: UpdateSubscriber): () => void;
   emitUpdate(update: NavigationUpdate): void;
@@ -452,6 +482,8 @@ export interface FetchPartialOptions {
   interceptSourceUrl?: string;
   /** RSC version for cache invalidation detection */
   version?: string;
+  /** Current router ID — server detects app switch and returns full response */
+  routerId?: string;
   /** If true, this is an HMR refetch - server should invalidate manifest cache */
   hmr?: boolean;
 }
@@ -520,6 +552,17 @@ export interface NavigationBridge {
   refresh(): Promise<void>;
   handlePopstate(): Promise<void>;
   registerLinkInterception(): () => void;
+  /** Current RSC version (live, reflects the latest updateVersion). */
+  getVersion(): string | undefined;
+  /** Update the RSC version (e.g. after HMR). Clears prefetch cache. */
+  updateVersion(newVersion: string): void;
+  /**
+   * Replace the active app-shell snapshot (rootLayout, basename, version)
+   * atomically. Used on cross-app navigations when the response's routerId
+   * indicates the user entered a different app. Theme, warmup, and prefetch
+   * TTL are document-lifetime and not part of the shell.
+   */
+  updateAppShell(next: import("./app-shell.js").AppShell): void;
 }
 
 /**

package/src/build/collect-fallback-refs.ts

@@ -0,0 +1,107 @@
+// Collect the `"use client"` client-reference keys reachable from an error /
+// notFound boundary registration, for routing them into the dedicated
+// `app-fallback` chunk (see vite/utils/client-chunks.ts).
+//
+// A boundary registration is not always a bare client element. The common,
+// load-bearing pattern wraps the client boundary in providers a thrown handler
+// needs (the layout that would normally supply them did not mount):
+//
+//   defaultErrorBoundary: ({ error }) => (
+//     <FallbackIntl locales={...}>
+//       <ThemedError error={error} />   // <- the real "use client" boundary
+//     </FallbackIntl>
+//   )
+//
+// So the value may be (a) a handler FUNCTION returning a tree, or (b) an element
+// tree with the client boundary nested below server wrappers. We:
+//   1. If it's a function, CALL it with synthetic props to get the returned tree.
+//      This only constructs JSX — the inner components are element `type`s, never
+//      invoked — so no hooks run. Guarded: a boundary that needs a real render
+//      context (request globals, etc.) throws and is skipped (graceful: it simply
+//      stays on the default grouping, as before).
+//   2. Walk the resulting tree and report every element whose `.type` is a
+//      plugin-rsc client reference.
+//
+// Limit: a boundary that *conditionally* renders different client components based
+// on the runtime error cannot be resolved statically — only the branch taken with
+// the synthetic error is seen. Such cases fall back to the default chunk; the
+// custom `clientChunks` function is the escape hatch.
+
+const CLIENT_REF = Symbol.for("react.client.reference");
+const MAX_DEPTH = 40;
+
+// Synthetic props covering the error-boundary (`{ error, reset }`) and notFound
+// (`{ pathname }`) handler shapes. The handler destructures what it needs.
+const SYNTHETIC_PROPS = {
+  error: new Error("rango: build-time fallback-chunk discovery"),
+  reset: () => {},
+  pathname: "/",
+  info: { componentStack: "" },
+};
+
+interface MaybeElement {
+  type?: { $$typeof?: symbol; $$id?: string };
+  props?: Record<string, unknown>;
+}
+
+function isReactNodeLike(v: unknown): boolean {
+  return (
+    Array.isArray(v) ||
+    (typeof v === "object" && v !== null && "$$typeof" in (v as object))
+  );
+}
+
+function walkElementTree(
+  node: unknown,
+  report: (refKey: string) => void,
+  depth: number,
+): void {
+  if (node == null || depth > MAX_DEPTH) return;
+  if (Array.isArray(node)) {
+    for (const child of node) walkElementTree(child, report, depth + 1);
+    return;
+  }
+  if (typeof node !== "object") return;
+
+  const el = node as MaybeElement;
+  const type = el.type;
+  if (type?.$$typeof === CLIENT_REF && typeof type.$$id === "string") {
+    // $$id is `<referenceKey>#<exportName>` in build mode — keep the referenceKey.
+    report(type.$$id.split("#")[0]);
+  }
+
+  const props = el.props;
+  if (props && typeof props === "object") {
+    // Children are always nodes; other props are followed only when they look
+    // like React nodes (slots/icons), never arbitrary data objects.
+    walkElementTree(props.children, report, depth + 1);
+    for (const key in props) {
+      if (key === "children") continue;
+      const value = props[key];
+      if (isReactNodeLike(value)) walkElementTree(value, report, depth + 1);
+    }
+  }
+}
+
+/**
+ * Report every `"use client"` client-reference key reachable from a single
+ * error/notFound boundary registration (handler function or element tree).
+ */
+export function collectFallbackClientRefs(
+  boundary: unknown,
+  report: (refKey: string) => void,
+): void {
+  try {
+    let node = boundary;
+    if (typeof node === "function") {
+      node = (node as (props: unknown) => unknown)(SYNTHETIC_PROPS);
+    }
+    walkElementTree(node, report, 0);
+  } catch {
+    // The boundary needs a real render context (request globals, hooks at the
+    // top level) or its tree has hostile getters. Its client refs can't be
+    // resolved statically — skip. It stays on the default grouping (no
+    // regression vs. not collecting), and the custom clientChunks fn is the
+    // escape hatch for such cases.
+  }
+}

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
@@ -45,7 +46,7 @@ export interface GeneratedManifest {
   routeTrailingSlash?: Record<string, string>;
   /** Route names using Prerender (for dev-mode Node.js delegation) */
   prerenderRoutes?: string[];
-  /** Route names with passthrough: true (handler kept in bundle for live fallback) */
+  /** Route names wrapped with Passthrough() (live handler for runtime fallback) */
   passthroughRoutes?: string[];
   /** Route name → response type for non-RSC routes */
   responseTypeRoutes?: Record<string, string>;
@@ -57,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,
@@ -150,10 +171,7 @@ function buildPrefixTreeNode(
         if (prerenderDefs && entry.prerenderDef) {
           prerenderDefs[name] = entry.prerenderDef;
         }
-        if (
-          passthroughRoutes &&
-          entry.prerenderDef?.options?.passthrough === true
-        ) {
+        if (passthroughRoutes && entry.isPassthrough === true) {
           passthroughRoutes.push(name);
         }
       }
@@ -169,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>,
@@ -189,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
@@ -285,6 +291,17 @@ export function generateManifest<TEnv>(
 export function generateManifestFull<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
+  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[]> = {};
@@ -298,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,
@@ -310,6 +327,8 @@ export function generateManifestFull<TEnv>(
       counters: {},
       mountIndex,
       trackedIncludes, // Enable include tracking
+      // basename sets the initial URL prefix for all path() registrations
+      ...(options?.urlPrefix ? { urlPrefix: options.urlPrefix } : {}),
     },
     () => {
       const helpers = createRouteHelpers();
@@ -320,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()) {
@@ -347,7 +382,7 @@ export function generateManifestFull<TEnv>(
       if (entry.prerenderDef) {
         prerenderDefs[name] = entry.prerenderDef;
       }
-      if (entry.prerenderDef?.options?.passthrough === true) {
+      if (entry.isPassthrough === true) {
         passthroughRoutes.push(name);
       }
     }
@@ -356,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

@@ -25,6 +25,9 @@ export {
 } from "./route-types/include-resolution.js";
 export {
   extractUrlsVariableFromRouter,
+  extractUrlsFromRouter,
+  extractBasenameFromRouter,
+  type UrlsExtractionResult,
   buildCombinedRouteMapForRouterFile,
   detectUnresolvableIncludes,
   detectUnresolvableIncludesForUrlsFile,
@@ -32,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[]>;
@@ -98,8 +99,14 @@ export function buildRouteTrie(
 }
 
 /**
- * Insert a route into the trie, handling optional params by forking
- * the insertion path (one terminal without the param, one with).
+ * 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,
@@ -107,14 +114,13 @@ function insertRoute(
   index: number,
   leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
 ): void {
-  // Collect param names, optional param names, and constraints across all segments
-  const paramNames: string[] = [];
+  // op (full optional list) and cv (full constraint map) are route-level and
+  // identical on every terminal, so compute them once on the shared base.
   const optionalParams: string[] = [];
   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);
       }
@@ -124,21 +130,15 @@ function insertRoute(
     }
   }
 
-  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 +218,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 +245,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 +265,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;