@rangojs/router 0.21.0 → 0.22.0

package/src/segment-system.tsx

@@ -5,7 +5,7 @@ import {
   type ComponentType,
   isValidElement,
 } from "react";
-import { OutletProvider } from "./outlet-provider.js";
+import { AuditedOutletProvider, OutletProvider } from "./outlet-provider.js";
 import { withOptimisticCommitNone } from "./browser/optimistic-commit.js";
 import { MountContextProvider } from "./browser/react/mount-context.js";
 import type { ResolvedSegment, RootLayoutProps } from "./types.js";
@@ -13,17 +13,25 @@ import { decodeLoaderResults } from "./decode-loader-results.js";
 import { LoaderRedirect } from "./loader-redirect.js";
 import { invariant } from "./errors.js";
 import {
+  AuditedLoaderBoundary,
+  AuditedRouteContent,
   RouteContentWrapper,
   LoaderBoundary,
   StreamedLoaderErrorBoundary,
 } from "./route-content-wrapper.js";
 import { RootErrorBoundary } from "./root-error-boundary.js";
 import { INTERNAL_RANGO_DEBUG } from "./internal-debug.js";
-import { getMemoizedContentPromise } from "./segment-content-promise.js";
+import { INTERNAL_RANGO_SUSPENSE_AUDIT } from "./internal-suspense-audit.js";
+import { getBoundaryContent } from "./segment-boundary-content.js";
 import {
   buildLoaderPromise,
   getMemoizedLoaderPromise,
 } from "./segment-loader-promise.js";
+import {
+  auditSegmentElement,
+  finishTreeAudit,
+  startTreeAudit,
+} from "./suspense-audit.js";
 
 /**
  * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
@@ -212,13 +220,25 @@ function wrapDefaultOutletContent(
     } as any);
   }
 
-  if (content.type === OutletProvider && props.segment?.type === "layout") {
+  if (
+    content.type ===
+      (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+        ? AuditedOutletProvider
+        : OutletProvider) &&
+    props.segment?.type === "layout"
+  ) {
     return React.cloneElement(content, {
       content: wrapDefaultOutletContent(props.content, transition),
     } as any);
   }
 
-  if (content.type === LoaderBoundary && props.segment?.type === "layout") {
+  if (
+    content.type ===
+      (process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+        ? AuditedLoaderBoundary
+        : LoaderBoundary) &&
+    props.segment?.type === "layout"
+  ) {
     return React.cloneElement(content, {
       outletContent: wrapDefaultOutletContent(props.outletContent, transition),
     } as any);
@@ -376,6 +396,10 @@ export async function renderSegments(
   }
   // Separate segments by type, passing intercept segments for explicit injection
   const tree = segmentTreeWalk(normalizedSegments, normalizedInterceptSegments);
+  // Dev only: the wrapper chain per segment, compared with the previous
+  // tree's (suspense-audit.ts, I5).
+  const treeAudit =
+    process.env.NODE_ENV !== "production" ? startTreeAudit() : undefined;
 
   // A route is "in a transition scope" when its own segment OR any layout in
   // its matched chain declares transition(). Both transition() forms land here:
@@ -473,34 +497,33 @@ export async function renderSegments(
 
     let nodeContent: ReactNode = null;
     if (!clientGroup && isRenderableLoading(loading)) {
-      // forceAwait (popstate, stale-revalidation, fully-prefetched nav) renders a
-      // loading() route with the route content ALREADY resolved, so its
-      // RouteContentWrapper Suspender does not suspend for a microtask and flash
-      // the loading() fallback on a NORMAL (non-transition) commit. The router
-      // data is known-ready on these paths, so awaiting the content here is free.
-      // The wrapper tree is unchanged (RouteContentWrapper is still created with
-      // the same key/fallback) — only the `content` prop is a resolved node
-      // instead of a pending promise, which Suspender renders synchronously. This
-      // mirrors the forceAwait loaderData unwrap above; a CLIENT component that
-      // suspends on mount inside the content still reveals a fallback (it is not
-      // pre-resolved).
-      const contentPromise = getMemoizedContentPromise(resolvedComponent);
-      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      // The wrapper tree is the same on every path; only `content` differs. A
+      // settled component is handed over as the node (getBoundaryContent), a
+      // pending one as its promise, so only pending work shows the loading()
+      // fallback. forceAwait also awaits a pending component here. A CLIENT
+      // component that suspends on mount inside the content still reveals a
+      // fallback.
+      let loadingContent: ReactNode = getBoundaryContent(resolvedComponent);
       if (forceAwait) {
         const contentAwaitStart = segDebug ? performance.now() : 0;
-        loadingContent = await contentPromise;
+        loadingContent = await loadingContent;
         if (segDebug) {
           segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
             ms: Math.round(performance.now() - contentAwaitStart),
           });
         }
       }
-      nodeContent = createElement(RouteContentWrapper, {
-        key: `suspense-loading-${id}`,
-        content: loadingContent,
-        fallback: loading,
-        segmentId: id,
-      });
+      nodeContent = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedRouteContent
+          : RouteContentWrapper,
+        {
+          key: `suspense-loading-${id}`,
+          content: loadingContent,
+          fallback: loading,
+          segmentId: id,
+        },
+      );
     } else {
       // [VT-DIAG] Gated behind INTERNAL_RANGO_DEBUG. A segment in the no-loading()
       // branch whose component decodes as a Promise/lazy gets registered into
@@ -593,7 +616,10 @@ export async function renderSegments(
       let boundaryAwaitedLoaderIds: string[] | undefined;
       if (forceAwait || isAction) {
         const awaitStart = segDebug ? performance.now() : 0;
-        boundaryLoaderData = await loaderDataPromise;
+        boundaryLoaderData =
+          loaderDataPromise instanceof Promise
+            ? await loaderDataPromise
+            : loaderDataPromise;
         if (segDebug) {
           segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
             loaderIds,
@@ -621,28 +647,38 @@ export async function renderSegments(
           );
         }
       }
-      content = createElement(LoaderBoundary, {
-        key: `loader-boundary-${key}`,
-        loaderDataPromise: boundaryLoaderData,
-        loaderIds,
-        loaderStreams: boundaryLoaderStreams,
-        awaitedLoaderIds: boundaryAwaitedLoaderIds,
-        fallback: loading,
-        outletKey: key,
-        outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        children: nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedLoaderBoundary
+          : LoaderBoundary,
+        {
+          key: `loader-boundary-${key}`,
+          loaderDataPromise: boundaryLoaderData,
+          loaderIds,
+          loaderStreams: boundaryLoaderStreams,
+          awaitedLoaderIds: boundaryAwaitedLoaderIds,
+          fallback: loading,
+          outletKey: key,
+          outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          children: nodeContent,
+        },
+      );
     } else if (loaderEntries.length === 0) {
-      content = createElement(OutletProvider, {
-        key,
-        content: outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        pending: outletPending,
-        children: nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedOutletProvider
+          : OutletProvider,
+        {
+          key,
+          content: outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          pending: outletPending,
+          children: nodeContent,
+        },
+      );
     } else {
       const layoutLoaders = loaderEntries.filter((l) => !l.parallelLoading);
       const parallelOwnedLoaders = loaderEntries.filter(
@@ -776,17 +812,23 @@ export async function renderSegments(
         }
       }
 
-      content = createElement(OutletProvider, {
-        key,
-        content: outletContent,
-        segment: node.segment,
-        parallel: node.parallel,
-        loaderData: Object.keys(loaderData).length > 0 ? loaderData : undefined,
-        loaderStreams,
-        awaitedLoaderIds,
-        pending: outletPending,
-        children: errorFallback ?? nodeContent,
-      });
+      content = createElement(
+        process.env.NODE_ENV !== "production" && INTERNAL_RANGO_SUSPENSE_AUDIT
+          ? AuditedOutletProvider
+          : OutletProvider,
+        {
+          key,
+          content: outletContent,
+          segment: node.segment,
+          parallel: node.parallel,
+          loaderData:
+            Object.keys(loaderData).length > 0 ? loaderData : undefined,
+          loaderStreams,
+          awaitedLoaderIds,
+          pending: outletPending,
+          children: errorFallback ?? nodeContent,
+        },
+      );
     }
 
     // Wrap with MountContextProvider for include() scoped components.
@@ -800,6 +842,22 @@ export async function renderSegments(
       });
     }
 
+    if (process.env.NODE_ENV !== "production") {
+      auditSegmentElement(
+        treeAudit,
+        id,
+        node.segment.type,
+        key,
+        content,
+        node.segment.type === "layout" &&
+          !!ReactViewTransition &&
+          !!transition &&
+          transition.viewTransition !== false,
+        node.parallel.map((p) => p.id),
+        [node.segment, ...node.parallel, ...node.loaders],
+      );
+    }
+
     if (segDebug) {
       segDebugLog(`segment ${id} built`, {
         type: node.segment.type,
@@ -849,6 +907,8 @@ export async function renderSegments(
     });
   }
 
+  if (process.env.NODE_ENV !== "production") finishTreeAudit(treeAudit, result);
+
   return result;
 }
 

package/src/server/build-version-table.ts

@@ -39,6 +39,21 @@ export function resolveRouterVersions(
   );
 }
 
+/**
+ * The version an on-demand prerender overlay key carries: the router's data
+ * version, because the overlay stores segment data, as the segment cache does
+ * (a client-only deploy keeps both). The write side (`router.prerender`,
+ * router.ts) and the read side (rsc/handler.ts) both call this with
+ * `createRouter({ version })`, the only override the trigger can see, so they
+ * cannot disagree; a `createRSCHandler({ version })` does not move it.
+ */
+export function resolvePrerenderVersion(
+  routerId: string | undefined,
+  routerVersion: string | undefined,
+): string {
+  return resolveRouterVersions(routerId, routerVersion).data;
+}
+
 /** The table gives some router a pair of its own. */
 function hasRouterVersions(): boolean {
   if (!table) return false;

package/src/server/context.ts

@@ -15,6 +15,10 @@ import { invariant, DslContextError } from "../errors";
 import type { DefaultRouteName } from "../types/global-namespace.js";
 import type { ContextVar } from "../context-var.js";
 import { PPR_LANE_HINT } from "../rsc/shell-capture-constants.js";
+import {
+  noteWarmIdentityRead,
+  type WarmContext,
+} from "../prerender/warm-request.js";
 import {
   endIdentityExempt,
   isInsideCacheExecScope,
@@ -261,8 +265,13 @@ export type EntryData =
       /** Original PrerenderHandlerDefinition (for build-time getParams access) */
       prerenderDef?: {
         getParams?: (ctx: any) => Promise<any[]> | any[];
-        options?: { concurrency?: number };
+        options?: {
+          concurrency?: number;
+          onDemand?: import("../prerender/on-demand.js").OnDemandOption;
+        };
       };
+      /** Set when the route opted into on-demand prerender (Prerender(..., { onDemand })) */
+      isOnDemand?: true;
       /** Set when route is wrapped with Passthrough() — has a separate live handler */
       isPassthrough?: true;
       /** Live handler for runtime fallback (only set on Passthrough routes) */
@@ -428,6 +437,7 @@ export const getContext = (): {
   getStore: () => HelperContext;
   getParent: () => EntryData | null;
   getOrCreateStore: (forRoute?: string) => HelperContext;
+  runIsolated: <T>(forRoute: string, callback: () => T) => T;
   getNextIndex: (
     type: (string & {}) | "layout" | "parallel" | "middleware" | "revalidate",
   ) => string;
@@ -447,26 +457,29 @@ export const getContext = (): {
   ) => T;
 } => {
   const context = RangoContext;
+  const createStore = (forRoute?: string): HelperContext => ({
+    manifest: new Map<string, EntryData>(),
+    namespace: "",
+    parent: null,
+    forRoute,
+    counters: {},
+    patterns: new Map<string, string>(),
+    patternsByPrefix: new Map<string, Map<string, string>>(),
+    trailingSlash: new Map<string, "never" | "always" | "ignore">(),
+    searchSchemas: new Map<string, Record<string, string>>(),
+  });
 
   return {
     context,
     getOrCreateStore: (forRoute?: string): HelperContext => {
       let store = RangoContext.getStore();
       if (!store) {
-        store = {
-          manifest: new Map<string, EntryData>(),
-          namespace: "",
-          parent: null,
-          forRoute,
-          counters: {},
-          patterns: new Map<string, string>(),
-          patternsByPrefix: new Map<string, Map<string, string>>(),
-          trailingSlash: new Map<string, "never" | "always" | "ignore">(),
-          searchSchemas: new Map<string, Record<string, string>>(),
-        } satisfies HelperContext;
+        store = createStore(forRoute);
       }
       return store;
     },
+    runIsolated: <T>(forRoute: string, callback: () => T): T =>
+      context.run(createStore(forRoute), callback),
     getStore: (): HelperContext => {
       const store = context.getStore();
       if (!store) {
@@ -959,19 +972,20 @@ export interface IdentityReadWording {
  * nothing and are not captured reads: they take refuseInCacheScope alone.
  */
 export function guardIdentityRead(
-  ctx: unknown,
+  ctx: WarmContext | null | undefined,
   surface: string,
   wording: IdentityReadWording,
 ): void {
   if (isInsideIdentityExempt()) return;
   const { verb, fix } = wording;
   if (tripShellCaptureGuard(ctx, surface, fix.warning)) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} while capturing a shared shell ` +
         `(ppr shell capture). ${fix.capture}`,
     );
   }
-  refuseInCacheScope(surface, wording);
+  refuseInCacheScope(surface, wording, ctx);
   if (wording.record !== false) recordLoaderIdentityRead(surface, verb);
 }
 
@@ -982,13 +996,16 @@ export function guardIdentityRead(
 export function refuseInCacheScope(
   surface: string,
   { verb, fix }: IdentityReadWording,
+  ctx?: WarmContext | null,
 ): void {
   if (isInsideCacheExecScope()) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} inside a "use cache" function. ${fix.useCache}`,
     );
   }
   if (isInsideCacheScope()) {
+    noteWarmIdentityRead(ctx, surface);
     throw new Error(
       `${surface} cannot be ${verb} inside a cache() boundary. ${fix.cacheScope}`,
     );
@@ -1074,7 +1091,7 @@ const NON_CACHEABLE_READ: IdentityReadWording = {
  */
 export function assertNonCacheableReadAllowed(
   keyOrVar: string | ContextVar<unknown>,
-  requestCtx?: unknown,
+  requestCtx?: WarmContext | null,
 ): void {
   const name = typeof keyOrVar === "string" ? ` "${keyOrVar}"` : "";
   guardIdentityRead(
@@ -1276,7 +1293,10 @@ export function isInsideAnyLoaderScope(): boolean {
 
 /**
  * The one ppr opt-in predicate: a page route entry that DECLARED `ppr`
- * (`false` and undefined mean plain axis 1). Shared by the serve path
+ * (`false`, undefined, and on-demand routes mean plain axis 1). A writable
+ * prerender refresh cannot atomically replace the separate document shell, so
+ * combining those lanes would pair a fresh tail with a stale prelude. Shared by
+ * the serve path
  * (rsc/shell-serve.ts resolvePprConfig) and the header-write latch below so
  * the two layers can never drift on what counts as a ppr route.
  */
@@ -1285,7 +1305,10 @@ export function isPprEntry(entry: EntryData): entry is EntryData & {
   ppr: true | import("../urls/pattern-types.js").PartialPrerenderProps;
 } {
   return (
-    entry.type === "route" && entry.ppr !== undefined && entry.ppr !== false
+    entry.type === "route" &&
+    entry.isOnDemand !== true &&
+    entry.ppr !== undefined &&
+    entry.ppr !== false
   );
 }
 

package/src/server/cookie-store.ts

@@ -21,6 +21,7 @@ import {
   requestReadCaptureFix,
   type IdentityReadWording,
 } from "./context.js";
+import { assertNotInsidePrerenderProducer } from "../prerender/producer-guard.js";
 import { requestHeaders, shadowRequestHeaders } from "./request-headers.js";
 
 /**
@@ -72,6 +73,7 @@ export interface CookieStore {
  */
 export function cookies(): CookieStore {
   const ctx = getRequestContext();
+  assertNotInsidePrerenderProducer(ctx, "cookies()");
   guardIdentityRead(ctx, "cookies()", COOKIES_READ);
   return createCookieStore(ctx);
 }
@@ -273,6 +275,7 @@ const HEADERS_READ_PROPS = new Set<string | symbol>([
  */
 export function headers(): ReadonlyHeaders {
   const ctx = getRequestContext();
+  assertNotInsidePrerenderProducer(ctx, "headers()");
   guardIdentityRead(ctx, "headers()", HEADERS_READ);
   return new Proxy(requestHeaders(ctx.request), {
     get(target, prop, receiver) {
@@ -313,6 +316,7 @@ export function invalidateClientCache(): void {
     }
     return;
   }
+  assertNotInsidePrerenderProducer(ctx, "invalidateClientCache()");
   refuseInCacheScope("invalidateClientCache()", COOKIES_READ);
   ctx._rotateStateCookie();
 }
@@ -338,6 +342,7 @@ export function keepClientCache(): void {
     }
     return;
   }
+  assertNotInsidePrerenderProducer(ctx, "keepClientCache()");
   refuseInCacheScope("keepClientCache()", COOKIES_READ);
   ctx._setKeepCacheDirective();
 }

package/src/server/handle-store.ts

@@ -340,6 +340,9 @@ export interface HandleStore {
     segmentId: string,
   ): Record<string, (string | null)[]> | undefined;
 
+  /** The segment ids for which getRecordOwners returns an entry. */
+  getOwnedSegmentIds(): string[];
+
   /**
    * Replay cached handle data back into the store (for cache hits).
    * Used to restore handle data when serving cached segments.
@@ -1087,6 +1090,16 @@ export function createHandleStore(): HandleStore {
       return result;
     },
 
+    getOwnedSegmentIds(): string[] {
+      const ids = new Set<string>();
+      for (const handleName in data) {
+        for (const id in data[handleName]) {
+          if (!ids.has(id) && this.getRecordOwners(id)) ids.add(id);
+        }
+      }
+      return [...ids];
+    },
+
     replaySegmentData(
       segmentId: string,
       segmentHandles: Record<string, unknown[]>,

package/src/server/request-context.ts

@@ -46,7 +46,10 @@ import { withDefer } from "../defer.js";
 import { type MetricsStore } from "./context.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
-import type { SegmentCacheStore } from "../cache/types.js";
+import type {
+  SegmentCacheStore,
+  ShellSnapshotHandlesValue,
+} from "../cache/types.js";
 import type { RouterVersions } from "../router-versions.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
@@ -289,6 +292,30 @@ export interface RequestContext<
   /** @internal Cache store for segment caching (optional, used by CacheScope) */
   _cacheStore?: SegmentCacheStore;
 
+  /**
+   * @internal Env-scoped writable prerender store (the durable overlay) plus the
+   * deployment identity for build-scoped keys, resolved per request from the
+   * `prerender` router option. Read by the serve-path overlay lookup before the
+   * bundled build manifest. Absent when no prerender store is configured.
+   */
+  // ResolvedPrerender<any> (not <TEnv>): onRevalidate's contravariant `env` would
+  // otherwise make RequestContext invariant in TEnv, breaking existing
+  // RequestContext<{}> -> RequestContext<unknown> assignments.
+  _prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
+
+  /**
+   * @internal Set only on the requestless on-demand producer's context. When
+   * present, the standalone request-scoped READS — `cookies()`, `headers()`,
+   * `invalidateClientCache()`, `keepClientCache()` — throw a
+   * PrerenderPersonalizationError so a personalized render is skipped rather than
+   * baked into a shared payload. Response MUTATIONS on the producer context
+   * (`ctx.setStatus`/`header`/`setCookie`) stay silent no-op stubs, matching
+   * build-time prerender (the design's "throw or skip" contract permits skip):
+   * they write to a discarded synthetic response, so there is nothing to leak.
+   * Never set on the live request path.
+   */
+  _onDemandProducer?: true;
+
   /**
    * @internal Compiled `cache.searchParams` filter for default cache-key
    * generation (undefined = "all", the byte-stable unfiltered format). Set
@@ -365,6 +392,22 @@ export interface RequestContext<
    */
   _shellForcedMiss?: true;
 
+  /**
+   * @internal This request is a router.prerender() warm
+   * (prerender/warm-request.ts). In `replace` mode every runtime cache read
+   * misses (isWarmReplace); the layers report into the record. A capture's
+   * derived context inherits it through the prototype.
+   */
+  _prerenderWarm?: import("../prerender/warm-request.js").PrerenderWarmRecord;
+
+  /**
+   * @internal Runs a callback in the async context this request entered the
+   * handler with (captureRequestEntryContext). router.prerender() dispatches
+   * a warm through it when called from inside a request. Absent where the
+   * 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
@@ -459,6 +502,8 @@ export interface RequestContext<
      * host) and miss the record.
      */
     fixedDocKey?: string;
+    /** @internal The snapshot's `handles` record (ShellSnapshotHandlesValue). */
+    prerenderHandles?: ShellSnapshotHandlesValue;
     /**
      * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
      * serve path. Its presence arms the explicit-scope composition in
@@ -808,6 +853,18 @@ export interface RequestContext<
    */
   _renderErrors?: unknown[];
 
+  /**
+   * @internal Rejections of streamed (loading()) handlers that were recovered
+   * into a declared errorBoundary()/notFoundBoundary() fallback, by segment id.
+   * The recovered promise resolves, so Flight reports nothing; cacheRoute
+   * (cache-scope.ts) refuses a write only when one of ITS segments is listed,
+   * the granularity a Flight error row has. The same errors are also pushed to
+   * `_renderErrors` for the document cache and PPR shell capture. A render
+   * under a derived context (shell capture, SWR re-render) owns its own map.
+   * Allocated on the first recovery.
+   */
+  _recoveredHandlerErrors?: Map<string, unknown>;
+
   /**
    * @internal Report a non-fatal background error through the router's
    * onError callback. Wired by the RSC handler / router during request
@@ -926,6 +983,8 @@ export type PublicRequestContext<
   | "_transitionWhenRefs"
   | "_pprReplayPostMatchReason"
   | "_cacheStore"
+  | "_prerender"
+  | "_onDemandProducer"
   | "_searchParamsFilter"
   | "_shellCaptureRun"
   | "_shellImplicitCache"
@@ -936,6 +995,8 @@ export type PublicRequestContext<
   | "_resolvedCacheKeys"
   | "_shellKey"
   | "_shellForcedMiss"
+  | "_prerenderWarm"
+  | "_runAtRequestEntry"
   | "_routeRecordWindow"
   | "_shellFragmentPayload"
   | "_shellCaptureGuardTripped"
@@ -957,6 +1018,7 @@ export type PublicRequestContext<
   | "_inActionRevalidation"
   | "_reportedErrors"
   | "_renderErrors"
+  | "_recoveredHandlerErrors"
   | "_renderBarrier"
   | "_resolveRenderBarrier"
   | "_renderBarrierSegmentOrder"
@@ -1007,6 +1069,22 @@ export const UNTRACKED_BACKGROUND_TASK: unique symbol = Symbol.for(
 // AsyncLocalStorage instance for request context
 const requestContextStorage = new AsyncLocalStorage<RequestContext<any>>();
 
+/**
+ * Capture the current async context (RequestContext._runAtRequestEntry), taken
+ * on handler entry before any router scope, so a nested dispatch (a
+ * router.prerender() warm called from a handler, loader or action) does not
+ * inherit the caller's route-definition, loader and cache-scope state. Per
+ * request: workerd refuses a snapshot outside the request that created it.
+ * See docs/design/prerender-every-route.md.
+ */
+export function captureRequestEntryContext():
+  | (<T>(fn: () => T) => T)
+  | undefined {
+  return typeof AsyncLocalStorage.snapshot === "function"
+    ? AsyncLocalStorage.snapshot()
+    : undefined;
+}
+
 /**
  * Run a function within a request context
  * Used by the RSC handler to provide context to server actions
@@ -1118,6 +1196,12 @@ export interface CreateRequestContextOptions<TEnv> {
   initialResponse?: Response;
   /** Optional cache store for segment caching (used by CacheScope) */
   cacheStore?: SegmentCacheStore;
+  /**
+   * Optional env-scoped writable prerender store + deployment identity (the
+   * durable overlay), resolved per request by the RSC handler from the
+   * `prerender` router option.
+   */
+  prerender?: import("../prerender/on-demand.js").ResolvedPrerender<any>;
   /**
    * Compiled `cache.searchParams` filter from the resolved handler cache
    * config (handler.ts). Stored as _searchParamsFilter.
@@ -1168,6 +1252,7 @@ export function createRequestContext<TEnv>(
     variables,
     initialResponse,
     cacheStore,
+    prerender,
     searchParamsFilter,
     explicitTaggedStores,
     cacheProfiles,
@@ -1543,6 +1628,7 @@ export function createRequestContext<TEnv>(
 
     _handleStore: handleStore,
     _cacheStore: cacheStore,
+    _prerender: prerender,
     _versions: versions,
     _searchParamsFilter: searchParamsFilter,
     _explicitTaggedStores: explicitTaggedStores,