@rangojs/router 0.16.0 → 0.18.0

package/dist/types/rsc/full-payload.d.ts

@@ -12,6 +12,7 @@ import type { RscPayload } from "./types.js";
 import type { HandlerContext } from "./handler-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import type { HandleStore } from "../server/handle-store.js";
+import type { Theme } from "../theme/types.js";
 /**
  * Build the metadata payload for a full (non-partial) document render.
  *
@@ -20,3 +21,16 @@ import type { HandleStore } from "../server/handle-store.js";
  *   derived-context store.
  */
 export declare function buildFullPayload(m: MatchResult, ctx: HandlerContext<any>, url: URL, reqCtx: RequestContext<any>, handleStore: HandleStore): RscPayload;
+/**
+ * The theme a document payload carries as `metadata.initialTheme` (the
+ * ThemeProvider's first state), read with no identity guard: it is the
+ * router's own read, not handler code (#971).
+ *
+ * A shell capture carries the no-cookie default, not the capturing visitor's
+ * theme. The shell and its ShellCacheEntry.initialTheme serve every visitor,
+ * and ThemeProvider re-syncs only from an explicitly stored theme, so a
+ * visitor with none kept the capturer's `useTheme().theme` for the page's
+ * lifetime. A visitor with a stored theme gets it pre-paint (theme script)
+ * and in the provider after mount.
+ */
+export declare function payloadInitialTheme(reqCtx: Pick<RequestContext<any>, "_themeConfig" | "_shellCaptureRun" | "_readTheme">): Theme | undefined;

package/dist/types/rsc/handler.d.ts

@@ -6,4 +6,4 @@
  */
 import type { CreateRSCHandlerOptions } from "./types.js";
 import type { RouterRequestInput } from "../router/router-interfaces.js";
-export declare function createRSCHandler<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>>(options: CreateRSCHandlerOptions<TEnv, TRoutes>): (request: Request, input?: RouterRequestInput<TEnv>) => Promise<Response>;
+export declare function createRSCHandler<TEnv = unknown, TRoutes extends Record<string, string> = Record<string, string>>(options: CreateRSCHandlerOptions<TEnv, TRoutes>): (incomingRequest: Request, input?: RouterRequestInput<TEnv>) => Promise<Response>;

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

@@ -6,7 +6,7 @@
  * 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 EntryData } from "../server/context.js";
 import type { HandlerContext } from "./handler-context.js";
 export interface ResponseRouteMatch {
     responseType: string;

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

@@ -2,8 +2,7 @@
  * 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.
+ * (initial page load) requests.
  */
 import { getRequestContext } from "../server/request-context.js";
 import type { HandlerContext } from "./handler-context.js";

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

@@ -73,6 +73,14 @@ export interface DevShellLookup {
     /** Resolved `ppr.captureTimeout` (ms) — the endpoint's capture honors it. */
     captureTimeout?: number;
 }
+/**
+ * Whether a build-time shell exists for `pathname` (the caller checks the
+ * request is search-less, like the entries lookupBuildShell serves): a
+ * manifest entry for the path in production, a Prerender route in dev. No
+ * asset load and no dev capture: it only decides whether a request that
+ * cannot read the build shell deserves a warning.
+ */
+export declare function hasBuildShell(pathname: string, dev?: DevShellLookup): Promise<boolean>;
 /**
  * Look up the baked shell entry for a request, applying every serve gate:
  * search-less requests only (the build captured the bare pathname; a

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

@@ -14,17 +14,64 @@
  * 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).
+ * past response completion. An attempt that consumed the whole budget is not
+ * retried in place (shell-capture.ts noShellCauses), so the envelope is one
+ * budget plus store I/O; the retry follows only an attempt that ended early
+ * (a cold-module abort). Past the ceiling the platform kill degrades 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;
+/**
+ * The shell key for one request partition (cache-scope.ts
+ * resolveShellPartition): the route cache() `key()` or store keyGenerator
+ * result that partitions the route's record partitions its shell too, so
+ * each partition captures and serves its own. Here, in the leaf module, so
+ * the testing helper `shellCacheKey` (testing/shell-status.ts) calls it
+ * without pulling shell-serve.ts.
+ *
+ * The partition is URI-encoded: it is request-derived, and raw it could end
+ * in a suffix another key is built with (navigationShellKey), so a partition
+ * `gold:navigation` named gold's navigation entry and its document shell
+ * replayed to gold's navigations. Encoded, it holds no `:` or `|`.
+ */
+export declare function partitionShellKey(key: string, partition: string): string;
+/**
+ * The navigation-only entry beside a document shell key (a cold partial
+ * request's capture, rsc-rendering.ts). A suffix after the (encoded)
+ * partition: partitionShellKey keeps the two unambiguous.
+ */
+export declare function navigationShellKey(key: string): string;
+/**
+ * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
+ * give React's fizz worker turns to flush the settled shell into the prelude and
+ * mark still-pending boundaries as POSTPONED (rather than errored) before
+ * controller.abort() lands. Not a wall-clock wait. Taken by captureShellHTML
+ * (ssr/index.tsx) and by the testing SSR stub (testing/serve-shell-request.ts),
+ * so the stub freezes the same Flight the real capture would.
+ *
+ * Why 16 and not the original 2: under the REPLAY-ONLY capture model
+ * (docs/design/ppr-shell-resume.md), the capture Flight render serializes ring-3
+ * cached segments that are ALREADY serialized, so it emits the whole shell payload
+ * in the first tick and the gate declares quiesce almost immediately (~a few ms).
+ * On the old fresh-execution path the Flight dribbled out as handlers ran, so
+ * Flight-quiet effectively meant "the shell has rendered" and 2 hops sufficed.
+ *
+ * Hops alone are NOT render-readiness: fizz cannot emit even <html> until the
+ * payload root settles, nor complete a shell whose client components are
+ * still loading — real module-runner I/O in dev (100ms+ cold), which no fixed
+ * count of near-zero-cost task hops can buy. captureShellHTML therefore
+ * awaits the payload-settled signal (SsrRootOptions.onPayloadSettled) and
+ * then the client-reference loads in flight in the isolate (captureClientLoads),
+ * deadline-bounded, between quiesce and these hops; the hops then only flush
+ * the settled tree and mark pending boundaries POSTPONED. Still task-based
+ * (masked loaders never emit, so more hops never lets a hole settle). Bounded
+ * by maxWaitMs end to end.
+ */
+export declare const POST_QUIESCE_TASK_HOPS = 16;
 /**
  * Hard cap on one capture TASK — runShellCapture end to end (both attempts +
  * the in-place retry delay). SHELL_CAPTURE_MAX_WAIT_MS arms only inside
@@ -42,3 +89,11 @@ export declare const SHELL_CAPTURE_MAX_WAIT_MS = 15000;
  * check on the stampede guard, keyed off the same constant.
  */
 export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;
+/**
+ * Shared PPR loader-lane hint, appended to every capture warning or error
+ * whose fix depends on the lane (shell-capture.ts warnings, the cookie-store.ts
+ * capture guard). Lives in this import-free leaf so cookie-store.ts can import
+ * it without pulling the capture orchestration module. Source anchor for the
+ * rule: resolveLoaderData (router/segment-resolution/loader-cache.ts).
+ */
+export declare const PPR_LANE_HINT: string;

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

@@ -15,8 +15,9 @@
  * the triggering request, and the derived context inherits its post-middleware
  * state (variables, cache store). Guarding is serve-time.
  */
+import { type MatchResult } from "../types.js";
 import { SHELL_CAPTURE_MAX_WAIT_MS } from "./shell-capture-constants.js";
-import { type RequestContext } from "../server/request-context.js";
+import { type RequestContext, type RouteRecordWindow } 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";
@@ -50,10 +51,11 @@ declare function delay(ms: number): Promise<void>;
  * 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
+ * different failures. A STRUCTURALLY ineligible route (a boundary-less live
+ * loader read, 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
@@ -90,6 +92,13 @@ declare function isCaptureBackedOff(key: string): boolean;
 declare function markCaptureBackoff(key: string): void;
 /** Clear any backoff for a key that just captured successfully. */
 declare function clearCaptureBackoff(key: string): void;
+/**
+ * Default limit (bytes) on a whole stored shell entry — prelude, postponed
+ * state, and snapshot — when the store declares none
+ * (SegmentCacheStore.maxShellEntryBytes). Cloudflare KV's 25 MiB value limit:
+ * the tightest common store tier a shell entry lands in.
+ */
+export declare const DEFAULT_SHELL_ENTRY_MAX_BYTES: number;
 /**
  * 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
@@ -99,8 +108,9 @@ declare function clearCaptureBackoff(key: string): void;
  * 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).
+ * the same policy. The doc record is exempt; over the cap the other records
+ * are dropped (shell still stored and replayed; the pins' loaders read the
+ * live store — see PartialPrerenderProps.maxSnapshotBytes).
  */
 export declare const DEFAULT_PPR_MAX_SNAPSHOT_BYTES: number;
 /**
@@ -115,10 +125,13 @@ export interface ShellCaptureDebugEvent {
     key: string;
     /**
      * What happened:
-     * - stored / redirect / no-shell / refused: one capture ATTEMPT's outcome
-     *   (see CaptureAttemptOutcome for the semantics of each)
+     * - stored / redirect / no-shell / refused / expired: 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-stored: a capture for the key stored after the scheduling request
+     *   read the store and missed (ShellCaptureDescriptor.storedSeqAtRead), so
+     *   the shell that request missed exists now
      * - 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
@@ -136,7 +149,7 @@ export interface ShellCaptureDebugEvent {
      * - backoff: the key entered (or escalated) backoff after a terminal
      *   no-shell — carries the new backoff state
      */
-    outcome: "stored" | "redirect" | "no-shell" | "refused" | "error" | "skip-in-flight" | "skip-backoff" | "skip-capacity" | "skip-inert-store" | "skip-queue-timeout" | "backoff";
+    outcome: "stored" | "redirect" | "no-shell" | "refused" | "expired" | "error" | "skip-in-flight" | "skip-stored" | "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). */
@@ -183,6 +196,14 @@ export interface ShellCaptureDebugEvent {
      * it attributable. Absent when nothing held the gate.
      */
     bakeWaitMs?: number;
+    /**
+     * How long the capture waited for its doc record: the handler layer's
+     * promises, async server components and handle pushes settling, then the
+     * record's encode (settleCaptureRecord). Part of the one capture deadline.
+     */
+    recordSettleMs?: number;
+    /** Bytes of the stored entry: prelude, postponed state, and snapshot. */
+    entryBytes?: number;
 }
 /**
  * Debug sink for the capture pipeline, mirroring {@link CFCacheDebug}: `true`
@@ -329,7 +350,17 @@ export interface ShellCaptureDescriptor {
     debugSink?: (event: ShellCaptureDebugEvent) => void;
     /** Store the snapshot for navigation replay, never the captured HTML prelude. */
     navigationOnly?: true;
+    /**
+     * lastStoredCaptureSeq(key) when a document request read the store and
+     * missed. The request schedules its capture only after rendering the MISS,
+     * so a capture another request started can store in between; a later
+     * sequence number then skips the redundant one (`skip-stored`), which would
+     * re-render the page and drop the isolate's memo of the shell just stored.
+     */
+    storedSeqAtRead?: number;
 }
+/** The latest stored capture's sequence number for `key` in this isolate, or 0. */
+export declare function lastStoredCaptureSeq(key: string): number;
 /**
  * Schedule the background shell capture for a served document. Stampede-guarded:
  * one capture per key per isolate. Runs via runBackground (waitUntil on workerd,
@@ -342,6 +373,26 @@ export interface ShellCaptureDescriptor {
  * 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 ttl/swr a shell is stored with: the route's ppr policy, capped by the
+ * route cache() records the capture replayed or wrote
+ * (RequestContext._routeRecordWindow). A HIT replays the capture's handler
+ * output, while a client navigation reads the route's cache() tier first, so
+ * a shell that outlived its record would show a document request other
+ * handler output than a navigation of the same URL. Freshness and total
+ * lifetime are capped separately, like the record's own SWR: the shell is
+ * fresh while the record is (at most `ttl`), and servable while the record
+ * is (at most `ttl + swr`), so a record already inside its swr window yields
+ * a shell that is stale from the start and serves while it recaptures.
+ *
+ * Whole seconds, rounded up (the SegmentCacheStore.putShell contract), so the
+ * shell may outlast the record by under a second. Null when the record's
+ * total lifetime has run out: the shell would be dead on arrival.
+ */
+export declare function capShellWindow(ttl: number, swr: number, record: Pick<RouteRecordWindow, "freshUntil" | "staleUntil">, now: number): {
+    ttl: number;
+    swr: number;
+} | null;
 /**
  * The outcome of one capture attempt.
  * - `stored`: a usable shell was captured (and a putShell was attempted; a store
@@ -349,10 +400,16 @@ export declare function scheduleShellCapture(ctx: HandlerContext<any>, request:
  *   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.
+ *   or its private capture abort landed before the shell completed, or the
+ *   capture ran out of ppr.captureTimeout. Retried once in place, when no
+ *   deadline ran out (noShellCauses).
+ * - `expired`: the route cache() record the capture read (not wrote) ran out
+ *   before the store (capShellWindow null): it was near its end (its age,
+ *   queue wait). Retried once in place, where a fresh match reads or renders
+ *   a newer record; a second `expired`, or no hard-cap budget left for the
+ *   retry, is terminal `no-shell` (backoff, warned once per route).
  */
-type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
+type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused" | "expired";
 /**
  * Per-attempt observability fields, filled along the capture path (barrier in
  * attemptCapture, the rest in captureAndStoreShell) and folded into the
@@ -360,7 +417,7 @@ type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
  * bag, not a return value: captureAndStoreShell's outcome type stays a string
  * union its existing callers (producer B, tests) consume unchanged.
  */
-type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "bakeWaitMs">;
+type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "writeSettleMs" | "preludeBytes" | "snapshotBytes" | "snapshotSkipped" | "untaggedBake" | "storeWrite" | "bakeWaitMs" | "recordSettleMs" | "entryBytes">;
 /**
  * Run the shell capture with a single in-place retry, then store the result.
  *
@@ -372,26 +429,93 @@ 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`; a
- * genuine render error is NOT retried — it propagates to scheduleShellCapture's
+ * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`
+ * that did not run out of ppr.captureTimeout (noShellCauses); 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>;
+/**
+ * What the record-first step produced ({@link settleCaptureRecord}):
+ * - `record`: the doc record settled; `match` carries its fragments in place
+ *   of the handler layer's elements, so the capture's Flight payload is the
+ *   bytes every HIT replays.
+ * - `prerender`: the prerender store supplied the handler layer (a
+ *   Prerender route); its HIT tail replays the same build-time segments, so
+ *   the capture renders the match as is.
+ * - `timeout`: handler output did not settle within the capture budget.
+ * - `refused`: a deterministic refusal (a capture guard tripped, the route
+ *   opted out, or the handler output failed); the warning already fired.
+ */
+export type CaptureRecordOutcome = {
+    kind: "record" | "prerender";
+    match: MatchResult;
+} | {
+    kind: "timeout";
+    reason: string;
+} | {
+    kind: "refused";
+};
+/**
+ * Record-first capture: the doc record is both the settle signal and the
+ * parity source.
+ *
+ * Writing the record Flight-serializes every non-loader segment
+ * (serializeSegments), which runs each handler's async server components and
+ * waits for every promise the handler output carries — the capture's "is the
+ * handler layer done" signal. Live-lane loader data is not in the record
+ * (loader segments are excluded and their masked promises never settle), so
+ * the wait never depends on a hole.
+ *
+ * The capture then renders its OWN Flight payload from the record's
+ * fragments (fragmentSegments, the function a HIT tail uses) instead of from
+ * the elements the match produced. Server components therefore render once
+ * per capture, inside the record's encode: before this, the capture's Flight
+ * render and the record's encode each ran them, so an uncached async
+ * component showed one value in the prelude and another on every HIT.
+ *
+ * Order, all bounded by the one capture deadline (`ppr.captureTimeout`):
+ * top-level handle promises, the handler pushes' nested promises, and the
+ * bake-lane loader containers settle first (the record encodes the handles
+ * a HIT restores, and its handle encode has its own 5s timeout that must
+ * never be the one that fires); then the capture's onResponse callbacks fire
+ * with a synthetic 200 (the implicit doc scope's cacheRoute, an explicit
+ * scope's own write), and the deferred writes settle.
+ */
+export declare function settleCaptureRecord(match: MatchResult, derivation: CaptureContextDerivation, capture: Pick<ShellCaptureDescriptor, "key">, deadline: number): Promise<CaptureRecordOutcome>;
+/**
+ * Race `work` against an absolute deadline, keeping its value. The losing
+ * work is not cancelled (a router match has no abort signal); callers that
+ * lose do not start it again (runShellCapture skips its in-place retry).
+ */
+export declare function withinDeadline<T>(work: Promise<T>, deadline: number): Promise<{
+    done: true;
+    value: T;
+} | {
+    done: false;
+}>;
 /**
  * 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.
+ * implementation so the capture semantics — the handle push funnel (handler
+ * pushes settled, loader pushes masked), the capture guards, snapshot
+ * recording, the implicit doc-cache scope — cannot drift between producers.
  */
 export interface CaptureContextDerivation {
     derivedCtx: RequestContext;
     freshHandleStore: HandleStore;
+    /**
+     * Resolves once every handler handle push has settled at any depth of
+     * plain objects and arrays (top-level promise, then the promises nested
+     * in what it resolved to). The record-first step awaits it before the doc
+     * record encodes its handles, so that encode never races a pending value.
+     */
+    handlerPushesSettled: () => Promise<void>;
 }
 /**
  * Derive the capture request context from a base context. Producer A passes
@@ -422,3 +546,11 @@ export declare function deriveShellCaptureContext(reqCtx: RequestContext<any>, d
 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, };
+/**
+ * @internal Reset this module's per-isolate state: the capture stampede
+ * guard, the refused-capture backoff, the recorded no-shell causes (which
+ * also skip a timed-out capture's in-place retry), the once-per-key warnings
+ * and the buffered debug events. Tests only (testing/serve-shell-request.ts
+ * resetShellTestState), between requests, never while a capture runs.
+ */
+export declare function resetShellCaptureStateForTests(): void;

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

@@ -17,7 +17,7 @@
  */
 import { type EntryData } from "../server/context.js";
 import type { SearchParamsFilter } from "../cache/search-params-filter.js";
-import type { DocumentShellCacheEntry, ShellCacheEntry, SegmentCacheStore } from "../cache/types.js";
+import type { DocumentShellCacheEntry, ShellCacheEntry, ShellDocumentRead, ShellReadStats, ShellSnapshotFailure, ShellSnapshotRecord, 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. */
@@ -94,6 +94,41 @@ export declare function resolvePprConfig(entry: EntryData | undefined | null): R
  * and lookup makes every shell request a permanent miss.
  */
 export declare function buildShellKey(url: URL, filter?: SearchParamsFilter): string;
+export { navigationShellKey, partitionShellKey, } from "./shell-capture-constants.js";
+/**
+ * The forced-MISS query marker. A document HIT that cannot finish its tail
+ * reloads the page with it (shellReloadScript); the serve gate renders a
+ * request carrying it on axis 1, with no shell read and no capture, so the
+ * reload can never be a HIT that degrades again. The handler drops it from
+ * the request on entry (withoutShellMissMarker) and keeps only the flag
+ * (RequestContext._shellForcedMiss), so nothing else sees it.
+ */
+export declare const SHELL_MISS_PARAM: string;
+/**
+ * The request without the forced-MISS marker, or undefined when it carries
+ * none. The handler calls it before anything reads the request: left in, the
+ * marker reached `ctx.request.url`, `originalUrl`, middleware, and the SSR
+ * search seed (so `useSearchParams` rendered it), and a `"use cache"` key
+ * built from the request URL was never read again. GET and HEAD only: the
+ * reload is a navigation, and a request with a body cannot be re-created
+ * without re-streaming it. The substring test keeps the URL parse off every
+ * other request.
+ */
+export declare function withoutShellMissMarker(request: Request): Request | undefined;
+/**
+ * The inline script a degraded document HIT ends with: reload once into a
+ * forced MISS. The marker in the URL is the loop bound — a request carrying
+ * it is never a HIT, so this script never runs on the reload, and if it ever
+ * did (a server that ignores the marker) it would return without touching
+ * the page. window.stop() runs only when it reloads: it keeps the half-sent
+ * Flight stream from being closed by DOMContentLoaded, which would throw
+ * React's "Connection closed" (#412) before the reload lands. `nonce` is the
+ * request's CSP nonce; a ppr route with an active nonce is axis 1
+ * (rsc-rendering.ts shellServePlan), so on a HIT it is normally absent.
+ */
+export declare function shellReloadScript(nonce?: string): string;
+/** An inline script a shell HIT's tail appends, carrying the CSP nonce if any. */
+export declare function inlineShellScript(body: string, nonce?: string): string;
 /**
  * The shell key's search portion (`?`-prefixed sorted search with the
  * cache.searchParams filter applied, or "") — ALSO the string the capture and
@@ -117,16 +152,11 @@ export declare function shellSearchSeed(url: URL, filter?: SearchParamsFilter):
  */
 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.
+ * DOCUMENT-half structural gate and type narrowing, without decoding the
+ * prelude: the prelude is a string and the postponed blob parses. Partial
+ * replay (which never serves the prelude) and the build-manifest read-through
+ * use it as-is; the document HIT path runs it inside
+ * {@link openShellDocument}, whose single decode is the prelude's check.
  *
  * navigationOnly entries store no document half (prelude/postponed absent) and
  * therefore never pass. The partial-replay path skips this gate for them
@@ -135,8 +165,46 @@ export declare function isValidShellHit(entry: ShellCacheEntry, buildVersion: st
  * 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;
+/** A document shell ready to serve: its prelude decoded exactly once. */
+export interface ShellDocument {
+    entry: ShellCacheEntry;
+    prelude: Uint8Array;
+    /** React's postponed state, parse-checked (null = DATA variant). */
+    postponed: string | null;
+    /**
+     * The capture snapshot: on the entry, or still arriving on its own promise
+     * after a prelude-first read (SegmentCacheStore.readShellDocument), which
+     * only the tail awaits.
+     */
+    snapshot: ShellSnapshotRecord[] | undefined | Promise<ShellSnapshotRecord[] | undefined>;
+    /** Why a prelude-first read's snapshot is missing (ShellDocumentRead). */
+    snapshotFailure?: Promise<ShellSnapshotFailure | undefined>;
+    /** The prelude-first read's stats, when perf metrics are on. */
+    stats?: ShellReadStats;
+}
+/**
+ * Pre-commit integrity gate for a document HIT, and its only prelude decode.
+ * 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 (`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. Returning null here turns a corrupt entry
+ * (store-layer fault) into a plain MISS the recapture overwrites. The decoded
+ * bytes are what serveShellHit enqueues, so the check costs no second decode.
+ * A prelude-first `read` (SegmentCacheStore.readShellDocument) already carries
+ * the raw bytes and a pending snapshot, so only its postponed blob is checked.
+ */
+export declare function openShellDocument(entry: ShellCacheEntry, read?: Pick<ShellDocumentRead, "prelude" | "snapshot" | "snapshotFailure" | "stats">): ShellDocument | null;
+/**
+ * Prelude enqueue granularity. A streaming compressor in front of the worker
+ * emits its first byte only after compressing the whole write it was handed:
+ * one 629 KB enqueue delayed the first compressed byte by the full prelude's
+ * compression time (brotli-6 5.1 ms, gzip-6 1.1 ms in Node zlib with a flush
+ * per write; workerd's CompressionStream emits nothing until the whole write is
+ * compressed), while 32 KB chunks emit within 0.1 ms and cost slightly more
+ * in total compression (0.55-0.70 ms) than one write (issue #941).
+ */
+export declare const SHELL_PRELUDE_CHUNK_BYTES: number;
 /** True when the store implements the shell entry family. */
 export declare function hasShellFamily(store: SegmentCacheStore | undefined): store is SegmentCacheStore & {
     getShell: NonNullable<SegmentCacheStore["getShell"]>;
@@ -152,8 +220,22 @@ export declare function hasShellFamily(store: SegmentCacheStore | undefined): st
 export interface ShellTailTiming {
     key: string;
     outcome: "complete" | "redirect" | "error";
+    /** The capture snapshot available to the tail (read and parsed). */
+    snapshotMs?: number;
+    /** Snapshot bytes read after the commit (prelude-first stores). */
+    snapshotBytes?: number;
+    /** Snapshot bytes read after the commit, excluding the parse. */
+    snapshotReadMs?: number;
+    /** Snapshot JSON.parse CPU (reads 0 on a deployed worker: see bytes). */
+    snapshotParseMs?: number;
+    /** Snapshot records by family, e.g. `segment:1/item:5` (no commas: it rides a Server-Timing desc). */
+    snapshotRecords?: string;
+    /** Records the capture pruned from the snapshot, same format (ShellCacheEntry.prunedRecords). */
+    snapshotPruned?: string;
     /** Loader-family seed decode (only when the entry carried a snapshot). */
     seedMs?: number;
+    /** The seed decode's own duration: Flight deserialization, CPU only. */
+    seedCpuMs?: number;
     /** Tail router.match() settled. */
     matchMs?: number;
     /** Tail stream (resume output) handed to the response stream. */
@@ -168,12 +250,13 @@ export interface ShellTailTiming {
     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.
+ * Compact single-line form for the console log and the Server-Timing mirror's
+ * `desc`: alphanumerics and `=`, `-`, `:`, `/` only (records=segment:1 pruned=item:5),
+ * so no quoted-string escaping is needed. Offsets are from the commit; the
+ * `-cpu` fields are CPU-only durations.
  */
 export declare function describeShellTailTiming(timing: ShellTailTiming): string;
-/** Buffer one terminal tail timing for the dev Server-Timing mirror. */
+/** Buffer one terminal tail timing for the Server-Timing mirror. */
 export declare function publishShellTailTiming(timing: ShellTailTiming): void;
 /**
  * Consume (read-and-clear) the buffered tail timing for `key`, so one tail
@@ -198,3 +281,43 @@ export declare function warnShellStoreMissingOnce(key: string): void;
  * the missing-store warning above (an undeclared route stays silent).
  */
 export declare function warnPprNonceActiveOnce(key: string): void;
+/**
+ * Dev only (the caller gates on NODE_ENV): warn once per route that the
+ * route's cache() entry reduces an explicit `ppr.ttl` or `ppr.swr`. `shell`
+ * is what the capture stores for a record written just now
+ * (shell-capture.ts capShellWindow), so the message states the values the
+ * shell actually gets. A ppr value the cap leaves whole (or raises: the
+ * cap can move a record's stale time into the shell's swr) is silent, and
+ * so is a ppr config that sets no ttl/swr.
+ */
+export declare function warnPprWindowCappedOnce(routeName: string, ppr: {
+    ttl?: number;
+    swr?: number;
+}, shell: {
+    ttl: number;
+    swr: number;
+}, cache: {
+    ttl: number;
+    swr: number;
+}): void;
+/**
+ * Whether a partitioned request needs no build-shell probe: its route was
+ * already warned, or its path was already found without one.
+ */
+export declare function partitionBuildShellCheckDone(pathname: string, routeName: string | undefined): boolean;
+/**
+ * Record a partitioned request's build-shell probe, and warn once per route
+ * when it found one: the route has a build-time shell its requests cannot
+ * read. The route's request partition (a `cache({ key })` enclosing it, at
+ * any depth (#970), or the store's keyGenerator) keys the shell per
+ * partition, and the build captured only
+ * the default one, so each partition captures at runtime. Same
+ * declared-intent-cannot-be-honored doctrine as the warnings above; a path
+ * with no build shell stays silent.
+ */
+export declare function notePartitionBuildShellCheck(pathname: string, routeName: string | undefined, found: boolean): void;
+/**
+ * @internal Reset the serve path's once-per-key warnings and buffered tail
+ * timings. Tests only (testing/serve-shell-request.ts resetShellTestState).
+ */
+export declare function resetShellServeStateForTests(): void;