@rangojs/router 0.15.1 → 0.17.0

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

@@ -120,12 +120,8 @@ export async function resolveLoaders<TEnv>(
   // 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.
+  // PPR bake/seed key input only; lane rule: see resolveLoaderData
+  // (loader-cache.ts). Unflagged loaders mask at capture regardless of the key.
   const bakeLane = !entryLoadingMasksLoaders(entry.loading);
 
   // Error context for wrapLoaderPromise: without it, a throwing DSL loader never
@@ -146,9 +142,9 @@ export async function resolveLoaders<TEnv>(
     // barrier), and the loader body can call rendered() before the await below
     // is reached.
     //
-    // Shell-capture renders await too: flagged loaders BAKE at capture
-    // (loader-mask masks only LIVE-lane loaders). Capture must await them so
-    // bake-lane handle pushes land in the prelude.
+    // Shell-capture renders await too: flagged loaders execute at capture
+    // (lane rule: see resolveLoaderData, loader-cache.ts), so their handle
+    // pushes must land in the prelude.
     const awaitedIndices = registerAwaitBeforeFlushIds(loaderEntries);
 
     // Streaming loaders: promises kick off now, settle during RSC serialization.
@@ -276,6 +272,16 @@ export interface ResolveSegmentOptions {
    * so error boundaries keep catching at request time.
    */
   throwOnError?: boolean;
+  /**
+   * The matched route's full entry chain. resolveAllSegments defaults it to
+   * its `entries`; withCacheLookup passes it when it resolves only the entries
+   * above a cache() boundary. An orphan list can hold an entry of the chain: a
+   * bare cache() marker sits in its layout's layout[] (it wraps that layout's
+   * routes) and is the parent of the routes after it. For those routes it
+   * resolves once, as a chain entry, below the cache() header latch (issue
+   * #918: resolved twice on a MISS, once and discarded on a HIT).
+   */
+  chain?: readonly EntryData[];
 }
 
 /**
@@ -349,6 +355,7 @@ export async function resolveSegment<TEnv>(
     }
 
     for (const orphan of entry.layout) {
+      if (options?.chain?.includes(orphan)) continue;
       const orphanSegments = await resolveOrphanLayout(
         orphan,
         params,
@@ -578,6 +585,26 @@ export async function resolveOrphanLayout<TEnv>(
     resolvedParallelEntries.add(parallelEntry.id);
   }
 
+  // Routeless entries nested in this one (a layout() after a bare cache()
+  // marker, a wrapper inside a routeless wrapper) wrap the same content one
+  // level deeper. Issue #918: they were never rendered. None is in the
+  // matched chain: that would put this orphan in it, and resolveSegment
+  // skips those.
+  for (const nested of orphan.layout) {
+    segments.push(
+      ...(await resolveOrphanLayout(
+        nested,
+        params,
+        context,
+        loaderPromises,
+        belongsToRoute,
+        deps,
+        options,
+        routeKey,
+      )),
+    );
+  }
+
   return segments;
 }
 
@@ -736,6 +763,10 @@ export async function resolveAllSegments<TEnv>(
 ): Promise<ResolvedSegment[]> {
   const allSegments: ResolvedSegment[] = [];
   const seenIds = new Set<string>();
+  const segmentOptions: ResolveSegmentOptions = {
+    ...options,
+    chain: options?.chain ?? entries,
+  };
 
   // ppr routes are document-scoped cached territory: the whole chain (root
   // layout down to the page) bakes into the shared shell, so the header-write
@@ -760,8 +791,9 @@ export async function resolveAllSegments<TEnv>(
     // Set ALS flag when entering a cache() boundary so that ctx.get()
     // can guard non-cacheable variable reads. Also latch the header-write
     // scope (response-level side effects — headers/cookies/status).
-    // Persists for all descendant entries.
-    if (entry.type === "cache") {
+    // Persists for all descendant entries. A route entry carries `cache` when
+    // cache() is among its own children (dsl-helpers.ts cache()).
+    if (entry.cache) {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
       latchCachedHeaderScope("cache", routeKey);
@@ -779,7 +811,7 @@ export async function resolveAllSegments<TEnv>(
           loaderPromises,
           deps,
           false,
-          options,
+          segmentOptions,
         ),
       (seg) => [seg],
       deps,

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

@@ -16,10 +16,28 @@
  * On hit: returns cached data directly, skips loader execution.
  * On stale hit (SWR): returns stale data, schedules background revalidation.
  * On miss: executes loader, schedules non-blocking cache write.
+ *
+ * Handle pushes (`ctx.use(Handle)(...)` in the loader body) are a side effect
+ * the HIT must reproduce: the MISS records the pushes of the body and of the
+ * loaders it awaits via ctx.use into the entry's `handles` blob (the
+ * "use cache" capture/encode), and every HIT — stale included — replays
+ * them, each loader's pushes at most once per request (a dependency another
+ * reader already ran keeps its live pushes). See replayLoaderHandles.
  */
 
-import type { LoaderEntry } from "../../server/context.js";
+import {
+  getCurrentLoaderBodyId,
+  isInsideLoaderBody,
+  type LoaderEntry,
+} from "../../server/context.js";
 import type { HandlerContext, InternalHandlerContext } from "../../types.js";
+import type { HandleStore } from "../../server/handle-store.js";
+import type { CacheItemResult } from "../../cache/types.js";
+import {
+  startHandleCapture,
+  type HandleCapture,
+} from "../../cache/handle-capture.js";
+import { encodeHandles, decodeHandles } from "../../cache/handle-snapshot.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import {
   getRequestContext,
@@ -121,6 +139,73 @@ function getLoaderStore(
   return resolveCacheStore(cacheConfig.options.store);
 }
 
+/**
+ * Replay a loader-cache entry's recorded handle pushes on a HIT.
+ *
+ * Pushed to the CURRENT owning segment (the recorded ids are the MISS
+ * request's), in recorded order.
+ *
+ * One delivery per loader per request: each recorded group is one loader
+ * body's pushes (recordOwnerKey), and `claim` (setupLoaderAccess
+ * _claimLoaderPushes) skips a group whose loader already ran in this request
+ * — a sibling loader or the handler read the dependency, and its live pushes
+ * stand — or that another replay delivered. A claimed loader that runs later
+ * (loaders stay live) replaces its replayed values with its live pushes
+ * (HandleStore.pushReplayed).
+ *
+ * Deliberately NOT inside the loader's body scope: a stale hit's background
+ * revalidation of the same loader can be running with a diverting capture
+ * keyed on that body scope (executeLoaderData), which would swallow the
+ * replay; and the store reads the body scope to tell a live push from a
+ * replayed one.
+ * Outside it, a PPR shell capture classifies replayed pushes as
+ * loader-scoped and unbaked (shell-capture.ts), so a shell HIT gets them
+ * from the loader's own re-run, not twice.
+ */
+async function replayLoaderHandles(
+  encoded: string,
+  handleStore: HandleStore,
+  segmentId: string,
+  claim: ((loaderId: string) => boolean) | undefined,
+): Promise<void> {
+  const recorded = await decodeHandles(encoded);
+  if (!recorded) return;
+  const delivers = new Map<string, boolean>();
+  for (const key in recorded) {
+    const owner = key.slice(key.indexOf(":") + 1);
+    let deliver = delivers.get(owner);
+    if (deliver === undefined) {
+      deliver = claim ? claim(owner) : true;
+      delivers.set(owner, deliver);
+    }
+    if (!deliver) continue;
+    for (const [handleName, values] of Object.entries(recorded[key])) {
+      for (const value of values) {
+        handleStore.pushReplayed(handleName, segmentId, value, owner);
+      }
+    }
+  }
+}
+
+/**
+ * Record key for the MISS capture: run-length groups by the innermost loader
+ * body, `${seq}:${loaderId}` — the cached loader or a dependency it awaits
+ * via ctx.use. Groups keep push order across bodies; the owner lets the
+ * replay deliver each loader's pushes at most once per request.
+ */
+function recordOwnerKey(cachedLoaderId: string): () => string {
+  let seq = 0;
+  let owner: string | undefined;
+  return () => {
+    const current = getCurrentLoaderBodyId() ?? cachedLoaderId;
+    if (current !== owner) {
+      owner = current;
+      seq++;
+    }
+    return `${seq}:${current}`;
+  };
+}
+
 /**
  * Resolve loader data with optional caching.
  *
@@ -131,6 +216,35 @@ function getLoaderStore(
  * (observePhase; see instrument.ts). A cache HIT returns without calling ctx.use,
  * so it emits no loader phase (the loader did not execute; the hit is only a
  * LoaderCache debug log).
+ *
+ * PPR loader lane rule — the canonical source statement; other sites point
+ * here (consumer docs: skills/ppr/SKILL.md "The loader lane rule";
+ * docs/design/loader-container-bake.md). This is the single funnel every
+ * loader segment path routes through (fresh resolveLoaders, cache-hit
+ * resolveLoadersOnly, revalidation resolveLoadersOnlyWithRevalidation, and
+ * intercept loaders in intercept-resolution.ts, which pass no bake key and
+ * never run under a shell capture), so the lane is decided here, per LOADER,
+ * never by the entry's loading():
+ *
+ * - BAKE lane: `loader(Def, { ssr: false })` (awaitBeforeFlush) with a
+ *   `bakeSegmentKey` from the caller. The loader EXECUTES at capture (the
+ *   flag's "data in the HTML before first flush" maps to the frozen prelude)
+ *   and its settled non-promise data bakes into the shell. Promises nested in
+ *   plain objects/arrays are masked (mask-nested.ts) and stay live holes at
+ *   the consumer's own Suspense — per-request material must be promise-shaped
+ *   (the #692 cross-session scar). The masked container registers on
+ *   `_shellCaptureLoaderRecords`: it holds the capture gate (bounded by
+ *   `ppr.captureTimeout`) and pins into the snapshot's loader family, and on a
+ *   HIT the recorded container is overlaid onto the fresh run (below) so the
+ *   payload matches the frozen prelude byte-for-byte. cookies()/headers() in
+ *   its body (nested promise bodies included) trip the capture guard.
+ * - LIVE lane: every other loader, whatever its entry's loading(). Never
+ *   executes at capture: the slot gets a never-resolving promise
+ *   (loader-mask.ts) and postpones at the reader's boundary — loading() or an
+ *   inline Suspense — then streams fresh per request. A masked read with NO
+ *   boundary above it root-postpones and the <body> sanity gate refuses the
+ *   shell (eternal-MISS warning). A route whose loaders are ALL `ssr: false`
+ *   needs no loading(): nothing masks.
  */
 export function resolveLoaderData<TEnv>(
   loaderEntry: LoaderEntry,
@@ -141,42 +255,8 @@ export function resolveLoaderData<TEnv>(
   // 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)) {
-    // Capture lane, per LOADER (not per entry):
-    //
-    // - `ssr: false` (awaitBeforeFlush) — the BAKE lane. The flag's
-    //   document promise is "this loader's data is in the HTML before first
-    //   flush"; under ppr the pre-flush HTML IS the frozen prelude, so the
-    //   loader executes at capture and its SETTLED return bakes into the
-    //   shell. Nested-promise SHAPE stays the liveness declaration: nested
-    //   thenables are masked so their subtrees postpone as holes (per-request
-    //   material must be promise-shaped — the #692 cross-session scar). The
-    //   masked container registers on _shellCaptureLoaderRecords: it holds
-    //   the capture gate (bounded by ppr.captureTimeout) and pins into the
-    //   shell snapshot, so a HIT tail replays the baked value and the
-    //   hydration payload matches the frozen prelude byte-for-byte.
-    // - Every other loader — LIVE unconditionally: masked with a
-    //   never-resolving promise, postponed at its boundary (loading() or an
-    //   inline Suspense), streamed fresh per request. A masked reader with NO
-    //   boundary above it root-postpones and the <body> sanity gate refuses
-    //   the shell (eternal-MISS warning) — the degrade for boundary-less ppr
-    //   routes. A route whose loaders are ALL flagged therefore needs no
-    //   loading() at all: nothing masks, the shell captures complete.
+    // Lane rule: see this function's JSDoc. Flagged = bake, else masked.
     if (loaderEntry.awaitBeforeFlush && bakeSegmentKey) {
       const containerPromise = executeLoaderData(loaderEntry, ctx, pathname);
       // Pre-attach a no-op catch: a bake-lane rejection during capture must
@@ -317,6 +397,16 @@ function executeLoaderData<TEnv>(
   const tags = resolveTags(loaderEntry);
   recordRequestTags(tags);
 
+  // Handle pushes: the store and the owning segment are read synchronously
+  // at kickoff, as createLoaderExecutor does for the body's own pushes.
+  const handleStore = _getRequestContext()?._handleStore;
+  const owningSegmentId = internal._currentSegmentId;
+  // Record only pushes from THIS loader's body and the loaders it awaits via
+  // ctx.use: the handler and sibling loaders push into the same store
+  // concurrently. A dependency can still run on a HIT for another reader
+  // (memoized per request); the replay's claim keeps its pushes to one copy.
+  const isOwnBodyPush = () => isInsideLoaderBody(loaderId);
+
   const dataPromise = (async () => {
     const codec = await getCodec();
     const key = await resolveLoaderKey(
@@ -335,11 +425,63 @@ function executeLoaderData<TEnv>(
     // 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({
+
+    // One readThroughItem call runs at most one execution — the foreground
+    // MISS or the background stale revalidation (flagged by wrapBackground)
+    // — so a single capture slot serves the setItem that follows it.
+    let capture: HandleCapture | undefined;
+    let revalidating = false;
+    let hitHandles: string | undefined;
+    const onCachedRead = (label: string, cached: CacheItemResult) => {
+      hitHandles = cached.handles;
+      debugLoaderCacheLog(`[LoaderCache] ${label}: ${key}`);
+    };
+    const execute = async (): Promise<any> => {
+      // A stale-hit revalidation runs on its own executor: it diverts its
+      // pushes (below), so sharing the page's memoized run of a dependency
+      // would take that dependency's pushes off the page.
+      const run = (revalidating && internal._runLoaderIsolated) || runMiss;
+      if (!handleStore) return run(loaderEntry.loader);
+      // A stale-hit revalidation diverts the body's pushes: the foreground
+      // already replayed the stale entry's, so the fresh ones belong only to
+      // the refreshed entry (not a duplicate in the live response).
+      const c = startHandleCapture(handleStore, {
+        accept: isOwnBodyPush,
+        divert: revalidating,
+        key: recordOwnerKey(loaderId),
+      });
+      capture = c.capture;
+      try {
+        return await run(loaderEntry.loader);
+      } finally {
+        c.stop();
+      }
+    };
+
+    // Flight encodes a rejected promise in the value or a handle push as an
+    // error row and completes normally. setItem runs after serialize and
+    // throws instead of storing it, into readThroughItem's cache-write /
+    // stale-revalidation report; a stale entry keeps serving.
+    const flightErrors: unknown[] = [];
+    const onFlightError = (error: unknown): void => {
+      flightErrors.push(error);
+    };
+
+    const data = await readThroughItem({
       getItem: (k) => store.getItem!(k),
-      setItem: (k, v, o) => store.setItem!(k, v, o),
+      // Handles ride the entry like "use cache" (encodeHandles: Flight, pending
+      // pushes awaited up to its timeout, the whole blob dropped on a timeout
+      // or a thrown encode). Encoded here, inside the deferred write, so a
+      // MISS response never waits on it.
+      setItem: async (k, v, o) => {
+        const handles = capture
+          ? await encodeHandles(capture.data, onFlightError)
+          : "";
+        if (flightErrors.length > 0) throw flightErrors[0];
+        await store.setItem!(k, v, handles ? { ...o, handles } : o);
+      },
       key,
-      execute: () => runMiss(loaderEntry.loader),
+      execute,
       // The rango.background span (kind=loader-revalidation) wraps the WHOLE
       // stale revalidation — the re-execution AND the serialize/setItem write
       // (read-through-swr routes the full task through wrapBackground) — so
@@ -347,21 +489,39 @@ function executeLoaderData<TEnv>(
       // store write all nest under one explanatory parent instead of dangling
       // under the ended foreground phases. Inside runWithRequestContext so
       // observePhase can read tracing on workerd (ALS detaches in waitUntil).
-      wrapBackground: (run) =>
-        runWithRequestContext(requestCtxForExecute, () =>
+      wrapBackground: (run) => {
+        revalidating = true;
+        return runWithRequestContext(requestCtxForExecute, () =>
           observePhase(PHASES.background("loader-revalidation"), run),
-        ),
-      serialize: (d) => codec.serializeResult(d),
+        );
+      },
+      serialize: (d) => codec.serializeResult(d, onFlightError),
       deserialize: (v) => codec.deserializeResult(v),
       storeOptions: { ttl, swr, tags },
-      onHit: () => debugLoaderCacheLog(`[LoaderCache] HIT: ${key}`),
-      onStale: () => debugLoaderCacheLog(`[LoaderCache] STALE: ${key}`),
+      onHit: (cached) => onCachedRead("HIT", cached),
+      onStale: (cached) => onCachedRead("STALE", cached),
       onMiss: () => debugLoaderCacheLog(`[LoaderCache] MISS: ${key}`),
       onCached: () => debugLoaderCacheLog(`[LoaderCache] Cached: ${key}`),
       host: requestCtxForExecute,
     });
+
+    // An entry written before handles were recorded has none: no replay.
+    if (hitHandles && handleStore && owningSegmentId) {
+      await replayLoaderHandles(
+        hitHandles,
+        handleStore,
+        owningSegmentId,
+        internal._claimLoaderPushes,
+      );
+    }
+    return data;
   })();
 
+  // Keep the store open for the replay: a HIT runs no loader body, so nothing
+  // else holds the auxiliary lane while getItem/decode are in flight, and a
+  // push after full drain throws LateHandlePushError.
+  handleStore?.trackAuxiliary(dataPromise);
+
   overrides.set(loaderId, dataPromise);
 
   return dataPromise;

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

@@ -2,13 +2,10 @@
  * 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.
+ * live-lane loaders (lane rule: see resolveLoaderData, loader-cache.ts) must
+ * NOT execute; their value slot gets a never-resolving promise so the
+ * consuming Suspense subtree postpones as a hole, and the serve pass runs them
+ * fresh into it.
  *
  * Capture mode is signalled by `requestCtx._shellCaptureRun`, set to true ONLY on
  * the derived request context of the background capture task (shell-capture.ts) —
@@ -36,24 +33,17 @@ export function isShellCaptureActive(
   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.
+// createMaskedLoaderPromise lives in the leaf module mask-nested.ts, beside
+// maskNestedContainerThenables (also used by the capture handle-store push
+// wrap in rsc/shell-capture.ts). Re-exported to keep the mask API in one place.
 export { createMaskedLoaderPromise } from "./mask-nested.js";
 
 /**
- * Entry-level lane input for an entry's loaders under PPR (the loading()
- * value; docs/design/loader-container-bake.md). The CAPTURE decision itself
- * is per LOADER in loader-cache.ts: an `ssr: false`
- * (awaitBeforeFlush) loader BAKES at capture regardless of this value — the
- * flag's document promise ("data in the HTML before first flush") maps to
- * the frozen prelude — while every other loader is LIVE (masked at capture,
- * fresh on every serve), postponing at loading() or an inline Suspense.
- * This helper still gates which entries pass a bake segment key for the
- * legacy loading()-less shape and the HIT-tail seed overlay.
- *
- * Mirrors segment-system's isRenderableLoading so the mask decision and the
- * tree's boundary placement can never disagree.
+ * True when the entry's loading() is renderable (mirrors segment-system's
+ * isRenderableLoading). Not the lane decision (lane rule: see
+ * resolveLoaderData, loader-cache.ts): callers only use it to decide whether
+ * an unflagged loader's segment key rides as the bake/seed key, which is inert
+ * at capture.
  */
 export function entryLoadingMasksLoaders(loading: unknown): boolean {
   return loading !== undefined && loading !== null && loading !== false;

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

@@ -2,9 +2,9 @@
  * Loader-family capture snapshot: elide + overlay for bake-lane loader
  * containers (docs/design/loader-container-bake.md).
  *
- * A loader on an entry with NO renderable loading() executes during shell
- * capture; its settled container bakes into the prelude while every promise
- * still pending at the quiet window postpones as a hole. To keep a HIT's fresh
+ * A bake-lane loader (lane rule: see resolveLoaderData, loader-cache.ts)
+ * executes during shell capture; its settled container bakes into the prelude
+ * while nested promises postpone as holes. To keep a HIT's fresh
  * payload byte-identical to that frozen prelude, the capture pins the container
  * in the shell snapshot:
  *
@@ -31,9 +31,9 @@
 import { isThenable } from "../../handles/is-thenable.js";
 
 // Capture-side nested-thenable masking lives in the LEAF module mask-nested.ts
-// (request-context also needs it for handle pushes and cannot import through
-// loader-mask without a cycle). Re-exported here so loader-cache and the unit
-// tests keep one import site for the snapshot family.
+// (shared with the capture handle-store push wrap in rsc/shell-capture.ts).
+// Re-exported here so loader-cache and the unit tests keep one import site for
+// the snapshot family.
 export { maskNestedContainerThenables } from "./mask-nested.js";
 
 /**

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

@@ -1,12 +1,12 @@
 /**
  * Capture-side nested-thenable masking — the mechanism behind "nested-promise
  * shape is the liveness declaration" for BOTH bake-lane loader containers
- * (loader-cache.ts) and pushed handle containers (request-context.ts
- * createUseFunction).
+ * (loader-cache.ts) and pushed handle containers (the capture handle store's
+ * push wrap in rsc/shell-capture.ts).
  *
- * Deliberately a LEAF module: request-context needs the mask for handle
- * pushes, and loader-mask (the other natural home) imports request-context —
- * importing from there would cycle. This module imports only is-thenable.
+ * Deliberately a LEAF module: loader-mask (the other natural home) imports
+ * request-context, so any funnel importing the mask from there inherits that
+ * graph. This module imports only is-thenable.
  */
 
 import { isThenable } from "../../handles/is-thenable.js";
@@ -33,8 +33,8 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
  * Deep-copy a container with every NESTED thenable replaced by a masked
  * (never-resolving) promise. Applied during shell capture to (a) bake-lane
  * loader containers (loader-cache.ts) and (b) pushed handle containers
- * (createUseFunction) — the two rango-owned funnels where consumers declare
- * per-request data by promise SHAPE.
+ * (shell-capture.ts capture store push wrap) — the two rango-owned funnels
+ * where consumers declare per-request data by promise SHAPE.
  *
  * Why: a nested promise that happened to SETTLE before the capture's quiet
  * window closed used to bake its value into the SHARED shell (and, for

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

@@ -215,11 +215,11 @@ export async function resolveLoadersWithRevalidation<TEnv>(
   // onError/loader.error. isPartial flags the reporting phase accordingly.
   const errorContext = { ...buildLoaderErrorContext(ctx), isPartial: true };
 
-  // PPR lane decision, same rule as the fresh funnel (fresh.ts): an entry
-  // without renderable loading() puts its loaders on the BAKE lane. The key
-  // must thread through EVERY resolveLoaderData funnel — omitting it here made
-  // a capture-active context whole-container-mask every loader on this path
-  // (a never-settling promise for a loader that should have executed).
+  // PPR bake/seed key, same as fresh.ts (lane rule: see resolveLoaderData,
+  // loader-cache.ts). The key must thread through EVERY resolveLoaderData
+  // funnel — omitting it here made a capture-active context
+  // whole-container-mask every loader on this path (a never-settling promise
+  // for a loader that should have executed).
   // Outside capture the key only activates the _shellLoaderSeed overlay,
   // which document-only serveShellHit seeds — inert for partial requests.
   const bakeLane = !entryLoadingMasksLoaders(entry.loading);
@@ -934,6 +934,8 @@ export async function resolveSegmentWithRevalidation<TEnv>(
   deps: SegmentResolutionDeps<TEnv>,
   actionContext?: ActionContext,
   stale?: boolean,
+  /** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+  chain?: readonly EntryData[],
 ): Promise<SegmentRevalidationResult> {
   const segments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
@@ -1066,6 +1068,7 @@ export async function resolveSegmentWithRevalidation<TEnv>(
     matchedIds.push(...parallelResult.matchedIds);
 
     for (const orphan of entry.layout) {
+      if (chain?.includes(orphan)) continue;
       const orphanResult = await resolveOrphanLayoutWithRevalidation(
         orphan,
         params,
@@ -1274,6 +1277,27 @@ export async function resolveOrphanLayoutWithRevalidation<TEnv>(
   segments.push(...parallelResult.segments);
   matchedIds.push(...parallelResult.matchedIds);
 
+  // Nested routeless entries; see resolveOrphanLayout (fresh.ts).
+  for (const nested of orphan.layout) {
+    const nestedResult = await resolveOrphanLayoutWithRevalidation(
+      nested,
+      params,
+      context,
+      clientSegmentIds,
+      prevParams,
+      request,
+      prevUrl,
+      nextUrl,
+      routeKey,
+      belongsToRoute,
+      deps,
+      actionContext,
+      stale,
+    );
+    segments.push(...nestedResult.segments);
+    matchedIds.push(...nestedResult.matchedIds);
+  }
+
   return { segments, matchedIds };
 }
 
@@ -1296,6 +1320,8 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
   pathname: string,
   deps: SegmentResolutionDeps<TEnv>,
   stale?: boolean,
+  /** The matched route's full chain; see ResolveSegmentOptions.chain (fresh.ts). */
+  chain: readonly EntryData[] = entries,
 ): Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }> {
   const allSegments: ResolvedSegment[] = [];
   const matchedIds: string[] = [];
@@ -1325,7 +1351,8 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
-    if (entry.type === "cache") {
+    // Same latch as resolveAllSegments (fresh.ts), route-level cache() included.
+    if (entry.cache) {
       const store = RangoContext.getStore();
       if (store) store.insideCacheScope = true;
       latchCachedHeaderScope("cache", routeKey);
@@ -1348,6 +1375,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
           deps,
           actionContext,
           stale,
+          chain,
         ),
       (seg) => ({ segments: [seg], matchedIds: [seg.id] }),
       deps,

package/src/router/segment-wrappers.ts

@@ -80,6 +80,8 @@ export interface SegmentWrappers<TEnv = any> {
     interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
+    chain?: readonly EntryData[],
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
   findInterceptForRoute: (
     targetRouteKey: string,
@@ -205,6 +207,7 @@ export function createSegmentWrappers<TEnv = any>(
     localRouteName: string,
     pathname: string,
     stale?: boolean,
+    chain?: readonly EntryData[],
   ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
     return _resolveAllSegmentsWithRevalidation(
       entries,
@@ -222,6 +225,7 @@ export function createSegmentWrappers<TEnv = any>(
       pathname,
       segmentDeps,
       stale,
+      chain,
     );
   }
 

package/src/rsc/render-pipeline.ts

@@ -155,9 +155,12 @@ function createFlightStage<TEnv>(
   if (input.ctx.devDiscoveryEpoch !== undefined && input.payload.metadata) {
     input.payload.metadata.devDiscoveryEpoch = input.ctx.devDiscoveryEpoch;
   }
+  // Read once here: onError can fire outside the ALS frame.
+  const renderErrors = _getRequestContext()?._renderErrors;
   const stream = input.ctx.renderToReadableStream<RscPayload>(input.payload, {
     temporaryReferences: input.temporaryReferences,
     onError: (error: unknown) => {
+      renderErrors?.push(error);
       input.ctx.callOnError(error, "rendering", {
         request: input.request,
         url: input.url,