@rangojs/router 0.27.0 → 0.29.0

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>;
@@ -755,6 +683,15 @@ export interface RequestContext<TEnv = DefaultEnv, TParams = Record<string, stri
     _renderBarrierGuardClosed?: boolean;
     /** @internal Per-request error dedup set for onError reporting */
     _reportedErrors: WeakSet<object>;
+    /**
+     * @internal The segment a parallel slot's or orphan layout's error came
+     * from, for the owning entry's catch (segment-resolution/helpers.ts
+     * noteThrower). Per request: an error object can be thrown by several.
+     */
+    _throwers?: WeakMap<object, {
+        id: string;
+        type: string;
+    }>;
     /**
      * @internal The errors this request printed to the server console, so a
      * failure prints once where it originated (server/print-server-error.ts). A derived context shares it through the prototype.
@@ -811,6 +748,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 +789,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" | "_throwers" | "_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:
@@ -896,6 +825,26 @@ export declare function captureRequestEntryContext(): (<T>(fn: () => T) => T) |
  * Used by the RSC handler to provide context to server actions
  */
 export declare function runWithRequestContext<TEnv, T>(context: RequestContext<TEnv>, fn: () => T): T;
+/**
+ * Run work whose output goes only to a cache, never to the response of the
+ * request that started it, on `context`: a stale entry's refresh (a "use
+ * cache" function, a cached loader, a cache() record, a document), a
+ * navigation's proactive cache() write, a PPR shell capture. No visitor made
+ * the invalidations in it, so they set no fresh-reads cookie
+ * (cache/tag-invalidation.ts), and onError marks every error reported inside
+ * it `background` (router/error-handling.ts invokeOnError). Its failure is
+ * reported inside it too: a catch outside runs on the visitor's frame.
+ */
+export declare function runAsBackgroundWork<TEnv, T>(context: RequestContext<TEnv>, fn: () => T): T;
+/** Whether the caller runs inside runAsBackgroundWork. */
+export declare function isBackgroundWork(): boolean;
+/**
+ * The set onError's dedupe records a reported error in. Background work keeps
+ * its own: an error object both the visitor's render and background work
+ * reach (a memoized rejection, a thrown constant) is reported by each, so a
+ * background report never takes the place of the visitor's.
+ */
+export declare function reportedErrorsOf(context: RequestContext<any>): WeakSet<object>;
 /**
  * Get the current request context
  * Throws if called outside of a request context
@@ -1004,8 +953,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

package/dist/types/server/rewrite-trail.d.ts

@@ -25,12 +25,12 @@ export declare function recordRewriteHop(reqCtx: TrailContext, from: URL, to: UR
 export declare function recordRewriteShell(reqCtx: TrailContext, audience: RewriteShell | undefined): void;
 /** The last hop's `rewrite(...).shell()` choice; undefined: none. */
 export declare function rewriteShellAudience(reqCtx: TrailContext | undefined): RewriteShell | undefined;
-type AudienceContext = Pick<RequestContext<any>, "_shellCaptureRun" | "_documentCacheRender" | "res">;
+type AudienceContext = Pick<RequestContext<any>, "_shellCaptureState" | "_documentCacheRender" | "res">;
 /**
  * A render other visitors may be served: a PPR shell capture, or a render
  * the document cache stores (its response opted in before next()). It shows
  * no visitor theme, and no visitor URL unless it is a visitor-keyed shell
- * capture (`_shellCaptureForVisitor`).
+ * capture (`_shellCaptureState.forVisitor`).
  */
 export declare function rendersForSharedAudience(reqCtx: AudienceContext): boolean;
 /**

package/dist/types/testing/dispatch.d.ts

@@ -2,9 +2,12 @@
  * dispatch — in-process request -> Response for unit/integration tests,
  * WITHOUT the Flight RSC runtime.
  *
- * dispatch runs the router's real matching and middleware execution so that
- * redirects, 404s, response routes (path.json / path.text / path.html / ...),
- * and middleware short-circuits behave exactly as in production. It deliberately
+ * dispatch runs the production handler's request stages
+ * (rsc/request-stages.ts: classify, the terminal plans, the global middleware
+ * passes, the response route and the response's finalization) so that
+ * redirects, 404s, reloads, response routes (path.json / path.text /
+ * path.html / ...), and middleware short-circuits behave exactly as in
+ * production. It deliberately
  * does NOT render React Server Components: there is no Flight stream, no SSR,
  * and no DOM. Hit an RSC (component) route and dispatch throws a clear error
  * directing you to renderToFlightString/renderServerTree/renderHandler or an e2e test.
@@ -17,19 +20,20 @@
  *   so a global auth middleware can 401/redirect them and middleware-set
  *   cookies/headers merge onto the 308/404 the way createResponseWithMergedHeaders
  *   merges them in production.
- * - Response routes (non-RSC)                         -> serialized Response
+ * - Response routes (non-RSC), served by production's handleResponseRoute
+ *   (rsc/response-route-handler.ts)                  -> serialized Response
  *   - json:           JSON.stringify(result) (bare value) with application/json
  *   - text/html/xml/md: String(result) with the mapped MIME type
- *   - handler returning or throwing a Response:         re-wrapped like
- *     handleResponseRoute (stub headers/cookies merged, Set-Cookie preserved,
- *     WebSocket upgrade passed through without reconstruction)
+ *   - handler returning or throwing a Response:         re-wrapped (stub
+ *     headers/cookies merged, Set-Cookie preserved, WebSocket upgrade passed
+ *     through without reconstruction)
  *   - handler throwing a non-Response error:            typed 500 / RouterError
- *     status, matching handleResponseRoute (RFC 9457 problem+json body with
- *     application/problem+json for json routes, text/plain message otherwise)
+ *     status (RFC 9457 problem+json body with application/problem+json for
+ *     json routes, text/plain message otherwise)
  *   - content-negotiated route:                         Vary: Accept appended
  *   - cached response route (cache({...})):             getResponse/putResponse
- *     hit/SWR/tag write, resolved from the matched entry tree exactly as
- *     handleResponseRoute does. The write is scheduled via ctx.waitUntil
+ *     hit/SWR/tag write, resolved from the matched entry tree. The write is
+ *     scheduled via ctx.waitUntil
  *     (a microtask without an executionContext), so a HIT-asserting test must
  *     flush microtasks between the seeding dispatch and the asserting one.
  * - Global middleware (router.use(...)) AND route-level middleware, with full
@@ -38,10 +42,17 @@
  *   global middleware runs first (so an auth gate can still 401/redirect),
  *   then — if it passes through — an X-RSC-Reload is returned. Route-level
  *   middleware is skipped on a partial, exactly as production skips it.
- * - A middleware redirect (3xx + Location) on a partial/action request
- *   (?_rsc_partial / ?_rsc_action): converted to a 204 + X-RSC-Redirect via the
- *   real interceptRedirectForPartial, so fetch() does not auto-follow the 3xx —
+ * - A global middleware redirect (3xx + Location) on a partial/action request
+ *   (?_rsc_partial / ?_rsc_action), and a findMatch() redirect on a partial
+ *   request: a 204 + X-RSC-Redirect, so fetch() does not auto-follow the 3xx —
  *   identical to production's no-location-state path.
+ * - The terminal plans production answers inside the global chain
+ *   (terminalPlanResponse): a `_rsc_v` version mismatch and a `_rsc_rid` app
+ *   switch reload (X-RSC-Reload), and an action (?_rsc_action) a rewrite moved
+ *   to a target that is not a page route throws production's error.
+ * - Route params and name are set inside the global chain, after classify, by
+ *   the stage production's executeRequest runs (recordPlanRoute): global
+ *   middleware sees them after next(), not before it.
  * - The open-redirect guard (rsc/redirect-guard.ts) on full (browser-followed)
  *   redirects: a cross-origin Location is rewritten to the basename root unless
  *   redirect(url, { external: true }) opted out, mirroring production's single
@@ -60,7 +71,9 @@
  *   after finalizeResponse (segmentCount 0 / cacheHit false — dispatch renders no
  *   RSC segments and holds no match-cache state), and a thrown non-Response error
  *   emits request.error with phase "routing". All three carry the same requestId
- *   (getRequestId). Emission is gated entirely on a configured sink; with none,
+ *   (getRequestId), as does a response-route timeout on a rewritten pass
+ *   (runRequestPasses carries the id to each pass's request, as in
+ *   production). Emission is gated entirely on a configured sink; with none,
  *   dispatch does zero new work and stays byte-identical for existing callers.
  *   Lets a consumer unit-test their sink wiring in-process instead of only at e2e.
  * - Response-route `renderStartMs` timeouts and `onTimeout`: dispatch races the
@@ -96,9 +109,13 @@
  *   request.start/end/error lifecycle above; cover cache/loader telemetry with an
  *   e2e test driving a real RSC request.
  *
- * dispatch reuses router.previewMatch(), which itself runs content negotiation
- * and resolves route middleware from the matched entry tree, so dispatch's
- * route-middleware collection is exactly the router's, not a re-implementation.
+ * Each pass is classified with the handler's classify stage
+ * (router/request-classification.ts classifyRequest), which runs content
+ * negotiation and resolves route middleware from the matched entry tree, so
+ * dispatch's route-middleware collection is exactly the router's, not a
+ * re-implementation. The origin guard is not run: it gates only the action,
+ * loader and PE-form plans, which classify gives a component route only, and
+ * dispatch throws on those before the pass's middleware.
  */
 import type { Rango } from "../router/router-interfaces.js";
 /**

package/dist/types/testing/render-route.d.ts

@@ -26,24 +26,30 @@
  *   - navigate() drives the navigation lifecycle as a click does:
  *     useNavigation() reads loading from the call and idle with the commit,
  *     and useLinkStatus().pending is true for a link to the destination until
- *     the commit is handed to React. A `transition` spec plus a pending
+ *     the commit, which React holds with it. A `transition` spec plus a pending
  *     Promise seeded via navigate(url, { loaders }) commits through
  *     production's commitInTransition (browser/partial-update.ts), which React
  *     holds: useNavigation() stays loading and the held reader's
  *     useLoader().isLoading reads true until the data lands. Without
  *     `transition` the commit is urgent (production's same-structure hold is
- *     not modeled). useAction().state stays idle: no action runs.
+ *     not modeled). navigate(url, { streamUntil }) gives the navigation a
+ *     response stream that stays open past the commit (isStreaming).
+ *     useAction().state stays idle: no action runs.
  *   - A spec's transition({ when }) decides every commit with production's
  *     browser decision: navigate() and useRouter().push model kind "push",
- *     useRouter().replace kind "replace", refresh() kind "revalidate".
- *     Back/forward, action and optimistic clientUrls() swap decisions are
- *     e2e territory.
+ *     useRouter().replace kind "replace", refresh() kind "revalidate", and a
+ *     back/forward that restores a page kind "pop". Action and optimistic
+ *     clientUrls() swap decisions are e2e territory.
  *   - Location state reaches readers the way it does in production:
  *     NavigationProvider holds the committed entry's state next to the
  *     payload, so a navigation whose loader the test holds keeps the entry
  *     being left on screen with its own state. A `popstate` event is a
- *     back/forward onto the entry history.state holds; the tree has one
- *     location, so no page is restored with it. A server action's state, a
+ *     back/forward onto the entry history.state holds. When it is the
+ *     mounted entry or one a navigate() wrote, history still holds the state
+ *     written there, and another page is on screen, its page is restored
+ *     from the history cache, with the handle values it had, as production's
+ *     restore is; otherwise the tree keeps its location. A stale entry's
+ *     revalidation, a restore that fetches, a server action's state, a
  *     redirect's and an intercept's are e2e territory.
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
@@ -361,8 +367,37 @@ export interface TestRouterHandle {
      * `handles`). They arrive on the response's handle stream, so `useHandle`
      * readers take them with the page's commit: while React holds the page,
      * readers keep the values of the page being left.
+     *
+     * `options.streamUntil` gives the navigation a response stream, as a real
+     * response has: it opens in a task after the call, before the commit (the
+     * response arrives, and `useNavigation().pendingUrl` clears), and stays open
+     * until the promise settles (a page that streams a tail past its commit:
+     * `isStreaming` reads true until then). Without it the navigation has no
+     * stream. A navigation that a newer one or a back/forward aborts before its
+     * response arrives opens none and commits nothing; one aborted after its
+     * response arrived stops counting as streaming at the abort, as in
+     * production, where its response streams on and is ignored.
+     *
+     * @example
+     * const tail = deferred();
+     * await router.navigate("/products/2", { streamUntil: tail.promise });
+     * // useNavigation(): idle, isStreaming true
+     * await act(async () => tail.resolve());
+     * // useNavigation(): idle, isStreaming false
+     *
+     * A navigation started while React holds a page goes inside
+     * `await act(async () => ...)`. Its first update makes React retry the held
+     * page, which suspends again; a synchronous act() scope drops that retry
+     * and React renders no later update of the same priority.
+     *
+     * @example
+     * await act(async () => {
+     *   await router.navigate("/products/3", { transition: false });
+     * });
      */
-    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & Pick<NavigateOptions, "state" | "replace" | "transition">): Promise<void>;
+    navigate(url: string, options?: Pick<RenderRouteOptions, "loaders" | "handles"> & Pick<NavigateOptions, "state" | "replace" | "transition"> & {
+        streamUntil?: Promise<unknown>;
+    }): Promise<void>;
     /**
      * Re-render the current location, as router.refresh() does: a spec's
      * transition({ when }) decides it with kind "revalidate" (`to` is `from`).

package/dist/types/testing/serve-shell-request.d.ts

@@ -81,7 +81,13 @@ export interface ServeShellRequestOptions<TEnv = any> {
      * and segments take an action's revalidation defaults; it renders live, as
      * an action does, so neither the route cache nor the document cache answers
      * or stores it, and a `ppr` route's `replayStatus` is
-     * `{ outcome: "BYPASS", reason: "stale" }`.
+     * `{ outcome: "BYPASS", reason: "stale" }`. `boundary` names the error
+     * segment of a thrown action's boundary the page at `from` shows
+     * (`_rsc_boundary`), as the follow-up an earlier action owes that page
+     * sends it, with `stale: true` and no `segments`: the response renders
+     * every segment above the boundary and nothing at or below it, claims the
+     * boundary in `matched` and sends no segment for it. The server reads it
+     * only beside `stale`.
      */
     partial?: true | {
         from?: string;
@@ -91,6 +97,7 @@ export interface ServeShellRequestOptions<TEnv = any> {
         fill?: boolean;
         interceptSource?: string;
         stale?: boolean;
+        boundary?: string;
     };
     /**
      * POST this form as a submit before hydration: the no-JS request the

package/dist/types/types/cache-types.d.ts

@@ -130,9 +130,12 @@ export interface CacheOptions<TEnv = unknown> {
      */
     condition?: (ctx: import("../server/request-context.js").RequestContext<TEnv>) => boolean;
     /**
-     * Custom cache key function - FULL OVERRIDE.
-     * Bypasses default key generation AND store's keyGenerator. The result is
-     * stored namespaced (`key:` plus its URI encoding), so no value it returns
+     * Custom cache key function. Replaces the URL part of the default key
+     * (host, path, params, search) AND bypasses the store's keyGenerator. The
+     * request kind stays: a document request, a navigation and each intercept
+     * navigation keep their own record under one result, so the result decides
+     * which requests of one kind share a record. It is stored namespaced
+     * (`key:` plus its URI encoding, then the kind), so no value it returns
      * names another route's record; a nested cache() keys its records within
      * this partition.
      *

package/dist/types/types/error-types.d.ts

@@ -67,11 +67,38 @@ export interface OnErrorContext<TEnv = any> {
     actionId?: string;
     /** Environment/bindings (platform context) */
     env?: TEnv;
-    /** Duration from request start to error (milliseconds) */
+    /**
+     * Duration from request start to error (milliseconds). For a `background`
+     * error it counts from the start of the request that started the work, so
+     * it includes that response and any wait before the work ran.
+     */
     duration?: number;
-    /** Whether this is a partial/navigation request */
+    /**
+     * Whether this is a partial/navigation request, on an error the segment
+     * walk catches (a handler that throws, a streamed `loading()` handler that
+     * rejects, a DSL loader that rejects): `true` for a navigation, unset for a
+     * document. A `cache()` record's refresh or proactive write reports the
+     * request that started it; a PPR shell capture renders a document. The
+     * `routing` phase reports `false`.
+     */
     isPartial?: boolean;
-    /** Whether an error boundary caught the error */
+    /**
+     * `true` when the error came from work whose output goes to a cache and
+     * never to the response of the request that started it: a stale `cache()`
+     * record's refresh, the write of a navigation that kept a layout mounted, a
+     * stale document cache entry's re-run, a PPR shell capture, or a stale
+     * `"use cache"` function's or cached loader's refresh, the work's own
+     * failure included. `request` and `url` are the starting request's (a
+     * shell capture's handler errors name the page it captures). A
+     * `router.prerender()` warm's own render is its request's: unset, while a
+     * shell capture it makes is `true`. Unset for every other error.
+     */
+    background?: boolean;
+    /**
+     * Whether an error boundary caught the error and its fallback reached the
+     * response. `false` on a `background` error: the failed render is never
+     * stored, so no visitor sees the fallback.
+     */
     handledByBoundary?: boolean;
     /** Stack trace (if available) */
     stack?: string;

package/dist/types/types/handler-context.d.ts

@@ -342,7 +342,7 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
     _reverseScope?: import("../server/context.js").ReverseScope;
     /**
      * @internal The on-demand overlay holds a "removed" marker for this request
-     * (tryPrerenderLookup, cache-lookup.ts); gateOnDemandProducer reads it. On
+     * (readPrerenderSource, cache-lookup.ts); gateOnDemandProducer reads it. On
      * this context, not the request's: withCacheLookup documents that the
      * request ALS can be lost mid-pipeline on workerd.
      */
@@ -390,6 +390,14 @@ export type InternalHandlerContext<TParams = {}, TEnv = DefaultEnv, TSearch exte
      * request is a fill. See router/segment-resolution/prefetch-deferral.ts.
      */
     _prefetchDeferral?: import("../router/segment-resolution/prefetch-deferral.js").PrefetchDeferral;
+    /**
+     * @internal DSL loaders registered and not started, by `$$id`: a prefetch
+     * deferred them, or a pass that skips loaders (`skipLoaders`) did not run
+     * them. A reader's ctx.use() starts one through its registration
+     * (registerDeferredLoader, startDeferredLoader in
+     * router/segment-resolution/prefetch-deferral.ts).
+     */
+    _deferredLoaders?: Map<string, import("../router/segment-resolution/prefetch-deferral.js").DeferredLoader>;
     /**
      * @internal Whether a loader was started in this request: a run of it (a
      * handler's or another loader's ctx.use()) or its cache() binding. A

package/dist/types/types/segments.d.ts

@@ -151,7 +151,7 @@ export interface ResolvedSegment {
     loaderData?: any;
     /**
      * True when this loader was awaited before first flush
-     * (loader(Def, { ssr: false })). Stamped by resolveLoaders (fresh.ts) on
+     * (loader(Def, { ssr: false })). Stamped by resolveOwnerLoaders on
      * document AND shell-capture renders — capture bakes flagged loaders and
      * awaits the same lane. Feeds segment-system's settled-value delivery and
      * the dev SSR suspension warning (ssr-suspension-warning.ts).