@rangojs/router 0.27.0 → 0.28.0

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

@@ -4,9 +4,9 @@
  * 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
+ * planShellCapture with it (ShellCaptureInput). 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 live-lane loaders mask (loader-mask.ts)
+ * handle store, `_shellCaptureState.run` so live-lane loaders mask (loader-mask.ts)
  * and postpone at their loading() or inline <Suspense> boundary. The match is
  * MIXED-CHAIN: cache()'d segments replay from ring 3, uncached segments execute
  * their handlers. The record-first step (settleCaptureRecord) waits for the
@@ -20,7 +20,7 @@
  */
 import { type MatchResult } from "../types.js";
 import { type ShellCaptureRefusal } from "./shell-capture-constants.js";
-import { type RequestContext, type RouteRecordWindow } from "../server/request-context.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";
@@ -128,7 +128,7 @@ export interface ShellCaptureDebugEvent {
      * - 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
+     * - skip-in-flight: planShellCapture 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
@@ -268,7 +268,7 @@ export declare function gateFlightForCapture(source: ReadableStream<Uint8Array>)
  * 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
+ * store, and passed to planShellCapture in its input — 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
@@ -336,7 +336,7 @@ export interface ShellCaptureDescriptor {
     /**
      * Set for a shell keyed by the visitor's URL (`rewrite(...).shell("visitor")`,
      * visitorShellKey): the capture renders the visitor's location
-     * (`RequestContext._shellCaptureForVisitor`) and stores it as
+     * (`ShellCaptureState.forVisitor`) and stores it as
      * ShellCacheEntry.pathname.
      */
     pathname?: string;
@@ -351,7 +351,7 @@ export interface ShellCaptureDescriptor {
     /**
      * A `router.prerender()` warm's capture (rsc-rendering.ts shellServePlan):
      * one explicit call that must store, so the guards that shed a herd of
-     * visitors do not apply to it. scheduleShellCapture skips the in-flight
+     * visitors do not apply to it. planShellCapture skips the in-flight
      * dedup and the refused-capture backoff, and attemptCapture waits longer on
      * the write barrier. Every correctness guard, the inert-store skip and the
      * queue limits still decide.
@@ -360,6 +360,21 @@ export interface ShellCaptureDescriptor {
 }
 /** The latest stored capture's sequence number for `key` in this isolate, or 0. */
 export declare function lastStoredCaptureSeq(key: string): number;
+/** One shell capture: the request it re-renders and what it stores. */
+export interface ShellCaptureInput {
+    ctx: HandlerContext<any>;
+    request: Request;
+    env: any;
+    url: URL;
+    reqCtx: RequestContext<any>;
+    /**
+     * The SSR module for the capture's own request and URL, called once the
+     * capture leaves the queue. A document passes the module it already
+     * resolved, returned as is, so the capture awaits only a pending one.
+     */
+    ssr: (request: Request, url: URL) => SSRModule | null | Promise<SSRModule | null>;
+    descriptor: ShellCaptureDescriptor;
+}
 /**
  * Schedule the background shell capture for a served document. Stampede-guarded:
  * one capture per key per isolate. Runs via runBackground (waitUntil on workerd,
@@ -367,15 +382,13 @@ export declare function lastStoredCaptureSeq(key: string): number;
  * 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.
+ * Eligibility (nonce/partial/status/strategy) is decided by the caller.
  */
-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;
+export declare function planShellCapture(input: ShellCaptureInput): 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
+ * (ShellCaptureState.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
@@ -456,9 +469,9 @@ type CaptureAttemptStats = Pick<ShellCaptureDebugEvent, "barrierWaitMs" | "write
  * several HTTP requests before a capture stuck. We retry ONLY on `no-shell`
  * that did not run out of ppr.captureTimeout (CaptureAttemptStats.noShellCause),
  * and on `expired`; a genuine render error is NOT retried — it propagates to
- * scheduleShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
+ * planShellCapture's reportCacheError. See docs/design/ppr-shell-resume.md.
  *
- * `request` and `url` are the capture's own identity (scheduleShellCapture
+ * `request` and `url` are the capture's own identity (planShellCapture
  * strips a navigation-only capture's transport parameters). `retryDelayMs` is
  * a parameter (defaulting to the module const) so unit tests can drive the
  * retry without a real 400ms wall-clock wait.
@@ -511,9 +524,113 @@ export type CaptureRecordOutcome = {
  * 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.
+ * scope's own write), and the deferred writes settle. A match holding an
+ * error or notFound boundary throws before the callbacks fire.
  */
 export declare function settleCaptureRecord(match: MatchResult, derivation: CaptureContextDerivation, capture: Pick<ShellCaptureDescriptor, "key">, deadline: number): Promise<CaptureRecordOutcome>;
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * capture wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+    freshUntil: number;
+    staleUntil: number;
+    ttl: number;
+    swr: number;
+    written: boolean;
+}
+/**
+ * @internal What a shell capture's render records about itself, on its
+ * derived request context as `_shellCaptureState`.
+ * RENDER_PASS_FIELDS["shell-capture"] (server/render-pass.ts) creates it with
+ * every field present, so it keeps one shape while the capture writes it. A
+ * background re-render the capture starts has none: it writes a route
+ * record, under cache() rules (RENDER_PASS_FIELDS["background-revalidation"]).
+ */
+export interface ShellCaptureState {
+    /**
+     * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
+     * capture task's derived request context (built by shell-capture.ts). This is
+     * the switch every capture-specific behavior reads: loader masking
+     * (loader-mask.ts isShellCaptureActive / resolveOwnerLoaders) and the
+     * identity-read capture guard (server/context.ts guardIdentityRead). The
+     * foreground render never sets it, so the
+     * served response is byte-identical to axis 1. The capture descriptor itself
+     * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
+     * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
+     * locally and passes it to planShellCapture in its input.
+     */
+    readonly run: true;
+    /**
+     * @internal Set beside `run` when the shell is keyed by the
+     * visitor's URL (`rewrite(...).shell("visitor")`): the capture renders the
+     * visitor's location and `ctx.rewrittenFrom`; the theme stays the default.
+     */
+    forVisitor: boolean | undefined;
+    /**
+     * @internal Bake-lane loader containers collected DURING a shell capture:
+     * segment-key -> the loader's (pre-wrap) result promise. Populated by
+     * resolveLoaderData for bake-lane loaders (lane rule: see its JSDoc in
+     * loader-cache.ts). Drained by captureAndStoreShell after the shell
+     * quiesces: settled containers are promise-elided, Flight-serialized, and
+     * pinned into the snapshot's loader family; a REJECTED container refuses
+     * the capture (error UI must never bake into the shared shell).
+     */
+    loaderRecords: Map<string, Promise<unknown>>;
+    /**
+     * @internal Set when a loader pushed a
+     * value the record cannot keep (masked nested promises, a pushed promise
+     * that settled to one, a live-lane loader's push, or a push outside a
+     * loader body): the loader records then carry `runs: 1`, so a HIT still
+     * runs their bodies for those pushes.
+     */
+    unrecordedLoaderPush: true | undefined;
+    /**
+     * @internal The lane of each loader the capture's matched route registers
+     * (loader-cache.ts routeLoaderLanes), set by createMatchContextForFull
+     * before any loader runs. The capture's push funnel credits a push made
+     * under a live-lane loader's body, at any depth, to that loader
+     * (shell-capture.ts deriveShellCaptureContext).
+     */
+    loaderLanes: ReadonlyMap<string, "live" | "bake"> | undefined;
+    /**
+     * @internal Set by the capture guard (server/context.ts
+     * guardIdentityRead) when it throws DURING a capture render: the read
+     * ("cookies()", "headers()", `ctx.get() for a non-cacheable variable`,
+     * "ctx.theme") and the fix the
+     * refusal warning gives for it. Load-bearing for the
+     * bake lane: a guard throw inside an executing loader is swallowed by
+     * wrapLoaderPromise into per-loader error UI, which would otherwise bake
+     * silently into the shared shell — the capture checks this flag after the
+     * render and refuses instead. Deterministic, so the capture does not retry.
+     */
+    guardTripped: {
+        surface: string;
+        fix: string;
+    } | undefined;
+    /**
+     * @internal The loader $$id whose BODY was executing when the capture guard
+     * tripped (read off the loader-body ALS scope at trip time), or undefined
+     * when the read came from handler/render code. Only used to make the
+     * once-per-key refusal warning name the real source — the old text
+     * hardcoded "a bake-lane loader", which misattributed handler-land reads
+     * and sent users debugging the wrong lane (issue #672, secondary).
+     */
+    guardTrippedLoaderId: string | undefined;
+    /**
+     * @internal The freshness window of the route cache() records this
+     * capture read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+     * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+     * its scope's swr. The narrowest record wins. A shell capture caps its
+     * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+     * shell is never fresher, or served longer, than the route cache() entry
+     * it replayed or wrote.
+     */
+    routeRecordWindow: RouteRecordWindow | undefined;
+}
 /**
  * The derived capture context and its fresh (mask-funneled) handle store,
  * shared by BOTH shell producers: the runtime background capture

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

@@ -17,6 +17,7 @@
  */
 import { type EntryData } from "../server/context.js";
 import type { DocumentShellCacheEntry, ShellCacheEntry, ShellDocumentRead, ShellEntryHead, ShellReadStats, ShellSnapshotFailure, ShellSnapshotRecord, SegmentCacheStore } from "../cache/types.js";
+import type { MetricsStore } from "../server/context.js";
 export { PPR_REPLAY_STATUS_HEADER, SHELL_STATUS_HEADER, buildShellKey, navigationShellKey, partitionShellKey, shellSearchSeed, } from "./shell-capture-constants.js";
 /**
  * Default shell ttl (seconds) for `ppr: true` and for a PartialPrerenderProps
@@ -76,18 +77,13 @@ export declare function normalizeCaptureTimeout(value: unknown): number | undefi
  */
 export declare function resolvePprConfig(entry: EntryData | undefined | null): ResolvedPprConfig | null;
 /**
- * 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
+ * The request without the forced-MISS marker (`WIRE.shellMiss`), or
+ * undefined when it carries none. A document HIT that cannot finish its tail
+ * reloads the page with the marker (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
+ * calls this on entry, before anything reads the request, and keeps only the
+ * flag (RequestContext._shellForcedMiss): 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
@@ -165,6 +161,35 @@ export interface ShellDocument {
  */
 export declare function openShellDocument(entry: ShellCacheEntry): ShellDocument | null;
 export declare function openShellDocument(entry: ShellEntryHead, read: Pick<ShellDocumentRead, "prelude" | "snapshot" | "snapshotFailure" | "stats">): ShellDocument | null;
+/**
+ * A document serve's store read: a getShell entry, or a prelude-first read
+ * (readShellDocument) whose entry is the head and whose snapshot arrives on
+ * its own promise.
+ */
+export type ShellRead = {
+    entry: ShellCacheEntry;
+    shouldRevalidate?: boolean;
+    read?: undefined;
+} | {
+    entry: ShellEntryHead;
+    shouldRevalidate?: boolean;
+    read: ShellDocumentRead;
+};
+/**
+ * The document serve's shell read from `source`, the app cache store, that
+ * degrades to null on failure (axis 1 MISS, never a 500) and records the raw
+ * `ppr:shell-read` outcome (pre-validity-gates, so a version-mismatch
+ * lifecycle miss stays distinguishable from a store miss). A store with a
+ * prelude-first read (readShellDocument) resolves before the snapshot is
+ * read, so the HIT commits without waiting for it. A build shell is read by
+ * shell-build-manifest.ts lookupBuildShell, which imports this module.
+ */
+export declare function readShell(source: SegmentCacheStore & {
+    getShell: NonNullable<SegmentCacheStore["getShell"]>;
+}, key: string, opts: {
+    tagHints?: readonly string[];
+    metrics?: MetricsStore;
+}): Promise<ShellRead | 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:

package/dist/types/server/context.d.ts

@@ -121,7 +121,7 @@ export type LoaderEntry = {
      * thrown notFound()/redirect() deterministically precede first flush.
      * Resolved at DSL-evaluation time from ctx.isSSR — entries are cached
      * per-isSSR (router/manifest.ts cache key), so the flag is already
-     * request-mode-correct when resolveLoaders (fresh.ts) reads it and never
+     * request-mode-correct when resolveOwnerLoaders reads it and never
      * appears on navigation-lane entries. Set by documentModeLoader, which
      * getDocumentModeEntry also applies to a lazy include's captured ancestors.
      */
@@ -566,7 +566,7 @@ export interface IdentityReadWording {
  *    only observed; it is never rendered. A cached body, loader body or
  *    funnel they start is guarded again.
  * 1. A PPR shell capture (`ctx` is the capture's derived context,
- *    `_shellCaptureRun`) trips first: the capture context is flagged (so a
+ *    `_shellCaptureState`) trips first: the capture context is flagged (so a
  *    caught throw still refuses the capture) and the read throws. The shell is
  *    shared per host+URL, and every HIT replays what the capture read. There
  *    is no loader-body exemption here: a bake-lane loader and a loader a
@@ -737,12 +737,13 @@ export declare function latchPprHeaderScopeForEntries(entries: EntryData[], rout
  * ONLY the ppr (shell) axis is dropped — dynamic() does NOT opt off the CACHE
  * axis. Two cases:
  * - Pure ppr funnel (no cache() boundary): clear the latch → writes re-permit.
- * - ppr route nested under a cache() boundary: fresh.ts latches "ppr" at the
- *   funnel top (first-wins), which MASKS the positional cache() latch, but the
- *   handler still runs inside the cache scope (`insideCacheScope`). A cache()
- *   HIT skips that handler, so the write is still non-deterministic — UNMASK to
- *   "cache" instead of clearing, so the guard keeps throwing (accurate cache()
- *   wording). This is why the check keys off `insideCacheScope`, not just kind.
+ * - ppr route nested under a cache() boundary: resolveAllSegments
+ *   latches "ppr" at the funnel top (first-wins), which MASKS the positional
+ *   cache() latch, but the handler still runs inside the cache scope
+ *   (`insideCacheScope`). A cache() HIT skips that handler, so the write is
+ *   still non-deterministic — UNMASK to "cache" instead of clearing, so the
+ *   guard keeps throwing (accurate cache() wording). This is why the check keys
+ *   off `insideCacheScope`, not just kind.
  *
  * A subsequent cache() entered AFTER dynamic() on a pure-ppr funnel re-latches
  * "cache" via latchCachedHeaderScope's `!store.cachedHeaderScope` guard (the

package/dist/types/server/handle-store.d.ts

@@ -169,6 +169,22 @@ export interface HandleStore {
      * array, in order. Without placeholders it is a plain replay.
      */
     replacePlaceholders(loaderIds: readonly string[], deliver: () => void): void;
+    /**
+     * A cache() or Prerender() HIT restored its stored values into
+     * `segmentIds` (cache-lookup.ts serveStoredSegments). The MISS ran each
+     * segment's handler after it started the segment's loaders, so a push into
+     * a restored array goes in front of the stored values until
+     * releaseRecordedValues: a loader's push lands where the same loader timing
+     * puts it on the MISS.
+     */
+    holdRecordedValues(segmentIds: readonly string[]): void;
+    /**
+     * The HIT's loader walk reached the place where the MISS ran
+     * `segmentId`'s handler (revalidation.ts resolveLoadersOnly,
+     * intercept-resolution.ts resolveInterceptLoadersOnly): later pushes
+     * follow the record's values.
+     */
+    releaseRecordedValues(segmentId: string): void;
     /**
      * Get all collected handle data after all handlers have settled.
      * Waits for `settled` (handler lane), then returns the data at that point.

package/dist/types/server/render-pass.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Derived render passes over a request past its middleware (PPR shell
+ * capture, PPR HIT tail, background re-render, document cache re-run), each
+ * `Object.create(base)`.
+ * A field missing from a RENDER_PASS_FIELDS row reads the foreground
+ * request's value (#684). derived-context-shape.rsc-test.tsx pins each row's
+ * own keys.
+ */
+import type { RecordingShellStore } from "../cache/shell-snapshot.js";
+import type { HandleStore } from "./handle-store.js";
+import { type RequestContext } from "./request-context.js";
+type ShellImplicitCache = NonNullable<RequestContext["_shellImplicitCache"]>;
+/** _handleStore, readonly on RequestContext, is written by the rows. */
+type PassUnderConstruction = RequestContext<any> & {
+    _handleStore: HandleStore;
+};
+/** What each purpose's caller builds for its row. */
+export interface RenderPassInit {
+    "shell-capture": {
+        handleStore: HandleStore;
+        /** A navigation-only capture renders this URL instead of the request's. */
+        identity: {
+            request: Request;
+            url: URL;
+        } | undefined;
+        /** Only with a cache store on the request. */
+        recording: {
+            store: RecordingShellStore;
+            implicitCache: ShellImplicitCache;
+        } | undefined;
+    };
+    "ppr-tail": {
+        /** The request's store, shared: the tail's handles are this response's. */
+        handleStore: HandleStore;
+        loaderSeed: RequestContext["_shellLoaderSeed"];
+        implicitCache: ShellImplicitCache;
+    };
+    "background-revalidation": {
+        handleStore: HandleStore;
+        /** Throwaway: the pass's response writes land here and are dropped. */
+        sink: RequestContext<any>;
+    };
+    "document-revalidation": {
+        /** The request's: the stale HIT pushed nothing into it. */
+        handleStore: HandleStore;
+        /**
+         * Holds the re-run's response writes, which make the response the
+         * document cache stores; starts from the request's response stub.
+         */
+        sink: RequestContext<any>;
+    };
+}
+export type RenderPurpose = keyof RenderPassInit;
+interface PassFieldPolicy<I> {
+    /** "own": wireRenderBarrier(pass, init.handleStore) before `own` runs. */
+    readonly renderBarrier: "own" | "inherited";
+    /**
+     * Named stores, not one Object.assign: on Node 24 an Object.assign that
+     * takes the object to 20 own properties leaves it in V8 dictionary mode
+     * (#1109).
+     */
+    readonly own: (pass: PassUnderConstruction, init: I, base: RequestContext<any>) => void;
+}
+export declare const RENDER_PASS_FIELDS: {
+    readonly [P in RenderPurpose]: PassFieldPolicy<RenderPassInit[P]>;
+};
+/**
+ * `Object.create(base)` with RENDER_PASS_FIELDS[purpose]'s own fields. The only
+ * place a request context is derived (tools/check-internals.mjs).
+ */
+export declare function deriveRenderPass<P extends RenderPurpose, TEnv>(base: RequestContext<TEnv>, purpose: P, init: RenderPassInit[P]): RequestContext<TEnv>;
+export {};

package/dist/types/server/request-context.d.ts

@@ -29,6 +29,7 @@ import type { RenderMode, RenderPhase } from "../router/timeout.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import type { RoutineTrace } from "../rsc/routine-plan.js";
 import type { ActionContinuation } from "../rsc/server-action.js";
+import type { ShellCaptureState } from "../rsc/shell-capture.js";
 import type { FormActionOutcome } from "../rsc/progressive-enhancement.js";
 import { type ExecutionStart } from "../cache/invalidation-order.js";
 export interface RenderForegroundCursor {
@@ -182,8 +183,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     method: string;
     /**
      * @internal Handle store for tracking handle data across segments.
-     * Readonly: a background render that needs its own store derives a context
-     * (rerenderAndCacheRoute, shell-capture.ts) instead of swapping this field,
+     * Readonly: a render that needs its own store derives a render pass
+     * (deriveRenderPass, server/render-pass.ts) instead of swapping this field,
      * which the foreground still reads while it produces the page.
      */
     readonly _handleStore: HandleStore;
@@ -233,52 +234,13 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _searchParamsFilter?: import("../cache/search-params-filter.js").SearchParamsFilter;
     /**
-     * @internal PPR shell-capture ACTIVE marker. True ONLY inside the background
-     * capture task's derived request context (built by shell-capture.ts). This is
-     * the switch every capture-specific behavior reads: loader masking
-     * (loader-mask.ts isShellCaptureActive / fresh.ts emitStreaming) and the
-     * identity-read capture guard (server/context.ts guardIdentityRead). The
-     * foreground render never sets it, so the
-     * served response is byte-identical to axis 1. The capture descriptor itself
-     * (key/ttl/swr/tags/store) is NOT threaded through the request context — the
-     * integrated PPR serve path (rsc/shell-serve.ts + rsc-rendering.ts) builds it
-     * locally and passes it to scheduleShellCapture directly.
-     */
-    _shellCaptureRun?: boolean;
-    /**
-     * @internal Set beside `_shellCaptureRun` when the shell is keyed by the
-     * visitor's URL (`rewrite(...).shell("visitor")`): the capture renders the
-     * visitor's location and `ctx.rewrittenFrom`; the theme stays the default.
-     */
-    _shellCaptureForVisitor?: boolean;
-    /**
-     * @internal Bake-lane loader containers collected DURING a shell capture:
-     * segment-key -> the loader's (pre-wrap) result promise. Populated by
-     * resolveLoaderData for bake-lane loaders (lane rule: see its JSDoc in
-     * loader-cache.ts). Drained by captureAndStoreShell after the shell
-     * quiesces: settled containers are promise-elided, Flight-serialized, and
-     * pinned into the snapshot's loader family; a REJECTED container refuses
-     * the capture (error UI must never bake into the shared shell). Own
-     * property of the capture's derived context only.
-     */
-    _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
-    /**
-     * @internal Set on a capture's derived context when a loader pushed a
-     * value the record cannot keep (masked nested promises, a pushed promise
-     * that settled to one, a live-lane loader's push, or a push outside a
-     * loader body): the loader records then carry `runs: 1`, so a HIT still
-     * runs their bodies for those pushes.
-     */
-    _shellCaptureUnrecordedLoaderPush?: true;
-    /**
-     * @internal The lane of each loader the capture's matched route registers
-     * (loader-cache.ts routeLoaderLanes), set by createMatchContextForFull
-     * before any loader runs. The capture's push funnel credits a push made
-     * under a live-lane loader's body, at any depth, to that loader
-     * (shell-capture.ts deriveShellCaptureContext). Own property of the
-     * capture's derived context only.
-     */
-    _shellCaptureLoaderLanes?: ReadonlyMap<string, "live" | "bake">;
+     * @internal A PPR shell capture's own state (rsc/shell-capture.ts
+     * ShellCaptureState): created by RENDER_PASS_FIELDS["shell-capture"]
+     * (server/render-pass.ts) on the capture's derived context. The foreground
+     * render and every background re-render never have one, so
+     * `_shellCaptureState?.run` is the capture switch.
+     */
+    _shellCaptureState?: ShellCaptureState;
     /**
      * @internal Record keys resolved for this request (CacheScope
      * resolveKeyFrom): by the scope's `key()` (one result) or its store's
@@ -295,9 +257,9 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _shellKey?: string;
     /**
      * @internal The request carried the forced-MISS reload marker
-     * (shell-serve.ts SHELL_MISS_PARAM). The handler strips the marker from the
-     * request on entry and sets this; the shell gate renders the request like a
-     * cache miss.
+     * (`WIRE.shellMiss`). The handler strips the marker from the request on
+     * entry (shell-serve.ts withoutShellMissMarker) and sets this; the shell
+     * gate renders the request like a cache miss.
      */
     _shellForcedMiss?: true;
     /**
@@ -314,16 +276,6 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * runtime has no AsyncLocalStorage.snapshot.
      */
     _runAtRequestEntry?: <T>(fn: () => T) => T;
-    /**
-     * @internal The freshness window of the route cache() records this
-     * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
-     * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
-     * its scope's swr. The narrowest record wins. A shell capture caps its
-     * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
-     * shell is never fresher, or served longer, than the route cache() entry
-     * it replayed or wrote.
-     */
-    _routeRecordWindow?: RouteRecordWindow;
     /**
      * @internal Loader-family snapshot seed for a shell HIT's tail render:
      * loader id -> the capture's elided container (already Flight-deserialized
@@ -445,30 +397,6 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * it as an own property for exactly that reason.
      */
     _shellFragmentPayload?: boolean;
-    /**
-     * @internal Set by the capture guard (server/context.ts
-     * guardIdentityRead) when it throws DURING a capture render: the read
-     * ("cookies()", "headers()", `ctx.get() for a non-cacheable variable`,
-     * "ctx.theme") and the fix the
-     * refusal warning gives for it. Load-bearing for the
-     * bake lane: a guard throw inside an executing loader is swallowed by
-     * wrapLoaderPromise into per-loader error UI, which would otherwise bake
-     * silently into the shared shell — the capture checks this flag after the
-     * render and refuses instead. Deterministic, so the capture does not retry.
-     */
-    _shellCaptureGuardTripped?: {
-        surface: string;
-        fix: string;
-    };
-    /**
-     * @internal The loader $$id whose BODY was executing when the capture guard
-     * tripped (read off the loader-body ALS scope at trip time), or undefined
-     * when the read came from handler/render code. Only used to make the
-     * once-per-key refusal warning name the real source — the old text
-     * hardcoded "a bake-lane loader", which misattributed handler-land reads
-     * and sent users debugging the wrong lane (issue #672, secondary).
-     */
-    _shellCaptureGuardTrippedLoaderId?: string;
     /**
      * @internal Handler-owned registry of explicit per-scope stores from
      * cache({ store }). Created once per createRSCHandler() and threaded into
@@ -732,8 +660,8 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * (loader(Def, { ssr: false })): segment resolution awaits these
      * before returning, so the render barrier cannot resolve until they settle.
      * rendered() checks this set to fail fast — a flagged loader awaiting the
-     * barrier is a guaranteed cycle, not a race. Registered by resolveLoaders
-     * (fresh.ts) before loader kickoff; only ever populated on document renders
+     * barrier is a guaranteed cycle, not a race. Registered by resolveOwnerLoaders
+     * before loader kickoff; only ever populated on document renders
      * (the flag is stamped per-isSSR at DSL evaluation).
      */
     _awaitBeforeFlushLoaderIds?: Set<string>;
@@ -811,6 +739,12 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      * keeping phases that began before the opt-in at their true (non-negative) offset.
      */
     _handlerStart?: number;
+    /**
+     * @internal Handler-level Server-Timing entries (rsc/handler.ts): the
+     * bootstrap timings, then the core handler's classify. A stale document
+     * cache entry's re-run has its own (render-pass.ts).
+     */
+    _handlerTiming?: string[];
     /** @internal Resolved platform phase-span tracing for this request (Cloudflare or OTel) */
     _tracing?: ResolvedTracing;
     /** @internal Router basename for this request (used by redirect()) */
@@ -846,27 +780,13 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
      */
     _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
-/**
- * @internal The freshness window of a route cache() record, as ms
- * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
- * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
- * the record that sets `staleUntil`: its cache() config, and whether this
- * request wrote it (cacheRoute) rather than read it.
- */
-export interface RouteRecordWindow {
-    freshUntil: number;
-    staleUntil: number;
-    ttl: number;
-    swr: number;
-    written: boolean;
-}
 /**
  * Public view of RequestContext, without internal methods and fields.
  *
  * This is the type exported to library consumers. Internal code should
  * use the full RequestContext interface directly.
  */
-export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureRun" | "_shellCaptureForVisitor" | "_shellImplicitCache" | "_shellLoaderSeed" | "_shellCaptureLoaderRecords" | "_shellCaptureUnrecordedLoaderPush" | "_shellCaptureLoaderLanes" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_routeRecordWindow" | "_shellFragmentPayload" | "_shellCaptureGuardTripped" | "_shellCaptureGuardTrippedLoaderId" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
+export type PublicRequestContext<TEnv = DefaultEnv, TParams = Record<string, string>> = Omit<RequestContext<TEnv, TParams>, "cookie" | "cookies" | "_readCookie" | "_readCookies" | "setCookie" | "deleteCookie" | "_handleStore" | "_transitionWhenRefs" | "_pprReplayPostMatchReason" | "_cacheStore" | "_prerender" | "_onDemandProducer" | "_searchParamsFilter" | "_shellCaptureState" | "_shellImplicitCache" | "_shellLoaderSeed" | "_resolvedCacheKeys" | "_shellKey" | "_shellForcedMiss" | "_prerenderWarm" | "_runAtRequestEntry" | "_shellFragmentPayload" | "_explicitTaggedStores" | "_requestTags" | "_recordTagOwners" | "_recordLoaderTags" | "_cacheProfiles" | "_onResponseCallbacks" | "_pendingBackgroundTasks" | "_themeConfig" | "_readTheme" | "_documentCacheRender" | "_payloadVisitorTheme" | "_payloadDeferred" | "_requestKind" | "_payloadVisitorLocation" | "_locationState" | "_routeName" | "_prevRouteKey" | "_visitorMoved" | "_inActionRevalidation" | "_actionRan" | "_reportedErrors" | "_printedErrors" | "_renderErrors" | "_recoveredHandlerErrors" | "_renderBarrier" | "_resolveRenderBarrier" | "_renderBarrierSegmentOrder" | "_treeHasStreaming" | "_renderBarrierWaiters" | "_handlerLoaderDeps" | "_awaitBeforeFlushLoaderIds" | "_renderBarrierHandleSnapshot" | "_renderBarrierGuardClosed" | "_reportBackgroundError" | "_debugPerformance" | "_metricsStore" | "_renderForeground" | "_activeRoutine" | "_renderDiagnosticsEnabled" | "_handlerStart" | "_handlerTiming" | "_tracing" | "_basename" | "_routerId" | "_versions" | "_setStatus" | "_rotateStateCookie" | "_setKeepCacheDirective" | "_freshReads" | "_setFreshReadsCookie" | "_requestRoot" | "_requestStart" | "_responseSent" | "_variables" | "_classifiedRoute" | "_requestMode" | "_cacheSignal" | "_dynamic" | "res">;
 /**
  * Marker for a waitUntil-scheduled fn whose task promise must NOT enter
  * _pendingBackgroundTasks. Used by the PPR shell capture for its own task:
@@ -1004,8 +924,8 @@ export declare function rebaseRequestContext(ctx: RequestContext<any>, request:
 /**
  * Wire a fresh render barrier onto `ctx`, closure-bound to THIS ctx and THIS
  * handle store. Called by createRequestContext for every fresh context, and by
- * deriveShellCaptureContext (rsc/shell-capture.ts) for the PPR capture's
- * derived context.
+ * deriveRenderPass (server/render-pass.ts) for a derived pass whose
+ * RENDER_PASS_FIELDS row owns its barrier (the PPR capture and the HIT tail).
  *
  * The derived-context call is load-bearing (issue #684, plan 009): the capture
  * context is `Object.create(reqCtx)`, so without its own wiring every