@rangojs/router 0.0.0-experimental.35 → 0.0.0-experimental.358c376d

package/src/router.ts

@@ -1,17 +1,23 @@
 import { type ReactNode } from "react";
 import { createCacheScope } from "./cache/cache-scope.js";
-import {
-  setCacheProfiles,
-  resolveCacheProfiles,
-} from "./cache/profile-registry.js";
+import { resolveCacheProfiles } from "./cache/profile-registry.js";
 import { isCachedFunction } from "./cache/taint.js";
 import { assertClientComponent } from "./component-utils.js";
+import {
+  isClientUrlPatterns,
+  isClientUrlReference,
+} from "./client-urls/server-projection.js";
+import type { ClientUrlPatterns } from "./client-urls/types.js";
 import { DefaultDocument } from "./components/DefaultDocument.js";
 import type { SerializedManifest } from "./debug.js";
+import {
+  DEV_DISCOVERY_EPOCH_HEADER,
+  DEV_DISCOVERY_PROBE_HEADER,
+  isValidDevDiscoveryEpoch,
+} from "./dev-discovery-protocol.js";
 import { createReverse, type ReverseFunction } from "./reverse.js";
 import {
   registerRouteMap,
-  getPrecomputedEntries,
   getRouterManifest,
   getRouterPrecomputedEntries,
   ensureRouterManifest,
@@ -19,11 +25,13 @@ import {
 import MapRootLayout from "./server/root-layout.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,
-  InterceptSelectorContext,
+  type EntryData,
   getContext,
-  RSCRouterContext,
+  RangoContext,
   type MetricsStore,
 } from "./server/context";
 import { createHandleStore, type HandleStore } from "./server/handle-store.js";
@@ -55,6 +63,7 @@ import { buildDebugManifest } from "./router/debug-manifest.js";
 
 import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
 import { createHandlerContext } from "./router/handler-context.js";
+import { normalizeBasename } from "./router/basename.js";
 import {
   setupLoaderAccess,
   setupLoaderAccessSilent,
@@ -63,15 +72,17 @@ import {
 import { loadManifest } from "./router/manifest.js";
 import { createMetricsStore } from "./router/metrics.js";
 import {
-  parsePattern,
+  compileMiddlewarePattern,
   type MiddlewareEntry,
   type MiddlewareFn,
 } from "./router/middleware.js";
 import {
   extractStaticPrefix,
+  joinPrefix,
   traverseBack,
 } 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,
@@ -89,14 +100,12 @@ import {
   RouterRegistry,
   nextRouterAutoId,
 } from "./router/router-registry.js";
+import type { RangoOptions, RootLayoutProps } from "./router/router-options.js";
 import type {
-  RSCRouterOptions,
-  RootLayoutProps,
-} from "./router/router-options.js";
-import type {
-  RSCRouter,
-  RSCRouterInternal,
+  Rango,
+  RangoInternal,
   RouterRequestInput,
+  UrlPatternMount,
 } from "./router/router-interfaces.js";
 
 // Extracted closure functions
@@ -110,29 +119,37 @@ import {
   matchForPrerender as _matchForPrerender,
   renderStaticSegment as _renderStaticSegment,
 } from "./router/prerender-match.js";
+import { resolveStateCookieName } from "./router/state-cookie-name.js";
+import { resolvePrefetchCacheTTL } from "./router/prefetch-cache-ttl.js";
+import { resolveDefaultPrefetch } from "./router/prefetch-default.js";
+import {
+  resolvePrefetchCacheSize,
+  resolvePrefetchConcurrency,
+} from "./router/prefetch-limits.js";
 
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
 export type {
-  RSCRouterOptions,
+  RangoOptions,
   RootLayoutProps,
   SSRStreamMode,
   SSROptions,
   ResolveStreamingContext,
 } from "./router/router-options.js";
 export type {
-  RSCRouter,
-  RSCRouterInternal,
+  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,
@@ -148,24 +165,49 @@ export function createRouter<TEnv = any>(
     nonce,
     version,
     prefetchCacheTTL: prefetchCacheTTLOption,
+    prefetchCacheSize: prefetchCacheSizeOption,
+    prefetchConcurrency: prefetchConcurrencyOption,
+    defaultPrefetch: defaultPrefetchOption,
+    stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
-    allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
+    tracing: tracingOption,
     ssr: ssrOption,
     timeout: timeoutShorthand,
     timeouts: timeoutsOption,
     onTimeout,
     originCheck: originCheckOption,
+    viewTransition: viewTransitionOption = "auto",
+    debugCacheSignal: debugCacheSignalOption = false,
+    debugShellCapture: debugShellCaptureOption,
+    strictMode: strictModeOption = true,
   } = options;
 
+  // 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 cache profiles: merge user config with guaranteed default profile.
-  // This resolved map is both stored on the router (for per-request context)
-  // and written to the global registry (for DSL-time cache("profileName")).
+  // 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);
-  setCacheProfiles(resolvedCacheProfiles);
 
   // Source file: prefer Vite-injected path (zero cost), fall back to
   // stack trace parsing for non-Vite environments (e.g. tests).
@@ -199,22 +241,53 @@ export function createRouter<TEnv = any>(
   // order (unlike the counter which depends on import order).
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
-
-  // 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 rawDevDiscoveryEpoch = (
+    globalThis as typeof globalThis & {
+      __RANGO_DEV_DISCOVERY_EPOCH?: unknown;
+    }
+  ).__RANGO_DEV_DISCOVERY_EPOCH;
+  const devDiscoveryEpoch = isValidDevDiscoveryEpoch(rawDevDiscoveryEpoch)
+    ? rawDevDiscoveryEpoch
+    : undefined;
+
+  // 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). Clamps to a
+  // non-negative integer and guards non-finite (NaN/Infinity) inputs so a
+  // malformed `Cache-Control: max-age=NaN` can never reach the wire.
+  const resolvedPrefetchCacheTTL = resolvePrefetchCacheTTL(
+    prefetchCacheTTLOption,
+  );
+  const prefetchCacheTTL = resolvedPrefetchCacheTTL.ms;
   const prefetchCacheControl: string | false =
-    prefetchCacheTTLSeconds === 0
-      ? false
-      : `private, max-age=${prefetchCacheTTLSeconds}`;
+    resolvedPrefetchCacheTTL.cacheControl;
+
+  // Resolve client-side prefetch limits (in-memory cache size and queue
+  // concurrency). Both are positive-integer counts; sub-1/non-finite inputs
+  // fall back to the defaults. Shipped to the client in payload metadata.
+  const prefetchCacheSize = resolvePrefetchCacheSize(prefetchCacheSizeOption);
+  const prefetchConcurrency = resolvePrefetchConcurrency(
+    prefetchConcurrencyOption,
+  );
+
+  // Resolve the router-wide default Link prefetch strategy ("none" in dev,
+  // "viewport" in production). Links without an explicit prop fall back to it.
+  const defaultPrefetch = resolveDefaultPrefetch(defaultPrefetchOption);
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
 
+  // Resolve StrictMode flag (default: true). Shipped to the client in payload
+  // metadata; the browser entry reads it once to decide whether to wrap the
+  // hydrated tree in React.StrictMode.
+  const strictMode = strictModeOption !== false;
+
   // Resolve theme config (null if theme not enabled)
   const resolvedThemeConfig = themeOption
     ? resolveThemeConfig(themeOption)
@@ -246,9 +319,14 @@ export function createRouter<TEnv = any>(
     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)
@@ -258,6 +336,7 @@ export function createRouter<TEnv = any>(
 
   // Store reference to urlpatterns for runtime manifest generation
   let storedUrlPatterns: UrlPatterns<TEnv, any> | null = null;
+  const urlpatternMounts: UrlPatternMount<TEnv>[] = [];
 
   // Global middleware storage
   const globalMiddleware: MiddlewareEntry<TEnv>[] = [];
@@ -312,7 +391,7 @@ export function createRouter<TEnv = any>(
     let regex: RegExp | null = null;
     let paramNames: string[] = [];
     if (fullPattern) {
-      const parsed = parsePattern(fullPattern);
+      const parsed = compileMiddlewarePattern(fullPattern);
       regex = parsed.regex;
       paramNames = parsed.paramNames;
     }
@@ -322,7 +401,6 @@ export function createRouter<TEnv = any>(
       regex,
       paramNames,
       handler,
-      mountPrefix,
     });
   }
 
@@ -352,27 +430,31 @@ export function createRouter<TEnv = any>(
     string,
     Record<string, string>
   > | null {
-    const current =
-      getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
+    const current = getRouterPrecomputedEntries(routerId);
     if (current !== precomputedSource) {
       precomputedSource = current;
-      precomputedByPrefix = current
-        ? new Map(current.map((e) => [e.staticPrefix, e.routes]))
-        : null;
+      // 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;
   }
 
   // Wrapper to pass debugPerformance to external createMetricsStore.
   // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  // With no active request context there is nowhere to hang the store, so return
+  // undefined: an orphan store would collect metrics no reader can reach (nothing
+  // holds it, and appendMetric(undefined, ...) is already a no-op).
   const getMetricsStore = () => {
     const reqCtx = _getRequestContext();
     const enabled = debugPerformance || !!reqCtx?._debugPerformance;
-    if (!enabled) return undefined;
-    if (!reqCtx) {
-      return createMetricsStore(true);
-    }
-    reqCtx._metricsStore ??= createMetricsStore(true);
+    if (!enabled || !reqCtx) return undefined;
+    // Anchor a mid-request store to the true request entry (reqCtx._handlerStart),
+    // not this call's performance.now(); undefined falls back to now() inside
+    // createMetricsStore (metrics.ts).
+    reqCtx._metricsStore ??= createMetricsStore(true, reqCtx._handlerStart);
     return reqCtx._metricsStore;
   };
 
@@ -383,11 +465,6 @@ export function createRouter<TEnv = any>(
   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).
   // 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).
@@ -398,13 +475,14 @@ export function createRouter<TEnv = any>(
       segmentType?: string;
     },
   ): Promise<T> => {
-    const store = getHandleStore();
+    // One ALS read serves both the store lookup and the onError closure.
+    const reqCtx = _getRequestContext();
+    const store = reqCtx?._handleStore;
     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", {
@@ -446,8 +524,12 @@ export function createRouter<TEnv = any>(
         ? getRequestId(errorContext.request)
         : undefined
       : undefined;
+    // Derived once here for both the loader.start and loader.end emits (the
+    // loader.error emit uses ctx.loaderName from wrapLoaderWithErrorHandling).
+    const loaderName = telemetrySink
+      ? segmentId.split(".").pop() || "unknown"
+      : "";
     if (telemetrySink) {
-      const loaderName = segmentId.split(".").pop() || "unknown";
       safeEmit(telemetry, {
         type: "loader.start",
         timestamp: loaderStart,
@@ -497,11 +579,17 @@ export function createRouter<TEnv = any>(
             }
           }
         : undefined,
+      // notFound() resolution deps: the streamed envelope carries the
+      // server-rendered not-found UI, mirroring the consumption lane's
+      // boundary resolution (segment-resolution/helpers.ts).
+      {
+        findNearestNotFoundBoundary,
+        notFoundComponent: notFound,
+      },
     );
 
     // 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",
@@ -526,7 +614,9 @@ export function createRouter<TEnv = any>(
     trackHandler,
     findNearestErrorBoundary,
     findNearestNotFoundBoundary,
+    notFoundComponent: notFound,
     callOnError,
+    viewTransitionDefault: viewTransitionOption,
   };
 
   // Match API dependencies
@@ -560,10 +650,18 @@ export function createRouter<TEnv = any>(
     mergedRouteMap,
     nextMountIndex: () => mountIndex++,
     getPrecomputedByPrefix,
+    routerId,
   };
 
-  function evaluateLazyEntry(entry: RouteEntry<TEnv>): void {
-    _evaluateLazyEntry(entry, lazyEvalDeps);
+  // Must return the Promise from _evaluateLazyEntry: an async include provider
+  // (`() => import("./routes")`) resolves off the startup path, and createFindMatch
+  // awaits this to know when the import + expansion have completed. Dropping it
+  // (typing this `void`) makes the import fire-and-forget, so findMatch spins the
+  // lazy-eval retry loop to its cap and returns null on the first request to any
+  // async include whose prefix isn't already covered by a unique precomputed entry
+  // (nested includes, shared prefixes, regex fallback).
+  function evaluateLazyEntry(entry: RouteEntry<TEnv>): void | Promise<void> {
+    return _evaluateLazyEntry(entry, lazyEvalDeps);
   }
 
   // Create findMatch with single-entry cache, bound to router state
@@ -602,6 +700,7 @@ export function createRouter<TEnv = any>(
 
   // Prerender/static match deps (bind closure state for extracted functions)
   const prerenderDeps = {
+    routerId,
     findMatch,
     buildRouterContext,
     mergedRouteMap,
@@ -613,6 +712,8 @@ export function createRouter<TEnv = any>(
     params: Record<string, string>,
     buildVars?: Record<string, any>,
     isPassthroughRoute?: boolean,
+    buildEnv?: TEnv,
+    devMode?: boolean,
   ) {
     return _matchForPrerender(
       pathname,
@@ -620,6 +721,8 @@ export function createRouter<TEnv = any>(
       prerenderDeps,
       buildVars,
       isPassthroughRoute,
+      buildEnv,
+      devMode,
     );
   }
 
@@ -627,12 +730,19 @@ export function createRouter<TEnv = any>(
     handler: Function,
     handlerId: string,
     routeName?: string,
+    buildEnv?: TEnv,
+    devMode?: boolean,
+    rootScoped?: boolean,
   ) {
     return _renderStaticSegment<TEnv>(
       handler,
       handlerId,
       mergedRouteMap,
       routeName,
+      buildEnv,
+      devMode,
+      routerId,
+      rootScoped,
     );
   }
 
@@ -645,6 +755,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -654,14 +765,48 @@ export function createRouter<TEnv = any>(
    * 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: RSCRouterInternal<TEnv, {}> = {
+  const router: RangoInternal<TEnv, {}> = {
     __brand: RSC_ROUTER_BRAND,
     id: routerId,
+    basename,
+
+    routes(
+      patternsOrBuilder:
+        | UrlPatterns<TEnv>
+        | UrlBuilder<TEnv>
+        | ClientUrlPatterns,
+    ): any {
+      // Pure-client mounting shorthand: a clientUrls() definition passed
+      // directly NORMALIZES to a root include in the canonical urls() tree —
+      // exactly `include("/", definition, { name: "" })`, keeping local route
+      // names bare and local patterns app-absolute. This is sugar over the
+      // ONE composition model, not a second registration path: it rides the
+      // same lazy include materialization, so no ordering, one-definition, or
+      // deferral rules exist. Prefixing, wrapping RSC layouts, and middleware
+      // scope still come from mounting through include() in urls() yourself.
+      if (
+        isClientUrlPatterns(patternsOrBuilder) ||
+        isClientUrlReference(patternsOrBuilder)
+      ) {
+        const clientSource = patternsOrBuilder as ClientUrlPatterns;
+        patternsOrBuilder = urls(({ include }) => [
+          include("/", clientSource, { name: "" }),
+        ]) as UrlPatterns<TEnv>;
+      }
+
+      // Wrap builder functions in urls() automatically
+      const urlPatterns: UrlPatterns<TEnv> =
+        typeof patternsOrBuilder === "function"
+          ? (urls(patternsOrBuilder) as UrlPatterns<TEnv>)
+          : patternsOrBuilder;
 
-    routes(urlPatterns: UrlPatterns<TEnv>): any {
       // Store reference for runtime manifest generation
       storedUrlPatterns = urlPatterns;
       const currentMountIndex = mountIndex++;
+      urlpatternMounts.push({
+        patterns: urlPatterns,
+        mountIndex: currentMountIndex,
+      });
 
       // Create manifest and patterns maps for route registration
       const manifest = new Map<string, EntryData>();
@@ -689,13 +834,13 @@ export function createRouter<TEnv = any>(
         errorBoundary: [],
         notFoundBoundary: [],
         layout: [],
-        parallel: [],
+        parallel: {},
         intercept: [],
         loader: [],
       };
 
       let handlerResult: AllUseItems[] = [];
-      RSCRouterContext.run(
+      RangoContext.run(
         {
           manifest,
           patterns: routePatterns,
@@ -705,7 +850,12 @@ export function createRouter<TEnv = any>(
           parent: syntheticMapRoot,
           counters: {},
           mountIndex: currentMountIndex,
+          routerId,
           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[];
@@ -725,7 +875,7 @@ export function createRouter<TEnv = any>(
         if (entry.type === "route" && entry.isPrerender) {
           if (!prerenderRouteKeys) prerenderRouteKeys = new Set();
           prerenderRouteKeys.add(name);
-          if (entry.prerenderDef?.options?.passthrough === true) {
+          if (entry.isPassthrough === true) {
             if (!passthroughRouteKeys) passthroughRouteKeys = new Set();
             passthroughRouteKeys.add(name);
           }
@@ -751,6 +901,7 @@ export function createRouter<TEnv = any>(
             trailingSlash: trailingSlashConfig,
             handler: urlPatterns.handler,
             mountIndex: currentMountIndex,
+            routerId,
             cacheProfiles: resolvedCacheProfiles,
             ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
             ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -770,6 +921,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: currentMountIndex,
+          routerId,
           cacheProfiles: resolvedCacheProfiles,
           ...(prerenderRouteKeys ? { prerenderRouteKeys } : {}),
           ...(passthroughRouteKeys ? { passthroughRouteKeys } : {}),
@@ -801,10 +953,13 @@ export function createRouter<TEnv = any>(
 
       // 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;
+        // 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: "",
@@ -813,6 +968,7 @@ export function createRouter<TEnv = any>(
           trailingSlash: trailingSlashConfig,
           handler: urlPatterns.handler,
           mountIndex: mountIndex++,
+          routerId,
           // Lazy evaluation fields
           lazy: true,
           lazyPatterns: lazyInclude.patterns,
@@ -851,8 +1007,18 @@ export function createRouter<TEnv = any>(
       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;
     },
 
@@ -888,15 +1054,35 @@ export function createRouter<TEnv = any>(
     // Expose prefetch cache settings
     prefetchCacheControl,
     prefetchCacheTTL,
+    prefetchCacheSize,
+    prefetchConcurrency,
+    defaultPrefetch,
+
+    // 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 StrictMode flag for the initial-render payload metadata
+    strictMode,
+
     // Expose router-wide performance debugging for request-level metrics setup
     debugPerformance,
 
-    // Expose debug manifest flag for handler
-    allowDebugManifest: allowDebugManifestOption,
+    // Expose the PPR shell-capture debug sink for the render layer
+    // (rsc-rendering resolves it into the capture descriptor)
+    debugShellCapture: debugShellCaptureOption,
+
+    // Expose resolved span tracing for the handler (Cloudflare custom spans)
+    tracing: resolvedTracing,
+
+    // Expose the raw telemetry sink so handler-level emitters (timeout, origin
+    // rejection, late-handle handler.error) can emit outside the match ALS.
+    // Raw (not the resolveSink no-op wrapper) so router.telemetry stays
+    // undefined when unconfigured and call sites gate on truthiness.
+    telemetry: telemetrySink,
 
     // Expose origin check configuration for handler (default: enabled)
     originCheck: originCheckOption ?? true,
@@ -950,9 +1136,26 @@ export function createRouter<TEnv = any>(
       return storedUrlPatterns ?? undefined;
     },
 
+    get __urlpatternMounts() {
+      return urlpatternMounts;
+    },
+
     // Expose source file for per-router type generation
     __sourceFile,
 
+    // Expose basename for runtime manifest generation
+    __basename: basename,
+
+    // Pin payload metadata to the worker generation that created this router.
+    __devDiscoveryEpoch: devDiscoveryEpoch,
+
+    // 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
@@ -964,14 +1167,28 @@ export function createRouter<TEnv = any>(
         | null = null;
 
       return async (request: Request, input: RouterRequestInput<TEnv> = {}) => {
+        if (
+          devDiscoveryEpoch !== undefined &&
+          request.headers.get(DEV_DISCOVERY_PROBE_HEADER) ===
+            String(devDiscoveryEpoch)
+        ) {
+          return new Response(null, {
+            headers: {
+              [DEV_DISCOVERY_EPOCH_HEADER]: String(devDiscoveryEpoch),
+            },
+          });
+        }
+
         // 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: handler.ts still accepts (request, env) — will be updated
-          // separately to accept RouterRequestInput.
+          // 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,
@@ -986,6 +1203,10 @@ export function createRouter<TEnv = any>(
       };
     })(),
 
+    // Low-level route matching for request classification
+    findMatch: (pathname: string, metricsStore?: any) =>
+      findMatch(pathname, metricsStore),
+
     // Debug utility for manifest inspection
     debugManifest: () => buildDebugManifest<TEnv>(routesEntries),
   };
@@ -994,8 +1215,10 @@ export function createRouter<TEnv = any>(
   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;