@rangojs/router 0.4.3 → 0.5.0

package/dist/types/cache/cf/cf-cache-store.d.ts

@@ -30,6 +30,8 @@ import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOpti
 export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
 export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     readonly supportsPassiveShellReads: true;
+    /** True when constructed without KV: the shell family no-ops (see ctor). */
+    readonly shellFamilyInert?: boolean;
     readonly defaults?: CacheDefaults;
     readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
     private readonly namespace?;

package/dist/types/cache/types.d.ts

@@ -164,6 +164,15 @@ export interface SegmentCacheStore<TEnv = unknown> {
      *   `stored` when acknowledged, or void for stores without acknowledgements.
      */
     putShell?(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    /**
+     * Declares the shell family present-but-inert: getShell/putShell exist but
+     * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
+     * captures whose only write target is inert — the background render would be
+     * dead work that still occupies the per-isolate serialized capture queue
+     * (a promise-heavy route bakes for seconds per MISS with nothing stored).
+     * Absent/false means the family, when present, actually stores.
+     */
+    shellFamilyInert?: boolean;
     /**
      * Get a cached function result by key.
      * Returns the serialized value, optional handle data, and staleness flag.
@@ -221,8 +230,8 @@ export interface CacheItemResult {
 /**
  * A cached PPR (Partial Pre-rendering) shell entry.
  *
- * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
- * and React's postponed state — because the pair is version- and
+ * A DOCUMENT entry carries BOTH artifacts a resume needs — the rendered HTML
+ * prelude and React's postponed state — because the pair is version- and
  * generation-coupled and must never be mixed across a React upgrade or a build
  * change. The reactVersion and buildVersion fields are the read-time gates that
  * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
@@ -231,15 +240,28 @@ export interface CacheItemResult {
  * positions against one exact tree; resuming it against a different React or a
  * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
  * are committed — an unrecoverable broken serve).
+ *
+ * A `navigationOnly` entry stores NEITHER half: nothing ever serves its HTML
+ * (document serving skips navigationOnly entries at the read gate, and partial
+ * replay consumes only `snapshot`/`docKey`), so the prelude would ride every
+ * store write and read as dead weight at KV-value scale. The capture still runs
+ * the full fizz prerender — it is the completeness arbiter and sanity gate —
+ * but its output is dropped before putShell. hasIntactShellPayload is the
+ * document-half gate; navigationOnly entries never satisfy it.
  */
 export interface ShellCacheEntry {
-    /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
-    prelude: string;
+    /**
+     * Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing).
+     * Absent on `navigationOnly` entries (no document half is stored — see the
+     * interface doc); present on every document-servable entry.
+     */
+    prelude?: string;
     /**
      * JSON.stringify of React's postponed state, or null when the shell settled
-     * with no holes (the DATA variant — served without a fizz resume).
+     * with no holes (the DATA variant — served without a fizz resume). Absent
+     * exactly when `prelude` is (navigationOnly entries).
      */
-    postponed: string | null;
+    postponed?: string | null;
     /** React.version captured at prerender time; the read-time invalidation gate. */
     reactVersion: string;
     /**
@@ -322,6 +344,17 @@ export interface ShellCacheEntry {
     /** Capture-generation start time; tag invalidations at or after it win. */
     createdAt: number;
 }
+/**
+ * A shell entry whose document half is present — what the document HIT path
+ * (serveShellHit / lookupBuildShell) consumes. hasIntactShellPayload
+ * (rsc/shell-serve.ts) is the runtime gate AND the type narrowing to this
+ * shape; navigationOnly entries never pass it (their document half is not
+ * stored).
+ */
+export type DocumentShellCacheEntry = ShellCacheEntry & {
+    prelude: string;
+    postponed: string | null;
+};
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family

package/dist/types/rsc/capture-queue.d.ts

@@ -1,5 +1,20 @@
 /** Bound queued/running capture closures retained by one isolate. */
 export declare const MAX_ADMITTED_CAPTURES: number;
+/** 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 declare function captureQueueDepths(): CaptureQueueDepths;
 /** The caller may drop this best-effort capture and retry on a later request. */
 export declare class CaptureQueueFullError extends Error {
     constructor();
@@ -24,10 +39,11 @@ export declare class CaptureQueueWaitTimeoutError extends Error {
     constructor(waitedMs: number);
 }
 /**
- * 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 declare function enqueueSerializedCapture(task: () => Promise<void>, opts?: {
     maxQueueWaitMs?: number;
+    priority?: "document" | "navigation";
 }): Promise<void>;

package/dist/types/rsc/shell-build-manifest.d.ts

@@ -24,7 +24,7 @@
  *   as the reference instant. No tombstones — the manifest is immutable; the
  *   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 type { SearchParamsFilter } from "../cache/search-params-filter.js";
 /** One baked manifest record (the __ps asset module's default export). */
 export interface BuildShellEntry {
@@ -49,7 +49,7 @@ declare global {
 /** Reset the memoized manifest (unit tests swap the global loader). */
 export declare function resetBuildShellManifestForTests(): void;
 export interface BuildShellHit {
-    entry: ShellCacheEntry;
+    entry: DocumentShellCacheEntry;
     /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
     stale: boolean;
 }

package/dist/types/rsc/shell-capture.d.ts

@@ -125,6 +125,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
@@ -132,7 +136,7 @@ export interface ShellCaptureDebugEvent {
      * - 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" | "skip-capacity" | "skip-queue-timeout" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "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;
     /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
@@ -163,6 +167,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;
 }
 /**
  * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
@@ -322,7 +342,7 @@ type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
  * bag, not a return value: captureAndStoreShell's outcome type stays a string
  * union its existing callers (producer B, tests) consume unchanged.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite">;
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "bakeWaitMs">;
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *

package/dist/types/rsc/shell-serve.d.ts

@@ -17,7 +17,7 @@
  */
 import { type EntryData } from "../server/context.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";
 /** Debug/status header the browser (and e2e assertions) can read: HIT | MISS. */
 export declare const SHELL_STATUS_HEADER = "x-rango-shell";
 /** Partial-navigation status header set only after captured PPR segments are consumed. */
@@ -106,18 +106,24 @@ export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): st
  */
 export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: string): boolean;
 /**
- * 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 declare function hasIntactShellPayload(entry: ShellCacheEntry): boolean;
+export declare function hasIntactShellPayload(entry: ShellCacheEntry): entry is DocumentShellCacheEntry;
 /** Decode a base64 prelude back into bytes for stream composition. */
 export declare function base64ToBytes(b64: string): Uint8Array;
 /** True when the store implements the shell entry family. */

package/dist/vite/index.js

@@ -2530,7 +2530,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.4.3",
+  version: "0.5.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/ppr/SKILL.md

@@ -358,14 +358,27 @@ curl -s -D - -o /dev/null https://app.example.com/products/1 | grep -i x-rango-s
   falls through to KV on a miss, and promotes the KV hit back into that colo.
   WITHOUT a KV namespace its shell family remains inert: every ppr route stays
   `MISS` forever. The store warns once per isolate — bind KV
-  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store.
+  (`new CFCacheStore({ ctx, kv: env.CACHE_KV })`) or use another store. An
+  inert store also stops captures at the gate: the store declares
+  `shellFamilyInert` and the scheduler skips the background render entirely
+  (`skip-inert-store` on the debug event) instead of burning a full capture per
+  MISS whose write could only no-op.
 - Structured capture diagnostics: `createRouter({ debugShellCapture: true })`
   logs one line per capture attempt/skip (outcome, durations, prelude and
   snapshot bytes, backoff state); pass a function to receive each
   `ShellCaptureDebugEvent` instead. `skip-capacity` means the isolate already
   has 32 queued/running captures; the dropped best-effort capture can retry on a
-  later request. In dev, with `debugPerformance` on, the
-  last capture outcome for a key also rides the next document GET's
+  later request. `skip-queue-timeout` means this capture waited 15s behind the
+  active or same-priority work and was dropped before rendering; document-shell
+  captures outrank queued navigation-only snapshots, but never interrupt the
+  active capture — the skip event and the `rango.background` span carry
+  `queuePriority`/`queueAhead` (class and backlog at enqueue) so a parked
+  capture diagnoses itself. A stored attempt reports `bakeWaitMs`: how long the
+  slowest bake source (a top-level pushed handle promise or a bake-lane loader
+  container) held the capture gate — in dev, past 2s, the source is also named
+  once per key in a console warning with the remedies (nest the promise /
+  `cache()` the work / add `loading()`). In dev, with `debugPerformance` on,
+  the last capture outcome for a key also rides the next document GET's
   `Server-Timing` as `ppr-capture;desc="…"`.
 - For deployed Cloudflare tier diagnostics, build with
   `INTERNAL_RANGO_DEBUG=1` and run `wrangler tail`. `[CFCacheStore][shell]`
@@ -621,6 +634,34 @@ capture with identity reads permitted, and the value bakes as a shared
 capture-time copy — mirroring `cache()` semantics (the consumption-lane
 rule; semantic-matrix row PPR3).
 
+### Designing routes for cheap captures (the cost model)
+
+The hole doctrine has a cost corollary that bites silently: **everything that
+bakes is awaited at capture, and that wait recurs on EVERY capture of the
+route**. A top-level pushed handle promise that takes 5s and a Meta promise
+chained 2s further make every capture occupy the per-isolate serialized queue
+for ~7s — while the served response still reads 13ms TTFB, because captures are
+detached. You will not see this cost in any request timing; you see it as slow
+MISS→HIT flips, `skip-queue-timeout` under prefetch pressure, and (in dev, past
+2s) the bake-cost warning naming the source.
+
+Three levers, in preference order:
+
+1. **Nest it** (`{ data: promise }` instead of the promise): the value becomes
+   a hole — per-request, streamed under the consumer's `<Suspense>`, zero
+   capture cost. Choose this whenever the value may be dynamic anyway.
+2. **`cache()` the work inside it**: the value stays baked (shell material,
+   tag-invalidatable), but the capture replays the cached value instead of
+   re-executing the expensive body (mixed-chain). Choose this for shared,
+   expensive-to-compute shell content.
+3. **`loading()` on the entry** (loaders only): moves the loader to the live
+   lane — masked at capture, fresh per serve — at the cost of a fallback in
+   the shell.
+
+Head material (Meta) generally cannot be a hole — the head is shell — so its
+promises bake by design; make them cheap with lever 2. `bakeWaitMs` on the
+capture debug event tells you what each capture actually paid.
+
 ## Execution matrix
 
 | Phase            | MISS (foreground)      | Background capture                                                 | HIT (foreground)                                            |

package/src/cache/cf/cf-cache-store.ts

@@ -267,10 +267,13 @@ interface KVItemEnvelope {
  * @internal
  */
 interface CFShellEnvelope {
-  /** base64-encoded prelude bytes */
-  p: string;
-  /** postponed state JSON, or null (DATA variant — no holes) */
-  po: string | null;
+  /**
+   * base64-encoded prelude bytes. Absent iff `no` (navigationOnly entries
+   * store no document half — ShellCacheEntry.prelude).
+   */
+  p?: string;
+  /** postponed state JSON, or null (DATA variant — no holes). Absent iff `no`. */
+  po?: string | null;
   /** React.version captured at prerender time */
   rv: string;
   /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
@@ -347,8 +350,14 @@ function isShellEnvelope(value: unknown): value is CFShellEnvelope {
   if (value == null || typeof value !== "object") return false;
   const envelope = value as Partial<CFShellEnvelope>;
   return (
-    typeof envelope.p === "string" &&
-    (envelope.po === null || typeof envelope.po === "string") &&
+    // Document half: required unless the envelope is navigationOnly (`no`),
+    // which stores neither field. Tolerate a legacy navigationOnly envelope
+    // that still carries them.
+    (typeof envelope.p === "string" ||
+      (envelope.p === undefined && envelope.no === true)) &&
+    (envelope.po === null ||
+      typeof envelope.po === "string" ||
+      (envelope.po === undefined && envelope.no === true)) &&
     typeof envelope.rv === "string" &&
     (envelope.bv === undefined || typeof envelope.bv === "string") &&
     typeof envelope.c === "number" &&
@@ -400,6 +409,8 @@ interface KVResponseEnvelope {
 
 export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   readonly supportsPassiveShellReads: true = true;
+  /** True when constructed without KV: the shell family no-ops (see ctor). */
+  readonly shellFamilyInert?: boolean;
   readonly defaults?: CacheDefaults;
   readonly keyGenerator?: (
     ctx: RequestContext<TEnv>,
@@ -471,6 +482,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     this.keyGenerator = options.keyGenerator;
     this.waitUntil = (fn) => options.ctx.waitUntil(fn());
     this.kv = options.kv;
+    // The shell family requires KV (getShell/putShell no-op without it — see
+    // warnShellFamilyInertOnce). Declaring it lets scheduleShellCapture skip
+    // captures whose write could only no-op instead of burning a background
+    // render per MISS that still occupies the serialized capture queue.
+    this.shellFamilyInert = options.kv ? undefined : true;
     this.onRevalidateTag = options.onRevalidateTag;
     // tagPurge accepts a ready purge function or a credentials object; the
     // object form is normalized through the built-in zone purge client, which
@@ -2083,8 +2099,11 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
         }
 
         const envelope: CFShellEnvelope = {
-          p: entry.prelude,
-          po: entry.postponed,
+          // Presence-keyed: a navigationOnly entry has no document half, and an
+          // omitted key (vs an explicit undefined) also keeps it out of the
+          // serialized JSON.
+          ...(entry.prelude !== undefined ? { p: entry.prelude } : {}),
+          ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
           rv: entry.reactVersion,
           bv: entry.buildVersion,
           c: entry.createdAt,

package/src/cache/types.ts

@@ -198,6 +198,16 @@ export interface SegmentCacheStore<TEnv = unknown> {
     tags?: string[],
   ): Promise<"stored" | "invalidated" | void>;
 
+  /**
+   * Declares the shell family present-but-inert: getShell/putShell exist but
+   * no-op (CFCacheStore without a KV namespace). scheduleShellCapture skips
+   * captures whose only write target is inert — the background render would be
+   * dead work that still occupies the per-isolate serialized capture queue
+   * (a promise-heavy route bakes for seconds per MISS with nothing stored).
+   * Absent/false means the family, when present, actually stores.
+   */
+  shellFamilyInert?: boolean;
+
   /**
    * Get a cached function result by key.
    * Returns the serialized value, optional handle data, and staleness flag.
@@ -264,8 +274,8 @@ export interface CacheItemResult {
 /**
  * A cached PPR (Partial Pre-rendering) shell entry.
  *
- * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
- * and React's postponed state — because the pair is version- and
+ * A DOCUMENT entry carries BOTH artifacts a resume needs — the rendered HTML
+ * prelude and React's postponed state — because the pair is version- and
  * generation-coupled and must never be mixed across a React upgrade or a build
  * change. The reactVersion and buildVersion fields are the read-time gates that
  * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
@@ -274,15 +284,28 @@ export interface CacheItemResult {
  * positions against one exact tree; resuming it against a different React or a
  * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
  * are committed — an unrecoverable broken serve).
+ *
+ * A `navigationOnly` entry stores NEITHER half: nothing ever serves its HTML
+ * (document serving skips navigationOnly entries at the read gate, and partial
+ * replay consumes only `snapshot`/`docKey`), so the prelude would ride every
+ * store write and read as dead weight at KV-value scale. The capture still runs
+ * the full fizz prerender — it is the completeness arbiter and sanity gate —
+ * but its output is dropped before putShell. hasIntactShellPayload is the
+ * document-half gate; navigationOnly entries never satisfy it.
  */
 export interface ShellCacheEntry {
-  /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
-  prelude: string;
+  /**
+   * Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing).
+   * Absent on `navigationOnly` entries (no document half is stored — see the
+   * interface doc); present on every document-servable entry.
+   */
+  prelude?: string;
   /**
    * JSON.stringify of React's postponed state, or null when the shell settled
-   * with no holes (the DATA variant — served without a fizz resume).
+   * with no holes (the DATA variant — served without a fizz resume). Absent
+   * exactly when `prelude` is (navigationOnly entries).
    */
-  postponed: string | null;
+  postponed?: string | null;
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
   /**
@@ -366,6 +389,18 @@ export interface ShellCacheEntry {
   createdAt: number;
 }
 
+/**
+ * A shell entry whose document half is present — what the document HIT path
+ * (serveShellHit / lookupBuildShell) consumes. hasIntactShellPayload
+ * (rsc/shell-serve.ts) is the runtime gate AND the type narrowing to this
+ * shape; navigationOnly entries never pass it (their document half is not
+ * stored).
+ */
+export type DocumentShellCacheEntry = ShellCacheEntry & {
+  prelude: string;
+  postponed: string | null;
+};
+
 /**
  * The families a shell snapshot pins. The item/segment/response families are
  * cache-store reads/writes (recorded by RecordingShellStore); the loader family

package/src/cache/vercel/vercel-cache-store.ts

@@ -184,10 +184,13 @@ interface VercelResponseEnvelope {
 
 /** Stored envelope for a PPR shell entry (getShell/putShell). */
 interface VercelShellEnvelope {
-  /** base64-encoded prelude bytes. */
-  p: string;
-  /** postponed state JSON, or null (DATA variant). */
-  po: string | null;
+  /**
+   * base64-encoded prelude bytes. Absent iff `no` (navigationOnly entries
+   * store no document half — ShellCacheEntry.prelude).
+   */
+  p?: string;
+  /** postponed state JSON, or null (DATA variant). Absent iff `no`. */
+  po?: string | null;
   /** React.version at capture. */
   rv: string;
   /** Build version at capture (ShellCacheEntry.buildVersion). */
@@ -868,8 +871,11 @@ export class VercelCacheStore<
           ? Math.min(totalTtl, TAG_MARKER_TTL_SECONDS)
           : totalTtl;
       const env: VercelShellEnvelope = {
-        p: entry.prelude,
-        po: entry.postponed,
+        // Presence-keyed: a navigationOnly entry has no document half, and an
+        // omitted key (vs an explicit undefined) also keeps it out of the
+        // serialized JSON.
+        ...(entry.prelude !== undefined ? { p: entry.prelude } : {}),
+        ...(entry.postponed !== undefined ? { po: entry.postponed } : {}),
         rv: entry.reactVersion,
         bv: entry.buildVersion,
         c: entry.createdAt,
@@ -1210,13 +1216,21 @@ export class VercelCacheStore<
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
     const { p, po, rv, bv, c, s, e, t, i, sn, dk, lh, tw, no } = raw;
-    if (typeof p !== "string" || typeof rv !== "string") return null;
-    if (po !== null && typeof po !== "string") return null;
+    if (typeof rv !== "string") return null;
+    // Document half: required unless navigationOnly (`no`), which stores
+    // neither field. Tolerate a legacy navigationOnly envelope that still
+    // carries them.
+    if (p === undefined ? no !== true : typeof p !== "string") return null;
+    if (
+      po === undefined ? no !== true : po !== null && typeof po !== "string"
+    ) {
+      return null;
+    }
     if (typeof c !== "number") return null;
     if (typeof s !== "number" || typeof e !== "number") return null;
     return {
-      p,
-      po: po as string | null,
+      ...(typeof p === "string" ? { p } : {}),
+      ...(po !== undefined ? { po: po as string | null } : {}),
       rv,
       bv: typeof bv === "string" ? bv : undefined,
       c,

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);