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

package/src/rsc/shell-capture.ts

@@ -327,6 +327,39 @@ function warnCaptureRefusedOnce(key: string, reason: string): void {
   );
 }
 
+/** Keys already warned about untagged bake-lane data baked into the shell. */
+const warnedUntaggedShellBakes = new Set<string>();
+
+/**
+ * Warn once per shell key that a bake-lane loader baked material into the shell
+ * but the capture recorded ZERO tags (no render-collected _requestTags, no
+ * static ppr.tags). Such data is frozen in the shared shell until TTL and is
+ * un-evictable by tag: a server action refreshes the CLIENT only (rotates Rango
+ * state, busts the browser HTTP cache) and never touches the server shell store,
+ * and updateTag()/revalidateTag() cannot drop data that was baked WITHOUT a tag.
+ *
+ * Coarse per-shell-key signal, not per-loader attribution — the tag set is
+ * unioned globally at the write barrier, not tracked per loader, so we cannot
+ * name the offending loader without adding attribution plumbing (deliberately
+ * not done). Dev-only + once-per-key so it never spams production or fires on
+ * every capture.
+ */
+function warnUntaggedShellBakeOnce(key: string): void {
+  if (warnedUntaggedShellBakes.has(key)) return;
+  warnedUntaggedShellBakes.add(key);
+  console.warn(
+    `[rango] Shell capture for "${key}" baked bake-lane loader data into the ` +
+      "shell with NO cache tag. That data is frozen in the shared shell until " +
+      "TTL and cannot be tag-invalidated: a server action refresh touches the " +
+      "client only (not the server shell store), and updateTag() cannot evict " +
+      "data that was baked without a tag.\n" +
+      'Fix: tag the data (cacheTag() / "use cache" / cache({ tags })) so ' +
+      "updateTag() drops the shell, or move the volatile read under a loading() " +
+      "hole so it stays on the live lane and is never baked. See the /ppr skill " +
+      "(node_modules/@rangojs/router/skills/ppr/SKILL.md).",
+  );
+}
+
 export interface FlightCaptureGate {
   /** Identity passthrough of the source stream; feed this to captureShellHTML. */
   stream: ReadableStream<Uint8Array>;
@@ -487,9 +520,12 @@ export function gateFlightForCapture(
  * store, and passed to scheduleShellCapture directly — it is NOT threaded through
  * the request context. `tags` carries the route's OPERATIONAL `ppr.tags`; the
  * capture UNIONS them with the shell's own auto-collected (non-loader) request
- * tags from its derived render (the collected set stays authoritative). `store`
- * is the same store the serve path resolved for its getShell read
- * (requestCtx._cacheStore), so the capture writes where the serve reads.
+ * tags from its derived render (the collected set stays authoritative). That
+ * union happens at the putShell WRITE BARRIER in captureAndStoreShell — after the
+ * capture quiesces — not at stream construction, so a tag recorded after an await
+ * in async shell content is still collected (issue #676). `store` is the same
+ * store the serve path resolved for its getShell read (requestCtx._cacheStore),
+ * so the capture writes where the serve reads.
  */
 export interface ShellCaptureDescriptor {
   key: string;
@@ -715,6 +751,11 @@ 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
@@ -771,24 +812,18 @@ async function attemptCapture(
       },
     });
 
-    // Shell tags = the non-loader request tags the capture render recorded on its
-    // own fresh _requestTags (loaders are masked, so loader cache tags — which
-    // belong to the holes, not the shell — are correctly excluded), UNIONED with
-    // the middleware's operational `tags` option (descriptor.tags). The collected
-    // set is authoritative; the option only adds tags the render cannot know.
-    const collected = [...derivedCtx._requestTags];
-    const union = new Set<string>([...(descriptor.tags ?? []), ...collected]);
-    const tags = union.size > 0 ? [...union] : undefined;
-
+    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
+    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
+    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
+    // content (and tags propagated by async cache()/"use cache" reads) lands after
+    // this synchronous construction point, so snapshotting here dropped it — the
+    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
     return captureAndStoreShell(
       ssrModule,
       rscStream,
       freshHandleStore,
       derivedCtx,
-      {
-        ...descriptor,
-        tags,
-      },
+      descriptor,
     );
   });
 }
@@ -873,11 +908,25 @@ async function captureAndStoreShell(
   const refuseOnGuardTrip = (): "refused" | undefined => {
     const fnName = reqCtx._shellCaptureGuardTripped;
     if (!fnName) return undefined;
+    // Name the recorded source instead of hardcoding a lane. Under the
+    // consumption-lane rule, handler-INVOKED loader bodies are exempt from
+    // the guard (their value is a baked shared copy, mirroring cache()), so a
+    // trip can only come from a bake-lane SEGMENT loader or from non-loader
+    // handler/render code — the old blanket "bake-lane loader" attribution
+    // sent a live-lane debugging session down the wrong lane (issue #672).
+    const loaderId = reqCtx._shellCaptureGuardTrippedLoaderId;
+    const origin = loaderId
+      ? `segment loader "${loaderId}"`
+      : "handler/render code (no loader body was executing)";
     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.",
+      `${origin} called ${fnName}() during capture. Identity must not bake into a shared shell. ` +
+        "For a segment loader (bake lane, no loading()): give its entry a loading() boundary " +
+        "(the live lane, masked at capture) or move the identity-dependent part into a nested " +
+        "promise. For handler/render code: keep the value live by consuming a loader " +
+        'client-side (useLoader in a "use client" component). Note: `await ctx.use(loader)` ' +
+        "inside a HANDLER is exempt from this guard — its value bakes into the shared shell " +
+        "as a capture-time copy, mirroring cache() semantics (the consumption-lane rule).",
     );
     return "refused";
   };
@@ -976,6 +1025,10 @@ async function captureAndStoreShell(
     // 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;
+    // Set once a bake-lane loader settles with real (non-hole) material: its data
+    // is frozen into the shell prelude regardless of whether snapshot
+    // serialization succeeds. Drives the untagged-bake dev warning below.
+    let bakedLoaderMaterial = false;
     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
@@ -996,6 +1049,9 @@ async function captureAndStoreShell(
         // 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;
+        // Past the hole check: this container settled with real material that
+        // bakes into the shell prelude (independent of the snapshot pin below).
+        bakedLoaderMaterial = true;
         try {
           // serializeResult (not rscSerialize): null is a valid container and
           // must round-trip; serializeResult preserves it through Flight.
@@ -1016,6 +1072,28 @@ async function captureAndStoreShell(
       }
     }
 
+    // Shell tags snapshot at the WRITE BARRIER, not at stream construction: by
+    // here the capture has quiesced and the deferred cache writes were awaited, so
+    // tags recorded AFTER an await in async shell content (and by async
+    // cache()/"use cache" reads propagating through recordRequestTags) are
+    // included — issue #676. Loaders are masked, so loader cache tags — which
+    // belong to the holes, not the shell — never execute during capture and cannot
+    // contribute. Union with the route's static ppr.tags (capture.tags); the
+    // collected set is authoritative, the option only adds what the render cannot
+    // know.
+    const collected = [...reqCtx._requestTags];
+    const union = new Set<string>([...(capture.tags ?? []), ...collected]);
+    const shellTags = union.size > 0 ? [...union] : undefined;
+
+    // Untagged-bake diagnostic: a bake-lane loader froze mutable data into the
+    // shell but nothing tags the entry, so it is un-invalidatable except by TTL —
+    // a read-your-own-writes gap on the document channel (an action refresh skips
+    // the server shell; updateTag cannot drop untagged data). Coarse per-shell-key
+    // signal; dev-only and once-per-key so it never spams production.
+    if (isDevMode() && bakedLoaderMaterial && shellTags === undefined) {
+      warnUntaggedShellBakeOnce(capture.key);
+    }
+
     const store = capture.store ?? reqCtx._cacheStore;
     if (store?.putShell) {
       try {
@@ -1039,7 +1117,7 @@ async function captureAndStoreShell(
           entry,
           capture.ttl,
           capture.swr,
-          capture.tags,
+          shellTags,
         );
       } catch (error) {
         // Best-effort: a failed put must never throw out of the background task.

package/src/server/context.ts

@@ -770,14 +770,23 @@ const loaderScopeALS: AsyncLocalStorage<{ active: true }> = ((
 
 // Purity-only scope: marks that a loader FUNCTION BODY is executing, regardless
 // of how the loader was invoked (DSL via runInsideLoaderScope, or handler-
-// invoked via ctx.use). Consulted ONLY by isInsideCacheScope() to exempt
-// request-scoped reads. It deliberately does NOT affect isInsideLoaderScope(),
-// so rendered()/barrier/deadlock gating (which must distinguish DSL from
-// handler-invoked loaders) is unchanged.
+// invoked via ctx.use). Consulted by isInsideCacheScope() to exempt
+// request-scoped reads, by getCurrentLoaderBodyId() for guard-warning
+// attribution, and by isInsideHandlerInvokedLoaderBody() for the
+// consumption-lane rule (the shell-capture guard exemption). It deliberately
+// does NOT affect isInsideLoaderScope(), so rendered()/barrier/deadlock
+// gating (which must distinguish DSL from handler-invoked loaders) is
+// unchanged.
 const LOADER_BODY_SCOPE_KEY = Symbol.for("rangojs-router:loader-body-scope");
-const loaderBodyScopeALS: AsyncLocalStorage<{ active: true }> = ((
-  globalThis as any
-)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{ active: true }>());
+const loaderBodyScopeALS: AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}> = ((globalThis as any)[LOADER_BODY_SCOPE_KEY] ??= new AsyncLocalStorage<{
+  active: true;
+  loaderId?: string;
+  handlerInvoked?: boolean;
+}>());
 
 /**
  * Check if the current execution is inside a cache() DSL boundary.
@@ -822,8 +831,37 @@ export function runInsideLoaderScope<T>(fn: () => T): T {
  * and handler-invoked via ctx.use) so request-scoped reads inside a loader
  * never trip the cache-scope guards — loaders always run fresh.
  */
-export function runInsideLoaderBodyScope<T>(fn: () => T): T {
-  return loaderBodyScopeALS.run({ active: true }, fn);
+export function runInsideLoaderBodyScope<T>(
+  fn: () => T,
+  loaderId?: string,
+  handlerInvoked?: boolean,
+): T {
+  return loaderBodyScopeALS.run({ active: true, loaderId, handlerInvoked }, fn);
+}
+
+/**
+ * The $$id of the loader whose body is currently executing, or undefined
+ * outside any loader body. Used by the shell-capture identity guard
+ * (cookie-store.ts) so its refusal warning can name the loader that read
+ * cookies()/headers() instead of blaming a lane it cannot see — the old
+ * hardcoded "bake-lane loader" text misled a live-lane debugging session
+ * (issue #672, secondary).
+ */
+export function getCurrentLoaderBodyId(): string | undefined {
+  return loaderBodyScopeALS.getStore()?.loaderId;
+}
+
+/**
+ * True while a HANDLER-invoked loader body (`await ctx.use(Loader)` from a
+ * handler, not the DSL segment funnel) is executing. The consumption-lane
+ * rule keys off this: handler consumption yields a BAKED copy in every shared
+ * artifact — cache(), "use cache", and the PPR shell — so the shell-capture
+ * identity guard (cookie-store.ts) permits cookies()/headers() here, exactly
+ * like the cache-purity guards do. DSL segment loaders (live lane masked at
+ * capture, bake lane guarded) never set the flag.
+ */
+export function isInsideHandlerInvokedLoaderBody(): boolean {
+  return loaderBodyScopeALS.getStore()?.handlerInvoked === true;
 }
 
 // Scope for handle PUSH CALLBACKS (push(() => ...), including async ones).

package/src/server/cookie-store.ts

@@ -9,7 +9,11 @@
 
 import type { CookieOptions } from "../router/middleware-types.js";
 import { getRequestContext, _getRequestContext } from "./request-context.js";
-import { isInsideCacheScope } from "./context.js";
+import {
+  isInsideCacheScope,
+  getCurrentLoaderBodyId,
+  isInsideHandlerInvokedLoaderBody,
+} from "./context.js";
 import { INSIDE_CACHE_EXEC } from "../cache/taint.js";
 
 /**
@@ -139,9 +143,19 @@ function assertNotInsideCacheContext(ctx: unknown, fnName: string): void {
  * shell-capture.ts). The captured shell prelude is shared across every user
  * hitting the URL, so a request-scoped read here would bake one user's
  * cookies/headers into markup served to others — same hazard as the cache
- * scopes above, at the document tier. Loaders need no exemption: they are
- * masked (never executed) during capture and remain the per-request holes of
- * the shell.
+ * scopes above, at the document tier. DSL segment loaders need no exemption:
+ * the live lane is masked (never executed) during capture, and the bake lane
+ * is exactly what this guard exists for.
+ *
+ * HANDLER-INVOKED loader bodies (`await ctx.use(Loader)` from a handler) are
+ * EXEMPT — the consumption-lane rule: handler consumption yields a BAKED
+ * shared copy in every artifact tier, and the cache-purity guards above
+ * already permit identity reads there (cache()/"use cache" bake the same
+ * reads today). Guarding only the PPR tier made the same code legal under
+ * cache() but capture-refusing under ppr (issue #672 / #674). The trade is
+ * documented: an identity read in a handler-consumed loader bakes the CAPTURE
+ * request's value into the shared shell; client-side consumption (useLoader)
+ * is the live lane.
  *
  * Keys off `_shellCaptureRun`, NOT the `_shellCapture` descriptor: the descriptor
  * is also present during the FOREGROUND render (it means "a capture is wanted"),
@@ -164,12 +178,19 @@ function assertNotInsideShellCapture(ctx: unknown, fnName: string): void {
     typeof ctx === "object" &&
     (ctx as { _shellCaptureRun?: unknown })._shellCaptureRun === true
   ) {
+    if (isInsideHandlerInvokedLoaderBody()) return;
     // 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).
+    // the flag after the render and refuses (shell-capture.ts). Also record
+    // WHICH loader body (if any) made the read, so the refusal warning can
+    // name the real source instead of hardcoding a lane — the read may come
+    // from a bake-lane loader OR from handler/render code (issue #672).
     (ctx as { _shellCaptureGuardTripped?: string })._shellCaptureGuardTripped =
       fnName;
+    (
+      ctx as { _shellCaptureGuardTrippedLoaderId?: string }
+    )._shellCaptureGuardTrippedLoaderId = getCurrentLoaderBodyId();
     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

@@ -220,6 +220,16 @@ export interface RequestContext<
    */
   _shellCaptureGuardTripped?: string;
 
+  /**
+   * @internal The loader $$id whose BODY was executing when the capture guard
+   * tripped (read off the loader-body ALS scope at trip time), or undefined
+   * when the read came from handler/render code. Only used to make the
+   * once-per-key refusal warning name the real source — the old text
+   * hardcoded "a bake-lane loader", which misattributed handler-land reads
+   * and sent users debugging the wrong lane (issue #672, secondary).
+   */
+  _shellCaptureGuardTrippedLoaderId?: string;
+
   /**
    * @internal Handler-owned registry of explicit per-scope stores from
    * cache({ store }). Created once per createRSCHandler() and threaded into
@@ -468,6 +478,15 @@ export interface RequestContext<
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
 
+  /**
+   * @internal True request entry timestamp (performance.now() at handler entry).
+   * Set once at request-context creation (rsc/handler.ts) so a metrics store
+   * created MID-request — ctx.debugPerformance() or the getMetricsStore wrapper —
+   * anchors its timeline to the real request start instead of the opt-in moment,
+   * keeping phases that began before the opt-in at their true (non-negative) offset.
+   */
+  _handlerStart?: number;
+
   /** @internal Resolved platform phase-span tracing for this request (Cloudflare or OTel) */
   _tracing?: ResolvedTracing;
 
@@ -509,6 +528,7 @@ export type PublicRequestContext<
   | "_transitionWhen"
   | "_cacheStore"
   | "_shellCaptureRun"
+  | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
   | "_cacheProfiles"
@@ -536,6 +556,7 @@ export type PublicRequestContext<
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
+  | "_handlerStart"
   | "_basename"
   | "_setStatus"
   | "_rotateStateCookie"
@@ -1028,6 +1049,7 @@ export function createRequestContext<TEnv>(
 
     _reportedErrors: new WeakSet<object>(),
     _metricsStore: undefined,
+    _handlerStart: undefined,
 
     _renderBarrier: null as any,
     _resolveRenderBarrier: null as any,

package/src/ssr/index.tsx

@@ -247,11 +247,22 @@ async function readStreamToUint8Array(
   const reader = stream.getReader();
   const chunks: Uint8Array[] = [];
   let total = 0;
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    chunks.push(value);
-    total += value.length;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      total += value.length;
+    }
+  } catch (error) {
+    // Mid-read abort path (documented): the prelude stream errors with our
+    // abort reason while we are still reading it. Cancel the source before
+    // rethrowing so it is not left uncancelled; releaseLock always runs in
+    // finally. Mirrors src/rsc/rsc-rendering.ts's serve-side reader cleanup.
+    reader.cancel(error).catch(() => {});
+    throw error;
+  } finally {
+    reader.releaseLock();
   }
   const out = new Uint8Array(total);
   let offset = 0;
@@ -434,113 +445,140 @@ export function createShellCaptureHandler<TEnv = unknown>(
   ): Promise<ShellCaptureResult | null> {
     const maxWaitMs = opts.maxWaitMs ?? DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS;
 
-    // No nonce (nonce'd requests never reach capture); no formState.
-    const SsrRoot = createSsrRootComponent({
-      createFromReadableStream,
-      rscStream,
-    });
-
-    const bootstrapScriptContent = await loadBootstrapScriptContent();
-
-    // Start prerender first, then run the abort schedule concurrently. When
-    // holes are pending, prerender's promise settles only after abort(); when
-    // the shell completes with no holes it settles on its own and the later
-    // abort() is a harmless no-op (the DATA variant).
-    const controller = new AbortController();
-    const prerenderPromise = prerender(<SsrRoot />, {
-      signal: controller.signal,
-      bootstrapScriptContent,
-      // Abort is how capture WORKS: once the shell is quiet we abort() to freeze
-      // the prelude and let the still-pending holes postpone. React reports the
-      // abort reason for each pending boundary through onError. Without an onError
-      // here React falls back to console.error, so every capture that still has a
-      // live hole at abort time (the normal case, and every cold-module capture
-      // where the shell is not yet done) dumps a DOMException [AbortError] stack —
-      // once per pending boundary. That is EXPECTED degradation, not a failure, so
-      // swallow the abort here. Genuine shell render errors (a component throwing)
-      // are NOT the abort and still surface through the deps.onError channel, the
-      // same one renderHTML uses. See docs/design/ppr-shell-resume.md.
-      onError: (error: unknown) => {
-        if (
-          controller.signal.aborted &&
-          (error as { name?: string } | null)?.name === "AbortError"
-        ) {
-          return;
-        }
-        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
-    // gateFlightForCapture), so there is no wall-clock debounce here — maxWaitMs
-    // is only the pathological guard for a shell that never goes quiet (a root
-    // postpone / hung handle), and should never fire in tests.
-    const timer = createCancelableTimeout(maxWaitMs);
-    try {
-      await Promise.race([opts.quiesce, timer.promise]);
-    } finally {
-      timer.cancel();
-    }
-    // Fixed task hops before the abort: give React's fizz worker turns to flush
-    // the now-complete shell and mark the still-pending boundaries as POSTPONED
-    // rather than errored. Deterministic (the byte set is already frozen), so a
-    // fixed count of turns suffices — no wall-clock.
-    for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) {
-      await macrotask();
-    }
-    controller.abort();
-
-    // A hard prerender rejection (fatal shell error) propagates. Expected
-    // degradation surfaces three ways and all return null: a trivial prelude
-    // (sanity gate below), the prerender REJECTING with an AbortError, or the
-    // prelude STREAM erroring with the abort reason mid-read — both abort
-    // shapes happen when our own abort lands before the shell completed (seen
-    // on dev cold paths, where module transform / first-render latency
-    // outlasts flight quiesce; a later request re-captures against warm
-    // modules and succeeds).
-    let prelude: Uint8Array;
-    let postponed: unknown;
+    // Arm the maxWaitMs deadline BEFORE the first await so it bounds the ENTIRE
+    // capture, the bootstrap-script load included. loadBootstrapScriptContent()
+    // used to run before the timer, so a hung/slow bootstrap load hung
+    // captureShellHTML with no upper bound and held the background capture task
+    // open. One deadline, shared by the bootstrap race below and the quiesce
+    // race, keeps the whole path "bounded by maxWaitMs like every quiesce input".
+    const deadline = createCancelableTimeout(maxWaitMs);
     try {
-      const result = await prerenderPromise;
-      prelude = await readStreamToUint8Array(result.prelude);
-      postponed = result.postponed;
-    } catch (error) {
-      // Name-based match: the rejection is a DOMException on workerd/Node,
-      // which is not an Error subclass there, so instanceof Error would let
-      // the abort escape as a spurious reported error.
-      if (
-        controller.signal.aborted &&
-        (error as { name?: string } | null)?.name === "AbortError"
-      ) {
+      // No nonce (nonce'd requests never reach capture); no formState.
+      const SsrRoot = createSsrRootComponent({
+        createFromReadableStream,
+        rscStream,
+      });
+
+      // Bootstrap load raced against the deadline. A load that never resolves
+      // within maxWaitMs is the same bounded no-shell degrade as a shell that
+      // never goes quiet: return null, do not hang. A load that REJECTS is a
+      // genuine error and still propagates (it is not the deadline). `null` is
+      // the deadline sentinel — disjoint from the load's `Promise<string>`, so
+      // the race narrows to `string | null` with no wrapper. The no-op catch
+      // keeps a late rejection off the unhandledRejection path when the deadline
+      // already won; a rejection that lands first still propagates out.
+      const load = loadBootstrapScriptContent();
+      load.catch(() => {});
+      const bootstrapScriptContent = await Promise.race([
+        load,
+        deadline.promise.then(() => null),
+      ]);
+      if (bootstrapScriptContent === null) {
         return null;
       }
-      throw error;
-    }
 
-    // Sanity gate: a prelude with no `<body` is the no-shell failure mode.
-    // Return null and store nothing; the request falls back to axis 1 and a
-    // later request re-captures. The dominant real-world cause is a loader
-    // route WITHOUT a route-level loading() boundary: renderSegments' loading-
-    // less branch awaits loader data at TREE-BUILD, so the masked loader pins
-    // the whole tree above <body> (root postpone). Root-postponing layouts and
-    // hung handles degrade the same way. shell-capture.ts logs a once-per-key
-    // warning so the eternal-MISS shape is diagnosable.
-    if (!new TextDecoder().decode(prelude).includes("<body")) {
-      return null;
-    }
+      // Start prerender first, then run the abort schedule concurrently. When
+      // holes are pending, prerender's promise settles only after abort(); when
+      // the shell completes with no holes it settles on its own and the later
+      // abort() is a harmless no-op (the DATA variant).
+      const controller = new AbortController();
+      // Private reason object: the deliberate abort is identified by object
+      // IDENTITY in both the onError below and the post-await catch. React
+      // propagates this EXACT object to onError for every still-pending boundary
+      // (verified identity-preserving), and rejects/errors the prelude with it.
+      const abortReason = { rangoShellCaptureAbort: true };
+      const prerenderPromise = prerender(<SsrRoot />, {
+        signal: controller.signal,
+        bootstrapScriptContent,
+        // Abort is how capture WORKS: once the shell is quiet we abort() to
+        // freeze the prelude and let the still-pending holes postpone. React
+        // reports the abort reason for each pending boundary through onError.
+        // Without an onError here React falls back to console.error, so every
+        // capture that still has a live hole at abort time (the normal case)
+        // dumps a stack once per pending boundary. That is EXPECTED degradation,
+        // so swallow OUR abort — matched by IDENTITY (error === abortReason).
+        // Discriminate by identity, NOT error.name: capture aborts before
+        // awaiting, so signal.aborted is unconditionally true and a name check
+        // swallowed genuine AbortError-named throws (a component's own
+        // fetch/AbortController cancellation) as if they were our abort. Genuine
+        // render errors are NOT our sentinel and still surface through
+        // deps.onError, the same channel renderHTML uses. See
+        // docs/design/ppr-shell-resume.md.
+        onError: (error: unknown) => {
+          if (error === abortReason) {
+            return;
+          }
+          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, bounded by the SAME deadline. By
+      // the time it resolves the Flight input is byte-quiet and FROZEN by the
+      // capture gate (shell-capture.ts gateFlightForCapture), so there is no
+      // wall-clock debounce here — maxWaitMs is only the pathological guard for a
+      // shell that never goes quiet (a root postpone / hung handle).
+      await Promise.race([opts.quiesce, deadline.promise]);
+      // Fixed task hops before the abort: give React's fizz worker turns to flush
+      // the now-complete shell and mark the still-pending boundaries as POSTPONED
+      // rather than errored. Deterministic (the byte set is already frozen), so a
+      // fixed count of turns suffices — no wall-clock.
+      for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) {
+        await macrotask();
+      }
+      controller.abort(abortReason);
+
+      // A hard prerender rejection (fatal shell error) propagates. Expected
+      // degradation surfaces three ways and all return null: a trivial prelude
+      // (sanity gate below), the prerender REJECTING with our abort reason, or
+      // the prelude STREAM erroring with our abort reason mid-read — both abort
+      // shapes happen when our own abort lands before the shell completed (seen
+      // on dev cold paths, where module transform / first-render latency
+      // outlasts flight quiesce; a later request re-captures against warm
+      // modules and succeeds).
+      let prelude: Uint8Array;
+      let postponed: unknown;
+      try {
+        const result = await prerenderPromise;
+        prelude = await readStreamToUint8Array(result.prelude);
+        postponed = result.postponed;
+      } catch (error) {
+        // Identity match: swallow ONLY our own deliberate abort
+        // (error === abortReason). Not error.name — capture aborts before this
+        // await, so signal.aborted is always true, and a name check let a
+        // genuine AbortError-named throw masquerade as our abort and degrade
+        // into a retryable no-shell, hiding real failures from reportCacheError.
+        if (error === abortReason) {
+          return null;
+        }
+        throw error;
+      }
+
+      // Sanity gate: a prelude with no `<body` is the no-shell failure mode.
+      // Return null and store nothing; the request falls back to axis 1 and a
+      // later request re-captures. The dominant real-world cause is a loader
+      // route WITHOUT a route-level loading() boundary: renderSegments' loading-
+      // less branch awaits loader data at TREE-BUILD, so the masked loader pins
+      // the whole tree above <body> (root postpone). Root-postponing layouts and
+      // hung handles degrade the same way. shell-capture.ts logs a once-per-key
+      // warning so the eternal-MISS shape is diagnosable.
+      if (!new TextDecoder().decode(prelude).includes("<body")) {
+        return null;
+      }
 
-    return {
-      prelude,
-      postponed: postponed == null ? null : JSON.stringify(postponed),
-    };
+      return {
+        prelude,
+        postponed: postponed == null ? null : JSON.stringify(postponed),
+      };
+    } finally {
+      deadline.cancel();
+    }
   };
 }