@rangojs/router 0.0.0-experimental.147 → 0.0.0-experimental.149

package/src/rsc/shell-build-manifest.ts

@@ -27,7 +27,12 @@
 
 import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
-import { hasIntactShellPayload, isValidShellHit } from "./shell-serve.js";
+import {
+  DEV_SHELL_PROBE_TIMEOUT_MS,
+  hasIntactShellPayload,
+  isValidShellHit,
+} from "./shell-serve.js";
+import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture.js";
 import { buildShellManifestKey } from "../prerender/shell-manifest-key.js";
 
 /** One baked manifest record (the __ps asset module's default export). */
@@ -133,18 +138,37 @@ export interface DevShellLookup {
   ttl: number;
   swr?: number;
   tags?: string[];
+  maxSnapshotBytes?: number;
+  /** Resolved `ppr.captureTimeout` (ms) — the endpoint's capture honors it. */
+  captureTimeout?: number;
 }
 
+/** Retry delay (~400ms) plus quiesce/fizz/store headroom past the budgets. */
+const DEV_SHELL_RETRY_MARGIN_MS = 5_000;
+
 /**
- * Bound like the dev prerender store fetch (see #697): inside a workerd
- * waitUntil an unsettled fetch pends forever instead of rejecting; on
- * timeout this degrades to a MISS and the runtime capture path takes over.
- * 20s (not the store fetch's 10s): the endpoint's response IS an inline
- * capture — up to ~5s attempt + 400ms + ~5s cold-graph retry — and this
- * fetch blocks a foreground document request, so it must outlast a full
- * cold capture cycle rather than abort into a MISS at 10s.
+ * Timed out like the dev prerender store fetch (see #697): inside a workerd
+ * waitUntil an unsettled fetch pends forever instead of rejecting; on timeout
+ * this degrades to a MISS and the runtime capture path takes over. But this
+ * fetch blocks a foreground document request and its response IS an inline
+ * capture, so the bound must cover the endpoint's FULL sequential worst case
+ * — aborting a still-healthy capture turns it into a spurious MISS. The terms
+ * of the server envelope (dev /__rsc_shell, vite/router-discovery.ts):
+ * - DEV_SHELL_PROBE_TIMEOUT_MS: the sequential /__rsc_prerender pre-flight
+ *   probe (same constant on the endpoint side).
+ * - 2x the capture settle budget (`ppr.captureTimeout`, default
+ *   SHELL_CAPTURE_MAX_WAIT_MS): first attempt + one in-place cold-graph retry.
+ * - DEV_SHELL_RETRY_MARGIN_MS: the ~400ms retry delay plus headroom.
+ * Deeper fix (possible follow-up): the endpoint owns ONE total deadline and
+ * this bound becomes a plain liveness backstop instead of envelope math.
  */
-const DEV_SHELL_FETCH_TIMEOUT_MS = 20_000;
+function devShellFetchTimeoutMs(captureTimeout: number | undefined): number {
+  return (
+    DEV_SHELL_PROBE_TIMEOUT_MS +
+    2 * (captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS) +
+    DEV_SHELL_RETRY_MARGIN_MS
+  );
+}
 
 async function fetchDevShellEntry(
   pathname: string,
@@ -162,9 +186,15 @@ async function fetchDevShellEntry(
   });
   if (dev.swr !== undefined) params.set("swr", String(dev.swr));
   if (dev.tags && dev.tags.length > 0) params.set("tags", dev.tags.join(","));
+  if (dev.maxSnapshotBytes !== undefined) {
+    params.set("maxSnapshotBytes", String(dev.maxSnapshotBytes));
+  }
+  if (dev.captureTimeout !== undefined) {
+    params.set("captureTimeout", String(dev.captureTimeout));
+  }
   try {
     const res = await fetch(`${devUrl}/__rsc_shell?${params}`, {
-      signal: AbortSignal.timeout(DEV_SHELL_FETCH_TIMEOUT_MS),
+      signal: AbortSignal.timeout(devShellFetchTimeoutMs(dev.captureTimeout)),
     });
     if (!res.ok) return undefined;
     return (await res.json()) as BuildShellEntry;

package/src/rsc/shell-capture-constants.ts

@@ -0,0 +1,27 @@
+/**
+ * Default upper bound on the capture prerender wait before forcing the abort
+ * that freezes the shell — the ONLY wall-clock on the capture path, and a
+ * pathological guard: it should never fire once the caller's `quiesce` is a
+ * task-quantized, frozen-byte signal (the capture gate in shell-capture.ts).
+ *
+ * Leaf module on purpose (imports nothing): shell-capture.ts re-exports it
+ * (single import site for the rsc graph — shell-build-manifest.ts sizes the
+ * dev fetch envelope from that re-export) and ssr/index.tsx uses it as
+ * captureShellHTML's own fallback; the ssr graph must not pull the capture
+ * orchestration module for one number.
+ *
+ * 15s, raised from 5s: captures are background work (waitUntil), so the budget
+ * costs latency-to-HIT only — never a served response — and 5s spuriously
+ * refused legitimately-slow deferred shell material (a real storefront's meta
+ * chains settle at ~7s). Ceiling math: workerd's waitUntil lifetime is ~30s
+ * past response completion, and a guaranteed two-attempt envelope needs
+ * 2x budget + the in-place retry delay + store I/O, i.e. budget <= ~14s. The
+ * 15s default deliberately sits just past that: attempt 1 always gets its
+ * full 15s, but when it consumed the whole budget the in-place RETRY may be
+ * truncated by the platform kill on workerd — degrading to the existing
+ * best-effort contract (the key stays MISS; a later request re-captures).
+ * Node/dev and build-time captures have no waitUntil ceiling. The per-route
+ * `ppr.captureTimeout` knob remains for tightening below the default. See
+ * docs/design/ppr-shell-resume.md (Cost model).
+ */
+export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;

package/src/rsc/shell-capture.ts

@@ -21,6 +21,8 @@ import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
 import { 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 {
   runWithRequestContext,
@@ -78,8 +80,13 @@ import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
  */
 const FLIGHT_QUIET_HOPS = 2;
 
-/** Default upper bound on the capture prerender wait before forcing the abort. */
-const SHELL_CAPTURE_MAX_WAIT_MS = 5000;
+/**
+ * Default capture budget. Canonical value, raise rationale, and ceiling math
+ * live on the leaf module (shell-capture-constants.ts, importable from the ssr
+ * graph too). Re-exported here so shell-build-manifest.ts's envelope math
+ * keeps its existing import site and cannot drift from the capture.
+ */
+export { SHELL_CAPTURE_MAX_WAIT_MS };
 
 /**
  * Upper bound on waiting for the capture's DEFERRED cache writes to settle before
@@ -369,6 +376,254 @@ function warnUntaggedShellBakeOnce(key: string): void {
   );
 }
 
+/**
+ * Default cap (serialized UTF-8 bytes) on the capture data snapshot riding
+ * inside a shell entry, when the route's `ppr` option does not set
+ * `maxSnapshotBytes`. 8 MiB: the snapshot shares the stored envelope with the
+ * base64 prelude and the postponed blob, and the tightest store value limit is
+ * Cloudflare KV's 25 MiB — 8 MiB of snapshot leaves the envelope well under it
+ * while still fitting any sane pinned-ring payload. Applied ONLY in
+ * captureAndStoreShell (the single defaulting site — resolvePprConfig passes
+ * the option through undefaulted), so every producer and direct caller gets
+ * the same policy. Over the cap the snapshot is skipped (shell still stored;
+ * pinned reads drift — see PartialPrerenderProps.maxSnapshotBytes).
+ */
+export const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number = 8 * 1024 * 1024;
+
+/** Cached encoder for the snapshot byte measurement (one per module, not per capture). */
+const SNAPSHOT_BYTE_ENCODER = new TextEncoder();
+
+/** Keys already warned about an over-cap snapshot (once per key per isolate). */
+const warnedOverCapSnapshots = new Set<string>();
+
+/**
+ * Warn once per key that the capture data snapshot exceeded the route's
+ * `maxSnapshotBytes` cap and was skipped. The shell entry is still stored and
+ * served — only the pinned-read replay is lost, so shell-baked cached content
+ * can drift from the frozen prelude between capture and HIT and hydration
+ * repairs it client-side (the pre-snapshot behavior). Once per key: the same
+ * page recaptures on every TTL roll and would otherwise re-warn forever.
+ */
+function warnSnapshotOverCapOnce(
+  key: string,
+  snapshotBytes: number,
+  capBytes: number,
+): void {
+  if (warnedOverCapSnapshots.has(key)) return;
+  warnedOverCapSnapshots.add(key);
+  console.warn(
+    `[rango] Shell capture for "${key}" recorded a ${snapshotBytes}-byte data ` +
+      `snapshot, over the ${capBytes}-byte cap — the snapshot was skipped and ` +
+      "the shell was stored without it. The page keeps serving, but cached " +
+      "content baked into the shell is no longer pinned: if it drifts before " +
+      "the shell's TTL, hydration repairs the mismatch client-side. Raise the " +
+      "cap via the route's ppr option ({ maxSnapshotBytes }) if the entry " +
+      "still fits your store's value limit (Cloudflare KV: 25 MiB per value), " +
+      "or shrink the cache()'d data the shell bakes.",
+  );
+}
+
+/**
+ * One structured event from the background capture pipeline, mirroring the
+ * CFCacheReadDebugEvent pattern (cache/cf/cf-cache-types.ts): typed fields an
+ * operator can assert against, emitted per attempt and per skip, so the
+ * stored / no-shell / refused / backed-off lifecycle is observable outside
+ * dev console warnings. Configured via `createRouter({ debugShellCapture })`.
+ */
+export interface ShellCaptureDebugEvent {
+  /** Shell cache key the event is about. */
+  key: string;
+  /**
+   * What happened:
+   * - stored / redirect / no-shell / refused: one capture ATTEMPT's outcome
+   *   (see CaptureAttemptOutcome for the semantics of each)
+   * - error: the capture task failed with a genuine error (also routed through
+   *   reportCacheError; the key is backed off)
+   * - skip-in-flight: scheduleShellCapture found a capture already running for
+   *   the key (stampede guard) and scheduled nothing
+   * - skip-backoff: the key is inside its refused-capture backoff window and
+   *   the capture was not attempted
+   * - backoff: the key entered (or escalated) backoff after a terminal
+   *   no-shell — carries the new backoff state
+   */
+  outcome:
+    | "stored"
+    | "redirect"
+    | "no-shell"
+    | "refused"
+    | "error"
+    | "skip-in-flight"
+    | "skip-backoff"
+    | "backoff";
+  /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
+  attempt?: number;
+  /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
+  attemptMs?: number;
+  /**
+   * Wall-clock ms the pre-render WRITE BARRIER waited on the foreground
+   * request's deferred cache writes (bounded by SHELL_CAPTURE_WRITE_BARRIER_MS).
+   */
+  barrierWaitMs?: number;
+  /**
+   * Wall-clock ms spent awaiting the capture's own deferred cache writes
+   * before the snapshot drain (bounded by SHELL_SNAPSHOT_WRITE_SETTLE_MS).
+   */
+  writeSettleMs?: number;
+  /** Stored prelude size in bytes (pre-base64). */
+  preludeBytes?: number;
+  /** Serialized snapshot size in UTF-8 bytes. Absent when nothing was recorded. */
+  snapshotBytes?: number;
+  /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
+  snapshotSkipped?: boolean;
+  /** Consecutive failure count in the key's backoff entry, when one exists. */
+  backoffFailures?: number;
+  /** Ms remaining in the key's backoff window, when one exists. */
+  backoffRemainingMs?: number;
+}
+
+/**
+ * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
+ * logs each event to console (visible via `wrangler tail`), a function
+ * receives the events for programmatic capture. Off by default.
+ */
+export type ShellCaptureDebug =
+  | boolean
+  | ((event: ShellCaptureDebugEvent) => void);
+
+/**
+ * Compact single-line form of an event's fields, shared by the console sink
+ * and the dev Server-Timing mirror's `desc` (rsc-rendering). Plain
+ * alphanumerics/`=`/`-`/`()` only, so it needs no quoted-string escaping.
+ */
+export function describeShellCaptureEvent(
+  event: ShellCaptureDebugEvent,
+): string {
+  const parts: string[] = [event.outcome];
+  if (event.attempt !== undefined) parts.push(`attempt=${event.attempt}`);
+  if (event.attemptMs !== undefined) parts.push(`${event.attemptMs}ms`);
+  if (event.barrierWaitMs !== undefined) {
+    parts.push(`barrier=${event.barrierWaitMs}ms`);
+  }
+  if (event.writeSettleMs !== undefined) {
+    parts.push(`write-settle=${event.writeSettleMs}ms`);
+  }
+  if (event.preludeBytes !== undefined) {
+    parts.push(`prelude=${event.preludeBytes}b`);
+  }
+  if (event.snapshotBytes !== undefined) {
+    parts.push(
+      `snapshot=${event.snapshotBytes}b${event.snapshotSkipped ? " (over cap, skipped)" : ""}`,
+    );
+  }
+  if (event.backoffFailures !== undefined) {
+    parts.push(`backoff-failures=${event.backoffFailures}`);
+  }
+  if (event.backoffRemainingMs !== undefined) {
+    parts.push(`backoff-remaining=${event.backoffRemainingMs}ms`);
+  }
+  return parts.join(" ");
+}
+
+/** The `debugShellCapture: true` console sink: one compact line per event. */
+function consoleCaptureDebugSink(event: ShellCaptureDebugEvent): void {
+  console.log(
+    `[ShellCache][debug] ${event.key} ${describeShellCaptureEvent(event)}`,
+  );
+}
+
+/**
+ * Resolve the `debugShellCapture` router option to a callable sink, or
+ * undefined when off. The INTERNAL_RANGO_DEBUG env-flag fallback lives HERE
+ * (not at a call site) so every producer that resolves a sink inherits it;
+ * an explicit `false` wins over the env flag.
+ */
+export function resolveShellCaptureDebugSink(
+  option: ShellCaptureDebug | undefined,
+): ((event: ShellCaptureDebugEvent) => void) | undefined {
+  if (option === false) return undefined;
+  if (option === true) return consoleCaptureDebugSink;
+  if (typeof option === "function") return option;
+  return INTERNAL_RANGO_DEBUG ? consoleCaptureDebugSink : undefined;
+}
+
+/**
+ * Attempt-terminal outcomes recorded for the dev Server-Timing mirror. Skip
+ * events are excluded so a later request's skip cannot overwrite the
+ * interesting terminal event before a metrics-enabled request reads it.
+ */
+const TIMING_RECORDED_OUTCOMES = new Set<ShellCaptureDebugEvent["outcome"]>([
+  "stored",
+  "redirect",
+  "no-shell",
+  "refused",
+  "error",
+]);
+
+/**
+ * Dev-only last-terminal-event-per-key buffer backing the Server-Timing
+ * mirror: the capture runs AFTER its triggering response is committed, so its
+ * outcome can only ride a LATER response's header. rsc-rendering consumes this
+ * on the next ppr GET for the key when the metrics store is active
+ * (debugPerformance) and appends a `ppr:capture` Server-Timing entry. Dev-only
+ * (isDevMode) so production isolates never grow the map; FIFO-capped because
+ * with debugPerformance OFF nothing ever drains it, and a long dev session
+ * sweeping many URLs would otherwise accumulate one entry per shell key
+ * forever.
+ */
+const lastCaptureEventsForTiming = new Map<string, ShellCaptureDebugEvent>();
+const MAX_TIMING_EVENT_KEYS = 100;
+
+/**
+ * Consume (read-and-clear) the buffered terminal capture event for `key`, so
+ * one capture reports into exactly one later response's Server-Timing.
+ */
+export function takeCaptureDebugEventForTiming(
+  key: string,
+): ShellCaptureDebugEvent | undefined {
+  const event = lastCaptureEventsForTiming.get(key);
+  if (event) lastCaptureEventsForTiming.delete(key);
+  return event;
+}
+
+/**
+ * Publish one capture debug event: buffer terminal outcomes for the dev
+ * Server-Timing mirror, then hand the event to the configured sink. A
+ * throwing sink is swallowed — diagnostics must never fail a capture.
+ */
+function publishCaptureDebugEvent(
+  descriptor: Pick<ShellCaptureDescriptor, "debugSink">,
+  event: ShellCaptureDebugEvent,
+): void {
+  if (isDevMode() && TIMING_RECORDED_OUTCOMES.has(event.outcome)) {
+    // Refresh insertion order for the FIFO cap, then evict the oldest key.
+    lastCaptureEventsForTiming.delete(event.key);
+    if (lastCaptureEventsForTiming.size >= MAX_TIMING_EVENT_KEYS) {
+      const oldest = lastCaptureEventsForTiming.keys().next().value;
+      if (oldest !== undefined) lastCaptureEventsForTiming.delete(oldest);
+    }
+    lastCaptureEventsForTiming.set(event.key, event);
+  }
+  const sink = descriptor.debugSink;
+  if (!sink) return;
+  try {
+    sink(event);
+  } catch {
+    // Diagnostics only: a throwing consumer sink must never fail the capture.
+  }
+}
+
+/** Current backoff state fields for `key` (empty when no backoff entry). */
+function backoffFields(
+  key: string,
+): Pick<ShellCaptureDebugEvent, "backoffFailures" | "backoffRemainingMs"> {
+  const entry = refusedCaptures.get(key);
+  if (!entry) return {};
+  return {
+    backoffFailures: entry.failures,
+    backoffRemainingMs: Math.max(0, entry.until - Date.now()),
+  };
+}
+
 export interface FlightCaptureGate {
   /** Identity passthrough of the source stream; feed this to captureShellHTML. */
   stream: ReadableStream<Uint8Array>;
@@ -548,9 +803,32 @@ export interface ShellCaptureDescriptor {
   ttl?: number;
   swr?: number;
   tags?: string[];
+  /**
+   * Per-route capture settle budget in ms (`ppr.captureTimeout`, resolved by
+   * resolvePprConfig). Feeds captureShellHTML's maxWaitMs — the ONE deadline
+   * bounding the whole capture, so it covers BOTH the fizz prerender AND the
+   * deferred-material settle window (the handlesBaked/loader-container
+   * holdUntil that keeps the gate from freezing while top-level pushes are
+   * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (15_000).
+   */
+  captureTimeout?: number;
   store?: SegmentCacheStore<any>;
   /** Gates the concise per-attempt capture breadcrumbs (INTERNAL_RANGO_DEBUG). */
   debug?: boolean;
+  /**
+   * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
+   * the snapshot is skipped and the shell stored without it (reported once per
+   * key). Absent = DEFAULT_PPR_MAX_SNAPSHOT_BYTES, applied in
+   * captureAndStoreShell — the single defaulting site.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Structured capture-pipeline debug sink, resolved from
+   * `createRouter({ debugShellCapture })` (or INTERNAL_RANGO_DEBUG) via
+   * {@link resolveShellCaptureDebugSink}. Receives one
+   * {@link ShellCaptureDebugEvent} per attempt/skip.
+   */
+  debugSink?: (event: ShellCaptureDebugEvent) => void;
 }
 
 /**
@@ -574,10 +852,20 @@ export function scheduleShellCapture(
   descriptor: ShellCaptureDescriptor,
 ): void {
   const key = descriptor.key;
-  if (inFlightCaptures.has(key)) return;
+  if (inFlightCaptures.has(key)) {
+    publishCaptureDebugEvent(descriptor, { key, outcome: "skip-in-flight" });
+    return;
+  }
   // Refused/failed within the window → skip the doomed re-render (one probe per
   // key per window per isolate). Expired entries self-evict inside the check.
-  if (isCaptureBackedOff(key)) return;
+  if (isCaptureBackedOff(key)) {
+    publishCaptureDebugEvent(descriptor, {
+      key,
+      outcome: "skip-backoff",
+      ...backoffFields(key),
+    });
+    return;
+  }
   inFlightCaptures.add(key);
   const captureTask = async () => {
     try {
@@ -595,12 +883,24 @@ export function scheduleShellCapture(
       // off so the next requests don't re-probe it. A `redirect` has no shell but
       // is not a doomed render — leave the backoff untouched.
       if (outcome === "stored") clearCaptureBackoff(key);
-      else if (outcome === "no-shell") markCaptureBackoff(key);
+      else if (outcome === "no-shell") {
+        markCaptureBackoff(key);
+        publishCaptureDebugEvent(descriptor, {
+          key,
+          outcome: "backoff",
+          ...backoffFields(key),
+        });
+      }
     } catch (error) {
       // Detached background task — pass reqCtx so onError still fires when the ALS
       // 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);
+      publishCaptureDebugEvent(descriptor, {
+        key,
+        outcome: "error",
+        ...backoffFields(key),
+      });
       reportCacheError(error, "cache-write", "[ShellCache] capture", reqCtx);
     } finally {
       inFlightCaptures.delete(key);
@@ -633,6 +933,21 @@ export function scheduleShellCapture(
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
+/**
+ * Per-attempt observability fields, filled along the capture path (barrier in
+ * attemptCapture, the rest in captureAndStoreShell) and folded into the
+ * attempt's {@link ShellCaptureDebugEvent} by runShellCapture. A plain mutable
+ * bag, not a return value: captureAndStoreShell's outcome type stays a string
+ * union its existing callers (producer B, tests) consume unchanged.
+ */
+interface CaptureAttemptStats {
+  barrierWaitMs?: number;
+  writeSettleMs?: number;
+  preludeBytes?: number;
+  snapshotBytes?: number;
+  snapshotSkipped?: boolean;
+}
+
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -665,15 +980,37 @@ async function runShellCapture(
     ? (message: string) => console.log(message)
     : () => {};
 
-  const first = await attemptCapture(
-    ctx,
-    request,
-    env,
-    url,
-    reqCtx,
-    ssrModule,
-    descriptor,
-  );
+  // One attempt + its structured debug event: the stats object rides through
+  // attemptCapture/captureAndStoreShell collecting the observability fields
+  // (barrier wait, write-settle wait, prelude/snapshot bytes), and the event
+  // folds them with the outcome. A genuine render error skips the attempt
+  // event — scheduleShellCapture's catch publishes the terminal `error` event.
+  const timedAttempt = async (
+    attempt: number,
+  ): Promise<CaptureAttemptOutcome> => {
+    const stats: CaptureAttemptStats = {};
+    const start = performance.now();
+    const outcome = await attemptCapture(
+      ctx,
+      request,
+      env,
+      url,
+      reqCtx,
+      ssrModule,
+      descriptor,
+      stats,
+    );
+    publishCaptureDebugEvent(descriptor, {
+      key: descriptor.key,
+      outcome,
+      attempt,
+      attemptMs: Math.round(performance.now() - start),
+      ...stats,
+    });
+    return outcome;
+  };
+
+  const first = await timedAttempt(1);
   // "refused" is deterministic (identity guard / rejected bake-lane loader —
   // its own warning already fired): no retry, and the caller backs the key off
   // exactly like a structural no-shell.
@@ -690,15 +1027,7 @@ async function runShellCapture(
     `[ShellCache] capture attempt 1/2 for ${descriptor.key} aborted before shell completed (cold modules?) — retrying`,
   );
   await delay(retryDelayMs);
-  const second = await attemptCapture(
-    ctx,
-    request,
-    env,
-    url,
-    reqCtx,
-    ssrModule,
-    descriptor,
-  );
+  const second = await timedAttempt(2);
   if (second === "refused") return "no-shell";
   if (second !== "no-shell") return second;
 
@@ -767,6 +1096,7 @@ async function attemptCapture(
   reqCtx: RequestContext<any>,
   ssrModule: SSRModule,
   descriptor: ShellCaptureDescriptor,
+  stats: CaptureAttemptStats,
 ): Promise<CaptureAttemptOutcome> {
   // WRITE BARRIER (ordering edge, not a narrower race): settle the foreground's
   // already-scheduled background tasks — its deferred ring-3/ring-1 cache writes —
@@ -777,7 +1107,9 @@ async function attemptCapture(
   // skipped, cache-store middleware's write path gated off by state.cacheHit), so
   // prelude, snapshot, and ring-3 agree on the foreground's generation. Runs per
   // attempt (the retry re-checks; already-settled promises are free).
+  const barrierStart = performance.now();
   await settleTrackedBackgroundTasks(reqCtx, SHELL_CAPTURE_WRITE_BARRIER_MS);
+  stats.barrierWaitMs = Math.round(performance.now() - barrierStart);
 
   const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(
     reqCtx,
@@ -817,6 +1149,7 @@ async function attemptCapture(
       freshHandleStore,
       derivedCtx,
       descriptor,
+      stats,
     );
   });
 }
@@ -1014,6 +1347,7 @@ async function captureAndStoreShell(
   handleStore: HandleStore,
   reqCtx: RequestContext<any>,
   capture: ShellCaptureDescriptor,
+  stats?: CaptureAttemptStats,
 ): Promise<Exclude<CaptureAttemptOutcome, "redirect">> {
   const captureShellHTML = ssrModule.captureShellHTML!;
 
@@ -1102,10 +1436,12 @@ async function captureAndStoreShell(
     // captureShellHTML CONSUMES the (gated) stream — it is not also SSR'd.
     let result: Awaited<ReturnType<typeof captureShellHTML>>;
     try {
+      // One deadline for the whole capture — semantics spec'd on the option
+      // (PartialPrerenderProps.captureTimeout, urls/pattern-types.ts).
       result = await observePhase(PHASES.ssr, () =>
         captureShellHTML(gate.stream, {
           quiesce,
-          maxWaitMs: SHELL_CAPTURE_MAX_WAIT_MS,
+          maxWaitMs: capture.captureTimeout ?? SHELL_CAPTURE_MAX_WAIT_MS,
         }),
       );
     } catch (error) {
@@ -1141,6 +1477,7 @@ async function captureAndStoreShell(
     if (result === null) {
       return "no-shell";
     }
+    if (stats) stats.preludeBytes = result.prelude.length;
 
     // 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 ??
@@ -1180,7 +1517,11 @@ async function captureAndStoreShell(
     const recording = getRecordingStore(reqCtx._cacheStore);
     let snapshot: ShellSnapshotRecord[] | undefined;
     if (recording) {
+      const settleStart = performance.now();
       await recording.settleWrites(SHELL_SNAPSHOT_WRITE_SETTLE_MS);
+      if (stats) {
+        stats.writeSettleMs = Math.round(performance.now() - settleStart);
+      }
       snapshot = recording.drainSnapshot();
     }
 
@@ -1239,6 +1580,29 @@ async function captureAndStoreShell(
       }
     }
 
+    // Snapshot size guard (issue #651): the snapshot duplicates every pinned
+    // cache value inside the shell entry, so a page over a large cache()
+    // segment can push the stored envelope toward store value limits (KV caps
+    // a value at 25 MiB) with no signal — the kv.put rejects deep inside
+    // waitUntil. Measure the serialized snapshot (UTF-8 bytes of the JSON that
+    // rides in the envelope) AFTER the loader family is appended, and over the
+    // cap store the shell WITHOUT it: pinned reads then fall back to the live
+    // store on a HIT (documented drift — hydration repairs a mismatch
+    // client-side, the pre-snapshot behavior), which beats losing the whole
+    // entry to a store-side write rejection. Reported once per key.
+    if (snapshot && snapshot.length > 0) {
+      const snapshotBytes = SNAPSHOT_BYTE_ENCODER.encode(
+        JSON.stringify(snapshot),
+      ).length;
+      if (stats) stats.snapshotBytes = snapshotBytes;
+      const cap = capture.maxSnapshotBytes ?? DEFAULT_PPR_MAX_SNAPSHOT_BYTES;
+      if (snapshotBytes > cap) {
+        warnSnapshotOverCapOnce(capture.key, snapshotBytes, cap);
+        snapshot = undefined;
+        if (stats) stats.snapshotSkipped = true;
+      }
+    }
+
     // Shell tags snapshot at the WRITE BARRIER, not at stream construction: by
     // here the capture has quiesced and the deferred cache writes were awaited, so
     // tags recorded AFTER an await in async shell content (and by async