@rangojs/router 0.0.0-experimental.125 → 0.0.0-experimental.127

package/src/router/middleware.ts

@@ -12,20 +12,24 @@ import type {
   ResponseHolder,
 } from "./middleware-types.js";
 import { _getRequestContext } from "../server/request-context.js";
+import {
+  EXTERNAL_REDIRECT_MARKER,
+  isExternalRedirect,
+  markExternalRedirect,
+} from "../redirect-origin.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
+import { observePhase, PHASES } from "./instrument.js";
 import { stripInternalParams } from "./handler-context.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
-// Re-export types and cookie utilities consumed through this module's path.
+// Re-export types consumed through this module's path.
 export type {
   CookieOptions,
-  MiddlewareCollectableEntry,
   MiddlewareContext,
   MiddlewareEntry,
   MiddlewareFn,
 } from "./middleware-types.js";
-export { parseCookies, serializeCookie } from "./middleware-cookies.js";
 
 const MIDDLEWARE_METRIC_DEPTH = 1;
 const POST_METRIC_MIN_DURATION_MS = 0.01;
@@ -238,9 +242,13 @@ export function createMiddlewareContext<TEnv>(
 
     reverse:
       reverse ??
-      ((name: string) => {
+      ((
+        name: string,
+        _params?: Record<string, string>,
+        _search?: Record<string, unknown>,
+      ) => {
         throw new Error(
-          `ctx.reverse() is not available - route map was not provided to middleware context`,
+          `ctx.reverse(${JSON.stringify(name)}) is not available: no route map is bound to this middleware context.`,
         );
       }),
 
@@ -293,6 +301,10 @@ function mergeStubHeaders(
   stubOverridesNonCookie: boolean,
 ): void {
   stub.forEach((value, name) => {
+    // The reserved external-redirect marker is internal and never a trust
+    // signal; never copy a stub value (e.g. a stray ctx.header() call) onto a
+    // browser-facing response. The opt-in is the out-of-band brand.
+    if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
     if (name.toLowerCase() === "set-cookie") {
       target.append(name, value);
     } else if (stubOverridesNonCookie || !target.has(name)) {
@@ -318,12 +330,50 @@ function mergeReqCtxStub(
     }
   }
   reqCtx.res.headers.forEach((value, name) => {
+    // Never propagate the reserved external-redirect marker (see mergeStubHeaders).
+    if (name.toLowerCase() === EXTERNAL_REDIRECT_MARKER) return;
     if (name !== "set-cookie" && !target.has(name)) {
       target.set(name, value);
     }
   });
 }
 
+// Clone `base` with stub headers merged into a fresh Headers (the clone keeps
+// the body mutable for post-next() modifications). Set-Cookie is always
+// appended; other headers obey stubOverridesNonCookie (see mergeStubHeaders).
+// mergeReqCtx folds in RequestContext stub cookies/headers; the intercept
+// short-circuit path passes false (its reqCtx headers are not merged here),
+// which is the one deliberate divergence between the call sites.
+function mergeResponse(
+  base: Response,
+  stub: Headers,
+  opts: { stubOverridesNonCookie: boolean; mergeReqCtx: boolean },
+): Response {
+  const mergedHeaders = new Headers(base.headers);
+  // The reserved external-redirect marker is never a trust signal and must never
+  // reach the browser. The guard strips it on 3xx redirects; strip it here too so
+  // a forged value cannot ride a non-3xx middleware response (which the 3xx-only
+  // guard would not touch) to the client. The opt-in is the out-of-band brand.
+  mergedHeaders.delete(EXTERNAL_REDIRECT_MARKER);
+  mergeStubHeaders(mergedHeaders, stub, opts.stubOverridesNonCookie);
+  if (opts.mergeReqCtx) {
+    mergeReqCtxStub(mergedHeaders, _getRequestContext());
+  }
+  const merged = new Response(base.body, {
+    status: base.status,
+    statusText: base.statusText,
+    headers: mergedHeaders,
+  });
+  // Transfer the out-of-band external-redirect brand across this rebuild: a
+  // middleware short-circuit `return redirect(url, { external: true })` reaches
+  // the open-redirect guard only after this merge, and the brand lives on the
+  // Response object, not in its headers.
+  if (isExternalRedirect(base)) {
+    markExternalRedirect(merged);
+  }
+  return merged;
+}
+
 /**
  * Execute middleware chain
  *
@@ -362,20 +412,16 @@ export async function executeMiddleware<TEnv>(
       // End of chain - call actual RSC handler
       const response = await finalHandler();
 
-      const mergedHeaders = new Headers(response.headers);
-      mergeStubHeaders(mergedHeaders, stubResponse.headers, true);
-      mergeReqCtxStub(mergedHeaders, _getRequestContext());
-
       if (isWebSocketUpgradeResponse(response)) {
         responseHolder.response = response;
         return response;
       }
 
-      // Clone response with merged headers (mutable for post-next() modifications)
-      responseHolder.response = new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: mergedHeaders,
+      // Chain ran to completion: stub headers overwrite (stubOverridesNonCookie)
+      // and reqCtx stub headers are merged in.
+      responseHolder.response = mergeResponse(response, stubResponse.headers, {
+        stubOverridesNonCookie: true,
+        mergeReqCtx: true,
       });
 
       return responseHolder.response;
@@ -433,9 +479,17 @@ export async function executeMiddleware<TEnv>(
       return nextPromise;
     };
 
+    // Wrap the middleware (including its downstream next() chain) in its span
+    // via the unified phase API. metric:false — the middleware's perf metric is
+    // its exclusive pre/post own-time, recorded directly above and below, finer
+    // than a single wrap. Spans nest by async context, so this onions
+    // middleware-over-middleware and the core handler underneath. Pass-through
+    // when neither surface is active.
     let result: Response | void;
     try {
-      result = await entry.handler(ctx, wrappedNext);
+      result = await observePhase(PHASES.middleware(metricLabel), () =>
+        entry.handler(ctx, wrappedNext),
+      );
     } catch (error) {
       // Thrown Response is short-circuit control flow, not an error.
       // Fall through to the `if (result instanceof Response)` branch below
@@ -474,13 +528,11 @@ export async function executeMiddleware<TEnv>(
         responseHolder.response = result;
         return result;
       }
-      const mergedHeaders = new Headers(result.headers);
-      mergeStubHeaders(mergedHeaders, stubResponse.headers, false);
-      mergeReqCtxStub(mergedHeaders, _getRequestContext());
-      const merged = new Response(result.body, {
-        status: result.status,
-        statusText: result.statusText,
-        headers: mergedHeaders,
+      // Explicit short-circuit: the returned Response's own headers win
+      // (stubOverridesNonCookie=false); reqCtx stub headers still merge in.
+      const merged = mergeResponse(result, stubResponse.headers, {
+        stubOverridesNonCookie: false,
+        mergeReqCtx: true,
       });
       responseHolder.response = merged;
       return merged;
@@ -579,6 +631,7 @@ export async function executeInterceptMiddleware<TEnv>(
       return stubResponse;
     }
 
+    const ordinal = index;
     const middleware = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -600,9 +653,20 @@ export async function executeInterceptMiddleware<TEnv>(
       return next();
     };
 
+    // Span-wrap each intercept middleware as rango.middleware (metric:false —
+    // intercept runs inside the render phase already metered by render:total, so
+    // it contributes a span but no separate perf metric). Bare MiddlewareFns
+    // have no pattern, so the label is scoped to "*" like a pattern-less entry.
+    const label = getMiddlewareMetricLabel(
+      { handler: middleware, pattern: null } as MiddlewareEntry<TEnv>,
+      ordinal,
+    );
+
     let result: Response | void;
     try {
-      result = await middleware(ctx, guardedNext);
+      result = await observePhase(PHASES.middleware(label), () =>
+        middleware(ctx, guardedNext),
+      );
     } catch (error) {
       // Thrown Response is short-circuit control flow, parity with the
       // explicit-return path below. Real errors propagate.
@@ -635,15 +699,13 @@ export async function executeInterceptMiddleware<TEnv>(
     });
 
     if (hasStubHeaders) {
-      // Clone and merge headers from stub into early response.
-      // Only fill in missing headers — the returned Response's explicit
-      // headers take precedence, matching executeMiddleware behavior.
-      const mergedHeaders = new Headers(response.headers);
-      mergeStubHeaders(mergedHeaders, stubResponse.headers, false);
-      return new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers: mergedHeaders,
+      // Only fill in missing headers — the returned Response's explicit headers
+      // take precedence (stubOverridesNonCookie=false), matching executeMiddleware.
+      // mergeReqCtx=false: the intercept path deliberately does NOT merge reqCtx
+      // stub headers here (pinned by intercept-middleware-headers.test.ts).
+      return mergeResponse(response, stubResponse.headers, {
+        stubOverridesNonCookie: false,
+        mergeReqCtx: false,
       });
     }
     return response;
@@ -684,7 +746,6 @@ export async function executeLoaderMiddleware<TEnv>(
       regex: null,
       paramNames: [],
       handler,
-      mountPrefix: null,
     } as MiddlewareEntry<TEnv>,
     params,
   }));

package/src/router/pattern-matching.ts

@@ -74,7 +74,6 @@ export function parsePattern(pattern: string): ParsedSegment[] {
 export interface CompiledPattern {
   regex: RegExp;
   paramNames: string[];
-  optionalParams: Set<string>;
   hasTrailingSlash: boolean;
   /**
    * Param-name → allowed values for constrained params (e.g. `:lang(en|gb)`).
@@ -142,7 +141,6 @@ export function compilePattern(pattern: string): CompiledPattern {
 
   const segments = parsePattern(normalizedPattern);
   const paramNames: string[] = [];
-  const optionalParams = new Set<string>();
   let constraints: Record<string, string[]> | undefined;
 
   let regexPattern = "";
@@ -164,7 +162,6 @@ export function compilePattern(pattern: string): CompiledPattern {
       }
 
       if (segment.optional) {
-        optionalParams.add(segment.value);
         // Optional: make the whole /segment optional
         regexPattern += `(?:/${valuePattern}${suffixPattern})?`;
       } else {
@@ -202,7 +199,6 @@ export function compilePattern(pattern: string): CompiledPattern {
   return {
     regex: new RegExp(`^${regexPattern}$`),
     paramNames,
-    optionalParams,
     hasTrailingSlash,
     ...(constraints ? { constraints } : {}),
   };
@@ -325,8 +321,8 @@ export function joinPrefix(base: string | undefined, prefix: string): string {
  *
  * Note: Optional params that are absent in the path are omitted from the
  * returned `params` (read as `undefined`), matching the trie matcher and
- * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition or
- * `optionalParams` to determine which keys are optional.
+ * the `ExtractParams<"/:locale?/...">` type. Use the pattern definition to
+ * determine which keys are optional.
  *
  * Trailing slash handling (priority order):
  * 1. Per-route `trailingSlash` config from route()
@@ -344,7 +340,6 @@ export interface RouteMatchResult<TEnv = any> {
   entry: RouteEntry<TEnv>;
   routeKey: string;
   params: Record<string, string>;
-  optionalParams: Set<string>;
   redirectTo?: string;
   /** Route has pre-rendered data available (from trie) */
   pr?: true;
@@ -463,13 +458,8 @@ export function findMatch<TEnv>(
         fullPattern = entry.prefix + pattern;
       }
 
-      const {
-        regex,
-        paramNames,
-        optionalParams,
-        hasTrailingSlash,
-        constraints,
-      } = getCompiledPattern(fullPattern);
+      const { regex, paramNames, hasTrailingSlash, constraints } =
+        getCompiledPattern(fullPattern);
 
       const trailingSlashMode: TrailingSlashMode | undefined =
         entry.trailingSlash?.[routeKey];
@@ -506,7 +496,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             redirectTo: pathname + "/",
             ...prFlag,
             ...ptFlag,
@@ -516,7 +505,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             redirectTo: pathname.slice(0, -1),
             ...prFlag,
             ...ptFlag,
@@ -527,7 +515,6 @@ export function findMatch<TEnv>(
           entry,
           routeKey,
           params,
-          optionalParams,
           ...prFlag,
           ...ptFlag,
         };
@@ -546,7 +533,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             ...prFlag,
             ...ptFlag,
           };
@@ -556,7 +542,6 @@ export function findMatch<TEnv>(
               entry,
               routeKey,
               params,
-              optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
               ...ptFlag,
@@ -566,7 +551,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             ...prFlag,
             ...ptFlag,
           };
@@ -576,7 +560,6 @@ export function findMatch<TEnv>(
               entry,
               routeKey,
               params,
-              optionalParams,
               redirectTo: alternatePathname,
               ...prFlag,
               ...ptFlag,
@@ -586,7 +569,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             ...prFlag,
             ...ptFlag,
           };
@@ -598,7 +580,6 @@ export function findMatch<TEnv>(
             entry,
             routeKey,
             params,
-            optionalParams,
             redirectTo: canonicalPath,
             ...prFlag,
             ...ptFlag,

package/src/router/prerender-match.ts

@@ -5,7 +5,7 @@ import {
   runWithRequestContext,
   type RequestContext,
 } from "../server/request-context.js";
-import { contextGet, contextSet } from "../context-var.js";
+import { contextGet, contextSet, hasContextVars } from "../context-var.js";
 import {
   createPrerenderContext,
   createStaticContext,
@@ -17,6 +17,7 @@ import { setupBuildUse } from "./loader-resolution.js";
 import { loadManifest } from "./manifest.js";
 import { traverseBack } from "./pattern-matching.js";
 import type { RouterContext } from "./router-context.js";
+import type { ResolveSegmentOptions } from "./segment-resolution.js";
 import { runWithRouterContext } from "./router-context.js";
 import type { EntryData, InterceptEntry } from "../server/context";
 import type {
@@ -40,7 +41,7 @@ export interface PrerenderMatchDeps<TEnv = any> {
     params: Record<string, string>,
     context: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
-    options?: { skipLoaders?: boolean },
+    options?: ResolveSegmentOptions,
   ) => Promise<ResolvedSegment[]>;
 }
 
@@ -159,10 +160,7 @@ export async function matchForPrerender<TEnv = any>(
             return passthroughResult();
           }
           // Preserve vars set by getParams() for the render context
-          if (
-            Object.keys(probeBuildVars).length > 0 ||
-            Object.getOwnPropertySymbols(probeBuildVars).length > 0
-          ) {
+          if (hasContextVars(probeBuildVars)) {
             devProbeBuildVars = probeBuildVars;
           }
         } catch (err: any) {
@@ -260,7 +258,9 @@ export async function matchForPrerender<TEnv = any>(
         matchedParams,
         buildCtx,
         loaderPromises,
-        { skipLoaders: true },
+        // throwOnError: a render failure (or `throw new Skip()`) must reach the
+        // build/dev caller, not be baked into a frozen error page (issue #587).
+        { skipLoaders: true, throwOnError: true },
       );
 
       // 9. Detect passthrough sentinel: handler returned ctx.passthrough().
@@ -332,6 +332,18 @@ export async function matchForPrerender<TEnv = any>(
         const interceptResolvedSegments: typeof nonLoaderSegments = [];
 
         for (const { intercept, entry: parentEntry } of foundIntercepts) {
+          // setupBuildUse keys handle pushes by ctx._currentSegmentId. The main
+          // resolveAllSegments pass left it on the route's segment id, so pin it
+          // to THIS intercept's slot id before resolving the handler/layout --
+          // otherwise the intercept's ctx.use() handle pushes land in the wrong
+          // bucket and getDataForSegment(seg.id) below drops them from the baked
+          // artifact. Re-pinned per iteration so multiple intercepts targeting
+          // the same route each get their own id (mirrors fresh.ts parallel-slot
+          // pinning).
+          const interceptSegmentId = `${parentEntry.shortCode}.${intercept.slotName}`;
+          (buildCtx as InternalHandlerContext<any, TEnv>)._currentSegmentId =
+            interceptSegmentId;
+
           // Resolve handler
           const handlerRaw =
             typeof intercept.handler === "function"
@@ -358,7 +370,7 @@ export async function matchForPrerender<TEnv = any>(
           }
 
           interceptResolvedSegments.push({
-            id: `${parentEntry.shortCode}.${intercept.slotName}`,
+            id: interceptSegmentId,
             namespace: `intercept:${intercept.routeName}`,
             type: "parallel" as const,
             index: 0,
@@ -489,6 +501,18 @@ export async function renderStaticSegment<TEnv = any>(
 
     const raw = await handler(buildCtx);
 
+    // Static handlers must return a ReactNode. A returned Response (e.g. an
+    // accidental redirect()) would otherwise be serialized as a corrupt build
+    // artifact; fail loudly instead. The fresh/revalidation paths route handler
+    // results through handleHandlerResult, which throws Responses; the static
+    // build path bypasses that, so guard here.
+    if (raw instanceof Response) {
+      throw new TypeError(
+        `Static handler "${routeName}" returned a Response. Static handlers must return a ReactNode; ` +
+          `Responses (redirects, file responses) are not supported during static pre-rendering.`,
+      );
+    }
+
     const segment: ResolvedSegment = {
       id: handlerId,
       namespace: handlerId,

package/src/router/revalidation.ts

@@ -33,16 +33,21 @@ function resolveActionRefId(ref: unknown): string | undefined {
 }
 
 /**
- * Build the `isAction()` helper bound to the current action's id. Matches a
- * single imported action reference, several (variadic), or any export of a
- * namespace import (`import * as Mod`). Returns `false` when there is no action
- * (plain navigation) or nothing matches.
+ * Build the `isAction()` helper bound to the current action's id. Called with no
+ * arguments it answers "is this request an action at all?" (any action) — `true`
+ * during action handling, `false` on plain navigation. Called with one or more
+ * action references it narrows to those: a single imported action, several
+ * (variadic), or any export of a namespace import (`import * as Mod`). Returns
+ * `false` when there is no action (plain navigation) or nothing matches.
  */
 function makeIsAction(
   currentActionId: string | undefined,
 ): (...actions: ActionRef[]) => boolean {
   return (...actions: ActionRef[]): boolean => {
     if (!currentActionId) return false;
+    // Bare isAction(): an action is in flight (currentActionId is set) and the
+    // caller did not narrow to a specific action, so this is "any action".
+    if (actions.length === 0) return true;
     for (const action of actions) {
       if (typeof action === "function") {
         if (resolveActionRefId(action) === currentActionId) return true;

package/src/router/route-snapshot.ts

@@ -230,7 +230,6 @@ export function createRouteSnapshot<TEnv = any>(
       entry: {} as any,
       routeKey: "test",
       params: {},
-      optionalParams: new Set(),
     } as RouteMatchResult<TEnv>,
     manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
     entries: [],

package/src/router/router-context.ts

@@ -19,6 +19,7 @@ import type {
 } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
 import type { TelemetrySink } from "./telemetry.js";
+import type { ResolveSegmentOptions } from "./segment-resolution.js";
 
 /**
  * Revalidation context passed to segment resolution
@@ -123,7 +124,6 @@ export interface RouterContext<TEnv = any> {
     request: Request,
     prevUrl: URL,
     nextUrl: URL,
-    loaderPromises: Map<string, Promise<any>>,
     actionContext: any | undefined,
     interceptResult: InterceptResult | null,
     localRouteName: string,
@@ -196,7 +196,7 @@ export interface RouterContext<TEnv = any> {
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
-    options?: { skipLoaders?: boolean },
+    options?: ResolveSegmentOptions,
   ) => Promise<ResolvedSegment[]>;
 
   resolveAllSegmentsGenerator?: (

package/src/router/router-interfaces.ts

@@ -9,10 +9,12 @@ import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
+import type { ExtractParams } from "../types/route-config.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RangoOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
 import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
+import type { ResolvedTracing } from "./tracing.js";
 
 /**
  * Options passed to router.fetch(), router.match(), and other request entrypoints.
@@ -105,9 +107,14 @@ export interface Rango<
    * createRouter({ document: RootLayout })
    *   .use(loggerMiddleware)           // All routes
    *   .use("/api/*", rateLimiter)      // Pattern match
+   *   .use("/users/:id", (ctx) => {})  // ctx.params.id is typed
    *   .routes(urlpatterns)
    * ```
    */
+  use<Pattern extends string>(
+    pattern: Pattern,
+    middleware: MiddlewareFn<TEnv, ExtractParams<Pattern>>,
+  ): Rango<TEnv, TRoutes>;
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
@@ -225,6 +232,10 @@ export interface RangoInternal<
   /**
    * Add global middleware that runs on all routes
    */
+  use<Pattern extends string>(
+    pattern: Pattern,
+    middleware: MiddlewareFn<TEnv, ExtractParams<Pattern>>,
+  ): Rango<TEnv, TRoutes>;
   use(
     patternOrMiddleware: string | MiddlewareFn<TEnv>,
     middleware?: MiddlewareFn<TEnv>,
@@ -310,6 +321,13 @@ export interface RangoInternal<
    */
   readonly debugPerformance?: boolean;
 
+  /**
+   * Resolved platform phase-span tracing (Cloudflare custom spans or OTel), or
+   * undefined when off. Threaded onto the request context and read at each
+   * traced phase.
+   */
+  readonly tracing?: ResolvedTracing;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.

package/src/router/router-options.ts

@@ -11,6 +11,7 @@ import type { UrlPatterns } from "../urls.js";
 import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { NamedRouteEntry } from "./content-negotiation.js";
 import type { TelemetrySink } from "./telemetry.js";
+import type { RouterTracingConfig } from "./tracing.js";
 import type { RouterTimeouts, OnTimeoutCallback } from "./timeout.js";
 
 /**
@@ -574,11 +575,14 @@ export interface RangoOptions<TEnv = any> {
   onTimeout?: OnTimeoutCallback<TEnv>;
 
   /**
-   * Telemetry sink for structured lifecycle events.
+   * Telemetry sink for structured, discrete lifecycle EVENTS: request
+   * start/end/error, loader start/end/error, handler errors, cache decisions,
+   * revalidation decisions, timeouts, origin rejections.
    *
-   * When provided, the router emits events for request start/end,
-   * loader start/end/error, handler errors, cache decisions, and
-   * revalidation decisions.
+   * This is the EVENT surface. Phase-duration SPANS (request/loader/render/ssr
+   * timing wired into a tracing backend) come from the separate `tracing`
+   * option below — a sink does not emit them, because async-context nesting
+   * cannot be faithfully reconstructed from after-the-fact start/end events.
    *
    * No-op when not configured (zero overhead).
    *
@@ -591,6 +595,18 @@ export interface RangoOptions<TEnv = any> {
    * });
    * ```
    *
+   * @example OpenTelemetry — pair the event sink with the tracing slot
+   * ```typescript
+   * import { createOTelTracing, createOTelSink } from "@rangojs/router";
+   * import { trace } from "@opentelemetry/api";
+   *
+   * const tracer = trace.getTracer("my-app");
+   * const router = createRouter({
+   *   tracing: createOTelTracing(tracer), // phase spans
+   *   telemetry: createOTelSink(tracer), // discrete-fact events
+   * });
+   * ```
+   *
    * @example Custom sink
    * ```typescript
    * const router = createRouter({
@@ -604,6 +620,44 @@ export interface RangoOptions<TEnv = any> {
    */
   telemetry?: TelemetrySink;
 
+  /**
+   * Span tracing for the router's performance phases (request, middleware, action,
+   * loaders, render, ssr). Connects the same phases shown in the
+   * `debugPerformance` timeline to the host platform's tracing system. This is
+   * the SPAN surface (the `telemetry` option above is the event surface).
+   *
+   * Two factories produce a config, both for this slot:
+   * - `createOTelTracing(tracer)` from `@rangojs/router` — any platform with an
+   *   OpenTelemetry SDK (including Node). Bridges the phases onto
+   *   `tracer.startActiveSpan`.
+   * - `createCloudflareTracing()` from `@rangojs/router/cloudflare` — Cloudflare
+   *   Workers native custom spans, alongside the automatic KV/D1/fetch spans.
+   *
+   * When tracing is unset — or off-platform (no OTel SDK / no Cloudflare tracing
+   * destination) — every span call falls through to the work directly, so the
+   * request behaves exactly as if tracing were off.
+   *
+   * @example OpenTelemetry
+   * ```typescript
+   * import { createOTelTracing } from "@rangojs/router";
+   * import { trace } from "@opentelemetry/api";
+   *
+   * const router = createRouter({
+   *   tracing: createOTelTracing(trace.getTracer("my-app")),
+   * });
+   * ```
+   *
+   * @example Cloudflare
+   * ```typescript
+   * import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+   *
+   * const router = createRouter({
+   *   tracing: createCloudflareTracing({ spans: { ssr: false } }),
+   * });
+   * ```
+   */
+  tracing?: RouterTracingConfig;
+
   /**
    * SSR configuration options.
    *