@rangojs/router 0.27.0 → 0.29.0

package/src/server/render-pass.ts

@@ -0,0 +1,291 @@
+/**
+ * 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 {
+  bindRes,
+  createUseFunction,
+  wireRenderBarrier,
+  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 const RENDER_PASS_FIELDS: {
+  readonly [P in RenderPurpose]: PassFieldPolicy<RenderPassInit[P]>;
+} = {
+  /** rsc/shell-capture.ts deriveShellCaptureContext. */
+  "shell-capture": {
+    // #684: an inherited barrier is the foreground's, already resolved:
+    // ctx.rendered() returns at once and ctx.use(handle) bakes the
+    // foreground's handles into the shell.
+    renderBarrier: "own",
+    own(pass, { handleStore, identity, recording }, base) {
+      // Fresh: the foreground's is drained and throws LateHandlePushError.
+      pass._handleStore = handleStore;
+      if (identity) {
+        pass.request = identity.request;
+        pass.url = identity.url;
+        pass.originalUrl = new URL(identity.url);
+        pass.pathname = identity.url.pathname;
+        pass.searchParams = identity.url.searchParams;
+      }
+      // The shell entry's invalidation tags (loader tags belong to holes).
+      pass._requestTags = new Set<string>();
+      // A capture-ephemeral store in the handler-lifetime set would warn on
+      // every later updateTag() and retain the snapshot.
+      pass._explicitTaggedStores = new Set();
+      // The capture's render errors refuse the capture only.
+      pass._renderErrors = [];
+      pass._recoveredHandlerErrors = undefined;
+      // `run` is read by the loader, cookies() and headers() capture guards.
+      // Every field is present from here on: one shape while the capture
+      // writes it.
+      pass._shellCaptureState = {
+        run: true,
+        forVisitor: undefined,
+        // Bake-lane loader containers: settleCaptureRecord awaits them, the
+        // drain pins them into the snapshot.
+        loaderRecords: new Map(),
+        unrecordedLoaderPush: undefined,
+        loaderLanes: undefined,
+        guardTripped: undefined,
+        guardTrippedLoaderId: undefined,
+        // The capture notes its own route records, not the foreground's.
+        routeRecordWindow: undefined,
+      };
+      // The inherited dynamic() writes the foreground, which already served;
+      // settleCaptureRecord and captureAndStoreShell read this latch.
+      pass._dynamic = false;
+      pass.dynamic = (): void => {
+        pass._dynamic = true;
+      };
+      // An inherited true makes serializeSegments double-encode a fragment.
+      pass._shellFragmentPayload = false;
+      // Metrics and spans are foreground surfaces, already ended.
+      pass._metricsStore = undefined;
+      pass._tracing = undefined;
+      // Fired by settleCaptureRecord: the capture builds no Response, and the
+      // doc record's write is gated on onResponse.
+      pass._onResponseCallbacks = [];
+      if (recording) {
+        // Own, so the request's _cacheStore is untouched.
+        pass._cacheStore = recording.store;
+        // Collects deferred cache writes (settleCaptureRecord awaits them)
+        // and still forwards each to the request's waitUntil.
+        pass.waitUntil = (fn: () => Promise<void>): void => {
+          const p = Promise.resolve().then(fn);
+          recording.store.trackWrite(p);
+          base.waitUntil(() => p);
+        };
+        // The doc record goes into the snapshot only, so a recapture misses
+        // and handlers re-run.
+        pass._shellImplicitCache = recording.implicitCache;
+      }
+    },
+  },
+
+  /** rsc/rsc-rendering.ts serveShellHit. */
+  "ppr-tail": {
+    // An inherited barrier carries the base's premature non-streaming handle
+    // snapshot into a streaming tail.
+    renderBarrier: "own",
+    own(pass, { handleStore, loaderSeed, implicitCache }) {
+      // #1035: the document hydrates with the handles as of the record
+      // replay, before any loader runs.
+      const resolveRenderBarrier = pass._resolveRenderBarrier;
+      pass._resolveRenderBarrier = (segments) => {
+        handleStore.freezeDocumentSnapshot();
+        resolveRenderBarrier(segments);
+      };
+      if (loaderSeed) pass._shellLoaderSeed = loaderSeed;
+      pass._shellImplicitCache = implicitCache;
+      // #700 fragment splice: own, so it never reaches a capture render.
+      pass._shellFragmentPayload = true;
+    },
+  },
+
+  /**
+   * router/match-middleware/background-revalidation.ts rerenderAndCacheRoute.
+   */
+  "background-revalidation": {
+    // The request's, resolved before the pass starts: a stale HIT resolves
+    // it in cache-lookup.ts before withBackgroundRevalidation starts the
+    // refresh, and proactive caching runs from onResponse, so a loader's
+    // rendered() here never waits. The route's and an open intercept's
+    // passes skip loaders: one runs only when a handler reads it, started
+    // through its registration (resolveOwnerLoaders), so its pushes stay out
+    // of the record (captureHandles drops loader pushes) and its value bakes
+    // into the handler's output, as on a MISS. A shell capture never opens
+    // an intercept (createNavigationCaptureRequest drops the intercept
+    // source).
+    renderBarrier: "inherited",
+    own(pass, { handleStore, sink }) {
+      // Read late by loader pushes and cache-scope.ts; setupLoaderAccess
+      // binds it at setup, so that also runs inside this pass.
+      pass._handleStore = handleStore;
+      // Nothing lands on the foreground's perf timeline.
+      pass._metricsStore = undefined;
+      pass._renderErrors = [];
+      pass._recoveredHandlerErrors = undefined;
+      // The barrier's deadlock bookkeeping is the pass's own and stays open.
+      // The visitor's is closed once its barrier resolves, so a handler's
+      // read of a loader that calls rendered() went unrecorded and rendered()
+      // let it through: the record baked the visitor's handle snapshot, or on
+      // a streaming tree rendered() awaited this pass's store, which awaits
+      // that handler, and the refresh never settled. Open, the read is
+      // refused as a MISS refuses it.
+      pass._handlerLoaderDeps = undefined;
+      pass._renderBarrierWaiters = undefined;
+      pass._renderBarrierGuardClosed = undefined;
+      // A route cache() record, not a shell, even when a capture's stale read
+      // starts it: under the capture's guard a loader body's headers() fails
+      // the refresh, and recaptures replay the stale record until it expires.
+      pass._shellCaptureState = undefined;
+      // Response writes go to the sink: a layout above the cache() boundary
+      // or an error boundary's status would otherwise reach the live response.
+      pass._onResponseCallbacks = [];
+      pass.header = sink.header;
+      pass.setCookie = sink.setCookie;
+      pass.deleteCookie = sink.deleteCookie;
+      pass.setStatus = sink.setStatus;
+      pass._setStatus = sink._setStatus;
+      pass.setTheme = sink.setTheme;
+      pass._rotateStateCookie = sink._rotateStateCookie;
+      pass._setKeepCacheDirective = sink._setKeepCacheDirective;
+      // An invalidation here is not the visitor's mutation.
+      pass._setFreshReadsCookie = sink._setFreshReadsCookie;
+      // A cached handler's dynamic() opts out nothing here: the inherited one
+      // would refuse the capture whose stale read started the pass, or opt
+      // out the visitor's request.
+      pass.dynamic = sink.dynamic;
+      bindRes(pass, () => sink.res);
+    },
+  },
+
+  /** cache/document-cache.ts: the re-run of a stale entry, a whole request. */
+  "document-revalidation": {
+    // The stale HIT matched and rendered nothing: the re-run is the
+    // request's render. The request's barrier closes over the request, whose
+    // _treeHasStreaming the re-run never sets.
+    renderBarrier: "own",
+    own(pass, { handleStore, sink }, base) {
+      pass._handleStore = handleStore;
+      // The request's use() reads the request's params and route name, which
+      // the re-run's match sets on this pass. Its own memo: a loader that
+      // middleware ahead of the cache started runs again here.
+      pass.use = createUseFunction({
+        handleStore,
+        loaderPromises: new Map(),
+        getContext: () => pass,
+      });
+      // Its own latch, from what middleware ahead of the cache set: the
+      // render reads it on this pass, as a MISS reads the request's. The
+      // sink's dynamic() clears the ppr header latch.
+      pass._dynamic = base._dynamic;
+      pass.dynamic = (): void => {
+        pass._dynamic = true;
+        sink.dynamic();
+      };
+      pass._metricsStore = undefined;
+      // The re-run's classify timing stays off the visitor's Server-Timing.
+      pass._handlerTiming = [];
+      pass._renderErrors = [];
+      pass._recoveredHandlerErrors = undefined;
+      pass._shellCaptureState = undefined;
+      // Response writes go to the sink, never the visitor's STALE response.
+      pass._onResponseCallbacks = [];
+      pass.header = sink.header;
+      pass.setCookie = sink.setCookie;
+      pass.deleteCookie = sink.deleteCookie;
+      pass.setStatus = sink.setStatus;
+      pass._setStatus = sink._setStatus;
+      pass.setTheme = sink.setTheme;
+      pass._setKeepCacheDirective = sink._setKeepCacheDirective;
+      // No client receives the re-run's response: no rotation, no
+      // fresh-reads cookie (the sink has no state cookie name).
+      pass._rotateStateCookie = sink._rotateStateCookie;
+      pass._setFreshReadsCookie = sink._setFreshReadsCookie;
+      bindRes(pass, () => sink.res);
+    },
+  },
+};
+
+/**
+ * `Object.create(base)` with RENDER_PASS_FIELDS[purpose]'s own fields. The only
+ * place a request context is derived (tools/check-internals.mjs).
+ */
+export function deriveRenderPass<P extends RenderPurpose, TEnv>(
+  base: RequestContext<TEnv>,
+  purpose: P,
+  init: RenderPassInit[P],
+): RequestContext<TEnv> {
+  const policy = RENDER_PASS_FIELDS[purpose];
+  const pass: RequestContext<TEnv> = Object.create(base);
+  if (policy.renderBarrier === "own") {
+    wireRenderBarrier(pass, init.handleStore);
+  }
+  policy.own(pass, init, base);
+  return pass;
+}

package/src/server/request-context.ts

@@ -66,6 +66,7 @@ import {
 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 { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
 import {
@@ -273,8 +274,8 @@ export interface RequestContext<
 
   /**
    * @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;
@@ -334,56 +335,13 @@ export interface RequestContext<
   _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.
+   * @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.
    */
-  _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">;
+  _shellCaptureState?: ShellCaptureState;
 
   /**
    * @internal Record keys resolved for this request (CacheScope
@@ -403,9 +361,9 @@ export interface RequestContext<
 
   /**
    * @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;
 
@@ -425,17 +383,6 @@ export interface RequestContext<
    */
   _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
@@ -563,29 +510,6 @@ export interface RequestContext<
    */
   _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
@@ -882,8 +806,8 @@ export interface RequestContext<
    * (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>;
@@ -909,6 +833,13 @@ export interface RequestContext<
   /** @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.
@@ -978,6 +909,13 @@ export interface RequestContext<
    */
   _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;
 
@@ -1020,21 +958,6 @@ export interface RequestContext<
   _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.
  *
@@ -1059,22 +982,15 @@ export type PublicRequestContext<
   | "_prerender"
   | "_onDemandProducer"
   | "_searchParamsFilter"
-  | "_shellCaptureRun"
-  | "_shellCaptureForVisitor"
+  | "_shellCaptureState"
   | "_shellImplicitCache"
   | "_shellLoaderSeed"
-  | "_shellCaptureLoaderRecords"
-  | "_shellCaptureUnrecordedLoaderPush"
-  | "_shellCaptureLoaderLanes"
   | "_resolvedCacheKeys"
   | "_shellKey"
   | "_shellForcedMiss"
   | "_prerenderWarm"
   | "_runAtRequestEntry"
-  | "_routeRecordWindow"
   | "_shellFragmentPayload"
-  | "_shellCaptureGuardTripped"
-  | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
   | "_recordTagOwners"
@@ -1096,6 +1012,7 @@ export type PublicRequestContext<
   | "_inActionRevalidation"
   | "_actionRan"
   | "_reportedErrors"
+  | "_throwers"
   | "_printedErrors"
   | "_renderErrors"
   | "_recoveredHandlerErrors"
@@ -1115,6 +1032,7 @@ export type PublicRequestContext<
   | "_activeRoutine"
   | "_renderDiagnosticsEnabled"
   | "_handlerStart"
+  | "_handlerTiming"
   | "_tracing"
   | "_basename"
   | "_routerId"
@@ -1230,6 +1148,46 @@ export function runWithRequestContext<TEnv, T>(
   return requestContextStorage.run(context, fn);
 }
 
+/** Inside background work: the errors its onError reports named. */
+const backgroundWork = new AsyncLocalStorage<WeakSet<object>>();
+
+/**
+ * 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 function runAsBackgroundWork<TEnv, T>(
+  context: RequestContext<TEnv>,
+  fn: () => T,
+): T {
+  const reported = backgroundWork.getStore() ?? new WeakSet<object>();
+  return requestContextStorage.run(context, () =>
+    backgroundWork.run(reported, fn),
+  );
+}
+
+/** Whether the caller runs inside runAsBackgroundWork. */
+export function isBackgroundWork(): boolean {
+  return backgroundWork.getStore() !== undefined;
+}
+
+/**
+ * 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 function reportedErrorsOf(
+  context: RequestContext<any>,
+): WeakSet<object> {
+  return backgroundWork.getStore() ?? context._reportedErrors;
+}
+
 /**
  * Get the current request context
  * Throws if called outside of a request context
@@ -1835,6 +1793,7 @@ export function createRequestContext<TEnv>(
     _locationState: undefined,
 
     _reportedErrors: new WeakSet<object>(),
+    _throwers: undefined,
     _printedErrors: new WeakSet<object>(),
     _renderErrors: [],
     _metricsStore: undefined,
@@ -1842,6 +1801,7 @@ export function createRequestContext<TEnv>(
     _activeRoutine: undefined,
     _renderDiagnosticsEnabled: undefined,
     _handlerStart: undefined,
+    _handlerTiming: undefined,
 
     _resolveRenderBarrier: null as any,
     _renderBarrierSegmentOrder: undefined,
@@ -1926,8 +1886,8 @@ export function rebaseRequestContext(
 /**
  * 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/src/server/rewrite-trail.ts

@@ -89,17 +89,19 @@ export function rewriteShellAudience(
 
 type AudienceContext = Pick<
   RequestContext<any>,
-  "_shellCaptureRun" | "_documentCacheRender" | "res"
+  "_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 function rendersForSharedAudience(reqCtx: AudienceContext): boolean {
-  return reqCtx._shellCaptureRun === true || documentCacheStoresRender(reqCtx);
+  return (
+    reqCtx._shellCaptureState?.run === true || documentCacheStoresRender(reqCtx)
+  );
 }
 
 /**
@@ -150,7 +152,7 @@ function readRewrittenFrom(
 ): string | undefined {
   if (!reqCtx) return undefined;
   if (reader === "render" && rendersForSharedAudience(reqCtx)) {
-    if (!reqCtx._shellCaptureForVisitor) return undefined;
+    if (!reqCtx._shellCaptureState?.forVisitor) return undefined;
     // guardIdentityRead minus the capture guard: a cache() boundary, a "use
     // cache" body or a loader's own cache() inside the capture is keyed
     // without the URL.

package/src/ssr/index.tsx

@@ -442,7 +442,7 @@ const SSR_FALSE_FIRST_FLUSH_TURNS = 3;
 
 /**
  * True when the matched chain has a `loader(Def, { ssr: false })` entry: its
- * payload segments carry `awaitBeforeFlush` (fresh.ts).
+ * payload segments carry `awaitBeforeFlush` (resolveOwnerLoaders).
  */
 function hasAwaitBeforeFlush(payload: {
   metadata?: { segments?: readonly { awaitBeforeFlush?: true }[] };