@rangojs/router 0.0.0-experimental.141 → 0.0.0-experimental.142

package/src/rsc/rsc-rendering.ts

@@ -11,7 +11,10 @@ import {
   setRequestContextParams,
   runWithRequestContext,
 } from "../server/request-context.js";
-import { SeededShellStore } from "../cache/shell-snapshot.js";
+import {
+  SeededShellStore,
+  buildShellLoaderSeed,
+} from "../cache/shell-snapshot.js";
 import { appendMetric } from "../router/metrics.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
@@ -38,7 +41,10 @@ import {
   base64ToBytes,
   hasShellFamily,
   warnShellStoreMissingOnce,
+  warnPprNonceActiveOnce,
 } from "./shell-serve.js";
+import { contextGet } from "../context-var.js";
+import { nonce as nonceToken } from "./nonce.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 import type { ShellCacheEntry } from "../cache/types.js";
@@ -107,16 +113,33 @@ async function handleRscRenderingInner<TEnv>(
   } | null = null;
   if (
     !isPartial &&
-    nonce === undefined &&
     request.method === "GET" &&
     !url.searchParams.has("__prerender_collect") &&
     !isRscRequest(request, url, false)
   ) {
     const pprConfig = resolvePprConfig(reqCtx._classifiedRoute?.manifestEntry);
     if (pprConfig) {
+      // A per-request CSP nonce pins the route to axis 1: useNonce() (and any app
+      // code reading the nonce) renders it into every nonced script/style/meta, so
+      // a shell shared per host+URL would freeze one request's nonce for every
+      // visitor and the browser's CSP would reject the frozen nonce for all but the
+      // capture request. The nonce arrives two ways and BOTH must gate: the
+      // createRouter({ nonce }) provider (threaded here as `nonce`), and a direct
+      // token write in middleware (ctx.set(nonce, value)). The token is only
+      // visible in the post-middleware request variables — and this commit point
+      // runs AFTER the whole middleware chain (see the block header), so it is
+      // present here. Reading it closes the gap the provider-only check left open
+      // (issue #656). The threaded-param check stays first: the provider path is
+      // resolved before any variable read and short-circuits cheaply.
+      const activeNonce = nonce ?? contextGet(reqCtx._variables, nonceToken);
       const store = reqCtx._cacheStore;
       const key = buildShellKey(url);
-      if (!hasShellFamily(store)) {
+      if (activeNonce !== undefined) {
+        // Declared intent that cannot be honored deserves a diagnostic (unlike an
+        // undeclared route, which is silent): a ppr route gated off by an active
+        // per-request nonce warns once per key. Axis 1 after the warning.
+        warnPprNonceActiveOnce(key);
+      } else if (!hasShellFamily(store)) {
         // Declared intent that cannot be honored deserves a diagnostic (unlike an
         // undeclared route, which is silent). Axis 1 after the warning.
         warnShellStoreMissingOnce(key);
@@ -469,12 +492,20 @@ function serveShellHit(
     // never recorded) falls through to the real store and stays LIVE. The
     // overlay lives on a DERIVED context (own _cacheStore), so the shared reqCtx
     // is untouched; an entry without a snapshot keeps the pre-snapshot behavior.
-    if (entry.snapshot && entry.snapshot.length > 0 && reqCtx._cacheStore) {
+    if (entry.snapshot && entry.snapshot.length > 0) {
       const seededCtx: RequestContext<any> = Object.create(reqCtx);
-      seededCtx._cacheStore = new SeededShellStore(
-        reqCtx._cacheStore,
-        entry.snapshot,
-      );
+      if (reqCtx._cacheStore) {
+        seededCtx._cacheStore = new SeededShellStore(
+          reqCtx._cacheStore,
+          entry.snapshot,
+        );
+      }
+      // Loader-family records (bake-lane containers, loader-container-bake):
+      // decode into a seed Map for the resolveLoaderData overlay, so the
+      // payload's baked container bytes match the frozen prelude while the
+      // hole-marker paths keep the fresh run's live nested promises.
+      const loaderSeed = await buildShellLoaderSeed(entry.snapshot);
+      if (loaderSeed) seededCtx._shellLoaderSeed = loaderSeed;
       return runWithRequestContext(seededCtx, () => renderTail(seededCtx));
     }
     return renderTail(reqCtx);

package/src/rsc/shell-capture.ts

@@ -33,6 +33,10 @@ import type {
   SegmentCacheStore,
   ShellSnapshotRecord,
 } from "../cache/types.js";
+import {
+  elideLoaderContainer,
+  isLoaderHoleMarker,
+} from "../router/segment-resolution/loader-snapshot.js";
 import {
   RecordingShellStore,
   getRecordingStore,
@@ -169,7 +173,8 @@ const inFlightCaptures = new Set<string>();
 
 /**
  * Refused-capture backoff bounds. The window is EXPONENTIAL in the consecutive
- * failure count: `min(BASE * 2^(failures-1), MAX)` — 1s, 2s, 4s, … capped at 60s.
+ * failure count: `min(BASE * 2^(failures-1), ceiling)` — 1s, 2s, 4s, … up to the
+ * mode's ceiling (60s in production, {@link REFUSED_CAPTURE_DEV_MAX_MS} in dev).
  *
  * Why exponential and not a flat 60s: a flat long window conflates two very
  * different failures. A STRUCTURALLY ineligible route (no loading(), a cookie
@@ -179,12 +184,44 @@ const inFlightCaptures = new Set<string>();
  * request or two, not be frozen for 60s (that would re-break the very cold-start DX
  * the retry fixes; it bit the cloudflare dev e2e). Escalating from 1s means the
  * eligible route re-probes almost immediately (warm now → HIT and clear), while the
- * doomed route ramps to the 60s cap within a handful of failures. Either way an
+ * doomed route ramps to the ceiling within a handful of failures. Either way an
  * app-wide mount never re-renders a doomed route on EVERY request.
  */
 const REFUSED_CAPTURE_BASE_MS = 1_000;
 const REFUSED_CAPTURE_MAX_MS = 60_000;
 
+/**
+ * DEV-only backoff ceiling. In dev the 60s production cap is pure harm: the
+ * dominant no-shell cause is a COLD module graph (route modules, SSR/Flight
+ * transforms built lazily), and the very attempt that failed WARMS that graph, so
+ * the next attempt a beat later usually completes the shell. Capping the dev window
+ * low keeps a cold-but-eligible route re-probing every ~2s instead of freezing for
+ * up to 60s once the exponential climbs (1s→2s→4s→…→60s). A 60s freeze outlasts the
+ * e2e warm windows on cold CI runners: the capture races an unfinished shell,
+ * escalates the backoff past the poll window, and every subsequent request inside
+ * that window is skipped as backed-off — an eternal MISS for the test even though
+ * the modules are warm by then. Production keeps the full 60s cap: there the
+ * no-shell cause is far more likely to be a genuinely ineligible route (no
+ * loading()), which SHOULD be re-probed rarely. See #652 (item 3) and
+ * docs/design/ppr-shell-resume.md ("Refused-capture backoff").
+ */
+const REFUSED_CAPTURE_DEV_MAX_MS = 2_000;
+
+/**
+ * Dev signal, matching the rest of the RSC runtime (handler.ts, server-action.ts,
+ * progressive-enhancement.ts): treat anything but an explicit production build as
+ * dev. The build folds `process.env.NODE_ENV` to a literal, so this is a compile-
+ * time constant in the shipped worker — no runtime probe.
+ */
+function isDevMode(): boolean {
+  return process.env.NODE_ENV !== "production";
+}
+
+/** The active backoff ceiling for the current mode (dev capped low, prod at 60s). */
+function refusedCaptureCeilingMs(): number {
+  return isDevMode() ? REFUSED_CAPTURE_DEV_MAX_MS : REFUSED_CAPTURE_MAX_MS;
+}
+
 /**
  * Refused-capture backoff: key -> { consecutive failure count, epoch ms until which
  * the key is not re-probed }. A key enters backoff only after runShellCapture's
@@ -203,12 +240,19 @@ function isCaptureBackedOff(key: string): boolean {
   return Date.now() < entry.until;
 }
 
-/** Record a refused/failed capture, escalating the backoff window exponentially. */
+/**
+ * Record a refused/failed capture, escalating the backoff window exponentially up
+ * to the current mode's ceiling. The failure count keeps climbing across attempts
+ * (so a genuinely doomed route still ramps toward its cap), but the WINDOW is
+ * clamped: 60s in production, {@link REFUSED_CAPTURE_DEV_MAX_MS} in dev so a
+ * cold-but-eligible route re-probes fast instead of freezing out the e2e warm
+ * window on a cold CI runner (#652 item 3).
+ */
 function markCaptureBackoff(key: string): void {
   const failures = (refusedCaptures.get(key)?.failures ?? 0) + 1;
   const window = Math.min(
     REFUSED_CAPTURE_BASE_MS * 2 ** (failures - 1),
-    REFUSED_CAPTURE_MAX_MS,
+    refusedCaptureCeilingMs(),
   );
   refusedCaptures.set(key, { failures, until: Date.now() + window });
 }
@@ -243,21 +287,46 @@ function warnNullCaptureOnce(key: string): void {
   warnedNullCaptures.add(key);
   console.warn(
     `[rango] Shell capture for "${key}" produced no usable shell after an in-place ` +
-      "retry; nothing was stored, so this request stays on MISS. Two things cause this, " +
-      "told apart by whether the route ever flips to HIT:\n" +
+      "retry; nothing was stored, so this request stays on MISS. Causes, told apart " +
+      "by whether the route ever flips to HIT:\n" +
       "  1. Cold-start warmup (dev module transform, or a cold worker): the capture raced " +
       "an unfinished shell render. This SELF-HEALS — the route flips to HIT once a later " +
       "request warms the modules. Usually nothing to do.\n" +
-      "  2. A loader route WITHOUT a route-level loading() boundary: its loader data is " +
-      "awaited at tree-build, so under capture's masked loaders no shell exists above " +
-      "<body>, and the route NEVER flips to HIT. Add loading() to the loader route (and " +
-      "keep shell material in a layout) to make it PPR-capturable.\n" +
+      "  2. Something suspends above <body> with no Suspense boundary and never settles " +
+      "within the capture window: a slower-than-the-capture-guard bake-lane loader " +
+      "(loaders on entries WITHOUT loading() execute at capture and their containers " +
+      "bake — the boundary-less await must settle for a shell to exist), or a pending " +
+      "promise consumed without a <Suspense> above it. The boundary belongs on the " +
+      "entry/component that OWNS the data: loading() on the entry that registers the " +
+      "loader (a child route's loading() does not unpin a parent layout's loaders), or " +
+      "a <Suspense> above the consuming component.\n" +
       'See the /ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md), "The hole ' +
-      'contract", or the design doc: ' +
+      'doctrine" and "The layout-with-loaders playbook", or the design docs: ' +
       "https://github.com/ivogt/vite-rsc/blob/main/packages/rangojs-router/docs/design/ppr-shell-resume.md",
   );
 }
 
+/** Keys already warned about a deterministic capture refusal (once per key). */
+const warnedRefusedCaptures = new Set<string>();
+
+/**
+ * Warn once per key that the capture was REFUSED for a deterministic reason
+ * (identity-guard trip or a rejected bake-lane loader). Distinct from
+ * warnNullCaptureOnce: these are not cold-start shapes, the retry is skipped,
+ * and the message carries the concrete cause instead of a differential.
+ */
+function warnCaptureRefusedOnce(key: string, reason: string): void {
+  if (warnedRefusedCaptures.has(key)) return;
+  warnedRefusedCaptures.add(key);
+  console.warn(
+    `[rango] Shell capture for "${key}" was refused: ${reason}\n` +
+      "The route stays on MISS (axis 1) — the page keeps working, only the shell " +
+      "cache is off. See the /ppr skill " +
+      "(node_modules/@rangojs/router/skills/ppr/SKILL.md) and " +
+      "docs/design/loader-container-bake.md.",
+  );
+}
+
 export interface FlightCaptureGate {
   /** Identity passthrough of the source stream; feed this to captureShellHTML. */
   stream: ReadableStream<Uint8Array>;
@@ -504,7 +573,7 @@ export function scheduleShellCapture(
  * - `no-shell`: the prelude came back trivial (no <body>) OR captureShellHTML
  *   rejected with our own abort. This is the only RETRYABLE outcome.
  */
-type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell";
+type CaptureAttemptOutcome = "stored" | "redirect" | "no-shell" | "refused";
 
 /**
  * Run the shell capture with a single in-place retry, then store the result.
@@ -547,6 +616,10 @@ async function runShellCapture(
     ssrModule,
     descriptor,
   );
+  // "refused" is deterministic (identity guard / rejected bake-lane loader —
+  // its own warning already fired): no retry, and the caller backs the key off
+  // exactly like a structural no-shell.
+  if (first === "refused") return "no-shell";
   // "stored" (success) or "redirect" (no shell exists): nothing to retry.
   if (first !== "no-shell") return first;
 
@@ -568,6 +641,7 @@ async function runShellCapture(
     ssrModule,
     descriptor,
   );
+  if (second === "refused") return "no-shell";
   if (second !== "no-shell") return second;
 
   // Both attempts came back with no usable shell. Cold-start would have healed by
@@ -641,6 +715,11 @@ async function attemptCapture(
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
   derivedCtx._metricsStore = undefined;
+  // Bake-lane loader containers (loaders on entries with no renderable
+  // loading() execute during capture — docs/design/loader-container-bake.md).
+  // resolveLoaderData registers each container promise here; the drain in
+  // captureAndStoreShell elides + pins them into the snapshot's loader family.
+  derivedCtx._shellCaptureLoaderRecords = new Map();
   // Own onResponse list so the capture's match-middleware callbacks (the ring-3
   // segment cache write registers here) are ISOLATED from the foreground's shared
   // array AND can be fired by captureAndStoreShell. The segment write is gated
@@ -765,13 +844,44 @@ async function captureAndStoreShell(
   // Bounded by maxWaitMs like every quiesce input (a defer hanging on a masked
   // loader still ends in the sanity-gate refusal).
   const handlesBaked = handleStore.getData().then(resolveDeferredHandleValues);
-  const gate = gateFlightForCapture(rscStream, undefined, handlesBaked);
+  // Bake-lane loader containers hold the gate the same way (loader-container-
+  // bake): a boundary-less container with real latency (a 100ms layout loader)
+  // would otherwise lose the 2-hop byte-quiet race — the pending loaderData row
+  // emits no bytes, the gate freezes, and the awaiting tree pins above <body>.
+  // The records map is fully populated before this point (loader promises are
+  // created during the capture's match()), so the hold covers every bake-lane
+  // container. allSettled: a REJECTED container releases the hold (the drain
+  // below refuses the capture); nested promises INSIDE a container never hold
+  // the gate — they stay holes. Bounded by maxWaitMs like every quiesce input.
+  const loaderRecordsForHold = reqCtx._shellCaptureLoaderRecords;
+  const holdUntil =
+    loaderRecordsForHold && loaderRecordsForHold.size > 0
+      ? Promise.allSettled([handlesBaked, ...loaderRecordsForHold.values()])
+      : handlesBaked;
+  const gate = gateFlightForCapture(rscStream, undefined, holdUntil);
   // Quiesce = handles settled AND the Flight shell rows went task-quiet. Either
   // half stalling is bounded by captureShellHTML's maxWaitMs.
   const quiesce = Promise.all([handleStore.settled, gate.quiesce]).then(
     () => {},
   );
 
+  // Deterministic identity-guard refusal, checked at BOTH exits below: the
+  // guard error either rejects the prerender itself (boundary-less segment —
+  // lands in the catch) or is swallowed into per-loader error UI (the render
+  // completes — caught after the try). One helper so the message and the
+  // "refused" mapping cannot drift between the two sites.
+  const refuseOnGuardTrip = (): "refused" | undefined => {
+    const fnName = reqCtx._shellCaptureGuardTripped;
+    if (!fnName) return undefined;
+    warnCaptureRefusedOnce(
+      capture.key,
+      `a bake-lane loader (a loader on an entry with no loading()) called ${fnName}() during capture. ` +
+        "Identity must not bake into a shared shell. Give that loader's entry a loading() boundary " +
+        "(the live lane, exempt from the guard) or move the identity-dependent part into a nested promise.",
+    );
+    return "refused";
+  };
+
   try {
     // captureShellHTML CONSUMES the (gated) stream — it is not also SSR'd.
     let result: Awaited<ReturnType<typeof captureShellHTML>>;
@@ -783,6 +893,10 @@ async function captureAndStoreShell(
         }),
       );
     } catch (error) {
+      // Guard-tripped rejection arrives here (not at the drain) — refuse
+      // BEFORE the AbortError-vs-rethrow decision below.
+      const refused = refuseOnGuardTrip();
+      if (refused) return refused;
       // captureShellHTML normally converts its OWN deliberate abort to a null
       // return (index.tsx). This catch is defensive: if an AbortError still escapes
       // (a runtime where the abort surfaces as a stream rejection outside its
@@ -801,6 +915,13 @@ async function captureAndStoreShell(
     // yet finished; on a loader route WITHOUT a route-level loading() boundary it is
     // the structural eternal-MISS shape (the masked loader pins the tree above
     // <body> at tree-build). The caller's warning names both.
+    // Guard check first — BEFORE the trivial-prelude retry path. A guard trip
+    // is deterministic (retrying re-trips it), and when the tripping loader's
+    // error UI still completed a shell, storing it would bake the failure into
+    // a shared page.
+    const refused = refuseOnGuardTrip();
+    if (refused) return refused;
+
     if (result === null) {
       return "no-shell";
     }
@@ -847,6 +968,54 @@ async function captureAndStoreShell(
       snapshot = recording.drainSnapshot();
     }
 
+    // Pin the bake-lane loader containers (loader family). Settled containers
+    // are promise-elided (a still-pending nested promise is a hole marker, not
+    // shell material) and Flight-serialized; a REJECTED container refuses the
+    // capture — per-loader error UI must never bake into the shared shell. A
+    // container still pending here either pinned the tree (the trivial-prelude
+    // gate above already returned no-shell) or postponed under an ANCESTOR
+    // boundary (it is a hole; omitting the record keeps it live).
+    const loaderRecords = reqCtx._shellCaptureLoaderRecords;
+    if (loaderRecords && loaderRecords.size > 0) {
+      // The codec import is deferred past the elide probes: a rejected record
+      // refuses and a never-settled record is omitted WITHOUT touching Flight
+      // (also keeps the virtual @vitejs/plugin-rsc import out of unit configs).
+      let serializeContainer:
+        | typeof import("../cache/segment-codec.js").serializeResult
+        | undefined;
+      for (const [segmentKey, containerPromise] of loaderRecords) {
+        const elided = await elideLoaderContainer(containerPromise);
+        if (elided.state === "rejected") {
+          warnCaptureRefusedOnce(
+            capture.key,
+            `the loader for segment "${segmentKey}" rejected during capture; its error UI must not bake into the shared shell. ` +
+              "Fix the loader, or give its entry a loading() boundary so it stays on the live lane.",
+          );
+          return "refused";
+        }
+        // The container itself never settled: it is a hole (under an ancestor
+        // boundary) or the trivial-prelude gate already fired. Omit — no pin.
+        if (isLoaderHoleMarker(elided.value)) continue;
+        try {
+          // serializeResult (not rscSerialize): null is a valid container and
+          // must round-trip; serializeResult preserves it through Flight.
+          serializeContainer ??= (await import("../cache/segment-codec.js"))
+            .serializeResult;
+          const serialized = await serializeContainer(elided.value);
+          if (serialized !== null) {
+            (snapshot ??= []).push({
+              family: "loader",
+              key: segmentKey,
+              value: { value: serialized },
+            });
+          }
+        } catch {
+          // Non-serializable container: leave it unpinned (it drifts on a HIT,
+          // the pre-snapshot behavior) rather than failing the capture.
+        }
+      }
+    }
+
     const store = capture.store ?? reqCtx._cacheStore;
     if (store?.putShell) {
       try {
@@ -895,3 +1064,17 @@ async function captureAndStoreShell(
 
 // Exported for unit tests that drive the capture core directly.
 export { runShellCapture, captureAndStoreShell };
+
+// Exported for unit tests that pin the refused-capture backoff policy directly
+// (dev cap vs production exponential growth, stored-clears, cold-start re-probe).
+// These are the same module-level functions the schedule path uses; a test that
+// drove them through a real capture round-trip could not assert the exact window
+// arithmetic without a full cold render.
+export {
+  isCaptureBackedOff,
+  markCaptureBackoff,
+  clearCaptureBackoff,
+  REFUSED_CAPTURE_BASE_MS,
+  REFUSED_CAPTURE_MAX_MS,
+  REFUSED_CAPTURE_DEV_MAX_MS,
+};

package/src/rsc/shell-serve.ts

@@ -122,3 +122,29 @@ export function warnShellStoreMissingOnce(key: string): void {
       "via createRouter({ cache }).",
   );
 }
+
+/** Keys already warned about an active per-request nonce (once per key). */
+const warnedNonceActive = new Set<string>();
+
+/**
+ * Warn once per key that a route declared `ppr` but a per-request CSP nonce is
+ * active for the request, so the route stays on axis 1 (a shared shell would
+ * freeze one request's nonce for every visitor — useNonce() renders it into every
+ * nonced script/style/meta and the browser's CSP would then reject the frozen
+ * nonce for all but the capture request). The nonce blocks capture whether it came
+ * from the `createRouter({ nonce })` provider or from a direct `ctx.set(nonce, …)`
+ * token write in middleware. Same declared-intent-cannot-be-honored doctrine as
+ * the missing-store warning above (an undeclared route stays silent).
+ */
+export function warnPprNonceActiveOnce(key: string): void {
+  if (warnedNonceActive.has(key)) return;
+  warnedNonceActive.add(key);
+  console.warn(
+    `[rango] Route for "${key}" declares the ppr path option, but a per-request ` +
+      "CSP nonce is active for this request (from createRouter({ nonce }) or a " +
+      "ctx.set(nonce, …) token write in middleware), so the route is served on " +
+      "axis 1 without a shell. A shell is shared per host+URL; baking one " +
+      "request's nonce into it would break CSP for every other visitor. Drop the " +
+      "ppr option on this route, or stop setting a per-request nonce for it.",
+  );
+}

package/src/server/cookie-store.ts

@@ -164,6 +164,12 @@ function assertNotInsideShellCapture(ctx: unknown, fnName: string): void {
     typeof ctx === "object" &&
     (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun === true
   ) {
+    // Flag the capture context BEFORE throwing: inside an executing bake-lane
+    // loader this throw is swallowed by wrapLoaderPromise into per-loader error
+    // UI, which would bake silently into the shared shell. The capture checks
+    // the flag after the render and refuses (shell-capture.ts).
+    (ctx as { _shellCaptureGuardTripped?: string })._shellCaptureGuardTripped =
+      fnName;
     throw new Error(
       `${fnName}() cannot be called while capturing a shared shell ` +
         `(shell-cache middleware). The captured shell is served to every user ` +

package/src/server/request-context.ts

@@ -187,6 +187,39 @@ export interface RequestContext<
    */
   _shellCaptureRun?: boolean;
 
+  /**
+   * @internal Bake-lane loader containers collected DURING a shell capture:
+   * segment-key -> the loader's (pre-wrap) result promise. Populated by
+   * resolveLoaderData for loaders on entries with no renderable loading() (the
+   * bake lane — they execute at capture instead of being masked; see
+   * docs/design/loader-container-bake.md). Drained by captureAndStoreShell
+   * after the shell quiesces: settled containers are promise-elided,
+   * Flight-serialized, and pinned into the snapshot's loader family; a
+   * REJECTED container refuses the capture (error UI must never bake into the
+   * shared shell). Own property of the capture's derived context only.
+   */
+  _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
+
+  /**
+   * @internal Loader-family snapshot seed for a shell HIT's tail render:
+   * segment-key -> the capture's elided container (already Flight-deserialized
+   * by serveShellHit). resolveLoaderData overlays it onto the fresh run's
+   * container (recorded paths pinned, hole-marker paths keep the fresh nested
+   * promises) so the payload's baked bytes match the frozen prelude. Own
+   * property of the HIT tail's derived context only.
+   */
+  _shellLoaderSeed?: Map<string, unknown>;
+
+  /**
+   * @internal Set (to the offending fn name) by the cookies()/headers()
+   * capture guard when it throws DURING a capture render. Load-bearing for the
+   * bake lane: a guard throw inside an executing loader is swallowed by
+   * wrapLoaderPromise into per-loader error UI, which would otherwise bake
+   * silently into the shared shell — the capture checks this flag after the
+   * render and refuses instead. Deterministic, so the capture does not retry.
+   */
+  _shellCaptureGuardTripped?: string;
+
   /**
    * @internal Handler-owned registry of explicit per-scope stores from
    * cache({ store }). Created once per createRSCHandler() and threaded into

package/src/ssr/index.tsx

@@ -470,6 +470,13 @@ export function createShellCaptureHandler<TEnv = unknown>(
         reportRenderError(onError, error);
       },
     });
+    // Pre-attach a no-op catch: the real await sits AFTER quiesce + the
+    // post-quiesce hops, so an early prerender rejection (e.g. a bake-lane
+    // loader tripping the identity guard within milliseconds) would otherwise
+    // spend several turns handler-less and crash the worker as an unhandled
+    // rejection. The actual rejection handling still happens at the await
+    // below; this parallel handler only keeps the gap crash-free.
+    prerenderPromise.catch(() => {});
 
     // Wait for the caller's quiesce signal. By the time it resolves the Flight
     // input is byte-quiet and FROZEN by the capture gate (shell-capture.ts

package/src/vite/discovery/dev-prerender-cache.ts

@@ -0,0 +1,117 @@
+/**
+ * Dev prerender result cache — memoizes /__rsc_prerender responses between
+ * HMR edits (issue #654).
+ *
+ * Freshness invariant (why identity keying is correct): the endpoint
+ * re-imports the user's entry module through a Vite module runner on every
+ * request. When ANY module in the entry → router → urls → handler chain was
+ * invalidated (file edit propagates up the importer graph), that import
+ * re-executes the entry, `createRouter()` re-runs, and `RouterRegistry.set`
+ * (router.ts) replaces the router instance with a NEW object. When nothing
+ * was invalidated, the import is a module-cache hit and the instance is the
+ * SAME object. Router-instance identity therefore IS the HMR generation:
+ * keying the cache on it gives "serve cached until an edit invalidates the
+ * chain" without any watcher bookkeeping, and the WeakMap lets every stale
+ * generation's bucket be garbage-collected the moment the registry drops
+ * the old instance.
+ *
+ * Staleness envelope: a cached body can only go stale through NON-module
+ * inputs (a getParams() reading a database, fs content outside the module
+ * graph). Production freezes those at build time, so serving them frozen
+ * between edits makes dev MORE faithful to production, not less — the
+ * pre-#654 behavior of re-rendering per request was the anomaly.
+ */
+
+import type { SerializedSegmentData } from "../../cache/types.js";
+
+/** Structural slice of `matchForPrerender`'s result the payload derivation needs. */
+export interface DevPrerenderMatchPayloadSource {
+  segments: SerializedSegmentData[];
+  handles: string;
+  interceptSegments?: SerializedSegmentData[];
+  interceptHandles?: string;
+}
+
+/** Serialized response bodies for the two endpoint variants of one render. */
+export interface DevPrerenderPayloadBodies {
+  /** `intercept != 1` response: the route's own segments + handles. */
+  main: string;
+  /**
+   * `intercept=1` response: main + intercept segments with the MERGED handle
+   * string. Falls back to `main` byte-for-byte when the route has no
+   * intercept segments — mirroring the endpoint's historical behavior.
+   */
+  intercept: string;
+}
+
+export interface DevPrerenderCache {
+  get(router: object, key: string): string | undefined;
+  set(router: object, key: string, body: string): void;
+}
+
+/**
+ * Derive both variant bodies from one matchForPrerender result, so a single
+ * render warms the main AND intercept cache keys (matchForPrerender computes
+ * intercept segments unconditionally either way — see prerender-match.ts
+ * step 14).
+ */
+export function payloadBodiesFromResult(
+  result: DevPrerenderMatchPayloadSource,
+): DevPrerenderPayloadBodies {
+  const main = JSON.stringify({
+    segments: result.segments,
+    handles: result.handles,
+  });
+  const intercept = result.interceptSegments?.length
+    ? JSON.stringify({
+        segments: [...result.segments, ...result.interceptSegments],
+        handles: result.interceptHandles ?? "",
+      })
+    : main;
+  return { main, intercept };
+}
+
+/**
+ * Cache key for one endpoint request shape. `pathname` and `routeName` come
+ * straight from the query; `passthrough` selects the getParams-checked match
+ * path; `intercept` selects which variant body is served. All four dimensions
+ * change the response, so all four are in the key.
+ */
+export function devPrerenderCacheKey(
+  pathname: string,
+  opts: { intercept: boolean; passthrough: boolean; routeName: string | null },
+): string {
+  return `${pathname}|i=${opts.intercept ? 1 : 0}|p=${opts.passthrough ? 1 : 0}|r=${opts.routeName ?? ""}`;
+}
+
+/**
+ * Per-router FIFO cap: a dev session that visits an unbounded set of
+ * prerendered pathnames (e.g. crawling param routes) must not grow one
+ * bucket without limit. 500 rendered payloads is far beyond any interactive
+ * session; eviction order does not matter for correctness (a miss just
+ * re-renders).
+ */
+const MAX_ENTRIES_PER_ROUTER = 500;
+
+export function createDevPrerenderCache(
+  maxEntriesPerRouter: number = MAX_ENTRIES_PER_ROUTER,
+): DevPrerenderCache {
+  const buckets = new WeakMap<object, Map<string, string>>();
+  return {
+    get(router: object, key: string): string | undefined {
+      return buckets.get(router)?.get(key);
+    },
+    set(router: object, key: string, body: string): void {
+      let bucket = buckets.get(router);
+      if (!bucket) {
+        bucket = new Map();
+        buckets.set(router, bucket);
+      }
+      if (!bucket.has(key) && bucket.size >= maxEntriesPerRouter) {
+        const oldest = bucket.keys().next().value;
+        if (oldest !== undefined) bucket.delete(oldest);
+      }
+      bucket.set(key, body);
+    },
+  };
+}