@rangojs/router 0.0.0-experimental.79 → 0.0.0-experimental.7c7e4327

package/src/router/types.ts

@@ -22,27 +22,11 @@ import type {
   ShouldRevalidateFn,
 } from "../types";
 
-/**
- * Result of resolving loaders with revalidation
- * Contains both segments to render and all matched segment IDs
- */
-export interface LoaderRevalidationResult {
-  segments: ResolvedSegment[];
-  matchedIds: string[];
-}
-
-/**
- * Result of resolving segments with revalidation
- * Contains both segments to render and all matched segment IDs
- */
 export interface SegmentRevalidationResult {
   segments: ResolvedSegment[];
   matchedIds: string[];
 }
 
-/**
- * Action context type for revalidation
- */
 export type ActionContext = {
   actionId?: string;
   actionUrl?: URL;
@@ -50,23 +34,6 @@ export type ActionContext = {
   formData?: FormData;
 };
 
-/**
- * Dependencies passed to segment resolution functions
- * These are created within createRouter and passed to extracted utilities
- */
-export interface RouterDependencies<TEnv> {
-  findNearestErrorBoundary: (
-    entry: EntryData | null,
-  ) => ReactNode | ErrorBoundaryHandler | null;
-  findNearestNotFoundBoundary: (
-    entry: EntryData | null,
-  ) => ReactNode | NotFoundBoundaryHandler | null;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted segment resolution functions.
- * These are the closure-bound helpers that cannot be imported directly.
- */
 export interface SegmentResolutionDeps<TEnv = any> {
   wrapLoaderPromise: <T>(
     promise: Promise<T>,
@@ -98,23 +65,16 @@ export interface SegmentResolutionDeps<TEnv = any> {
   ) => ReactNode | NotFoundBoundaryHandler | null;
   notFoundComponent?: ReactNode | ((props: { pathname: string }) => ReactNode);
   callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+  /**
+   * Router-level default for the per-segment `transition({ viewTransition })`
+   * flag, from createRouter({ viewTransition }). Resolved into each segment's
+   * transition config during resolution (only `false` is stamped) so the render
+   * gate reads the boundary decision off the segment on both server and client.
+   * Undefined is treated as "auto" (wrap).
+   */
+  viewTransitionDefault?: "auto" | false;
 }
 
-/**
- * Dependencies injected from createRouter closure into extracted intercept resolution functions.
- */
-export interface InterceptResolutionDeps<TEnv = any> {
-  wrapLoaderPromise: SegmentResolutionDeps<TEnv>["wrapLoaderPromise"];
-  evaluateInterceptWhen: (
-    intercept: InterceptEntry,
-    selectorContext: InterceptSelectorContext | null,
-    isAction: boolean,
-  ) => boolean;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted match API functions.
- */
 export interface MatchApiDeps<TEnv = any> {
   findMatch: (pathname: string, ms?: any) => any;
   getMetricsStore: () => any;
@@ -129,23 +89,13 @@ export interface MatchApiDeps<TEnv = any> {
   getRouteMap: () => Record<string, string>;
 }
 
-/**
- * Title descriptor types for template support
- */
 export type TitleDescriptor =
   | string
   | { template: string; default: string } // For layouts - template applied to child titles
-  | { absolute: string }; // Bypass parent template
+  | { absolute: string };
 
-/**
- * Unset descriptor to remove inherited meta
- * Key format matches getMetaKey output: "title", "name:description", "property:og:image"
- */
 export type UnsetDescriptor = { unset: string };
 
-/**
- * Base meta descriptor types (sync values)
- */
 export type MetaDescriptorBase =
   | { charSet: "utf-8" }
   | { title: TitleDescriptor }
@@ -157,10 +107,6 @@ export type MetaDescriptorBase =
   | UnsetDescriptor
   | { [name: string]: unknown };
 
-/**
- * Meta descriptor that can be sync or async.
- * Use Promise<MetaDescriptorBase> for streaming meta that resolves after initial render.
- */
 export type MetaDescriptor = MetaDescriptorBase | Promise<MetaDescriptorBase>;
 
 type LdJsonObject = { [Key in string]: LdJsonValue } & {

package/src/router/url-params.ts

@@ -0,0 +1,57 @@
+/**
+ * URL param encode/decode at the route boundary.
+ *
+ * Extraction (decode): regex/trie matchers keep param values URL-encoded;
+ * `safeDecodeURIComponent` turns them back into raw strings so `ctx.params`
+ * matches the contract apps expect (Express/React Router/Fastify/Koa) and
+ * round-trips through reverse stay stable. Malformed %-encoding is
+ * preserved as-is so a broken URL doesn't crash matching.
+ *
+ * Reversal (encode): `encodePathSegment` escapes only what RFC 3986
+ * requires for a path segment — `/`, `?`, `#`, space, control chars,
+ * non-ASCII — and leaves pchar sub-delims (`@ : $ & + , ; =` and friends)
+ * readable. `encodeURIComponent` over-encodes for path segments, which
+ * makes generated URLs harder for humans to read in the address bar
+ * (e.g. mailbox IDs like `ivo@example.com` would become
+ * `ivo%40example.com` even though `@` is path-legal).
+ */
+
+export function safeDecodeURIComponent(raw: string): string {
+  if (raw === "" || raw.indexOf("%") === -1) return raw;
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
+const PATH_SAFE_ESCAPES: Record<string, string> = {
+  "%3A": ":",
+  "%40": "@",
+  "%24": "$",
+  "%26": "&",
+  "%2B": "+",
+  "%2C": ",",
+  "%3B": ";",
+  "%3D": "=",
+};
+
+export function encodePathSegment(value: string): string {
+  return encodeURIComponent(value).replace(
+    /%(?:3A|40|24|26|2B|2C|3B|3D)/gi,
+    (match) => PATH_SAFE_ESCAPES[match.toUpperCase()] ?? match,
+  );
+}
+
+/**
+ * Encode a catch-all remainder: encode each `/`-separated segment but keep the
+ * separators, so `a/b c` -> `a/b%20c` (not `a%2Fb%20c`). Shared by the reverse
+ * helper and the build-time prerender substitution so both produce identical
+ * URLs. `encode` defaults to the path-safe `encodePathSegment`.
+ */
+export function encodePathRemainder(
+  value: string,
+  encode: (segment: string) => string = encodePathSegment,
+): string {
+  return value.split("/").map(encode).join("/");
+}

package/src/router.ts

@@ -1,9 +1,6 @@
 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 { DefaultDocument } from "./components/DefaultDocument.js";
@@ -21,11 +18,11 @@ 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";
@@ -57,6 +54,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,
@@ -65,15 +63,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,
@@ -91,13 +91,10 @@ 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,
 } from "./router/router-interfaces.js";
 
@@ -112,26 +109,32 @@ 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 {
+  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,
@@ -151,31 +154,48 @@ export function createRouter<TEnv = any>(
     nonce,
     version,
     prefetchCacheTTL: prefetchCacheTTLOption,
+    prefetchCacheSize: prefetchCacheSizeOption,
+    prefetchConcurrency: prefetchConcurrencyOption,
+    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,
+    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.
-  const basename =
-    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
-      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
-      : undefined;
+  // 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).
@@ -210,21 +230,40 @@ export function createRouter<TEnv = any>(
   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;
+  // 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 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)
@@ -256,9 +295,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)
@@ -322,7 +366,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;
     }
@@ -332,7 +376,6 @@ export function createRouter<TEnv = any>(
       regex,
       paramNames,
       handler,
-      mountPrefix,
     });
   }
 
@@ -366,23 +409,28 @@ export function createRouter<TEnv = any>(
       getRouterPrecomputedEntries(routerId) ?? getPrecomputedEntries();
     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;
   };
 
@@ -393,11 +441,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).
@@ -408,13 +451,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", {
@@ -456,8 +500,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,
@@ -511,7 +559,6 @@ export function createRouter<TEnv = any>(
 
     // 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",
@@ -538,6 +585,7 @@ export function createRouter<TEnv = any>(
     findNearestNotFoundBoundary,
     notFoundComponent: notFound,
     callOnError,
+    viewTransitionDefault: viewTransitionOption,
   };
 
   // Match API dependencies
@@ -574,8 +622,15 @@ export function createRouter<TEnv = any>(
     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
@@ -665,6 +720,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -674,7 +730,7 @@ 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,
@@ -722,7 +778,7 @@ export function createRouter<TEnv = any>(
       };
 
       let handlerResult: AllUseItems[] = [];
-      RSCRouterContext.run(
+      RangoContext.run(
         {
           manifest,
           patterns: routePatterns,
@@ -834,10 +890,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: "",
@@ -932,13 +991,31 @@ export function createRouter<TEnv = any>(
     // Expose prefetch cache settings
     prefetchCacheControl,
     prefetchCacheTTL,
+    prefetchCacheSize,
+    prefetchConcurrency,
+
+    // 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 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 debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 
@@ -1000,6 +1077,13 @@ export function createRouter<TEnv = any>(
     // 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
@@ -1017,8 +1101,10 @@ export function createRouter<TEnv = any>(
         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,
@@ -1046,9 +1132,9 @@ export function createRouter<TEnv = any>(
 
   // If urls option was provided, auto-register them
   if (typeof urlsOption === "function") {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
   } else if (urlsOption) {
-    return router.routes(urlsOption) as RSCRouter<TEnv, {}>;
+    return router.routes(urlsOption) as Rango<TEnv, {}>;
   }
 
   return router;