@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/router/segment-resolution/loader-snapshot.ts

@@ -0,0 +1,259 @@
+/**
+ * Loader-family capture snapshot: elide + overlay for bake-lane loader
+ * containers (docs/design/loader-container-bake.md).
+ *
+ * A loader on an entry with NO renderable loading() executes during shell
+ * capture; its settled container bakes into the prelude while every promise
+ * still pending at the quiet window postpones as a hole. To keep a HIT's fresh
+ * payload byte-identical to that frozen prelude, the capture pins the container
+ * in the shell snapshot:
+ *
+ *   - elide:   deep-walk the settled container; a PENDING nested promise is a
+ *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
+ *              loader-cache masks every nested thenable at capture
+ *              ({@link maskNestedContainerThenables}), nested promises are
+ *              ALWAYS pending here for new captures. The SETTLED-marker branch
+ *              below is legacy: it fires only if a settled thenable reaches
+ *              elide anyway, and the overlay keeps decoding SETTLED markers
+ *              from pre-mask snapshots. The result is promise-free and
+ *              Flight-serializable.
+ *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
+ *              the live nested promises), then the recorded container is laid
+ *              over it: recorded paths win (they are what the prelude froze),
+ *              hole-marker paths take the fresh run's value (the live hole),
+ *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
+ *              wrote use(data.x) against a promise-shaped container, and
+ *              handing them the raw value throws React #438 on every HIT (the
+ *              storefront PDP regression) — and fresh-only paths pass through
+ *              (they cannot contradict prelude bytes that never rendered them).
+ */
+
+import { isThenable } from "../../handles/is-thenable.js";
+
+// Capture-side nested-thenable masking lives in the LEAF module mask-nested.ts
+// (request-context also needs it for handle pushes and cannot import through
+// loader-mask without a cycle). Re-exported here so loader-cache and the unit
+// tests keep one import site for the snapshot family.
+export { maskNestedContainerThenables } from "./mask-nested.js";
+
+/**
+ * Marker object standing in for a pending nested promise in a recorded loader
+ * container. Shape-checked (not identity-checked) because the record round-trips
+ * through Flight serialization and a JSON-embedding store envelope.
+ */
+export const LOADER_HOLE_KEY = "$rangoLoaderHole" as const;
+
+export interface LoaderHoleMarker {
+  [LOADER_HOLE_KEY]: 1;
+}
+
+export function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_HOLE_KEY] === 1
+  );
+}
+
+/**
+ * Marker wrapping the inlined value of a NESTED promise that settled during
+ * capture. The value baked (physics), but the container key was a promise —
+ * the overlay must hand consumers a Promise.resolve(value), not the raw value,
+ * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
+ * container is never wrapped: loader-cache overlays against the awaited fresh
+ * container value.
+ */
+export const LOADER_SETTLED_KEY = "$rangoLoaderSettled" as const;
+
+export interface LoaderSettledMarker {
+  [LOADER_SETTLED_KEY]: 1;
+  value: unknown;
+  /**
+   * Present when the pinned subtree contains hole markers. Computed once at
+   * capture (elide already visits every node) so the per-HIT overlay never
+   * rescans the pinned structure to pick its rehydration path.
+   */
+  holes?: 1;
+}
+
+export function isLoaderSettledMarker(
+  value: unknown,
+): value is LoaderSettledMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_SETTLED_KEY] === 1
+  );
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Probe whether a promise is already settled without waiting for it: races it
+ * against an immediately-resolved sentinel across two microtask hops (then
+ * chaining means a resolved inner value needs one extra hop to surface).
+ * Returns the settled state, or "pending" if it has not settled by then.
+ */
+async function probeSettled(
+  p: PromiseLike<unknown>,
+): Promise<
+  | { state: "fulfilled"; value: unknown }
+  | { state: "rejected" }
+  | { state: "pending" }
+> {
+  const PENDING = Symbol("pending");
+  // Two sentinel hops: Promise.resolve(p) adoption costs a microtask, so a
+  // single-hop sentinel would misreport an already-fulfilled promise as pending.
+  const sentinel = Promise.resolve()
+    .then(() => undefined)
+    .then(() => PENDING as unknown);
+  try {
+    const raced = await Promise.race([Promise.resolve(p), sentinel]);
+    if (raced === PENDING) return { state: "pending" };
+    return { state: "fulfilled", value: raced };
+  } catch {
+    return { state: "rejected" };
+  }
+}
+
+export type ElideResult =
+  | { state: "ok"; value: unknown; hasHole: boolean }
+  | { state: "rejected" };
+
+/**
+ * Deep-elide a settled bake-lane container for recording. Settled nested
+ * promises pin their value behind a settled marker (they baked, but consumers
+ * hold a promise-shaped key); pending ones become hole markers; a REJECTED
+ * nested promise poisons the record (error UI must never bake into a shared
+ * shell) — the caller refuses the capture. Only plain objects/arrays are
+ * traversed; anything else (Date, Map, class instance) is a pinned leaf.
+ * Cycles are cut as pinned references (best effort — Flight rejects true
+ * cycles later regardless).
+ *
+ * The ROOT container promise-chain unwraps with NO marker: loader-cache
+ * overlays against the AWAITED fresh container, so the recorded root must be
+ * the unwrapped structure. Everything below it goes through elideNested.
+ */
+export async function elideLoaderContainer(
+  value: unknown,
+  seen: Set<object> = new Set(),
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    return elideLoaderContainer(probed.value, seen);
+  }
+  return elideNested(value, seen);
+}
+
+async function elideNested(
+  value: unknown,
+  seen: Set<object>,
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    const inner = await elideNested(probed.value, seen);
+    if (inner.state === "rejected") return inner;
+    const marker: LoaderSettledMarker = inner.hasHole
+      ? { [LOADER_SETTLED_KEY]: 1, value: inner.value, holes: 1 }
+      : { [LOADER_SETTLED_KEY]: 1, value: inner.value };
+    return { state: "ok", value: marker, hasHole: inner.hasHole };
+  }
+
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
+    seen.add(value);
+    const out: unknown[] = new Array(value.length);
+    let hasHole = false;
+    for (let i = 0; i < value.length; i++) {
+      const r = await elideNested(value[i], seen);
+      if (r.state === "rejected") return r;
+      out[i] = r.value;
+      hasHole ||= r.hasHole;
+    }
+    return { state: "ok", value: out, hasHole };
+  }
+
+  if (isPlainObject(value)) {
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
+    seen.add(value);
+    const out: Record<string, unknown> = {};
+    let hasHole = false;
+    for (const key of Object.keys(value)) {
+      const r = await elideNested(value[key], seen);
+      if (r.state === "rejected") return r;
+      out[key] = r.value;
+      hasHole ||= r.hasHole;
+    }
+    return { state: "ok", value: out, hasHole };
+  }
+
+  return { state: "ok", value, hasHole: false };
+}
+
+/**
+ * Overlay a recorded (elided) container onto the fresh run's container for a
+ * shell HIT. Recorded wins per path; hole markers take the fresh value (the
+ * live nested promise); fresh-only object keys pass through. Where the shapes
+ * disagree structurally, recorded wins wholesale — it is what the prelude
+ * froze, and parity beats freshness inside the shell.
+ */
+export function overlayLoaderContainer(
+  fresh: unknown,
+  recorded: unknown,
+): unknown {
+  if (isLoaderHoleMarker(recorded)) return fresh;
+
+  if (isLoaderSettledMarker(recorded)) {
+    const pinned = recorded.value;
+    // Deep holes inside a settled container (capture-computed `holes` bit)
+    // need the fresh promise's resolved value to fill them; a fully-pinned
+    // container resolves immediately (the prelude already shows it — never
+    // gate it on fresh latency). A rejecting fresh run degrades holes to
+    // undefined instead of poisoning the pin.
+    if (recorded.holes === 1) {
+      return Promise.resolve(fresh).then(
+        (freshValue) => overlayLoaderContainer(freshValue, pinned),
+        () => overlayLoaderContainer(undefined, pinned),
+      );
+    }
+    return Promise.resolve(overlayLoaderContainer(undefined, pinned));
+  }
+
+  if (Array.isArray(recorded)) {
+    const freshArr = Array.isArray(fresh) ? fresh : [];
+    return recorded.map((item, i) => overlayLoaderContainer(freshArr[i], item));
+  }
+
+  if (isPlainObject(recorded)) {
+    if (!isPlainObject(fresh)) {
+      // Shape drift: still honor markers (holes fall back to undefined).
+      const out: Record<string, unknown> = {};
+      for (const key of Object.keys(recorded)) {
+        out[key] = overlayLoaderContainer(undefined, recorded[key]);
+      }
+      return out;
+    }
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(recorded)) {
+      out[key] = overlayLoaderContainer(fresh[key], recorded[key]);
+    }
+    for (const key of Object.keys(fresh)) {
+      if (!(key in out)) out[key] = fresh[key];
+    }
+    return out;
+  }
+
+  return recorded;
+}

package/src/router/segment-resolution/mask-nested.ts

@@ -0,0 +1,83 @@
+/**
+ * Capture-side nested-thenable masking — the mechanism behind "nested-promise
+ * shape is the liveness declaration" for BOTH bake-lane loader containers
+ * (loader-cache.ts) and pushed handle containers (request-context.ts
+ * createUseFunction).
+ *
+ * Deliberately a LEAF module: request-context needs the mask for handle
+ * pushes, and loader-mask (the other natural home) imports request-context —
+ * importing from there would cycle. This module imports only is-thenable.
+ */
+
+import { isThenable } from "../../handles/is-thenable.js";
+
+/**
+ * A promise that never settles — the masked stand-in for a per-request value
+ * during shell capture. The consuming Suspense subtree suspends forever, so
+ * the static prerender postpones it as a hole instead of baking a per-request
+ * value into the shared shell. The capture abort (`maxWaitMs` in
+ * captureShellHTML) bounds how long the prerender waits before it freezes the
+ * prelude, so this never hangs the request.
+ */
+export function createMaskedLoaderPromise<T = unknown>(): Promise<T> {
+  return new Promise<T>(() => {});
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep-copy a container with every NESTED thenable replaced by a masked
+ * (never-resolving) promise. Applied during shell capture to (a) bake-lane
+ * loader containers (loader-cache.ts) and (b) pushed handle containers
+ * (createUseFunction) — the two rango-owned funnels where consumers declare
+ * per-request data by promise SHAPE.
+ *
+ * Why: a nested promise that happened to SETTLE before the capture's quiet
+ * window closed used to bake its value into the SHARED shell (and, for
+ * loaders, the snapshot pinned it for every HIT) — per-request data frozen
+ * and served cross-session (found live: a storefront basket, carrying the
+ * capturing session's basketId/customer identifiers, served to anonymous
+ * visitors). The window waits for the slowest shared material on the page, so
+ * any real data source (a 5ms SQL read, a 200ms basket API) lost the race.
+ * Masking makes the consuming subtree postpone as a hole no matter when the
+ * promise settles: liveness by declaration, not by racing the window.
+ *
+ * Only plain objects/arrays are traversed; other values are leaves. The INPUT
+ * IS NEVER MUTATED — handler-side loader consumption (the consumption-lane
+ * rule, semantic-matrix PPR3) shares the raw container and must keep real
+ * values. Cycles are preserved as cycles in the copy.
+ */
+export function maskNestedContainerThenables(
+  value: unknown,
+  seen: Map<object, unknown> = new Map(),
+): unknown {
+  if (isThenable(value)) return createMaskedLoaderPromise();
+
+  if (Array.isArray(value)) {
+    const cached = seen.get(value);
+    if (cached !== undefined) return cached;
+    const out: unknown[] = new Array(value.length);
+    seen.set(value, out);
+    for (let i = 0; i < value.length; i++) {
+      out[i] = maskNestedContainerThenables(value[i], seen);
+    }
+    return out;
+  }
+
+  if (isPlainObject(value)) {
+    const cached = seen.get(value);
+    if (cached !== undefined) return cached;
+    const out: Record<string, unknown> = {};
+    seen.set(value, out);
+    for (const key of Object.keys(value)) {
+      out[key] = maskNestedContainerThenables(value[key], seen);
+    }
+    return out;
+  }
+
+  return value;
+}

package/src/router/segment-resolution/revalidation.ts

@@ -660,6 +660,7 @@ export async function resolveParallelSegmentsWithRevalidation<TEnv>(
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
         deps.viewTransitionDefault,
+        parallelId,
       ),
       params,
       slot,
@@ -861,6 +862,7 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       entry.transition,
       deps.viewTransitionDefault,
+      entry.shortCode,
     ),
     params,
     belongsToRoute,
@@ -1197,6 +1199,7 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
     transition: applyViewTransitionDefault(
       orphan.transition,
       deps.viewTransitionDefault,
+      orphan.shortCode,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });

package/src/router/segment-resolution/view-transition-default.ts

@@ -8,29 +8,49 @@
  */
 
 import type { EntryData } from "../../server/context";
+import { getRequestContext } from "../../server/request-context.js";
 
 /**
- * Resolve the effective `viewTransition` for a segment's transition config.
+ * Resolve a segment's transition config: stamp the `viewTransition` default and
+ * peel off a transition({ when }) predicate.
  *
- * The per-segment value (set via the transition() DSL) always wins. When it is
- * unset, the router-level createRouter({ viewTransition }) default is stamped
- * in so the render gate reads the boundary decision off the segment — server
- * and client, via the serialized segment — without the router option being
- * threaded to the client. Only `false` is ever stamped; an unset (or "auto")
- * value is left untouched because it already means "wrap" at the gate, which
- * also avoids needless object allocation and payload growth. Used by both the
- * fresh and revalidation resolution paths.
+ * `viewTransition`: the per-segment value (set via the transition() DSL) always
+ * wins. When it is unset, the router-level createRouter({ viewTransition })
+ * default is stamped in so the render gate reads the boundary decision off the
+ * segment — server and client, via the serialized segment — without the router
+ * option being threaded to the client. Only `false` is ever stamped; an unset
+ * (or "auto") value is left untouched because it already means "wrap" at the
+ * gate, which also avoids needless object allocation and payload growth.
+ *
+ * `when`: a server-only predicate. It is STRIPPED from the returned config (a
+ * function cannot cross Flight or the segment cache) and recorded on the request
+ * context keyed by `segmentId`, so rsc-rendering can evaluate it post-handler —
+ * outside any cache scope — and drop this segment's transition when it returns
+ * false. Used by both the fresh and revalidation resolution paths.
  */
 export function applyViewTransitionDefault(
   transition: EntryData["transition"],
   viewTransitionDefault: "auto" | false | undefined,
+  segmentId?: string,
 ): EntryData["transition"] {
   if (!transition) return transition;
-  if (
-    transition.viewTransition === undefined &&
-    viewTransitionDefault === false
-  ) {
-    return { ...transition, viewTransition: false };
+  let result = transition;
+  if (result.when) {
+    if (segmentId !== undefined) {
+      try {
+        const ctx = getRequestContext();
+        (ctx._transitionWhen ??= []).push({ id: segmentId, when: result.when });
+      } catch {
+        // No active request context (e.g. a unit test calling this util
+        // directly). Skip collection; the strip below still applies so the
+        // serialized config never carries the function.
+      }
+    }
+    const { when: _when, ...rest } = result;
+    result = rest;
+  }
+  if (result.viewTransition === undefined && viewTransitionDefault === false) {
+    return { ...result, viewTransition: false };
   }
-  return transition;
+  return result;
 }

package/src/router/substitute-pattern-params.ts

@@ -1,12 +1,23 @@
-import { encodePathSegment } from "./url-params.js";
+import { encodePathSegment, encodePathRemainder } from "./url-params.js";
+import { parsePattern } from "./parse-pattern.js";
 
 /**
  * Substitute `:param` placeholders in a route pattern with values from
- * `params`. Two-pass: optional params (`:name?`) first so absent values
- * collapse cleanly, then required params (throws on missing). Constraint
- * syntax (`:name(en|gb)`) is stripped from the result. Trailing-slash
- * patterns like `/blog/` are preserved unless an optional segment was
- * actually omitted.
+ * `params`, producing a URL. Built by walking the SAME parsed segments the
+ * matcher uses (`parsePattern`) and emitting one piece per segment — so a
+ * substituted value is never re-scanned as if it were another placeholder (a
+ * catch-all value like `sha:abc/x` used to make the "required" pass read `:abc`
+ * and throw). Constraint syntax (`:name(en|gb)`) is stripped; trailing-slash
+ * patterns like `/blog/` are preserved unless an optional segment was omitted.
+ *
+ * Semantics per segment:
+ * - static             -> emitted verbatim.
+ * - `:name`            -> required; `undefined` throws, `""` yields an empty segment.
+ * - `:name?`           -> optional; `undefined`/`""` omitted.
+ * - `:name*` / `:name+`-> catch-all; the value is multi-segment, so each segment
+ *                         is encoded and the `/` separators are preserved. `+`
+ *                         (one-or-more) throws when absent; `*` (and bare `*`)
+ *                         omit when absent.
  *
  * Shared by `ctx.reverse()` (server), `createReverse()` (typed runtime
  * helper), and `useReverse()` (client hook). The behavior must stay
@@ -17,40 +28,48 @@ export function substitutePatternParams(
   params: Record<string, string | undefined>,
   routeName: string,
 ): string {
-  let result = pattern;
-  let hadOmittedOptional = false;
+  const hasTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
+  const normalized = hasTrailingSlash ? pattern.slice(0, -1) : pattern;
+  const segments = parsePattern(normalized);
 
-  result = result.replace(
-    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(\?)/g,
-    (_match, key) => {
-      const value = params[key as string];
-      // The matcher omits absent optional params (so `value` is `undefined`
-      // here), but caller-supplied params or `getParams()` shapes may still
-      // pass `""` explicitly. Treat both as the absent form.
+  const parts: string[] = [];
+  for (const seg of segments) {
+    if (seg.type === "static") {
+      parts.push("/" + seg.value);
+    } else if (seg.type === "wildcard") {
+      const value = params[seg.value];
       if (value === undefined || value === "") {
-        hadOmittedOptional = true;
-        return "";
+        // `:name+` requires at least one segment; bare `*` / `:name*` collapse.
+        if (seg.oneOrMore) {
+          throw new Error(
+            `Missing param "${seg.value}" for route "${routeName}"`,
+          );
+        }
+      } else {
+        parts.push("/" + encodePathRemainder(value));
       }
-      return encodePathSegment(value);
-    },
-  );
-
-  result = result.replace(
-    /:([a-zA-Z_][a-zA-Z0-9_]*)(\([^)]*\))?(?!\?)/g,
-    (_match, key) => {
-      const value = params[key as string];
-      if (value === undefined) {
-        throw new Error(`Missing param "${key}" for route "${routeName}"`);
+    } else {
+      // Plain param. Constraint (`seg.constraint`) is intentionally not re-emitted.
+      const value = params[seg.value];
+      const suffix = seg.suffix ?? "";
+      if (seg.optional) {
+        // The matcher omits absent optionals (`undefined`); callers/getParams()
+        // may pass `""` explicitly — treat both as absent.
+        if (value !== undefined && value !== "") {
+          parts.push("/" + encodePathSegment(value) + suffix);
+        }
+      } else {
+        if (value === undefined) {
+          throw new Error(
+            `Missing param "${seg.value}" for route "${routeName}"`,
+          );
+        }
+        parts.push("/" + encodePathSegment(value) + suffix);
       }
-      return encodePathSegment(value);
-    },
-  );
-
-  if (hadOmittedOptional) {
-    const hadTrailingSlash = pattern.length > 1 && pattern.endsWith("/");
-    result = result.replace(/\/\/+/g, "/").replace(/\/+$/, "") || "/";
-    if (hadTrailingSlash && !result.endsWith("/")) result += "/";
+    }
   }
 
+  let result = parts.join("") || "/";
+  if (hasTrailingSlash && !result.endsWith("/")) result += "/";
   return result;
 }

package/src/router/telemetry-otel.ts

@@ -41,7 +41,7 @@ import { runThenSettle } from "./tracing.js";
 import type {
   RouterTracingConfig,
   SpanRunner,
-  TracePhaseToggles,
+  TracingToggleOptions,
 } from "./tracing.js";
 
 // ---------------------------------------------------------------------------
@@ -92,13 +92,11 @@ const STATUS_ERROR = 2;
 // Tracing adapter: phase spans via startActiveSpan (the `tracing` slot)
 // ---------------------------------------------------------------------------
 
-/** Options for createOTelTracing. */
-export interface OTelTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
-}
+/**
+ * Options for createOTelTracing. Alias of the shared {@link TracingToggleOptions}
+ * (`enabled` master switch + per-phase `spans` toggles); the name is public API.
+ */
+export type OTelTracingOptions = TracingToggleOptions;
 
 /**
  * Create the tracing config that maps the router's phases onto OTel spans via

package/src/router/telemetry.ts

@@ -38,6 +38,14 @@ export interface RequestEndEvent extends BaseEvent {
   durationMs: number;
   segmentCount: number;
   cacheHit: boolean;
+  /**
+   * HTTP status when a Response ended the transaction — a thrown-Response
+   * short-circuit (redirect / auth gate carries the Response's status, e.g. 302),
+   * or dispatch()'s final response status. Absent for a normal render completion:
+   * the Response is built after match(), so match()/matchPartial() have no status
+   * to stamp there. Lets a sink split 3xx short-circuits from 2xx completions.
+   */
+  status?: number;
 }
 
 export interface RequestErrorEvent extends BaseEvent {
@@ -320,7 +328,7 @@ export function createConsoleSink(): TelemetrySink {
           break;
         case "request.end":
           console.log(
-            `[telemetry] ${event.type} ${event.method} ${event.pathname} ${event.durationMs.toFixed(1)}ms segments=${event.segmentCount} cache=${event.cacheHit}`,
+            `[telemetry] ${event.type} ${event.method} ${event.pathname} ${event.durationMs.toFixed(1)}ms segments=${event.segmentCount} cache=${event.cacheHit}${event.status !== undefined ? ` status=${event.status}` : ""}`,
           );
           break;
         case "request.error":

package/src/router/tracing.ts

@@ -81,17 +81,26 @@ export interface TracePhaseToggles {
   ssr?: boolean;
 }
 
+/**
+ * The option pair shared by every tracing factory (enabled master switch +
+ * per-phase span toggles). Extended by OTelTracingOptions,
+ * CloudflareTracingOptions, VercelTracingOptions, and RouterTracingConfig so
+ * a phase added to TracePhaseToggles propagates everywhere from one place.
+ */
+export interface TracingToggleOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+}
+
 /**
  * Value passed to `createRouter({ tracing })`. Produced by a platform factory
  * such as `createCloudflareTracing()`.
  */
-export interface RouterTracingConfig {
+export interface RouterTracingConfig extends TracingToggleOptions {
   /** Platform span runner. */
   runner: SpanRunner;
-  /** Master switch. Defaults to true when a config object is provided. */
-  enabled?: boolean;
-  /** Per-phase span toggles. */
-  spans?: TracePhaseToggles;
 }
 
 /**