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

package/src/segment-system.tsx

@@ -17,6 +17,22 @@ import {
   getMemoizedLoaderPromise,
 } from "./segment-loader-promise.js";
 
+/**
+ * Client-only debug log for the segment tree build. Gated on the baked flag
+ * AND `typeof window` (renderSegments also runs during SSR/RSC, which must
+ * stay silent). Timestamped so tree-build steps line up with the
+ * `[Browser][boot]` sequence around hydrateRoot.
+ */
+function segDebugLog(msg: string, details?: Record<string, unknown>): void {
+  if (!(INTERNAL_RANGO_DEBUG && typeof window === "object")) return;
+  const prefix = `[Browser][segments] ${msg} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}
+
 // ViewTransition is only available in React experimental.
 // Access via namespace import to avoid compile-time errors on stable React.
 const ReactViewTransition: any =
@@ -212,6 +228,17 @@ export async function renderSegments(
     rootLayout: RootLayout,
   } = options || {};
 
+  const segDebug = INTERNAL_RANGO_DEBUG && typeof window === "object";
+  const segDebugStart = segDebug ? performance.now() : 0;
+  if (segDebug) {
+    segDebugLog("renderSegments start", {
+      segments: segments.map((s) => `${s.id}:${s.type}`),
+      isAction: !!isAction,
+      forceAwait: !!forceAwait,
+      intercepts: interceptSegments?.length ?? 0,
+    });
+  }
+
   const temporalLazyRefs: Promise<any>[] = [];
   const normalizedSegments = restoreParallelLoaderMarkers(segments);
   const normalizedInterceptSegments = interceptSegments
@@ -273,6 +300,15 @@ export async function renderSegments(
     );
     const { component, id, params, loading } = node.segment;
 
+    if (segDebug) {
+      segDebugLog(`segment ${id}`, {
+        type: node.segment.type,
+        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
+        hasLoading: loading !== undefined && loading !== null,
+        parallel: node.parallel.map((p) => p.id),
+      });
+    }
+
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
     // transition scope drops the param from its key, so navigating between two
@@ -403,10 +439,25 @@ export async function renderSegments(
 
     if (loading !== undefined && loading !== null) {
       const loaderDataPromise = getMemoizedLoaderPromise(loaderEntries);
+      let boundaryLoaderData: Promise<any[]> | any[] = loaderDataPromise;
+      if (forceAwait || isAction) {
+        const awaitStart = segDebug ? performance.now() : 0;
+        boundaryLoaderData = await loaderDataPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: loaders awaited (forceAwait/action)`, {
+            loaderIds,
+            ms: Math.round(performance.now() - awaitStart),
+          });
+        }
+      } else if (segDebug) {
+        segDebugLog(
+          `segment ${id}: streaming loaders via LoaderBoundary (suspense)`,
+          { loaderIds },
+        );
+      }
       content = createElement(LoaderBoundary, {
         key: `loader-boundary-${key}`,
-        loaderDataPromise:
-          forceAwait || isAction ? await loaderDataPromise : loaderDataPromise,
+        loaderDataPromise: boundaryLoaderData,
         loaderIds,
         fallback: loading,
         outletKey: key,
@@ -430,7 +481,17 @@ export async function renderSegments(
       );
 
       const layoutLoaderIds = layoutLoaders.map((l) => l.loaderId!);
+      // No loading() on this segment, so its loader data cannot stream behind
+      // a Suspense fallback — the tree build BLOCKS here until the data
+      // arrives. On the initial document this await runs before hydrateRoot.
+      const layoutAwaitStart = segDebug ? performance.now() : 0;
       const resolvedData = await buildLoaderPromise(layoutLoaders);
+      if (segDebug) {
+        segDebugLog(`segment ${id}: layout loaders awaited (blocking)`, {
+          loaderIds: layoutLoaderIds,
+          ms: Math.round(performance.now() - layoutAwaitStart),
+        });
+      }
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
@@ -463,10 +524,27 @@ export async function renderSegments(
 
           p.loaderIds = ownedLoaders.map((l) => l.loaderId!);
           const aggregated = getMemoizedLoaderPromise(ownedLoaders);
-          p.loaderDataPromise =
-            (forceAwait || isAction) && aggregated instanceof Promise
-              ? await aggregated
-              : aggregated;
+          if ((forceAwait || isAction) && aggregated instanceof Promise) {
+            const parallelAwaitStart = segDebug ? performance.now() : 0;
+            p.loaderDataPromise = await aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders awaited (forceAwait/action)`,
+                {
+                  loaderIds: p.loaderIds,
+                  ms: Math.round(performance.now() - parallelAwaitStart),
+                },
+              );
+            }
+          } else {
+            p.loaderDataPromise = aggregated;
+            if (segDebug) {
+              segDebugLog(
+                `segment ${id}: parallel ${p.id} loaders streaming (suspense)`,
+                { loaderIds: p.loaderIds },
+              );
+            }
+          }
         }
       }
 
@@ -524,6 +602,12 @@ export async function renderSegments(
     });
   }
 
+  if (segDebug) {
+    segDebugLog("renderSegments complete", {
+      ms: Math.round(performance.now() - segDebugStart),
+    });
+  }
+
   return result;
 }
 

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

@@ -1,5 +1,6 @@
 import React from "react";
 import { createSsrRootComponent } from "./ssr-root.js";
+import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import type { ErrorPhase } from "../types.js";
 
 /**
@@ -247,11 +248,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 +446,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();
+    }
   };
 }
 
@@ -556,7 +595,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
 export function createShellResumeHandler<TEnv = unknown>(
   deps: SSRDependencies<TEnv>,
 ) {
-  const { createFromReadableStream, injectRSCPayload, resume, onError } = deps;
+  const { createFromReadableStream, resume, onError } = deps;
 
   /**
    * @param rscStream - Fresh full Flight stream for this request.
@@ -571,11 +610,12 @@ export function createShellResumeHandler<TEnv = unknown>(
     try {
       if (postponed === null) {
         // DATA variant: the stored prelude is the complete shell. No fizz runs;
-        // feed injectRSCPayload a minimal HTML stream so its flush appends the
-        // fresh Flight payload scripts after the shell. The stream must emit at
-        // least one chunk — see createDataVariantHtmlStream.
+        // the eager injector pumps the fresh Flight payload scripts without
+        // needing an HTML chunk to trigger it (the stock injector deadlocked on
+        // a chunkless stream — see createDataVariantHtmlStream, kept for the
+        // batching invariant's sake).
         return createDataVariantHtmlStream().pipeThrough(
-          injectRSCPayload(rscStream, { nonce }),
+          injectRSCPayloadEager(rscStream, { nonce }),
         );
       }
 
@@ -602,7 +642,14 @@ export function createShellResumeHandler<TEnv = unknown>(
         nonce,
       });
 
-      return resumed.pipeThrough(injectRSCPayload(rscStream2, { nonce }));
+      // EAGER injection (resume-only): the stored prelude — a complete document
+      // through </body></html> — is already on the wire ahead of this stream,
+      // so a Flight <script> is valid as the first tail byte. The stock
+      // injector waits for the first fizz chunk, which only appears when the
+      // first hole's loaders resolve — parking the whole hydration payload
+      // (root row included) behind the slowest live loader. See
+      // inject-rsc-eager.ts for the measured failure mode.
+      return resumed.pipeThrough(injectRSCPayloadEager(rscStream2, { nonce }));
     } catch (error) {
       reportRenderError(onError, error);
       throw error;