@rangojs/router 0.4.2 → 0.5.0

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

@@ -10,12 +10,12 @@
  * scopes are in play:
  * - Wildcard (default): built by `buildPrefetchKey(rangoState, target)` —
  *   shape `rangoState\0/target?...`. Shared across all source pages and
- *   invalidated automatically when Rango state bumps (deploy or
- *   server-action invalidation).
+ *   source segment trees; `_rsc_segments` is omitted from this key. Invalidated
+ *   automatically when Rango state bumps (deploy or server-action invalidation).
  * - Source-scoped: built by `buildSourceKey(rangoState, sourceHref, target)`
  *   — shape `rangoState\0sourceHref\0/target?...`. Embeds the Rango state
- *   (so rotation invalidates source-scoped entries too) plus the source
- *   href (so each originating page gets its own slot). Populated when the
+ *   (so rotation invalidates source-scoped entries too), the source href, and
+ *   the exact source segment tree. Populated when the
  *   server tags a response with `X-RSC-Prefetch-Scope: source` (intercept
  *   modals etc.), OR when a Link opts in with `prefetchKey=":source"` — in
  *   both cases so source-sensitive responses cannot bleed into navigations
@@ -91,7 +91,9 @@ export declare function isPrefetchCacheDisabled(): boolean;
  * - Wildcard (source-agnostic): prefix is the Rango state value from
  *   `getRangoState()`. Shared across all source pages. Invalidated
  *   automatically when Rango state bumps (deploy or server-action).
- *   Key shape: `rangoState\0/target?...`.
+ *   `_rsc_segments` is omitted so sibling payloads prefetched from one page
+ *   remain reusable after another prefetched navigation commits. Key shape:
+ *   `rangoState\0/target?...`.
  * - Source-scoped: use `buildSourceKey()`. Key shape:
  *   `rangoState\0sourceHref\0/target?...` — embeds the Rango state so
  *   rotation invalidates source-scoped entries alongside wildcard ones,
@@ -100,9 +102,10 @@ export declare function isPrefetchCacheDisabled(): boolean;
  *   `X-RSC-Prefetch-Scope: source` (intercept modals, etc.) or when a
  *   Link opts in via `prefetchKey=":source"`.
  *
- * The `_rsc_segments` query param that travels in the target URL means
- * clients with different mounted segment trees naturally get different
- * keys — so segment-level diffs remain consistent across both scopes.
+ * Source-scoped keys retain `_rsc_segments` because their exact source tree is
+ * part of the opt-in contract. Wildcard responses are source-agnostic by
+ * contract; callers use source scope when a custom revalidation decision makes
+ * the response depend on the current URL or segment tree.
  */
 export declare function buildPrefetchKey(prefix: string, targetUrl: URL): string;
 /**

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/read-through-swr.d.ts

@@ -25,13 +25,14 @@ export interface ReadThroughItemConfig<T> {
     /** Execute the underlying function/loader on miss or revalidation */
     execute: () => Promise<T>;
     /**
-     * Optional wrapper applied to execute() ONLY on the background
-     * stale-revalidation path (not the foreground miss, where the caller's context
-     * is already established). Used to re-establish the request-context ALS, which
-     * a detached waitUntil task loses on workerd. Defaults to calling execute()
-     * directly.
+     * Optional wrapper applied to the WHOLE background stale-revalidation task
+     * (execute + serialize + setItem) — not the foreground miss, where the
+     * caller's context is already established. Used to re-establish the
+     * request-context ALS, which a detached waitUntil task loses on workerd,
+     * and to open the rango.background span so the write is covered too.
+     * Defaults to running the task directly.
      */
-    wrapBackground?: (run: () => Promise<T>) => Promise<T>;
+    wrapBackground?: (run: () => Promise<void>) => Promise<void>;
     /** Serialize result for storage. Return null to skip caching. */
     serialize: (data: T) => Promise<string | null>;
     /** Deserialize cached value back to the original type */

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/cloudflare/tracing.d.ts

@@ -1,10 +1,11 @@
 /**
  * Cloudflare custom-spans integration.
  *
- * Bridges the router's performance phases (request, middleware, action,
- * loaders, handler, render, ssr) onto Cloudflare Workers custom spans so they show
- * up in the trace waterfall and OpenTelemetry exports next to the platform's
- * automatic spans (KV reads, D1 queries, fetch calls), with correct nesting.
+ * Bridges the router's observable phases (request, middleware, action, loaders,
+ * handler, render, ssr, response, background) onto Cloudflare Workers custom
+ * spans so they show up in the trace waterfall and OpenTelemetry exports next
+ * to the platform's automatic spans (KV reads, D1 queries, fetch calls), with
+ * correct nesting.
  *
  * Usage (Cloudflare preset only):
  *
@@ -27,12 +28,15 @@
  *
  * Span duration note: enterSpan ends a span when its callback's returned value
  * (or promise) settles. For the streaming phases (request/render/ssr) that is at
- * stream CONSTRUCTION, not body-drain. Instrumentation is best-effort and never
- * wraps or buffers the response body, so it cannot regress streaming or latency.
- * A loader/Suspense child that resolves mid-stream therefore keeps a rango.loader
- * span that can extend past its render parent — overlapping spans are valid. Uses
- * only the typed enterSpan API; spans bound work up to stream-handoff, matching
- * the co-emitted perf metric.
+ * stream CONSTRUCTION, not body-drain; rango.response marks that handoff
+ * boundary explicitly (it wraps only response finalization, never the body).
+ * Instrumentation is best-effort and never wraps or buffers the response body,
+ * so it cannot regress streaming or latency. A loader/Suspense child that
+ * resolves mid-stream therefore keeps a rango.loader span that can extend past
+ * its render parent — overlapping spans are valid. Uses only the typed enterSpan
+ * API; spans bound work up to stream-handoff, matching the co-emitted perf
+ * metric. On deployed Workers a rango.response span may report 0 ms (non-I/O
+ * timers are frozen); its position and attributes are the value.
  */
 import { type RouterTracingConfig, type TracingToggleOptions } from "../router/tracing.js";
 /**
@@ -44,8 +48,8 @@ export type CloudflareTracingOptions = TracingToggleOptions;
 /**
  * Create the tracing config for a Cloudflare router. Pass the result to
  * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
- * action, loaders, handler, render, and ssr phases; pass `spans` to turn
- * individual phases off.
+ * action, loaders, handler, render, ssr, response, and background phases; pass
+ * `spans` to turn individual phases off.
  *
  * @see createOTelTracing (`@rangojs/router`) for the same slot on any platform
  *   with an OpenTelemetry SDK.

package/dist/types/router/instrument.d.ts

@@ -5,13 +5,11 @@
  * The router exposes the same work on three surfaces, and the rule is: each
  * surface has exactly one owner here, so they cannot drift.
  *
- *   - observePhase(): a span of work. Co-emits the `debugPerformance` perf
- *     metric (metrics store -> [RSC Perf] timeline + Server-Timing) AND the
- *     platform span (tracing runner -> Cloudflare custom spans / OTel). From one
- *     wrap site, so the span set is always a subset of the perf phases and the
- *     two can't disagree. Phases that meter their own perf metric with a finer
- *     decomposition (request, middleware) pass `metric: false` and get the span
- *     only — still co-located, still one owner per surface.
+ *   - observePhase(): a span of work. From one wrap site, emits the platform
+ *     span (tracing runner -> Cloudflare custom spans / OTel) and, when the
+ *     phase has one, its `debugPerformance` metric (metrics store -> [RSC Perf]
+ *     timeline + Server-Timing). Phases that meter their own perf metric with a
+ *     finer decomposition, or are deliberately span-only, pass `metric: false`.
  *   - observeEvent(): a discrete fact (TelemetrySink): cache decisions,
  *     revalidation decisions, handler errors, timeouts, origin rejections.
  *     Event-shaped, not phase-shaped — derived from the same call sites but a
@@ -59,6 +57,11 @@ export interface PhaseSpec {
      */
     lazyAttributes?: () => Record<string, string | number | boolean> | undefined;
 }
+/**
+ * The detached background lanes wrapped by the rango.background span (the
+ * `rango.background.kind` attribute). One name per task execution boundary.
+ */
+export type BackgroundTaskKind = "shell-capture" | "document-revalidation" | "loader-revalidation" | "use-cache-revalidation";
 /**
  * The router's observable phases. One definition per phase keeps the `rango.*`
  * span names, perf-metric labels, and identifying attributes from spreading
@@ -99,6 +102,32 @@ export declare const PHASES: {
     /** SSR HTML render from the RSC stream. Colon-delimited like the other ssr:*
      * setup metrics (ssr:module-load / ssr:stream-mode). */
     readonly ssr: PhaseSpec;
+    /**
+     * One detached background task (waitUntil work that outlives the response):
+     * a PPR shell capture or an SWR background revalidation. The wrapper is the
+     * explanatory parent for everything the task does — the platform's automatic
+     * KV/fetch/cache spans, and (for the revalidation lanes) the re-run's own
+     * rango.* phase spans — so post-handoff work never appears as orphan spans
+     * dangling under an ended foreground phase. `kind` identifies the lane.
+     * Span only (metric:false): the perf timeline is finalized with the
+     * response, so a background metric could never reach it. The shell-capture
+     * lane keeps its INNER phase spans suppressed (derived context strips
+     * _tracing — a capture re-render duplicating the foreground's span set was
+     * the original #670 leak); the revalidation lanes keep theirs, nested here.
+     */
+    readonly background: (kind: BackgroundTaskKind) => PhaseSpec;
+    /** Final response construction + host handoff: opened AFTER downstream
+     * middleware/core execution returns a Response, wrapping only finalization
+     * (redirect interception/guarding, Server-Timing mutation, final response
+     * selection) and ending immediately before the router handler returns the
+     * response to the host. Handoff-bound, never drain-bound — it must never
+     * read, tee, buffer, or await response.body, so it cannot regress streaming.
+     * At most one per traced request; absent when the request throws before a
+     * response exists. Span only (metric:false) — a co-emitted metric would
+     * circularly mutate the Server-Timing header this phase itself finalizes.
+     * On Cloudflare it may report 0 ms (non-I/O timers are frozen); its position
+     * and attributes (status/mode/body kind, set by the handler) are the value. */
+    readonly response: PhaseSpec;
 };
 /**
  * Instrument one unit of work: open its span AND (unless `metric: false`) record
@@ -108,14 +137,15 @@ export declare const PHASES: {
  * returns a promise both the metric duration and the span end when it settles.
  *
  * This is the ONLY phase primitive: every phase (request/middleware/action/
- * loader/handler/render/ssr) is construction-bound — the span and metric settle
- * when fn's own work completes (for the streaming phases, when the RSC/HTML
- * stream is constructed, NOT when the body drains). Instrumentation is strictly
- * best-effort: it never wraps or buffers the response and adds no work on the
- * streaming path, so it cannot regress response latency or streaming. A loader
- * that resolves while the body streams therefore keeps a rango.loader span that
- * may extend past its render parent — overlapping spans are valid; the loader
- * really did take that long.
+ * loader/handler/render/ssr/response/background) settles when fn's own work
+ * completes. For streaming phases that means when the RSC/HTML stream is
+ * constructed, NOT when the body drains; for response, when finalization hands
+ * the stream to the host. Instrumentation is strictly best-effort: it never
+ * wraps or buffers the response and adds no work on the streaming path, so it
+ * cannot regress response latency or streaming. A loader that resolves while
+ * the body streams therefore keeps a rango.loader span that may extend past its
+ * render parent — overlapping spans are valid; the loader really did take that
+ * long.
  *
  * Reads the metrics store + tracing off the RequestContext ALS, which is active
  * for the WHOLE request — contrast observeEvent, which reads the RouterContext

package/dist/types/router/telemetry-otel.d.ts

@@ -6,10 +6,10 @@
  *   - createOTelTracing(tracer): the OTel adapter for the `tracing` SLOT — the
  *     canonical phase-span layer. It bridges observePhase's callback boundary
  *     onto OTel's callback-bound `startActiveSpan`, so the router's phase spans
- *     (rango.request/middleware/loader/render/ssr) nest by async context and the
- *     loader's own OTel spans (db/fetch) land under rango.loader. This is the
- *     OTel equivalent of createCloudflareTracing — pass it to
- *     `createRouter({ tracing })`.
+ *     (rango.request/middleware/action/loader/handler/render/ssr/response/
+ *     background) nest by async context and the loader's own OTel spans
+ *     (db/fetch) land under rango.loader. This is the OTel equivalent of
+ *     createCloudflareTracing — pass it to `createRouter({ tracing })`.
  *
  *   - createOTelSink(tracer): the OTel adapter for the `telemetry` SLOT — a
  *     TelemetrySink for the EVENT-shaped facts (handler errors, cache decisions,

package/dist/types/router/timeout.d.ts

@@ -10,7 +10,18 @@ export interface RouterTimeouts {
     actionMs?: number;
     /** Timeout for initial render/response production (ms). */
     renderStartMs?: number;
-    /** Timeout for idle streaming after render starts (ms). Reserved for PR 2. */
+    /**
+     * Timeout for idle streaming after the response is handed off (ms): when no
+     * chunk flows to the client for this long, the body stream is errored with a
+     * RouterTimeoutError ("stream-idle") and the source render is canceled —
+     * bounding hangs from never-settling promises embedded in the payload.
+     * END-TO-END semantics: a stalled slow client counts as idle the same as a
+     * wedged producer, so pick generous budgets (seconds). Opt-in (unset =
+     * unbounded, and the `timeout` shorthand deliberately does not apply);
+     * onTimeout does NOT fire — no replacement Response can be served
+     * mid-stream — the trip reports via onError + the request.timeout event.
+     * Enforcement: rsc/stream-idle.ts, wired at the handler's response tail.
+     */
     streamIdleMs?: number;
 }
 export type TimeoutPhase = "action" | "render-start" | "stream-idle";

package/dist/types/router/tracing.d.ts

@@ -1,11 +1,12 @@
 /**
  * Span tracing hook (platform-agnostic).
  *
- * The core router emits its existing performance phases (request, middleware, action,
- * loaders, render, ssr) as spans by calling traceSpan() at a small set of
- * execution boundaries. When no tracing is configured the call is a direct
- * pass-through: fn is invoked with a no-op span, with no wrapper and no
- * allocation, so a non-traced request behaves exactly as before.
+ * The core router emits its observable phases (request, middleware, action,
+ * loaders, handler, render, ssr, response, background) as spans by calling
+ * traceSpan() at a small set of execution boundaries. When no tracing is
+ * configured the call is a direct pass-through: fn is invoked with a no-op
+ * span, with no wrapper and no allocation, so a non-traced request behaves
+ * exactly as before.
  *
  * A platform integration supplies a SpanRunner that wraps fn in a real span.
  * Two runners ship: the Cloudflare one (createCloudflareTracing in
@@ -29,7 +30,10 @@
  * useLoader, plus the fetchable path), rango.handler (span-only, one per segment
  * route/layout handler execution; the handler:<id> perf metric is owned by the
  * track() at the call site), rango.render (render:total:<route>; normal AND
- * action-revalidation renders), rango.ssr (ssr:render-html).
+ * action-revalidation renders), rango.ssr (ssr:render-html), rango.response
+ * (span-only; final response construction + host handoff — the explicit
+ * stream-handoff marker), and rango.background (span-only; detached work, see
+ * below).
  *
  * Span-duration caveat (best-effort, never buffers): a span ends when its
  * callback's value (or promise) settles. For the streaming phases (request,
@@ -40,6 +44,19 @@
  * rango.loader span that can extend past its render parent; overlapping spans are
  * valid (the loader really did take that long). Phase spans bound the work up to
  * stream-handoff, which is also what the co-emitted perf metric measures.
+ * rango.response makes that handoff boundary explicit: it wraps only response
+ * finalization (redirect interception/guarding, Server-Timing mutation, final
+ * response selection) after downstream execution returns, ending immediately
+ * before the handler returns the Response to the host. It is handoff-bound,
+ * never drain-bound — it never reads, tees, or awaits response.body, and it is
+ * absent when the request throws before a response exists.
+ *
+ * rango.background wraps DETACHED work (waitUntil tasks that outlive the
+ * response): PPR shell captures and SWR background revalidations. It is the
+ * explanatory parent for spans those tasks produce after the foreground
+ * phases ended — without it, post-handoff work reads as orphan spans dangling
+ * under an ended parent. See PHASES.background (instrument.ts) for the lane
+ * kinds and per-lane inner-span policy.
  *
  * Both shipped runners (Cloudflare, OTel) keep the core agnostic: the
  * platform-specific bridge lives at the edge behind the SpanRunner contract.
@@ -58,17 +75,14 @@ export interface TraceSpan {
  */
 export type SpanRunner = <T>(name: string, fn: (span: TraceSpan) => T) => T;
 /** The router phases that can be wrapped in a span. */
-export type TracePhase = "request" | "middleware" | "action" | "loader" | "handler" | "render" | "ssr";
-/** Per-phase span toggles. Omitted phases default to enabled. */
-export interface TracePhaseToggles {
-    request?: boolean;
-    middleware?: boolean;
-    action?: boolean;
-    loader?: boolean;
-    handler?: boolean;
-    render?: boolean;
-    ssr?: boolean;
-}
+export type TracePhase = "request" | "middleware" | "action" | "loader" | "handler" | "render" | "ssr" | "response" | "background";
+/**
+ * Per-phase span toggles. Omitted phases default to enabled. Derived from
+ * TracePhase so a new phase cannot be silently missing here — the other phase
+ * lists in this file (ALL_PHASES_ON, resolveTracing) are exhaustiveness-checked
+ * by their Record<TracePhase, boolean> annotations.
+ */
+export type TracePhaseToggles = Partial<Record<TracePhase, boolean>>;
 /**
  * The option pair shared by every tracing factory (enabled master switch +
  * per-phase span toggles). Extended by OTelTracingOptions,

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

@@ -1,12 +1,49 @@
 /** 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();
 }
 /**
- * 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).
+ * Budget on how long a capture may WAIT in the queue before it is dropped
+ * instead of run. On workerd a queued capture rides the scheduling request's
+ * waitUntil, whose post-response lifetime is bounded (~30s): a capture that
+ * already burned 15s+ parked behind a slow predecessor would start its own
+ * up-to-15s attempt (captureTimeout) with no budget left and risk being
+ * killed mid-store-write. Dropping at the budget is safe — captures are
+ * best-effort by contract, and a later request re-probes the key (the drop
+ * does NOT mark backoff: the route is not doomed, the isolate was busy).
+ * Matches one attempt's SHELL_CAPTURE_MAX_WAIT_MS so wait + attempt fits the
+ * platform budget. Field-observed: a navigation-shell capture parked ~24s
+ * behind a predecessor's two-attempt cycle.
+ */
+export declare const CAPTURE_QUEUE_WAIT_BUDGET_MS: number;
+/** Thrown (async) when the queue wait exceeded the budget; the task never ran. */
+export declare class CaptureQueueWaitTimeoutError extends Error {
+    readonly waitedMs: number;
+    constructor(waitedMs: number);
+}
+/**
+ * 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>): Promise<void>;
+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,10 +125,18 @@ export interface ShellCaptureDebugEvent {
      * - skip-backoff: the key is inside its refused-capture backoff window and
      *   the capture was not attempted
      * - skip-capacity: the isolate capture queue is full; a later request may retry
+     * - skip-inert-store: the resolved store's shell family is missing or
+     *   declared inert (SegmentCacheStore.shellFamilyInert — a CFCacheStore
+     *   without a KV namespace); nothing could store the result, so the
+     *   background render was not scheduled at all
+     * - skip-queue-timeout: the capture waited past CAPTURE_QUEUE_WAIT_BUDGET_MS
+     *   behind other captures and was dropped unrun (no backoff — the route is
+     *   not doomed, the isolate was busy; a later request re-probes). Carries
+     *   queueWaitMs.
      * - backoff: the key entered (or escalated) backoff after a terminal
      *   no-shell — carries the new backoff state
      */
-    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "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). */
@@ -157,6 +165,24 @@ export interface ShellCaptureDebugEvent {
     backoffFailures?: number;
     /** Ms remaining in the key's backoff window, when one exists. */
     backoffRemainingMs?: number;
+    /** Ms the capture waited in the serialized queue (skip-queue-timeout). */
+    queueWaitMs?: number;
+    /** Queue priority class at enqueue: document outranks queued navigation. */
+    queuePriority?: "document" | "navigation";
+    /**
+     * Captures ahead at enqueue: the active one plus every waiting capture of
+     * same-or-higher priority. 0 = this capture starts immediately.
+     */
+    queueAhead?: number;
+    /**
+     * Ms the capture gate was HELD waiting for the slowest bake source — a
+     * top-level pushed handle promise or a bake-lane loader container — to
+     * settle, measured from capture start. Bake time is by-design shell latency
+     * (the hole doctrine: top-level promises bake), but it recurs on EVERY
+     * capture of the route and occupies the serialized queue; this field makes
+     * it attributable. Absent when nothing held the gate.
+     */
+    bakeWaitMs?: number;
 }
 /**
  * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
@@ -316,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. */