@rangojs/router 0.0.0-experimental.144 → 0.0.0-experimental.145

package/dist/vite/index.js

@@ -2393,7 +2393,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.144",
+  version: "0.0.0-experimental.145",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -8217,6 +8217,7 @@ function poke() {
   };
 }
 export {
+  directoryClientChunks,
   poke,
   rango
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.144",
+  "version": "0.0.0-experimental.145",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/ppr/SKILL.md

@@ -251,18 +251,18 @@ async function Handler(ctx: HandlerContext) {
 | already-resolved / instant / synchronous values | `loader(() => Promise.resolve(x))` + `loading()`                  | a raw promise that settles inside the quiet window BAKES; only the live lane guarantees live     |
 | none of the above                               | nothing                                                           | it bakes — that is what the shell is for                                                         |
 
-The physics caveat in one line: promise holes are holes because the I/O is
-genuinely pending at capture. If the value can resolve near-instantly (memory
-read, warmed cache), it may bake into the shell — when liveness must be
-guaranteed rather than probable, use the live lane (`loading()`). The same
-physics governs bake-lane nested promises, with one shape guarantee: a nested
-promise that settles inside the window pins its VALUE, but the container key
-KEEPS its promise shape on HITs (the snapshot rehydrates a
-`Promise.resolve(pinned)`), so an unconditional `use(data.x)` consumer never
-breaks — it just reads the pinned value. Note the timing consequence: whether
-such a value is pinned or live can vary per capture (concurrent loader traffic
-extends the quiet window), so treat "fast-resolving promise on the bake lane"
-as PINNED for correctness purposes.
+The physics caveat in one line: HANDLER-created promise props are holes only
+because the I/O is genuinely pending at capture — if the value can resolve
+near-instantly (memory read, warmed cache), it may bake into the shell; when
+liveness must be guaranteed rather than probable, use a loader. BAKE-LANE
+NESTED promises are exempt from that race: the capture MASKS every thenable
+nested in a bake-lane container regardless of settle timing
+(`maskNestedContainerThenables`, loader-cache.ts), so the consuming boundary
+always postpones as a hole and every HIT streams the FRESH value — the
+promise SHAPE is the liveness declaration, not a bet on latency. (Before the
+mask, a nested promise that settled inside the window pinned its capture-time
+value into the shared shell; found live as a storefront basket — with the
+capturing session's identifiers — served to anonymous visitors.)
 
 ### Handles: "nesting = liveness"
 
@@ -272,7 +272,11 @@ as PINNED for correctness purposes.
   by the capture's 5s guard).
 - `ctx.use(H)({ x: promise })` — the container passes through verbatim
   (resolution is shallow); the nested promise streams to the consumer, who must
-  `<Suspense>` it. Under capture that boundary postpones — a hole.
+  `<Suspense>` it. Under capture that boundary postpones — a hole — REGARDLESS
+  of settle timing: the capture masks nested thenables in pushed handle
+  containers (the capture store's push wrap, shell-capture.ts), so even an
+  already-resolved nested promise holes instead of baking its value into the
+  shared shell. Same shape-is-the-declaration rule as bake-lane loaders.
 
 ### Want a hole for already-resolved data?
 
@@ -284,8 +288,9 @@ how fast the value settles.
 
 A loader on an entry with no renderable `loading()` EXECUTES during capture
 (the capture gate holds open for its real latency, bounded by the 5s guard).
-Its settled container bakes into the prelude; every promise still nested in it
-postpones at the consumer's own `<Suspense>` — a hole. On every HIT the
+Its settled container bakes into the prelude; every promise nested in it is
+masked at capture (regardless of how fast it settles) and postpones at the
+consumer's own `<Suspense>` — a hole. On every HIT the
 capture snapshot's loader family overlays the recorded container onto the
 fresh run, so the payload matches the frozen prelude byte-for-byte while the
 nested promises run fresh. The return shape is the declaration:
@@ -552,21 +557,22 @@ evicted by tag at all — move always-fresh data under a `loading()` hole.
 - **The session-object bake trap (the guard cannot save you here)**: the
   capture guard sees `cookies()`/`headers()` calls ONLY. A bake-lane loader
   reading a middleware-provided session object (`ctx.get("session")`) refuses
-  nothing — and its FAST-RESOLVE branch is the killer:
+  nothing. Per-user data survives ONLY behind a nested promise — the shape is
+  the declaration, and it holds for BOTH branches regardless of settle timing
+  (nested thenables are masked at capture):
 
   ```typescript
   const CartLoader = createLoader(async (ctx) => {
     const basketId = ctx.get("session")!.get("basketId");
-    if (!basketId) return { cart: Promise.resolve(null) }; // SETTLED → BAKES
-    return { cart: fetchBasket(basketId) }; // pending → hole
+    if (!basketId) return { cart: Promise.resolve(null) }; // nested thenable → masked → hole, fresh per HIT
+    return { cart: fetchBasket(basketId) }; // nested thenable → masked → hole, fresh per HIT
   });
   ```
 
-  If the capturing request is anonymous (it usually is), `cart: null` bakes
-  and is snapshot-pinned: every logged-in user gets the anonymous badge on
-  every HIT. The branch asymmetry makes it nondeterministic per capture. Any
-  loader whose data is per-user belongs on the live lane — for a header
-  widget, a parallel slot with its own `loading()` (playbook lever 3).
+  The remaining trap is returning per-user data as PLAIN container material:
+  `return { user: session.user }` bakes it into the shared shell like any
+  other settled value — deterministically, not by race. Wrap it in a promise
+  (even an already-resolved one) or put the loader on the live lane.
 
 - **Theme on a HIT is capture-then-corrected**: the resume tree replays the
   CAPTURE's `initialTheme` (resume requires it to match the frozen prelude);

package/src/browser/logging.ts

@@ -63,3 +63,21 @@ export function debugLog(msg: string, ...args: unknown[]): void {
     console.log(msg, ...args);
   }
 }
+
+/**
+ * Boot-sequence debug log: one line per initial-document step (flight decode,
+ * handle stream, bridge wiring, initial tree build, hydration commit), each
+ * stamped with performance.now() so the gap BEFORE hydrateRoot is visible.
+ * The initial document path was otherwise silent — FE debug only started
+ * talking at the first soft navigation, so a boot stall (e.g. an await that
+ * holds initBrowserApp, and with it hydrateRoot) was invisible.
+ */
+export function bootLog(step: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const prefix = `[Browser][boot] ${step} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}

package/src/browser/rsc-router.tsx

@@ -33,6 +33,7 @@ import {
   splitInterceptSegments,
 } from "./intercept-utils.js";
 import { createAppShellRef } from "./app-shell.js";
+import { bootLog, IS_BROWSER_DEBUG } from "./logging.js";
 
 // Vite HMR types are provided by vite/client
 
@@ -156,6 +157,8 @@ export async function initBrowserApp(
     initialTheme,
   } = options;
 
+  bootLog("initBrowserApp start");
+  bootLog("flight decode: awaiting initial payload from document stream");
   const initialPayload =
     await deps.createFromReadableStream<RscPayload>(rscStream);
 
@@ -169,6 +172,14 @@ export async function initBrowserApp(
   // Get initial segments and compute history key from current URL
   const initialSegments = (initialPayload.metadata?.segments ??
     []) as ResolvedSegment[];
+  if (IS_BROWSER_DEBUG) {
+    bootLog("initial payload decoded", {
+      version: initialPayload.metadata?.version,
+      routerId: initialPayload.metadata?.routerId,
+      segments: initialSegments.map((s) => s.id),
+      matched: initialPayload.metadata?.matched,
+    });
+  }
   const initialHistoryKey = generateHistoryKey(window.location.href);
 
   // Create navigation store with history-based caching
@@ -207,11 +218,24 @@ export async function initBrowserApp(
   // This ensures useHandle returns correct data during hydration to avoid mismatch
   // The handles property is an async generator that yields on each push
   if (initialPayload.metadata?.handles) {
+    // This for-await consumes the handle generator to completion BEFORE
+    // hydrateRoot is called — on a streaming/PPR document the generator only
+    // ends when its stream side does, so the per-push logs below are the
+    // primary probe for "the document render is holding hydration".
+    bootLog("handles: consuming payload handle stream (pre-hydration await)");
     const handlesGenerator = initialPayload.metadata.handles;
     let lastHandleData: Record<string, Record<string, unknown[]>> = {};
+    let handlePushes = 0;
     for await (const handleData of handlesGenerator) {
       lastHandleData = handleData;
+      if (IS_BROWSER_DEBUG) {
+        handlePushes += 1;
+        bootLog(`handles: push #${handlePushes}`, {
+          segments: Object.keys(handleData),
+        });
+      }
     }
+    bootLog("handles: stream complete", { pushes: handlePushes });
     // Initialize event controller with initial handle state before hydration.
     eventController.setHandleData(
       lastHandleData,
@@ -221,6 +245,8 @@ export async function initBrowserApp(
     // Update the initial cache entry with the processed handleData
     // The cache entry was created by createNavigationStore but without handleData
     store.updateCacheHandleData(initialHistoryKey, lastHandleData);
+  } else {
+    bootLog("handles: none in payload");
   }
 
   // Create composable utilities
@@ -321,9 +347,17 @@ export async function initBrowserApp(
   if (linkInterception) {
     navigationBridge.registerLinkInterception();
   }
+  bootLog("bridges registered (action + navigation)");
 
   // Build initial tree with rootLayout
+  bootLog("building initial segment tree (renderSegments)");
   const initialTree = renderSegments(initialPayload.metadata!.segments);
+  if (IS_BROWSER_DEBUG && initialTree instanceof Promise) {
+    initialTree.then(
+      () => bootLog("initial segment tree settled"),
+      (err: unknown) => bootLog("initial segment tree rejected", { err }),
+    );
+  }
 
   // Setup HMR with debounce — burst saves (format-on-save, rapid edits)
   // fire many rsc:update events in quick succession. Without debouncing,
@@ -491,9 +525,14 @@ export async function initBrowserApp(
   };
   browserAppContext = context;
 
+  bootLog("initBrowserApp complete -- handing off to hydrateRoot");
   return context;
 }
 
+// Once-flag so the hydration-commit boot log fires a single time (StrictMode
+// re-runs the root effect; the second flush is not a second hydration).
+let hydrationCommitLogged = false;
+
 /**
  * Get the browser app context. Throws if initBrowserApp hasn't been called.
  */
@@ -561,6 +600,10 @@ export function Rango(_props: RangoProps): React.ReactElement {
   // that does not depend on React internals like __reactFiber.
   React.useEffect(() => {
     document.documentElement.dataset.hydrated = "";
+    if (IS_BROWSER_DEBUG && !hydrationCommitLogged) {
+      hydrationCommitLogged = true;
+      bootLog("hydration commit (root effect flushed)");
+    }
   }, []);
 
   return (

package/src/cache/cache-runtime.ts

@@ -412,26 +412,26 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       try {
         const result = await serveCached(cached);
         // Background revalidation — must capture handles if tainted args present.
-        // Use an isolated handle store so background pushes don't pollute the
-        // live response or throw LateHandlePushError on the completed store.
-        // Same isolation pattern as route-level background-revalidation.ts.
         runBackground(requestCtx, async () => {
-          // The closure-captured requestCtx is reused for the framework's own
-          // reads (handle store swap, error reporting) AND, below, to
-          // re-establish the request-context ALS around the user fn. ALS context
-          // may be gone inside waitUntil: on workerd a waitUntil task runs
-          // detached from the request's I/O context, so getRequestContext()
-          // inside the cached body would otherwise throw.
-          let originalHandleStore:
-            | ReturnType<typeof createHandleStore>
-            | undefined;
-          if (hasTaintedArgs && requestCtx) {
-            originalHandleStore = requestCtx._handleStore;
-            requestCtx._handleStore = createHandleStore();
-          }
-          const bgHandleStore = hasTaintedArgs
-            ? requestCtx?._handleStore
-            : undefined;
+          // The background body runs under a DERIVED context with an OWN
+          // _handleStore (the shell-capture isolation pattern —
+          // shell-capture.ts attemptCapture): its handle pushes land in the
+          // isolated store (captured below, persisted with the entry) while
+          // the foreground keeps pushing into the ORIGINAL store, untouched.
+          // Derivation matters because the foreground is STILL RENDERING here
+          // — runBackground/waitUntil starts the task on the next microtask,
+          // not after the response. The previous shape swapped
+          // requestCtx._handleStore in place (restore in finally), which
+          // routed the whole overlap window's foreground pushes into the
+          // background store: lost from the live document AND persisted into
+          // the revalidated entry (issue #684, plan 010).
+          const bgHandleStore =
+            hasTaintedArgs && requestCtx ? createHandleStore() : undefined;
+          const bgCtx: typeof requestCtx = bgHandleStore
+            ? Object.assign(Object.create(requestCtx), {
+                _handleStore: bgHandleStore,
+              })
+            : requestCtx;
           let bgCapture: HandleCapture | undefined;
           let bgStopCapture: (() => void) | undefined;
           if (bgHandleStore) {
@@ -440,28 +440,15 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted ARGS only — not requestCtx. The args stamp guards
-          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
-          // which is sufficient for correctness.
-          //
-          // We intentionally skip stamping requestCtx here because:
-          // 1. runBackground starts the async task synchronously (before the
-          //    first await), so stampCacheExec would pollute the shared
-          //    requestCtx while the foreground pipeline is still running.
-          //    This causes assertNotInsideCacheExec to fire when cache-store
-          //    later calls requestCtx.onResponse().
-          // 2. requestCtx methods are closure-bound to the original ctx, so
-          //    neither Object.create() nor a proxy can isolate the stamp.
-          // 3. The foreground miss path already stamps requestCtx and catches
-          //    cookies()/headers() misuse on first execution. The background
-          //    re-runs the same function with the same request.
-          const bgTaintedArgs: unknown[] = [];
-          for (const arg of args) {
-            if (isTainted(arg)) {
-              stampCacheExec(arg as object);
-              bgTaintedArgs.push(arg);
-            }
-          }
+          // Tainted args are NOT stamped here, in contrast to the foreground
+          // miss path below. The args include the live HandlerContext the
+          // still-rendering foreground holds, and INSIDE_CACHE_EXEC is a
+          // property stamped onto that SHARED object — so for the whole
+          // revalidation window a concurrent foreground ctx.set() /
+          // ctx.headers.*() would throw (issue #684, plan 010). requestCtx is
+          // not stamped for the same reason. In-fn misuse is already caught
+          // by the miss path's stamps on the function's FIRST execution — the
+          // background re-runs the same function with the same request.
 
           try {
             // Re-establish the request-context ALS so a "use cache" body that
@@ -469,8 +456,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // getRequestContext().env.ApiKey) resolves during the background
             // revalidation instead of throwing "called outside of a request
             // context". runWithRequestContext sets the store for fn's
-            // synchronous kickoff; its async continuations inherit it.
-            const scoped = runWithRequestContext(requestCtx, () =>
+            // synchronous kickoff; its async continuations inherit it. The
+            // DERIVED context goes in, so ambient _handleStore reads inside
+            // the body resolve to the isolated store.
+            const scoped = runWithRequestContext(bgCtx, () =>
               runWithCacheTagScope(() => fn.apply(this, args)),
             );
             const freshResult = await scoped.result;
@@ -507,15 +496,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               "[use cache] background revalidation failed",
               requestCtx,
             );
-          } finally {
-            for (const arg of bgTaintedArgs) {
-              unstampCacheExec(arg as object);
-            }
-            // Restore original handle store
-            if (originalHandleStore && requestCtx) {
-              requestCtx._handleStore = originalHandleStore;
-            }
           }
+          // No finally: nothing shared was mutated — the derived context and
+          // its handle store are garbage after the task settles.
         });
         return result;
       } catch (error) {
@@ -601,6 +584,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // inside the cached function body (those side effects are lost on hit).
     // Uses ref-counted stamp/unstamp so overlapping executions
     // sharing the same ctx don't clear each other's guards.
+    //
+    // LOAD-BEARING for the stale-revalidation path above: the background
+    // re-execution deliberately does NOT re-stamp (the objects are live
+    // foreground state mid-render), relying on THIS stamp having caught in-fn
+    // misuse on the function's first execution — an entry only becomes
+    // stale-revalidatable because a stamped miss ran clean and stored it. Do
+    // not create a "use cache" entry via any path that skips this stamp.
     const taintedArgs: unknown[] = [];
     for (const arg of args) {
       if (isTainted(arg)) {

package/src/cache/cf/cf-cache-store.ts

@@ -211,6 +211,8 @@ interface KVShellEnvelope {
   po: string | null;
   /** React.version captured at prerender time */
   rv: string;
+  /** Build version captured at prerender time (ShellCacheEntry.buildVersion) */
+  bv?: string;
   /** createdAt (ms epoch) */
   c: number;
   /** When entry becomes stale (ms epoch) */
@@ -1673,6 +1675,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
           prelude: envelope.p,
           postponed: envelope.po,
           reactVersion: envelope.rv,
+          buildVersion: envelope.bv,
           initialTheme: envelope.i,
           snapshot: envelope.sn,
           createdAt: envelope.c,
@@ -1734,6 +1737,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
               p: entry.prelude,
               po: entry.postponed,
               rv: entry.reactVersion,
+              bv: entry.buildVersion,
               c: entry.createdAt,
               s: staleAt,
               e: staleAt + swrWindow * 1000,

package/src/cache/types.ts

@@ -225,10 +225,13 @@ export interface CacheItemResult {
  * One entry carries BOTH artifacts a resume needs — the rendered HTML prelude
  * and React's postponed state — because the pair is version- and
  * generation-coupled and must never be mixed across a React upgrade or a build
- * change. The reactVersion field is the read-time gate that enforces that: the
- * shell-cache middleware treats an entry whose reactVersion differs from the
- * running React as a miss (the postponed blob is build-coupled and cannot be
- * resumed by a different React).
+ * change. The reactVersion and buildVersion fields are the read-time gates that
+ * enforce both halves: isValidShellHit (rsc/shell-serve.ts) treats an entry
+ * whose reactVersion differs from the running React, or whose buildVersion
+ * differs from the running build, as a miss (the postponed blob encodes hole
+ * positions against one exact tree; resuming it against a different React or a
+ * different app build tree-mismatches inside resume(), AFTER the 200 + prelude
+ * are committed — an unrecoverable broken serve).
  */
 export interface ShellCacheEntry {
   /** Rendered HTML prelude bytes, base64-encoded (stores are JSON-serializing). */
@@ -240,6 +243,17 @@ export interface ShellCacheEntry {
   postponed: string | null;
   /** React.version captured at prerender time; the read-time invalidation gate. */
   reactVersion: string;
+  /**
+   * Build version captured at prerender time (the RSC handler's `version` —
+   * the `@rangojs/router:version` build stamp by default, bumped per build and
+   * on dev RSC-module edits). The second read-time gate: a persistent shared
+   * store (KV/runtime-cache) survives deploys, and an app-code change that
+   * keeps the same React version would otherwise leave a stale-build
+   * prelude+postponed live under the same key. Optional only for entries
+   * stored before the field existed — those are treated as a miss and the
+   * recapture re-stamps them (pre-release, no compat shim).
+   */
+  buildVersion?: string;
   /**
    * The initialTheme the CAPTURE render was built with (the derived context's
    * reqCtx.theme). The resume tail must render ThemeProvider with the SAME

package/src/cache/vercel/vercel-cache-store.ts

@@ -177,6 +177,8 @@ interface VercelShellEnvelope {
   po: string | null;
   /** React.version at capture. */
   rv: string;
+  /** Build version at capture (ShellCacheEntry.buildVersion). */
+  bv?: string;
   /** createdAt (ms since epoch). */
   c: number;
   /** staleAt (ms since epoch). */
@@ -776,6 +778,7 @@ export class VercelCacheStore<
         prelude: env.p,
         postponed: env.po,
         reactVersion: env.rv,
+        buildVersion: env.bv,
         initialTheme: env.i,
         snapshot: env.sn,
         createdAt: env.c,
@@ -805,6 +808,7 @@ export class VercelCacheStore<
         p: entry.prelude,
         po: entry.postponed,
         rv: entry.reactVersion,
+        bv: entry.buildVersion,
         c: entry.createdAt,
         s: staleAt,
         e: expiresAt,
@@ -1091,7 +1095,7 @@ export class VercelCacheStore<
 
   private asShellEnvelope(raw: unknown): VercelShellEnvelope | null {
     if (!isRecord(raw)) return null;
-    const { p, po, rv, c, s, e, t, i, sn } = raw;
+    const { p, po, rv, bv, c, s, e, t, i, sn } = raw;
     if (typeof p !== "string" || typeof rv !== "string") return null;
     if (po !== null && typeof po !== "string") return null;
     if (typeof c !== "number") return null;
@@ -1100,6 +1104,7 @@ export class VercelCacheStore<
       p,
       po: po as string | null,
       rv,
+      bv: typeof bv === "string" ? bv : undefined,
       c,
       s,
       e,

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

@@ -36,7 +36,10 @@ import {
   DEFAULT_ROUTE_TTL,
 } from "../../cache/cache-policy.js";
 import { readThroughItem } from "../../cache/read-through-swr.js";
-import { overlayLoaderContainer } from "./loader-snapshot.js";
+import {
+  maskNestedContainerThenables,
+  overlayLoaderContainer,
+} from "./loader-snapshot.js";
 import { recordRequestTags } from "../../cache/cache-tag.js";
 import {
   isShellCaptureActive,
@@ -162,8 +165,21 @@ export function resolveLoaderData<TEnv>(
     // never as an unhandled rejection that can kill the worker before the
     // drain probes this record.
     containerPromise.catch(() => {});
-    reqCtx?._shellCaptureLoaderRecords?.set(bakeSegmentKey, containerPromise);
-    return containerPromise;
+    // 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) {

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

@@ -36,17 +36,10 @@ export function isShellCaptureActive(
   return reqCtx?._shellCaptureRun === true;
 }
 
-/**
- * A promise that never settles — the masked stand-in for a loader's value during
- * shell capture. The consuming Suspense subtree suspends forever, so the static
- * prerender postpones it as a hole instead of baking a per-request value into the
- * shared shell. The capture abort (`maxWaitMs` in captureShellHTML) bounds how
- * long the prerender waits before it freezes the prelude, so this never hangs the
- * request.
- */
-export function createMaskedLoaderPromise<T = unknown>(): Promise<T> {
-  return new Promise<T>(() => {});
-}
+// 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;

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

@@ -8,12 +8,14 @@
  * payload byte-identical to that frozen prelude, the capture pins the container
  * in the shell snapshot:
  *
- *   - elide:   deep-walk the settled container; a SETTLED nested promise baked
- *              its value (physics: it won the quiet window), so it is pinned as
- *              that value wrapped in a SETTLED marker — the wrapper remembers
- *              "this was a promise" so the overlay can rehydrate the shape; a
- *              PENDING nested promise is a hole, replaced by
- *              {@link LOADER_HOLE_KEY}. The result is promise-free and
+ *   - elide:   deep-walk the settled container; a PENDING nested promise is a
+ *              hole, replaced by {@link LOADER_HOLE_KEY} — and since
+ *              loader-cache masks every nested thenable at capture
+ *              ({@link maskNestedContainerThenables}), nested promises are
+ *              ALWAYS pending here for new captures. The SETTLED-marker branch
+ *              below is legacy: it fires only if a settled thenable reaches
+ *              elide anyway, and the overlay keeps decoding SETTLED markers
+ *              from pre-mask snapshots. The result is promise-free and
  *              Flight-serializable.
  *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
  *              the live nested promises), then the recorded container is laid
@@ -28,6 +30,12 @@
 
 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.
+export { maskNestedContainerThenables } from "./mask-nested.js";
+
 /**
  * Marker object standing in for a pending nested promise in a recorded loader
  * container. Shape-checked (not identity-checked) because the record round-trips