@rangojs/router 0.0.0-experimental.9 → 0.0.0-experimental.a06372ef

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.
- */
-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)
+ * See docs/manifests.md for the full data flow.
  */
-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;
 }
@@ -227,6 +116,101 @@ 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.
+ *
+ * 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);
+}
+
+/** @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> {
+  if (perRouterManifestMap.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
@@ -240,3 +224,52 @@ export function setManifestReadyPromise(promise: Promise<void>): void {
 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,7 +35,7 @@ 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;
@@ -55,10 +56,12 @@ export type TypedRouteItem<
   TName 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;
@@ -118,13 +121,30 @@ 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;
@@ -147,6 +167,15 @@ export type IncludeItem = {
     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;
   };
   [IncludeBrand]: void;
 };
@@ -156,7 +185,7 @@ export type IncludeItem = {
  * Used for type inference in urls() API
  */
 export type TypedIncludeItem<
-  TRoutes extends Record<string, string> = Record<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>,
@@ -182,6 +211,7 @@ export type AllUseItems =
   | ErrorBoundaryItem
   | NotFoundBoundaryItem
   | CacheItem
+  | TransitionItem
   | IncludeItem;
 
 /** Items that can be used inside a layout callback */
@@ -196,17 +226,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
@@ -216,5 +246,14 @@ 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[])[];

package/src/router/content-negotiation.ts

@@ -0,0 +1,116 @@
+/**
+ * Content Negotiation Utilities
+ *
+ * Pure functions for HTTP Accept header parsing and response type matching.
+ * Used by createRouter's previewMatch for content negotiation between
+ * RSC routes and response routes (JSON, text, image, stream, etc.).
+ */
+
+// Response type -> MIME type used for Accept header matching
+export const RESPONSE_TYPE_MIME: Record<string, string> = {
+  json: "application/json",
+  text: "text/plain",
+  xml: "application/xml",
+  html: "text/html",
+  md: "text/markdown",
+};
+
+// Reverse lookup: MIME type -> response type tag (e.g. "text/html" -> "html")
+export const MIME_RESPONSE_TYPE: Record<string, string> = Object.fromEntries(
+  Object.entries(RESPONSE_TYPE_MIME).map(([tag, mime]) => [mime, tag]),
+);
+
+export type NamedRouteEntry =
+  | string
+  | { path: string; search?: Record<string, string> };
+
+export function flattenNamedRoutes(
+  routeNames?: Record<string, NamedRouteEntry>,
+): Record<string, string> {
+  if (!routeNames) return {};
+  const flattened: Record<string, string> = {};
+  for (const [name, entry] of Object.entries(routeNames)) {
+    flattened[name] = typeof entry === "string" ? entry : entry.path;
+  }
+  return flattened;
+}
+
+export interface AcceptEntry {
+  mime: string;
+  q: number;
+  order: number;
+}
+
+/**
+ * Parse an Accept header into a sorted array of MIME entries.
+ * Respects q-values (default 1.0) and uses client order as tiebreaker
+ * when q-values are equal (matching Express/Hono behavior).
+ */
+export function parseAcceptTypes(accept: string): AcceptEntry[] {
+  const entries: AcceptEntry[] = [];
+  const parts = accept.split(",");
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i]!;
+    const segments = part.split(";");
+    const mime = segments[0]!.trim().toLowerCase();
+    if (!mime) continue;
+    let q = 1.0;
+    for (let j = 1; j < segments.length; j++) {
+      const param = segments[j]!.trim();
+      if (param.startsWith("q=")) {
+        q = Math.max(0, Math.min(1, Number(param.slice(2)) || 0));
+      }
+    }
+    entries.push({ mime, q, order: i });
+  }
+  // Sort: highest q first, then lowest client order first (stable)
+  entries.sort((a, b) => b.q - a.q || a.order - b.order);
+  return entries;
+}
+
+// Sentinel response type for RSC routes in negotiation candidates
+export const RSC_RESPONSE_TYPE = "__rsc__";
+
+/**
+ * Pick the best negotiate variant by walking the client's sorted Accept list.
+ * For each accepted MIME type (in q-value/order priority), check if any
+ * candidate serves that type. Wildcards match the first candidate.
+ * Falls back to the first candidate if nothing matches.
+ */
+export function pickNegotiateVariant(
+  acceptEntries: AcceptEntry[],
+  candidates: Array<{ routeKey: string; responseType: string }>,
+): { routeKey: string; responseType: string } {
+  // Build a MIME -> candidate lookup for O(1) matching
+  const byCandidateMime = new Map<
+    string,
+    { routeKey: string; responseType: string }
+  >();
+  for (const c of candidates) {
+    const mime =
+      c.responseType === RSC_RESPONSE_TYPE
+        ? "text/html"
+        : RESPONSE_TYPE_MIME[c.responseType];
+    if (mime && !byCandidateMime.has(mime)) {
+      byCandidateMime.set(mime, c);
+    }
+  }
+
+  for (const entry of acceptEntries) {
+    if (entry.q === 0) continue;
+    // Wildcard matches first candidate
+    if (entry.mime === "*/*") return candidates[0]!;
+    // Type wildcard (e.g. "text/*") -- match first candidate with that type
+    if (entry.mime.endsWith("/*")) {
+      const typePrefix = entry.mime.slice(0, entry.mime.indexOf("/"));
+      for (const [mime, candidate] of byCandidateMime) {
+        if (mime.startsWith(typePrefix + "/")) return candidate;
+      }
+      continue;
+    }
+    const match = byCandidateMime.get(entry.mime);
+    if (match) return match;
+  }
+  // No match -- use first candidate as default
+  return candidates[0]!;
+}

package/src/router/debug-manifest.ts

@@ -0,0 +1,72 @@
+import { type EntryData, getContext } from "../server/context";
+import { serializeManifest, type SerializedManifest } from "../debug.js";
+import { createRouteHelpers } from "../route-definition.js";
+import MapRootLayout from "../server/root-layout.js";
+import type { RouteEntry, TrailingSlashMode } from "../types";
+
+/**
+ * Build a serialized manifest from all route entries for debug inspection.
+ * Used by the `debugManifest()` method on the router instance.
+ */
+export async function buildDebugManifest<TEnv = any>(
+  routesEntries: RouteEntry<TEnv>[],
+): Promise<SerializedManifest> {
+  const manifest = new Map<string, EntryData>();
+
+  for (const entry of routesEntries) {
+    const Store = {
+      manifest,
+      namespace: `debug.M${entry.mountIndex}`,
+      parent: null as EntryData | null,
+      counters: {} as Record<string, number>,
+      mountIndex: entry.mountIndex,
+      patterns: new Map<string, string>(),
+      trailingSlash: new Map<string, TrailingSlashMode>(),
+    };
+
+    await getContext().runWithStore(
+      Store,
+      `debug.M${entry.mountIndex}`,
+      null,
+      async () => {
+        const helpers = createRouteHelpers();
+
+        // Wrap handler execution in root layout (same as loadManifest)
+        let promiseResult: Promise<any> | null = null;
+        helpers.layout(MapRootLayout, () => {
+          const result = entry.handler();
+          if (result instanceof Promise) {
+            promiseResult = result;
+            return [];
+          }
+          return result;
+        });
+
+        if (promiseResult !== null) {
+          const load = await (promiseResult as Promise<any>);
+          if (load && typeof load === "object" && "default" in load) {
+            // Promise<{ default: fn }> — e.g. dynamic import
+            if (typeof load.default !== "function") {
+              throw new Error(
+                `[@rangojs/router] Unsupported async handler: { default } must be a function, ` +
+                  `got ${typeof load.default}. Use () => import('./urls') for lazy loading.`,
+              );
+            }
+            load.default(helpers);
+          } else if (typeof load === "function") {
+            // Promise<fn>
+            load(helpers);
+          } else {
+            // Reject unsupported async handler results (same policy as manifest.ts)
+            throw new Error(
+              `[@rangojs/router] Unsupported async handler result (${typeof load}). ` +
+                `Lazy route handlers must resolve to a function or { default: fn }.`,
+            );
+          }
+        }
+      },
+    );
+  }
+
+  return serializeManifest(manifest);
+}