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

package/src/router/telemetry-otel.ts

@@ -41,7 +41,7 @@ import { runThenSettle } from "./tracing.js";
 import type {
   RouterTracingConfig,
   SpanRunner,
-  TracePhaseToggles,
+  TracingToggleOptions,
 } from "./tracing.js";
 
 // ---------------------------------------------------------------------------
@@ -92,13 +92,11 @@ const STATUS_ERROR = 2;
 // Tracing adapter: phase spans via startActiveSpan (the `tracing` slot)
 // ---------------------------------------------------------------------------
 
-/** Options for createOTelTracing. */
-export interface OTelTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
-}
+/**
+ * Options for createOTelTracing. Alias of the shared {@link TracingToggleOptions}
+ * (`enabled` master switch + per-phase `spans` toggles); the name is public API.
+ */
+export type OTelTracingOptions = TracingToggleOptions;
 
 /**
  * Create the tracing config that maps the router's phases onto OTel spans via

package/src/router/tracing.ts

@@ -81,17 +81,26 @@ export interface TracePhaseToggles {
   ssr?: boolean;
 }
 
+/**
+ * The option pair shared by every tracing factory (enabled master switch +
+ * per-phase span toggles). Extended by OTelTracingOptions,
+ * CloudflareTracingOptions, VercelTracingOptions, and RouterTracingConfig so
+ * a phase added to TracePhaseToggles propagates everywhere from one place.
+ */
+export interface TracingToggleOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+}
+
 /**
  * Value passed to `createRouter({ tracing })`. Produced by a platform factory
  * such as `createCloudflareTracing()`.
  */
-export interface RouterTracingConfig {
+export interface RouterTracingConfig extends TracingToggleOptions {
   /** Platform span runner. */
   runner: SpanRunner;
-  /** Master switch. Defaults to true when a config object is provided. */
-  enabled?: boolean;
-  /** Per-phase span toggles. */
-  spans?: TracePhaseToggles;
 }
 
 /**

package/src/router.ts

@@ -420,13 +420,13 @@ export function createRouter<TEnv = any>(
 
   // Wrapper to pass debugPerformance to external createMetricsStore.
   // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  // With no active request context there is nowhere to hang the store, so return
+  // undefined: an orphan store would collect metrics no reader can reach (nothing
+  // holds it, and appendMetric(undefined, ...) is already a no-op).
   const getMetricsStore = () => {
     const reqCtx = _getRequestContext();
     const enabled = debugPerformance || !!reqCtx?._debugPerformance;
-    if (!enabled) return undefined;
-    if (!reqCtx) {
-      return createMetricsStore(true);
-    }
+    if (!enabled || !reqCtx) return undefined;
     reqCtx._metricsStore ??= createMetricsStore(true);
     return reqCtx._metricsStore;
   };
@@ -501,8 +501,12 @@ export function createRouter<TEnv = any>(
         ? getRequestId(errorContext.request)
         : undefined
       : undefined;
+    // Derived once here for both the loader.start and loader.end emits (the
+    // loader.error emit uses ctx.loaderName from wrapLoaderWithErrorHandling).
+    const loaderName = telemetrySink
+      ? segmentId.split(".").pop() || "unknown"
+      : "";
     if (telemetrySink) {
-      const loaderName = segmentId.split(".").pop() || "unknown";
       safeEmit(telemetry, {
         type: "loader.start",
         timestamp: loaderStart,
@@ -556,7 +560,6 @@ export function createRouter<TEnv = any>(
 
     // Emit loader.end after the promise settles (fire-and-forget)
     if (telemetrySink) {
-      const loaderName = segmentId.split(".").pop() || "unknown";
       result.then((r) => {
         safeEmit(telemetry, {
           type: "loader.end",
@@ -1008,6 +1011,12 @@ export function createRouter<TEnv = any>(
     // Expose resolved span tracing for the handler (Cloudflare custom spans)
     tracing: resolvedTracing,
 
+    // Expose the raw telemetry sink so handler-level emitters (timeout, origin
+    // rejection, late-handle handler.error) can emit outside the match ALS.
+    // Raw (not the resolveSink no-op wrapper) so router.telemetry stays
+    // undefined when unconfigured and call sites gate on truthiness.
+    telemetry: telemetrySink,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 

package/src/rsc/handler.ts

@@ -85,7 +85,8 @@ import {
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
-import { observePhase, observeEvent, PHASES } from "../router/instrument.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import { safeEmit, resolveSink, getRequestId } from "../router/telemetry.js";
 import {
   startSSRSetup,
   getSSRSetup,
@@ -246,16 +247,19 @@ export function createRSCHandler<
       metadata: { timeout: true, phase, durationMs },
     });
 
-    observeEvent({
-      type: "request.timeout",
-      timestamp: performance.now(),
-      phase,
-      pathname: url.pathname,
-      routeKey,
-      actionId,
-      durationMs,
-      customHandler: !!router.onTimeout,
-    });
+    if (router.telemetry) {
+      safeEmit(resolveSink(router.telemetry), {
+        type: "request.timeout",
+        timestamp: performance.now(),
+        requestId: getRequestId(request),
+        phase,
+        pathname: url.pathname,
+        routeKey,
+        actionId,
+        durationMs,
+        customHandler: !!router.onTimeout,
+      });
+    }
 
     if (router.onTimeout) {
       try {
@@ -590,7 +594,13 @@ export function createRSCHandler<
 
         const fullTiming = timingParts.join(", ");
         if (fullTiming && !isWebSocketUpgradeResponse(response)) {
-          response.headers.set("Server-Timing", fullTiming);
+          try {
+            response.headers.set("Server-Timing", fullTiming);
+          } catch {
+            // Immutable headers (e.g. a passed-through platform Response) — drop
+            // the timing header, never the response. Instrumentation must not
+            // 500 a request.
+          }
         }
 
         // Single open-redirect chokepoint: every response (PE, full-page,
@@ -737,15 +747,18 @@ export function createRSCHandler<
           },
         });
 
-        observeEvent({
-          type: "request.origin-rejected",
-          timestamp: performance.now(),
-          method: request.method,
-          pathname: url.pathname,
-          phase: originPhase,
-          origin: request.headers.get("origin"),
-          host: request.headers.get("host"),
-        });
+        if (router.telemetry) {
+          safeEmit(resolveSink(router.telemetry), {
+            type: "request.origin-rejected",
+            timestamp: performance.now(),
+            requestId: getRequestId(request),
+            method: request.method,
+            pathname: url.pathname,
+            phase: originPhase,
+            origin: request.headers.get("origin"),
+            host: request.headers.get("host"),
+          });
+        }
 
         return originResult;
       }
@@ -787,15 +800,18 @@ export function createRSCHandler<
         params: reqCtx.params as Record<string, string>,
         handledByBoundary: true,
       });
-      observeEvent({
-        type: "handler.error",
-        timestamp: performance.now(),
-        error,
-        handledByBoundary: true,
-        pathname: url.pathname,
-        routeKey: reqCtx._routeName,
-        params: reqCtx.params as Record<string, string>,
-      });
+      if (router.telemetry) {
+        safeEmit(resolveSink(router.telemetry), {
+          type: "handler.error",
+          timestamp: performance.now(),
+          requestId: getRequestId(request),
+          error,
+          handledByBoundary: true,
+          pathname: url.pathname,
+          routeKey: reqCtx._routeName,
+          params: reqCtx.params as Record<string, string>,
+        });
+      }
     };
 
     // Set route params early so all execution paths can access ctx.params.

package/src/rsc/nonce.ts

@@ -8,11 +8,20 @@ import { createVar } from "../context-var.js";
 /**
  * Typed ContextVar token for CSP nonce.
  *
- * Use this to access the nonce in middleware or handlers:
+ * Use this to READ the nonce in middleware or handlers:
  * ```ts
  * import { nonce } from "@rangojs/router";
  * const value = ctx.get(nonce); // string | undefined
  * ```
+ *
+ * Supply the nonce via the `createRouter({ nonce })` provider, not by writing
+ * this token yourself. The provider value is threaded into the router's SSR
+ * machinery (NonceContext/useNonce, Scripts/MetaTags attributes, the inlined
+ * Flight payload scripts) AND sets this token. A direct `ctx.set(nonce, value)`
+ * in middleware runs AFTER the SSR nonce is resolved: the value is readable via
+ * `ctx.get(nonce)` and gates PPR shell capture (a per-request nonce must never
+ * bake into a shared shell), but the router will not apply it to its own
+ * scripts — useNonce() stays undefined for that request.
  */
 export const nonce: ContextVar<string> = createVar<string>();
 

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,16 @@ async function attemptCapture(
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
   derivedCtx._metricsStore = undefined;
+  // Spans, like perf metrics above, are a FOREGROUND surface: the capture
+  // re-render must not emit a second rango.render/loader/ssr set after the
+  // foreground rango.request span ended (orphan spans in the trace).
+  // _tracing is otherwise inherited through Object.create(reqCtx).
+  derivedCtx._tracing = 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 +849,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 +898,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 +920,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 +973,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 +1069,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,
+};