@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/route-map-builder.ts

@@ -8,28 +8,32 @@
  * See docs/manifests.md for the full data flow.
  */
 
-// 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;
-
 /**
  * Register routes into the global route map.
  * Routes are merged with any existing registered routes.
- * Called by createRouter() during module evaluation.
+ * Called by createRouter() during module evaluation, and by lazy-include
+ * expansion (src/router/lazy-includes.ts) with each expansion's route delta.
+ *
+ * Merges IN PLACE — O(|map|), not O(total routes). The previous
+ * `globalRouteMap = { ...globalRouteMap, ...map }` copy made every
+ * lazy-include first hit O(total routes) on the request path: with a 26k-route
+ * manifest the spread measured 8.9ms/call (M4, node), paid once per level of a
+ * nested async-include chain (3 calls on a 3-level chain — the 464ms edge
+ * cold-hit in issue #666).
+ *
+ * In-place mutation is safe because every getGlobalRouteMap() consumer reads
+ * it fresh per call (server/request-context.ts, rsc/loader-fetch.ts,
+ * router/intercept-resolution.ts, testing/generated-routes.ts,
+ * rsc/manifest-init.ts) — none memoizes the returned reference. If you add a
+ * consumer that caches the map object, it will now observe later
+ * registrations; snapshot it yourself if you need frozen contents.
  */
 export function registerRouteMap(map: Record<string, string>): void {
-  // Always merge with existing map (don't replace)
-  globalRouteMap = { ...globalRouteMap, ...map };
+  Object.assign(globalRouteMap, map);
 }
 
 /**
@@ -43,7 +47,6 @@ export function registerRouteMap(map: Record<string, string>): void {
  * @internal
  */
 export function getGlobalRouteMap(): Record<string, string> {
-  // Cached manifest is complete (includes lazy routes), so prefer it
   if (cachedManifest) {
     return cachedManifest;
   }
@@ -79,43 +82,6 @@ export function clearCachedManifest(): void {
   cachedManifest = null;
 }
 
-/**
- * Set pre-computed route entries from build-time data.
- *
- * 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.
- *
- * @param entries - Array of { staticPrefix, routes } from build-time prefix tree leaves
- */
-export function setPrecomputedEntries(
-  entries: Array<{
-    staticPrefix: string;
-    routes: Record<string, string>;
-  }> | null,
-): void {
-  cachedPrecomputedEntries = entries;
-}
-
-/**
- * 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.
@@ -138,13 +104,18 @@ const perRouterPrecomputedEntriesMap: Map<
 export function clearAllRouterData(): void {
   globalRouteMap = {};
   cachedManifest = null;
-  cachedPrecomputedEntries = null;
-  cachedRouteTrie = null;
   rootScopeRoutes.clear();
+  perRouterRootScopeRoutes.clear();
   globalSearchSchemas.clear();
+  perRouterSearchSchemas.clear();
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
+  authoritativeTrieRouters.clear();
+  // Clear the loader registry too: a loader that survives a clear closes over
+  // a module import whose data predates the clear, and re-running it would
+  // re-install that stale trie as authoritative.
+  routerManifestLoaders.clear();
 }
 
 export function setRouterManifest(
@@ -168,6 +139,23 @@ export function setRouterTrie(
   perRouterTrieMap.set(routerId, trie);
 }
 
+// Routers whose trie came from the COMPLETE build manifest (deserialized via
+// ensureRouterManifest). For these, a trie miss is a real 404 and findMatch
+// skips the regex fallback scan — the only remaining route-count-proportional
+// match path (#664). Dev rebuilds (manifest-init.ts, router-discovery HMR
+// pushes) deliberately never mark authoritative: the dev-only trie-gap warning
+// in find-match.ts depends on the fallback running on misses, and dev route
+// churn (HMR, dev-time routes) makes a stale-trie 404 unacceptable there.
+const authoritativeTrieRouters: Set<string> = new Set();
+
+export function markRouterTrieAuthoritative(routerId: string): void {
+  authoritativeTrieRouters.add(routerId);
+}
+
+export function isRouterTrieAuthoritative(routerId: string): boolean {
+  return authoritativeTrieRouters.has(routerId);
+}
+
 export function getRouterTrie(
   routerId: string,
 ): import("./build/route-trie.js").TrieNode | undefined {
@@ -199,18 +187,23 @@ export function registerRouterManifestLoader(
 }
 
 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;
+  // Gate on the trie: it is the only data the lazy loader supplies (the
+  // name->path map is pre-set by the eager virtual module's
+  // setRouterManifest() and never comes from the loader). Gating on the
+  // manifest instead would let the loader be skipped while the per-router
+  // trie is missing, and findMatch would fall back to insertion-order regex
+  // matching — which mishandles wildcard priority (catch-alls match before
+  // specific routes).
+  if (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.trie) {
+      perRouterTrieMap.set(routerId, mod.trie);
+      // A trie serialized into the build manifest comes from complete
+      // discovery — misses are authoritative 404s (see find-match.ts).
+      markRouterTrieAuthoritative(routerId);
+    }
     if (mod.precomputedEntries)
       perRouterPrecomputedEntriesMap.set(routerId, mod.precomputedEntries);
     routerManifestLoaders.delete(routerId);
@@ -231,14 +224,19 @@ 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.
+//
+// Both this and the search-schema registry below are keyed by route NAME and
+// registered by path() at evaluation time. Two routers can legally declare the
+// same route name (per-router manifests keep them apart), so each registry has
+// a per-router tier consulted first; the global tier is the fallback for
+// contexts with no router identity (single-router apps, unit tests, evaluation
+// outside generateManifestFull). Without the per-router tier, the
+// last-evaluated router silently won for BOTH routers.
 const rootScopeRoutes: Map<string, boolean> = new Map();
+const perRouterRootScopeRoutes: Map<string, Map<string, boolean>> = new Map();
 
 /**
  * Register whether a route is at root scope.
@@ -247,35 +245,65 @@ const rootScopeRoutes: Map<string, boolean> = new Map();
 export function registerRouteRootScope(
   routeName: string,
   rootScoped: boolean,
+  routerId?: string,
 ): void {
   rootScopeRoutes.set(routeName, rootScoped);
+  if (routerId) {
+    let perRouter = perRouterRootScopeRoutes.get(routerId);
+    if (!perRouter) {
+      perRouter = new Map();
+      perRouterRootScopeRoutes.set(routerId, perRouter);
+    }
+    perRouter.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 {
+export function isRouteRootScoped(
+  routeName: string,
+  routerId?: string,
+): boolean | undefined {
+  if (routerId) {
+    const scoped = perRouterRootScopeRoutes.get(routerId)?.get(routeName);
+    if (scoped !== undefined) return scoped;
+  }
   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();
+const perRouterSearchSchemas: Map<
+  string,
+  Map<string, SearchSchema>
+> = new Map();
 
 export function registerSearchSchema(
   routeName: string,
   schema: SearchSchema,
+  routerId?: string,
 ): void {
   globalSearchSchemas.set(routeName, schema);
+  if (routerId) {
+    let perRouter = perRouterSearchSchemas.get(routerId);
+    if (!perRouter) {
+      perRouter = new Map();
+      perRouterSearchSchemas.set(routerId, perRouter);
+    }
+    perRouter.set(routeName, schema);
+  }
 }
 
-export function getSearchSchema(routeName: string): SearchSchema | undefined {
+export function getSearchSchema(
+  routeName: string,
+  routerId?: string,
+): SearchSchema | undefined {
+  if (routerId) {
+    const schema = perRouterSearchSchemas.get(routerId)?.get(routeName);
+    if (schema !== undefined) return schema;
+  }
   return globalSearchSchemas.get(routeName);
 }

package/src/route-types.ts

@@ -5,47 +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 TransitionBrand: 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;
 };
 
 /**
@@ -67,64 +63,49 @@ 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";
-  [TransitionBrand]: void;
 };
 
 /**
@@ -134,10 +115,7 @@ export type TransitionItem = {
 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;
-};
+> = WithChildren<TransitionItem, TChildRoutes, TChildResponses>;
 
 /**
  * Typed cache item that carries child routes as phantom type
@@ -146,10 +124,7 @@ export type TypedTransitionItem<
 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)
@@ -184,7 +159,6 @@ export type IncludeItem = {
      */
     includeScope?: string;
   };
-  [IncludeBrand]: void;
 };
 
 /**
@@ -253,7 +227,6 @@ export type InterceptUseItem =
   | NotFoundBoundaryItem
   | LayoutItem
   | RouteItem
-  | WhenItem
   | TransitionItem;
 export type LoaderUseItem = RevalidateItem | CacheItem;
 

package/src/router/basename.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize a router basename to its canonical form: a single leading slash,
+ * no trailing slash, and `undefined` for an empty or bare-"/" value.
+ *
+ * This is the single source of truth used by both createRouter() (so the RSC
+ * handler stores a canonical basename on the request context) and the testing
+ * primitives (so a consumer can pass the same un-normalized string their
+ * createRouter() accepts and observe the same redirect() prefixing).
+ */
+export function normalizeBasename(basename?: string): string | undefined {
+  if (!basename) return undefined;
+  const trimmed = basename.replace(/^\/+|\/+$/g, "");
+  return trimmed ? "/" + trimmed : undefined;
+}