@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.1

package/dist/types/rsc/response-route-handler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Response Route Handler
+ *
+ * Handles response routes (JSON, text, HTML, XML, markdown, image, stream)
+ * that bypass the RSC rendering pipeline entirely. Includes content-type
+ * dispatch, route middleware execution, and response caching with SWR.
+ */
+import type { MiddlewareFn } from "../router/middleware.js";
+import type { EntryData } from "../server/context.js";
+import type { HandlerContext } from "./handler-context.js";
+export interface ResponseRouteMatch {
+    responseType: string;
+    handler: Function;
+    params?: Record<string, string>;
+    negotiated?: boolean;
+    manifestEntry?: EntryData;
+    routeMiddleware?: Array<{
+        handler: MiddlewareFn;
+        params: Record<string, string>;
+    }>;
+}
+/**
+ * Handle a response route (non-RSC). Dispatches by content type, wraps
+ * with route middleware and response caching when configured.
+ *
+ * For partial (client-side navigation) requests, returns X-RSC-Reload
+ * so the browser triggers a hard navigation to the response route URL.
+ */
+export declare function handleResponseRoute<TEnv>(handlerCtx: HandlerContext<TEnv>, preview: ResponseRouteMatch, request: Request, env: TEnv, url: URL, variables: Record<string, any>): Promise<Response>;

package/dist/types/rsc/rsc-rendering.d.ts

@@ -0,0 +1,18 @@
+/**
+ * RSC Rendering Handler (Navigation)
+ *
+ * Handles RSC rendering for both partial (client-side navigation) and full
+ * (initial page load) requests. Includes prerender collection for build-time
+ * static generation.
+ */
+import { getRequestContext } from "../server/request-context.js";
+import type { HandlerContext } from "./handler-context.js";
+export declare function handleRscRendering<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, isPartial: boolean, handleStore: ReturnType<typeof getRequestContext>["_handleStore"], nonce: string | undefined): Promise<Response>;
+/**
+ * Neutralize the shell-HIT degradation redirect target. The inline
+ * `location.replace` in a committed 200 body bypasses the 3xx chokepoint
+ * (guardOutgoingRedirect only sees 3xx + Location), so this reuses the same
+ * same-origin resolver directly: unsafe targets neutralize to the
+ * redirect-guard.ts landing instead of navigating the user off-host.
+ */
+export declare function resolveShellHitRedirectTarget(rawTarget: string, requestOrigin: string, basename: string | undefined): string;

package/dist/types/rsc/runtime-warnings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime guardrail warnings (dev-only).
+ *
+ * W3: PE action redirect / Response handling.
+ */
+/**
+ * Extract a redirect Response from a thrown or returned value.
+ * Returns a redirect Response to send to the client, or null if the value
+ * is not a redirect Response.
+ */
+export declare function extractRedirectResponse(value: unknown): Response | null;
+/**
+ * Warn when a non-redirect Response is returned from an action during PE.
+ */
+export declare function warnNonRedirectPeResponse(): void;
+/**
+ * Warn when a non-redirect Response is returned (not thrown) from an action
+ * on the JS (fetch) path. A raw Response cannot be serialized into Flight, so
+ * it is discarded — mirroring the PE path. Use `throw redirect('/path')` for
+ * redirects.
+ */
+export declare function warnNonRedirectActionResponse(actionId: string): void;

package/dist/types/rsc/server-action.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Server Action Handler
+ *
+ * Handles server action execution and post-action revalidation as two
+ * separate phases:
+ *
+ * 1. executeServerAction — decodes args, runs the action, handles redirects
+ *    and error boundaries. Returns either a final Response (redirect/error)
+ *    or an ActionContinuation for the revalidation phase.
+ *
+ * 2. revalidateAfterAction — takes the continuation, matches affected
+ *    segments, builds the RSC payload, and returns the Flight response.
+ *
+ * The handler (handler.ts) runs the action BEFORE route middleware, then
+ * wraps revalidation inside route middleware — identical to a normal render.
+ */
+import { getRequestContext } from "../server/request-context.js";
+import type { HandlerContext } from "./handler-context.js";
+import type { MatchResult } from "../types.js";
+/**
+ * Data flowing from action execution to the revalidation phase.
+ * When the action completes without redirect, the handler passes this to route
+ * middleware → revalidateAfterAction.
+ *
+ * `errorBoundary` carries the matched error-boundary result when the action
+ * threw and a boundary matched. The error-boundary render is then performed in
+ * the revalidation phase so it runs INSIDE the same route-middleware wrapper as
+ * a successful revalidation — route middleware (context vars, headers, cookies)
+ * must apply to the error render too, matching the module doc's "identical to a
+ * normal render". When `errorBoundary` is set, `actionContext` is unused (the
+ * boundary is already matched; no matchPartial is run).
+ */
+export interface ActionContinuation {
+    returnValue: {
+        ok: boolean;
+        data: unknown;
+    };
+    actionStatus: number;
+    temporaryReferences: ReturnType<HandlerContext["createTemporaryReferenceSet"]>;
+    actionContext: {
+        actionId: string;
+        actionUrl: URL;
+        actionResult: unknown;
+        formData?: FormData;
+    };
+    errorBoundary?: MatchResult;
+}
+/**
+ * Phase 1: Execute the server action.
+ *
+ * Decodes arguments, runs the action, handles redirects and error
+ * boundaries. Returns a final Response (redirect, error boundary render)
+ * or an ActionContinuation for the revalidation phase.
+ */
+export declare function executeServerAction<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, actionId: string, handleStore: ReturnType<typeof getRequestContext>["_handleStore"]): Promise<Response | ActionContinuation>;
+/**
+ * Phase 2: Revalidate after action.
+ *
+ * Matches affected segments, builds the RSC payload, and returns the
+ * Flight response. Called inside route middleware (same as a normal render).
+ *
+ * Invariant: the response payload MUST have isPartial: true. The client
+ * (server-action-bridge) rejects non-partial payloads because partial
+ * reconciliation requires matched/diff semantics that full renders don't
+ * provide. Redirects are the only non-partial outcome and are handled via
+ * X-RSC-Redirect headers before Flight deserialization.
+ */
+export declare function revalidateAfterAction<TEnv>(ctx: HandlerContext<TEnv>, request: Request, env: TEnv, url: URL, handleStore: ReturnType<typeof getRequestContext>["_handleStore"], continuation: ActionContinuation): Promise<Response>;

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

@@ -0,0 +1,84 @@
+/**
+ * Build-time shell entry read-through (producer B, issue #699).
+ *
+ * The build stages one ShellCacheEntry per Prerender+ppr URL as a lazy
+ * manifest module injected into the RSC bundle
+ * (`globalThis.__loadShellManifestModule`, mirroring the prerender payload
+ * manifest — the worker handles every request; nothing is served from
+ * assets). The serve path consults this on a runtime shell-store MISS, so the
+ * FIRST request after a deploy is already a shell HIT with zero runtime
+ * capture. The worker cannot tell where an entry came from: a build hit is
+ * served through the same serveShellHit as a captured one.
+ *
+ * Lifecycle:
+ * - No expiry until the next deploy — the buildVersion gate retires entries
+ *   the moment a new build ships (a new manifest replaces them anyway).
+ * - `ppr.ttl` drives STALENESS ONLY: past createdAt + ttl the entry still
+ *   serves, but a runtime recapture is scheduled — SWR is the UPGRADE path
+ *   from build entry to fresher runtime entry, not the bootstrap path. The
+ *   runtime store is consulted first, so a captured entry supersedes the
+ *   build entry as soon as it lands.
+ * - `updateTag()` evicts build entries like runtime ones: the read-through
+ *   validates the entry's baked tag union against the store's tag
+ *   invalidation markers (isTagsInvalidatedSince) with the entry's createdAt
+ *   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";
+/** One baked manifest record (the __ps asset module's default export). */
+export interface BuildShellEntry {
+    entry: ShellCacheEntry;
+    /** Resolved ppr ttl (seconds) — drives staleness/recapture, never expiry. */
+    ttl: number;
+    swr?: number;
+    /** The putShell-barrier tag union baked at build (static + recorded). */
+    tags?: string[];
+    routeName: string;
+}
+interface ShellManifestModule {
+    /** Manifest key (pathname — see shell-manifest-key.ts) -> asset specifier. */
+    default: Record<string, string>;
+    loadShellAsset: (spec: string) => Promise<{
+        default: BuildShellEntry;
+    }>;
+}
+declare global {
+    var __loadShellManifestModule: (() => Promise<ShellManifestModule>) | undefined;
+}
+/** Reset the memoized manifest (unit tests swap the global loader). */
+export declare function resetBuildShellManifestForTests(): void;
+export interface BuildShellHit {
+    entry: ShellCacheEntry;
+    /** Past createdAt + ttl: serve, but schedule the runtime recapture. */
+    stale: boolean;
+}
+/**
+ * Dev-mode lookup context: there is no build manifest in dev, so producer B
+ * runs ON DEMAND through the Vite dev server's /__rsc_shell endpoint
+ * (memoized per router HMR generation), mirroring the dev prerender store's
+ * /__rsc_prerender flow. Only armed for PRERENDERED routes (matched.pr) —
+ * exactly production's candidate set; everything else keeps runtime capture.
+ */
+export interface DevShellLookup {
+    /** True when the classified route is trie-flagged pr (Prerender-backed). */
+    isPrerenderRoute: boolean;
+    /** Canonical route key of the classified route (endpoint verification). */
+    routeName: string | undefined;
+    /** Resolved ppr policy from the serve gate (the endpoint is policy-free). */
+    ttl: number;
+    swr?: number;
+    tags?: string[];
+    maxSnapshotBytes?: number;
+    /** Resolved `ppr.captureTimeout` (ms) — the endpoint's capture honors it. */
+    captureTimeout?: number;
+}
+/**
+ * Look up the baked shell entry for a request, applying every serve gate:
+ * search-less requests only (the build captured the bare pathname; a
+ * search-bearing URL has its own shell identity owned by runtime capture),
+ * version validity, payload integrity, and tag-invalidation markers. Returns
+ * null on any gate failure — the caller degrades to the ordinary MISS path
+ * (axis 1 + runtime capture), never a broken serve.
+ */
+export declare function lookupBuildShell(url: URL, buildVersion: string, store: SegmentCacheStore, dev?: DevShellLookup): Promise<BuildShellHit | null>;
+export {};

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

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

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

@@ -0,0 +1,370 @@
+/**
+ * PPR shell capture orchestration (Axis 2, see docs/design/ppr-shell-resume.md).
+ *
+ * Capture does NOT flow through the HTTP middleware pipeline. The integrated PPR
+ * serve path (rsc-rendering.ts + shell-serve.ts) builds a ShellCaptureDescriptor
+ * from the route's `ppr` path option after the served response is built and calls
+ * scheduleShellCapture. The capture then runs as a background task that re-derives
+ * the page via `ctx.router.match()` under its OWN derived request context — fresh
+ * handle store, `_shellCaptureRun: true` so loaders mask (loader-mask.ts) and every
+ * loading() subtree postpones. The render is MIXED-CHAIN: cache()'d segments replay
+ * from ring 3, uncached segments execute their handlers fresh. It drives the static
+ * prerender to a quiescent shell, aborts to freeze the prelude + postponed state,
+ * and stores the pair via putShell. Because it uses match() rather than the HTTP
+ * pipeline, the middleware chain (auth, logging) never re-runs — it already ran for
+ * the triggering request, and the derived context inherits its post-middleware
+ * state (variables, cache store). Guarding is serve-time.
+ */
+import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
+import { type RequestContext } from "../server/request-context.js";
+import { type HandleStore } from "../server/handle-store.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { HandlerContext } from "./handler-context.js";
+import type { SSRModule } from "./types.js";
+/**
+ * Default capture budget. Canonical value, raise rationale, and ceiling math
+ * live on the leaf module (shell-capture-constants.ts, importable from the ssr
+ * graph too). Re-exported here so shell-build-manifest.ts's envelope math
+ * keeps its existing import site and cannot drift from the capture.
+ */
+export { SHELL_CAPTURE_MAX_WAIT_MS };
+/**
+ * Delay before the in-place retry of a capture that produced no usable shell.
+ *
+ * The dominant reason a first capture comes back with a trivial prelude is a
+ * COLD render: in dev the module transform graph (route modules, the SSR/Flight
+ * transforms) is being built lazily and outlasts the task-quantized quiesce, so
+ * the shell has not finished rendering when we freeze it; on a cold worker the
+ * first invocation pays the same one-time cost. The first attempt WARMS that
+ * graph, so a second attempt a short beat later usually completes the shell in
+ * the SAME background task — no extra HTTP request needed. Short enough to feel
+ * instant, long enough for the module graph to settle. See
+ * docs/design/ppr-shell-resume.md ("Capture retry-in-place").
+ */
+declare const SHELL_CAPTURE_RETRY_DELAY_MS = 400;
+/** Sleep `ms`, unref'd so a Node dev process is never kept alive by the timer. */
+declare function delay(ms: number): Promise<void>;
+/**
+ * Refused-capture backoff bounds. The window is EXPONENTIAL in the consecutive
+ * failure count: `min(BASE * 2^(failures-1), ceiling)` — 1s, 2s, 4s, … up to the
+ * mode's ceiling (60s in production, {@link REFUSED_CAPTURE_DEV_MAX_MS} in dev).
+ *
+ * Why exponential and not a flat 60s: a flat long window conflates two very
+ * different failures. A STRUCTURALLY ineligible route (no loading(), a cookie
+ * reader) fails forever and wants the long 60s cap. But a cold-but-ELIGIBLE route
+ * can also fail the in-place retry under a truly cold graph (dev module transform,
+ * or a cold worker under parallel load) — and it must recover FAST, on the next
+ * request or two, not be frozen for 60s (that would re-break the very cold-start DX
+ * the retry fixes; it bit the cloudflare dev e2e). Escalating from 1s means the
+ * eligible route re-probes almost immediately (warm now → HIT and clear), while the
+ * doomed route ramps to the ceiling within a handful of failures. Either way an
+ * app-wide mount never re-renders a doomed route on EVERY request.
+ */
+declare const REFUSED_CAPTURE_BASE_MS = 1000;
+declare const REFUSED_CAPTURE_MAX_MS = 60000;
+/**
+ * DEV-only backoff ceiling. In dev the 60s production cap is pure harm: the
+ * dominant no-shell cause is a COLD module graph (route modules, SSR/Flight
+ * transforms built lazily), and the very attempt that failed WARMS that graph, so
+ * the next attempt a beat later usually completes the shell. Capping the dev window
+ * low keeps a cold-but-eligible route re-probing every ~2s instead of freezing for
+ * up to 60s once the exponential climbs (1s→2s→4s→…→60s). A 60s freeze outlasts the
+ * e2e warm windows on cold CI runners: the capture races an unfinished shell,
+ * escalates the backoff past the poll window, and every subsequent request inside
+ * that window is skipped as backed-off — an eternal MISS for the test even though
+ * the modules are warm by then. Production keeps the full 60s cap: there the
+ * no-shell cause is far more likely to be a genuinely ineligible route (no
+ * loading()), which SHOULD be re-probed rarely. See #652 (item 3) and
+ * docs/design/ppr-shell-resume.md ("Refused-capture backoff").
+ */
+declare const REFUSED_CAPTURE_DEV_MAX_MS = 2000;
+/** True iff `key` is still inside its (exponential) backoff window. */
+declare function isCaptureBackedOff(key: string): boolean;
+/**
+ * Record a refused/failed capture, escalating the backoff window exponentially up
+ * to the current mode's ceiling. The failure count keeps climbing across attempts
+ * (so a genuinely doomed route still ramps toward its cap), but the WINDOW is
+ * clamped: 60s in production, {@link REFUSED_CAPTURE_DEV_MAX_MS} in dev so a
+ * cold-but-eligible route re-probes fast instead of freezing out the e2e warm
+ * window on a cold CI runner (#652 item 3).
+ */
+declare function markCaptureBackoff(key: string): void;
+/** Clear any backoff for a key that just captured successfully. */
+declare function clearCaptureBackoff(key: string): void;
+/**
+ * Default cap (serialized UTF-8 bytes) on the capture data snapshot riding
+ * inside a shell entry, when the route's `ppr` option does not set
+ * `maxSnapshotBytes`. 8 MiB: the snapshot shares the stored envelope with the
+ * base64 prelude and the postponed blob, and the tightest store value limit is
+ * Cloudflare KV's 25 MiB — 8 MiB of snapshot leaves the envelope well under it
+ * while still fitting any sane pinned-ring payload. Applied ONLY in
+ * captureAndStoreShell (the single defaulting site — resolvePprConfig passes
+ * the option through undefaulted), so every producer and direct caller gets
+ * the same policy. Over the cap the snapshot is skipped (shell still stored;
+ * pinned reads drift — see PartialPrerenderProps.maxSnapshotBytes).
+ */
+export declare const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number;
+/**
+ * One structured event from the background capture pipeline, mirroring the
+ * CFCacheReadDebugEvent pattern (cache/cf/cf-cache-types.ts): typed fields an
+ * operator can assert against, emitted per attempt and per skip, so the
+ * stored / no-shell / refused / backed-off lifecycle is observable outside
+ * dev console warnings. Configured via `createRouter({ debugShellCapture })`.
+ */
+export interface ShellCaptureDebugEvent {
+    /** Shell cache key the event is about. */
+    key: string;
+    /**
+     * What happened:
+     * - stored / redirect / no-shell / refused: one capture ATTEMPT's outcome
+     *   (see CaptureAttemptOutcome for the semantics of each)
+     * - error: the capture task failed with a genuine error (also routed through
+     *   reportCacheError; the key is backed off)
+     * - skip-in-flight: scheduleShellCapture found a capture already running for
+     *   the key (stampede guard) and scheduled nothing
+     * - skip-backoff: the key is inside its refused-capture backoff window and
+     *   the capture was not attempted
+     * - backoff: the key entered (or escalated) backoff after a terminal
+     *   no-shell — carries the new backoff state
+     */
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "backoff";
+    /** Attempt number (1 = first, 2 = in-place retry). Absent on skips. */
+    attempt?: number;
+    /** Wall-clock ms of the whole attempt (barrier + render + drain + put). */
+    attemptMs?: number;
+    /**
+     * Wall-clock ms the pre-render WRITE BARRIER waited on the foreground
+     * request's deferred cache writes (bounded by SHELL_CAPTURE_WRITE_BARRIER_MS).
+     */
+    barrierWaitMs?: number;
+    /**
+     * Wall-clock ms spent awaiting the capture's own deferred cache writes
+     * before the snapshot drain (bounded by SHELL_SNAPSHOT_WRITE_SETTLE_MS).
+     */
+    writeSettleMs?: number;
+    /** Stored prelude size in bytes (pre-base64). */
+    preludeBytes?: number;
+    /** Serialized snapshot size in UTF-8 bytes. Absent when nothing was recorded. */
+    snapshotBytes?: number;
+    /** True when the snapshot exceeded maxSnapshotBytes and was dropped. */
+    snapshotSkipped?: boolean;
+    /** Outcome reported by a store that supports shell-write acknowledgements. */
+    storeWrite?: "stored" | "invalidated";
+    /** Consecutive failure count in the key's backoff entry, when one exists. */
+    backoffFailures?: number;
+    /** Ms remaining in the key's backoff window, when one exists. */
+    backoffRemainingMs?: number;
+}
+/**
+ * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
+ * logs each event to console (visible via `wrangler tail`), a function
+ * receives the events for programmatic capture. Off by default.
+ */
+export type ShellCaptureDebug = boolean | ((event: ShellCaptureDebugEvent) => void);
+/**
+ * Compact single-line form of an event's fields, shared by the console sink
+ * and the dev Server-Timing mirror's `desc` (rsc-rendering). Plain
+ * alphanumerics/`=`/`-`/`()` only, so it needs no quoted-string escaping.
+ */
+export declare function describeShellCaptureEvent(event: ShellCaptureDebugEvent): string;
+/**
+ * Resolve the `debugShellCapture` router option to a callable sink, or
+ * undefined when off. The INTERNAL_RANGO_DEBUG env-flag fallback lives HERE
+ * (not at a call site) so every producer that resolves a sink inherits it;
+ * an explicit `false` wins over the env flag.
+ */
+export declare function resolveShellCaptureDebugSink(option: ShellCaptureDebug | undefined): ((event: ShellCaptureDebugEvent) => void) | undefined;
+/**
+ * Consume (read-and-clear) the buffered terminal capture event for `key`, so
+ * one capture reports into exactly one later response's Server-Timing.
+ */
+export declare function takeCaptureDebugEventForTiming(key: string): ShellCaptureDebugEvent | undefined;
+export interface FlightCaptureGate {
+    /** Identity passthrough of the source stream; feed this to captureShellHTML. */
+    stream: ReadableStream<Uint8Array>;
+    /**
+     * Resolves once the source has been byte-quiet for FLIGHT_QUIET_HOPS macrotask
+     * hops (or has closed — the DATA variant). At that instant the gate FREEZES:
+     * no further source byte reaches the fizz side, and the readable is left open
+     * (never closed / errored) so fizz postpones the still-pending references
+     * instead of seeing "Connection closed".
+     */
+    quiesce: Promise<void>;
+    /**
+     * Stop the internal macrotask-hop loop. captureShellHTML's maxWaitMs bounds the
+     * overall wait; dispose() is the clean shutdown for the pathological case where
+     * the source never goes byte-quiet (quiesce never fires), so the hop loop would
+     * otherwise keep rescheduling after captureShellHTML has already aborted and
+     * returned.
+     */
+    dispose(): void;
+}
+/**
+ * Wrap the capture Flight stream so the fizz shell prerender reads a stream that
+ * (a) forwards the shell rows unchanged, (b) resolves `quiesce` after the rows go
+ * byte-silent for FLIGHT_QUIET_HOPS macrotask hops, and (c) FREEZES at that
+ * instant — dropping any later byte without closing or erroring the readable, so
+ * the pending masked-loader references stay pending and fizz postpones them (the
+ * "unclosing stream" property, here for free because the masked rows never emit).
+ * Freezing also guarantees no post-quiesce byte — including an error row from any
+ * later abort/cancel of the underlying render — can corrupt the frozen prelude.
+ *
+ * Quiet is measured in TASKS, not wall-clock: after the first byte a macrotask
+ * hop loop compares a byte counter each turn and fires after K quiet turns. The
+ * hop timers are unref'd so they never keep a Node process alive, and the source
+ * closing (no holes) fires quiesce immediately for the DATA variant — the
+ * TransformStream then closes the readable, so fizz completes with postponed null.
+ *
+ * `holdUntil` keeps the gate from FREEZING before shell material with real latency
+ * has emitted. The hole doctrine bakes TOP-LEVEL pushed handle promises into the
+ * shell (resolvedHandleStream awaits them before the handles row emits), but a
+ * pushed promise that takes longer than the quiet window would otherwise be frozen
+ * out — the handles row would never reach fizz and the prelude would come back
+ * trivial. While `holdUntil` is pending, byte-quiet detection keeps running but the
+ * gate neither fires nor freezes; once it resolves, the quiet counter restarts so a
+ * burst of rows unblocked by it (the resolved handles row) is still captured. It
+ * never delays a HOLE from postponing: holes are pending promises that emit no
+ * bytes, so holding the gate open longer only ever admits shell rows. Bounded by
+ * captureShellHTML's maxWaitMs like every other quiesce input.
+ */
+export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>, quietHops?: number, holdUntil?: Promise<unknown>): FlightCaptureGate;
+/**
+ * The background shell-capture descriptor: everything the capture task needs to
+ * store the shell. Built by the integrated PPR serve path (rsc-rendering.ts) from
+ * the route's `ppr` path option (`PartialPrerenderProps`) and the app-level cache
+ * store, and passed to scheduleShellCapture directly — it is NOT threaded through
+ * the request context. `tags` carries the route's OPERATIONAL `ppr.tags`; the
+ * capture UNIONS them with the shell's own auto-collected (non-loader) request
+ * tags from its derived render (the collected set stays authoritative). That
+ * union happens at the putShell WRITE BARRIER in captureAndStoreShell — after the
+ * capture quiesces — not at stream construction, so a tag recorded after an await
+ * in async shell content is still collected (issue #676). `store` is the same
+ * store the serve path resolved for its getShell read (requestCtx._cacheStore),
+ * so the capture writes where the serve reads.
+ */
+export interface ShellCaptureDescriptor {
+    key: string;
+    /**
+     * The RSC handler's build version (HandlerContext.version), stamped into the
+     * stored entry as ShellCacheEntry.buildVersion — the serve-side
+     * isValidShellHit gate compares it against the running build so a persistent
+     * store can never resume a stale build's postponed blob.
+     */
+    buildVersion: string;
+    ttl?: number;
+    swr?: number;
+    tags?: string[];
+    /**
+     * Per-route capture settle budget in ms (`ppr.captureTimeout`, resolved by
+     * resolvePprConfig). Feeds captureShellHTML's maxWaitMs — the ONE deadline
+     * bounding the whole capture, so it covers BOTH the fizz prerender AND the
+     * deferred-material settle window (the handlesBaked/loader-container
+     * holdUntil that keeps the gate from freezing while top-level pushes are
+     * pending). Undefined = SHELL_CAPTURE_MAX_WAIT_MS (15_000).
+     */
+    captureTimeout?: number;
+    store?: SegmentCacheStore<any>;
+    /** Gates the concise per-attempt capture breadcrumbs (INTERNAL_RANGO_DEBUG). */
+    debug?: boolean;
+    /**
+     * Cap (serialized UTF-8 bytes) on the entry's capture data snapshot; over it
+     * the snapshot is skipped and the shell stored without it (reported once per
+     * key). Absent = DEFAULT_PPR_MAX_SNAPSHOT_BYTES, applied in
+     * captureAndStoreShell — the single defaulting site.
+     */
+    maxSnapshotBytes?: number;
+    /**
+     * Structured capture-pipeline debug sink, resolved from
+     * `createRouter({ debugShellCapture })` (or INTERNAL_RANGO_DEBUG) via
+     * {@link resolveShellCaptureDebugSink}. Receives one
+     * {@link ShellCaptureDebugEvent} per attempt/skip.
+     */
+    debugSink?: (event: ShellCaptureDebugEvent) => void;
+}
+/**
+ * Schedule the background shell capture for a served document. Stampede-guarded:
+ * one capture per key per isolate. Runs via runBackground (waitUntil on workerd,
+ * fire-and-forget in Node dev), so the served response is never blocked on it. Any
+ * error is routed through reportCacheError — capture is best-effort; a failure just
+ * means the next request recaptures.
+ *
+ * Eligibility (nonce/allReady/partial/status/strategy) is decided by the caller
+ * (rsc-rendering.ts maybeScheduleShellCapture); this function only owns the
+ * stampede guard and the background dispatch.
+ */
+export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor): void;
+/**
+ * The outcome of one capture attempt.
+ * - `stored`: a usable shell was captured (and a putShell was attempted; a store
+ *   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.
+ */
+type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
+/**
+ * Per-attempt observability fields, filled along the capture path (barrier in
+ * attemptCapture, the rest in captureAndStoreShell) and folded into the
+ * attempt's {@link ShellCaptureDebugEvent} by runShellCapture. A plain mutable
+ * bag, not a return value: captureAndStoreShell's outcome type stays a string
+ * union its existing callers (producer B, tests) consume unchanged.
+ */
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "storeWrite">;
+/**
+ * Run the shell capture with a single in-place retry, then store the result.
+ *
+ * Each attempt re-derives EVERYTHING (fresh context, fresh router.match, fresh
+ * Flight render) via {@link attemptCapture} — a capture consumes its handle store,
+ * its request-tag set, and its one-shot Flight stream, so none of them are
+ * reusable across attempts. A first attempt that comes back `no-shell` is almost
+ * always a cold render (dev module transform / cold worker) that had not finished
+ * 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.
+ *
+ * `retryDelayMs` is a parameter (defaulting to the module const) so unit tests can
+ * drive the retry without a real 400ms wall-clock wait.
+ */
+declare function runShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule, descriptor: ShellCaptureDescriptor, retryDelayMs?: number): Promise<CaptureAttemptOutcome>;
+/**
+ * The derived capture context and its fresh (mask-funneled) handle store,
+ * shared by BOTH shell producers: the runtime background capture
+ * (attemptCapture, producer A) and the build-time prerender shell capture
+ * (prerender/build-shell-capture.ts, producer B — issue #699). One
+ * implementation so the capture semantics — the nested-thenable mask funnel,
+ * handler-liveness bookkeeping, snapshot recording, the implicit doc-cache
+ * scope — cannot drift between producers.
+ */
+export interface CaptureContextDerivation {
+    derivedCtx: RequestContext;
+    freshHandleStore: HandleStore;
+}
+/**
+ * Derive the capture request context from a base context. Producer A passes
+ * the foreground request's post-middleware context (the derived context
+ * inherits its variables/env/cookie machinery through the prototype);
+ * producer B passes a synthetic build-request context created by
+ * createRequestContext over the build env, with a fresh MemorySegmentCacheStore
+ * as `_cacheStore` so the recording/snapshot machinery arms identically.
+ */
+export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">): CaptureContextDerivation;
+/**
+ * Seal handles, derive the quiesce signal, prerender + abort via the SSR module's
+ * captureShellHTML, and store the result. Returns the attempt outcome (the caller
+ * owns retry/warn decisions — this function no longer warns). Never throws out of
+ * the store write: a failed putShell is routed through reportCacheError so the
+ * background task stays best-effort, and the attempt still counts as `stored` (the
+ * 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.
+ */
+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, };
+export { isCaptureBackedOff, markCaptureBackoff, clearCaptureBackoff, REFUSED_CAPTURE_BASE_MS, REFUSED_CAPTURE_MAX_MS, REFUSED_CAPTURE_DEV_MAX_MS, };