@rangojs/router 0.0.0-experimental.80 → 0.0.0-experimental.80daa23e

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

@@ -0,0 +1,425 @@
+/**
+ * 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
+     * - 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 custom store
+     *   whose backing tier is unavailable; built-in stores never declare it);
+     *   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" | "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). */
+    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;
+    /** A bake-lane loader settled into a shell that uses TTL/SWR-only invalidation. */
+    untaggedBake?: true;
+    /** Outcome reported by a store that supports shell-write acknowledgements. */
+    storeWrite?: "stored" | "invalidated" | "uncacheable";
+    /** 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;
+    /** 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`
+ * 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 key's search portion (shellSearchSeed: `?`-prefixed sorted search,
+     * cache.searchParams filter applied, or ""). Seeds the capture render's SSR
+     * store so static-part `useSearchParams` reads bake markup consistent with
+     * the shell's own key; the resume pass derives the identical string from
+     * the HIT request. Computed next to the key so the two cannot drift.
+     * Omitted (build-time bare-pathname captures) = search-less, same as "".
+     */
+    searchSeed?: string;
+    /**
+     * The scheduling request's origin, seeding the capture render's SSR store
+     * location. Shell keys are host-scoped, so the resume pass's request
+     * agrees modulo protocol drift; the seed keeps origin-dependent static
+     * markup (Link's data-external) identical across capture, resume, and
+     * browser hydration. Omitted (build-time host-agnostic captures) falls
+     * back to the internal host.
+     */
+    originSeed?: 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;
+    /** Store the snapshot for navigation replay, never the captured HTML prelude. */
+    navigationOnly?: true;
+}
+/**
+ * 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/partial/status/strategy) is decided by the caller. An SSR
+ * module loader may be passed for cold partial requests; it runs only after the
+ * capture enters the guarded background queue, never on response latency.
+ */
+export declare function scheduleShellCapture(ctx: HandlerContext<any>, request: Request, env: any, url: URL, reqCtx: RequestContext<any>, ssrModule: SSRModule | ((request: Request, url: URL) => Promise<SSRModule | null>), 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`: 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";
+/**
+ * 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" | "untaggedBake" | "storeWrite" | "bakeWaitMs">;
+/**
+ * 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`; 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">, identity?: {
+    request: Request;
+    url: URL;
+}): 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 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, };
+export { isCaptureBackedOff, markCaptureBackoff, clearCaptureBackoff, REFUSED_CAPTURE_BASE_MS, REFUSED_CAPTURE_MAX_MS, REFUSED_CAPTURE_DEV_MAX_MS, };

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

@@ -0,0 +1,200 @@
+/**
+ * Integrated PPR shell serving (Axis 2, see docs/design/ppr-shell-resume.md).
+ *
+ * PPR is opt-in per PAGE ROUTE via the `ppr` path option
+ * (`path(pattern, Handler, { name, ppr: true | PartialPrerenderProps })`) and the
+ * serving logic is INTEGRAL to the render pipeline — there is no middleware to
+ * mount. This module owns the config/key/store plumbing the render layer
+ * (rsc-rendering.ts) uses at its COMMIT POINT, which sits after the WHOLE
+ * middleware chain (global `router.use()` chain AND route DSL `middleware()`,
+ * both of which wrap the render pass): any middleware rejection/redirect wins
+ * before a single shell byte is written.
+ *
+ * The shell store is the app-level `createRouter({ cache })` store
+ * (`requestCtx._cacheStore`). A store without the `getShell`/`putShell` family
+ * degrades a ppr route to axis 1 with a once-per-key warning (the declared
+ * intent cannot be honored — unlike an undeclared route, which is silent).
+ */
+import { type EntryData } from "../server/context.js";
+import type { SearchParamsFilter } from "../cache/search-params-filter.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. */
+export declare const PPR_REPLAY_STATUS_HEADER = "x-rango-ppr-replay";
+/**
+ * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
+ * that omits `ttl`.
+ */
+export declare const DEFAULT_PPR_TTL_SECONDS = 300;
+/**
+ * Timeout for the dev /__rsc_shell endpoint's sequential /__rsc_prerender
+ * pre-flight probe (vite/router-discovery.ts). Hoisted here so the client-side
+ * fetch bound (shell-build-manifest.ts devShellFetchTimeoutMs) enumerates the
+ * SAME term of the endpoint's worst-case envelope — the two cannot drift.
+ */
+export declare const DEV_SHELL_PROBE_TIMEOUT_MS: number;
+/** The route's ppr option normalized to a concrete policy. */
+export interface ResolvedPprConfig {
+    ttl: number;
+    swr?: number;
+    tags?: string[];
+    /**
+     * Snapshot size cap, passed through undefaulted (like swr/tags): the single
+     * defaulting site is captureAndStoreShell (DEFAULT_PPR_MAX_SNAPSHOT_BYTES in
+     * shell-capture.ts), so direct descriptor callers and resolved configs
+     * cannot drift.
+     */
+    maxSnapshotBytes?: number;
+    /**
+     * Capture settle budget in ms (`ppr.captureTimeout`). Undefined = the
+     * capture default (SHELL_CAPTURE_MAX_WAIT_MS, 15_000) — the default's single
+     * owner stays shell-capture.ts so build/runtime producers cannot drift.
+     */
+    captureTimeout?: number;
+}
+/**
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms is
+ * clamped to the default ceiling; anything else (including
+ * 0/negative/NaN/Infinity/non-number) resolves to undefined, which means "use
+ * the capture default" downstream.
+ * Mirrors the prefetch-limit option policy: invalid values silently fall back
+ * to the default rather than throwing at request time. Also the boundary
+ * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),
+ * whose param crossed an HTTP query string.
+ */
+export declare function normalizeCaptureTimeout(value: unknown): number | undefined;
+/**
+ * Normalize the matched page route's `ppr` path option. Returns null when the
+ * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
+ * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
+ *
+ * The route's NAME is irrelevant here (and everywhere on the shell lane):
+ * nameless `path()` routes register their EntryData under a synthesized
+ * `$path_*` manifest key with the `ppr` option intact (urls/path-helper.ts),
+ * so a nameless entry resolves exactly like a named one — pinned by the
+ * nameless-ppr e2e in both apps (issue #714).
+ *
+ * PPR is a DOCUMENT-level property of the page route; there is no subtree
+ * inheritance (declaring it on a layout is not supported — a follow-up).
+ */
+export declare function resolvePprConfig(entry: EntryData | undefined | null): ResolvedPprConfig | null;
+/**
+ * Shell cache key: host + pathname + sorted search + a `:shell` namespace suffix
+ * (so it can never collide with a document-cache key; the store further isolates
+ * the shell family internally).
+ *
+ * The key includes the request HOST: in a multi-tenant host-router deployment
+ * (one worker, one shared KV/runtime-cache store) a host-less key would serve
+ * tenant A's captured shell to tenant B's users.
+ *
+ * `filter` is the request's compiled `cache.searchParams` config
+ * (ctx._searchParamsFilter): excluded params collapse onto one shell slot.
+ * Callers on the serve/capture path MUST pass it -- key drift between capture
+ * and lookup makes every shell request a permanent miss.
+ */
+export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
+/**
+ * The shell key's search portion (`?`-prefixed sorted search with the
+ * cache.searchParams filter applied, or "") — ALSO the string the capture and
+ * resume SSR renders seed their store location with (SSRRenderOptions.search
+ * / ShellCaptureOptions.search / ShellResumeOptions.search). Search is part
+ * of shell identity, so static-part `useSearchParams` reads render exactly
+ * what the key names; deriving seed and key from this one helper is what
+ * keeps capture, resume, and lookup byte-agreed (drift = replay mismatch or
+ * permanent MISS).
+ */
+export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter): string;
+/**
+ * Version gates for a stored shell: reactVersion AND buildVersion must both
+ * match the running server. The postponed blob encodes hole positions against
+ * one exact tree, so resuming it under a different React OR a different app
+ * build tree-mismatches inside resume() — after the 200 + prelude committed,
+ * with no recovery. Either mismatch is a miss: the recapture overwrites the
+ * same key (self-healing) and the entry otherwise ages out via TTL. An entry
+ * with no buildVersion (stored before the field existed) is a miss for the
+ * same reason — its build is unknown, so it cannot be proven resumable.
+ */
+export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: string): boolean;
+/**
+ * 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): 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. */
+export declare function hasShellFamily(store: SegmentCacheStore | undefined): store is SegmentCacheStore & {
+    getShell: NonNullable<SegmentCacheStore["getShell"]>;
+    putShell: NonNullable<SegmentCacheStore["putShell"]>;
+};
+/**
+ * Per-stage timing of one shell-HIT tail, all offsets in ms from the response
+ * commit (prelude flush). The HIT commits its 200 + headers BEFORE the live
+ * tail runs, so Server-Timing on the HIT response structurally cannot carry
+ * these numbers — they ride the dev mirror below instead (same doctrine as
+ * the ppr:capture mirror in rsc-rendering.ts, issue #651).
+ */
+export interface ShellTailTiming {
+    key: string;
+    outcome: "complete" | "redirect" | "error";
+    /** Loader-family seed decode (only when the entry carried a snapshot). */
+    seedMs?: number;
+    /** Tail router.match() settled. */
+    matchMs?: number;
+    /** Tail stream (resume output) handed to the response stream. */
+    handoverMs?: number;
+    /** First resumed-HTML byte enqueued on the wire. */
+    firstHtmlMs?: number;
+    /** Tail fully drained (last hole settled and flushed). */
+    completeMs?: number;
+    /** Prelude size flushed at commit (decoded bytes). */
+    preludeBytes?: number;
+    /** Total tail bytes streamed behind the prelude. */
+    tailBytes?: number;
+}
+/**
+ * Compact single-line form for the console log and the dev Server-Timing
+ * mirror's `desc`. Plain alphanumerics/`=`/`-` only — no quoted-string
+ * escaping needed.
+ */
+export declare function describeShellTailTiming(timing: ShellTailTiming): string;
+/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+export declare function publishShellTailTiming(timing: ShellTailTiming): void;
+/**
+ * Consume (read-and-clear) the buffered tail timing for `key`, so one tail
+ * reports into exactly one later response's Server-Timing.
+ */
+export declare function takeShellTailTimingForServerTiming(key: string): ShellTailTiming | undefined;
+/**
+ * Warn once per key that a route declared `ppr` but the app-level cache store
+ * does not implement the shell family (getShell/putShell), so the route stays on
+ * axis 1. Unlike an undeclared route (silent), a declared route that cannot be
+ * honored deserves a diagnostic.
+ */
+export declare function warnShellStoreMissingOnce(key: string): void;
+/**
+ * Warn once per key that a route declared `ppr` but a per-request CSP nonce is
+ * active for the request, so the route stays on axis 1 (a shared shell would
+ * freeze one request's nonce for every visitor — useNonce() renders it into every
+ * nonced script/style/meta and the browser's CSP would then reject the frozen
+ * nonce for all but the capture request). The nonce blocks capture whether it came
+ * from the `createRouter({ nonce })` provider or from a direct `ctx.set(nonce, …)`
+ * token write in middleware. Same declared-intent-cannot-be-honored doctrine as
+ * the missing-store warning above (an undeclared route stays silent).
+ */
+export declare function warnPprNonceActiveOnce(key: string): void;