@rangojs/router 0.0.0-experimental.2 → 0.0.0-experimental.20dbba0c

package/src/route-map-builder.ts

@@ -1,146 +1,281 @@
 /**
- * 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 {}
- *   }
- * }
- * ```
+ * See docs/manifests.md for the full data flow.
  */
 
-import type { PrefixRoutePatterns } from "./href.js";
+// Singleton route map instance - populated incrementally as routes are encountered
+let globalRouteMap: Record<string, string> = {};
+
+// Cached complete manifest - includes all routes (including lazy includes)
+// Set from runtime cache or build-time import
+let cachedManifest: Record<string, string> | null = null;
+
+// Pre-computed route entries from build-time prefix tree leaf nodes.
+// Used by evaluateLazyEntry() to skip running the handler for route matching.
+let cachedPrecomputedEntries: Array<{
+  staticPrefix: string;
+  routes: Record<string, string>;
+}> | null = null;
 
 /**
- * Route map builder interface
- *
- * Accumulates route types through the builder chain for type-safe href.
+ * Register routes into the global route map.
+ * Routes are merged with any existing registered routes.
+ * Called by createRouter() during module evaluation.
  */
-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;
+export function registerRouteMap(map: Record<string, string>): void {
+  // Always merge with existing map (don't replace)
+  globalRouteMap = { ...globalRouteMap, ...map };
 }
 
 /**
- * Add routes to a map with optional prefix
- * Keys stay unchanged for composability - only URL patterns get prefixed.
+ * Get the globally registered route map
  *
- * @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)
+ * Used internally by reverse to resolve route names to URLs at runtime.
+ * Returns the cached manifest if available (complete with lazy includes),
+ * otherwise returns the runtime-accumulated route map.
+ *
+ * @returns The registered route map
+ * @internal
  */
-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;
+export function getGlobalRouteMap(): Record<string, string> {
+  // Cached manifest is complete (includes lazy routes), so prefer it
+  if (cachedManifest) {
+    return cachedManifest;
   }
+  return globalRouteMap;
 }
 
 /**
- * Create a new route map builder
- *
- * @returns A builder for accumulating routes with type-safe prefixes
+ * Set the cached manifest (for runtime cache integration)
  *
- * @example
- * ```typescript
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog");
+ * This sets the complete route manifest from a runtime cache.
+ * The cached manifest includes all routes (including lazy includes)
+ * and takes precedence over the incrementally-built globalRouteMap.
  *
- * // Types are accumulated through the chain
- * type AppRoutes = typeof routeMap.routes;
- * ```
+ * @param manifest - The complete route manifest to cache
  */
-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;
-    },
-  };
+export function setCachedManifest(manifest: Record<string, string>): void {
+  cachedManifest = manifest;
+}
 
-  return builder;
+/**
+ * Check if a cached manifest is loaded
+ *
+ * @returns true if a complete manifest is available
+ */
+export function hasCachedManifest(): boolean {
+  return cachedManifest !== null;
 }
 
-// Singleton route map instance - populated when routes.ts is imported
-let globalRouteMap: Record<string, string> = {};
+/**
+ * Clear the cached manifest (for testing)
+ */
+export function clearCachedManifest(): void {
+  cachedManifest = null;
+}
 
 /**
- * Register the route map globally for href to use at runtime
- *
- * Call this after building your route map to make it available to href.
- *
- * @param map - The route map to register
+ * Set pre-computed route entries from build-time data.
  *
- * @example
- * ```typescript
- * const routeMap = createRouteMap()
- *   .add(homeRoutes)
- *   .add(blogRoutes, "blog");
+ * Each entry corresponds to a leaf node in the prefix tree (no nested includes).
+ * evaluateLazyEntry() checks these before running the handler, avoiding the
+ * 5-50ms cost of handler evaluation for route matching on the first request.
  *
- * registerRouteMap(routeMap.routes);
- * ```
+ * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
  */
-export function registerRouteMap(map: Record<string, string>): void {
-  globalRouteMap = map;
+export function setPrecomputedEntries(
+  entries: Array<{
+    staticPrefix: string;
+    routes: Record<string, string>;
+  }> | null,
+): void {
+  cachedPrecomputedEntries = entries;
 }
 
 /**
- * Get the globally registered route map
- *
- * Used internally by href to resolve route names to URLs at runtime.
+ * Get pre-computed route entries (if available)
+ */
+export function getPrecomputedEntries(): typeof cachedPrecomputedEntries {
+  return cachedPrecomputedEntries;
+}
+
+// Route trie for O(path_length) matching at runtime.
+// Built at build time from the route manifest and serialized into the virtual module.
+let cachedRouteTrie: import("./build/route-trie.js").TrieNode | null = null;
+
+export function setRouteTrie(trie: typeof cachedRouteTrie): void {
+  cachedRouteTrie = trie;
+}
+
+export function getRouteTrie(): typeof cachedRouteTrie {
+  return cachedRouteTrie;
+}
+
+// Per-router isolated data: each router gets its own manifest, trie, and
+// 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 perRouterPrecomputedEntriesMap: Map<
+  string,
+  Array<{ staticPrefix: string; routes: Record<string, string> }>
+> = new Map();
+
+/**
+ * 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.
  *
- * @returns The registered route map
+ * The virtual module calls this before repopulating with fresh data,
+ * preventing stale entries from removed routes from accumulating.
  */
-export function getGlobalRouteMap(): Record<string, string> {
-  return globalRouteMap;
+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);
+}
+
+/** @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 {
+  perRouterTrieMap.set(routerId, trie);
+}
+
+export function getRouterTrie(
+  routerId: string,
+): import("./build/route-trie.js").TrieNode | undefined {
+  return perRouterTrieMap.get(routerId);
+}
+
+export function setRouterPrecomputedEntries(
+  routerId: string,
+  entries: Array<{ staticPrefix: string; routes: Record<string, string> }>,
+): void {
+  perRouterPrecomputedEntriesMap.set(routerId, entries);
+}
+
+export function getRouterPrecomputedEntries(
+  routerId: string,
+): Array<{ staticPrefix: string; routes: Record<string, string> }> | undefined {
+  return perRouterPrecomputedEntriesMap.get(routerId);
+}
+
+// Lazy loader registry: per-router manifest modules are loaded on first request
+// via import() to keep startup fast and allow Rollup to code-split per router.
+const routerManifestLoaders: Map<string, () => Promise<any>> = new Map();
+
+export function registerRouterManifestLoader(
+  routerId: string,
+  loader: () => Promise<any>,
+): void {
+  routerManifestLoaders.set(routerId, loader);
+}
+
+export async function ensureRouterManifest(routerId: string): Promise<void> {
+  // 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);
+    routerManifestLoaders.delete(routerId);
+  }
+}
+
+// Dev-mode manifest readiness gate.
+// The Vite discovery plugin calls setManifestReadyPromise() before starting
+// discovery, and resolves it when discovery completes. The handler awaits
+// waitForManifestReady() on first request if the manifest isn't yet available.
+let manifestReadyPromise: Promise<void> | null = null;
+
+export function setManifestReadyPromise(promise: Promise<void>): void {
+  manifestReadyPromise = promise;
+}
+
+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
+// ============================================================================
+
+import type { SearchSchema } from "./search-params.js";
+
+// Global search schema map: route name -> search schema descriptor.
+// Populated by path() when a search option is provided.
+const globalSearchSchemas: Map<string, SearchSchema> = new Map();
+
+export function registerSearchSchema(
+  routeName: string,
+  schema: SearchSchema,
+): void {
+  globalSearchSchemas.set(routeName, schema);
+}
+
+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

@@ -19,6 +19,7 @@ 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 TransitionBrand: unique symbol;
 export declare const IncludeBrand: unique symbol;
 export declare const UrlPatternsBrand: unique symbol;
 
@@ -34,9 +35,11 @@ export type LayoutItem = {
  * Used for type inference in urls() API
  */
 export type TypedLayoutItem<
-  TChildRoutes extends Record<string, string> = Record<string, string>
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
 > = LayoutItem & {
   readonly __childRoutes?: TChildRoutes;
+  readonly __childResponses?: TChildResponses;
 };
 export type RouteItem = {
   name: string;
@@ -51,10 +54,14 @@ export type RouteItem = {
  */
 export type TypedRouteItem<
   TName extends string = string,
-  TPattern extends string = string
+  TPattern extends string = string,
+  TData = unknown,
+  TSearch = {},
 > = RouteItem & {
   readonly __name?: TName;
   readonly __pattern?: TPattern;
+  readonly __data?: TData;
+  readonly __search?: TSearch;
 };
 export type ParallelItem = {
   name: string;
@@ -114,15 +121,34 @@ export type CacheItem = {
   uses?: AllUseItems[];
   [CacheBrand]: void;
 };
+export type TransitionItem = {
+  name: string;
+  type: "transition";
+  [TransitionBrand]: void;
+};
+
+/**
+ * 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>,
+> = TransitionItem & {
+  readonly __childRoutes?: TChildRoutes;
+  readonly __childResponses?: TChildResponses;
+};
 
 /**
  * Typed cache item that carries child routes as phantom type
  * Used for type inference in urls() API
  */
 export type TypedCacheItem<
-  TChildRoutes extends Record<string, string> = Record<string, string>
+  TChildRoutes extends Record<string, any> = Record<string, string>,
+  TChildResponses extends Record<string, unknown> = Record<string, unknown>,
 > = CacheItem & {
   readonly __childRoutes?: TChildRoutes;
+  readonly __childResponses?: TChildResponses;
 };
 
 /**
@@ -133,7 +159,31 @@ export type IncludeItem = {
   name: string;
   prefix: string;
   patterns: unknown; // UrlPatterns - avoid circular ref
-  options?: { name?: string };
+  options?: { name?: string; lazy?: boolean };
+  /** Whether this include should be lazily evaluated on first request */
+  lazy?: boolean;
+  /** Captured context for deferred lazy evaluation */
+  _lazyContext?: {
+    urlPrefix: string;
+    namePrefix: string | undefined;
+    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;
 };
 
@@ -142,11 +192,15 @@ export type IncludeItem = {
  * Used for type inference in urls() API
  */
 export type TypedIncludeItem<
-  TRoutes extends Record<string, string> = Record<string, string>,
-  TNamePrefix extends string = string
+  TRoutes extends Record<string, any> = Record<string, string>,
+  TNamePrefix extends string = string,
+  TUrlPrefix extends string = string,
+  TResponses extends Record<string, unknown> = Record<string, unknown>,
 > = IncludeItem & {
   readonly __routes?: TRoutes;
   readonly __namePrefix?: TNamePrefix;
+  readonly __urlPrefix?: TUrlPrefix;
+  readonly __responses?: TResponses;
 };
 
 /**
@@ -164,6 +218,7 @@ export type AllUseItems =
   | ErrorBoundaryItem
   | NotFoundBoundaryItem
   | CacheItem
+  | TransitionItem
   | IncludeItem;
 
 /** Items that can be used inside a layout callback */
@@ -178,13 +233,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 ParallelUseItem =
   | RevalidateItem
   | LoaderItem
   | LoadingItem
   | ErrorBoundaryItem
-  | NotFoundBoundaryItem;
+  | NotFoundBoundaryItem
+  | TransitionItem;
 export type InterceptUseItem =
   | MiddlewareItem
   | RevalidateItem
@@ -194,5 +253,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;