@rangojs/router 0.4.1 → 0.4.3

package/src/rsc/shell-capture.ts

@@ -22,11 +22,13 @@ import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
 import {
   CaptureQueueFullError,
+  CaptureQueueWaitTimeoutError,
   enqueueSerializedCapture,
 } from "./capture-queue.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import { observePhase, PHASES } from "../router/instrument.js";
+import type { TraceSpan } from "../router/tracing.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
@@ -416,6 +418,10 @@ export interface ShellCaptureDebugEvent {
    * - skip-backoff: the key is inside its refused-capture backoff window and
    *   the capture was not attempted
    * - skip-capacity: the isolate capture queue is full; a later request may retry
+   * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
+   *   behind other captures and was dropped unrun (no backoff — the route is
+   *   not doomed, the isolate was busy; a later request re-probes). Carries
+   *   queueWaitMs.
    * - backoff: the key entered (or escalated) backoff after a terminal
    *   no-shell — carries the new backoff state
    */
@@ -428,6 +434,7 @@ export interface ShellCaptureDebugEvent {
     | "skip-in-flight"
     | "skip-backoff"
     | "skip-capacity"
+    | "skip-queue-timeout"
     | "backoff";
   /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
   attempt?: number;
@@ -457,6 +464,8 @@ export interface ShellCaptureDebugEvent {
   backoffFailures?: number;
   /** Ms remaining in the key's backoff window, when one exists. */
   backoffRemainingMs?: number;
+  /** Ms the capture waited in the serialized queue (skip-queue-timeout). */
+  queueWaitMs?: number;
 }
 
 /**
@@ -503,6 +512,9 @@ export function describeShellCaptureEvent(
   if (event.backoffRemainingMs !== undefined) {
     parts.push(`backoff-remaining=${event.backoffRemainingMs}ms`);
   }
+  if (event.queueWaitMs !== undefined) {
+    parts.push(`queue-wait=${event.queueWaitMs}ms`);
+  }
   return parts.join(" ");
 }
 
@@ -853,7 +865,7 @@ export function scheduleShellCapture(
     return;
   }
   inFlightCaptures.add(key);
-  const captureTask = async () => {
+  const captureTask = async (span: TraceSpan) => {
     try {
       const setupUrl = descriptor.navigationOnly
         ? stripInternalParams(url)
@@ -881,6 +893,7 @@ export function scheduleShellCapture(
         resolvedSsrModule,
         descriptor,
       );
+      span.setAttribute("rango.background.outcome", outcome);
       // Update the negative cache off the terminal outcome. A stored shell clears
       // any prior backoff; a `no-shell` (after the in-place retry) backs the key
       // off so the next requests don't re-probe it. A `redirect` has no shell but
@@ -899,6 +912,7 @@ export function scheduleShellCapture(
       // context is gone. A genuine failure recurs, so back it off too (re-probe
       // once per window, not every request) and report it once.
       markCaptureBackoff(key);
+      span.setAttribute("rango.background.outcome", "error");
       publishCaptureDebugEvent(descriptor, {
         key,
         outcome: "error",
@@ -914,20 +928,58 @@ export function scheduleShellCapture(
   // capture makes the sibling freeze a trivial prelude and store nothing
   // (rotating eternal-MISS victims on GH runners). The stampede guard above
   // stays per-key (dedupe while queued); the queue is cross-key.
+  //
+  // The whole serialized task — queue wait INCLUDED — is wrapped in the
+  // rango.background span (kind=shell-capture). The span is the explanatory
+  // parent for the capture's platform KV/fetch/cache spans (the capture's own
+  // rango.* phase spans stay suppressed — deriveShellCaptureContext strips
+  // _tracing), and queue_wait_ms makes a capture parked behind a slow
+  // predecessor link visible instead of reading as an unexplained dead gap
+  // (observed in production: ~24s of zero I/O before capture start).
+  // observePhase reads tracing off the ALS context captured when runBackground
+  // registered the task — the foreground request context, tracing intact.
   const serializedTask = async () => {
-    try {
-      await enqueueSerializedCapture(captureTask);
-    } catch (error) {
-      if (error instanceof CaptureQueueFullError) {
-        inFlightCaptures.delete(key);
-        publishCaptureDebugEvent(descriptor, {
-          key,
-          outcome: "skip-capacity",
+    await observePhase(PHASES.background("shell-capture"), async (span) => {
+      span.setAttribute("rango.shell_key", key);
+      const queueStart = performance.now();
+      try {
+        await enqueueSerializedCapture(() => {
+          span.setAttribute(
+            "rango.background.queue_wait_ms",
+            Math.round(performance.now() - queueStart),
+          );
+          return captureTask(span);
         });
-        return;
+      } catch (error) {
+        if (error instanceof CaptureQueueFullError) {
+          inFlightCaptures.delete(key);
+          span.setAttribute("rango.background.outcome", "skip-capacity");
+          publishCaptureDebugEvent(descriptor, {
+            key,
+            outcome: "skip-capacity",
+          });
+          return;
+        }
+        if (error instanceof CaptureQueueWaitTimeoutError) {
+          // Dropped unrun after waiting past the queue budget: no backoff (the
+          // route is not doomed, the isolate was busy) — a later request
+          // re-probes the key.
+          inFlightCaptures.delete(key);
+          span.setAttribute("rango.background.outcome", "skip-queue-timeout");
+          span.setAttribute(
+            "rango.background.queue_wait_ms",
+            Math.round(error.waitedMs),
+          );
+          publishCaptureDebugEvent(descriptor, {
+            key,
+            outcome: "skip-queue-timeout",
+            queueWaitMs: Math.round(error.waitedMs),
+          });
+          return;
+        }
+        throw error;
       }
-      throw error;
-    }
+    });
   };
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),
@@ -945,8 +997,9 @@ export function scheduleShellCapture(
  *   I/O failure is reported separately and does NOT make the attempt retryable —
  *   the capture itself worked).
  * - `redirect`: the matched route redirects, so there is no shell to capture.
- * - `no-shell`: the prelude came back trivial (no <body>) OR captureShellHTML
- *   rejected with our own abort. This is the only RETRYABLE outcome.
+ * - `no-shell`: captureShellHTML returned null because the prelude was unusable
+ *   or its private capture abort landed before the shell completed. This is the
+ *   only RETRYABLE outcome.
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
@@ -995,9 +1048,9 @@ type CaptureAttemptStats = Pick<
  * when we froze the shell; the attempt itself warmed the module graph, so a second
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
- * several HTTP requests before a capture stuck. We retry ONLY on `no-shell` (and a
- * defensively-caught abort); a genuine render error is NOT retried — it propagates
- * to scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`; a
+ * genuine render error is NOT retried — it propagates to scheduleShellCapture's
+ * reportCacheError. See docs/design/ppr-shell-resume.md.
  *
  * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
  * drive the retry without a real 400ms wall-clock wait.
@@ -1329,6 +1382,10 @@ export function deriveShellCaptureContext(
   derivedCtx._explicitTaggedStores = new Set();
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
+  // Own-property reset: an inherited flag would make serializeSegments store
+  // a double-encoded fragment. No current arming site reaches a capture
+  // render (kept as defense-in-depth for a future one).
+  derivedCtx._shellFragmentPayload = false;
   derivedCtx._metricsStore = undefined;
   // Spans, like perf metrics above, are a FOREGROUND surface: the capture
   // re-render must not emit a second rango.render/loader/ssr set after the
@@ -1395,9 +1452,10 @@ export function deriveShellCaptureContext(
  * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
  * present (eligibility is checked before scheduling).
  *
- * A `no-shell` result (trivial prelude, or a defensively-caught abort) is the only
- * retryable outcome; a genuine (non-abort) captureShellHTML error propagates so it
- * reaches reportCacheError and is NOT retried.
+ * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
+ * captureShellHTML error propagates to reportCacheError and is NOT retried. The
+ * capture handler converts only its own private abort sentinel to null before this
+ * layer sees it.
  */
 async function captureAndStoreShell(
   ssrModule: SSRModule,
@@ -1504,19 +1562,13 @@ async function captureAndStoreShell(
         }),
       );
     } catch (error) {
-      // Guard-tripped rejection arrives here (not at the drain) — refuse
-      // BEFORE the AbortError-vs-rethrow decision below.
+      // Guard-tripped rejection arrives here (not at the drain), so refuse it
+      // before propagating other capture errors.
       const refused = refuseOnGuardTrip();
       if (refused) return refused;
-      // captureShellHTML normally converts its OWN deliberate abort to a null
-      // return (index.tsx). This catch is defensive: if an AbortError still escapes
-      // (a runtime where the abort surfaces as a stream rejection outside its
-      // guard), treat it as the same retryable "no usable shell" degradation rather
-      // than a failure — do NOT report it as an error. A genuine (non-abort) render
-      // error is a real failure: rethrow so it reaches reportCacheError (no retry).
-      if ((error as { name?: string } | null)?.name === "AbortError") {
-        return "no-shell";
-      }
+      // captureShellHTML converts its OWN deliberate abort to null by sentinel
+      // identity. An escaped AbortError can therefore be a component's real
+      // cancellation and must not be hidden or retried by name.
       throw error;
     }
 

package/src/rsc/stream-idle.ts

@@ -0,0 +1,137 @@
+/**
+ * Stream-idle timeout — the enforcement for `timeouts.streamIdleMs` (the
+ * "stream-idle" TimeoutPhase, reserved since the timeout API landed).
+ *
+ * WHY: nothing else bounds a streaming response body's lifetime.
+ * `renderStartMs` only bounds time-to-Response-construction; once the body is
+ * streaming, a single never-settling promise embedded in the payload (a
+ * deferred loader that never resolves, an orphaned ctx.rendered() barrier)
+ * holds the Flight/HTML stream — and the client's connection — open forever.
+ * Deferred HANDLES have a 10s auto-resolve net (defer.ts); loader promises
+ * and everything else have none. Field-observed as multi-second dead
+ * connections only closed by client cancellation.
+ *
+ * SEMANTICS — end-to-end idle flow, deliberately: the watchdog re-arms on
+ * every chunk that flows THROUGH to the client, so "idle" means "no bytes
+ * reached the wire for N ms". A stalled slow client counts as idle the same
+ * as a wedged producer — the two are indistinguishable here without buffering,
+ * and buffering is banned on the streaming path. Pick budgets accordingly
+ * (generous, seconds not millis); the feature is OPT-IN (unset = today's
+ * unbounded behavior, and the `timeout` shorthand deliberately does not apply
+ * to streamIdleMs — see resolveTimeouts).
+ *
+ * ON TRIP: the client-facing stream is errored with a RouterTimeoutError
+ * ("stream-idle") — the host terminates the response visibly (truncated
+ * chunked encoding), which is debuggable, unlike a silent clean close that
+ * would present a half-document as complete. Erroring the transform makes the
+ * pipe cancel its SOURCE, which aborts React's fizz/flight render — but only
+ * when the watchdog's branch is the sole consumer. When an upstream layer
+ * teed or cloned the body first (the document-cache MISS drain,
+ * response-cache clones), the watchdog holds one tee branch: tee semantics
+ * cancel the underlying source only once EVERY branch cancels, so the cache
+ * branch keeps the wedged render alive, bounded only by the platform's
+ * waitUntil budget — exactly as it was before this feature. The client-facing
+ * bound is unconditional; source teardown is best-effort. `onTimeout` does
+ * NOT apply: the response already left the handler, so no replacement
+ * Response can be served — the trip is reported via onError + the
+ * request.timeout telemetry event instead.
+ *
+ * COST: one identity TransformStream hop per chunk, only when the timeout is
+ * enabled. Never buffers, never reads ahead, adds no work when disabled.
+ */
+
+import { RouterTimeoutError } from "../router/timeout.js";
+
+/** What the watchdog observed when it tripped. */
+export interface StreamIdleTrip {
+  /** ms since the watchdog armed (response handoff) — the stream's lifetime. */
+  totalMs: number;
+  /** Chunks forwarded before the trip. */
+  chunks: number;
+  /** The error the client-facing stream was terminated with. */
+  error: RouterTimeoutError;
+}
+
+/**
+ * Wrap `response`'s body in an idle watchdog. Returns a NEW Response with the
+ * same status/headers whose body errors (and cancels the source) once no chunk
+ * has flowed for `idleMs`. Callers gate on isTimeoutEnabled + body presence +
+ * NOT a websocket upgrade (a 101/webSocket response must never be
+ * reconstructed); this function assumes those checks were made. `onTrip` fires
+ * at most once, after the client-facing stream has been errored.
+ */
+export function applyStreamIdleTimeout(
+  response: Response,
+  idleMs: number,
+  onTrip: (trip: StreamIdleTrip) => void,
+): Response {
+  const source = response.body;
+  if (!source) return response;
+
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let chunks = 0;
+  let settled = false;
+  let controllerRef!: TransformStreamDefaultController<unknown>;
+
+  const disarm = () => {
+    settled = true;
+    if (timer) clearTimeout(timer);
+  };
+
+  const trip = () => {
+    if (settled) return;
+    const error = new RouterTimeoutError(
+      "stream-idle",
+      performance.now() - start,
+    );
+    try {
+      controllerRef.error(error);
+    } catch {
+      // The stream already terminated (raced a close/cancel) — nothing was
+      // interrupted, so do not report a timeout.
+      return;
+    }
+    // Erroring the transform makes the pipe abort and CANCEL the source
+    // stream (React aborts the wedged render). Mark settled AFTER the error
+    // took, then report.
+    disarm();
+    onTrip({ totalMs: error.durationMs, chunks, error });
+  };
+
+  const arm = () => {
+    if (settled) return;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(trip, idleMs);
+    (timer as { unref?: () => void }).unref?.();
+  };
+
+  // `cancel` is the spec's newer transformer hook (client-side cancellation);
+  // TS's lib.dom Transformer type lags it, hence the intersection. Runtimes
+  // without it fall back to the settled/try-catch guards in trip().
+  const transformer: Transformer<unknown, unknown> & { cancel?: () => void } = {
+    start(controller) {
+      controllerRef = controller;
+      arm();
+    },
+    transform(chunk, controller) {
+      controller.enqueue(chunk);
+      chunks++;
+      arm();
+    },
+    flush() {
+      // Natural end of the source stream.
+      disarm();
+    },
+    cancel() {
+      disarm();
+    },
+  };
+  const watchdog = new TransformStream<unknown, unknown>(transformer);
+
+  return new Response(source.pipeThrough(watchdog) as ReadableStream, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}

package/src/segment-fragments.ts

@@ -6,10 +6,11 @@
  * fragment STRINGS ride the outgoing payload verbatim inside these envelopes
  * — the outer Flight render copies a string instead of re-serializing a whole
  * element tree — and the CONSUMER expands each envelope through its own Flight
- * deserializer: the SSR resume pass (ssr/ssr-root.tsx) and browser hydration
- * (browser/rsc-router.tsx). Each fragment is its own row space, decoded
- * independently, exactly like the segment codec's per-record decode — so
- * there is no Flight row-id collision or shared-row dedupe hazard.
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx), browser hydration, and
+ * capability-gated partial navigation/prefetch decoders. Each fragment is its
+ * own row space, decoded independently, exactly like the segment codec's
+ * per-record decode — so there is no Flight row-id collision or shared-row
+ * dedupe hazard.
  *
  * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
  * loading). A plain object is never a valid ReactNode, so the marker cannot
@@ -22,6 +23,25 @@
 
 import type { ResolvedSegment } from "./types.js";
 
+/** Partial-request capability gate for browser-side fragment expansion. */
+export const SEGMENT_FRAGMENT_CAPABILITY_HEADER: string =
+  "X-Rango-Fragment-Passthrough";
+
+/** One-shot request marker that forces server-side fragment validation. */
+export const SEGMENT_FRAGMENT_RECOVERY_HEADER: string =
+  "X-Rango-Fragment-Recovery";
+
+/** A stored fragment failed in its consumer-side Flight decoder. */
+export class SegmentFragmentDecodeError extends Error {
+  readonly cause: unknown;
+
+  constructor(cause: unknown) {
+    super("Failed to decode a stored RSC segment fragment");
+    this.name = "SegmentFragmentDecodeError";
+    this.cause = cause;
+  }
+}
+
 /**
  * One RSC-encoded fragment traveling inside an RscPayload segment field.
  * `f` is the stored Flight document (segment-codec output) for that field.
@@ -107,6 +127,27 @@ export async function expandSegmentFragments(
   if (decodes.length > 0) await Promise.all(decodes);
 }
 
+/**
+ * Expand every envelope in an RscPayload-shaped object, in place. Decode
+ * failures use a distinct error so partial navigation can retry once through
+ * the server's decode-and-evict path. The
+ * hasSegmentFragments pre-scan keeps envelope-free payloads — every
+ * non-replay response — to one synchronous field walk; this runs on every
+ * navigation and prefetch decode.
+ */
+export async function expandPayloadFragments(
+  payload: { metadata?: { segments?: ResolvedSegment[] } },
+  decode: FragmentDecoder,
+): Promise<void> {
+  const segments = payload.metadata?.segments;
+  if (!hasSegmentFragments(segments)) return;
+  try {
+    await expandSegmentFragments(segments, decode);
+  } catch (error) {
+    throw new SegmentFragmentDecodeError(error);
+  }
+}
+
 /**
  * True when any segment carries an unexpanded envelope. Cheap scan used by
  * consumers that only need to know whether an expansion pass is required.

package/src/server/request-context.ts

@@ -303,6 +303,12 @@ export interface RequestContext<
     keyPrefix?: "doc";
     /** @internal Called only after the implicit cache hit decodes successfully. */
     onHit?: () => void;
+    /**
+     * @internal Called when the seeded document record fails server-side
+     * deserialization. Partial replay uses it to replace the enclosing shell
+     * snapshot after serving the fresh fallback.
+     */
+    onCorrupt?: () => void;
     /**
      * @internal The resolved key of the canonical document segment record.
      * Written during a CAPTURE render by CacheScope.cacheRoute when a
@@ -334,15 +340,22 @@ export interface RequestContext<
   };
 
   /**
-   * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
-   * render emit stored segment fragments VERBATIM into the payload
+   * @internal Fragment-passthrough marker: cache/prerender-store hits during
+   * THIS render emit stored segment fragments VERBATIM into the payload
    * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
-   * per request; the payload consumers (SSR resume + browser hydration)
-   * expand them (segment-fragments.ts, issue #700). Own property of
-   * serveShellHit's derived tail context ONLY — it must never be visible to a
-   * capture render: the capture SSR-prerenders the payload AND serializes
-   * segments into records (cacheRoute), and an envelope reaching
-   * serializeSegments would store a double-encoded fragment.
+   * per request; the payload consumers (SSR resume, browser hydration, and
+   * the client partial-navigation decode chokepoints) expand them
+   * (segment-fragments.ts, issue #700). Partial requests arm only after the
+   * browser advertises `X-Rango-Fragment-Passthrough: 1`; a decode failure
+   * retries without it so CacheScope can evict the bad record. Two arming sites,
+   * both scoped to a
+   * render/match window: serveShellHit's derived tail context (document
+   * HIT), and matchPartialWithPprReplay's mutate-restore around the partial
+   * match (matchPartialForReplay). It must never be visible to a capture
+   * render: the capture SSR-prerenders the payload AND serializes segments
+   * into records (cacheRoute), and an envelope reaching serializeSegments
+   * would store a double-encoded fragment — deriveShellCaptureContext resets
+   * it as an own property for exactly that reason.
    */
   _shellFragmentPayload?: boolean;
 
@@ -678,6 +691,13 @@ export interface RequestContext<
    */
   _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
 
+  /**
+   * @internal Classified request mode from classifyRequest, read by the
+   * rango.response span tail (rsc/handler.ts) for the rango.response.mode
+   * attribute. Unset when middleware short-circuits before core execution.
+   */
+  _requestMode?: import("../router/request-classification.js").RequestPlan["mode"];
+
   /**
    * @internal Coarse route-level cache signal for the X-Rango-Cache debug
    * header. Populated by match/matchPartial only when the debug cache signal
@@ -757,6 +777,7 @@ export type PublicRequestContext<
   | "_setKeepCacheDirective"
   | "_variables"
   | "_classifiedRoute"
+  | "_requestMode"
   | "_cacheSignal"
   | "_dynamic"
   | "res"

package/src/testing/dispatch.ts

@@ -151,9 +151,11 @@ import type { TelemetrySink } from "../router/telemetry.js";
 import {
   RouterTimeoutError,
   createDefaultTimeoutResponse,
+  isTimeoutEnabled,
   withTimeout,
 } from "../router/timeout.js";
 import type { OnTimeoutCallback, ResolvedTimeouts } from "../router/timeout.js";
+import { applyStreamIdleTimeout } from "../rsc/stream-idle.js";
 
 /**
  * The internal subset of the router surface dispatch depends on. The public
@@ -854,7 +856,59 @@ export async function dispatch<TEnv = any>(
       // it leaves -- a cross-origin Location is rewritten to the basename root
       // unless redirect(url, { external: true }) opted out. Soft partial/action
       // redirects are already resolved at createSimpleRedirectResponse time.
-      return guardOutgoingRedirect(finalResponse, url.origin, router.basename);
+      const guardedResponse = guardOutgoingRedirect(
+        finalResponse,
+        url.origin,
+        router.basename,
+      );
+
+      // Mirror production's stream-idle watchdog (handler.ts response tail),
+      // same gating and reporting — dispatch is the userland dogfood surface
+      // for timeouts.streamIdleMs, so the primitive carries the real wiring,
+      // not a stub. Websocket check FIRST (an upgrade response's body getter
+      // must never be poked); onTimeout does not apply mid-stream.
+      const streamIdleMs = router.timeouts?.streamIdleMs;
+      if (
+        isTimeoutEnabled(streamIdleMs) &&
+        !isWebSocketUpgradeResponse(guardedResponse) &&
+        guardedResponse.body
+      ) {
+        return applyStreamIdleTimeout(
+          guardedResponse,
+          streamIdleMs!,
+          (trip) => {
+            invokeOnError(
+              router.onError,
+              trip.error,
+              "handler",
+              {
+                request: req,
+                url,
+                env,
+                handledByBoundary: false,
+                metadata: {
+                  timeout: true,
+                  phase: "stream-idle",
+                  durationMs: trip.totalMs,
+                },
+              },
+              "RSC",
+            );
+            if (sink) {
+              safeEmit(resolveSink(sink), {
+                type: "request.timeout",
+                timestamp: performance.now(),
+                requestId: telemetryRequestId,
+                phase: "stream-idle",
+                pathname: url.pathname,
+                durationMs: trip.totalMs,
+                customHandler: false,
+              });
+            }
+          },
+        );
+      }
+      return guardedResponse;
     } catch (error) {
       if (sink) {
         if (error instanceof Response) {

package/src/vercel/tracing.ts

@@ -1,12 +1,13 @@
 /**
  * Vercel OpenTelemetry tracing integration.
  *
- * Bridges the router's performance phases (request, middleware, action,
- * loaders, handler, render, ssr) onto OpenTelemetry spans so they show up in
- * Vercel's trace waterfall next to the platform's automatic spans, with correct
- * nesting. Vercel exposes tracing through OpenTelemetry (not a native import-free
- * API like Cloudflare), so this is a thin convenience over `createOTelTracing`:
- * it reads the global OTel tracer that `@vercel/otel`'s `registerOTel()` installs.
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto OpenTelemetry spans so they
+ * show up in Vercel's trace waterfall next to the platform's automatic spans,
+ * with correct nesting. Vercel exposes tracing through OpenTelemetry (not a
+ * native import-free API like Cloudflare), so this is a thin convenience over
+ * `createOTelTracing`: it reads the global OTel tracer that `@vercel/otel`'s
+ * `registerOTel()` installs.
  *
  * Usage (vercel preset). A Rango/Vite app does NOT auto-load `instrumentation.ts`
  * the way Next.js does, so export the tracing config from there and import it —
@@ -69,8 +70,8 @@ export interface VercelTracingOptions extends TracingToggleOptions {
 /**
  * Create the tracing config for a Vercel router. Pass the result to
  * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
- * action, loaders, handler, render, and ssr phases; pass `spans` to turn
- * individual phases off.
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
  *
  * @see createOTelTracing (`@rangojs/router`) for the underlying adapter on any
  *   platform with an OpenTelemetry SDK.