@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/src/rsc/shell-serve.ts

@@ -0,0 +1,337 @@
+/**
+ * Integrated PPR shell serving (Axis 2, see docs/design/ppr-shell-resume.md).
+ *
+ * PPR is opt-in per PAGE ROUTE via the `ppr` path option
+ * (`path(pattern, Handler, { name, ppr: true | PartialPrerenderProps })`) and the
+ * serving logic is INTEGRAL to the render pipeline — there is no middleware to
+ * mount. This module owns the config/key/store plumbing the render layer
+ * (rsc-rendering.ts) uses at its COMMIT POINT, which sits after the WHOLE
+ * middleware chain (global `router.use()` chain AND route DSL `middleware()`,
+ * both of which wrap the render pass): any middleware rejection/redirect wins
+ * before a single shell byte is written.
+ *
+ * The shell store is the app-level `createRouter({ cache })` store
+ * (`requestCtx._cacheStore`). A store without the `getShell`/`putShell` family
+ * degrades a ppr route to axis 1 with a once-per-key warning (the declared
+ * intent cannot be honored — unlike an undeclared route, which is silent).
+ */
+
+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 {
+  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. */
+export const SHELL_STATUS_HEADER = "x-rango-shell";
+
+/** Partial-navigation status header set only after captured PPR segments are consumed. */
+export const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
+
+/**
+ * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
+ * that omits `ttl`.
+ */
+export const DEFAULT_PPR_TTL_SECONDS = 300;
+
+/**
+ * Timeout for the dev /__rsc_shell endpoint's sequential /__rsc_prerender
+ * pre-flight probe (vite/router-discovery.ts). Hoisted here so the client-side
+ * fetch bound (shell-build-manifest.ts devShellFetchTimeoutMs) enumerates the
+ * SAME term of the endpoint's worst-case envelope — the two cannot drift.
+ */
+export const DEV_SHELL_PROBE_TIMEOUT_MS: number = 10_000;
+
+/** The route's ppr option normalized to a concrete policy. */
+export interface ResolvedPprConfig {
+  ttl: number;
+  swr?: number;
+  tags?: string[];
+  /**
+   * Snapshot size cap, passed through undefaulted (like swr/tags): the single
+   * defaulting site is captureAndStoreShell (DEFAULT_PPR_MAX_SNAPSHOT_BYTES in
+   * shell-capture.ts), so direct descriptor callers and resolved configs
+   * cannot drift.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in ms (`ppr.captureTimeout`). Undefined = the
+   * capture default (SHELL_CAPTURE_MAX_WAIT_MS, 15_000) — the default's single
+   * owner stays shell-capture.ts so build/runtime producers cannot drift.
+   */
+  captureTimeout?: number;
+}
+
+/**
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms is
+ * clamped to the default ceiling; anything else (including
+ * 0/negative/NaN/Infinity/non-number) resolves to undefined, which means "use
+ * the capture default" downstream.
+ * Mirrors the prefetch-limit option policy: invalid values silently fall back
+ * to the default rather than throwing at request time. Also the boundary
+ * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),
+ * whose param crossed an HTTP query string.
+ */
+export function normalizeCaptureTimeout(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1
+    ? Math.min(value, SHELL_CAPTURE_MAX_WAIT_MS)
+    : undefined;
+}
+
+/**
+ * Normalize the matched page route's `ppr` path option. Returns null when the
+ * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
+ * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
+ *
+ * The route's NAME is irrelevant here (and everywhere on the shell lane):
+ * nameless `path()` routes register their EntryData under a synthesized
+ * `$path_*` manifest key with the `ppr` option intact (urls/path-helper.ts),
+ * so a nameless entry resolves exactly like a named one — pinned by the
+ * nameless-ppr e2e in both apps (issue #714).
+ *
+ * PPR is a DOCUMENT-level property of the page route; there is no subtree
+ * inheritance (declaring it on a layout is not supported — a follow-up).
+ */
+export function resolvePprConfig(
+  entry: EntryData | undefined | null,
+): ResolvedPprConfig | null {
+  // isPprEntry (server/context.ts) is the ONE opt-in predicate — shared with
+  // the header-write latch so serve and guard can never drift.
+  if (!entry || !isPprEntry(entry)) return null;
+  const ppr = entry.ppr;
+  if (ppr === true) return { ttl: DEFAULT_PPR_TTL_SECONDS };
+  return {
+    ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,
+    swr: ppr.swr,
+    tags: ppr.tags,
+    maxSnapshotBytes: ppr.maxSnapshotBytes,
+    captureTimeout: normalizeCaptureTimeout(ppr.captureTimeout),
+  };
+}
+
+/**
+ * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
+ * (so it can never collide with a document-cache key; the store further isolates
+ * the shell family internally).
+ *
+ * The key includes the request HOST: in a multi-tenant host-router deployment
+ * (one worker, one shared KV/runtime-cache store) a host-less key would serve
+ * tenant A's captured shell to tenant B's users.
+ *
+ * `filter` is the request's compiled `cache.searchParams` config
+ * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
+ * Callers on the serve/capture path MUST pass it -- key drift between capture
+ * and lookup makes every shell request a permanent miss.
+ */
+export function buildShellKey(url: URL, filter?: SearchParamsFilter): string {
+  const sorted = sortedSearchString(url.searchParams, filter);
+  const searchSuffix = sorted ? `?${sorted}` : "";
+  return `${url.host}${url.pathname}${searchSuffix}:shell`;
+}
+
+/**
+ * Version gates for a stored shell: reactVersion AND buildVersion must both
+ * match the running server. The postponed blob encodes hole positions against
+ * one exact tree, so resuming it under a different React OR a different app
+ * build tree-mismatches inside resume() — after the 200 + prelude committed,
+ * with no recovery. Either mismatch is a miss: the recapture overwrites the
+ * same key (self-healing) and the entry otherwise ages out via TTL. An entry
+ * with no buildVersion (stored before the field existed) is a miss for the
+ * same reason — its build is unknown, so it cannot be proven resumable.
+ */
+export function isValidShellHit(
+  entry: ShellCacheEntry,
+  buildVersion: string,
+): boolean {
+  return (
+    entry.reactVersion === React.version && entry.buildVersion === buildVersion
+  );
+}
+
+/**
+ * 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,
+): 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);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Decode a base64 prelude back into bytes for stream composition. */
+export function base64ToBytes(b64: string): Uint8Array {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+/** True when the store implements the shell entry family. */
+export function hasShellFamily(
+  store: SegmentCacheStore | undefined,
+): store is SegmentCacheStore & {
+  getShell: NonNullable<SegmentCacheStore["getShell"]>;
+  putShell: NonNullable<SegmentCacheStore["putShell"]>;
+} {
+  return !!store?.getShell && !!store?.putShell;
+}
+
+/**
+ * Per-stage timing of one shell-HIT tail, all offsets in ms from the response
+ * commit (prelude flush). The HIT commits its 200 + headers BEFORE the live
+ * tail runs, so Server-Timing on the HIT response structurally cannot carry
+ * these numbers — they ride the dev mirror below instead (same doctrine as
+ * the ppr:capture mirror in rsc-rendering.ts, issue #651).
+ */
+export interface ShellTailTiming {
+  key: string;
+  outcome: "complete" | "redirect" | "error";
+  /** Loader-family seed decode (only when the entry carried a snapshot). */
+  seedMs?: number;
+  /** Tail router.match() settled. */
+  matchMs?: number;
+  /** Tail stream (resume output) handed to the response stream. */
+  handoverMs?: number;
+  /** First resumed-HTML byte enqueued on the wire. */
+  firstHtmlMs?: number;
+  /** Tail fully drained (last hole settled and flushed). */
+  completeMs?: number;
+  /** Prelude size flushed at commit (decoded bytes). */
+  preludeBytes?: number;
+  /** Total tail bytes streamed behind the prelude. */
+  tailBytes?: number;
+}
+
+/**
+ * Compact single-line form for the console log and the dev Server-Timing
+ * mirror's `desc`. Plain alphanumerics/`=`/`-` only — no quoted-string
+ * escaping needed.
+ */
+export function describeShellTailTiming(timing: ShellTailTiming): string {
+  const parts: string[] = [timing.outcome];
+  if (timing.seedMs !== undefined) parts.push(`seed=${timing.seedMs}ms`);
+  if (timing.matchMs !== undefined) parts.push(`match=${timing.matchMs}ms`);
+  if (timing.handoverMs !== undefined) {
+    parts.push(`handover=${timing.handoverMs}ms`);
+  }
+  if (timing.firstHtmlMs !== undefined) {
+    parts.push(`first-html=${timing.firstHtmlMs}ms`);
+  }
+  if (timing.completeMs !== undefined) {
+    parts.push(`complete=${timing.completeMs}ms`);
+  }
+  if (timing.preludeBytes !== undefined) {
+    parts.push(`prelude=${timing.preludeBytes}b`);
+  }
+  if (timing.tailBytes !== undefined) parts.push(`tail=${timing.tailBytes}b`);
+  return parts.join(" ");
+}
+
+/**
+ * Dev-only last-tail-per-key buffer backing the `ppr:tail` Server-Timing
+ * mirror: a HIT's tail finishes after its own headers are long gone, so its
+ * per-stage numbers ride the NEXT ppr GET for the key when the metrics
+ * surface is active (debugPerformance). Same shape and FIFO cap as the
+ * capture mirror (shell-capture.ts lastCaptureEventsForTiming); dev-only so
+ * production isolates never grow the map.
+ */
+const lastTailTimingsForServerTiming = new Map<string, ShellTailTiming>();
+const MAX_TAIL_TIMING_KEYS = 100;
+
+/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+export function publishShellTailTiming(timing: ShellTailTiming): void {
+  if (process.env.NODE_ENV === "production") return;
+  lastTailTimingsForServerTiming.delete(timing.key);
+  if (lastTailTimingsForServerTiming.size >= MAX_TAIL_TIMING_KEYS) {
+    const oldest = lastTailTimingsForServerTiming.keys().next().value;
+    if (oldest !== undefined) lastTailTimingsForServerTiming.delete(oldest);
+  }
+  lastTailTimingsForServerTiming.set(timing.key, timing);
+}
+
+/**
+ * Consume (read-and-clear) the buffered tail timing for `key`, so one tail
+ * reports into exactly one later response's Server-Timing.
+ */
+export function takeShellTailTimingForServerTiming(
+  key: string,
+): ShellTailTiming | undefined {
+  const timing = lastTailTimingsForServerTiming.get(key);
+  if (timing) lastTailTimingsForServerTiming.delete(key);
+  return timing;
+}
+
+/** Keys already warned about a missing shell store family (once per key). */
+const warnedMissingStore = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but the app-level cache store
+ * does not implement the shell family (getShell/putShell), so the route stays on
+ * axis 1. Unlike an undeclared route (silent), a declared route that cannot be
+ * honored deserves a diagnostic.
+ */
+export function warnShellStoreMissingOnce(key: string): void {
+  if (warnedMissingStore.has(key)) return;
+  warnedMissingStore.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but the app-level ` +
+      "cache store does not implement the shell family (getShell/putShell), so " +
+      "the route is served on axis 1 without a shell. Use MemorySegmentCacheStore, " +
+      "CFCacheStore, or VercelCacheStore (or add the family to your custom store) " +
+      "via createRouter({ cache }).",
+  );
+}
+
+/** Keys already warned about an active per-request nonce (once per key). */
+const warnedNonceActive = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but a per-request CSP nonce is
+ * active for the request, so the route stays on axis 1 (a shared shell would
+ * freeze one request's nonce for every visitor — useNonce() renders it into every
+ * nonced script/style/meta and the browser's CSP would then reject the frozen
+ * nonce for all but the capture request). The nonce blocks capture whether it came
+ * from the `createRouter({ nonce })` provider or from a direct `ctx.set(nonce, …)`
+ * token write in middleware. Same declared-intent-cannot-be-honored doctrine as
+ * the missing-store warning above (an undeclared route stays silent).
+ */
+export function warnPprNonceActiveOnce(key: string): void {
+  if (warnedNonceActive.has(key)) return;
+  warnedNonceActive.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but a per-request ` +
+      "CSP nonce is active for this request (from createRouter({ nonce }) or a " +
+      "ctx.set(nonce, …) token write in middleware), so the route is served on " +
+      "axis 1 without a shell. A shell is shared per host+URL; baking one " +
+      "request's nonce into it would break CSP for every other visitor. Drop the " +
+      "ppr option on this route, or stop setting a per-request nonce for it.",
+  );
+}

package/src/rsc/ssr-setup.ts

@@ -7,10 +7,19 @@
  */
 
 import type { HandlerContext } from "./handler-context.js";
-import type { SSRModule } from "./types.js";
+import type { SSRModule, SSRRenderOptions } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 import type { MetricsStore } from "../server/context.js";
+import type {
+  RscFlightStage,
+  RscPreparedHtmlRender,
+} from "./render-pipeline.js";
 import { appendMetric } from "../router/metrics.js";
+import {
+  parseAcceptTypes,
+  prefersFlightRepresentation,
+  RSC_WIRE_MIME,
+} from "../router/content-negotiation.js";
 import { _getRequestContext } from "../server/request-context.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
@@ -65,6 +74,49 @@ export function startSSRSetup<TEnv>(
   ]);
 }
 
+export interface SsrHtmlStageOptions<TEnv> {
+  ctx: HandlerContext<TEnv>;
+  request: Request;
+  env: TEnv;
+  url: URL;
+  /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
+  metricsStore: MetricsStore | undefined;
+  /**
+   * renderHTML options minus streamMode (the stage resolves streamMode). Carries
+   * the per-site nonce and, for the PE action re-render, formState. Spread
+   * verbatim so each call site's exact key set is preserved.
+   */
+  render: Omit<SSRRenderOptions, "streamMode">;
+  /** ResponseInit merged into the prepared render (e.g. content-type). */
+  init?: ResponseInit;
+}
+
+/**
+ * Build the `html` stage callback renderRscResponse drives: await the (possibly
+ * early-kicked-off) SSR setup, then renderHTML over the Flight stream. The four
+ * render paths (rsc-rendering full/partial, 404, PE, PE-error) differ only in
+ * metricsStore, render options (nonce/formState), and init — threaded here so
+ * the getSSRSetup + renderHTML wiring lives in one place.
+ */
+export function createSsrHtmlStage<TEnv>(
+  options: SsrHtmlStageOptions<TEnv>,
+): (flight: RscFlightStage) => Promise<RscPreparedHtmlRender> {
+  return async (flight) => {
+    const [ssrModule, streamMode] = await getSSRSetup(
+      options.ctx,
+      options.request,
+      options.env,
+      options.url,
+      options.metricsStore,
+    );
+    return {
+      render: () =>
+        ssrModule.renderHTML(flight.stream, { ...options.render, streamMode }),
+      ...(options.init && { init: options.init }),
+    };
+  };
+}
+
 /**
  * Retrieve the SSR setup result. Returns the early-kicked-off promise
  * when available (stashed on request variables), otherwise starts a
@@ -77,7 +129,7 @@ export function getSSRSetup<TEnv>(
   url: URL,
   metricsStore: MetricsStore | undefined,
 ): Promise<SSRSetup> {
-  const early = _getRequestContext()?.var?.[SSR_SETUP_VAR] as
+  const early = _getRequestContext()?._variables?.[SSR_SETUP_VAR] as
     | Promise<SSRSetup>
     | undefined;
   if (early) return early;
@@ -90,15 +142,45 @@ export function getSSRSetup<TEnv>(
   );
 }
 
+/**
+ * Accept-based flight opt-in: the client explicitly listed the RSC wire
+ * format (text/x-component) in Accept, ranked above the HTML document, and
+ * did not override with __html.
+ *
+ * The flight stream is an internal transport representation — it is served
+ * ONLY on explicit opt-in (this Accept value, or the _rsc_ / __rsc transport
+ * params). Everything else (missing Accept, wildcards, application/json,
+ * browser Accept strings) gets the HTML document, per RFC 9110: a missing
+ * Accept is equivalent to a full wildcard, and a wildcard gets the server's
+ * canonical representation. The old rule ("no text/html substring → flight")
+ * handed the wire format to every generic client — curl, health checks,
+ * link unfurlers.
+ *
+ * The includes() guard is a parse-skipping fast path: the bulk of traffic
+ * (browsers, curl, monitors) never mentions the wire format and pays no
+ * parseAcceptTypes allocation. Ranking lives in prefersFlightRepresentation
+ * (router/content-negotiation.ts), co-located with the candidate MIME set.
+ */
+function acceptsFlightExplicitly(request: Request, url: URL): boolean {
+  if (url.searchParams.has("__html")) return false;
+  const accept = request.headers.get("accept");
+  if (accept === null || !accept.includes(RSC_WIRE_MIME)) return false;
+  return prefersFlightRepresentation(parseAcceptTypes(accept));
+}
+
 /**
  * Classify whether a request may require SSR (HTML rendering).
  *
- * Returns false for requests that are definitively RSC-only, loader fetches,
- * prerender collection, or Accept-based RSC (no text/html). This mirrors
- * the isRscRequest decision in rsc-rendering.ts.
+ * Returns false for requests that are definitively RSC-only: transport
+ * params (partial/action/loader/__rsc), prerender collection, or an explicit
+ * Accept: text/x-component. Must never return false for a request whose
+ * render-time decision (isRscRequest) will be HTML — the two share
+ * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
+ * keys its HTML/RSC response slots off this function, so any divergence from
+ * the render decision poisons a cache slot with the wrong representation.
  *
  * Note: response/mime routes are excluded by the caller — this function
- * runs after previewMatch() classifies the route type.
+ * runs after classifyRequest() determines the request mode.
  */
 export function mayNeedSSR(request: Request, url: URL): boolean {
   if (
@@ -112,17 +194,30 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
     return false;
   }
 
-  // Mirror the Accept-based RSC decision from rsc-rendering.ts:
-  // if Accept is present and does not include text/html (and no __html override),
-  // the response will be RSC, not HTML.
-  const accept = request.headers.get("accept");
-  if (
-    accept &&
-    !accept.includes("text/html") &&
-    !url.searchParams.has("__html")
-  ) {
-    return false;
-  }
+  return !acceptsFlightExplicitly(request, url);
+}
 
-  return true;
+// Final render-time decision: is the response an RSC stream (vs HTML)?
+// Flight requires explicit opt-in: the partial transport param, __rsc, or
+// Accept: text/x-component. mayNeedSSR is the coarse pre-filter over the
+// transport params; both delegate the Accept call to acceptsFlightExplicitly.
+//
+// _rsc_partial is read from the URL in addition to the plan-derived isPartial
+// flag: the 404 fallback plan hardcodes mode "full-render" even for partial
+// navigations (handler.ts RouteNotFoundError catch), so a partial 404 reaches
+// this decision with isPartial=false. The old Accept rule masked that by
+// classifying */* as flight; without the URL check a client-side navigation
+// to a missing route received an HTML 404 it cannot apply, and the
+// navigation never committed (multi-router soft-404, popstate not-found).
+export function isRscRequest(
+  request: Request,
+  url: URL,
+  isPartial: boolean,
+): boolean {
+  return (
+    isPartial ||
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("__rsc") ||
+    acceptsFlightExplicitly(request, url)
+  );
 }

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,
+  });
+}