@rangojs/router 0.4.2 → 0.5.0

package/src/rsc/shell-capture.ts

@@ -22,11 +22,14 @@ import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
 import {
   CaptureQueueFullError,
+  CaptureQueueWaitTimeoutError,
+  captureQueueDepths,
   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,
@@ -395,6 +398,43 @@ function warnSnapshotOverCapOnce(
   );
 }
 
+/**
+ * Dev warning threshold (ms) for the slowest bake-source settlement wait. Bake
+ * time is by-design shell latency (top-level pushed handle promises and
+ * bake-lane loader containers settle before the freeze), but it recurs on
+ * EVERY capture of the route and occupies the per-isolate serialized capture
+ * queue — silently: the served response's own timing never shows it (a route
+ * can read 13ms TTFB while each of its captures holds the queue for seconds).
+ * Past this threshold the source gets named once per key with the remedy
+ * ladder.
+ */
+const SHELL_CAPTURE_BAKE_WARN_MS = 2_000;
+
+/** Keys already warned about an expensive bake source (once per key). */
+const warnedBakeCosts = new Set<string>();
+
+/**
+ * Dev-only, once per key: name the slowest bake source and the three remedies
+ * in preference order. The doctrine ("nesting = liveness") makes the cost
+ * legitimate, so this is a cost report with an exit, not a deprecation.
+ */
+function warnBakeCostOnce(key: string, source: string, ms: number): void {
+  if (warnedBakeCosts.has(key)) return;
+  warnedBakeCosts.add(key);
+  console.warn(
+    `[rango] Shell capture for "${key}" waited ${ms}ms for ${source} to ` +
+      "settle before the shell could freeze. This cost recurs on every capture " +
+      "of the route and occupies the per-isolate capture queue; the served " +
+      "response never shows it. Top-level promises BAKE by design (the " +
+      "container settles; nested promises stay live). To make the value " +
+      "per-request instead, nest it ({ data: promise }) and read it with use() " +
+      "under Suspense; to keep it baked but cheap, wrap the work in cache() " +
+      "(the capture replays the cached value); for a segment loader, add a " +
+      "loading() boundary to its entry (live lane, masked at capture). See the " +
+      "/ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md).",
+  );
+}
+
 /**
  * One structured event from the background capture pipeline, mirroring the
  * CFCacheReadDebugEvent pattern (cache/cf/cf-cache-types.ts): typed fields an
@@ -416,6 +456,14 @@ 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-inert-store: the resolved store's shell family is missing or
+   *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
+   *   without a KV namespace); nothing could store the result, so the
+   *   background render was not scheduled at all
+   * - 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 +476,8 @@ export interface ShellCaptureDebugEvent {
     | "skip-in-flight"
     | "skip-backoff"
     | "skip-capacity"
+    | "skip-inert-store"
+    | "skip-queue-timeout"
     | "backoff";
   /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
   attempt?: number;
@@ -457,6 +507,24 @@ 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;
+  /** Queue priority class at enqueue: document outranks queued navigation. */
+  queuePriority?: "document" | "navigation";
+  /**
+   * Captures ahead at enqueue: the active one plus every waiting capture of
+   * same-or-higher priority. 0 = this capture starts immediately.
+   */
+  queueAhead?: number;
+  /**
+   * Ms the capture gate was HELD waiting for the slowest bake source — a
+   * top-level pushed handle promise or a bake-lane loader container — to
+   * settle, measured from capture start. Bake time is by-design shell latency
+   * (the hole doctrine: top-level promises bake), but it recurs on EVERY
+   * capture of the route and occupies the serialized queue; this field makes
+   * it attributable. Absent when nothing held the gate.
+   */
+  bakeWaitMs?: number;
 }
 
 /**
@@ -503,6 +571,18 @@ 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`);
+  }
+  if (event.queuePriority !== undefined) {
+    parts.push(`queue-priority=${event.queuePriority}`);
+  }
+  if (event.queueAhead !== undefined) {
+    parts.push(`queue-ahead=${event.queueAhead}`);
+  }
+  if (event.bakeWaitMs !== undefined) {
+    parts.push(`bake=${event.bakeWaitMs}ms`);
+  }
   return parts.join(" ");
 }
 
@@ -852,8 +932,18 @@ export function scheduleShellCapture(
     });
     return;
   }
+  // A capture whose write can only no-op is dead work that still occupies the
+  // serialized queue (a promise-heavy route bakes for seconds per MISS),
+  // starving captures that CAN store. Skip scheduling entirely when the
+  // resolved store (same defaulting as captureAndStoreShell) has no shell
+  // family or declared it inert (CFCacheStore without a KV namespace).
+  const scheduledStore = descriptor.store ?? reqCtx._cacheStore;
+  if (!scheduledStore?.putShell || scheduledStore.shellFamilyInert) {
+    publishCaptureDebugEvent(descriptor, { key, outcome: "skip-inert-store" });
+    return;
+  }
   inFlightCaptures.add(key);
-  const captureTask = async () => {
+  const captureTask = async (span: TraceSpan) => {
     try {
       const setupUrl = descriptor.navigationOnly
         ? stripInternalParams(url)
@@ -881,6 +971,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 +990,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 +1006,79 @@ 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",
-        });
-        return;
+    await observePhase(PHASES.background("shell-capture"), async (span) => {
+      span.setAttribute("rango.shell_key", key);
+      // A production page can enqueue several navigation-only captures through
+      // viewport prefetching. Let a later document MISS overtake that queued
+      // speculative work so it can become a shell HIT before the 15s queue
+      // budget expires. Never preempts the active capture. Priority and the
+      // backlog ahead at enqueue ride the span (and the skip event below), so
+      // a skip-queue-timeout diagnoses itself instead of needing a trace dive.
+      const queuePriority = descriptor.navigationOnly
+        ? ("navigation" as const)
+        : ("document" as const);
+      const depths = captureQueueDepths();
+      const queueAhead =
+        (depths.running ? 1 : 0) +
+        depths.document +
+        (queuePriority === "navigation" ? depths.navigation : 0);
+      span.setAttribute("rango.background.queue_priority", queuePriority);
+      span.setAttribute("rango.background.queue_ahead", queueAhead);
+      const queueStart = performance.now();
+      try {
+        await enqueueSerializedCapture(
+          () => {
+            span.setAttribute(
+              "rango.background.queue_wait_ms",
+              Math.round(performance.now() - queueStart),
+            );
+            return captureTask(span);
+          },
+          { priority: queuePriority },
+        );
+      } 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),
+            queuePriority,
+            queueAhead,
+          });
+          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),
@@ -983,6 +1134,7 @@ type CaptureAttemptStats = Pick<
   | "snapshotSkipped"
   | "untaggedBake"
   | "storeWrite"
+  | "bakeWaitMs"
 >;
 
 /**
@@ -1459,6 +1611,29 @@ async function captureAndStoreShell(
     loaderRecordsForHold && loaderRecordsForHold.size > 0
       ? Promise.allSettled([handlesBaked, ...loaderRecordsForHold.values()])
       : handlesBaked;
+  // Bake-cost attribution: record how long each bake source held the gate,
+  // measured from capture start. Side-channel observers only — holdUntil and
+  // its consumers are untouched, and a rejected source is recorded the same
+  // (allSettled swallows it; the drain below owns the refusal). Folded into
+  // stats.bakeWaitMs (+ a once-per-key dev warning) after a successful
+  // capture; on a refusal the other warnings own the story.
+  const bakeStart = performance.now();
+  const bakeWaits: { source: string; ms: number }[] = [];
+  const observeBake = (source: string, promise: Promise<unknown>): void => {
+    const record = (): void => {
+      bakeWaits.push({
+        source,
+        ms: Math.round(performance.now() - bakeStart),
+      });
+    };
+    promise.then(record, record);
+  };
+  observeBake("top-level pushed handle promises", handlesBaked);
+  if (loaderRecordsForHold) {
+    for (const [loaderId, promise] of loaderRecordsForHold) {
+      observeBake(`bake-lane segment loader "${loaderId}"`, promise);
+    }
+  }
   const gate = gateFlightForCapture(rscStream, undefined, holdUntil);
   // Quiesce = handles settled AND the Flight shell rows went task-quiet. Either
   // half stalling is bounded by captureShellHTML's maxWaitMs.
@@ -1538,6 +1713,23 @@ async function captureAndStoreShell(
     }
     if (stats) stats.preludeBytes = result.prelude.length;
 
+    // Every bake source has settled by here (quiesce gates on holdUntil).
+    // Surface the slowest one: sub-ms settles are noise, threshold-crossers
+    // get the dev warning with the remedy ladder.
+    let slowestBake: { source: string; ms: number } | undefined;
+    for (const wait of bakeWaits) {
+      if (!slowestBake || wait.ms > slowestBake.ms) slowestBake = wait;
+    }
+    if (slowestBake && slowestBake.ms > 0) {
+      if (stats) stats.bakeWaitMs = slowestBake.ms;
+      if (
+        process.env.NODE_ENV !== "production" &&
+        slowestBake.ms >= SHELL_CAPTURE_BAKE_WARN_MS
+      ) {
+        warnBakeCostOnce(capture.key, slowestBake.source, slowestBake.ms);
+      }
+    }
+
     // Store per the flag's key/ttl/swr/tags, into the flag's store: the middleware
     // threads the SAME store it resolved for its getShell read (options.store ??
     // _cacheStore), so a store-attached middleware writes captures where it reads
@@ -1694,11 +1886,23 @@ async function captureAndStoreShell(
     if (store?.putShell) {
       try {
         const entry: ShellCacheEntry = {
-          // slice() copies just this view's bytes into a fresh ArrayBuffer, so a
-          // prelude that is a subarray of a larger backing buffer encodes only its
-          // own region — bufferToBase64 reads the whole ArrayBuffer it is handed.
-          prelude: bufferToBase64(result.prelude.slice().buffer as ArrayBuffer),
-          postponed: result.postponed,
+          // Document half only for document captures. A navigationOnly entry's
+          // HTML is never served (document reads skip the flag; partial replay
+          // consumes only snapshot/docKey), so storing it would ride every KV
+          // write/read as dead weight — the prerender still ran above as the
+          // completeness arbiter and sanity gate, its output is dropped here.
+          ...(capture.navigationOnly
+            ? {}
+            : {
+                // slice() copies just this view's bytes into a fresh
+                // ArrayBuffer, so a prelude that is a subarray of a larger
+                // backing buffer encodes only its own region — bufferToBase64
+                // reads the whole ArrayBuffer it is handed.
+                prelude: bufferToBase64(
+                  result.prelude.slice().buffer as ArrayBuffer,
+                ),
+                postponed: result.postponed,
+              }),
           reactVersion: React.version,
           buildVersion: capture.buildVersion,
           // The theme this capture's payload was built with (buildFullPayload

package/src/rsc/shell-serve.ts

@@ -20,7 +20,11 @@ import React from "react";
 import { isPprEntry, type EntryData } from "../server/context.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
-import type { ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+import type {
+  DocumentShellCacheEntry,
+  ShellCacheEntry,
+  SegmentCacheStore,
+} from "../cache/types.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
 
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
@@ -150,18 +154,29 @@ export function isValidShellHit(
 }
 
 /**
- * Payload integrity gate, run BEFORE the HIT response commits: a stored entry
- * whose prelude is not decodable base64 or whose postponed blob is not
- * parseable JSON would otherwise throw AFTER the 200 + full static prelude
- * flushed (`serveShellHit` decodes at stream construction, `resumeShellHTML`
- * parses in the tail) — the client gets a visually complete page that never
- * hydrates, re-served on every request until the entry ages out (no eviction
- * path exists; failure schedules no recapture by itself). Checking here turns
- * a corrupt entry (store-layer fault) into a plain MISS the recapture
- * overwrites. Cost: one duplicate decode/parse per HIT, sub-ms against a
- * prelude flush that dominates the path.
+ * DOCUMENT-half integrity gate and type narrowing, run BEFORE the HIT response
+ * commits: a stored entry whose prelude is not decodable base64 or whose
+ * postponed blob is not parseable JSON would otherwise throw AFTER the 200 +
+ * full static prelude flushed (`serveShellHit` decodes at stream construction,
+ * `resumeShellHTML` parses in the tail) — the client gets a visually complete
+ * page that never hydrates, re-served on every request until the entry ages
+ * out (no eviction path exists; failure schedules no recapture by itself).
+ * Checking here turns a corrupt entry (store-layer fault) into a plain MISS
+ * the recapture overwrites. Cost: one duplicate decode/parse per HIT, sub-ms
+ * against a prelude flush that dominates the path.
+ *
+ * navigationOnly entries store no document half (prelude/postponed absent) and
+ * therefore never pass. The partial-replay path skips this gate for them
+ * (replayableShellSnapshot) — snapshot fragment corruption is caught by the
+ * consumer-side Flight decoders instead (SegmentFragmentDecodeError → healing
+ * capture).
  */
-export function hasIntactShellPayload(entry: ShellCacheEntry): boolean {
+export function hasIntactShellPayload(
+  entry: ShellCacheEntry,
+): entry is DocumentShellCacheEntry {
+  if (typeof entry.prelude !== "string" || entry.postponed === undefined) {
+    return false;
+  }
   try {
     base64ToBytes(entry.prelude);
     if (entry.postponed !== null) JSON.parse(entry.postponed);

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/server/request-context.ts

@@ -691,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
@@ -770,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.