@rangojs/router 0.4.1 → 0.4.3

package/dist/types/browser/navigation-client.d.ts

@@ -14,4 +14,4 @@ import type { NavigationClient, RscBrowserDependencies } from "./types.js";
  * @param deps - RSC browser dependencies (createFromFetch)
  * @returns NavigationClient instance
  */
-export declare function createNavigationClient(deps: Pick<RscBrowserDependencies, "createFromFetch">): NavigationClient;
+export declare function createNavigationClient(deps: Pick<RscBrowserDependencies, "createFromFetch" | "createFromReadableStream">): NavigationClient;

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;
 /**
@@ -180,4 +183,13 @@ export declare function setInflightPromise(key: string, promise: Promise<Decoded
  */
 export declare function setInflightPromiseWithAliases(keys: string[], promise: Promise<DecodedPrefetch | null>): void;
 export declare function clearPrefetchInflight(key: string): void;
+/** Whether this document may request stored segment fragment envelopes. */
+export declare function isFragmentPassthroughEnabled(): boolean;
+/**
+ * Disable fragment passthrough for the rest of this document after one stored
+ * fragment fails to decode. The recovery replaces shared cache entries, while
+ * this guard prevents the current tab's HTTP cache from serving its already-
+ * cached corrupt variant again.
+ */
+export declare function disableFragmentPassthrough(): void;
 export declare function clearPrefetchCache(rotateRangoState?: boolean): void;

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

@@ -70,6 +70,8 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      * @internal
      */
     private emitDebug;
+    /** Build-time-gated shell tier trace for deployed cross-colo diagnostics. */
+    private debugShell;
     /**
      * Resolve the cache-key base URL for the current cache operation.
      * Prefers an explicit `baseUrl` option; otherwise derives it from the live
@@ -263,10 +265,10 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
      */
     private warnShellFamilyInertOnce;
     /**
-     * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
-     * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
-     * like kvGetItem, minus the L1 promote. SWR is a plain staleness flag — KV has
-     * no REVALIDATING herd guard, so the capture scheduler's module-level
+     * Get a cached PPR shell entry from Cache API, falling through to KV and
+     * promoting a valid KV hit. Both tiers store one envelope so the prelude,
+     * postponed state, snapshot, versions, and generation metadata cannot mix.
+     * SWR remains a plain staleness flag; the capture scheduler's module-level
      * in-flight set is the recapture stampede guard.
      */
     getShell(key: string): Promise<{
@@ -274,12 +276,21 @@ export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<T
         shouldRevalidate?: boolean;
     } | null>;
     /**
-     * Store a PPR shell entry in KV with TTL and optional SWR window. The write is
-     * registered with waitUntil and awaited so invalidation rejection can be
-     * acknowledged to the capture scheduler. The tags/taggedAt ride in the envelope
-     * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
+     * Store a PPR shell envelope in Cache API and, when its retention meets KV's
+     * 60-second floor, KV. The shared write is registered with waitUntil and
+     * awaited so invalidation rejection can be acknowledged to the capture
+     * scheduler. Short-lived shells remain useful in L1 even though KV rejects
+     * them.
      */
     putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<"stored" | "invalidated" | void>;
+    /** Rebuild the public shell entry from its validated storage envelope. */
+    private shellEnvelopeToEntry;
+    /** Build the Cache API representation of the coupled shell envelope. */
+    private shellEnvelopeResponse;
+    /** KV shell fallback with corruption checks and background L1 promotion. */
+    private kvGetShell;
+    /** Promote a valid KV shell into the per-colo Cache API tier. */
+    private promoteShellToL1;
     /**
      * Convert string key to Request object for CF Cache API.
      * Includes version in URL if specified (for cache invalidation on code changes).

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

@@ -189,8 +189,10 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
      *   per-request memo is consulted (synchronously, no KV read), so a request
      *   that ran `updateTag()` still masks its own not-yet-purged entries
      *   (read-your-own-writes).
-     * - The KV tier and PPR shells still use the KV markers — those are written
-     *   regardless, and purge cannot reach KV — so keep `kv` configured for L2.
+     * - The KV tier and PPR shell reads still use the KV markers. Runtime shell
+     *   L1 entries are purgeable, but their taggedAt is the capture-start time: a
+     *   capture can finish after an invalidation purge, so eviction alone cannot
+     *   reject that older generation. Keep `kv` configured for shell L2 + markers.
      *   Without `kv`, purge mode is the ONLY tag invalidation and the store is
      *   L1-only: a supported configuration (previously tag invalidation without
      *   KV had no read-side effect at all). One KV-less caveat: an entry whose

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/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

@@ -4,9 +4,30 @@ export declare const MAX_ADMITTED_CAPTURES: number;
 export declare class CaptureQueueFullError extends Error {
     constructor();
 }
+/**
+ * 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 every previously enqueued capture has 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;
+}): Promise<void>;

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

@@ -125,10 +125,14 @@ 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-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-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 +161,8 @@ 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;
 }
 /**
  * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
@@ -304,8 +310,9 @@ export declare function scheduleShellCapture(ctx: HandlerContext<any>, request:
  *   I/O failure is reported separately and does NOT make the attempt retryable —
  *   the capture itself worked).
  * - `redirect`: the matched route redirects, so there is no shell to capture.
- * - `no-shell`: the prelude came back trivial (no <body>) OR captureShellHTML
- *   rejected with our own abort. This is the only RETRYABLE outcome.
+ * - `no-shell`: captureShellHTML returned null because the prelude was unusable
+ *   or its private capture abort landed before the shell completed. This is the
+ *   only RETRYABLE outcome.
  */
 type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 /**
@@ -327,9 +334,9 @@ type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "write
  * when we froze the shell; the attempt itself warmed the module graph, so a second
  * attempt a short beat later usually completes the shell in the SAME background
  * task. That kills the old multi-request warmup where the caller had to re-issue
- * several HTTP requests before a capture stuck. We retry ONLY on `no-shell` (and a
- * defensively-caught abort); a genuine render error is NOT retried — it propagates
- * to scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`; a
+ * genuine render error is NOT retried — it propagates to scheduleShellCapture's
+ * reportCacheError. See docs/design/ppr-shell-resume.md.
  *
  * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
  * drive the retry without a real 400ms wall-clock wait.
@@ -369,9 +376,10 @@ export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, d
  * capture worked; only the store I/O failed). `ssrModule.captureShellHTML` MUST be
  * present (eligibility is checked before scheduling).
  *
- * A `no-shell` result (trivial prelude, or a defensively-caught abort) is the only
- * retryable outcome; a genuine (non-abort) captureShellHTML error propagates so it
- * reaches reportCacheError and is NOT retried.
+ * A `no-shell` result from captureShellHTML is the only retryable outcome. Every
+ * captureShellHTML error propagates to reportCacheError and is NOT retried. The
+ * capture handler converts only its own private abort sentinel to null before this
+ * layer sees it.
  */
 declare function captureAndStoreShell(ssrModule: SSRModule, rscStream: ReadableStream<Uint8Array>, handleStore: HandleStore, reqCtx: RequestContext<any>, capture: ShellCaptureDescriptor, stats?: CaptureAttemptStats, captureStartedAt?: number): Promise<Exclude<CaptureAttemptOutcome, "redirect">>;
 export { runShellCapture, captureAndStoreShell, delay, SHELL_CAPTURE_RETRY_DELAY_MS, };

package/dist/types/rsc/stream-idle.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Stream-idle timeout — the enforcement for `timeouts.streamIdleMs` (the
+ * "stream-idle" TimeoutPhase, reserved since the timeout API landed).
+ *
+ * WHY: nothing else bounds a streaming response body's lifetime.
+ * `renderStartMs` only bounds time-to-Response-construction; once the body is
+ * streaming, a single never-settling promise embedded in the payload (a
+ * deferred loader that never resolves, an orphaned ctx.rendered() barrier)
+ * holds the Flight/HTML stream — and the client's connection — open forever.
+ * Deferred HANDLES have a 10s auto-resolve net (defer.ts); loader promises
+ * and everything else have none. Field-observed as multi-second dead
+ * connections only closed by client cancellation.
+ *
+ * SEMANTICS — end-to-end idle flow, deliberately: the watchdog re-arms on
+ * every chunk that flows THROUGH to the client, so "idle" means "no bytes
+ * reached the wire for N ms". A stalled slow client counts as idle the same
+ * as a wedged producer — the two are indistinguishable here without buffering,
+ * and buffering is banned on the streaming path. Pick budgets accordingly
+ * (generous, seconds not millis); the feature is OPT-IN (unset = today's
+ * unbounded behavior, and the `timeout` shorthand deliberately does not apply
+ * to streamIdleMs — see resolveTimeouts).
+ *
+ * ON TRIP: the client-facing stream is errored with a RouterTimeoutError
+ * ("stream-idle") — the host terminates the response visibly (truncated
+ * chunked encoding), which is debuggable, unlike a silent clean close that
+ * would present a half-document as complete. Erroring the transform makes the
+ * pipe cancel its SOURCE, which aborts React's fizz/flight render — but only
+ * when the watchdog's branch is the sole consumer. When an upstream layer
+ * teed or cloned the body first (the document-cache MISS drain,
+ * response-cache clones), the watchdog holds one tee branch: tee semantics
+ * cancel the underlying source only once EVERY branch cancels, so the cache
+ * branch keeps the wedged render alive, bounded only by the platform's
+ * waitUntil budget — exactly as it was before this feature. The client-facing
+ * bound is unconditional; source teardown is best-effort. `onTimeout` does
+ * NOT apply: the response already left the handler, so no replacement
+ * Response can be served — the trip is reported via onError + the
+ * request.timeout telemetry event instead.
+ *
+ * COST: one identity TransformStream hop per chunk, only when the timeout is
+ * enabled. Never buffers, never reads ahead, adds no work when disabled.
+ */
+import { RouterTimeoutError } from "../router/timeout.js";
+/** What the watchdog observed when it tripped. */
+export interface StreamIdleTrip {
+    /** ms since the watchdog armed (response handoff) — the stream's lifetime. */
+    totalMs: number;
+    /** Chunks forwarded before the trip. */
+    chunks: number;
+    /** The error the client-facing stream was terminated with. */
+    error: RouterTimeoutError;
+}
+/**
+ * Wrap `response`'s body in an idle watchdog. Returns a NEW Response with the
+ * same status/headers whose body errors (and cancels the source) once no chunk
+ * has flowed for `idleMs`. Callers gate on isTimeoutEnabled + body presence +
+ * NOT a websocket upgrade (a 101/webSocket response must never be
+ * reconstructed); this function assumes those checks were made. `onTrip` fires
+ * at most once, after the client-facing stream has been errored.
+ */
+export declare function applyStreamIdleTimeout(response: Response, idleMs: number, onTrip: (trip: StreamIdleTrip) => void): Response;

package/dist/types/segment-fragments.d.ts

@@ -6,10 +6,11 @@
  * fragment STRINGS ride the outgoing payload verbatim inside these envelopes
  * — the outer Flight render copies a string instead of re-serializing a whole
  * element tree — and the CONSUMER expands each envelope through its own Flight
- * deserializer: the SSR resume pass (ssr/ssr-root.tsx) and browser hydration
- * (browser/rsc-router.tsx). Each fragment is its own row space, decoded
- * independently, exactly like the segment codec's per-record decode — so
- * there is no Flight row-id collision or shared-row dedupe hazard.
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx), browser hydration, and
+ * capability-gated partial navigation/prefetch decoders. Each fragment is its
+ * own row space, decoded independently, exactly like the segment codec's
+ * per-record decode — so there is no Flight row-id collision or shared-row
+ * dedupe hazard.
  *
  * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
  * loading). A plain object is never a valid ReactNode, so the marker cannot
@@ -20,6 +21,15 @@
  * it must stay dependency-free: no plugin-rsc, no request-context.
  */
 import type { ResolvedSegment } from "./types.js";
+/** Partial-request capability gate for browser-side fragment expansion. */
+export declare const SEGMENT_FRAGMENT_CAPABILITY_HEADER: string;
+/** One-shot request marker that forces server-side fragment validation. */
+export declare const SEGMENT_FRAGMENT_RECOVERY_HEADER: string;
+/** A stored fragment failed in its consumer-side Flight decoder. */
+export declare class SegmentFragmentDecodeError extends Error {
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
 /**
  * One RSC-encoded fragment traveling inside an RscPayload segment field.
  * `f` is the stored Flight document (segment-codec output) for that field.
@@ -49,6 +59,19 @@ export type FragmentDecoder = (stream: ReadableStream<Uint8Array>) => Promise<un
  * the same posture as a parseable-but-mismatched postponed blob.
  */
 export declare function expandSegmentFragments(segments: ResolvedSegment[] | undefined, decode: FragmentDecoder): Promise<void>;
+/**
+ * Expand every envelope in an RscPayload-shaped object, in place. Decode
+ * failures use a distinct error so partial navigation can retry once through
+ * the server's decode-and-evict path. The
+ * hasSegmentFragments pre-scan keeps envelope-free payloads — every
+ * non-replay response — to one synchronous field walk; this runs on every
+ * navigation and prefetch decode.
+ */
+export declare function expandPayloadFragments(payload: {
+    metadata?: {
+        segments?: ResolvedSegment[];
+    };
+}, decode: FragmentDecoder): Promise<void>;
 /**
  * True when any segment carries an unexpanded envelope. Cheap scan used by
  * consumers that only need to know whether an expansion pass is required.