@rangojs/router 0.17.0 → 0.18.0

package/dist/types/router/segment-resolution/loader-snapshot.d.ts

@@ -4,9 +4,11 @@
  *
  * A bake-lane loader (lane rule: see resolveLoaderData, loader-cache.ts)
  * executes during shell capture; its settled container bakes into the prelude
- * while nested promises postpone as holes. To keep a HIT's fresh
- * payload byte-identical to that frozen prelude, the capture pins the container
- * in the shell snapshot:
+ * while nested promises postpone as holes. To keep a HIT's fresh payload in
+ * agreement with that frozen prelude, the capture pins the container in the
+ * shell snapshot. Everything outside a hole is pinned; the one exception is a
+ * server-component element holding a promise, which is a hole as a whole (see
+ * elideLoaderContainer):
  *
  *   - elide:   deep-walk the settled container; a PENDING nested promise is a
  *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
@@ -27,7 +29,8 @@
  *              storefront PDP regression) — and fresh-only paths pass through
  *              (they cannot contradict prelude bytes that never rendered them).
  */
-export { maskNestedContainerThenables } from "./mask-nested.js";
+import { maskNestedContainerThenables } from "./mask-nested.js";
+export { maskNestedContainerThenables };
 /**
  * Marker object standing in for a pending nested promise in a recorded loader
  * container. Shape-checked (not identity-checked) because the record round-trips
@@ -70,21 +73,29 @@ export type ElideResult = {
  * promises pin their value behind a settled marker (they baked, but consumers
  * hold a promise-shaped key); pending ones become hole markers; a REJECTED
  * nested promise poisons the record (error UI must never bake into a shared
- * shell) — the caller refuses the capture. Only plain objects/arrays are
- * traversed; anything else (Date, Map, class instance) is a pinned leaf.
- * Cycles are cut as pinned references (best effort — Flight rejects true
- * cycles later regardless).
+ * shell) — the caller refuses the capture. Plain data objects, arrays and the
+ * props of host, Suspense/Fragment and client-reference elements are
+ * traversed copy-on-write (an element through cloneElementWithProps); a shared
+ * subtree or a cycle resolves to the same elided result. An element Flight
+ * renders by calling user code (see rendersOnServer) is a leaf, or ONE hole
+ * marker when a thenable sits anywhere in its props: the pin encode calls that
+ * component, so a marker inside its props would reach it. Anything else
+ * (Date, Map, class instance, lazy node) is a pinned leaf.
  *
  * The ROOT container promise-chain unwraps with NO marker: loader-cache
  * overlays against the AWAITED fresh container, so the recorded root must be
  * the unwrapped structure. Everything below it goes through elideNested.
  */
-export declare function elideLoaderContainer(value: unknown, seen?: Set<object>): Promise<ElideResult>;
+export declare function elideLoaderContainer(value: unknown, seen?: Map<object, ElideResult>): Promise<ElideResult>;
 /**
  * Overlay a recorded (elided) container onto the fresh run's container for a
  * shell HIT. Recorded wins per path; hole markers take the fresh value (the
  * live nested promise); fresh-only object keys pass through. Where the shapes
  * disagree structurally, recorded wins wholesale — it is what the prelude
- * froze, and parity beats freshness inside the shell.
+ * froze, and parity beats freshness inside the shell. Copy-on-write: a
+ * recorded subtree without markers comes back by identity. A recorded element
+ * is rebuilt through cloneElementWithProps only at its marker paths, so its
+ * other props stay pinned; props the fresh element adds do not pass through
+ * (the prelude rendered the element without them).
  */
 export declare function overlayLoaderContainer(fresh: unknown, recorded: unknown): unknown;

package/dist/types/router/segment-resolution/mask-nested.d.ts

@@ -1,13 +1,16 @@
 /**
- * Capture-side nested-thenable masking — the mechanism behind "nested-promise
- * shape is the liveness declaration" for BOTH bake-lane loader containers
- * (loader-cache.ts) and pushed handle containers (the capture handle store's
- * push wrap in rsc/shell-capture.ts).
+ * Capture-side nested thenables. Masking is the mechanism behind "nested-
+ * promise shape is the liveness declaration" for the loader lane: bake-lane
+ * loader containers (loader-cache.ts) and DSL loader handle pushes (the
+ * capture handle store's push wrap in rsc/shell-capture.ts). Handler handle
+ * pushes are handler output and bake: the capture waits for their nested
+ * promises instead (settleNestedThenables).
  *
  * Deliberately a LEAF module: loader-mask (the other natural home) imports
  * request-context, so any funnel importing the mask from there inherits that
- * graph. This module imports only is-thenable.
+ * graph. This module imports only is-thenable and react.
  */
+import { type ReactElement } from "react";
 /**
  * A promise that never settles — the masked stand-in for a per-request value
  * during shell capture. The consuming Suspense subtree suspends forever, so
@@ -18,11 +21,55 @@
  */
 export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
 /**
- * Deep-copy a container with every NESTED thenable replaced by a masked
+ * A data object the container walks descend into: prototype Object.prototype
+ * or null, and no symbol `$$typeof`. React elements, lazy nodes and references
+ * are plain objects too, told apart by that symbol (Flight switches on it).
+ * They are React's, not data: an element's dev-only fields (`_debugStack`,
+ * `_debugTask`, `_debugInfo`, `ref`) are non-enumerable, so a key-by-key copy
+ * drops them and dev Flight refuses it ("Attempted to render <x> without
+ * development properties", issue #942).
+ */
+export declare function isPlainDataObject(value: unknown): value is Record<string, unknown>;
+/**
+ * cloneElement with only the given props replaced, keeping React's dev key
+ * validation. React 19 dev cloneElement resets `_store.validated`, so a
+ * keyless child of a static children list (validated at creation) would warn
+ * "Each child in a list should have a unique key" once cloned. Pass only the
+ * props that change: cloneElement re-parents the element (owner) when its
+ * config carries `ref`.
+ */
+export declare function cloneElementWithProps(element: ReactElement, props: Record<string, unknown>): ReactElement;
+/**
+ * Resolves once `value` and every thenable reachable from it through plain
+ * data objects, arrays and React element props has settled, following what
+ * each thenable resolves to. A rejection counts as settled: the consumer that
+ * encodes the value reports it. Other objects are leaves (the same walk as
+ * maskNestedContainerThenables), so a promise inside a Map is not waited for.
+ * An element is walked through its props only (`<X data={promise} />` in a
+ * handle value is handler output too), never its owner or type, and is never
+ * rebuilt: nothing is copied, only awaited.
+ *
+ * The capture waits on this for HANDLER handle pushes (shell-capture.ts):
+ * handler output is baked, so its promises must settle before the doc record
+ * encodes the handles every HIT replays.
+ */
+export declare function settleNestedThenables(value: unknown): Promise<void>;
+/**
+ * Optional single-walk report for maskNestedContainerThenables: `thenable`
+ * flips true when the walk masked at least one thenable. The capture push
+ * funnel reads it for a loader push: a container with a masked nested
+ * promise keeps its loader tag, so the handle encode never waits on a mask.
+ * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ */
+export interface MaskReport {
+    thenable: boolean;
+}
+/**
+ * Copy a container with every NESTED thenable replaced by a masked
  * (never-resolving) promise. Applied during shell capture to (a) bake-lane
- * loader containers (loader-cache.ts) and (b) pushed handle containers
- * (shell-capture.ts capture store push wrap) — the two rango-owned funnels
- * where consumers declare per-request data by promise SHAPE.
+ * loader containers (loader-cache.ts) and (b) DSL loader handle pushes
+ * (shell-capture.ts capture store push wrap) — the rango-owned funnels where
+ * a loader declares per-request data by promise SHAPE.
  *
  * Why: a nested promise that happened to SETTLE before the capture's quiet
  * window closed used to bake its value into the SHARED shell (and, for
@@ -34,20 +81,14 @@ export declare function createMaskedLoaderPromise<T = unknown>(): Promise<T>;
  * Masking makes the consuming subtree postpone as a hole no matter when the
  * promise settles: liveness by declaration, not by racing the window.
  *
- * Only plain objects/arrays are traversed; other values are leaves. The INPUT
- * IS NEVER MUTATED — handler-side loader consumption (the consumption-lane
- * rule, semantic-matrix PPR3) shares the raw container and must keep real
- * values. Cycles are preserved as cycles in the copy.
- */
-/**
- * Optional single-walk report for maskNestedContainerThenables: `thenable`
- * flips true when the walk masked at least one thenable. The shell fast path
- * reads it at handle-push time — a pushed container with a nested thenable
- * declares per-request data, and a shell entry whose HANDLER layer made such
- * a declaration cannot be served handler-free (the hole would never fill).
- * Same single-pass shape as elideLoaderContainer's `hasHole`.
+ * Plain data objects, arrays and React element props are traversed: JSX
+ * carrying a promise (`<Reviews data={fetchReviews()} />`) declares
+ * per-request data the same way a plain container does. Other values, lazy
+ * nodes included, are leaves. Copy-on-write: a subtree without a thenable
+ * comes back by identity, so an element is rebuilt only when its props hold
+ * one, and then through cloneElementWithProps, which keeps its type, key,
+ * owner, dev fields and key validation. The INPUT IS NEVER MUTATED — handler-side loader consumption (the
+ * consumption-lane rule, semantic-matrix PPR3) shares the raw container and
+ * must keep real values. Cycles are preserved as cycles in the copy.
  */
-export interface MaskReport {
-    thenable: boolean;
-}
 export declare function maskNestedContainerThenables(value: unknown, seen?: Map<object, unknown>, report?: MaskReport): unknown;

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

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";
@@ -91,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
@@ -100,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;
 /**
@@ -116,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
@@ -137,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). */
@@ -184,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`
@@ -330,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,
@@ -343,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
@@ -350,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
@@ -361,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.
  *
@@ -373,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
@@ -423,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;