@rangojs/router 0.0.0-experimental.12 → 0.0.0-experimental.121

package/src/route-map-builder.ts

@@ -1,115 +1,12 @@
 /**
- * Client-safe route map builder
+ * Route manifest storage and retrieval.
  *
- * Provides a fluent API for building route maps with prefixes.
- * Can be imported in client code without pulling in server dependencies.
+ * The route manifest maps route names to URL patterns. It is populated
+ * by the virtual module (which imports from .named-routes.gen.ts files)
+ * and consumed by reverse() and href() at runtime.
  *
- * @example
- * ```typescript
- * import { createRouteMap, registerRouteMap } from "rsc-router/browser";
- *
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog")
- *   .add(shopRoutes, "shop");
- *
- * registerRouteMap(routeMap.routes);
- *
- * declare global {
- *   namespace RSCRouter {
- *     interface RegisteredRoutes extends typeof routeMap.routes {}
- *   }
- * }
- * ```
- */
-
-import type { PrefixRoutePatterns } from "./reverse.js";
-
-/**
- * Route map builder interface
- *
- * Accumulates route types through the builder chain for type-safe reverse.
+ * See docs/manifests.md for the full data flow.
  */
-export interface RouteMapBuilder<TRoutes extends Record<string, string> = {}> {
-  /**
-   * Add routes without prefix
-   */
-  add<T extends Record<string, string>>(routes: T): RouteMapBuilder<TRoutes & T>;
-
-  /**
-   * Add routes with prefix (only URL patterns are prefixed, keys stay unchanged)
-   * @param routes - Route definitions to add
-   * @param prefix - URL prefix WITHOUT leading slash (e.g., "blog" not "/blog")
-   */
-  add<T extends Record<string, string>, P extends string>(
-    routes: T,
-    prefix: P
-  ): RouteMapBuilder<TRoutes & PrefixRoutePatterns<T, `/${P}`>>;
-
-  /**
-   * The accumulated route map (for typeof extraction in module augmentation)
-   */
-  readonly routes: TRoutes;
-}
-
-/**
- * Add routes to a map with optional prefix
- * Keys stay unchanged for composability - only URL patterns get prefixed.
- *
- * @param routeMap - The map to add routes to
- * @param routes - Routes to add
- * @param prefix - Optional prefix for URL paths WITHOUT leading slash (keys stay unchanged)
- */
-function addRoutes(
-  routeMap: Record<string, string>,
-  routes: Record<string, string>,
-  prefix: string = ""
-): void {
-  // Normalize prefix: remove leading slash if accidentally provided
-  const normalizedPrefix = prefix.startsWith("/") ? prefix.slice(1) : prefix;
-
-  for (const [key, pattern] of Object.entries(routes)) {
-    const prefixedPattern =
-      normalizedPrefix && pattern !== "/"
-        ? `/${normalizedPrefix}${pattern}`
-        : normalizedPrefix && pattern === "/"
-          ? `/${normalizedPrefix}`
-          : pattern;
-    // Use original key - enables reusable route modules
-    routeMap[key] = prefixedPattern;
-  }
-}
-
-/**
- * Create a new route map builder
- *
- * @returns A builder for accumulating routes with type-safe prefixes
- *
- * @example
- * ```typescript
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog");
- *
- * // Types are accumulated through the chain
- * type AppRoutes = typeof routeMap.routes;
- * ```
- */
-export function createRouteMap(): RouteMapBuilder<{}> {
-  const routeMap: Record<string, string> = {};
-
-  const builder: RouteMapBuilder<any> = {
-    add(routes: Record<string, string>, prefix?: string) {
-      addRoutes(routeMap, routes, prefix);
-      return builder;
-    },
-    get routes() {
-      return routeMap;
-    },
-  };
-
-  return builder;
-}
 
 // Singleton route map instance - populated incrementally as routes are encountered
 let globalRouteMap: Record<string, string> = {};
@@ -126,21 +23,9 @@ let cachedPrecomputedEntries: Array<{
 }> | null = null;
 
 /**
- * Register the route map globally for reverse to use at runtime
- *
- * Call this after building your route map to make it available to reverse.
+ * Register routes into the global route map.
  * Routes are merged with any existing registered routes.
- *
- * @param map - The route map to register
- *
- * @example
- * ```typescript
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog");
- *
- * registerRouteMap(routeMap.routes);
- * ```
+ * Called by createRouter() during module evaluation.
  */
 export function registerRouteMap(map: Record<string, string>): void {
   // Always merge with existing map (don't replace)
@@ -155,6 +40,7 @@ export function registerRouteMap(map: Record<string, string>): void {
  * otherwise returns the runtime-accumulated route map.
  *
  * @returns The registered route map
+ * @internal
  */
 export function getGlobalRouteMap(): Record<string, string> {
   // Cached manifest is complete (includes lazy routes), so prefer it
@@ -203,7 +89,10 @@ export function clearCachedManifest(): void {
  * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
  */
 export function setPrecomputedEntries(
-  entries: Array<{ staticPrefix: string; routes: Record<string, string> }> | null,
+  entries: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> | null,
 ): void {
   cachedPrecomputedEntries = entries;
 }
@@ -231,25 +120,57 @@ export function getRouteTrie(): typeof cachedRouteTrie {
 // precomputed entries so multi-router setups (e.g. site + admin via
 // createHostRouter()) don't see each other's routes.
 const perRouterManifestMap: Map<string, Record<string, string>> = new Map();
-const perRouterTrieMap: Map<string, import("./build/route-trie.js").TrieNode> = new Map();
+const perRouterTrieMap: Map<string, import("./build/route-trie.js").TrieNode> =
+  new Map();
 const perRouterPrecomputedEntriesMap: Map<
   string,
   Array<{ staticPrefix: string; routes: Record<string, string> }>
 > = new Map();
 
-export function setRouterManifest(routerId: string, manifest: Record<string, string>): void {
+/**
+ * Clear all cached route data (global and per-router).
+ * Called during HMR when route definitions change so the handler rebuilds
+ * the trie from the updated router.urlpatterns on the next request.
+ *
+ * The virtual module calls this before repopulating with fresh data,
+ * preventing stale entries from removed routes from accumulating.
+ */
+export function clearAllRouterData(): void {
+  globalRouteMap = {};
+  cachedManifest = null;
+  cachedPrecomputedEntries = null;
+  cachedRouteTrie = null;
+  rootScopeRoutes.clear();
+  globalSearchSchemas.clear();
+  perRouterManifestMap.clear();
+  perRouterTrieMap.clear();
+  perRouterPrecomputedEntriesMap.clear();
+}
+
+export function setRouterManifest(
+  routerId: string,
+  manifest: Record<string, string>,
+): void {
   perRouterManifestMap.set(routerId, manifest);
 }
 
-export function getRouterManifest(routerId: string): Record<string, string> | undefined {
+/** @internal */
+export function getRouterManifest(
+  routerId: string,
+): Record<string, string> | undefined {
   return perRouterManifestMap.get(routerId);
 }
 
-export function setRouterTrie(routerId: string, trie: import("./build/route-trie.js").TrieNode): void {
+export function setRouterTrie(
+  routerId: string,
+  trie: import("./build/route-trie.js").TrieNode,
+): void {
   perRouterTrieMap.set(routerId, trie);
 }
 
-export function getRouterTrie(routerId: string): import("./build/route-trie.js").TrieNode | undefined {
+export function getRouterTrie(
+  routerId: string,
+): import("./build/route-trie.js").TrieNode | undefined {
   return perRouterTrieMap.get(routerId);
 }
 
@@ -278,13 +199,20 @@ export function registerRouterManifestLoader(
 }
 
 export async function ensureRouterManifest(routerId: string): Promise<void> {
-  if (perRouterManifestMap.has(routerId)) return;
+  // Check both manifest AND trie. The virtual module's setRouterManifest()
+  // pre-sets the manifest at startup, but the per-router trie is only
+  // available from the lazy loader. Without this, the lazy loader never
+  // runs and findMatch falls back to the global merged trie — which
+  // contains routes from ALL routers and breaks multi-router setups.
+  if (perRouterManifestMap.has(routerId) && perRouterTrieMap.has(routerId))
+    return;
   const loader = routerManifestLoaders.get(routerId);
   if (loader) {
     const mod = await loader();
     if (mod.manifest) perRouterManifestMap.set(routerId, mod.manifest);
     if (mod.trie) perRouterTrieMap.set(routerId, mod.trie);
-    if (mod.precomputedEntries) perRouterPrecomputedEntriesMap.set(routerId, mod.precomputedEntries);
+    if (mod.precomputedEntries)
+      perRouterPrecomputedEntriesMap.set(routerId, mod.precomputedEntries);
     routerManifestLoaders.delete(routerId);
   }
 }
@@ -303,6 +231,34 @@ export function waitForManifestReady(): Promise<void> | null {
   return manifestReadyPromise;
 }
 
+// ============================================================================
+// Route Scope Registry
+// ============================================================================
+
+// Tracks whether each route is at root scope (no named include boundary above).
+// Used by dot-local reverse resolution to decide whether bare-name fallback
+// is allowed after scoped lookups are exhausted.
+const rootScopeRoutes: Map<string, boolean> = new Map();
+
+/**
+ * Register whether a route is at root scope.
+ * Called by path() during route evaluation.
+ */
+export function registerRouteRootScope(
+  routeName: string,
+  rootScoped: boolean,
+): void {
+  rootScopeRoutes.set(routeName, rootScoped);
+}
+
+/**
+ * Check if a route is at root scope.
+ * Returns undefined if the route has not been registered (e.g. in unit tests).
+ */
+export function isRouteRootScoped(routeName: string): boolean | undefined {
+  return rootScopeRoutes.get(routeName);
+}
+
 // ============================================================================
 // Search Schema Registry
 // ============================================================================
@@ -320,8 +276,6 @@ export function registerSearchSchema(
   globalSearchSchemas.set(routeName, schema);
 }
 
-export function getSearchSchema(
-  routeName: string,
-): SearchSchema | undefined {
+export function getSearchSchema(routeName: string): SearchSchema | undefined {
   return globalSearchSchemas.get(routeName);
 }

package/src/route-name.ts

@@ -0,0 +1,53 @@
+/**
+ * Route name utilities for filtering internal route names.
+ *
+ * Internal names stay active in the runtime manifest for matching and local
+ * reverse() resolution, but they must not leak into public APIs or generated
+ * route maps.
+ */
+
+export const AUTO_GENERATED_ROUTE_PREFIX = "$path_";
+export const INTERNAL_INCLUDE_SCOPE_PREFIX = "$prefix_";
+
+const RESERVED_PREFIXES = [
+  AUTO_GENERATED_ROUTE_PREFIX,
+  INTERNAL_INCLUDE_SCOPE_PREFIX,
+] as const;
+
+/**
+ * Check if a route name is internal.
+ * Internal names include:
+ * - unnamed path() routes like "$path__health" or "docs.$path__health"
+ * - hidden include scopes like "$prefix_0.index" or "blog.$prefix_1.post"
+ *
+ * User-defined names containing "$" (e.g. "docs.$admin") are valid and must
+ * be preserved.
+ */
+export function isAutoGeneratedRouteName(name: string): boolean {
+  return name.split(".").some((segment) => {
+    return (
+      segment.startsWith(AUTO_GENERATED_ROUTE_PREFIX) ||
+      segment.startsWith(INTERNAL_INCLUDE_SCOPE_PREFIX)
+    );
+  });
+}
+
+/**
+ * Validate that a user-provided route name does not collide with
+ * reserved internal prefixes. Checks every dot-separated segment,
+ * mirroring the same rule used by isAutoGeneratedRouteName().
+ *
+ * Throws with a clear message when a reserved prefix is detected.
+ */
+export function validateUserRouteName(name: string): void {
+  for (const segment of name.split(".")) {
+    for (const prefix of RESERVED_PREFIXES) {
+      if (segment.startsWith(prefix)) {
+        throw new Error(
+          `Route name "${name}" contains segment "${segment}" which uses reserved internal prefix "${prefix}". ` +
+            `Choose a different name to avoid collision with auto-generated route names.`,
+        );
+      }
+    }
+  }
+}

package/src/route-types.ts

@@ -5,46 +5,43 @@
  */
 
 /**
- * Branded return types for route helpers
+ * Brand for UrlPatterns nominal typing (see pattern-types.ts). The route-item
+ * types below are discriminated by their `type` literal, so they carry no brand.
  */
-export declare const LayoutBrand: unique symbol;
-export declare const RouteBrand: unique symbol;
-export declare const ParallelBrand: unique symbol;
-export declare const InterceptBrand: unique symbol;
-export declare const MiddlewareBrand: unique symbol;
-export declare const RevalidateBrand: unique symbol;
-export declare const LoaderBrand: unique symbol;
-export declare const LoadingBrand: unique symbol;
-export declare const ErrorBoundaryBrand: unique symbol;
-export declare const NotFoundBoundaryBrand: unique symbol;
-export declare const WhenBrand: unique symbol;
-export declare const CacheBrand: unique symbol;
-export declare const IncludeBrand: unique symbol;
 export declare const UrlPatternsBrand: unique symbol;
 
 export type LayoutItem = {
   name: string;
   type: "layout";
   uses?: AllUseItems[];
-  [LayoutBrand]: void;
 };
 
 /**
- * Typed layout item that carries child routes as phantom type
- * Used for type inference in urls() API
+ * Phantom inference fields attached to wrapper items (layout/cache/transition)
+ * so the urls() type extractor can read their child routes/responses. The fields
+ * never exist at runtime.
  */
-export type TypedLayoutItem<
+type WithChildren<
+  TBase,
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = LayoutItem & {
+> = TBase & {
   readonly __childRoutes?: TChildRoutes;
   readonly __childResponses?: TChildResponses;
 };
+
+/**
+ * Typed layout item that carries child routes as phantom type
+ * Used for type inference in urls() API
+ */
+export type TypedLayoutItem<
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = WithChildren<LayoutItem, TChildRoutes, TChildResponses>;
 export type RouteItem = {
   name: string;
   type: "route";
   uses?: AllUseItems[];
-  [RouteBrand]: void;
 };
 
 /**
@@ -66,60 +63,63 @@ export type ParallelItem = {
   name: string;
   type: "parallel";
   uses?: ParallelUseItem[];
-  [ParallelBrand]: void;
 };
 export type InterceptItem = {
   name: string;
   type: "intercept";
   uses?: InterceptUseItem[];
-  [InterceptBrand]: void;
 };
 export type LoaderItem = {
   name: string;
   type: "loader";
   uses?: LoaderUseItem[];
-  [LoaderBrand]: void;
 };
 export type MiddlewareItem = {
   name: string;
   type: "middleware";
   uses?: AllUseItems[];
-  [MiddlewareBrand]: void;
 };
 export type RevalidateItem = {
   name: string;
   type: "revalidate";
   uses?: AllUseItems[];
-  [RevalidateBrand]: void;
 };
 export type LoadingItem = {
   name: string;
   type: "loading";
-  [LoadingBrand]: void;
 };
 export type ErrorBoundaryItem = {
   name: string;
   type: "errorBoundary";
   uses?: AllUseItems[];
-  [ErrorBoundaryBrand]: void;
 };
 export type NotFoundBoundaryItem = {
   name: string;
   type: "notFoundBoundary";
   uses?: AllUseItems[];
-  [NotFoundBoundaryBrand]: void;
 };
 export type WhenItem = {
   name: string;
   type: "when";
-  [WhenBrand]: void;
 };
 export type CacheItem = {
   name: string;
   type: "cache";
   uses?: AllUseItems[];
-  [CacheBrand]: void;
 };
+export type TransitionItem = {
+  name: string;
+  type: "transition";
+};
+
+/**
+ * Typed transition item that carries child routes as phantom type
+ * Used for type inference when transition() wraps child routes
+ */
+export type TypedTransitionItem<
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
+> = WithChildren<TransitionItem, TChildRoutes, TChildResponses>;
 
 /**
  * Typed cache item that carries child routes as phantom type
@@ -128,10 +128,7 @@ export type CacheItem = {
 export type TypedCacheItem<
   TChildRoutes extends Record<string, any> = Record<string, string>,
   TChildResponses extends Record<string, unknown> = Record<string, unknown>,
-> = CacheItem & {
-  readonly __childRoutes?: TChildRoutes;
-  readonly __childResponses?: TChildResponses;
-};
+> = WithChildren<CacheItem, TChildRoutes, TChildResponses>;
 
 /**
  * Include item for URL pattern composition (used by urls() API)
@@ -151,8 +148,21 @@ export type IncludeItem = {
     parent: unknown; // EntryData - avoid circular import
     /** Counter snapshot from pattern extraction for consistent shortCode indices */
     counters?: Record<string, number>;
+    /** Cache profiles for DSL-time cache("profileName") resolution */
+    cacheProfiles?: Record<
+      string,
+      import("./cache/profile-registry.js").CacheProfile
+    >;
+    /** Root scope flag for dot-local reverse resolution */
+    rootScoped?: boolean;
+    /**
+     * Positional include scope token composed from the parent scope plus this
+     * include's sibling index (`${parentScope}I${idx}`). Applied to direct-
+     * descendant shortCodes during lazy evaluation so routes inside the
+     * include cannot collide with siblings declared outside it.
+     */
+    includeScope?: string;
   };
-  [IncludeBrand]: void;
 };
 
 /**
@@ -186,6 +196,7 @@ export type AllUseItems =
   | ErrorBoundaryItem
   | NotFoundBoundaryItem
   | CacheItem
+  | TransitionItem
   | IncludeItem;
 
 /** Items that can be used inside a layout callback */
@@ -200,17 +211,17 @@ export type RouteUseItem =
   | LoadingItem
   | ErrorBoundaryItem
   | NotFoundBoundaryItem
-  | CacheItem;
+  | CacheItem
+  | TransitionItem;
 /** Items that can be used inside a response route (path.json(), etc.) */
-export type ResponseRouteUseItem =
-  | MiddlewareItem
-  | CacheItem;
+export type ResponseRouteUseItem = MiddlewareItem | CacheItem;
 export type ParallelUseItem =
   | RevalidateItem
   | LoaderItem
   | LoadingItem
   | ErrorBoundaryItem
-  | NotFoundBoundaryItem;
+  | NotFoundBoundaryItem
+  | TransitionItem;
 export type InterceptUseItem =
   | MiddlewareItem
   | RevalidateItem
@@ -220,5 +231,25 @@ export type InterceptUseItem =
   | NotFoundBoundaryItem
   | LayoutItem
   | RouteItem
-  | WhenItem;
+  | WhenItem
+  | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
+
+/**
+ * Allow composition factories in use() callbacks.
+ * Factories return T[], which placed inside a use() callback array
+ * creates nested arrays like (T | T[])[]. These are flattened at
+ * runtime via .flat(3).
+ */
+export type UseItems<T> = (T | readonly T[])[];
+
+/**
+ * Union of all items that handler.use() may return.
+ * A handler doesn't know its mount site at definition time, so the type
+ * is intentionally broad — validation happens per-mount-site at runtime.
+ */
+export type HandlerUseItem =
+  | RouteUseItem
+  | LayoutUseItem
+  | ParallelUseItem
+  | InterceptUseItem;