@rangojs/router 0.27.0 → 0.29.0

package/dist/types/rsc/request-stages.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Request stages
+ *
+ * The stages a request runs through before and after rendering: classify,
+ * guard, the global middleware passes, the response route, and the
+ * response's finalization. The RSC handler (rsc/handler.ts createRSCHandler)
+ * runs them all around its Flight executor. The dispatch testing primitive
+ * (testing/dispatch.ts) runs classify, the terminal plans, the passes, the
+ * response route and the finalization, and throws where a plan would render
+ * a component. Sharing them keeps dispatch's responses identical to
+ * production's; a hand-kept mirror drifted once (#1128).
+ *
+ * No import of @vitejs/plugin-rsc on this graph: dispatch loads it in a
+ * plain Vitest project, where plugin-rsc's entries cannot load (they import
+ * Vite virtuals). testing/__tests__/testing-module-graph.test.ts pins it.
+ */
+import type { MiddlewareEntry } from "../router/middleware-types.js";
+import { type RequestContext } from "../server/request-context.js";
+import { type RewritePassesOptions, type RewritePassesResult } from "./rewrite-passes.js";
+import { type ResponseRouteMatch } from "./response-route-handler.js";
+import type { ErrorPhase } from "../types.js";
+import type { OnErrorCallback } from "../types/error-types.js";
+import { type InvokeOnErrorContext } from "../router/error-handling.js";
+import type { OriginCheckPhase } from "./origin-guard.js";
+import { type OnTimeoutCallback, type ResolvedTimeouts, type TimeoutPhase } from "../router/timeout.js";
+import { type TelemetrySink } from "../router/telemetry.js";
+import { type ClassifyRequestDeps, type ExecutableRequestPlan, type RequestPlan, type ResponseRoutePlan } from "../router/request-classification.js";
+/**
+ * The router members the stages read. The handler's `RangoInternal` carries
+ * them; dispatch reads them off the router a test passes.
+ */
+export interface StageRouter<TEnv = unknown> {
+    readonly basename: string | undefined;
+    readonly middleware: MiddlewareEntry<TEnv>[];
+    readonly onError?: OnErrorCallback<TEnv>;
+    readonly telemetry?: TelemetrySink;
+    readonly timeouts?: ResolvedTimeouts;
+    readonly onTimeout?: OnTimeoutCallback<TEnv>;
+}
+/** Report an error through the router's onError. */
+export type ReportError<TEnv = unknown> = (error: unknown, phase: ErrorPhase, context: InvokeOnErrorContext<TEnv>) => void;
+/**
+ * What the stages call back into. The handler's context bundle
+ * (rsc/handler-context.ts HandlerContext) extends it.
+ */
+export interface RequestStageContext<TEnv = unknown> {
+    router: StageRouter<TEnv>;
+    callOnError: ReportError<TEnv>;
+    getRequiredRouteMap: () => Record<string, string>;
+    /**
+     * The redirect a partial or action request receives: a Flight payload in
+     * the handler (fetch() would follow a raw 3xx to HTML). dispatch has no
+     * Flight runtime and answers 204 + X-RSC-Redirect.
+     */
+    createRedirectFlightResponse: (redirectUrl: string, locationState?: Record<string, unknown>, external?: boolean) => Response;
+    /**
+     * Reports a response-route handler's own throw; absent, it goes to
+     * callOnError with phase "handler". dispatch passes a no-op: it does not
+     * report that throw (its documented boundary, testing/dispatch.ts).
+     */
+    reportResponseRouteError?: (error: unknown, context: InvokeOnErrorContext<TEnv>) => void;
+}
+/** What classify and the terminal plans read beyond the stage context. */
+export interface ClassifyContext<TEnv = unknown> {
+    router: {
+        readonly id: string;
+        readonly findMatch: ClassifyRequestDeps<TEnv>["findMatch"];
+    };
+    /** The router's DOCUMENT version: the `_rsc_v` reload check. */
+    version: string;
+}
+/**
+ * Per-request error reporter that deduplicates via the ALS request context.
+ *
+ * Uses the same _reportedErrors WeakSet as the router layer so errors
+ * that propagate across layers are only reported once per request.
+ */
+export declare function createErrorReporter<TEnv>(router: {
+    readonly onError?: OnErrorCallback<TEnv>;
+}): ReportError<TEnv>;
+/**
+ * Wire background error reporting so "use cache" and other subsystems can
+ * surface non-fatal errors through the router's onError callback.
+ */
+export declare function reportBackgroundErrors<TEnv>(reqCtx: RequestContext<TEnv>, request: Request, url: URL, callOnError: ReportError<TEnv>): void;
+/**
+ * Classify a request into its plan. classifyRequest throws
+ * RouteNotFoundError for an unknown route; that falls through to a
+ * full-render plan with no matched route, so the render path renders the
+ * 404 page (match()/matchPartial() re-throw and the render's catch renders
+ * it).
+ */
+export declare function classify<TEnv>(request: Request, url: URL, ctx: ClassifyContext<TEnv>): Promise<RequestPlan<TEnv>>;
+/** The plan classify answers an unknown route with (the render path's 404). */
+export declare function isUnmatchedPlan(plan: RequestPlan<any>): boolean;
+/**
+ * Record a plan's route on the request context: its params and name, and the
+ * classified snapshot match()/matchPartial() reuse instead of resolving the
+ * route again. Runs inside the global chain, so global middleware sees the
+ * route after next(). A redirect has none.
+ */
+export declare function recordPlanRoute<TEnv>(plan: ExecutableRequestPlan<TEnv>): void;
+/**
+ * The checks between classification and execution that need no await.
+ * Returns the response of a terminal plan (a partial request's redirect, a
+ * version or app-switch reload), null to go on. Throws for a rewritten
+ * action whose target is not a page route.
+ *
+ * Synchronous, and the origin guard is a separate step: the caller awaits
+ * checkRequestOrigin only for the modes ORIGIN_CHECK_PHASE_BY_MODE gates, so
+ * a full, partial or response plan reaches execution without an added
+ * microtask (rsc/__tests__/request-microtasks.rsc-test.tsx).
+ */
+export declare function terminalPlanResponse<TEnv>(plan: RequestPlan<TEnv>, url: URL, ctx: RequestStageContext<TEnv> & ClassifyContext<TEnv>): Response | null;
+/**
+ * The origin guard's rejection: reports it through onError and telemetry,
+ * and returns the response checkRequestOrigin rejected the request with. The
+ * caller awaits checkRequestOrigin itself, for the modes
+ * ORIGIN_CHECK_PHASE_BY_MODE gates (action, loader, PE form), so the guard
+ * adds no microtask over that await.
+ */
+export declare function originRejectedResponse<TEnv>(rejection: Response, phase: OriginCheckPhase, request: Request, env: TEnv, url: URL, ctx: RequestStageContext<TEnv>): Response;
+export interface RequestPassesOptions<TEnv> {
+    ctx: RequestStageContext<TEnv>;
+    reqCtx: RequestContext<TEnv>;
+    /** The visitor's request and raw URL: the first pass. */
+    request: Request;
+    url: URL;
+    env: TEnv;
+    variables: Record<string, any>;
+    /** The visitor's global middleware, when the caller matched it already. */
+    firstPassMiddleware?: Array<{
+        entry: MiddlewareEntry<TEnv>;
+        params: Record<string, string>;
+    }>;
+    /** Runs before a pass's global chain; dispatch matches the pass there. */
+    beforePass?: (request: Request, url: URL, index: number) => Promise<void>;
+    /** The core handler a pass's global chain wraps. */
+    core: (request: Request, url: URL) => Promise<Response>;
+    onHop?: RewritePassesOptions["onHop"];
+    refuse?: RewritePassesOptions["refuse"];
+}
+export interface RequestPassesResult extends RewritePassesResult {
+    /** Whether the last pass ran a global middleware chain. */
+    hasMiddleware: boolean;
+}
+/**
+ * One pass per URL: the global middleware chain matched on the pass's path,
+ * wrapping the core handler. A `throw rewrite()` from global or route
+ * middleware unwinds the pass, and the next one runs the same request as
+ * the target from the top, as a direct visit would (rsc/rewrite-passes.ts).
+ */
+export declare function runRequestPasses<TEnv>(opts: RequestPassesOptions<TEnv>): Promise<RequestPassesResult>;
+/**
+ * The flat match handleResponseRoute takes, with params at the top level,
+ * built from a response-route plan.
+ */
+export declare function responseRouteMatch(plan: ResponseRoutePlan<any>): ResponseRouteMatch;
+export interface ServeResponseRouteOptions<TEnv> {
+    match: ResponseRouteMatch;
+    /** The matched route's key, for the timeout report. */
+    routeKey: string | undefined;
+    /** The pass's request, raw URL and env. */
+    request: Request;
+    url: URL;
+    env: TEnv;
+    variables: Record<string, any>;
+    /**
+     * Receives the handler's work when the deadline wins. The handler leaves
+     * it running; dispatch cancels its body.
+     */
+    abandon?: (work: Promise<Response>) => void;
+}
+/**
+ * A response route: its handler (rsc/response-route-handler.ts) under the
+ * renderStartMs deadline, which starts here, inside the global chain, so
+ * global middleware time never counts toward it.
+ */
+export declare function serveResponseRoute<TEnv>(ctx: RequestStageContext<TEnv>, opts: ServeResponseRouteOptions<TEnv>): Promise<Response>;
+/**
+ * Handle a timeout by reporting the error, emitting telemetry,
+ * and returning either the custom onTimeout response or a default 504.
+ */
+export declare function timeoutResponse<TEnv>(ctx: RequestStageContext<TEnv>, request: Request, env: TEnv, url: URL, phase: TimeoutPhase, durationMs: number, routeKey?: string, actionId?: string): Promise<Response>;
+export interface FinalizeRequestOptions<TEnv> {
+    ctx: RequestStageContext<TEnv>;
+    reqCtx: RequestContext<TEnv>;
+    /** The visitor's request, raw URL and env. */
+    request: Request;
+    url: URL;
+    env: TEnv;
+    /** runRequestPasses' result. */
+    hasMiddleware: boolean;
+    rewrittenTo?: string;
+    /** Runs on the response before the open-redirect guard. */
+    beforeGuard?: (response: Response) => void;
+}
+/**
+ * The response the global chain returned, made ready to leave: a partial or
+ * action request's redirect converted, onResponse callbacks drained, the
+ * rewrite header, the open-redirect guard and the stream-idle watchdog.
+ */
+export declare function finalizeRequestResponse<TEnv>(downstream: Response, opts: FinalizeRequestOptions<TEnv>): Response;

package/dist/types/rsc/response-cache-serve.d.ts

@@ -5,23 +5,18 @@
  * matched entry tree, condition eval, key resolution (route key() > store
  * keyGenerator > default, CacheScope.resolveKeyFrom), tag resolution,
  * pre-handler-callback timing, and the fresh-hit / SWR-revalidate /
- * miss-write branches — for BOTH the production
- * response-route handler (rsc/response-route-handler.ts) and the dispatch testing
- * primitive (testing/dispatch.ts), so the two can never drift.
+ * miss-write branches — for the response-route handler
+ * (rsc/response-route-handler.ts), which the production handler and the
+ * dispatch testing primitive both run (rsc/request-stages.ts
+ * serveResponseRoute), so the two can never drift.
  *
- * Plugin-rsc hazard: cache-scope.ts pulls @vitejs/plugin-rsc (via segment-codec),
- * which the non-Vite unit-test runner cannot resolve, and this module is on the
- * testing barrel's EAGER graph (dispatch imports it). So `createCacheScope` is
- * NOT imported here at runtime — it is INJECTED by the caller (production
- * imports it statically; dispatch lazy-imports it only once a response route
- * matches). The only runtime imports here are plugin-rsc-free
- * (helpers' isCacheableStatus/finalizeResponse, traverseBack); cache-scope is a
- * type-only import (erased at build).
+ * `createCacheScope` is injected by the caller: the response-route handler
+ * passes the real one, unit tests a stub.
  */
 import type { CacheScope } from "../cache/cache-scope.js";
 import { type RequestContext } from "../server/request-context.js";
 import type { EntryCacheConfig, EntryData } from "../server/context.js";
-/** Injected cache-scope builder (kept off this module's runtime import graph). */
+/** Injected cache-scope builder. */
 export interface CacheScopeDeps {
     createCacheScope: (config: EntryCacheConfig | undefined, parent?: CacheScope | null) => CacheScope | null;
 }

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

@@ -7,7 +7,7 @@
  */
 import type { MiddlewareFn } from "../router/middleware.js";
 import { type EntryData } from "../server/context.js";
-import type { HandlerContext } from "./handler-context.js";
+import type { RequestStageContext } from "./request-stages.js";
 export interface ResponseRouteMatch {
     responseType: string;
     handler: Function;
@@ -26,4 +26,4 @@ export interface ResponseRouteMatch {
  * For partial (client-side navigation) requests, returns X-RSC-Reload
  * so the browser triggers a hard navigation to the response route URL.
  */
-export declare function handleResponseRoute<TEnv>(handlerCtx: HandlerContext<TEnv>, preview: ResponseRouteMatch, request: Request, env: TEnv, url: URL, variables: Record<string, any>): Promise<Response>;
+export declare function handleResponseRoute<TEnv>(handlerCtx: Pick<RequestStageContext<TEnv>, "callOnError" | "getRequiredRouteMap" | "reportResponseRouteError">, preview: ResponseRouteMatch, request: Request, env: TEnv, url: URL, variables: Record<string, any>): Promise<Response>;

package/dist/types/rsc/routine-plan.d.ts

@@ -62,7 +62,7 @@ export declare function step<T>(name: string, execute: () => T | Promise<T>): Ro
  *
  * Settlement tracking follows the RETURNED value: a returned promise is
  * observed until it settles; a scheduler that fires-and-forgets internally
- * (e.g. scheduleShellCapture via runBackground) returns void, so its trace
+ * (e.g. planShellCapture via runBackground) returns void, so its trace
  * entry settles at the scheduling call, not at background completion. That is
  * deliberate — the plan's contract ends at the handoff.
  */

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

@@ -27,8 +27,8 @@ import type { MatchResult } from "../types.js";
  * the revalidation phase so it runs INSIDE the same route-middleware wrapper as
  * a successful revalidation — route middleware (context vars, headers, cookies)
  * must apply to the error render too, matching the module doc's "identical to a
- * normal render". When `errorBoundary` is set, `actionContext` is unused (the
- * boundary is already matched; no matchPartial is run).
+ * normal render". That render is the action's revalidation, cut at the
+ * boundary (ActionContext.boundary).
  */
 export interface ActionContinuation {
     returnValue: {

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

@@ -139,7 +139,7 @@ export declare const POST_QUIESCE_TASK_HOPS = 16;
  * short is an acceptable loss — every terminal path backs the key off anyway),
  * and below workerd's ~30s waitUntil grace so the cap timer still fires in a
  * live context. When workerd kills the context BEFORE the cap fires, the timer
- * dies with it — that stranding is healed by scheduleShellCapture's staleness
+ * dies with it — that stranding is healed by planShellCapture's staleness
  * check on the stampede guard, keyed off the same constant.
  */
 export declare const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25000;

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.