@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.26

package/src/browser/types.ts

@@ -121,7 +121,7 @@ export interface NavigationState {
   /** Whether RSC data is currently streaming (initial load or navigation) */
   isStreaming: boolean;
 
-  /** Current location (updated optimistically) */
+  /** Current location */
   location: NavigationLocation;
 
   /** URL being navigated to (null when idle) */
@@ -178,7 +178,7 @@ export type ActionStateListener = (state: TrackedActionState) => void;
 
 /**
  * Cache interface for storing segments
- * Compatible with both Map and LRUCache
+ * Compatible with Map
  *
  * @internal This type is an implementation detail and may change without notice.
  */
@@ -215,7 +215,7 @@ export interface NavigationUpdate {
 /**
  * State value for navigate/Link
  * - LocationStateEntry[]: Type-safe state entries (recommended)
- * - unknown: Legacy format for backwards compatibility
+ * - unknown: Plain state format (object or getter function)
  */
 export type HistoryState =
   | import("./react/location-state-shared.js").LocationStateEntry[]
@@ -234,14 +234,22 @@ export interface NavigateOptions {
    * @example
    * ```tsx
    * // Type-safe state (recommended)
-   * const ProductState = createLocationState<{ name: string }>("product");
+   * const ProductState = createLocationState<{ name: string }>();
    * navigate("/product/123", { state: [ProductState({ name: "Widget" })] });
    *
+   * // Type-safe just-in-time state (getter called at navigation time)
+   * navigate("/product/123", {
+   *   state: [ProductState(() => ({ name: computeName() }))],
+   * });
+   *
    * // Multiple states
    * navigate("/checkout", { state: [ProductState(p), CartState(c)] });
    *
-   * // Legacy format (backwards compatible)
+   * // Plain static state
    * navigate("/product", { state: { from: "list" } });
+   *
+   * // Plain just-in-time state
+   * navigate("/product", { state: () => ({ from: window.location.pathname }) });
    * ```
    */
   state?: HistoryState;
@@ -394,35 +402,6 @@ export interface NavigationStore {
   ): () => void;
 }
 
-// ============================================================================
-// Request Controller Types
-// ============================================================================
-
-/**
- * Disposable abort controller with automatic cleanup
- */
-export interface DisposableAbortController extends Disposable {
-  controller: AbortController;
-}
-
-/**
- * Request controller for managing concurrent requests
- *
- * Separates navigation requests (aborted on new navigation) from
- * action requests (complete independently of navigation).
- */
-export interface RequestController {
-  create(): AbortController;
-  createDisposable(): DisposableAbortController;
-  /** Create a disposable controller for actions (not aborted by navigation) */
-  createActionDisposable(): DisposableAbortController;
-  /** Abort all navigation requests (not actions) */
-  abortAll(): void;
-  /** Abort all action requests (used for error handling) */
-  abortAllActions(): void;
-  remove(controller: AbortController): void;
-}
-
 // ============================================================================
 // Navigation Client Types
 // ============================================================================
@@ -480,7 +459,6 @@ export interface LinkInterceptorOptions {
  */
 export interface ServerActionBridge {
   register(): void;
-  unregister(): void;
 }
 
 /**
@@ -526,3 +504,11 @@ export interface NavigationBridgeConfig {
 
 // Re-export ResolvedSegment for convenience
 export type { ResolvedSegment };
+
+/**
+ * Token for tracking an active stream.
+ * Call end() when the stream completes.
+ */
+export interface StreamingToken {
+  end(): void;
+}

package/src/browser/validate-redirect-origin.ts

@@ -0,0 +1,29 @@
+/**
+ * Validate that a client-consumed redirect URL (from headers or Flight payload)
+ * targets the same origin as the current page. Prevents open-redirect attacks
+ * via crafted responses.
+ *
+ * @returns The canonical (normalized) URL string on success, or null if blocked.
+ */
+export function validateRedirectOrigin(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  try {
+    const target = new URL(url, currentOrigin);
+    if (target.origin !== currentOrigin) {
+      console.error(
+        `[rango] Redirect blocked: origin mismatch (${target.origin})`,
+      );
+      return null;
+    }
+    // Return pathname+search+hash for relative inputs, full href for absolute.
+    // This normalizes protocol-relative and other ambiguous forms.
+    return target.href.startsWith(currentOrigin)
+      ? target.href
+      : target.pathname + target.search + target.hash;
+  } catch {
+    console.error(`[rango] Redirect blocked: invalid URL "${url}"`);
+    return null;
+  }
+}

package/src/build/generate-manifest.ts

@@ -51,8 +51,6 @@ export interface GeneratedManifest {
   responseTypeRoutes?: Record<string, string>;
   /** Route name -> search schema descriptor for typed URL helpers */
   routeSearchSchemas?: Record<string, Record<string, string>>;
-  /** Generation timestamp */
-  generatedAt: string;
 }
 
 /**
@@ -202,6 +200,11 @@ function buildPrefixTreeNode(
     }
   }
 
+  // Remove from visited so sibling branches can reuse the same patterns
+  // without false circular-include detection. Only ancestors in the current
+  // recursion path should trigger the cycle guard.
+  visited.delete(patterns);
+
   return {
     staticPrefix: extractStaticPrefix(urlPrefix),
     fullPrefix: urlPrefix,
@@ -232,11 +235,20 @@ function captureAncestry(
 }
 
 /**
- * Generate manifest from UrlPatterns
+ * Internal manifest result including build-pipeline-only fields.
+ * Not part of the public API — use generateManifest() for the public surface.
+ */
+export interface FullManifest extends GeneratedManifest {
+  _routeAncestry: Record<string, string[]>;
+  _prerenderDefs?: Record<string, any>;
+}
+
+/**
+ * Generate manifest from UrlPatterns (public API).
  *
- * This runs all patterns (including lazy ones) at build time to extract:
- * - The complete prefix tree for short-circuit optimization
- * - The complete route manifest for href()
+ * Returns only the public GeneratedManifest fields. Internal build pipeline
+ * consumers that need _routeAncestry or _prerenderDefs should use
+ * generateManifestFull() instead.
  *
  * @example
  * ```typescript
@@ -254,10 +266,26 @@ function captureAncestry(
 export function generateManifest<TEnv>(
   urlpatterns: UrlPatterns<TEnv, any>,
   mountIndex: number = 0,
-): GeneratedManifest & {
-  _routeAncestry: Record<string, string[]>;
-  _prerenderDefs?: Record<string, any>;
-} {
+): GeneratedManifest {
+  const {
+    _routeAncestry: _,
+    _prerenderDefs: __,
+    ...publicManifest
+  } = generateManifestFull(urlpatterns, mountIndex);
+  return publicManifest;
+}
+
+/**
+ * Generate manifest with internal build-pipeline fields.
+ *
+ * Used by the Vite plugin (discover-routers via dynamic import through
+ * @rangojs/router/build), manifest-init (direct import), and trie
+ * building. Not intended for external use.
+ */
+export function generateManifestFull<TEnv>(
+  urlpatterns: UrlPatterns<TEnv, any>,
+  mountIndex: number = 0,
+): FullManifest {
   const routeManifest: Record<string, string> = {};
   const routeAncestry: Record<string, string[]> = {};
   const prefixTree: Record<string, PrefixTreeNode> = {};
@@ -376,8 +404,6 @@ export function generateManifest<TEnv>(
       Object.keys(routeSearchSchemas).length > 0
         ? routeSearchSchemas
         : undefined,
-    generatedAt: new Date().toISOString(),
-    // Internal: routeAncestry is used only for trie building, not exported
     _routeAncestry: routeAncestry,
     // Internal: prerender handler definitions for build-time getParams() access
     _prerenderDefs:
@@ -401,7 +427,6 @@ export function generateManifestCode<TEnv>(
 
   return `/**
  * Auto-generated route manifest
- * Generated at: ${manifest.generatedAt}
  *
  * DO NOT EDIT - This file is generated by @rangojs/router
  */

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

@@ -27,6 +27,10 @@ export {
   extractUrlsVariableFromRouter,
   buildCombinedRouteMapForRouterFile,
   detectUnresolvableIncludes,
+  detectUnresolvableIncludesForUrlsFile,
+  findNestedRouterConflict,
+  formatNestedRouterConflictError,
   findRouterFiles,
   writeCombinedRouteTypes,
 } from "./route-types/router-processing.js";
+export { findUrlsVariableNames } from "./route-types/per-module-writer.js";

package/src/build/index.ts

@@ -17,6 +17,7 @@
 
 export {
   generateManifest,
+  generateManifestFull,
   generateManifestCode,
   type GeneratedManifest,
 } from "./generate-manifest.js";

package/src/build/route-trie.ts

@@ -47,6 +47,8 @@ export interface TrieNode {
   s?: Record<string, TrieNode>;
   /** Param child: { n: paramName, c: child node } */
   p?: { n: string; c: TrieNode };
+  /** Suffix-param children keyed by suffix (e.g., ".html" → { n: "productId", c: ... }) */
+  xp?: Record<string, { n: string; c: TrieNode }>;
   /** Wildcard terminal: leaf + paramName */
   w?: TrieLeaf & { pn: string };
 }
@@ -158,6 +160,11 @@ export function extractAncestryFromTrie(
         visit(child);
       }
     }
+    if (node.xp) {
+      for (const child of Object.values(node.xp)) {
+        visit(child.c);
+      }
+    }
     if (node.p) {
       visit(node.p.c);
     }
@@ -235,10 +242,19 @@ function insertSegments(
       mergeLeaf(node, leaf);
       // AND continue with param child (param present)
     }
-    if (!node.p) {
-      node.p = { n: segment.value, c: {} };
+    if (segment.suffix) {
+      // Suffix param: keyed by suffix string (e.g., ".html")
+      if (!node.xp) node.xp = {};
+      if (!node.xp[segment.suffix]) {
+        node.xp[segment.suffix] = { n: segment.value, c: {} };
+      }
+      insertSegments(node.xp[segment.suffix].c, segments, index + 1, leaf);
+    } 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, leaf);
   } else if (segment.type === "wildcard") {
     // Wildcard consumes all remaining segments
     const wildLeaf = { ...leaf, pn: "*" };

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

@@ -2,6 +2,7 @@ import {
   extractParamsFromPattern,
   formatRouteEntry,
 } from "./param-extraction.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
 
 // ---------------------------------------------------------------------------
 // Code generation
@@ -66,15 +67,23 @@ export function generateRouteTypesSource(
   routeManifest: Record<string, string>,
   searchSchemas?: Record<string, Record<string, string>>,
 ): string {
-  const entries = Object.entries(routeManifest).sort(([a], [b]) =>
-    a.localeCompare(b),
-  );
+  const entries = Object.entries(routeManifest)
+    .filter(([name]) => !isAutoGeneratedRouteName(name))
+    .sort(([a], [b]) => a.localeCompare(b));
+
+  const filteredSearchSchemas = searchSchemas
+    ? Object.fromEntries(
+        Object.entries(searchSchemas).filter(
+          ([name]) => !isAutoGeneratedRouteName(name),
+        ),
+      )
+    : undefined;
 
   const objectBody = entries
     .map(([name, pattern]) => {
       const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : `"${name}"`;
       const params = extractParamsFromPattern(pattern);
-      const search = searchSchemas?.[name];
+      const search = filteredSearchSchemas?.[name];
       return formatRouteEntry(key, pattern, params, search);
     })
     .join("\n");

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

@@ -325,6 +325,13 @@ function buildRouteMapFromBlock(
       );
     }
 
+    // Includes without a name keep their child names private to the mounted
+    // module. They remain active at runtime via an internal scope prefix, but
+    // they are intentionally omitted from generated public route maps.
+    if (namePrefix === null) {
+      continue;
+    }
+
     // Apply prefixes
     for (const [name, pattern] of Object.entries(childResult.routes)) {
       const prefixedName = namePrefix ? `${namePrefix}.${name}` : name;
@@ -394,5 +401,11 @@ export function buildCombinedRouteMapWithSearch(
     searchSchemas,
     diagnosticsOut,
   );
+
+  // Remove from visited so sibling branches can include the same variable
+  // without false circular-include detection. Only ancestors in the current
+  // recursion path should trigger the cycle guard.
+  visited.delete(key);
+
   return { routes, searchSchemas };
 }

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

@@ -26,7 +26,7 @@ export function writePerModuleRouteTypes(
  * Find all variable names assigned to urls() calls in source code.
  * e.g. `export const patterns = urls(...)` -> ["patterns"]
  */
-function findUrlsVariableNames(code: string): string[] {
+export function findUrlsVariableNames(code: string): string[] {
   const sourceFile = ts.createSourceFile(
     "input.tsx",
     code,
@@ -97,9 +97,21 @@ export function writePerModuleRouteTypesForFile(filePath: string): void {
       routes = extractRoutesFromSource(source);
     }
 
-    if (routes.length === 0) return;
-
     const genPath = filePath.replace(/\.(tsx?)$/, ".gen.ts");
+
+    // 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([]));
+        console.log(
+          `[rsc-router] Generated route types (placeholder) -> ${genPath}`,
+        );
+      }
+      return;
+    }
+
     const genSource = generatePerModuleTypesSource(routes);
     const existing = existsSync(genPath)
       ? readFileSync(genPath, "utf-8")

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

@@ -1,15 +1,146 @@
-import { readFileSync, writeFileSync, existsSync, unlinkSync } from "node:fs";
-import { join, dirname, resolve, basename as pathBasename } from "node:path";
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  unlinkSync,
+  readdirSync,
+} from "node:fs";
+import {
+  join,
+  dirname,
+  resolve,
+  sep,
+  basename as pathBasename,
+} from "node:path";
 import ts from "typescript";
 import { generateRouteTypesSource } from "./codegen.js";
 import type { ScanFilter } from "./scan-filter.js";
-import { findTsFiles } from "./scan-filter.js";
 import {
   resolveImportedVariable,
   resolveImportPath,
   buildCombinedRouteMapWithSearch,
   type UnresolvableInclude,
 } from "./include-resolution.js";
+import { findUrlsVariableNames } from "./per-module-writer.js";
+import { isAutoGeneratedRouteName } from "../../route-name.js";
+
+function countPublicRouteEntries(source: string): number {
+  const matches =
+    source.matchAll(/^\s+(?:"([^"]+)"|([a-zA-Z_$][^:]*)):\s*["{]/gm) ?? [];
+  let count = 0;
+  for (const match of matches) {
+    const routeName = match[1] || match[2];
+    if (routeName && !isAutoGeneratedRouteName(routeName.trim())) {
+      count++;
+    }
+  }
+  return count;
+}
+
+const ROUTER_CALL_PATTERN = /\bcreateRouter\s*[<(]/;
+
+function isRoutableSourceFile(name: string): boolean {
+  return (
+    (name.endsWith(".ts") ||
+      name.endsWith(".tsx") ||
+      name.endsWith(".js") ||
+      name.endsWith(".jsx")) &&
+    !name.includes(".gen.")
+  );
+}
+
+function findRouterFilesRecursive(
+  dir: string,
+  filter: ScanFilter | undefined,
+  results: string[],
+): void {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    console.warn(
+      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+    );
+    return;
+  }
+
+  const childDirs: string[] = [];
+  const routerFilesInDir: string[] = [];
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      childDirs.push(fullPath);
+      continue;
+    }
+
+    if (!isRoutableSourceFile(entry.name)) continue;
+    if (filter && !filter(fullPath)) continue;
+
+    try {
+      const source = readFileSync(fullPath, "utf-8");
+      if (ROUTER_CALL_PATTERN.test(source)) {
+        routerFilesInDir.push(fullPath);
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  // A directory that contains a router file is treated as a router root.
+  // Once found, deeper directories are skipped to avoid redundant scans.
+  if (routerFilesInDir.length > 0) {
+    results.push(...routerFilesInDir);
+    return;
+  }
+
+  for (const childDir of childDirs) {
+    findRouterFilesRecursive(childDir, filter, results);
+  }
+}
+
+export function findNestedRouterConflict(
+  routerFiles: string[],
+): { ancestor: string; nested: string } | null {
+  const routerDirs = [
+    ...new Set(routerFiles.map((filePath) => dirname(resolve(filePath)))),
+  ].sort((a, b) => a.length - b.length);
+
+  for (let i = 0; i < routerDirs.length; i++) {
+    const ancestorDir = routerDirs[i];
+    const prefix = ancestorDir.endsWith(sep)
+      ? ancestorDir
+      : `${ancestorDir}${sep}`;
+    for (let j = i + 1; j < routerDirs.length; j++) {
+      const nestedDir = routerDirs[j];
+      if (!nestedDir.startsWith(prefix)) continue;
+      const ancestorFile = routerFiles.find(
+        (filePath) => dirname(resolve(filePath)) === ancestorDir,
+      );
+      const nestedFile = routerFiles.find(
+        (filePath) => dirname(resolve(filePath)) === nestedDir,
+      );
+      if (ancestorFile && nestedFile) {
+        return { ancestor: ancestorFile, nested: nestedFile };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function formatNestedRouterConflictError(
+  conflict: { ancestor: string; nested: string },
+  prefix = "[rsc-router]",
+): string {
+  return (
+    `${prefix} Nested router roots are not supported.\n` +
+    `Router root: ${conflict.ancestor}\n` +
+    `Nested router: ${conflict.nested}\n` +
+    `Move the nested router into a sibling directory or configure it as a separate app root.`
+  );
+}
 
 // ---------------------------------------------------------------------------
 // Router file URL extraction
@@ -184,6 +315,33 @@ export function detectUnresolvableIncludes(
   return diagnostics;
 }
 
+/**
+ * Walk the include tree for a standalone urls() module file and detect
+ * all unresolvable includes. Mirrors detectUnresolvableIncludes() but
+ * operates on urls() variable declarations instead of going through
+ * createRouter().
+ */
+export function detectUnresolvableIncludesForUrlsFile(
+  filePath: string,
+): UnresolvableInclude[] {
+  const realPath = resolve(filePath);
+  let source: string;
+  try {
+    source = readFileSync(realPath, "utf-8");
+  } catch {
+    return [];
+  }
+
+  const varNames = findUrlsVariableNames(source);
+  if (varNames.length === 0) return [];
+
+  const diagnostics: UnresolvableInclude[] = [];
+  for (const varName of varNames) {
+    buildCombinedRouteMapWithSearch(realPath, varName, new Set(), diagnostics);
+  }
+  return diagnostics;
+}
+
 // ---------------------------------------------------------------------------
 // Per-router named-routes.gen.ts writer
 // ---------------------------------------------------------------------------
@@ -193,19 +351,8 @@ export function detectUnresolvableIncludes(
  * Call once at startup; the result can be reused on subsequent watcher triggers.
  */
 export function findRouterFiles(root: string, filter?: ScanFilter): string[] {
-  const files = findTsFiles(root, filter);
   const result: string[] = [];
-  for (const filePath of files) {
-    if (filePath.includes(".gen.")) continue;
-    try {
-      const source = readFileSync(filePath, "utf-8");
-      if (/\bcreateRouter\s*[<(]/.test(source)) {
-        result.push(filePath);
-      }
-    } catch {
-      continue;
-    }
-  }
+  findRouterFilesRecursive(root, filter, result);
   return result;
 }
 
@@ -234,6 +381,11 @@ export function writeCombinedRouteTypes(
   const routerFilePaths = knownRouterFiles ?? findRouterFiles(root);
   if (routerFilePaths.length === 0) return;
 
+  const nestedRouterConflict = findNestedRouterConflict(routerFilePaths);
+  if (nestedRouterConflict) {
+    throw new Error(formatNestedRouterConflictError(nestedRouterConflict));
+  }
+
   for (const routerFilePath of routerFilePaths) {
     let routerSource: string;
     try {
@@ -300,10 +452,10 @@ export function writeCombinedRouteTypes(
       // or other dynamic code. During HMR (file watcher), always write so
       // newly added routes appear immediately.
       if (opts?.preserveIfLarger && existing) {
-        const existingCount = (
-          existing.match(/^\s+["a-zA-Z_$][^:]*:\s*["{]/gm) || []
+        const existingCount = countPublicRouteEntries(existing);
+        const newCount = Object.keys(result.routes).filter(
+          (name) => !isAutoGeneratedRouteName(name),
         ).length;
-        const newCount = Object.keys(result.routes).length;
         if (existingCount > newCount) {
           continue;
         }

package/src/build/runtime-discovery.ts

@@ -4,6 +4,7 @@ import {
   generateRouteTypesSource,
   buildCombinedRouteMapForRouterFile,
 } from "./generate-route-types.ts";
+import { isAutoGeneratedRouteName } from "../route-name.js";
 
 export interface RuntimeDiscoveryOptions {
   /** Project root directory (where package.json / node_modules live). */
@@ -140,7 +141,18 @@ export async function discoverAndWriteRouteTypes(
       const manifest = generateManifest(router.urlpatterns, routerMountIndex);
       routerMountIndex++;
 
-      const routeManifest: Record<string, string> = manifest.routeManifest;
+      // Filter out auto-generated route names that the runtime creates for
+      // unnamed routes (path() with no name option). These get names like
+      // "$path__health" at root level or "docs.$path__health" under include().
+      // Match the Vite discovery writer's predicate: any name starting with "$"
+      // is internal. For prefixed names, check each dot-separated segment.
+      const rawManifest: Record<string, string> = manifest.routeManifest;
+      const routeManifest: Record<string, string> = {};
+      for (const [name, pattern] of Object.entries(rawManifest)) {
+        if (!isAutoGeneratedRouteName(name)) {
+          routeManifest[name] = pattern;
+        }
+      }
       let routeSearchSchemas:
         | Record<string, Record<string, string>>
         | undefined = manifest.routeSearchSchemas;

package/src/cache/background-task.ts

@@ -0,0 +1,34 @@
+/**
+ * Background Task Runner
+ *
+ * Unified helper for scheduling async work via waitUntil.
+ * When waitUntil is unavailable, falls back to blocking or skipping.
+ */
+
+interface WaitUntilHost {
+  waitUntil?: (fn: () => Promise<void>) => void;
+}
+
+/**
+ * Schedule an async task in the background via waitUntil.
+ *
+ * @param host - Object with optional waitUntil (request context or similar)
+ * @param task - Async function to execute
+ * @param blockWhenNoWaitUntil - If true, awaits the task when waitUntil is
+ *   unavailable (e.g., Node.js dev server). If false (default), the task
+ *   is silently skipped when waitUntil is unavailable.
+ * @returns A promise when blocking fallback is used, void otherwise.
+ */
+export function runBackground(
+  host: WaitUntilHost | null | undefined,
+  task: () => Promise<void>,
+  blockWhenNoWaitUntil = false,
+): Promise<void> | void {
+  if (host?.waitUntil) {
+    host.waitUntil(task);
+    return;
+  }
+  if (blockWhenNoWaitUntil) {
+    return task();
+  }
+}