@rangojs/router 0.24.3 → 0.25.0

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

@@ -62,70 +62,107 @@ export function findUrlsVariableNames(code: string): string[] {
   return names;
 }
 
+export interface PerModuleRouteTypesPlan {
+  genPath: string;
+  /** A urls()/clientUrls() variable resolved to zero routes; content is empty. */
+  isPlaceholder: boolean;
+  content: string;
+}
+
 /**
- * Generate per-module route types for a single url module file.
- * Follows include() calls recursively to produce the full route tree.
- * No-ops if the file doesn't contain `urls(`/`clientUrls(` or has no named
- * routes.
+ * Pure half of the per-module writer: reads sources, never writes. Returns
+ * null when the file has no `urls(`/`clientUrls(` or no named routes and no
+ * urls() variable. Throws on failure.
  */
-export function writePerModuleRouteTypesForFile(filePath: string): void {
-  try {
-    const source = readFileSync(filePath, "utf-8");
-    if (!source.includes("urls(") && !source.includes("clientUrls(")) return;
+export function planPerModuleRouteTypesForFile(
+  filePath: string,
+): PerModuleRouteTypesPlan | null {
+  const source = readFileSync(filePath, "utf-8");
+  if (!source.includes("urls(") && !source.includes("clientUrls(")) return null;
 
-    const varNames = findUrlsVariableNames(source);
+  const varNames = findUrlsVariableNames(source);
 
-    type Route = {
-      name: string;
-      pattern: string;
-      params?: Record<string, string>;
-      search?: Record<string, string>;
-    };
-    let routes: Route[];
+  type Route = {
+    name: string;
+    pattern: string;
+    params?: Record<string, string>;
+    search?: Record<string, string>;
+  };
+  let routes: Route[];
 
-    if (varNames.length > 0) {
-      // Follow includes recursively via the combined route map builder.
-      // The visited set in buildCombinedRouteMapWithSearch prevents infinite loops.
-      // Share one per-file scan memo across all urls() variables so a shared
-      // include target is read+parsed once for this file, not once per variable.
-      routes = [];
-      const memo = createScanMemo();
-      for (const varName of varNames) {
-        const { routes: routeMap, searchSchemas } =
-          buildCombinedRouteMapWithSearch(
-            filePath,
-            varName,
-            undefined,
-            undefined,
-            undefined,
-            memo,
-          );
-        for (const [name, pattern] of Object.entries(routeMap)) {
-          const params = extractParamsFromPattern(pattern);
-          routes.push({
-            name,
-            pattern,
-            ...(params ? { params } : {}),
-            ...(searchSchemas[name] ? { search: searchSchemas[name] } : {}),
-          });
-        }
+  if (varNames.length > 0) {
+    // Follow includes recursively via the combined route map builder.
+    // The visited set in buildCombinedRouteMapWithSearch prevents infinite loops.
+    // Share one per-file scan memo across all urls() variables so a shared
+    // include target is read+parsed once for this file, not once per variable.
+    routes = [];
+    const memo = createScanMemo();
+    for (const varName of varNames) {
+      const { routes: routeMap, searchSchemas } =
+        buildCombinedRouteMapWithSearch(
+          filePath,
+          varName,
+          undefined,
+          undefined,
+          undefined,
+          memo,
+        );
+      for (const [name, pattern] of Object.entries(routeMap)) {
+        const params = extractParamsFromPattern(pattern);
+        routes.push({
+          name,
+          pattern,
+          ...(params ? { params } : {}),
+          ...(searchSchemas[name] ? { search: searchSchemas[name] } : {}),
+        });
       }
-    } else {
-      // Fallback: no urls() variable found, extract path() calls directly
-      routes = extractRoutesFromSource(source);
     }
+  } else {
+    // Fallback: no urls() variable found, extract path() calls directly
+    routes = extractRoutesFromSource(source);
+  }
+
+  // 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");
 
-    // 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");
+  if (routes.length === 0) {
+    if (varNames.length === 0) return null;
+    return {
+      genPath,
+      isPlaceholder: true,
+      content: generatePerModuleTypesSource([]),
+    };
+  }
+  return {
+    genPath,
+    isPlaceholder: false,
+    content: generatePerModuleTypesSource(routes),
+  };
+}
+
+/**
+ * Generate per-module route types for a single url module file.
+ * Follows include() calls recursively to produce the full route tree.
+ * No-ops if the file doesn't contain `urls(`/`clientUrls(` or has no named
+ * routes.
+ */
+export function writePerModuleRouteTypesForFile(filePath: string): void {
+  try {
+    const plan = planPerModuleRouteTypesForFile(filePath);
+    if (!plan) return;
+    const { genPath, isPlaceholder, content } = plan;
+    const exists = existsSync(genPath);
 
-    // When a urls() variable was found but static resolution yields zero
-    // routes, write an empty placeholder so generated imports stay
-    // resolvable until runtime discovery fills them in.
-    if (routes.length === 0) {
-      if (varNames.length > 0 && !existsSync(genPath)) {
-        writeFileSync(genPath, generatePerModuleTypesSource([]));
+    // A urls() variable whose static resolution yields zero routes gets an
+    // empty placeholder so an import of the sibling .gen.ts resolves. Nothing
+    // fills it in later: runtime discovery writes only *.named-routes.gen.ts
+    // (runtime-discovery.ts), so it stays `routes = {}` until a static run can
+    // resolve the module's includes and overwrites it.
+    if (isPlaceholder) {
+      if (!exists) {
+        writeFileSync(genPath, content);
         console.log(
           `[rango] Generated route types (placeholder) -> ${genPath}`,
         );
@@ -133,12 +170,8 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       return;
     }
 
-    const genSource = generatePerModuleTypesSource(routes);
-    const existing = existsSync(genPath)
-      ? readFileSync(genPath, "utf-8")
-      : null;
-    if (existing !== genSource) {
-      writeFileSync(genPath, genSource);
+    if (!exists || readFileSync(genPath, "utf-8") !== content) {
+      writeFileSync(genPath, content);
       console.log(`[rango] Generated route types -> ${genPath}`);
     }
   } catch (err) {

package/src/cache/cache-runtime.ts

@@ -508,6 +508,15 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           if (ctx._routeName) {
             keyArgs.push(ctx._routeName);
           }
+          // A layout's / parallel's / their loader's ctx resolves dot names
+          // in its own module (withReverseScope), so one route's segments
+          // can reverse the same name differently.
+          const scope = ctx._reverseScope;
+          if (scope) {
+            keyArgs.push(
+              `reverse-scope:${scope.prefix ?? ""}:${scope.rootScoped}`,
+            );
+          }
           keyArgs.push(ctx.pathname, ctx.params);
           if (ctx._responseType) {
             keyArgs.push(ctx._responseType);

package/src/cache/cache-scope.ts

@@ -24,6 +24,7 @@ import {
   runInSegmentTagScope,
 } from "./cache-tag.js";
 import { reportCacheError } from "./cache-error.js";
+import { isInterceptSegment } from "../browser/intercept-utils.js";
 import {
   predatesInvalidation,
   type ExecutionStart,
@@ -373,7 +374,7 @@ export class CacheScope {
       const next = id.charCodeAt(boundary.length);
       return !(next >= 48 && next <= 57);
     }
-    return namespace?.startsWith("intercept:") === true;
+    return isInterceptSegment({ namespace });
   }
 
   /**

package/src/cache/cf/cf-cache-store.ts

@@ -422,6 +422,7 @@ function shellHeadToEntry(head: ShellFrameHead): ShellEntryHead {
     reactVersion: head.rv,
     buildVersion: head.bv,
     initialTheme: head.i,
+    pathname: head.lp,
     docKey: head.dk,
     prunedRecords: head.pr,
     navigationOnly: head.no,
@@ -2695,6 +2696,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           t: tags,
           ta: taggedAt,
           i: entry.initialTheme,
+          lp: entry.pathname,
           dk: entry.docKey,
           pr: entry.prunedRecords,
           no: entry.navigationOnly,

package/src/cache/cf/cf-shell-frame.ts

@@ -47,6 +47,8 @@ export interface ShellFrameHead {
   ta?: number;
   /** ShellCacheEntry.initialTheme */
   i?: string;
+  /** ShellCacheEntry.pathname (a visitor-keyed shell's rendered location). */
+  lp?: string;
   /** ShellCacheEntry.docKey; navigation replay needs it after any round trip. */
   dk?: string;
   /** ShellCacheEntry.prunedRecords (diagnostic). */
@@ -79,6 +81,7 @@ function isShellFrameHead(value: unknown): value is ShellFrameHead {
         head.t.every((tag) => typeof tag === "string"))) &&
     (head.ta === undefined || isFiniteNumber(head.ta)) &&
     (head.i === undefined || typeof head.i === "string") &&
+    (head.lp === undefined || typeof head.lp === "string") &&
     (head.dk === undefined || typeof head.dk === "string") &&
     (head.pr === undefined || typeof head.pr === "string") &&
     (head.no === undefined || head.no === true) &&

package/src/cache/types.ts

@@ -468,6 +468,14 @@ export interface ShellCacheEntry {
    * ThemeProvider.
    */
   initialTheme?: string;
+  /**
+   * The payload pathname of a shell keyed by the visitor's URL
+   * (`rewrite(...).shell("visitor")`, visitorShellKey); absent when the
+   * capture rendered its key's own URL. The serve tail replays it as it does
+   * `initialTheme`, and the serve gate serves the entry only to a request
+   * that renders this location.
+   */
+  pathname?: string;
   /**
    * The CAPTURE DATA SNAPSHOT, in stored/serialized form: the doc segment
    * record every HIT replays the handler layer from (`docKey`) and the

package/src/cache/vercel/vercel-cache-store.ts

@@ -271,6 +271,8 @@ interface VercelShellEnvelope {
   t?: string[];
   /** initialTheme the capture render was built with (resume theme fidelity). */
   i?: string;
+  /** ShellCacheEntry.pathname (a visitor-keyed shell's rendered location). */
+  lp?: string;
   /** Capture data snapshot (ShellCacheEntry.snapshot). */
   sn: ShellSnapshotRecord[];
   /**
@@ -1158,6 +1160,7 @@ export class VercelCacheStore<
       reactVersion: env.rv,
       buildVersion: env.bv,
       initialTheme: env.i,
+      pathname: env.lp,
       snapshot: env.sn,
       docKey: env.dk,
       prunedRecords: env.pr,
@@ -1326,6 +1329,7 @@ export class VercelCacheStore<
         e: Math.min(expiresAt, now + retentionTtl * 1000),
         t: safeTags.length > 0 ? safeTags : undefined,
         i: entry.initialTheme,
+        lp: entry.pathname,
         sn: entry.snapshot,
         dk: entry.docKey,
         pr: entry.prunedRecords,
@@ -1743,7 +1747,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, bv, c, s, e, t, i, sn, dk, pr, no } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, lp, sn, dk, pr, no } = raw;
     if (typeof rv !== "string" || typeof bv !== "string") return null;
     // Document half: required unless navigationOnly (`no`), which stores
     // neither field. Tolerate a legacy navigationOnly envelope that still
@@ -1766,6 +1770,7 @@ export class VercelCacheStore<
       e,
       t: Array.isArray(t) ? (t as string[]) : undefined,
       i: typeof i === "string" ? i : undefined,
+      lp: typeof lp === "string" ? lp : undefined,
       // A non-array field reads as no records.
       sn: Array.isArray(sn) ? (sn as ShellSnapshotRecord[]) : [],
       dk: typeof dk === "string" ? dk : undefined,

package/src/client-urls/client-root.tsx

@@ -108,17 +108,21 @@ export function ClientUrlsRoot({
   definition,
   routeId,
   namePrefix = "",
+  foreign,
 }: {
   definition: ClientUrlPatterns;
   routeId: string;
   /** include() route-name prefix, injected at materialization for canonical
    *  name composition (intercept-target coordination). */
   namePrefix?: string;
+  /** The server's routes that compete with the group's for a URL
+   *  (competingPatterns in server-projection.ts). */
+  foreign?: readonly string[];
 }): ReactNode {
-  // The include() mount prefix this group renders under ("/" at root). The
-  // module trie is built from definition-LOCAL patterns; navigation strips
-  // this prefix before matching (see stripMountPrefix in navigation.ts), the
-  // same way client href()/useMount resolve include-relative URLs.
+  // The include() mount pattern this group renders under ("/" at root).
+  // Navigation matches an absolute pathname against the definition's
+  // patterns joined to it (buildClientUrlsTrie in client-urls.ts), as
+  // useReverse joins it.
   const mount = useMount();
   const [intent, setIntent] = useState<ClientUrlNavigationIntent | null>(null);
 
@@ -155,8 +159,9 @@ export function ClientUrlsRoot({
         namePrefix,
         setIntent,
         optimisticRoute ? undefined : routeId,
+        foreign,
       ),
-    [definition, mount, namePrefix, routeId, optimisticRoute],
+    [definition, mount, namePrefix, routeId, optimisticRoute, foreign],
   );
 
   // Pending entries for the destination's loaders: useLoader use()s a Promise