@rangojs/router 0.0.0-experimental.e9c0b2f2 → 0.0.0-experimental.ea9f40f2

package/src/router/prefetch-limits.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolve the client-side prefetch limits — the in-memory prefetch cache size
+ * and the speculative-prefetch queue concurrency — once, at router init. Both
+ * are positive-integer counts shipped to the browser in payload metadata; the
+ * browser entry feeds them to the prefetch cache (`initPrefetchCache`) and the
+ * prefetch queue (`setPrefetchConcurrency`) at startup.
+ *
+ * Policy note: this is a SEPARATE policy from resolvePrefetchCacheTTL
+ * (prefetch-cache-ttl.ts). These are counts, not durations, so the disable
+ * paths differ: a TTL of `false`/0 intentionally turns prefetching off, but a
+ * cache size or concurrency of 0 would silently break prefetching while leaving
+ * it nominally enabled — never the intent of passing a number. So any value
+ * that is not a finite integer >= 1 (0, negative, fractional below 1, NaN,
+ * Infinity, undefined) falls back to the default. Finite values >= 1 are
+ * floored. Do not unify this guard with the TTL guard.
+ */
+
+export const DEFAULT_PREFETCH_CACHE_SIZE = 100;
+export const DEFAULT_PREFETCH_CONCURRENCY = 2;
+
+export function resolvePrefetchCacheSize(raw: number | undefined): number {
+  return resolvePositiveCount(raw, DEFAULT_PREFETCH_CACHE_SIZE);
+}
+
+export function resolvePrefetchConcurrency(raw: number | undefined): number {
+  return resolvePositiveCount(raw, DEFAULT_PREFETCH_CONCURRENCY);
+}
+
+function resolvePositiveCount(
+  raw: number | undefined,
+  fallback: number,
+): number {
+  if (typeof raw === "number" && Number.isFinite(raw) && raw >= 1) {
+    return Math.floor(raw);
+  }
+  return fallback;
+}

package/src/router/prerender-match.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from "react";
 import { createHandleStore } from "../server/handle-store.js";
+import { resolveSegmentHandleValues } from "../handles/deferred-resolution.js";
 import { getRequestContext } from "../server/request-context.js";
 import {
   runWithRequestContext,
@@ -32,7 +33,9 @@ import type {
 import type { RouteMatchResult } from "./pattern-matching.js";
 
 export interface PrerenderMatchDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   buildRouterContext: () => RouterContext<TEnv>;
   mergedRouteMap: Record<string, string>;
   resolveAllSegments: (
@@ -73,7 +76,7 @@ export async function matchForPrerender<TEnv = any>(
   passthrough?: true;
 } | null> {
   // 1. Find the matching route entry
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (!matched) return null;
 
   // Use params from trie match if available, fall back to provided params
@@ -293,7 +296,9 @@ export async function matchForPrerender<TEnv = any>(
       for (const seg of nonLoaderSegments) {
         const segHandles = handleStore.getDataForSegment(seg.id);
         if (Object.keys(segHandles).length > 0) {
-          handlesRecord[seg.id] = segHandles;
+          // Resolve deferred values before encoding so the baked artifact holds
+          // resolved data (prerender = build-time cache).
+          handlesRecord[seg.id] = await resolveSegmentHandleValues(segHandles);
         }
       }
       const handles = await encodeHandles(handlesRecord);
@@ -394,7 +399,8 @@ export async function matchForPrerender<TEnv = any>(
           for (const seg of interceptResolvedSegments) {
             const segHandles = handleStore.getDataForSegment(seg.id);
             if (Object.keys(segHandles).length > 0) {
-              interceptHandlesRecord[seg.id] = segHandles;
+              interceptHandlesRecord[seg.id] =
+                await resolveSegmentHandleValues(segHandles);
             }
           }
           // The intercept artifact serves main + intercept segments together, so
@@ -533,7 +539,7 @@ export async function renderStaticSegment<TEnv = any>(
     const segHandles = handleStore.getDataForSegment(handlerId);
     const handles =
       Object.keys(segHandles).length > 0
-        ? await encodeHandleValue(segHandles)
+        ? await encodeHandleValue(await resolveSegmentHandleValues(segHandles))
         : "";
 
     return { encoded: serialized.encoded, handles };

package/src/router/preview-match.ts

@@ -6,7 +6,9 @@ import type { MiddlewareFn } from "./middleware.js";
 import { resolveRoute } from "./route-snapshot.js";
 
 export interface PreviewMatchDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
 }
 
 /**

package/src/router/request-classification.ts

@@ -121,7 +121,9 @@ export type {
 };
 
 export interface ClassifyRequestDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   routerVersion: string;
   routerId: string;
 }
@@ -148,6 +150,23 @@ export async function classifyRequest<TEnv = any>(
   const pathname = url.pathname;
   const isAction =
     request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
+  const isLoaderFetch = url.searchParams.has("_rsc_loader");
+  const isPartialReq = url.searchParams.has("_rsc_partial");
+  const contentType = request.headers.get("content-type") || "";
+  const isFormSubmission =
+    contentType.includes("multipart/form-data") ||
+    contentType.includes("application/x-www-form-urlencoded");
+  const isPeRender = request.method === "POST" && !isAction && isFormSubmission;
+
+  // A plain document request (full-render mode) is the only mode that renders
+  // through match() with isSSR:true; every other mode (action, loader, PE,
+  // partial) renders — if at all — through the non-SSR matchPartial() path.
+  // Resolve the manifest under the flag the eventual render will use so
+  // createMatchContextForFull can reuse this snapshot instead of re-resolving.
+  // Response routes ignore isSSR entirely (they short-circuit before match),
+  // so the flag is moot for them. Mode detection below reuses these booleans.
+  const willFullRender =
+    !isAction && !isLoaderFetch && !isPartialReq && !isPeRender;
 
   const clientVersion = url.searchParams.get("_rsc_v");
   if (
@@ -189,6 +208,7 @@ export async function classifyRequest<TEnv = any>(
   const result = await resolveRoute<TEnv>(pathname, {
     findMatch: deps.findMatch,
     lite: true,
+    isSSR: willFullRender,
   });
 
   if (!result) {
@@ -229,7 +249,6 @@ export async function classifyRequest<TEnv = any>(
 
   const actionId =
     request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
-  const isLoaderFetch = url.searchParams.has("_rsc_loader");
 
   const hasVariants =
     snapshot.matched.negotiateVariants &&
@@ -244,15 +263,11 @@ export async function classifyRequest<TEnv = any>(
     return { mode: "loader", route: snapshot };
   }
 
-  const contentType = request.headers.get("content-type") || "";
-  const isFormSubmission =
-    contentType.includes("multipart/form-data") ||
-    contentType.includes("application/x-www-form-urlencoded");
-  if (request.method === "POST" && !isAction && isFormSubmission) {
+  if (isPeRender) {
     return { mode: "pe-render", route: snapshot };
   }
 
-  if (url.searchParams.has("_rsc_partial")) {
+  if (isPartialReq) {
     return { mode: "partial-render", route: snapshot, negotiated };
   }
 

package/src/router/route-snapshot.ts

@@ -48,6 +48,15 @@ export interface RouteSnapshot<TEnv = any> {
   isPassthrough: boolean;
   /** Response type for non-RSC routes (e.g. "application/json") */
   responseType?: string;
+  /**
+   * The isSSR flag the manifest was resolved with. Recorded so consumers can
+   * decide whether the snapshot is reusable: a snapshot resolved with isSSR
+   * differs (loading({ ssr: false }) entries) and is cached under a different
+   * manifest partition, so the full (document) path only reuses an isSSR:true
+   * snapshot and the partial path only reuses a non-isSSR one. Undefined on
+   * inline snapshots (redirect / not-found) that are never reused.
+   */
+  isSSR?: boolean;
 }
 
 export type ResolveRouteResult<TEnv = any> =
@@ -56,7 +65,9 @@ export type ResolveRouteResult<TEnv = any> =
   | null;
 
 export interface ResolveRouteDeps<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<RouteMatchResult<TEnv> | null>;
   metricsStore?: MetricsStore;
   isSSR?: boolean;
   /**
@@ -105,7 +116,7 @@ export async function resolveRoute<TEnv = any>(
 
   const routeMatchStart =
     metricsStore && !skipRouteMatchMetric ? performance.now() : 0;
-  const matched = deps.findMatch(pathname);
+  const matched = await deps.findMatch(pathname);
   if (metricsStore && !skipRouteMatchMetric) {
     metricsStore.metrics.push({
       label: "route-matching",
@@ -175,6 +186,7 @@ export async function resolveRoute<TEnv = any>(
       cacheScope,
       isPassthrough,
       responseType,
+      isSSR,
     },
   };
 }

package/src/router/router-context.ts

@@ -55,7 +55,9 @@ export interface InterceptResult {
  * Instead of passing 20+ parameters, middleware calls getRouterContext() to access them.
  */
 export interface RouterContext<TEnv = any> {
-  findMatch: (pathname: string) => RouteMatchResult | null;
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult | null | Promise<RouteMatchResult | null>;
 
   loadManifest: (
     entry: any,

package/src/router/router-interfaces.ts

@@ -9,12 +9,14 @@ import type { NonceProvider } from "../rsc/types.js";
 import type { ExecutionContext } from "../server/request-context.js";
 import type { SerializedSegmentData } from "../cache/types.js";
 import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
 import type { ExtractParams } from "../types/route-config.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RangoOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
 import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 import type { ResolvedTracing } from "./tracing.js";
+import type { TelemetrySink } from "./telemetry.js";
 
 /**
  * Options passed to router.fetch(), router.match(), and other request entrypoints.
@@ -301,6 +303,20 @@ export interface RangoInternal<
    */
   readonly prefetchCacheTTL: number;
 
+  /**
+   * Maximum number of decoded prefetch payloads the client keeps in its
+   * in-memory prefetch cache (FIFO eviction at capacity). Shipped to the
+   * client in payload metadata. Derived from prefetchCacheSize.
+   */
+  readonly prefetchCacheSize: number;
+
+  /**
+   * Maximum number of speculative prefetch requests the client runs
+   * concurrently. Shipped to the client in payload metadata. Derived from
+   * prefetchConcurrency.
+   */
+  readonly prefetchConcurrency: number;
+
   /**
    * Resolved rango state cookie name (`{prefix}_{routerId}`), composed once at
    * router init and shipped to the client in payload metadata. The server-side
@@ -335,6 +351,14 @@ export interface RangoInternal<
    */
   readonly tracing?: ResolvedTracing;
 
+  /**
+   * Raw telemetry sink from RangoOptions, exposed so handler-level emitters
+   * (rsc/handler.ts timeout/origin/late-handle) can emit WITHOUT the
+   * RouterContext ALS, which only match()/matchPartial() enter. See
+   * observeEvent's emitter list in router/instrument.ts.
+   */
+  readonly telemetry?: TelemetrySink;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.
@@ -502,7 +526,14 @@ export interface RangoInternal<
    * Used by classifyRequest() for request classification without
    * entering the full match pipeline.
    */
-  findMatch(pathname: string, metricsStore?: any): any;
+  // Async since a lazy async include (`() => import()`) must resolve before its
+  // routes can match. Typed (not `any`) so a consumer doing
+  // `const m = router.findMatch(p); if (!m) ...; m.entry` gets a compile error
+  // (m is a Promise) instead of the silent always-truthy bug.
+  findMatch(
+    pathname: string,
+    metricsStore?: any,
+  ): Promise<RouteMatchResult<TEnv> | null>;
 
   /**
    * Debug utility to serialize the manifest for inspection

package/src/router/router-options.ts

@@ -497,6 +497,36 @@ export interface RangoOptions<TEnv = any> {
    */
   prefetchCacheTTL?: number | false;
 
+  /**
+   * Maximum number of decoded prefetch payloads the client keeps in its
+   * in-memory prefetch cache. When the cache is full the oldest entry is
+   * evicted (FIFO) to make room for a new prefetch.
+   *
+   * Each entry retains a fully decoded RSC payload (and the route's client
+   * chunks pulled in while decoding), so this is the lever on client-side
+   * prefetch memory: a higher value warms more routes at the cost of more
+   * retained payloads. Staleness is bounded separately by `prefetchCacheTTL`;
+   * this bounds the entry COUNT.
+   *
+   * Values below 1 (or non-finite) fall back to the default. To turn
+   * prefetching off entirely, set `prefetchCacheTTL: false` instead.
+   *
+   * @default 100
+   */
+  prefetchCacheSize?: number;
+
+  /**
+   * Maximum number of speculative prefetch requests (viewport/render strategy)
+   * the client runs concurrently. Hover prefetches bypass this queue and fire
+   * immediately; this caps only the background, idle-gated queue so prefetches
+   * never saturate the browser's connection pool.
+   *
+   * Values below 1 (or non-finite) fall back to the default.
+   *
+   * @default 2
+   */
+  prefetchConcurrency?: number;
+
   /**
    * Prefix for the rango state cookie name. The resolved name is
    * `{prefix}_{routerId}`; the prefix is sanitized to cookie-name-safe

package/src/router/segment-resolution/fresh.ts

@@ -19,6 +19,10 @@ import type {
 } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { resolveLoaderData } from "./loader-cache.js";
+import {
+  isShellCaptureActive,
+  entryLoadingMasksLoaders,
+} from "./loader-mask.js";
 import {
   handleHandlerResult,
   tryStaticHandler,
@@ -60,6 +64,24 @@ export async function resolveLoaders<TEnv>(
   const hasLoading = "loading" in entry && entry.loading !== undefined;
   const loadingDisabled = hasLoading && entry.loading === false;
 
+  // Emit the streaming (non-awaiting) loader shape when loading is enabled OR
+  // during a PPR shell capture. In capture, LIVE-lane loaders are masked with
+  // never-resolving promises (loader-mask.ts); the loading-disabled branch below
+  // AWAITS the loader promises, which would hang the capture render's match()
+  // forever on those masked promises. Forcing the streaming shape lets match()
+  // complete so the prerender can postpone the loader subtrees as holes. The
+  // `!loadingDisabled` short-circuit keeps the ALS check off the hot path (only
+  // loading-disabled entries consult it), so normal requests are unchanged.
+  const emitStreaming = !loadingDisabled || isShellCaptureActive();
+
+  // PPR lane decision for this entry's loaders (loader-container-bake): an
+  // entry WITHOUT renderable loading() puts its loaders on the BAKE lane —
+  // executed at capture (container bakes, nested pending promises hole at the
+  // consumer's Suspense) and overlay-pinned from the shell snapshot on a HIT.
+  // Renderable loading() keeps the LIVE lane (masked at capture, always
+  // fresh). Computed per entry; resolveLoaderData applies the policy.
+  const bakeLane = !entryLoadingMasksLoaders(entry.loading);
+
   // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
   // fires createRouter({ onError }) (phase "loader") nor emits the loader.error
   // telemetry event — wrapLoaderPromise only builds the onError/telemetry path
@@ -67,7 +89,7 @@ export async function resolveLoaders<TEnv>(
   // loader failures the same way handlers/actions/routing/fetchable-loaders do.
   const errorContext = buildLoaderErrorContext(ctx);
 
-  if (!loadingDisabled) {
+  if (emitStreaming) {
     // Streaming loaders: promises kick off now, settle during RSC serialization.
     const segments = loaderEntries.map((loaderEntry, i) => {
       const { loader } = loaderEntry;
@@ -82,7 +104,12 @@ export async function resolveLoaders<TEnv>(
         loaderId: loader.$$id,
         loaderData: deps.wrapLoaderPromise(
           runInsideLoaderScope(() =>
-            resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+            resolveLoaderData(
+              loaderEntry,
+              ctx,
+              ctx.pathname,
+              bakeLane ? segmentId : null,
+            ),
           ),
           entry,
           segmentId,
@@ -111,7 +138,12 @@ export async function resolveLoaders<TEnv>(
     const segmentId = `${shortCode}D${i}.${loader.$$id}`;
     const wrapped = deps.wrapLoaderPromise(
       runInsideLoaderScope(() =>
-        resolveLoaderData(loaderEntry, ctx, ctx.pathname),
+        resolveLoaderData(
+          loaderEntry,
+          ctx,
+          ctx.pathname,
+          bakeLane ? segmentId : null,
+        ),
       ),
       entry,
       segmentId,
@@ -202,6 +234,7 @@ export async function resolveSegment<TEnv>(
       transition: applyViewTransitionDefault(
         entry.transition,
         deps.viewTransitionDefault,
+        entry.shortCode,
       ),
       params,
       belongsToRoute: false,
@@ -345,6 +378,7 @@ export async function resolveSegment<TEnv>(
       transition: applyViewTransitionDefault(
         entry.transition,
         deps.viewTransitionDefault,
+        entry.shortCode,
       ),
       params,
       belongsToRoute: true,
@@ -432,6 +466,7 @@ export async function resolveOrphanLayout<TEnv>(
     transition: applyViewTransitionDefault(
       orphan.transition,
       deps.viewTransitionDefault,
+      orphan.shortCode,
     ),
     ...(orphan.mountPath ? { mountPath: orphan.mountPath } : {}),
   });
@@ -565,6 +600,7 @@ export async function resolveParallelEntry<TEnv>(
       transition: applyViewTransitionDefault(
         parallelEntry.transition,
         deps.viewTransitionDefault,
+        `${parentShortCode}.${slot}`,
       ),
       params,
       slot,

package/src/router/segment-resolution/loader-cache.ts

@@ -21,7 +21,11 @@
 import type { LoaderEntry } from "../../server/context.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
-import { getRequestContext } from "../../server/request-context.js";
+import {
+  getRequestContext,
+  _getRequestContext,
+  runWithRequestContext,
+} from "../../server/request-context.js";
 import { sortedRouteParams } from "../../cache/cache-key-utils.js";
 import {
   resolveTtl,
@@ -32,7 +36,15 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
+import {
+  maskNestedContainerThenables,
+  overlayLoaderContainer,
+} from "./loader-snapshot.js";
 import { recordRequestTags } from "../../cache/cache-tag.js";
+import {
+  isShellCaptureActive,
+  createMaskedLoaderPromise,
+} from "./loader-mask.js";
 // Lazy-loaded to avoid pulling @vitejs/plugin-rsc/rsc into modules that
 // import segment-resolution but never use loader caching.
 let _serializeResult: typeof import("../../cache/segment-codec.js").serializeResult;
@@ -123,6 +135,76 @@ export function resolveLoaderData<TEnv>(
   loaderEntry: LoaderEntry,
   ctx: HandlerContext<any, TEnv>,
   pathname: string,
+  bakeSegmentKey?: string | null,
+): Promise<any> {
+  // One ALS read serves the capture check, the record registration, and the
+  // seed lookup — this runs for every loader on every request.
+  const reqCtx = _getRequestContext();
+  // PPR shell capture policy — gated here, the single funnel every loader
+  // segment path routes through (fresh resolveLoaders, cache-hit
+  // resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation).
+  //
+  // Two lanes (docs/design/loader-container-bake.md):
+  // - LIVE lane (entry has renderable loading(); no `bakeSegmentKey`): never
+  //   execute during capture. The slot gets a never-resolving promise so the
+  //   LoaderBoundary postpones (a hole). See loader-mask.ts.
+  // - BAKE lane (no renderable loading(); callers pass `bakeSegmentKey`):
+  //   execute during capture exactly like axis 1 — the settled container bakes
+  //   into the prelude, nested pending promises postpone at the consumer's own
+  //   Suspense. The container promise is registered on the derived context so
+  //   captureAndStoreShell pins it into the snapshot's loader family; on a
+  //   shell HIT the recorded container is overlaid onto the fresh run so the
+  //   payload matches the frozen prelude byte-for-byte.
+  if (isShellCaptureActive(reqCtx)) {
+    if (!bakeSegmentKey) {
+      return createMaskedLoaderPromise();
+    }
+    const containerPromise = executeLoaderData(loaderEntry, ctx, pathname);
+    // Pre-attach a no-op catch: a bake-lane rejection during capture must
+    // surface through the drain's refusal (and the wrapper's error boundary),
+    // never as an unhandled rejection that can kill the worker before the
+    // drain probes this record.
+    containerPromise.catch(() => {});
+    // Nested-promise SHAPE is the liveness declaration: mask nested thenables
+    // in the capture's copy of the container so the consuming subtree
+    // postpones as a hole no matter when the promise settles, elide records a
+    // HOLE marker, and every HIT streams the fresh value. Without this, a
+    // nested promise that settled before the quiet window baked its value into
+    // the SHARED shell and the snapshot pinned it for every visitor
+    // (per-request basket data served cross-session, found live). The raw
+    // container is untouched: handler-side ctx.use consumption (the
+    // consumption-lane rule, semantic-matrix PPR3) keeps real values.
+    const maskedPromise = containerPromise.then((container: unknown) =>
+      maskNestedContainerThenables(container),
+    );
+    maskedPromise.catch(() => {});
+    reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, maskedPromise);
+    return maskedPromise;
+  }
+
+  if (bakeSegmentKey) {
+    const seed = reqCtx?._shellLoaderSeed;
+    if (seed && seed.has(bakeSegmentKey)) {
+      const recorded = seed.get(bakeSegmentKey);
+      // HIT tail: run fresh (only the loader body can mint the live nested
+      // promises), then pin the recorded paths over it. A fresh REJECTION here
+      // skips the overlay and flows to the per-loader error boundary — the
+      // payload then diverges from the prelude (same residual class as uncached
+      // nondeterminism in shell material).
+      return executeLoaderData(loaderEntry, ctx, pathname).then(
+        (fresh: unknown) => overlayLoaderContainer(fresh, recorded),
+      );
+    }
+  }
+
+  return executeLoaderData(loaderEntry, ctx, pathname);
+}
+
+/** The pre-policy loader execution: cache read-through or plain ctx.use. */
+function executeLoaderData<TEnv>(
+  loaderEntry: LoaderEntry,
+  ctx: HandlerContext<any, TEnv>,
+  pathname: string,
 ): Promise<any> {
   const cacheConfig = loaderEntry.cache;
 
@@ -202,11 +284,20 @@ export function resolveLoaderData<TEnv>(
       ctx.params,
     );
 
+    // Capture the request context up front (foreground, ALS present) so the
+    // background stale revalidation can re-establish it. On workerd a waitUntil
+    // task runs detached from the request's I/O context, so a loader body that
+    // reads the ambient getRequestContext() would otherwise throw "called
+    // outside of a request context" and the revalidation would fail silently.
+    // The wrap is applied via wrapBackground (background path only); the
+    // foreground miss runs execute() directly since its context is present.
+    const requestCtxForExecute = getRequestContext();
     return readThroughItem({
       getItem: (k) => store.getItem!(k),
       setItem: (k, v, o) => store.setItem!(k, v, o),
       key,
       execute: () => runMiss(loaderEntry.loader),
+      wrapBackground: (run) => runWithRequestContext(requestCtxForExecute, run),
       serialize: (d) => codec.serializeResult(d),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },
@@ -214,7 +305,7 @@ export function resolveLoaderData<TEnv>(
       onStale: () => debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`),
       onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
       onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
-      host: getRequestContext(),
+      host: requestCtxForExecute,
     });
   })();
 

package/src/router/segment-resolution/loader-mask.ts

@@ -0,0 +1,60 @@
+/**
+ * PPR shell-capture loader masking.
+ *
+ * During a shell CAPTURE re-render (Axis 2, see docs/design/ppr-shell-resume.md)
+ * route loaders are the "live lane": they must NOT execute — no side effects, no
+ * cost, no cache round-trips. Instead every loader segment's value slot receives
+ * a never-resolving promise, so the loader-consuming Suspense subtree stays
+ * pending and React's static `prerender` marks it as a postponed hole. The frozen
+ * shell (prelude) captures only the fallback; the resumed serve pass runs the
+ * loaders fresh through the unchanged execution path and streams their output
+ * into the holes.
+ *
+ * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
+ * the derived request context of the background capture task (shell-capture.ts) —
+ * NOT by the foreground render, whose `_shellCapture` descriptor merely means "a
+ * capture is wanted" and must not change behavior. This module is the single home
+ * for the mask so every loader execution site gates the same way (loader-cache.ts
+ * `resolveLoaderData`, fresh.ts `resolveLoaders`).
+ */
+
+import {
+  _getRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
+
+/**
+ * True when the current render is the active PPR shell capture and route loaders
+ * must be masked rather than executed. Reads `_shellCaptureRun` off the ALS
+ * request context (the capture task re-establishes its derived context via
+ * runWithRequestContext), so it is accurate at the loader resolution sites, which
+ * run synchronously inside the pipeline's context frame.
+ */
+export function isShellCaptureActive(
+  reqCtx: RequestContext<any> | undefined = _getRequestContext(),
+): boolean {
+  return reqCtx?._shellCaptureRun === true;
+}
+
+// createMaskedLoaderPromise moved to the leaf module mask-nested.ts (shared
+// with the handle-push funnel in request-context, which cannot import THIS
+// module without a cycle). Re-exported to keep the mask API in one place.
+export { createMaskedLoaderPromise } from "./mask-nested.js";
+
+/**
+ * Lane decision for an entry's loaders under PPR (the loading() value decides;
+ * docs/design/loader-container-bake.md):
+ *
+ * - RENDERABLE loading() (the LoaderBoundary Suspense fallback) — the LIVE
+ *   lane: masked at capture, guaranteed fresh on every serve. Returns true.
+ * - No loading() (absent, or explicitly `false`, incl. `loading(x, { ssr:
+ *   false })` under the SSR manifest) — the BAKE lane: the loader executes
+ *   during capture, its settled container bakes, nested pending promises hole
+ *   at the consumer's own Suspense. Returns false.
+ *
+ * Mirrors segment-system's isRenderableLoading so the mask decision and the
+ * tree's boundary placement can never disagree.
+ */
+export function entryLoadingMasksLoaders(loading: unknown): boolean {
+  return loading !== undefined && loading !== null && loading !== false;
+}