@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/router.ts

@@ -1,70 +1,43 @@
-import type { ComponentType } from "react";
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
-import type { SegmentCacheStore } from "./cache/types.js";
+import { resolveCacheProfiles } from "./cache/profile-registry.js";
+import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
-import {
-  sanitizeError,
-} from "./errors";
-import { serializeManifest, type SerializedManifest } from "./debug.js";
-import {
-  createReverse,
-  type ReverseFunction,
-  type PrefixRoutePatterns,
-} from "./reverse.js";
+import type { SerializedManifest } from "./debug.js";
+import { createReverse, type ReverseFunction } from "./reverse.js";
 import {
   registerRouteMap,
-  getGlobalRouteMap,
   getPrecomputedEntries,
-  getRouteTrie,
   getRouterManifest,
-  getRouterTrie,
   getRouterPrecomputedEntries,
   ensureRouterManifest,
 } from "./route-map-builder.js";
-import { tryTrieMatch } from "./router/trie-matching.js";
-import {
-  createRouteHelpers,
-  type RouteHandlers,
-} from "./route-definition.js";
 import MapRootLayout from "./server/root-layout.js";
-import type { AllUseItems, IncludeItem } from "./route-types.js";
+import type { AllUseItems } from "./route-types.js";
 import type { UrlPatterns } from "./urls.js";
+import type { UrlBuilder } from "./urls/pattern-types.js";
+import { urls } from "./urls.js";
+import { buildPrecomputedByPrefix } from "./build/prefix-tree-utils.js";
 import {
-  EntryData,
-  InterceptEntry,
-  InterceptSelectorContext,
+  type EntryData,
   getContext,
-  RSCRouterContext,
-  runWithPrefixes,
+  RangoContext,
   type MetricsStore,
 } from "./server/context";
 import { createHandleStore, type HandleStore } from "./server/handle-store.js";
-import { getRequestContext } from "./server/request-context.js";
+import {
+  getRequestContext,
+  _getRequestContext,
+} from "./server/request-context.js";
 import type {
-  ErrorBoundaryHandler,
-  ErrorInfo,
   ErrorPhase,
   HandlerContext,
   LoaderDataResult,
-  MatchResult,
-  NotFoundBoundaryHandler,
-  OnErrorCallback,
   ResolvedRouteMap,
-  RouteDefinition,
   RouteEntry,
   TrailingSlashMode,
 } from "./types";
-import type {
-  NonceProvider,
-} from "./rsc/types.js";
-import {
-  runWithRequestContext,
-  type RequestContext,
-  type ExecutionContext,
-} from "./server/request-context.js";
-import type { SerializedSegmentData, SegmentHandleData } from "./cache/types.js";
 
 // Extracted router utilities
 import {
@@ -74,1072 +47,93 @@ import {
   invokeOnError,
 } from "./router/error-handling.js";
 
-// Extracted segment resolution functions
-import {
-  resolveAllSegments as _resolveAllSegments,
-  resolveLoadersOnly as _resolveLoadersOnly,
-  resolveLoadersOnlyWithRevalidation as _resolveLoadersOnlyWithRevalidation,
-  buildEntryRevalidateMap as _buildEntryRevalidateMap,
-  resolveAllSegmentsWithRevalidation as _resolveAllSegmentsWithRevalidation,
-} from "./router/segment-resolution.js";
-
-// Extracted intercept resolution functions
-import {
-  findInterceptForRoute as _findInterceptForRoute,
-  resolveInterceptEntry as _resolveInterceptEntry,
-  resolveInterceptLoadersOnly as _resolveInterceptLoadersOnly,
-} from "./router/intercept-resolution.js";
-
-// Extracted match API functions
-import {
-  createMatchContextForFull as _createMatchContextForFull,
-  createMatchContextForPartial as _createMatchContextForPartial,
-  matchError as _matchError,
-} from "./router/match-api.js";
+// Extracted module factories
+import { createSegmentWrappers } from "./router/segment-wrappers.js";
+import { createMatchHandlers } from "./router/match-handlers.js";
+import { buildDebugManifest } from "./router/debug-manifest.js";
 
 import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
-import { createHandlerContext, createBuildContext } from "./router/handler-context.js";
+import { createHandlerContext } from "./router/handler-context.js";
+import { normalizeBasename } from "./router/basename.js";
 import {
   setupLoaderAccess,
   setupLoaderAccessSilent,
-  setupBuildUse,
   wrapLoaderWithErrorHandling,
 } from "./router/loader-resolution.js";
 import { loadManifest } from "./router/manifest.js";
+import { createMetricsStore } from "./router/metrics.js";
 import {
-  createMetricsStore,
-} from "./router/metrics.js";
-import {
-  collectRouteMiddleware,
   parsePattern,
   type MiddlewareEntry,
   type MiddlewareFn,
 } from "./router/middleware.js";
 import {
   extractStaticPrefix,
-  findMatch as findRouteMatch,
-  isLazyEvaluationNeeded,
+  joinPrefix,
   traverseBack,
-  type RouteMatchResult,
 } from "./router/pattern-matching.js";
+import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
+import { resolveTracing } from "./router/tracing.js";
 import { evaluateRevalidation } from "./router/revalidation.js";
 import {
   type RouterContext,
   runWithRouterContext,
 } from "./router/router-context.js";
-import {
-  type ActionContext,
-  type MatchContext,
-  createPipelineState,
-} from "./router/match-context.js";
-import { createMatchPartialPipeline } from "./router/match-pipelines.js";
-import { collectMatchResult } from "./router/match-result.js";
-import {
-  runWithRouterLogContext,
-  withRouterLogScope,
-} from "./router/logging.js";
 import { resolveThemeConfig } from "./theme/constants.js";
+import { resolveTimeouts } from "./router/timeout.js";
 
-// Response type -> MIME type used for Accept header matching
-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")
-const MIME_RESPONSE_TYPE: Record<string, string> = Object.fromEntries(
-  Object.entries(RESPONSE_TYPE_MIME).map(([tag, mime]) => [mime, tag]),
-);
-
-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).
- */
-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();
-    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
-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.
- */
-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]!;
-}
-
-/**
- * Props passed to the root layout component
- */
-export interface RootLayoutProps {
-  children: ReactNode;
-}
-
-/**
- * Router configuration options
- */
-/**
- * Brand marker for identifying router instances at build time.
- * Used by the Vite plugin to auto-discover routers from module exports.
- */
-export const RSC_ROUTER_BRAND: "__rsc_router__" = "__rsc_router__";
-
-/**
- * Global registry of all router instances created via createRouter().
- * Each router is keyed by its id (auto-generated or user-provided).
- * Used by the Vite plugin at build time to discover routers and extract
- * manifests, prefix trees, and pre-render candidates.
- */
-export const RouterRegistry: Map<string, RSCRouter<any, any>> = new Map();
-
-let routerAutoId = 0;
-
-export interface RSCRouterOptions<TEnv = any> {
-  /**
-   * Unique identifier for this router instance.
-   * Used to namespace static output files and route maps.
-   * Auto-generated if not provided.
-   */
-  id?: string;
-
-  /**
-   * Injected by the Vite transform at compile time.
-   * Hash of filename + line number for stable cross-environment ID.
-   * @internal
-   */
-  $$id?: string;
-
-  /**
-   * Enable performance metrics collection
-   * When enabled, metrics are output to console and available via Server-Timing header
-   */
-  debugPerformance?: boolean;
-
-  /**
-   * Allow the `?__debug_manifest` query parameter to return route manifest data as JSON.
-   * In development mode this is always enabled regardless of this setting.
-   * Defaults to true. Set to false to disable in production.
-   * @internal
-   */
-  allowDebugManifest?: boolean;
-
-  /**
-   * Document component that wraps the entire application.
-   *
-   * This component provides the HTML structure for your app and wraps
-   * both normal route content AND error states, preventing the app shell
-   * from unmounting during errors (avoids FOUC).
-   *
-   * Must be a client component ("use client") that accepts { children }.
-   *
-   * If not provided, a default document with basic HTML structure is used:
-   * `<html><head><meta charset/viewport></head><body>{children}</body></html>`
-   *
-   * @example
-   * ```typescript
-   * // components/Document.tsx
-   * "use client";
-   * export function Document({ children }: { children: ReactNode }) {
-   *   return (
-   *     <html lang="en">
-   *       <head>
-   *         <link rel="stylesheet" href="/styles.css" />
-   *       </head>
-   *       <body>
-   *         <nav>...</nav>
-   *         {children}
-   *       </body>
-   *     </html>
-   *   );
-   * }
-   *
-   * // router.tsx
-   * const router = createRouter<AppEnv>({
-   *   document: Document,
-   * });
-   * ```
-   */
-  document?: ComponentType<RootLayoutProps>;
-
-  /**
-   * Default error boundary fallback used when no error boundary is defined in the route tree
-   * If not provided, errors will propagate and crash the request
-   */
-  defaultErrorBoundary?: ReactNode | ErrorBoundaryHandler;
-
-  /**
-   * Default not-found boundary fallback used when no notFoundBoundary is defined in the route tree
-   * If not provided, DataNotFoundError will be treated as a regular error
-   */
-  defaultNotFoundBoundary?: ReactNode | NotFoundBoundaryHandler;
-
-  /**
-   * Component to render when no route matches the requested URL.
-   *
-   * This is rendered within your document/app shell with a 404 status code.
-   * Use this for a custom 404 page that maintains your app's look and feel.
-   *
-   * If not provided, a default "Page not found" component is rendered.
-   *
-   * Can be a static ReactNode or a function receiving the pathname.
-   *
-   * @example
-   * ```typescript
-   * // Simple static component
-   * const router = createRouter<AppEnv>({
-   *   document: Document,
-   *   notFound: <NotFound404 />,
-   * });
-   *
-   * // Dynamic component with pathname
-   * const router = createRouter<AppEnv>({
-   *   document: Document,
-   *   notFound: ({ pathname }) => (
-   *     <div>
-   *       <h1>404 - Not Found</h1>
-   *       <p>No page exists at {pathname}</p>
-   *       <a href="/">Go home</a>
-   *     </div>
-   *   ),
-   * });
-   * ```
-   */
-  notFound?: ReactNode | ((props: { pathname: string }) => ReactNode);
-
-  /**
-   * Callback invoked when an error occurs during request handling.
-   *
-   * This callback is for notification/logging purposes - it cannot modify
-   * the error handling flow. Use errorBoundary() in route definitions to
-   * customize error UI.
-   *
-   * The callback receives comprehensive context about the error including:
-   * - The error itself
-   * - Phase where it occurred (routing, middleware, loader, handler, etc.)
-   * - Request info (URL, method, params)
-   * - Route info (routeKey, segmentId)
-   * - Environment/bindings
-   * - Duration from request start
-   *
-   * @example
-   * ```typescript
-   * const router = createRouter<AppEnv>({
-   *   onError: (context) => {
-   *     // Send to error tracking service
-   *     Sentry.captureException(context.error, {
-   *       tags: {
-   *         phase: context.phase,
-   *         route: context.routeKey,
-   *       },
-   *       extra: {
-   *         url: context.url.toString(),
-   *         params: context.params,
-   *         duration: context.duration,
-   *       },
-   *     });
-   *   },
-   * });
-   * ```
-   */
-  onError?: OnErrorCallback<TEnv>;
-
-  /**
-   * Cache store for segment caching.
-   *
-   * When provided, enables route-level caching via cache() boundaries.
-   * The store handles persistence (memory, KV, Redis, etc.).
-   *
-   * Can be a static config or a function receiving env for runtime bindings.
-   *
-   * @example Static config
-   * ```typescript
-   * import { MemorySegmentCacheStore } from "rsc-router/rsc";
-   *
-   * const router = createRouter({
-   *   cache: {
-   *     store: new MemorySegmentCacheStore({ defaults: { ttl: 60 } }),
-   *   },
-   * });
-   * ```
-   *
-   * @example Dynamic config with env (e.g., Cloudflare Workers with ExecutionContext)
-   * ```typescript
-   * const router = createRouter<AppEnv>({
-   *   cache: (env) => ({
-   *     store: new CFCacheStore({
-   *       defaults: { ttl: 60 },
-   *       ctx: env.ctx, // ExecutionContext for non-blocking writes
-   *     }),
-   *   }),
-   * });
-   * ```
-   */
-  cache?:
-    | { store: SegmentCacheStore; enabled?: boolean }
-    | ((env: TEnv & { ctx?: ExecutionContext }) => {
-        store: SegmentCacheStore;
-        enabled?: boolean;
-      });
-
-  /**
-   * Theme configuration for automatic theme management.
-   *
-   * When provided, enables:
-   * - ctx.theme and ctx.setTheme() in route handlers
-   * - useTheme() hook for client components
-   * - FOUC prevention via inline script in MetaTags
-   * - Automatic ThemeProvider wrapping in NavigationProvider
-   *
-   * @example
-   * ```typescript
-   * const router = createRouter<AppEnv>({
-   *   theme: {
-   *     defaultTheme: "system",
-   *     themes: ["light", "dark"],
-   *   }
-   * });
-   *
-   * // In route handler:
-   * route("settings", (ctx) => {
-   *   const theme = ctx.theme;     // "light" | "dark" | "system"
-   *   ctx.setTheme("dark");        // Sets cookie
-   *   return <SettingsPage />;
-   * });
-   *
-   * // In client component:
-   * import { useTheme } from "@rangojs/router/theme";
-   *
-   * function ThemeToggle() {
-   *   const { theme, setTheme, themes } = useTheme();
-   *   return <select value={theme} onChange={e => setTheme(e.target.value)}>
-   *     {themes.map(t => <option key={t}>{t}</option>)}
-   *   </select>;
-   * }
-   * ```
-   *
-   * Use `theme: true` to enable with all defaults.
-   */
-  theme?: import("./theme/types.js").ThemeConfig | true;
-
-  /**
-   * URL patterns to register with the router.
-   *
-   * Alternative to calling `.routes()` method - allows passing patterns
-   * directly in the config for a more concise setup.
-   *
-   * @example
-   * ```typescript
-   * import { urls } from "@rangojs/router/server";
-   *
-   * const urlpatterns = urls(({ path, layout }) => [
-   *   path("/", HomePage, { name: "home" }),
-   *   path("/about", AboutPage, { name: "about" }),
-   * ]);
-   *
-   * const router = createRouter<AppEnv>({
-   *   document: Document,
-   *   urls: urlpatterns,
-   * });
-   * ```
-   */
-  urls?: UrlPatterns<TEnv, any>;
-
-  /**
-   * Injected by the Vite transform at compile time.
-   * Static import of NamedRoutes from the generated named-routes file.
-   * Provides O(1) reverse() fallback when lazy includes haven't resolved.
-   * @internal
-   */
-  $$routeNames?: Record<string, string>;
+// Extracted content negotiation utilities
+import { flattenNamedRoutes } from "./router/content-negotiation.js";
 
-  /**
-   * Nonce provider for Content Security Policy (CSP).
-   *
-   * Can be:
-   * - A function that returns a nonce string
-   * - A function that returns `true` to auto-generate a nonce
-   * - Undefined to disable nonce (default)
-   *
-   * The nonce will be applied to inline scripts injected by the RSC payload.
-   * It's also available to middleware via `ctx.get('nonce')`.
-   *
-   * @example Auto-generate nonce
-   * ```tsx
-   * createRouter({
-   *   nonce: () => true,
-   * });
-   * ```
-   *
-   * @example Custom nonce from request context
-   * ```tsx
-   * createRouter({
-   *   nonce: (request, env) => env.nonce,
-   * });
-   * ```
-   */
-  nonce?: NonceProvider<TEnv>;
-
-  /**
-   * RSC version string included in metadata.
-   * The browser sends this back on partial requests to detect version mismatches.
-   *
-   * Defaults to the auto-generated VERSION from `@rangojs/router:version` virtual module.
-   * Only set this if you need a custom versioning strategy.
-   *
-   * @default VERSION from @rangojs/router:version
-   */
-  version?: string;
-
-  /**
-   * Enable connection warmup to keep TCP+TLS alive after idle periods.
-   *
-   * When enabled, the client sends a HEAD request after the user returns
-   * from an idle period (60s+), prewarming the TLS connection before
-   * the next navigation.
-   *
-   * @default true
-   */
-  warmup?: boolean;
-}
-
-/**
- * Merge route patterns with response types into a single route map.
- * Routes with response types get { path, response } objects; others stay as strings.
- * Handles both plain string routes and { path, search } object routes.
- */
-type MergeRoutesWithResponses<
-  TRoutes extends Record<string, unknown>,
-  TResponses,
-> = {
-  [K in keyof TRoutes]: K extends keyof NonNullable<TResponses>
-    ? unknown extends NonNullable<TResponses>[K]
-      ? TRoutes[K] // RSC route — TData defaults to unknown, keep as-is
-      : TRoutes[K] extends { readonly path: infer P extends string }
-        ? TRoutes[K] & { readonly response: NonNullable<TResponses>[K] }
-        : { readonly path: TRoutes[K] & string; readonly response: NonNullable<TResponses>[K] }
-    : TRoutes[K]
-};
-
-/**
- * Extract the URL pattern from a route entry (string or { path, response } object)
- */
-type PatternOfEntry<V> =
-  V extends string ? V
-  : V extends { readonly path: infer P extends string } ? P
-  : never;
-
-/**
- * Type-level detection of conflicting route keys.
- * Extracts keys that exist in both TExisting and TNew but with different URL patterns.
- * Returns `never` if no conflicts exist.
- * Compares patterns (not full entries) to handle both string and { path, response } values.
- *
- * @example
- * ```typescript
- * ConflictingKeys<{ a: "/a" }, { a: "/b" }> // "a" (conflict - same key, different URLs)
- * ConflictingKeys<{ a: "/a" }, { a: "/a" }> // never (no conflict - same key and URL)
- * ConflictingKeys<{ a: "/a" }, { b: "/b" }> // never (no conflict - different keys)
- * ```
- */
-type ConflictingKeys<
-  TExisting extends Record<string, unknown>,
-  TNew extends Record<string, unknown>,
-> = {
-  [K in keyof TExisting & keyof TNew]: PatternOfEntry<TExisting[K]> extends PatternOfEntry<TNew[K]>
-    ? PatternOfEntry<TNew[K]> extends PatternOfEntry<TExisting[K]>
-      ? never // Same pattern, no conflict
-      : K // Different patterns, conflict
-    : K; // Different patterns, conflict
-}[keyof TExisting & keyof TNew];
-
-/**
- * Error type returned when route keys conflict.
- * Methods require an impossible `never` parameter so TypeScript errors at the call site.
- */
-type RouteConflictError<TConflicts extends string> = {
-  __error: `Route key conflict! Key "${TConflicts}" already exists with a different URL pattern.`;
-  hint: "Route keys must be globally unique. Use prefixed names like 'blog.index' instead of 'index'.";
-  conflictingKeys: TConflicts;
-  // These methods require `never` so calling them produces an error at the call site
-  routes: (
-    __conflict: `Fix route key conflict: "${TConflicts}" is already defined with a different URL pattern`,
-  ) => never;
-  map: (
-    __conflict: `Fix route key conflict: "${TConflicts}" is already defined with a different URL pattern`,
-  ) => never;
-};
-
-/**
- * Simplified route helpers for inline route definitions.
- * Uses TRoutes (Record<string, string>) instead of RouteDefinition.
- *
- * Note: Some helpers use `any` for context types as a trade-off for simpler usage.
- * The main type safety is in the `route` helper which enforces valid route names.
- * For full type safety, use the standard map() API with separate handler files.
- */
-type InlineRouteHelpers<TRoutes extends Record<string, string>, TEnv> = {
-  /**
-   * Define a route handler for a specific route pattern
-   */
-  route: <K extends keyof TRoutes & string>(
-    name: K,
-    handler:
-      | ((ctx: HandlerContext<{}, TEnv>) => ReactNode | Promise<ReactNode>)
-      | ReactNode,
-  ) => AllUseItems;
-
-  /**
-   * Define a layout that wraps child routes
-   */
-  layout: (
-    component:
-      | ReactNode
-      | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>),
-    use?: () => AllUseItems[],
-  ) => AllUseItems;
-
-  /**
-   * Define parallel routes
-   */
-  parallel: (
-    slots: Record<
-      `@${string}`,
-      | ReactNode
-      | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>)
-    >,
-    use?: () => AllUseItems[],
-  ) => AllUseItems;
-
-  /**
-   * Define route middleware
-   */
-  middleware: (
-    fn: (ctx: any, next: () => Promise<void>) => Promise<void>,
-  ) => AllUseItems;
-
-  /**
-   * Define revalidation handlers
-   */
-  revalidate: (fn: (ctx: any) => boolean | Promise<boolean>) => AllUseItems;
-
-  /**
-   * Define data loaders
-   */
-  loader: (loader: any, use?: () => AllUseItems[]) => AllUseItems;
-
-  /**
-   * Define loading states
-   */
-  loading: (component: ReactNode) => AllUseItems;
-
-  /**
-   * Define error boundaries
-   */
-  errorBoundary: (
-    handler: ReactNode | ((props: { error: Error }) => ReactNode),
-  ) => AllUseItems;
-
-  /**
-   * Define not found boundaries
-   */
-  notFoundBoundary: (
-    handler: ReactNode | ((props: { pathname: string }) => ReactNode),
-  ) => AllUseItems;
-
-  /**
-   * Define intercept routes
-   */
-  intercept: (
-    name: string,
-    handler:
-      | ReactNode
-      | ((ctx: HandlerContext<any, TEnv>) => ReactNode | Promise<ReactNode>),
-    use?: () => AllUseItems[],
-  ) => AllUseItems;
-
-  /**
-   * Define when conditions for intercepts
-   */
-  when: (condition: (ctx: any) => boolean | Promise<boolean>) => AllUseItems;
-
-  /**
-   * Define cache configuration
-   */
-  cache: (
-    config: { ttl?: number; swr?: number } | false,
-    use?: () => AllUseItems[],
-  ) => AllUseItems;
-};
-
-/**
- * Router builder for chaining .use() and .map()
- * TRoutes accumulates all registered route types through the chain
- * TLocalRoutes contains the routes for the current .routes() call (for inline handler typing)
- */
-interface RouteBuilder<
-  T extends RouteDefinition,
-  TEnv,
-  TRoutes extends Record<string, unknown>,
-  TLocalRoutes extends Record<string, string> = Record<string, string>,
-> {
-  /**
-   * Add middleware scoped to this mount
-   * Called between .routes() and .map()
-   *
-   * @example
-   * ```typescript
-   * .routes("/admin", adminRoutes)
-   * .use(authMiddleware)           // All of /admin/*
-   * .use("/danger/*", superAuth)   // Only /admin/danger/*
-   * .map(() => import("./admin"))
-   * ```
-   */
-  use(
-    patternOrMiddleware: string | MiddlewareFn<TEnv>,
-    middleware?: MiddlewareFn<TEnv>,
-  ): RouteBuilder<T, TEnv, TRoutes, TLocalRoutes>;
-
-  /**
-   * Map routes to handlers
-   *
-   * Supports two patterns:
-   *
-   * 1. Lazy loading (code-split):
-   * ```typescript
-   * .routes(homeRoutes)
-   * .map(() => import("./handlers/home"))
-   * ```
-   *
-   * 2. Inline definition:
-   * ```typescript
-   * .routes({ index: "/", about: "/about" })
-   * .map(({ route }) => [
-   *   route("index", () => <HomePage />),
-   *   route("about", () => <AboutPage />),
-   * ])
-   * ```
-   */
-  // Inline definition overload - handler receives helpers (must be first for correct inference)
-  // Uses TLocalRoutes so route names don't need the prefix
-  map<
-    H extends (
-      helpers: InlineRouteHelpers<TLocalRoutes, TEnv>,
-    ) => Array<AllUseItems>,
-  >(
-    handler: H,
-  ): RSCRouter<TEnv, TRoutes>;
-  // Lazy loading overload - verifies imported handlers match route definition
-  map(
-    handler: () =>
-      | Array<AllUseItems>
-      | Promise<{ default: RouteHandlers<TLocalRoutes> }>
-      | Promise<RouteHandlers<TLocalRoutes>>,
-  ): RSCRouter<TEnv, TRoutes>;
-
-  /**
-   * Accumulated route map for typeof extraction
-   * Used for module augmentation: `type AppRoutes = typeof _router.routeMap`
-   */
-  readonly routeMap: TRoutes;
-}
-
-/**
- * RSC Router interface
- * TRoutes accumulates all registered route types through the builder chain
- */
-export interface RSCRouter<
-  TEnv = any,
-  TRoutes extends Record<string, unknown> = Record<string, string>,
-> {
-  /**
-   * Brand marker for build-time discovery.
-   * The Vite plugin uses this to identify router instances in module exports.
-   */
-  readonly __brand: typeof RSC_ROUTER_BRAND;
-
-  /**
-   * Unique identifier for this router instance.
-   * Used to namespace static output and isolate route maps between routers.
-   */
-  readonly id: string;
-
-  /**
-   * Register routes with a prefix
-   * Route keys stay unchanged, only URL patterns get the prefix applied.
-   * This enables composable route modules that work regardless of mount point.
-   *
-   * @throws Compile-time error if route keys conflict with previously registered routes
-   */
-  routes<const TPrefix extends string, const T extends Record<string, string>>(
-    prefix: TPrefix,
-    routes: T,
-  ): ConflictingKeys<TRoutes, PrefixRoutePatterns<T, TPrefix>> extends never
-    ? RouteBuilder<
-        RouteDefinition,
-        TEnv,
-        TRoutes & PrefixRoutePatterns<T, TPrefix>,
-        T
-      >
-    : RouteConflictError<
-        ConflictingKeys<TRoutes, PrefixRoutePatterns<T, TPrefix>> & string
-      >;
-
-  /**
-   * Register routes without a prefix
-   * Route types are accumulated through the chain
-   *
-   * @throws Compile-time error if route keys conflict with previously registered routes
-   */
-  routes<const T extends Record<string, string>>(
-    routes: T,
-  ): ConflictingKeys<TRoutes, T> extends never
-    ? RouteBuilder<RouteDefinition, TEnv, TRoutes & T, T>
-    : RouteConflictError<ConflictingKeys<TRoutes, T> & string>;
-
-  /**
-   * Register routes using Django-style URL patterns
-   * This is the new API for @rangojs/router - call once with urls() result
-   *
-   * @example
-   * ```typescript
-   * createRouter({})
-   *   .routes(urlpatterns)  // Single call with urls() result
-   * ```
-   */
-  routes<T extends UrlPatterns<TEnv, any>>(
-    patterns: T,
-  ): RSCRouter<
-    TEnv,
-    TRoutes &
-      (NonNullable<T["_routes"]> extends Record<string, unknown>
-        ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
-        : Record<string, string>)
-  >;
-
-  /**
-   * Add global middleware that runs on all routes
-   * Position matters: middleware before any .routes() is global
-   *
-   * @example
-   * ```typescript
-   * createRouter({ document: RootLayout })
-   *   .use(loggerMiddleware)           // All routes
-   *   .use("/api/*", rateLimiter)      // Pattern match
-   *   .routes(homeRoutes)
-   *   .map(() => import("./home"))
-   * ```
-   */
-  use(
-    patternOrMiddleware: string | MiddlewareFn<TEnv>,
-    middleware?: MiddlewareFn<TEnv>,
-  ): RSCRouter<TEnv, TRoutes>;
-
-  /**
-   * Type-safe URL builder for registered routes
-   * Types are inferred from the accumulated route registrations
-   * Route keys stay unchanged regardless of mount prefix.
-   *
-   * @example
-   * ```typescript
-   * // Given: .routes("/shop", { cart: "/cart", detail: "/product/:slug" })
-   * router.reverse("cart"); // "/shop/cart"
-   * router.reverse("detail", { slug: "widget" }); // "/shop/product/widget"
-   * ```
-   */
-  reverse: ReverseFunction<TRoutes>;
-
-  /**
-   * Accumulated route map for typeof extraction
-   * Used for module augmentation: `type AppRoutes = typeof _router.routeMap`
-   *
-   * @example
-   * ```typescript
-   * const _router = createRouter<AppEnv>()
-   *   .routes(homeRoutes).map(() => import('./home'))
-   *   .routes('/shop', shopRoutes).map(() => import('./shop'));
-   *
-   * type AppRoutes = typeof _router.routeMap;
-   *
-   * declare global {
-   *   namespace RSCRouter {
-   *     interface RegisteredRoutes extends AppRoutes {}
-   *   }
-   * }
-   * ```
-   */
-  readonly routeMap: TRoutes;
-
-  /**
-   * Root layout component that wraps the entire application
-   * Access this to pass to renderSegments
-   */
-  readonly rootLayout?: ComponentType<RootLayoutProps>;
-
-  /**
-   * Error callback for monitoring/alerting
-   * Called when errors occur in loaders, actions, or routes
-   */
-  readonly onError?: RSCRouterOptions<TEnv>["onError"];
-
-  /**
-   * Cache configuration (for internal use by RSC handler)
-   */
-  readonly cache?: RSCRouterOptions<TEnv>["cache"];
-
-  /**
-   * Not found component to render when no route matches (for internal use by RSC handler)
-   */
-  readonly notFound?: RSCRouterOptions<TEnv>["notFound"];
-
-  /**
-   * Resolved theme configuration (null if theme not enabled)
-   * Used by NavigationProvider to include ThemeProvider and by MetaTags to render theme script
-   */
-  readonly themeConfig: import("./theme/types.js").ResolvedThemeConfig | null;
-
-  /**
-   * Whether connection warmup is enabled.
-   * When true, the client sends HEAD /?_rsc_warmup after idle periods
-   * and the server responds with 204 No Content.
-   */
-  readonly warmupEnabled: boolean;
-
-  /**
-   * Whether ?__debug_manifest is allowed in production.
-   * Always enabled in development.
-   * @internal
-   */
-  readonly allowDebugManifest: boolean;
-
-  /**
-   * App-level middleware entries (for internal use by RSC handler)
-   * These wrap the entire request/response cycle
-   */
-  readonly middleware: MiddlewareEntry<TEnv>[];
-
-  /**
-   * Nonce provider for CSP (for internal use by createHandler)
-   */
-  readonly nonce?: NonceProvider<TEnv>;
-
-  /**
-   * RSC version string (for internal use by createHandler)
-   */
-  readonly version?: string;
-
-  /**
-   * URL patterns reference for build-time manifest generation
-   * @internal
-   */
-  readonly urlpatterns?: UrlPatterns<TEnv, any>;
-
-  /**
-   * Source file path where createRouter() was called.
-   * Set via Error.stack parsing at construction time.
-   * Used by the Vite plugin to write per-router named-routes.gen.ts files.
-   * @internal
-   */
-  readonly __sourceFile?: string;
-
-  match(request: Request, context: TEnv): Promise<MatchResult>;
-
-  /**
-   * Build-time pre-render match. Resolves segments with a BuildContext
-   * (no request/env/headers/cookies), skipping middleware and loaders.
-   * Used by the Vite plugin to collect pre-render data at build time.
-   * @internal
-   */
-  matchForPrerender(
-    pathname: string,
-    params: Record<string, string>,
-  ): Promise<{
-    segments: SerializedSegmentData[];
-    handles: Record<string, SegmentHandleData>;
-    routeName: string;
-    params: Record<string, string>;
-  } | null>;
-
-  /**
-   * Preview match - returns route middleware without segment resolution.
-   * Also returns responseType and handler for response routes (non-RSC short-circuit).
-   */
-  previewMatch(
-    request: Request,
-    context: TEnv,
-  ): Promise<{
-    routeMiddleware?: Array<{
-      handler: import("./router/middleware.js").MiddlewareFn;
-      params: Record<string, string>;
-    }>;
-    responseType?: string;
-    handler?: Function;
-    params?: Record<string, string>;
-    negotiated?: boolean;
-  } | null>;
-
-  matchPartial(
-    request: Request,
-    context: TEnv,
-    actionContext?: {
-      actionId?: string;
-      actionUrl?: URL;
-      actionResult?: any;
-      formData?: FormData;
-    },
-  ): Promise<MatchResult | null>;
-
-  /**
-   * Match an error to the nearest error boundary and return error segments
-   *
-   * Used when an action or other operation fails and we need to render
-   * the error boundary UI. Finds the nearest errorBoundary in the route tree
-   * for the current URL and renders it with the error info.
-   *
-   * @param request - The current request (used to match the route)
-   * @param context - Environment context
-   * @param error - The error that occurred
-   * @param segmentType - Type of segment where error occurred (default: "route")
-   * @returns MatchResult with error segment, or null if no error boundary found
-   */
-  matchError(
-    request: Request,
-    context: TEnv,
-    error: unknown,
-    segmentType?: ErrorInfo["segmentType"],
-  ): Promise<MatchResult | null>;
-
-  /**
-   * @internal
-   * Debug utility to serialize the manifest for inspection
-   * Returns a JSON-friendly representation of all routes and layouts
-   */
-  debugManifest(): Promise<SerializedManifest>;
-
-  /**
-   * Handle an RSC request.
-   *
-   * Uses the router's configuration (nonce, version, cache) automatically.
-   * The handler is lazily created on first call.
-   *
-   * @example Cloudflare Workers
-   * ```tsx
-   * import { router } from "./router";
-   *
-   * export default { fetch: router.fetch };
-   * ```
-   *
-   * @example Direct export
-   * ```tsx
-   * const router = createRouter({
-   *   document: Document,
-   *   urls: urlpatterns,
-   *   nonce: () => true,
-   * });
-   *
-   * export const fetch = router.fetch;
-   * ```
-   */
-  fetch(
-    request: Request,
-    env: TEnv & { ctx?: ExecutionContext },
-  ): Promise<Response>;
-}
+// Extracted router types and registry
+import {
+  RSC_ROUTER_BRAND,
+  RouterRegistry,
+  nextRouterAutoId,
+} from "./router/router-registry.js";
+import type { RangoOptions, RootLayoutProps } from "./router/router-options.js";
+import type {
+  Rango,
+  RangoInternal,
+  RouterRequestInput,
+} from "./router/router-interfaces.js";
 
-/**
- * Create an RSC router with generic context type
- * Route types are accumulated automatically through the builder chain
- *
- * @example
- * ```typescript
- * interface AppContext {
- *   db: Database;
- *   user?: User;
- * }
- *
- * const router = createRouter<AppContext>({
- *   debugPerformance: true  // Enable metrics
- * });
- *
- * // Route types accumulate through the chain - no module augmentation needed!
- * // Keys stay unchanged, only URL patterns get the prefix
- * router
- *   .routes(homeRoutes)          // accumulates homeRoutes
- *   .map(() => import('./home'))
- *   .routes('/shop', shopRoutes) // accumulates shopRoutes with prefixed URLs
- *   .map(() => import('./shop'));
- *
- * // router.reverse now has type-safe autocomplete for all registered routes
- * // Given shopRoutes = { cart: "/cart" }, reverse uses original key:
- * router.reverse("cart"); // "/shop/cart"
- * ```
- */
+// Extracted closure functions
+import {
+  findLazyIncludes,
+  evaluateLazyEntry as _evaluateLazyEntry,
+  type LazyEvalDeps,
+} from "./router/lazy-includes.js";
+import { createFindMatch } from "./router/find-match.js";
+import {
+  matchForPrerender as _matchForPrerender,
+  renderStaticSegment as _renderStaticSegment,
+} from "./router/prerender-match.js";
+import { resolveStateCookieName } from "./router/state-cookie-name.js";
+
+// Re-export public types and values from extracted modules
+export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
+export type {
+  RangoOptions,
+  RootLayoutProps,
+  SSRStreamMode,
+  SSROptions,
+  ResolveStreamingContext,
+} from "./router/router-options.js";
+export type {
+  Rango,
+  RangoInternal,
+  RouterRequestInput,
+} from "./router/router-interfaces.js";
+export { toInternal } from "./router/router-interfaces.js";
 
 export function createRouter<TEnv = any>(
-  options: RSCRouterOptions<TEnv> = {},
-): RSCRouter<TEnv, {}> {
+  options: RangoOptions<TEnv> = {},
+): Rango<TEnv, {}> {
   const {
     id: userProvidedId,
     $$id: injectedId,
+    basename: basenameOption,
     debugPerformance = false,
     document: documentOption,
     defaultErrorBoundary,
@@ -1147,38 +141,106 @@ export function createRouter<TEnv = any>(
     notFound,
     onError,
     cache,
+    cacheProfiles: cacheProfilesOption,
     theme: themeOption,
     urls: urlsOption,
     $$routeNames: staticRouteNames,
+    $$sourceFile: injectedSourceFile,
     nonce,
     version,
+    prefetchCacheTTL: prefetchCacheTTLOption,
+    stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
-    allowDebugManifest: allowDebugManifestOption = true,
+    allowDebugManifest: allowDebugManifestOption = false,
+    telemetry: telemetrySink,
+    tracing: tracingOption,
+    ssr: ssrOption,
+    timeout: timeoutShorthand,
+    timeouts: timeoutsOption,
+    onTimeout,
+    originCheck: originCheckOption,
+    viewTransition: viewTransitionOption = "auto",
+    debugCacheSignal: debugCacheSignalOption = false,
   } = options;
 
-  // Capture the source file that called createRouter() via stack trace parsing.
-  // Used by the Vite plugin to write per-router named-routes.gen.ts files.
-  let __sourceFile: string | undefined;
-  try {
-    const stack = new Error().stack;
-    if (stack) {
-      const lines = stack.split("\n");
-      for (const line of lines) {
-        const match = line.match(/\((.+?\.(ts|tsx|js|jsx)):\d+:\d+\)/);
-        if (match && !match[1].endsWith("/router.ts") && !match[1].includes("@rangojs/router") && !match[1].includes("node_modules")) {
-          // Strip file: URL protocol prefix from Vite module runner stack traces
-          __sourceFile = match[1].startsWith("file:") ? match[1].slice(5) : match[1];
-          break;
+  // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
+  // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
+  // no X-Rango-Cache header is emitted and output is byte-identical.
+  const cacheSignalEnabled =
+    debugCacheSignalOption ||
+    (typeof process !== "undefined" &&
+      (process as { env?: Record<string, string | undefined> }).env
+        ?.RANGO_TEST_SIGNALS === "1");
+
+  // Normalize basename: ensure leading slash, strip trailing slash.
+  // A bare "/" is equivalent to no basename. Shared with the testing
+  // primitives via normalizeBasename so they can never drift.
+  const basename = normalizeBasename(basenameOption);
+
+  // Resolve telemetry sink (no-op when not configured)
+  const telemetry = resolveSink(telemetrySink);
+
+  // Resolve span tracing (undefined when not configured; every traceSpan() call
+  // is then a direct pass-through with zero behavior change).
+  const resolvedTracing = resolveTracing(tracingOption);
+
+  // Resolve cache profiles: merge user config with the guaranteed default
+  // profile. This resolved map is threaded onto each request context; the
+  // "use cache: <profile>" runtime path reads it request-scoped.
+  const resolvedCacheProfiles = resolveCacheProfiles(cacheProfilesOption);
+
+  // Source file: prefer Vite-injected path (zero cost), fall back to
+  // stack trace parsing for non-Vite environments (e.g. tests).
+  let __sourceFile: string | undefined = injectedSourceFile;
+  if (!__sourceFile) {
+    try {
+      const stack = new Error().stack;
+      if (stack) {
+        const lines = stack.split("\n");
+        for (const line of lines) {
+          const match = line.match(/\((.+?\.(ts|tsx|js|jsx)):\d+:\d+\)/);
+          if (
+            match &&
+            !match[1].endsWith("/router.ts") &&
+            !match[1].includes("@rangojs/router") &&
+            !match[1].includes("node_modules")
+          ) {
+            __sourceFile = match[1].startsWith("file:")
+              ? match[1].slice(5)
+              : match[1];
+            break;
+          }
         }
       }
-    }
-  } catch {}
+    } catch {}
+  }
 
   // Router ID priority: explicit id > Vite-injected $$id > counter fallback.
   // $$id is a hash of filename+line injected by the Vite transform at compile
   // time, so it's stable across build/runtime regardless of module evaluation
   // order (unlike the counter which depends on import order).
-  const routerId = userProvidedId ?? injectedId ?? `router_${routerAutoId++}`;
+  const routerId =
+    userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
+
+  // Resolve the rango state cookie name once, here, so the two cookie writers
+  // (the client document.cookie writer and the server Set-Cookie writer)
+  // consume one pre-composed name and cannot drift.
+  const resolvedStateCookieName = resolveStateCookieName(
+    stateCookiePrefixOption,
+    routerId,
+  );
+
+  // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
+  // Clamp to a non-negative integer for valid Cache-Control max-age.
+  const rawTTL =
+    prefetchCacheTTLOption !== undefined ? prefetchCacheTTLOption : 300;
+  const prefetchCacheTTLSeconds =
+    rawTTL === false ? 0 : Math.max(0, Math.floor(rawTTL));
+  const prefetchCacheTTL = prefetchCacheTTLSeconds * 1000;
+  const prefetchCacheControl: string | false =
+    prefetchCacheTTLSeconds === 0
+      ? false
+      : `private, max-age=${prefetchCacheTTLSeconds}`;
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
@@ -1188,21 +250,40 @@ export function createRouter<TEnv = any>(
     ? resolveThemeConfig(themeOption)
     : null;
 
+  // Resolve timeout config (merge shorthand + structured)
+  const resolvedTimeouts = resolveTimeouts(timeoutShorthand, timeoutsOption);
+
   /**
    * Wrapper for invokeOnError that binds the router's onError callback.
    * Uses the shared utility from router/error-handling.ts for consistent behavior.
+   *
+   * Deduplicates via per-request WeakSet stored on the ALS request context.
+   * A closure-level WeakSet would silently swallow errors if the same object
+   * instance is thrown across separate requests (e.g. a singleton error).
    */
   function callOnError(
     error: unknown,
     phase: ErrorPhase,
     context: Parameters<typeof invokeOnError<TEnv>>[3],
   ): void {
+    if (error != null && typeof error === "object") {
+      const reportedErrors = _getRequestContext()?._reportedErrors;
+      if (reportedErrors) {
+        if (reportedErrors.has(error)) return;
+        reportedErrors.add(error);
+      }
+    }
     invokeOnError(onError, error, phase, context, "Router");
   }
 
-  // Validate document is a client component
+  // Validate document is a client component. Under a test runner the "use
+  // client" transform has not run, so a real exported document has no marker;
+  // allowServerInTest lets the router construct in a bare unit test (for
+  // dispatch / assertGeneratedRoutesMatch) while a real build still throws.
   if (documentOption !== undefined) {
-    assertClientComponent(documentOption, "document");
+    assertClientComponent(documentOption, "document", {
+      allowServerInTest: true,
+    });
   }
 
   // Use default document if none provided (keeps internal name as rootLayout)
@@ -1239,6 +320,18 @@ export function createRouter<TEnv = any>(
       handler = patternOrMiddleware;
     }
 
+    // Prevent "use cache" functions from being used as middleware.
+    // They return data/JSX and do not call next() — silently accepting
+    // them would be a confusing no-op.
+    if (isCachedFunction(handler)) {
+      throw new Error(
+        `A "use cache" function cannot be used as middleware. ` +
+          `Cached functions return data and do not participate in the ` +
+          `middleware chain. Remove the "use cache" directive or use a ` +
+          `regular middleware function instead.`,
+      );
+    }
+
     // If mount-scoped, prepend mount prefix to pattern
     let fullPattern = pattern;
     if (mountPrefix && pattern) {
@@ -1264,836 +357,264 @@ export function createRouter<TEnv = any>(
       regex,
       paramNames,
       handler,
-      mountPrefix,
     });
   }
 
-  // Track all registered routes with their prefixes for reverse()
-  const mergedRouteMap: Record<string, string> = {};
-
-  // Lazy precomputed entries lookup: rebuilt when per-router data arrives.
-  // In production multi-router setups, per-router data is loaded lazily via
-  // ensureRouterManifest(). At createRouter() time the data isn't available yet,
-  // so we defer building the Map until first use and invalidate when the
-  // per-router source changes.
-  let precomputedByPrefix: Map<string, Record<string, string>> | null = null;
-  let precomputedSource: Array<{ staticPrefix: string; routes: Record<string, string> }> | null | undefined;
-
-  function getPrecomputedByPrefix(): Map<string, Record<string, string>> | null {
-    const current = getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
-    if (current !== precomputedSource) {
-      precomputedSource = current;
-      precomputedByPrefix = current
-        ? new Map(current.map((e) => [e.staticPrefix, e.routes]))
-        : null;
-    }
-    return precomputedByPrefix;
-  }
-
-
-  // Wrapper to pass debugPerformance to external createMetricsStore
-  const getMetricsStore = () => createMetricsStore(debugPerformance);
-
-  // Wrapper to pass defaults to error/notFound boundary finders
-  const findNearestErrorBoundary = (entry: EntryData | null) =>
-    findErrorBoundary(entry, defaultErrorBoundary);
-
-  const findNearestNotFoundBoundary = (entry: EntryData | null) =>
-    findNotFoundBoundary(entry, defaultNotFoundBoundary);
-
-  // Helper to get handleStore from request context
-  const getHandleStore = (): HandleStore | undefined => {
-    return getRequestContext()?._handleStore;
-  };
-
-  // Track a pending handler promise (non-blocking)
-  const trackHandler = <T>(promise: Promise<T>): Promise<T> => {
-    const store = getHandleStore();
-    return store ? store.track(promise) : promise;
-  };
-
-  // Wrapper for wrapLoaderWithErrorHandling that uses router's error boundary finder
-  // Includes onError callback for loader error notification
-  function wrapLoaderPromise<T>(
-    promise: Promise<T>,
-    entry: EntryData,
-    segmentId: string,
-    pathname: string,
-    errorContext?: {
-      request: Request;
-      url: URL;
-      routeKey?: string;
-      params?: Record<string, string>;
-      env?: TEnv;
-      isPartial?: boolean;
-      requestStartTime?: number;
-    },
-  ): Promise<LoaderDataResult<T>> {
-    return wrapLoaderWithErrorHandling(
-      promise,
-      entry,
-      segmentId,
-      pathname,
-      findNearestErrorBoundary,
-      createErrorInfo,
-      // Invoke onError when loader fails
-      errorContext
-        ? (error, ctx) => {
-            callOnError(error, "loader", {
-              request: errorContext.request,
-              url: errorContext.url,
-              routeKey: errorContext.routeKey,
-              params: errorContext.params,
-              segmentId: ctx.segmentId,
-              segmentType: "loader",
-              loaderName: ctx.loaderName,
-              env: errorContext.env,
-              isPartial: errorContext.isPartial,
-              handledByBoundary: ctx.handledByBoundary,
-              requestStartTime: errorContext.requestStartTime,
-            });
-          }
-        : undefined,
-    );
-  }
-
-  // Dependencies object for extracted segment resolution functions.
-  // Captures closure-bound helpers from createRouter.
-  const segmentDeps: SegmentResolutionDeps<TEnv> = {
-    wrapLoaderPromise,
-    trackHandler,
-    findNearestErrorBoundary,
-    findNearestNotFoundBoundary,
-    callOnError,
-  };
-
-  // Match API dependencies
-  const matchApiDeps: MatchApiDeps<TEnv> = {
-    findMatch: (pathname: string, ms?: any) => findMatch(pathname, ms),
-    getMetricsStore,
-    findInterceptForRoute: (routeKey, parentEntry, selectorContext, isAction) =>
-      findInterceptForRoute(routeKey, parentEntry, selectorContext, isAction),
-    callOnError,
-    findNearestErrorBoundary,
-    getRouteMap: () => getRouterManifest(routerId) ?? getGlobalRouteMap(),
-  };
-
-  // Thin wrappers that bind the deps to extracted functions.
-  // These maintain the same signatures as the original inline functions
-  // so that RouterContext and call sites don't need to change.
-
-  function resolveAllSegments(
-    entries: EntryData[],
-    routeKey: string,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    loaderPromises: Map<string, Promise<any>>,
-    options?: { skipLoaders?: boolean },
-  ) {
-    return _resolveAllSegments(entries, routeKey, params, context, loaderPromises, segmentDeps, options);
-  }
-
-  function resolveLoadersOnly(
-    entries: EntryData[],
-    context: HandlerContext<any, TEnv>,
-  ) {
-    return _resolveLoadersOnly(entries, context, segmentDeps);
-  }
-
-  function resolveLoadersOnlyWithRevalidation(
-    entries: EntryData[],
-    context: HandlerContext<any, TEnv>,
-    clientSegmentIds: Set<string>,
-    prevParams: Record<string, string>,
-    request: Request,
-    prevUrl: URL,
-    nextUrl: URL,
-    routeKey: string,
-    actionContext?: { actionId?: string; actionUrl?: URL; actionResult?: any; formData?: FormData },
-  ) {
-    return _resolveLoadersOnlyWithRevalidation(
-      entries, context, clientSegmentIds, prevParams, request,
-      prevUrl, nextUrl, routeKey, segmentDeps, actionContext,
-    );
-  }
-
-  function buildEntryRevalidateMap(entries: EntryData[]) {
-    return _buildEntryRevalidateMap(entries);
-  }
-
-  function resolveAllSegmentsWithRevalidation(
-    entries: EntryData[],
-    routeKey: string,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    clientSegmentSet: Set<string>,
-    prevParams: Record<string, string>,
-    request: Request,
-    prevUrl: URL,
-    nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
-    actionContext: { actionId?: string; actionUrl?: URL; actionResult?: any; formData?: FormData } | undefined,
-    interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
-    localRouteName: string,
-    pathname: string,
-  ) {
-    return _resolveAllSegmentsWithRevalidation(
-      entries, routeKey, params, context, clientSegmentSet, prevParams, request,
-      prevUrl, nextUrl, loaderPromises, actionContext, interceptResult,
-      localRouteName, pathname, segmentDeps,
-    );
-  }
-
-  function findInterceptForRoute(
-    targetRouteKey: string,
-    fromEntry: EntryData | null,
-    selectorContext: InterceptSelectorContext | null = null,
-    isAction: boolean = false,
-  ) {
-    return _findInterceptForRoute(targetRouteKey, fromEntry, selectorContext, isAction);
-  }
-
-  function resolveInterceptEntry(
-    interceptEntry: InterceptEntry,
-    parentEntry: EntryData,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    belongsToRoute: boolean = true,
-    revalidationContext?: any,
-  ) {
-    return _resolveInterceptEntry(
-      interceptEntry, parentEntry, params, context, belongsToRoute,
-      segmentDeps, revalidationContext,
-    );
-  }
-
-  function resolveInterceptLoadersOnly(
-    interceptEntry: InterceptEntry,
-    parentEntry: EntryData,
-    params: Record<string, string>,
-    context: HandlerContext<any, TEnv>,
-    belongsToRoute: boolean = true,
-    revalidationContext: any,
-  ) {
-    return _resolveInterceptLoadersOnly(
-      interceptEntry, parentEntry, params, context, belongsToRoute,
-      segmentDeps, revalidationContext,
-    );
-  }
-
-  // Detect lazy includes in handler result and create placeholder entries
-  // Lazy includes are IncludeItem with lazy: true and _lazyContext
-  // Moved to outer scope so it can be reused by evaluateLazyEntry for nested includes
-  function findLazyIncludes(items: AllUseItems[]): Array<{
-    prefix: string;
-    patterns: UrlPatterns<TEnv>;
-    context: {
-      urlPrefix: string;
-      namePrefix: string | undefined;
-      parent: unknown;
-    };
-  }> {
-    const lazyItems: Array<{
-      prefix: string;
-      patterns: UrlPatterns<TEnv>;
-      context: {
-        urlPrefix: string;
-        namePrefix: string | undefined;
-        parent: unknown;
-      };
-    }> = [];
-
-    for (const item of items) {
-      if (!item) continue;
-      if (item.type === "include") {
-        const includeItem = item as IncludeItem;
-        if (includeItem.lazy === true && includeItem._lazyContext) {
-          lazyItems.push({
-            prefix: includeItem.prefix,
-            patterns: includeItem.patterns as UrlPatterns<TEnv>,
-            context: includeItem._lazyContext,
-          });
-        }
-      }
-      // Recursively check nested items (in layouts, etc.)
-      if ((item as any).uses && Array.isArray((item as any).uses)) {
-        lazyItems.push(...findLazyIncludes((item as any).uses));
-      }
-    }
-
-    return lazyItems;
-  }
-
-  /**
-   * Evaluate a lazy entry's patterns and populate its routes
-   * This runs the lazy patterns handler and updates the entry in-place
-   * Also detects nested lazy includes and registers them as new entries
-   */
-  function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
-    if (!entry.lazy || entry.lazyEvaluated || !entry.lazyPatterns) {
-      return;
-    }
-
-    // Check for pre-computed routes from build-time data.
-    // Only leaf nodes (no nested includes) are precomputed, so entries with
-    // nested lazy includes fall through to the handler below.
-    // When multiple entries share the same staticPrefix (e.g., several
-    // include("/", ...) calls), the precomputed data merges all their routes
-    // into one entry. Assigning that merged set to the first matching entry
-    // causes findMatch to pick the wrong handler for routes belonging to a
-    // different include. Skip the shortcut when the prefix is shared.
-    const currentPrecomputed = getPrecomputedByPrefix();
-    if (currentPrecomputed) {
-      const routes = currentPrecomputed.get(entry.staticPrefix);
-      if (routes) {
-        const prefixIsShared = routesEntries.filter(
-          (e) => e.staticPrefix === entry.staticPrefix,
-        ).length > 1;
-        if (!prefixIsShared) {
-          entry.lazyEvaluated = true;
-          entry.routes = routes as ResolvedRouteMap<any>;
-          for (const [name, pattern] of Object.entries(routes)) {
-            mergedRouteMap[name] = pattern;
-          }
-          registerRouteMap(mergedRouteMap);
-          return;
-        }
-      }
-    }
-
-    // Mark as evaluated immediately to prevent concurrent evaluation.
-    // JS is single-threaded but handlers.handler() could theoretically yield,
-    // and the while-loop in findMatch retries after evaluation.
-    entry.lazyEvaluated = true;
-
-    const lazyPatterns = entry.lazyPatterns as UrlPatterns<TEnv>;
-    const lazyContext = entry.lazyContext;
-
-    // Create a new context for evaluating the lazy patterns
-    const manifest = new Map<string, EntryData>();
-    const patterns = new Map<string, string>();
-    const patternsByPrefix = new Map<string, Map<string, string>>();
-    const trailingSlashMap = new Map<string, TrailingSlashMode>();
-
-    // Capture the handler result to detect nested lazy includes
-    let handlerResult: AllUseItems[] = [];
-
-    // Merge captured counters from include() to maintain consistent
-    // shortCode indices with sibling entries from pattern extraction
-    const lazyCounters: Record<string, number> = {};
-    if (lazyContext && (lazyContext as any).counters) {
-      const captured = (lazyContext as any).counters as Record<string, number>;
-      for (const [key, value] of Object.entries(captured)) {
-        lazyCounters[key] = value;
-      }
-    }
-
-    RSCRouterContext.run(
-      {
-        manifest,
-        patterns,
-        patternsByPrefix,
-        trailingSlash: trailingSlashMap,
-        namespace: "lazy",
-        parent: (lazyContext?.parent as EntryData | null) ?? null,
-        counters: lazyCounters,
-      },
-      () => {
-        // Run the lazy patterns handler with the original context prefixes
-        // The prefix comes from the IncludeItem stored in lazyPatterns
-        const includePrefix = (entry as any)._lazyPrefix || "";
-        const fullPrefix = (lazyContext?.urlPrefix || "") + includePrefix;
-
-        if (fullPrefix || lazyContext?.namePrefix) {
-          runWithPrefixes(fullPrefix, lazyContext?.namePrefix, () => {
-            handlerResult = lazyPatterns.handler() as AllUseItems[];
-          });
-        } else {
-          handlerResult = lazyPatterns.handler() as AllUseItems[];
-        }
-      },
-    );
-
-    // Populate the entry's routes from the patterns
-    const routesObject: Record<string, string> = {};
-    for (const [name, pattern] of patterns.entries()) {
-      routesObject[name] = pattern;
-      // Also add to merged route map for reverse() support
-      const existingPattern = mergedRouteMap[name];
-      if (existingPattern !== undefined && existingPattern !== pattern) {
-        console.warn(
-          `[@rangojs/router] Route name conflict: "${name}" already maps to "${existingPattern}", ` +
-            `overwriting with "${pattern}" (from lazy include). Use unique route names to avoid this.`,
-        );
-      }
-      mergedRouteMap[name] = pattern;
-    }
-
-    // Update the entry in-place
-    entry.routes = routesObject as ResolvedRouteMap<any>;
-
-    // Note: Do NOT clear lazyPatterns/lazyContext here.
-    // loadManifest() needs them on every request to re-run the handler
-    // in the correct AsyncLocalStorage context (Store.manifest).
-
-    // Update trailing slash config if available
-    if (trailingSlashMap.size > 0) {
-      entry.trailingSlash = Object.fromEntries(trailingSlashMap);
-    }
-
-    // Detect nested lazy includes and register them as new entries
-    const nestedLazyIncludes = findLazyIncludes(handlerResult);
-    for (const lazyInclude of nestedLazyIncludes) {
-      // Compute the full URL prefix (combining parent prefix if any)
-      const fullPrefix = lazyInclude.context.urlPrefix
-        ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-        : lazyInclude.prefix;
-
-      const nestedEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
-        prefix: "",
-        staticPrefix: extractStaticPrefix(fullPrefix),
-        routes: {} as ResolvedRouteMap<any>, // Empty until first match
-        trailingSlash: entry.trailingSlash,
-        handler: (lazyInclude.patterns as UrlPatterns<TEnv>).handler,
-        mountIndex: entry.mountIndex,
-        // Lazy evaluation fields
-        lazy: true,
-        lazyPatterns: lazyInclude.patterns,
-        lazyContext: lazyInclude.context,
-        lazyEvaluated: false,
-        // Store the include prefix for evaluation
-        _lazyPrefix: lazyInclude.prefix,
-      };
-      // Insert nested lazy entry before any entry whose staticPrefix is a
-      // prefix of (but shorter than) this lazy entry's staticPrefix.
-      // This ensures more specific lazy includes are matched before
-      // less specific eager entries (e.g., "/href/nested" before "/href/:id").
-      const nestedPrefix = nestedEntry.staticPrefix;
-      let insertIndex = routesEntries.length;
-      if (nestedPrefix) {
-        for (let i = 0; i < routesEntries.length; i++) {
-          const existing = routesEntries[i]!;
-          if (
-            nestedPrefix.startsWith(existing.staticPrefix) &&
-            nestedPrefix.length > existing.staticPrefix.length
-          ) {
-            insertIndex = i;
-            break;
-          }
-        }
-      }
-      routesEntries.splice(insertIndex, 0, nestedEntry);
-    }
-
-    // Re-register route map for runtime reverse() usage
-    registerRouteMap(mergedRouteMap);
-  }
-
-  // Single-entry cache for findMatch to avoid redundant matching within the same request.
-  // previewMatch and match both call findMatch with the same pathname — this ensures
-  // the route matching work (which may check thousands of routes) only happens once.
-  let lastFindMatchPathname: string | null = null;
-  let lastFindMatchResult: RouteMatchResult<TEnv> | null = null;
-
-  // Wrapper for findMatch that uses routesEntries
-  // Handles lazy evaluation by evaluating lazy entries on first match.
-  // Phase 1: try O(path_length) trie match.
-  // Phase 2: fall back to regex iteration.
-  function findMatch(
-    pathname: string,
-    ms?: MetricsStore,
-  ): RouteMatchResult<TEnv> | null {
-    // Return cached result if same pathname (avoids double-match per request)
-    if (lastFindMatchPathname === pathname) {
-      return lastFindMatchResult;
-    }
-
-    // Helper to push sub-metrics
-    const pushMetric = ms
-      ? (label: string, start: number) => {
-          ms.metrics.push({
-            label,
-            duration: performance.now() - start,
-            startTime: start - ms.requestStart,
-          });
-        }
-      : undefined;
-
-    // Phase 1: Try trie match (O(path_length))
-    // Prefer per-router trie (isolated) over global trie (merged).
-    const routeTrie = getRouterTrie(routerId) ?? getRouteTrie();
-    if (routeTrie) {
-      const trieStart = performance.now();
-      const trieResult = tryTrieMatch(routeTrie, pathname);
-      pushMetric?.("match:trie", trieStart);
-
-      if (trieResult) {
-        // Find the RouteEntry that contains this route.
-        // Multiple entries can share the same staticPrefix (e.g., several
-        // include("/", patterns) calls all produce staticPrefix=""). Evaluate
-        // each candidate and pick the one whose routes include the matched key.
-        const entryStart = performance.now();
-        let entry: RouteEntry<TEnv> | undefined;
-        let fallbackEntry: RouteEntry<TEnv> | undefined;
-
-        for (const e of routesEntries) {
-          if (e.staticPrefix !== trieResult.sp) continue;
-          if (!fallbackEntry) fallbackEntry = e;
-          evaluateLazyEntry(e);
-          if (
-            e.routes &&
-            trieResult.routeKey in (e.routes as Record<string, unknown>)
-          ) {
-            entry = e;
-            break;
-          }
-        }
-
-        // If no entry had the route in its routes map, use the first matching
-        // entry as fallback (handles main entry with inline routes not yet
-        // reflected in its routes object).
-        if (!entry) entry = fallbackEntry;
-
-        // If entry not found (nested include not yet discovered), evaluate parent
-        if (!entry) {
-          const parent = routesEntries.find(
-            (e) =>
-              trieResult.sp.startsWith(e.staticPrefix) &&
-              e.staticPrefix !== trieResult.sp,
-          );
-          if (parent) {
-            const lazyStart = performance.now();
-            evaluateLazyEntry(parent);
-            pushMetric?.("match:lazy-eval", lazyStart);
-          }
-          entry = routesEntries.find((e) => e.staticPrefix === trieResult.sp);
-        }
-        pushMetric?.("match:entry-resolve", entryStart);
-
-        if (entry) {
-          lastFindMatchPathname = pathname;
-          lastFindMatchResult = {
-            entry,
-            routeKey: trieResult.routeKey,
-            params: trieResult.params,
-            optionalParams: new Set(trieResult.optionalParams || []),
-            redirectTo: trieResult.redirectTo,
-            ancestry: trieResult.ancestry,
-            ...(trieResult.pr ? { pr: true } : {}),
-            ...(trieResult.pt ? { pt: true } : {}),
-            ...(trieResult.responseType ? { responseType: trieResult.responseType } : {}),
-            ...(trieResult.negotiateVariants ? { negotiateVariants: trieResult.negotiateVariants } : {}),
-            ...(trieResult.rscFirst ? { rscFirst: true } : {}),
-          };
-          return lastFindMatchResult;
-        }
-      }
-    }
-
-    // Phase 2: Fall back to existing matching (regex iteration)
-    const regexStart = performance.now();
-    let result = findRouteMatch(pathname, routesEntries);
-
-    // If we hit a lazy entry that needs evaluation, evaluate and retry.
-    // Cap iterations to prevent infinite loops from pathological nesting.
-    const MAX_LAZY_ITERATIONS = 100;
-    let iterations = 0;
-    while (isLazyEvaluationNeeded(result)) {
-      if (++iterations > MAX_LAZY_ITERATIONS) {
-        console.error(
-          `[@rangojs/router] Exceeded ${MAX_LAZY_ITERATIONS} lazy evaluation iterations ` +
-            `for pathname "${pathname}". This likely indicates circular lazy includes.`,
-        );
-        lastFindMatchPathname = pathname;
-        lastFindMatchResult = null;
-        return null;
-      }
-      evaluateLazyEntry(result.lazyEntry);
-      result = findRouteMatch(pathname, routesEntries);
-    }
-    pushMetric?.("match:regex-fallback", regexStart);
-
-    lastFindMatchPathname = pathname;
-    lastFindMatchResult = result;
-    return result;
-  }
-
-
-  /**
-   * Build-time pre-render match. Resolves segments with a BuildContext
-   * (no request/env/headers/cookies), skipping middleware and loaders.
-   */
-  async function matchForPrerender(
-    pathname: string,
-    params: Record<string, string>,
-  ): Promise<{
-    segments: SerializedSegmentData[];
-    handles: Record<string, SegmentHandleData>;
-    routeName: string;
-    params: Record<string, string>;
-  } | null> {
-    // 1. Find the matching route entry
-    const matched = findMatch(pathname);
-    if (!matched) return null;
-
-    // Use params from trie match if available, fall back to provided params
-    const matchedParams = matched.params ?? params;
-
-    // Build a minimal RouterContext for loadManifest/traverseBack
-    const routerCtx: RouterContext<TEnv> = {
-      findMatch,
-      loadManifest,
-      traverseBack,
-      createHandlerContext,
-      setupLoaderAccess,
-      setupLoaderAccessSilent,
-      getContext,
-      getMetricsStore,
-      createCacheScope,
-      findInterceptForRoute,
-      resolveAllSegmentsWithRevalidation,
-      resolveInterceptEntry,
-      evaluateRevalidation,
-      getRequestContext,
-      resolveAllSegments,
-      createHandleStore,
-      buildEntryRevalidateMap,
-      resolveLoadersOnlyWithRevalidation,
-      resolveInterceptLoadersOnly,
-      resolveLoadersOnly,
-    };
-
-    return runWithRouterContext(routerCtx, async () => {
-      // 2. Load the manifest entry tree
-      const manifestEntry = await loadManifest(
-        matched.entry,
-        matched.routeKey,
-        pathname,
-        undefined,
-        false,
-      );
-
-      // 3. Build ancestor chain [root, ..., route]
-      const entries: EntryData[] = [];
-      for (const entry of traverseBack(manifestEntry)) {
-        entries.push(entry);
-      }
-
-      // 4. Create handle store for collecting handle data
-      const handleStore = createHandleStore();
+  // Track all registered routes with their prefixes for reverse().
+  // Seed from injected NamedRoutes so reverse() works at module load time
+  // for routes that come from lazy includes.
+  const mergedRouteMap: Record<string, string> =
+    flattenNamedRoutes(staticRouteNames);
 
-      // 5. Create a minimal request context with the handle store
-      const stubRes = new Response(null, { status: 200 });
-      const minimalRequestContext: RequestContext<TEnv> = {
-        env: {} as TEnv,
-        request: new Request("http://prerender" + pathname),
-        url: new URL("http://prerender" + pathname),
-        pathname,
-        searchParams: new URLSearchParams(),
-        var: {},
-        get: () => undefined as any,
-        set: () => {},
-        params: matchedParams,
-        res: stubRes,
-        cookie: () => undefined,
-        cookies: () => ({}),
-        setCookie: () => {},
-        deleteCookie: () => {},
-        header: () => {},
-        use: (() => {
-          throw new Error("use() not available during pre-rendering");
-        }) as any,
-        method: "GET",
-        _handleStore: handleStore,
-        waitUntil: () => {},
-        onResponse: () => {},
-        _onResponseCallbacks: [],
-      };
-
-      return runWithRequestContext(minimalRequestContext, async () => {
-        // 6. Create BuildContext (no request/env/headers/cookies)
-        const buildCtx = createBuildContext<TEnv>(
-          matchedParams,
-          pathname,
-          handleStore,
-        );
-
-        // 7. Wire use() for handles only (loaders throw)
-        setupBuildUse(buildCtx);
-
-        // 8. Resolve all segments with skipLoaders
-        const loaderPromises = new Map<string, Promise<any>>();
-        const allSegments = await resolveAllSegments(
-          entries,
-          matched.routeKey,
-          matchedParams,
-          buildCtx,
-          loaderPromises,
-          { skipLoaders: true },
-        );
+  // Track names that came from the static seed so we can silently overwrite
+  // them during routes() registration. The gen file may be stale during HMR,
+  // so conflicts between seeded and runtime-registered values are expected.
+  const seededNames = new Set(Object.keys(mergedRouteMap));
 
-        // 9. Filter out any loader segments (belt-and-suspenders)
-        const nonLoaderSegments = allSegments.filter((s) => s.type !== "loader");
+  // Lazy precomputed entries lookup: rebuilt when per-router data arrives.
+  // In production multi-router setups, per-router data is loaded lazily via
+  // ensureRouterManifest(). At createRouter() time the data isn't available yet,
+  // so we defer building the Map until first use and invalidate when the
+  // per-router source changes.
+  let precomputedByPrefix: Map<string, Record<string, string>> | null = null;
+  let precomputedSource:
+    | Array<{ staticPrefix: string; routes: Record<string, string> }>
+    | null
+    | undefined;
+
+  function getPrecomputedByPrefix(): Map<
+    string,
+    Record<string, string>
+  > | null {
+    const current =
+      getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
+    if (current !== precomputedSource) {
+      precomputedSource = current;
+      // buildPrecomputedByPrefix drops any staticPrefix owned by more than one
+      // leaf include instead of collapsing it last-wins (which would mis-assign
+      // one include's routes to another's entry and 500 a valid sibling route).
+      // Such shared-prefix includes resolve via the handler path instead.
+      precomputedByPrefix = current ? buildPrecomputedByPrefix(current) : null;
+    }
+    return precomputedByPrefix;
+  }
 
-        // 10. Wait for handles to settle
-        await handleStore.settled;
+  // Wrapper to pass debugPerformance to external createMetricsStore.
+  // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  const getMetricsStore = () => {
+    const reqCtx = _getRequestContext();
+    const enabled = debugPerformance || !!reqCtx?._debugPerformance;
+    if (!enabled) return undefined;
+    if (!reqCtx) {
+      return createMetricsStore(true);
+    }
+    reqCtx._metricsStore ??= createMetricsStore(true);
+    return reqCtx._metricsStore;
+  };
 
-        // 11. Serialize segments using the cache serializer
-        const { serializeSegments } = await import("./cache/cache-scope.js");
-        const serializedSegments = await serializeSegments(nonLoaderSegments);
+  // Wrapper to pass defaults to error/notFound boundary finders
+  const findNearestErrorBoundary = (entry: EntryData | null) =>
+    findErrorBoundary(entry, defaultErrorBoundary);
 
-        // 12. Collect handle data per segment (skip segments with no handle data)
-        const handles: Record<string, SegmentHandleData> = {};
-        for (const seg of nonLoaderSegments) {
-          const segHandles = handleStore.getDataForSegment(seg.id);
-          if (Object.keys(segHandles).length > 0) {
-            handles[seg.id] = segHandles;
-          }
-        }
+  const findNearestNotFoundBoundary = (entry: EntryData | null) =>
+    findNotFoundBoundary(entry, defaultNotFoundBoundary);
 
-        // Use the trie-level route key (e.g., "docs", "docs.article")
-        const routeName = matched.routeKey;
+  // Helper to get handleStore from request context
+  const getHandleStore = (): HandleStore | undefined => {
+    return _getRequestContext()?._handleStore;
+  };
 
-        return {
-          segments: serializedSegments,
-          handles,
-          routeName,
-          params: matchedParams,
-        };
+  // Track a pending handler promise (non-blocking).
+  // Attaches a side-effect .catch() to report streaming handler errors to onError
+  // without altering the rejection chain (React's streaming error boundary still handles it).
+  const trackHandler = <T>(
+    promise: Promise<T>,
+    errorContext?: {
+      segmentId?: string;
+      segmentType?: string;
+    },
+  ): Promise<T> => {
+    const store = getHandleStore();
+    const tracked = store ? store.track(promise) : promise;
+
+    // Report streaming handler errors to onError as a side-effect.
+    // The rejection still propagates to the RSC stream for client error boundaries.
+    // Captures request context eagerly (closure) so the catch handler has full context.
+    const reqCtx = _getRequestContext();
+    if (reqCtx && onError) {
+      tracked.catch((error) => {
+        callOnError(error, "handler", {
+          request: reqCtx.request,
+          url: reqCtx.url,
+          routeKey: reqCtx._routeName,
+          params: reqCtx.params as Record<string, string>,
+          env: reqCtx.env as TEnv,
+          segmentId: errorContext?.segmentId,
+          segmentType: errorContext?.segmentType as any,
+          handledByBoundary: true,
+        });
       });
-    });
-  }
+    }
 
-  /**
-   * Match request and return segments (document/SSR requests)
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
-  async function match(request: Request, env: TEnv): Promise<MatchResult> {
-    // Build RouterContext with all closure functions needed by middleware
-    const routerCtx: RouterContext<TEnv> = {
-      findMatch,
-      loadManifest,
-      traverseBack,
-      createHandlerContext,
-      setupLoaderAccess,
-      setupLoaderAccessSilent,
-      getContext,
-      getMetricsStore,
-      createCacheScope,
-      findInterceptForRoute,
-      resolveAllSegmentsWithRevalidation,
-      resolveInterceptEntry,
-      evaluateRevalidation,
-      getRequestContext,
-      resolveAllSegments,
-      createHandleStore,
-      buildEntryRevalidateMap,
-      resolveLoadersOnlyWithRevalidation,
-      resolveInterceptLoadersOnly,
-      resolveLoadersOnly,
-    };
+    return tracked;
+  };
 
-    return runWithRouterLogContext(
-      { request, transaction: "match" },
-      () =>
-        runWithRouterContext(routerCtx, async () =>
-          withRouterLogScope("match", async () => {
-            const result = await createMatchContextForFull(request, env);
-
-          // Handle redirect case
-          if ("type" in result && result.type === "redirect") {
-            return {
-              segments: [],
-              matched: [],
-              diff: [],
-              params: {},
-              redirect: result.redirectUrl,
-            };
-          }
+  // Wrapper for wrapLoaderWithErrorHandling that uses router's error boundary finder
+  // Includes onError callback for loader error notification and telemetry emission.
+  function wrapLoaderPromise<T>(
+    promise: Promise<T>,
+    entry: EntryData,
+    segmentId: string,
+    pathname: string,
+    errorContext?: {
+      request: Request;
+      url: URL;
+      routeKey?: string;
+      params?: Record<string, string>;
+      env?: TEnv;
+      isPartial?: boolean;
+      requestStartTime?: number;
+    },
+  ): Promise<LoaderDataResult<T>> {
+    const loaderStart = telemetrySink ? performance.now() : 0;
+    const loaderRequestId = telemetrySink
+      ? errorContext?.request
+        ? getRequestId(errorContext.request)
+        : undefined
+      : undefined;
+    if (telemetrySink) {
+      const loaderName = segmentId.split(".").pop() || "unknown";
+      safeEmit(telemetry, {
+        type: "loader.start",
+        timestamp: loaderStart,
+        requestId: loaderRequestId,
+        segmentId,
+        loaderName,
+        pathname,
+      });
+    }
 
-            const ctx = result as MatchContext<TEnv>;
-
-            try {
-              const state = createPipelineState();
-              const pipeline = createMatchPartialPipeline(ctx, state);
-              return await collectMatchResult(pipeline, ctx, state);
-            } catch (error) {
-              if (error instanceof Response) throw error;
-              // Report unhandled errors during full match pipeline
-              callOnError(error, "routing", {
-                request,
-                url: ctx.url,
-                env,
-                isPartial: false,
-                handledByBoundary: false,
+    const result = wrapLoaderWithErrorHandling(
+      promise,
+      entry,
+      segmentId,
+      pathname,
+      findNearestErrorBoundary,
+      createErrorInfo,
+      // Invoke onError when loader fails
+      errorContext
+        ? (error, ctx) => {
+            callOnError(error, "loader", {
+              request: errorContext.request,
+              url: errorContext.url,
+              routeKey: errorContext.routeKey,
+              params: errorContext.params,
+              segmentId: ctx.segmentId,
+              segmentType: "loader",
+              loaderName: ctx.loaderName,
+              env: errorContext.env,
+              isPartial: errorContext.isPartial,
+              handledByBoundary: ctx.handledByBoundary,
+              requestStartTime: errorContext.requestStartTime,
+            });
+            if (telemetrySink) {
+              const errorObj =
+                error instanceof Error ? error : new Error(String(error));
+              safeEmit(telemetry, {
+                type: "loader.error",
+                timestamp: performance.now(),
+                requestId: loaderRequestId,
+                segmentId: ctx.segmentId,
+                loaderName: ctx.loaderName,
+                pathname,
+                error: errorObj,
+                handledByBoundary: ctx.handledByBoundary,
               });
-              throw sanitizeError(error);
             }
-          }),
-        ),
+          }
+        : undefined,
     );
-  }
 
-  async function matchError(
-    request: Request,
-    _context: TEnv,
-    error: unknown,
-    segmentType: ErrorInfo["segmentType"] = "route",
-  ): Promise<MatchResult | null> {
-    return runWithRouterLogContext(
-      { request, transaction: "matchError" },
-      () =>
-        withRouterLogScope("matchError", () =>
-          _matchError(
-            request,
-            _context,
-            error,
-            matchApiDeps,
-            defaultErrorBoundary,
-            segmentType,
-          ),
-        ),
-    );
+    // Emit loader.end after the promise settles (fire-and-forget)
+    if (telemetrySink) {
+      const loaderName = segmentId.split(".").pop() || "unknown";
+      result.then((r) => {
+        safeEmit(telemetry, {
+          type: "loader.end",
+          timestamp: performance.now(),
+          requestId: loaderRequestId,
+          segmentId,
+          loaderName,
+          pathname,
+          durationMs: performance.now() - loaderStart,
+          ok: r.ok,
+        });
+      });
+    }
+
+    return result;
   }
 
+  // Dependencies object for extracted segment resolution functions.
+  // Captures closure-bound helpers from createRouter.
+  const segmentDeps: SegmentResolutionDeps<TEnv> = {
+    wrapLoaderPromise,
+    trackHandler,
+    findNearestErrorBoundary,
+    findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
+    callOnError,
+    viewTransitionDefault: viewTransitionOption,
+  };
 
-  async function createMatchContextForFull(
-    request: Request,
-    env: TEnv,
-  ) {
-    return _createMatchContextForFull(request, env, matchApiDeps, findInterceptForRoute);
-  }
+  // Match API dependencies
+  const matchApiDeps: MatchApiDeps<TEnv> = {
+    findMatch: (pathname: string, ms?: any) => findMatch(pathname, ms),
+    getMetricsStore,
+    findInterceptForRoute: (routeKey, parentEntry, selectorContext, isAction) =>
+      findInterceptForRoute(routeKey, parentEntry, selectorContext, isAction),
+    callOnError,
+    findNearestErrorBoundary,
+    // Use per-router manifest when available, otherwise the static named map
+    // seeded into mergedRouteMap at router creation.
+    getRouteMap: () => getRouterManifest(routerId) ?? mergedRouteMap,
+  };
 
-  async function createMatchContextForPartial(
-    request: Request,
-    env: TEnv,
-    actionContext?: { actionId?: string; actionUrl?: URL; actionResult?: any; formData?: FormData },
-  ) {
-    return _createMatchContextForPartial(request, env, matchApiDeps, findInterceptForRoute, actionContext);
+  // Create segment resolution wrappers bound to segmentDeps
+  const {
+    resolveAllSegments,
+    resolveLoadersOnly,
+    resolveLoadersOnlyWithRevalidation,
+    buildEntryRevalidateMap,
+    resolveAllSegmentsWithRevalidation,
+    findInterceptForRoute,
+    resolveInterceptEntry,
+    resolveInterceptLoadersOnly,
+  } = createSegmentWrappers<TEnv>(segmentDeps);
+
+  // Lazy evaluation deps — captures closure state for extracted evaluateLazyEntry
+  const lazyEvalDeps: LazyEvalDeps<TEnv> = {
+    routesEntries,
+    mergedRouteMap,
+    nextMountIndex: () => mountIndex++,
+    getPrecomputedByPrefix,
+    routerId,
+  };
+
+  function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
+    _evaluateLazyEntry(entry, lazyEvalDeps);
   }
 
-  /**
-   * Match partial request with revalidation
-   *
-   * Uses generator middleware pipeline for clean separation of concerns:
-   * - cache-lookup: Check cache first
-   * - segment-resolution: Resolve segments on cache miss
-   * - intercept-resolution: Handle intercept routes
-   * - cache-store: Store results in cache
-   * - background-revalidation: SWR revalidation
-   */
-  async function matchPartial(
-    request: Request,
-    context: TEnv,
-    actionContext?: ActionContext,
-  ): Promise<MatchResult | null> {
-    // Build RouterContext with all closure functions needed by middleware
-    const routerCtx: RouterContext<TEnv> = {
+  // Create findMatch with single-entry cache, bound to router state
+  const findMatch = createFindMatch<TEnv>({
+    routesEntries,
+    evaluateLazyEntry,
+    routerId,
+  });
+
+  // Build a RouterContext once — shared by match, matchPartial, matchForPrerender
+  function buildRouterContext(): RouterContext<TEnv> {
+    return {
       findMatch,
       loadManifest,
       traverseBack,
@@ -2113,479 +634,307 @@ export function createRouter<TEnv = any>(
       buildEntryRevalidateMap,
       resolveLoadersOnlyWithRevalidation,
       resolveInterceptLoadersOnly,
+      resolveLoadersOnly,
+      telemetry: telemetrySink,
     };
-
-    return runWithRouterLogContext(
-      { request, transaction: "matchPartial" },
-      () =>
-        runWithRouterContext(routerCtx, async () =>
-          withRouterLogScope("matchPartial", async () => {
-            const ctx = await createMatchContextForPartial(
-              request,
-              context,
-              actionContext,
-            );
-            if (!ctx) return null;
-
-            try {
-              const state = createPipelineState();
-              const pipeline = createMatchPartialPipeline(ctx, state);
-              return await collectMatchResult(pipeline, ctx, state);
-            } catch (error) {
-              if (error instanceof Response) throw error;
-              // Report unhandled errors during partial match pipeline
-              callOnError(error, actionContext ? "action" : "revalidation", {
-                request,
-                url: ctx.url,
-                env: context,
-                actionId: actionContext?.actionId,
-                isPartial: true,
-                handledByBoundary: false,
-              });
-              throw sanitizeError(error);
-            }
-          }),
-        ),
-    );
   }
 
-  /**
-   * Preview match - returns route middleware without segment resolution.
-   * Also returns responseType and handler for response routes (non-RSC short-circuit).
-   */
-  async function previewMatch(
-    request: Request,
-    _context: TEnv,
-  ): Promise<{
-    routeMiddleware?: Array<{
-      handler: import("./router/middleware.js").MiddlewareFn;
-      params: Record<string, string>;
-    }>;
-    responseType?: string;
-    handler?: Function;
-    params?: Record<string, string>;
-    negotiated?: boolean;
-  } | null> {
-    return runWithRouterLogContext(
-      { request, transaction: "previewMatch" },
-      async () =>
-        withRouterLogScope("previewMatch", async () => {
-          const url = new URL(request.url);
-          const pathname = url.pathname;
-
-          // Quick route matching
-          const matched = findMatch(pathname);
-          if (!matched) {
-            return null;
-          }
-
-    // Skip redirect check - will be handled in full match
-    if (matched.redirectTo) {
-      return { routeMiddleware: undefined };
-    }
+  // Prerender/static match deps (bind closure state for extracted functions)
+  const prerenderDeps = {
+    findMatch,
+    buildRouterContext,
+    mergedRouteMap,
+    resolveAllSegments,
+  };
 
-    // Load manifest (without segment resolution)
-    const manifestEntry = await loadManifest(
-      matched.entry,
-      matched.routeKey,
+  async function matchForPrerender(
+    pathname: string,
+    params: Record<string, string>,
+    buildVars?: Record<string, any>,
+    isPassthroughRoute?: boolean,
+    buildEnv?: TEnv,
+    devMode?: boolean,
+  ) {
+    return _matchForPrerender(
       pathname,
-      undefined, // No metrics store for preview
-      false, // isSSR - doesn't matter for preview
-    );
-
-    // Collect route-level middleware from entry tree
-    // Includes middleware from orphan layouts (inline layouts within routes)
-    const routeMiddleware = collectRouteMiddleware(
-      traverseBack(manifestEntry),
-      matched.params,
+      params,
+      prerenderDeps,
+      buildVars,
+      isPassthroughRoute,
+      buildEnv,
+      devMode,
     );
+  }
 
-    // Check for response type (from trie match or manifest entry)
-    const responseType = matched.responseType ||
-      (manifestEntry.type === "route" ? manifestEntry.responseType : undefined);
-
-    // Content negotiation: when negotiate variants exist, pick the best
-    // handler based on the Accept header. Uses q-values and client order
-    // as tiebreaker (matching Express/Hono behavior). RSC routes participate
-    // as text/html candidates so browsers naturally get HTML without
-    // special-casing.
-    if (matched.negotiateVariants && matched.negotiateVariants.length > 0) {
-      const acceptEntries = parseAcceptTypes(request.headers.get("accept") || "");
-
-      // Build candidate list preserving definition order.
-      // For wildcard (*/*) and no-Accept fallback, the first candidate wins.
-      const variants = matched.negotiateVariants;
-      let candidates: Array<{ routeKey: string; responseType: string }>;
-      if (responseType) {
-        // Primary is response-type — include it as a candidate
-        candidates = [...variants, { routeKey: matched.routeKey, responseType }];
-      } else {
-        // Primary is RSC — insert as text/html candidate in definition order
-        const rscCandidate = { routeKey: matched.routeKey, responseType: RSC_RESPONSE_TYPE };
-        candidates = matched.rscFirst
-          ? [rscCandidate, ...variants]
-          : [...variants, rscCandidate];
-      }
-
-      const variant = pickNegotiateVariant(acceptEntries, candidates);
-
-      // If the winner is RSC, fall through to default RSC handling
-      if (variant.responseType === RSC_RESPONSE_TYPE) {
-        // Fall through — RSC won negotiation
-      } else if (responseType && variant.routeKey === matched.routeKey) {
-        // Fall through — response-type primary won, already set
-      } else {
-        const negotiateEntry = await loadManifest(
-          matched.entry,
-          variant.routeKey,
-          pathname,
-          undefined,
-          false,
-        );
-        return {
-          routeMiddleware: routeMiddleware.length > 0 ? routeMiddleware : undefined,
-          responseType: variant.responseType,
-          handler: negotiateEntry.type === "route" ? negotiateEntry.handler : undefined,
-          params: matched.params,
-          negotiated: true,
-        };
-      }
-    }
-
-    // If we passed through the negotiation block (variants exist), mark as
-    // negotiated so the handler sets Vary: Accept on the response.
-          const hasVariants = matched.negotiateVariants && matched.negotiateVariants.length > 0;
-          return {
-            routeMiddleware: routeMiddleware.length > 0 ? routeMiddleware : undefined,
-            ...(responseType ? {
-              responseType,
-              handler: manifestEntry.type === "route" ? manifestEntry.handler : undefined,
-              params: matched.params,
-            } : {}),
-            ...(hasVariants ? { negotiated: true } : {}),
-          };
-        }),
+  async function renderStaticSegment(
+    handler: Function,
+    handlerId: string,
+    routeName?: string,
+    buildEnv?: TEnv,
+    devMode?: boolean,
+  ) {
+    return _renderStaticSegment<TEnv>(
+      handler,
+      handlerId,
+      mergedRouteMap,
+      routeName,
+      buildEnv,
+      devMode,
     );
   }
 
-  /**
-   * Create route builder with accumulated route types
-   * The TNewRoutes type parameter captures the new routes being added
-   */
-  function createRouteBuilder<TNewRoutes extends Record<string, string>>(
-    prefix: string,
-    routes: TNewRoutes,
-  ): RouteBuilder<RouteDefinition, TEnv, any, TNewRoutes> {
-    const currentMountIndex = mountIndex++;
-
-    // Merge routes into the reverse map
-    // Keys stay unchanged for composability - only URL patterns get prefixed
-    const routeEntries = routes as Record<string, string>;
-    for (const [key, pattern] of Object.entries(routeEntries)) {
-      // Build prefixed pattern: "/shop" + "/cart" -> "/shop/cart"
-      // Root prefix "/" is a no-op — don't double the leading slash.
-      const effectivePrefix = prefix === "/" ? "" : prefix;
-      const prefixedPattern =
-        effectivePrefix && pattern !== "/"
-          ? `${effectivePrefix}${pattern}`
-          : effectivePrefix && pattern === "/"
-            ? effectivePrefix
-            : pattern;
-
-      // Runtime validation: warn if key already exists with different pattern
-      const existingPattern = mergedRouteMap[key];
-      if (
-        existingPattern !== undefined &&
-        existingPattern !== prefixedPattern
-      ) {
-        console.warn(
-          `[rsc-router] Route key conflict: "${key}" already maps to "${existingPattern}", ` +
-            `overwriting with "${prefixedPattern}". Use unique key names to avoid this.`,
-        );
-      }
-
-      // Use original key - enables reusable route modules
-      mergedRouteMap[key] = prefixedPattern;
-    }
-
-    // Auto-register route map for runtime reverse() usage
-    registerRouteMap(mergedRouteMap);
-
-    // Extract trailing slash config if present (attached by route())
-    const trailingSlashConfig = (routes as any).__trailingSlash as
-      | Record<string, TrailingSlashMode>
-      | undefined;
-
-    // Create builder object so .use() can return it
-    const builder: RouteBuilder<RouteDefinition, TEnv, any, TNewRoutes> = {
-      use(
-        patternOrMiddleware: string | MiddlewareFn<TEnv>,
-        middleware?: MiddlewareFn<TEnv>,
-      ) {
-        // Mount-scoped middleware - prefix is the mount prefix
-        addMiddleware(patternOrMiddleware, middleware, prefix || null);
-        return builder;
-      },
-
-      map(
-        handler:
-          | ((
-              helpers: InlineRouteHelpers<TNewRoutes, TEnv>,
-            ) => Array<AllUseItems>)
-          | (() =>
-              | Array<AllUseItems>
-              | Promise<{ default: () => Array<AllUseItems> }>
-              | Promise<() => Array<AllUseItems>>),
-      ) {
-        // Store handler as-is - detection happens at call time based on return type
-        // Both patterns use the same signature:
-        // - Inline: ({ route }) => [...] - receives helpers, returns Array
-        // - Lazy: () => import(...) - ignores helpers, returns Promise
-        routesEntries.push({
-          prefix,
-          staticPrefix: extractStaticPrefix(prefix),
-          routes: routes as ResolvedRouteMap<any>,
-          trailingSlash: trailingSlashConfig,
-          handler: handler as any,
-          mountIndex: currentMountIndex,
-        });
-        // Return router with accumulated types
-        // At runtime this is the same object, but TypeScript tracks the accumulated route types
-        return router as any;
-      },
-
-      // Expose accumulated route map for typeof extraction
-      get routeMap() {
-        return mergedRouteMap as TNewRoutes;
-      },
-    };
+  // Create match handler functions bound to router state
+  const matchHandlers = createMatchHandlers<TEnv>({
+    buildRouterContext,
+    callOnError,
+    matchApiDeps,
+    defaultErrorBoundary,
+    findMatch,
+    findInterceptForRoute,
+    telemetry: telemetrySink,
+    cacheSignalEnabled,
+  });
 
-    return builder;
-  }
+  const { match, matchPartial, matchError, previewMatch } = matchHandlers;
 
   /**
    * Router instance
    * The type system tracks accumulated routes through the builder chain
    * Initial TRoutes is {} (empty) to avoid poisoning accumulated types with Record<string, string>
    */
-  const router: RSCRouter<TEnv, {}> = {
+  const router: RangoInternal<TEnv, {}> = {
     __brand: RSC_ROUTER_BRAND,
     id: routerId,
+    basename,
 
-    routes(
-      prefixOrRoutes: string | Record<string, string> | UrlPatterns<TEnv>,
-      maybeRoutes?: Record<string, string>,
-    ): any {
-      // Note: Multiple .routes() calls are allowed for backwards compatibility
-      // with the old map() pattern. For new code, prefer urls() with include().
-
-      // Check if argument is UrlPatterns (new Django-style API)
-      // Detect by checking for handler and definitions properties
-      if (
-        typeof prefixOrRoutes === "object" &&
-        prefixOrRoutes !== null &&
-        "handler" in prefixOrRoutes &&
-        "definitions" in prefixOrRoutes &&
-        typeof (prefixOrRoutes as UrlPatterns<TEnv>).handler === "function"
-      ) {
-        const urlPatterns = prefixOrRoutes as UrlPatterns<TEnv>;
-        // Store reference for runtime manifest generation
-        storedUrlPatterns = urlPatterns;
-        const currentMountIndex = mountIndex++;
-
-        // Create manifest and patterns maps for route registration
-        const manifest = new Map<string, EntryData>();
-        const patterns = new Map<string, string>();
-        const patternsByPrefix = new Map<string, Map<string, string>>();
-        const trailingSlashMap = new Map<string, TrailingSlashMode>();
-
-        // Run the handler once to extract patterns for route matching.
-        // Note: loadManifest will re-run the handler to register entries in its context.
-        // Lazy includes are detected in the return value and handled separately.
-        //
-        // Pattern extraction must use the same mountIndex and MapRootLayout root
-        // parent as loadManifest so that shortCodes produced here match those at
-        // runtime.  include() captures the current parent and counters; if those
-        // shortCodes diverge from the runtime tree the segment reconciliation on
-        // the client will see a full mismatch and remount the entire page.
-        const syntheticMapRoot: EntryData = {
-          type: "layout",
-          id: `#synthetic-maproot-M${currentMountIndex}`,
-          shortCode: `M${currentMountIndex}L0`,
-          parent: null,
-          handler: MapRootLayout,
-          middleware: [],
-          revalidate: [],
-          errorBoundary: [],
-          notFoundBoundary: [],
-          layout: [],
-          parallel: [],
-          intercept: [],
-          loader: [],
-        };
+    routes(patternsOrBuilder: UrlPatterns<TEnv> | UrlBuilder<TEnv>): any {
+      // Wrap builder functions in urls() automatically
+      const urlPatterns: UrlPatterns<TEnv> =
+        typeof patternsOrBuilder === "function"
+          ? (urls(patternsOrBuilder) as UrlPatterns<TEnv>)
+          : patternsOrBuilder;
 
-        let handlerResult: AllUseItems[] = [];
-        RSCRouterContext.run(
-          {
-            manifest,
-            patterns,
-            patternsByPrefix,
-            trailingSlash: trailingSlashMap,
-            namespace: "root",
-            parent: syntheticMapRoot,
-            counters: {},
-            mountIndex: currentMountIndex,
-          },
-          () => {
-            handlerResult = urlPatterns.handler() as AllUseItems[];
-          },
-        );
+      // Store reference for runtime manifest generation
+      storedUrlPatterns = urlPatterns;
+      const currentMountIndex = mountIndex++;
 
-        // Store the ORIGINAL handler - loadManifest will re-run it to register manifest entries
-        // Convert trailingSlash map to object for the router
-        const trailingSlashConfig =
-          trailingSlashMap.size > 0
-            ? Object.fromEntries(trailingSlashMap)
-            : undefined;
-
-        // Collect route keys that have prerender handlers (for non-trie match path)
-        let prerenderRouteKeys: Set<string> | undefined;
-        for (const [name, entry] of manifest.entries()) {
-          if (entry.type === "route" && entry.isPrerender) {
-            if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
-            prerenderRouteKeys.add(name);
-          }
-        }
+      // Create manifest and patterns maps for route registration
+      const manifest = new Map<string, EntryData>();
+      const routePatterns = new Map<string, string>();
+      const patternsByPrefix = new Map<string, Map<string, string>>();
+      const trailingSlashMap = new Map<string, TrailingSlashMode>();
+
+      // Run the handler once to extract patterns for route matching.
+      // Note: loadManifest will re-run the handler to register entries in its context.
+      // Lazy includes are detected in the return value and handled separately.
+      //
+      // Pattern extraction must use the same mountIndex and MapRootLayout root
+      // parent as loadManifest so that shortCodes produced here match those at
+      // runtime.  include() captures the current parent and counters; if those
+      // shortCodes diverge from the runtime tree the segment reconciliation on
+      // the client will see a full mismatch and remount the entire page.
+      const syntheticMapRoot: EntryData = {
+        type: "layout",
+        id: `#synthetic-maproot-M${currentMountIndex}`,
+        shortCode: `M${currentMountIndex}L0`,
+        parent: null,
+        handler: MapRootLayout,
+        middleware: [],
+        revalidate: [],
+        errorBoundary: [],
+        notFoundBoundary: [],
+        layout: [],
+        parallel: {},
+        intercept: [],
+        loader: [],
+      };
 
-        // Create separate RouteEntry for each URL prefix group
-        // This enables prefix-based short-circuit optimization
-        if (patternsByPrefix.size > 0) {
-          for (const [prefix, prefixPatterns] of patternsByPrefix.entries()) {
-            const routesObject: Record<string, string> = {};
-            for (const [name, pattern] of prefixPatterns.entries()) {
-              routesObject[name] = pattern;
-            }
+      let handlerResult: AllUseItems[] = [];
+      RangoContext.run(
+        {
+          manifest,
+          patterns: routePatterns,
+          patternsByPrefix,
+          trailingSlash: trailingSlashMap,
+          namespace: "root",
+          parent: syntheticMapRoot,
+          counters: {},
+          mountIndex: currentMountIndex,
+          cacheProfiles: resolvedCacheProfiles,
+          // basename sets the initial URL prefix so all path() patterns
+          // are registered with the prefix (e.g. "/admin" + "/users" = "/admin/users").
+          // No namePrefix — route names stay unprefixed.
+          ...(basename ? { urlPrefix: basename } : {}),
+        },
+        () => {
+          handlerResult = urlPatterns.handler() as AllUseItems[];
+        },
+      );
 
-            routesEntries.push({
-              // prefix is "" because patterns already include the URL prefix
-              // (e.g., "/site/:locale/user1/:id" not just "/user1/:id")
-              prefix: "",
-              // staticPrefix is the actual prefix for short-circuit optimization
-              staticPrefix: extractStaticPrefix(prefix),
-              routes: routesObject as ResolvedRouteMap<any>,
-              trailingSlash: trailingSlashConfig,
-              handler: urlPatterns.handler,
-              mountIndex: currentMountIndex,
-              ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
-            });
+      // Convert trailingSlash map to object for the router
+      const trailingSlashConfig =
+        trailingSlashMap.size > 0
+          ? Object.fromEntries(trailingSlashMap)
+          : undefined;
+
+      // Collect route keys that have prerender handlers (for non-trie match path)
+      let prerenderRouteKeys: Set<string> | undefined;
+      let passthroughRouteKeys: Set<string> | undefined;
+      for (const [name, entry] of manifest.entries()) {
+        if (entry.type === "route" && entry.isPrerender) {
+          if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
+          prerenderRouteKeys.add(name);
+          if (entry.isPassthrough === true) {
+            if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
+            passthroughRouteKeys.add(name);
           }
-        } else {
-          // Fallback: no prefix grouping, use flat patterns map
+        }
+      }
+
+      // Create separate RouteEntry for each URL prefix group
+      // This enables prefix-based short-circuit optimization
+      if (patternsByPrefix.size > 0) {
+        for (const [prefix, prefixPatterns] of patternsByPrefix.entries()) {
           const routesObject: Record<string, string> = {};
-          for (const [name, pattern] of patterns.entries()) {
+          for (const [name, pattern] of prefixPatterns.entries()) {
             routesObject[name] = pattern;
           }
 
           routesEntries.push({
+            // prefix is "" because patterns already include the URL prefix
+            // (e.g., "/site/:locale/user1/:id" not just "/user1/:id")
             prefix: "",
-            staticPrefix: "",
+            // staticPrefix is the actual prefix for short-circuit optimization
+            staticPrefix: extractStaticPrefix(prefix),
             routes: routesObject as ResolvedRouteMap<any>,
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
+            cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
+            ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
           });
         }
-
-        // Build route map from registered patterns
-        for (const [name, pattern] of patterns.entries()) {
-          // Runtime validation: warn if key already exists with different pattern
-          const existingPattern = mergedRouteMap[name];
-          if (existingPattern !== undefined && existingPattern !== pattern) {
-            console.warn(
-              `[@rangojs/router] Route name conflict: "${name}" already maps to "${existingPattern}", ` +
-                `overwriting with "${pattern}". Use unique route names to avoid this.`,
-            );
-          }
-          mergedRouteMap[name] = pattern;
+      } else {
+        // Fallback: no prefix grouping, use flat patterns map
+        const routesObject: Record<string, string> = {};
+        for (const [name, pattern] of routePatterns.entries()) {
+          routesObject[name] = pattern;
         }
 
-        // Detect lazy includes in handler result and create placeholder entries
-        // Uses findLazyIncludes from outer scope (shared with evaluateLazyEntry)
-        const lazyIncludes = findLazyIncludes(handlerResult);
+        routesEntries.push({
+          prefix: "",
+          staticPrefix: "",
+          routes: routesObject as ResolvedRouteMap<any>,
+          trailingSlash: trailingSlashConfig,
+          handler: urlPatterns.handler,
+          mountIndex: currentMountIndex,
+          routerId,
+          cacheProfiles: resolvedCacheProfiles,
+          ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
+          ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
+        });
+      }
+
+      // Build route map from registered patterns
+      for (const [name, pattern] of routePatterns.entries()) {
+        // Runtime validation: warn if key already exists with different pattern.
+        // Skip warning for entries that came from the static seed — the gen file
+        // can be stale during HMR, so runtime registration is authoritative.
+        const existingPattern = mergedRouteMap[name];
+        if (
+          existingPattern !== undefined &&
+          existingPattern !== pattern &&
+          !seededNames.has(name)
+        ) {
+          console.warn(
+            `[@rangojs/router] Route name conflict: "${name}" already maps to "${existingPattern}", ` +
+              `overwriting with "${pattern}". Use unique route names to avoid this.`,
+          );
+        }
+        mergedRouteMap[name] = pattern;
+        seededNames.delete(name);
+      }
 
-        // Create placeholder RouteEntry for each lazy include
-        for (const lazyInclude of lazyIncludes) {
-          // Compute the full URL prefix (combining parent prefix if any)
-          const fullPrefix = lazyInclude.context.urlPrefix
-            ? lazyInclude.context.urlPrefix + lazyInclude.prefix
-            : lazyInclude.prefix;
+      // Detect lazy includes in handler result and create placeholder entries
+      const lazyIncludes = findLazyIncludes(handlerResult);
+
+      // Create placeholder RouteEntry for each lazy include
+      for (const lazyInclude of lazyIncludes) {
+        // Compute the full URL prefix (combining parent prefix if any). Use the
+        // slash-collapsing join so a trailing-slash parent prefix does not
+        // produce a double-slash staticPrefix the trie's sp can never match.
+        const fullPrefix = joinPrefix(
+          lazyInclude.context.urlPrefix,
+          lazyInclude.prefix,
+        );
 
-          const lazyEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
-            prefix: "",
-            staticPrefix: extractStaticPrefix(fullPrefix),
-            routes: {} as ResolvedRouteMap<any>, // Empty until first match
-            trailingSlash: trailingSlashConfig,
-            handler: urlPatterns.handler,
-            mountIndex: currentMountIndex,
-            // Lazy evaluation fields
-            lazy: true,
-            lazyPatterns: lazyInclude.patterns,
-            lazyContext: lazyInclude.context,
-            lazyEvaluated: false,
-            // Store the include prefix for evaluation
-            _lazyPrefix: lazyInclude.prefix,
-          };
-          // Insert lazy entry before any entry whose staticPrefix is a
-          // prefix of (but shorter than) this lazy entry's staticPrefix.
-          // This ensures more specific lazy includes are matched before
-          // less specific eager entries (e.g., "/href/nested" before "/href/:id").
-          const lazyPrefix = lazyEntry.staticPrefix;
-          let insertIndex = routesEntries.length;
-          if (lazyPrefix) {
-            for (let i = 0; i < routesEntries.length; i++) {
-              const existing = routesEntries[i]!;
-              if (
-                lazyPrefix.startsWith(existing.staticPrefix) &&
-                lazyPrefix.length > existing.staticPrefix.length
-              ) {
-                insertIndex = i;
-                break;
-              }
+        const lazyEntry: RouteEntry<TEnv> & { _lazyPrefix?: string } = {
+          prefix: "",
+          staticPrefix: extractStaticPrefix(fullPrefix),
+          routes: {} as ResolvedRouteMap<any>, // Empty until first match
+          trailingSlash: trailingSlashConfig,
+          handler: urlPatterns.handler,
+          mountIndex: mountIndex++,
+          routerId,
+          // Lazy evaluation fields
+          lazy: true,
+          lazyPatterns: lazyInclude.patterns,
+          lazyContext: lazyInclude.context,
+          lazyEvaluated: false,
+          _lazyPrefix: lazyInclude.prefix,
+        };
+        // Insert lazy entry before any entry whose staticPrefix is a
+        // prefix of (but shorter than) this lazy entry's staticPrefix.
+        // This ensures more specific lazy includes are matched before
+        // less specific eager entries (e.g., "/href/nested" before "/href/:id").
+        const lazyPrefix = lazyEntry.staticPrefix;
+        let insertIndex = routesEntries.length;
+        if (lazyPrefix) {
+          for (let i = 0; i < routesEntries.length; i++) {
+            const existing = routesEntries[i]!;
+            if (
+              lazyPrefix.startsWith(existing.staticPrefix) &&
+              lazyPrefix.length > existing.staticPrefix.length
+            ) {
+              insertIndex = i;
+              break;
             }
           }
-          routesEntries.splice(insertIndex, 0, lazyEntry);
         }
-
-        // Auto-register route map for runtime reverse() usage
-        registerRouteMap(mergedRouteMap);
-
-        // Return the router (no .map() needed for UrlPatterns)
-        return router;
+        routesEntries.splice(insertIndex, 0, lazyEntry);
       }
 
-      // Legacy API: route() + map() pattern
-      // If second argument exists, first is prefix
-      if (maybeRoutes !== undefined) {
-        return createRouteBuilder(prefixOrRoutes as string, maybeRoutes);
-      }
-      // Otherwise, first argument is routes with empty prefix
-      return createRouteBuilder("", prefixOrRoutes as Record<string, string>);
+      // Auto-register route map for runtime reverse() usage
+      registerRouteMap(mergedRouteMap);
+
+      return router;
     },
 
     use(
       patternOrMiddleware: string | MiddlewareFn<TEnv>,
       middleware?: MiddlewareFn<TEnv>,
     ): any {
-      // Global middleware - no mount prefix
-      addMiddleware(patternOrMiddleware, middleware, null);
+      // Auto-prefix pattern with basename so router-level middleware
+      // patterns are router-relative (e.g. "/users/*" matches "/app/users/*").
+      if (basename && typeof patternOrMiddleware === "string") {
+        const pattern = patternOrMiddleware;
+        const prefixed =
+          pattern === "/*" || pattern === "*"
+            ? `${basename}/*`
+            : `${basename}${pattern}`;
+        addMiddleware(prefixed, middleware, null);
+      } else {
+        addMiddleware(patternOrMiddleware, middleware, null);
+      }
       return router;
     },
 
     // Type-safe URL builder using merged route map
     // Types are tracked through the builder chain via TRoutes parameter
-    // Falls back to static route names from the generated file (injected by Vite)
-    reverse: createReverse(mergedRouteMap, () => staticRouteNames),
+    // Seeded with static route names from the generated file (injected by Vite)
+    reverse: createReverse(mergedRouteMap),
 
     // Expose accumulated route map for typeof extraction
     // Returns {} initially, but builder chain accumulates specific route types
@@ -2608,20 +957,69 @@ export function createRouter<TEnv = any>(
     // Expose resolved theme configuration for NavigationProvider and MetaTags
     themeConfig: resolvedThemeConfig,
 
+    // Expose resolved cache profiles for per-request resolution
+    cacheProfiles: resolvedCacheProfiles,
+
+    // Expose prefetch cache settings
+    prefetchCacheControl,
+    prefetchCacheTTL,
+
+    // Expose the resolved rango state cookie name for the server-side writer
+    // (invalidateClientCache) and for shipping to the client in metadata.
+    resolvedStateCookieName,
+
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 
+    // Expose router-wide performance debugging for request-level metrics setup
+    debugPerformance,
+
+    // Expose resolved span tracing for the handler (Cloudflare custom spans)
+    tracing: resolvedTracing,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 
+    // Expose origin check configuration for handler (default: enabled)
+    originCheck: originCheckOption ?? true,
+
+    // Expose SSR configuration for handler
+    ssr: ssrOption,
+
+    // Expose resolved timeouts for RSC handler
+    timeouts: resolvedTimeouts,
+    onTimeout,
+
     // Expose global middleware for RSC handler
     middleware: globalMiddleware,
 
-    match,
+    match: (request: Request, input: RouterRequestInput<TEnv> = {}) => {
+      const env = input.env ?? ({} as TEnv);
+      return match(request, env);
+    },
     matchForPrerender,
-    matchPartial,
-    matchError,
-    previewMatch,
+    renderStaticSegment,
+    matchPartial: (
+      request: Request,
+      input: RouterRequestInput<TEnv> = {},
+      actionContext?: Parameters<typeof matchPartial>[2],
+    ) => {
+      const env = input.env ?? ({} as TEnv);
+      return matchPartial(request, env, actionContext);
+    },
+    matchError: (
+      request: Request,
+      input: RouterRequestInput<TEnv> | undefined,
+      error: unknown,
+      segmentType?: Parameters<typeof matchError>[3],
+    ) => {
+      const env = input?.env ?? ({} as TEnv);
+      return matchError(request, env, error, segmentType);
+    },
+    previewMatch: (request: Request, input: RouterRequestInput<TEnv> = {}) => {
+      const env = input.env ?? ({} as TEnv);
+      return previewMatch(request, env);
+    },
 
     // Expose nonce provider for fetch
     nonce,
@@ -2637,93 +1035,67 @@ export function createRouter<TEnv = any>(
     // Expose source file for per-router type generation
     __sourceFile,
 
+    // Expose basename for runtime manifest generation
+    __basename: basename,
+
+    // Expose router-level boundary defaults for build-time clientChunks
+    // discovery (so a "use client" default boundary lands in app-fallback).
+    // These are createRouter options, never pushed onto EntryData.
+    __defaultErrorBoundary: defaultErrorBoundary,
+    __defaultNotFoundBoundary: defaultNotFoundBoundary,
+    __notFound: notFound,
+
     // RSC request handler (lazily created on first call)
     fetch: (() => {
       // Handler is created on first call and reused
       let handler:
         | ((
             request: Request,
-            env: TEnv & { ctx?: ExecutionContext },
+            input: RouterRequestInput<TEnv>,
           ) => Promise<Response>)
         | null = null;
 
-      return async (
-        request: Request,
-        env: TEnv & { ctx?: ExecutionContext },
-      ) => {
+      return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
         // Trigger lazy import of per-router manifest data before route matching.
         // No-op if data is already loaded or no loader is registered.
         await ensureRouterManifest(routerId);
         if (!handler) {
           // Lazy import deferred to first request to avoid dev mode issues
           const { createRSCHandler } = await import("./rsc/handler.js");
+          // Cast: createRSCHandler receives `router as any`, which erases TEnv
+          // and infers its handler as RouterRequestInput<unknown>. Re-narrow the
+          // returned handler to RouterRequestInput<TEnv> so the call below stays
+          // typed. (The handler already accepts (request, RouterRequestInput).)
           handler = createRSCHandler({
             router: router as any,
             cache,
             nonce,
             version,
-          });
+          }) as (
+            request: Request,
+            input: RouterRequestInput<TEnv>,
+          ) => Promise<Response>;
         }
-        return handler(request, env);
+        return handler!(request, input);
       };
     })(),
 
-    // Debug utility for manifest inspection
-    async debugManifest(): 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) {
-                const useItems = load.default;
-                if (typeof useItems === "function") {
-                  useItems(helpers);
-                }
-              }
-            }
-          },
-        );
-      }
+    // Low-level route matching for request classification
+    findMatch: (pathname: string, metricsStore?: any) =>
+      findMatch(pathname, metricsStore),
 
-      return serializeManifest(manifest);
-    },
+    // Debug utility for manifest inspection
+    debugManifest: () => buildDebugManifest<TEnv>(routesEntries),
   };
 
   // Register router in the global registry for build-time discovery
   RouterRegistry.set(routerId, router);
 
   // If urls option was provided, auto-register them
-  if (urlsOption) {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+  if (typeof urlsOption === "function") {
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
+  } else if (urlsOption) {
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
   }
 
   return router;