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

package/dist/bin/rango.js

@@ -1394,7 +1394,7 @@ var init_generate_route_types = __esm({
 function getVirtualVersionContent(version) {
   return `export const VERSION = ${JSON.stringify(version)};`;
 }
-var VIRTUAL_ENTRY_BROWSER, VIRTUAL_ENTRY_SSR, VIRTUAL_IDS;
+var VIRTUAL_ENTRY_BROWSER, VIRTUAL_IDS;
 var init_virtual_entries = __esm({
   "src/vite/plugins/virtual-entries.ts"() {
     "use strict";
@@ -1434,45 +1434,6 @@ async function initializeApp() {
 }
 
 initializeApp().catch(console.error);
-`.trim();
-    VIRTUAL_ENTRY_SSR = `
-import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
-import { renderToReadableStream, resume } from "react-dom/server.edge";
-import { prerender } from "react-dom/static.edge";
-import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
-import {
-  createSSRHandler,
-  createShellCaptureHandler,
-  createShellResumeHandler,
-} from "@rangojs/router/ssr";
-
-export const renderHTML = createSSRHandler({
-  createFromReadableStream,
-  renderToReadableStream,
-  injectRSCPayload,
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
-});
-
-export const captureShellHTML = createShellCaptureHandler({
-  createFromReadableStream,
-  renderToReadableStream,
-  injectRSCPayload,
-  prerender,
-  resume,
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
-});
-
-export const resumeShellHTML = createShellResumeHandler({
-  createFromReadableStream,
-  renderToReadableStream,
-  injectRSCPayload,
-  prerender,
-  resume,
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
-});
 `.trim();
     VIRTUAL_IDS = {
       browser: "virtual:rsc-router/entry.browser.js",

package/dist/vite/index.js

@@ -2210,21 +2210,35 @@ async function initializeApp() {
 
 initializeApp().catch(console.error);
 `.trim();
-var VIRTUAL_ENTRY_SSR = `
-import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+function getVirtualEntrySSR(headScripts = "preinit") {
+  const preinit = headScripts !== "preload";
+  const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference," : "createFromReadableStream,";
+  const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
+  const install = preinit ? `
+// Upgrade client-reference modulepreload hints to executing module scripts in
+// the document head, for every render pass (live SSR, shell capture, resume).
+// See src/ssr/preinit-client-references.ts for the full rationale.
+installClientReferencePreinit(setOnClientReference);
+` : "";
+  const hs = JSON.stringify(headScripts);
+  return `
+import {
+  ${depsImportNames}
+} from "@rangojs/router/internal/deps/ssr";
 import { renderToReadableStream, resume } from "react-dom/server.edge";
 import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
 import {
   createSSRHandler,
   createShellCaptureHandler,
-  createShellResumeHandler,
+  createShellResumeHandler,${ssrImportNames}
 } from "@rangojs/router/ssr";
-
+${install}
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
   renderToReadableStream,
   injectRSCPayload,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -2235,6 +2249,7 @@ export const captureShellHTML = createShellCaptureHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -2245,10 +2260,12 @@ export const resumeShellHTML = createShellResumeHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
 `.trim();
+}
 var RSC_ENTRY_BOOTSTRAP_IMPORTS = [
   "virtual:rsc-router/routes-manifest",
   "virtual:rsc-router/loader-manifest"
@@ -2393,7 +2410,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.146",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -4017,13 +4034,13 @@ function normalizeHostRouterEntry(rawInput, root, exists) {
   }
   return exists(resolve4(root, raw)) ? "./" + raw : raw;
 }
-function createVirtualEntriesPlugin(entries, routerPathRef) {
+function createVirtualEntriesPlugin(entries, routerPathRef, options) {
   const virtualModules = {};
   if (entries.client === VIRTUAL_IDS.browser) {
     virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
   }
   if (entries.ssr === VIRTUAL_IDS.ssr) {
-    virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
+    virtualModules[VIRTUAL_IDS.ssr] = getVirtualEntrySSR(options?.headScripts);
   }
   const knownIds = new Set(Object.keys(virtualModules));
   if (entries.rsc === VIRTUAL_IDS.rsc) {
@@ -7893,7 +7910,11 @@ async function rango(options) {
         }
       }
     });
-    plugins.push(createVirtualEntriesPlugin(finalEntries));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, void 0, {
+        headScripts: resolvedOptions.headScripts
+      })
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
@@ -8073,7 +8094,11 @@ If this is a multi-app host router, export a createHostRouter() instance and set
         }
       }
     });
-    plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, routerRef, {
+        headScripts: resolvedOptions.headScripts
+      })
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
@@ -8217,6 +8242,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.146",
   "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/cache-scope.ts

@@ -452,7 +452,11 @@ export class CacheScope {
       }
 
       // Collect handle data for non-loader segments only
-      const handles = captureHandles(nonLoaderSegments, handleStore);
+      const handles = captureHandles(
+        nonLoaderSegments,
+        handleStore,
+        requestCtx._shellCaptureLoaderHandleValues,
+      );
 
       try {
         if (INTERNAL_RANGO_DEBUG) {
@@ -512,3 +516,28 @@ export function createCacheScope(
   if (!config) return parent; // No config, inherit parent
   return new CacheScope(config.options, parent);
 }
+
+/**
+ * Shell fast path: when the route tree derived NO cache scope and the current
+ * request context carries the `_shellImplicitCache` marker (a shell capture,
+ * or a HIT tail serving an eligible entry), substitute an implicit doc-level
+ * scope so withCacheLookup/withCacheStore treat the WHOLE matched route as a
+ * cache() boundary — the shell entry IS a cache() of the handler layer, with
+ * loaders as the live carve-outs (resolveFreshLoadersAndYield).
+ *
+ * An existing scope — including an explicit cache(false) opt-out — always
+ * wins: the consumer's cache() semantics (their ttl/swr/store/condition) are
+ * never overridden, and cache(false) keeps the tail on the full handler
+ * re-run path.
+ */
+export function resolveShellImplicitCacheScope(
+  scope: CacheScope | null,
+): CacheScope | null {
+  if (scope) return scope;
+  const marker = getRequestContext()?._shellImplicitCache;
+  if (!marker) return null;
+  return new CacheScope(
+    { ttl: marker.ttl, swr: marker.swr, store: marker.store },
+    null,
+  );
+}

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/handle-snapshot.ts

@@ -83,14 +83,35 @@ export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
 /**
  * Capture handle data for a set of segments from the handle store.
  * Used when caching segments to preserve their handle data.
+ *
+ * `exclude` (shell captures: RequestContext._shellCaptureLoaderHandleValues)
+ * drops DSL-loader-scoped push values from the CACHE WRITE only: loaders
+ * re-run fresh on every HIT, so replaying their captured values would
+ * duplicate the fresh push — and their masked nested promises would stall the
+ * Flight handle encode to its timeout. Threaded as an explicit argument so
+ * every other getDataForSegment consumer (the render-barrier snapshot,
+ * prerender) provably sees every push.
  */
 export function captureHandles(
   segments: ResolvedSegment[],
   handleStore: HandleStore,
+  exclude?: WeakSet<object>,
 ): Record<string, SegmentHandleData> {
   const handles: Record<string, SegmentHandleData> = {};
   for (const seg of segments) {
-    handles[seg.id] = handleStore.getDataForSegment(seg.id);
+    const data = handleStore.getDataForSegment(seg.id);
+    if (!exclude) {
+      handles[seg.id] = data;
+      continue;
+    }
+    const filtered: SegmentHandleData = {};
+    for (const [handleName, values] of Object.entries(data)) {
+      const kept = values.filter(
+        (v) => typeof v !== "object" || v === null || !exclude.has(v),
+      );
+      if (kept.length > 0) filtered[handleName] = kept;
+    }
+    handles[seg.id] = filtered;
   }
   return handles;
 }