@rangojs/router 0.4.3 → 0.5.1

package/src/rsc/capture-queue.ts

@@ -19,15 +19,55 @@
  * is bounded; a capture killed mid-queue by that bound simply recaptures on a
  * later request (the existing best-effort contract).
  *
- * The chain link resolves in `finally` and the prior link is awaited with a
- * swallow, so one rejected capture can never wedge every later one.
+ * Document shells outrank queued navigation-only snapshots. Production Link
+ * prefetching can enqueue several expensive navigation captures at once; a
+ * strict FIFO made the requesting page's document capture wait
+ * behind speculative work until its queue budget expired. The active capture
+ * is never interrupted, and each priority remains FIFO.
  */
-let captureQueue: Promise<void> = Promise.resolve();
 let admittedCaptures = 0;
+let captureRunning = false;
+
+interface QueuedCapture {
+  waitStart: number;
+  state: "waiting" | "running" | "settled";
+  signalStart: () => void;
+}
+
+const documentCaptures: QueuedCapture[] = [];
+const navigationCaptures: QueuedCapture[] = [];
 
 /** Bound queued/running capture closures retained by one isolate. */
 export const MAX_ADMITTED_CAPTURES: number = 32;
 
+/** Point-in-time queue occupancy, for capture-scheduling telemetry. */
+export interface CaptureQueueDepths {
+  /** A capture is currently executing (never preempted). */
+  running: boolean;
+  /** Waiting document-priority captures (run before every navigation capture). */
+  document: number;
+  /** Waiting navigation-priority captures. */
+  navigation: number;
+}
+
+/**
+ * Snapshot the queue's waiting/running state. Wait-timed-out entries still
+ * sitting in the arrays (pruned lazily by takeNextCapture) are excluded — they
+ * will never run, so counting them would overstate the backlog.
+ */
+export function captureQueueDepths(): CaptureQueueDepths {
+  const waiting = (queue: QueuedCapture[]): number => {
+    let count = 0;
+    for (const queued of queue) if (queued.state === "waiting") count++;
+    return count;
+  };
+  return {
+    running: captureRunning,
+    document: waiting(documentCaptures),
+    navigation: waiting(navigationCaptures),
+  };
+}
+
 /** The caller may drop this best-effort capture and retry on a later request. */
 export class CaptureQueueFullError extends Error {
   constructor() {
@@ -65,7 +105,7 @@ export class CaptureQueueWaitTimeoutError extends Error {
 }
 
 /**
- * Upper bound on how long one queue link may hold the queue. A capture task
+ * Upper bound on how long one running capture may hold the queue. A capture task
  * normally settles well inside this (attempt + in-place retry + writes), but
  * a task wedged on never-settling I/O — a workerd waitUntil fetch that pends
  * instead of rejecting (seen on GH runners with the dev prerender store
@@ -76,70 +116,103 @@ export class CaptureQueueWaitTimeoutError extends Error {
 const QUEUE_LINK_CAP_MS = 60_000;
 
 /**
- * Run `task` after every previously enqueued capture has settled. Returns a
- * promise for THIS task's completion (rejections propagate to the caller —
- * the queue itself is insulated).
+ * Run `task` after the active capture and every higher/equal-priority capture
+ * ahead of it have settled. Returns a promise for THIS task's completion
+ * (rejections propagate to the caller — the queue itself is insulated).
  */
 export function enqueueSerializedCapture(
   task: () => Promise<void>,
-  opts?: { maxQueueWaitMs?: number },
+  opts?: {
+    maxQueueWaitMs?: number;
+    priority?: "document" | "navigation";
+  },
 ): Promise<void> {
   if (admittedCaptures >= MAX_ADMITTED_CAPTURES) {
     return Promise.reject(new CaptureQueueFullError());
   }
   admittedCaptures++;
-  const prior = captureQueue;
-  let releaseQueue!: () => void;
-  captureQueue = new Promise<void>((resolve) => {
-    releaseQueue = resolve;
+
+  let signalStart!: () => void;
+  const startGate = new Promise<void>((resolve) => {
+    signalStart = resolve;
   });
-  return (async () => {
-    const waitStart = performance.now();
+  const queued: QueuedCapture = {
+    waitStart: performance.now(),
+    state: "waiting",
+    signalStart,
+  };
+
+  const completion = (async () => {
     const budget = opts?.maxQueueWaitMs ?? CAPTURE_QUEUE_WAIT_BUDGET_MS;
-    // The wait itself is budget-raced: the drop fires AT the budget, not once
-    // the predecessor eventually settles — a waiter parked behind a wedged
-    // link must not stay pending until that link's 60s cap just to learn it
-    // was already over budget.
     let waitTimer: ReturnType<typeof setTimeout> | undefined;
     const waitTimedOut = await Promise.race([
-      prior.catch(() => {}).then(() => false),
+      startGate.then(() => false),
       new Promise<boolean>((resolve) => {
-        waitTimer = setTimeout(() => resolve(true), budget);
+        waitTimer = setTimeout(() => {
+          if (queued.state !== "waiting") return;
+          queued.state = "settled";
+          admittedCaptures--;
+          resolve(true);
+        }, budget);
         (waitTimer as { unref?: () => void }).unref?.();
       }),
     ]);
     if (waitTimer) clearTimeout(waitTimer);
     if (waitTimedOut) {
-      // Never started: hand the admission slot back here (the taskPromise
-      // finally below does it for tasks that ran). Serialization stays
-      // intact: THIS link releases only once the predecessor settles —
-      // releasing now would let a successor run concurrently with it.
-      admittedCaptures--;
-      prior.catch(() => {}).then(releaseQueue, releaseQueue);
-      throw new CaptureQueueWaitTimeoutError(performance.now() - waitStart);
+      throw new CaptureQueueWaitTimeoutError(
+        performance.now() - queued.waitStart,
+      );
     }
+
+    let capTimer: ReturnType<typeof setTimeout> | undefined;
+    const taskPromise = Promise.resolve()
+      .then(task)
+      .finally(() => {
+        // A capped capture releases serialization, but its detached task still
+        // counts against admission until it actually settles.
+        admittedCaptures--;
+      });
+    const cap = new Promise<void>((resolve) => {
+      capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
+      (capTimer as { unref?: () => void }).unref?.();
+    });
+
     try {
-      let capTimer: ReturnType<typeof setTimeout> | undefined;
-      const taskPromise = Promise.resolve()
-        .then(task)
-        .finally(() => {
-          // A timed-out link releases serialization, but its detached task still
-          // counts against admission until it actually settles.
-          admittedCaptures--;
-        });
-      try {
-        await Promise.race([
-          taskPromise,
-          new Promise<void>((resolve) => {
-            capTimer = setTimeout(resolve, QUEUE_LINK_CAP_MS);
-            (capTimer as { unref?: () => void }).unref?.();
-          }),
-        ]);
-      } finally {
-        if (capTimer) clearTimeout(capTimer);
-      }
+      await Promise.race([taskPromise, cap]);
     } finally {
-      releaseQueue();
+      if (capTimer) clearTimeout(capTimer);
+      queued.state = "settled";
+      captureRunning = false;
+      // Handoff must happen before this caller's waitUntil promise settles.
+      // Resolving first lets workerd terminate the context with the queue lock
+      // still held, permanently parking later captures in the isolate.
+      startNextCapture();
     }
   })();
+
+  const queue =
+    opts?.priority === "document" ? documentCaptures : navigationCaptures;
+  queue.push(queued);
+  startNextCapture();
+  return completion;
+}
+
+function takeNextCapture(): QueuedCapture | undefined {
+  for (const queue of [documentCaptures, navigationCaptures]) {
+    let queued: QueuedCapture | undefined;
+    while ((queued = queue.shift())) {
+      if (queued.state === "waiting") return queued;
+    }
+  }
+  return undefined;
+}
+
+function startNextCapture(): void {
+  if (captureRunning) return;
+  const queued = takeNextCapture();
+  if (!queued) return;
+
+  captureRunning = true;
+  queued.state = "running";
+  queued.signalStart();
 }

package/src/rsc/rsc-rendering.ts

@@ -79,6 +79,7 @@ import { reportCacheError } from "../cache/cache-error.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type {
+  DocumentShellCacheEntry,
   SegmentCacheStore,
   ShellCacheEntry,
   ShellSnapshotRecord,
@@ -212,7 +213,14 @@ function replayableShellSnapshot(
   if (!isValidShellHit(entry, buildVersion)) {
     return { reason: "invalid-version" };
   }
-  if (!hasIntactShellPayload(entry)) return { reason: "corrupt-entry" };
+  // navigationOnly entries store no document half (prelude/postponed absent),
+  // so the payload gate applies to document-snapshot entries alone. Replay
+  // consumes only the snapshot; fragment corruption inside it is caught by the
+  // consumer-side Flight decoders (SegmentFragmentDecodeError →
+  // segmentReplayCorrupt → healing capture at the document key).
+  if (!entry.navigationOnly && !hasIntactShellPayload(entry)) {
+    return { reason: "corrupt-entry" };
+  }
   if (entry.handlerLiveHoles) return { reason: "handler-live-holes" };
   if (entry.transitionWhen) return { reason: "transition-when" };
   // Eligibility requires the CANONICAL doc segment record (`docKey`), not just
@@ -386,7 +394,7 @@ async function handleRscRenderingInner<TEnv>(
           // build-manifest hit further down): schedule the background
           // recapture when asked, then commit the composed response.
           const serveHit = (
-            entry: ShellCacheEntry,
+            entry: DocumentShellCacheEntry,
             revalidate: boolean | undefined,
           ): Response => {
             if (revalidate) {
@@ -1159,7 +1167,7 @@ function serveShellHit(
   reqCtx: RequestContext<any>,
   handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
   ssrModule: SSRModule,
-  entry: ShellCacheEntry,
+  entry: DocumentShellCacheEntry,
   descriptor: ShellCaptureDescriptor,
 ): Response {
   const preludeBytes = base64ToBytes(entry.prelude);

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

@@ -25,7 +25,11 @@
  *   markers say whether it is still current.
  */
 
-import type { SegmentCacheStore, ShellCacheEntry } from "../cache/types.js";
+import type {
+  DocumentShellCacheEntry,
+  SegmentCacheStore,
+  ShellCacheEntry,
+} from "../cache/types.js";
 import { sortedSearchString } from "../cache/cache-key-utils.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
 import {
@@ -88,20 +92,29 @@ function loadManifest(): Promise<ShellManifestModule | null> {
  * Spec-only keying is sound because buildVersion is process-constant on the
  * manifest path (folded into the shipped worker; dev never loads a manifest).
  */
-const validatedSpecs = new Map<string, BuildShellEntry | null>();
+const validatedSpecs = new Map<string, ValidatedBuildShellEntry | null>();
+
+/**
+ * A manifest record whose document half passed hasIntactShellPayload — the
+ * casts below sit directly on that runtime gate (build entries are always
+ * document-shaped; the predicate narrows entry, not the record around it).
+ */
+type ValidatedBuildShellEntry = BuildShellEntry & {
+  entry: DocumentShellCacheEntry;
+};
 
 async function validatedManifestRecord(
   mod: ShellManifestModule,
   spec: string,
   buildVersion: string,
-): Promise<BuildShellEntry | undefined> {
+): Promise<ValidatedBuildShellEntry | undefined> {
   let verdict = validatedSpecs.get(spec);
   if (verdict === undefined) {
     const record = (await mod.loadShellAsset(spec)).default;
     verdict =
       isValidShellHit(record.entry, buildVersion) &&
       hasIntactShellPayload(record.entry)
-        ? record
+        ? (record as ValidatedBuildShellEntry)
         : null;
     validatedSpecs.set(spec, verdict);
   }
@@ -118,7 +131,7 @@ export function resetBuildShellManifestForTests(): void {
 const warnedTagCheckUnsupported = new Set<string>();
 
 export interface BuildShellHit {
-  entry: ShellCacheEntry;
+  entry: DocumentShellCacheEntry;
   /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
   stale: boolean;
 }
@@ -273,7 +286,7 @@ export async function lookupBuildShell(
     const hasManifest = globalThis.__loadShellManifestModule !== undefined;
     if (!hasManifest && !dev) return null;
     if (sortedSearchString(url.searchParams, filter) !== "") return null;
-    let record: BuildShellEntry | undefined;
+    let record: ValidatedBuildShellEntry | undefined;
     if (hasManifest) {
       const mod = await loadManifest();
       if (!mod) return null;
@@ -286,7 +299,7 @@ export async function lookupBuildShell(
         fetched !== undefined &&
         isValidShellHit(fetched.entry, buildVersion) &&
         hasIntactShellPayload(fetched.entry)
-          ? fetched
+          ? (fetched as ValidatedBuildShellEntry)
           : undefined;
     }
     if (!record) return null;

package/src/rsc/shell-capture.ts

@@ -23,6 +23,7 @@ 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";
@@ -397,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
@@ -418,6 +456,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-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
@@ -434,6 +476,7 @@ 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. */
@@ -466,6 +509,22 @@ export interface ShellCaptureDebugEvent {
   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;
 }
 
 /**
@@ -515,6 +574,15 @@ export function describeShellCaptureEvent(
   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(" ");
 }
 
@@ -864,6 +932,16 @@ 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 (span: TraceSpan) => {
     try {
@@ -941,15 +1019,34 @@ export function scheduleShellCapture(
   const serializedTask = async () => {
     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);
-        });
+        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);
@@ -974,6 +1071,8 @@ export function scheduleShellCapture(
             key,
             outcome: "skip-queue-timeout",
             queueWaitMs: Math.round(error.waitedMs),
+            queuePriority,
+            queueAhead,
           });
           return;
         }
@@ -1035,6 +1134,7 @@ type CaptureAttemptStats = Pick<
   | "snapshotSkipped"
   | "untaggedBake"
   | "storeWrite"
+  | "bakeWaitMs"
 >;
 
 /**
@@ -1511,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.
@@ -1590,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
@@ -1746,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);