@rangojs/router 0.17.0 → 0.18.0

package/src/server/request-context.ts

@@ -17,6 +17,7 @@ import type { CookieOptions } from "../router/middleware.js";
 import {
   KEEP_CACHE_HEADER,
   getRawCookieValue,
+  freshReadsCookieName,
   mintStateValue,
   serializeStateCookie,
 } from "../browser/cookie-name.js";
@@ -64,6 +65,7 @@ import {
   assertNonCacheableReadAllowed,
   clearPprHeaderScope,
 } from "./context.js";
+import { assertThemeReadAllowed } from "./cookie-store.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -165,6 +167,40 @@ export interface RequestContext<
   _rotateStateCookie(): void;
   /** @internal Set the keepClientCache() directive header on the response. */
   _setKeepCacheDirective(): void;
+  /**
+   * @internal This request carries the fresh-reads cookie: it follows an
+   * updateTag()/revalidateTag() by the same user, so the stores read tag
+   * markers and shells from the store, not from an isolate memo.
+   */
+  _freshReads?: boolean;
+  /**
+   * @internal Set the fresh-reads cookie on this response for `maxAgeMs`
+   * (rounded up to whole seconds; the longest stays). Called by
+   * updateTag()/revalidateTag().
+   */
+  _setFreshReadsCookie(maxAgeMs: number): void;
+  /**
+   * @internal The context createRequestContext() returned. A context derived
+   * from it with Object.create (a PPR HIT tail, a shell capture, a background
+   * revalidation render) inherits it, so per-request invalidation state
+   * (tag-invalidation.ts, the stores' masks) is keyed by the request, not by
+   * whichever derived object called or read (#973).
+   */
+  _requestRoot?: RequestContext<any, any>;
+  /**
+   * @internal The tags this request invalidated with
+   * updateTag()/revalidateTag(), each with its position in the invalidation
+   * order (tag-invalidation.ts currentCacheSeq). Kept on _requestRoot. A
+   * "use cache" execution that started before one of its own tags was
+   * invalidated is neither joined nor written (cache-runtime.ts, #973).
+   */
+  _tagInvalidations?: Map<string, number>;
+  /**
+   * @internal The handler has handed the response to the host (rsc/handler.ts
+   * `rango.response`): header and cookie writes after this are lost, as from
+   * a streaming loader or render.
+   */
+  _responseSent?: boolean;
 
   /**
    * Access loader data or push handle data.
@@ -264,6 +300,49 @@ export interface RequestContext<
    */
   _shellCaptureLoaderRecords?: Map<string, Promise<unknown>>;
 
+  /**
+   * @internal Set on a capture's derived context when a loader pushed a
+   * value the record cannot keep (a deferred push, masked nested promises,
+   * or a push outside a loader body): the loader records then carry
+   * `runs: 1`, so a HIT still runs their bodies for those pushes.
+   */
+  _shellCaptureUnrecordedLoaderPush?: true;
+
+  /**
+   * @internal Record keys resolved for this request (CacheScope
+   * resolveKeyFrom): by the scope's `key()` (one result) or its store's
+   * keyGenerator (one per default key). A shell capture's derived context
+   * reads it through the prototype chain, so the capture reuses the
+   * partition its request resolved instead of running `key()` again.
+   */
+  _resolvedCacheKeys?: Map<unknown, Map<string, Promise<string>>>;
+
+  /**
+   * @internal The shell store key the PPR serve path resolved for this
+   * document request (rsc-rendering.ts shellServePlan), request partition
+   * included. Read by the testing helper serveShellRequest.
+   */
+  _shellKey?: string;
+
+  /**
+   * @internal The request carried the forced-MISS reload marker
+   * (shell-serve.ts SHELL_MISS_PARAM). The handler strips the marker from the
+   * request on entry and sets this; the shell gate renders the request like a
+   * cache miss.
+   */
+  _shellForcedMiss?: true;
+
+  /**
+   * @internal The freshness window of the route cache() records this
+   * request read or wrote (cache-scope.ts noteRouteRecordWindow), as ms
+   * timestamps: `freshUntil` is the record's `expiresAt`, `staleUntil` adds
+   * its scope's swr. The narrowest record wins. A shell capture caps its
+   * entry's ttl and ttl+swr to it (shell-capture.ts capShellWindow), so a
+   * shell is never fresher, or served longer, than the route cache() entry
+   * it replayed or wrote.
+   */
+  _routeRecordWindow?: RouteRecordWindow;
+
   /**
    * @internal Loader-family snapshot seed for a shell HIT's tail render:
    * segment-key -> the capture's elided container (already Flight-deserialized
@@ -271,8 +350,10 @@ export interface RequestContext<
    * overlays it onto the fresh run's container (recorded paths pinned,
    * hole-marker paths keep the fresh nested promises) so the payload's baked
    * bytes match the frozen prelude; a hole-free entry resolves pin-first
-   * without gating on the fresh run. Own property of the HIT tail's derived
-   * context only.
+   * and does not run the loader. Two owners: serveShellHit sets it on the
+   * HIT tail's derived context, and matchPartialWithPprReplay sets it on the
+   * request context of a PPR partial replay once its doc record hits, and
+   * restores the previous value after the match.
    */
   _shellLoaderSeed?: Map<
     string,
@@ -280,16 +361,17 @@ export interface RequestContext<
   >;
 
   /**
-   * @internal Shell fast-path marker: makes the next eligible match treat the
-   * whole matched route as an implicit doc-level cache() boundary (see
+   * @internal The doc record marker: makes the next match treat the whole
+   * matched route as an implicit doc-level cache() boundary (see
    * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
    * (a) the capture's derived context — with a record-only store so the
    * capture's cacheRoute write lands in the snapshot, never the real store —
-   * (b) a HIT tail's seeded context, and (c) an eligible normal-route partial
-   * replay, where `store` is a request-local segment overlay. Handler-live holes
-   * and conditional transitions decline replay.
-   * Routes with their own cache() config are never overridden — their scope's
-   * store/key/ttl/swr/condition semantics stay authoritative. On the
+   * (b) a document HIT tail's seeded context (`docTail`), and (c) an eligible
+   * normal-route partial replay, where `store` is a request-local segment
+   * overlay.
+   * A document HIT tail replays the record even for a route with its own
+   * cache() config (the gate before the commit already evaluated that
+   * scope's opt-outs). Elsewhere the route's scope stays authoritative. On the
    * navigation-replay serve path (`onExplicitHit` set) the marker COMPOSES with
    * such a scope instead of being ignored: the seeded doc record supplies the match
    * only when the explicit tier misses (withCacheLookup). cache(false) and a
@@ -306,12 +388,17 @@ export interface RequestContext<
      * segment record even when the triggering request is partial.
      */
     keyPrefix?: "doc";
-    /** @internal Called only after the implicit cache hit decodes successfully. */
-    onHit?: () => void;
+    /**
+     * @internal Called only after the implicit cache hit decodes
+     * successfully; the lookup awaits it before returning the hit, so work
+     * it starts lands before the route's loaders resolve.
+     */
+    onHit?: () => void | Promise<void>;
     /**
      * @internal Called when the seeded document record fails server-side
      * deserialization. Partial replay uses it to replace the enclosing shell
-     * snapshot after serving the fresh fallback.
+     * snapshot after serving the fresh fallback. A document HIT tail does not
+     * set it: withCacheLookup throws ShellRecordUnavailableError instead.
      */
     onCorrupt?: () => void;
     /**
@@ -322,6 +409,21 @@ export interface RequestContext<
      * require the exact consumable record instead of "any segment record".
      */
     docKey?: string;
+    /**
+     * @internal Set on a document HIT tail (serveShellHit). The implicit doc
+     * scope replaces any route-derived cache() scope for the tail's match
+     * (resolveShellImplicitCacheScope), and a lookup that does not hit throws
+     * ShellRecordUnavailableError instead of resolving segments
+     * (withCacheLookup): a HIT never runs a handler.
+     */
+    docTail?: true;
+    /**
+     * @internal The key a document HIT tail looks the doc record up by: the
+     * entry's own `docKey`. Recomputing it could name another key (a store
+     * keyGenerator folding request data, a build-time capture's synthetic
+     * host) and miss the record.
+     */
+    fixedDocKey?: string;
     /**
      * @internal Set ONLY by matchPartialWithPprReplay on the navigation-replay
      * serve path. Its presence arms the explicit-scope composition in
@@ -365,31 +467,16 @@ export interface RequestContext<
   _shellFragmentPayload?: boolean;
 
   /**
-   * @internal Handler-layer liveness observed DURING a shell capture, from
-   * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
-   * when a push made OUTSIDE a DSL loader scope carries a nested thenable
-   * (masked to a never-filling hole); (b) still-pending top-level handler
-   * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
-   * executing during the capture (loader-resolution.ts — its consumption-lane
-   * value would freeze on a handler-free HIT). captureAndStoreShell folds it
-   * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
-   * property of the capture's derived context only.
-   */
-  _shellCaptureHandleLiveness?: {
-    holes: boolean;
-    pendingPushes: number;
-    handlerInvokedLoader: boolean;
-  };
-
-  /**
-   * @internal Set (to the offending fn name) by the cookies()/headers()
-   * capture guard when it throws DURING a capture render. Load-bearing for the
+   * @internal Set by the capture guard (server/context.ts
+   * tripShellCaptureGuard) when it throws DURING a capture render: the read
+   * ("cookies()", "headers()", "ctx.get()", "ctx.theme") and the fix the
+   * refusal warning gives for it. Load-bearing for the
    * bake lane: a guard throw inside an executing loader is swallowed by
    * wrapLoaderPromise into per-loader error UI, which would otherwise bake
    * silently into the shared shell — the capture checks this flag after the
    * render and refuses instead. Deterministic, so the capture does not retry.
    */
-  _shellCaptureGuardTripped?: string;
+  _shellCaptureGuardTripped?: { surface: string; fix: string };
 
   /**
    * @internal The loader $$id whose BODY was executing when the capture guard
@@ -420,6 +507,23 @@ export interface RequestContext<
    */
   _requestTags: Set<string>;
 
+  /**
+   * @internal This request can write a route cache() record: its match
+   * resolved a cache scope (match-api.ts). Arms the record tag owners
+   * (cache-tag.ts armRecordTagOwners); off, the segment scopes, loader links
+   * and owned tag sets are skipped entirely. A capture's or background
+   * re-render's derived context (Object.create) inherits it.
+   */
+  _recordTagOwners?: true;
+
+  /**
+   * @internal This request resolves a loader bound with its own cache()
+   * (match-api.ts, or the binding's funnel). Arms the per-execution loader
+   * tag sets (cache-tag.ts armLoaderTagSets); off, a loader execution
+   * allocates no set and a read links nothing. Derived contexts inherit it.
+   */
+  _recordLoaderTags?: true;
+
   /** @internal Cache profiles for "use cache" profile resolution (per-router) */
   _cacheProfiles?: Record<
     string,
@@ -467,6 +571,11 @@ export interface RequestContext<
    * Returns the theme value from the cookie, or the default theme if not set.
    * This is the user's preference ("light", "dark", or "system"), not the resolved value.
    *
+   * The visitor's cookie, so it is guarded like `cookies()`: reading it
+   * refuses a ppr shell capture and throws inside a `cache()` boundary or a
+   * `"use cache"` function (#971). A non-enumerable getter: a spread or
+   * `Object.assign` copy of the context does not carry it.
+   *
    * @example
    * ```typescript
    * route("settings", (ctx) => {
@@ -475,7 +584,7 @@ export interface RequestContext<
    * });
    * ```
    */
-  theme?: Theme;
+  readonly theme?: Theme;
 
   /**
    * Set the theme (only available when theme is enabled in router config)
@@ -499,6 +608,15 @@ export interface RequestContext<
   /** @internal Theme configuration (null if theme not enabled) */
   _themeConfig?: ResolvedThemeConfig | null;
 
+  /**
+   * @internal The theme cookie (or the default) read with no identity guard.
+   * The guarded reads (`theme` here, the handler and middleware `ctx.theme`)
+   * call it after assertThemeReadAllowed; the router's own payload read goes
+   * through payloadInitialTheme (rsc/full-payload.ts). Undefined without
+   * theme config.
+   */
+  _readTheme(): Theme | undefined;
+
   /**
    * Attach location state entries to the current response.
    *
@@ -726,6 +844,21 @@ export interface RequestContext<
   _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
+/**
+ * @internal The freshness window of a route cache() record, as ms
+ * timestamps: fresh until `freshUntil` (its `expiresAt`), stale until
+ * `staleUntil` (plus its scope's swr). `ttl`, `swr` and `written` describe
+ * the record that sets `staleUntil`: its cache() config, and whether this
+ * request wrote it (cacheRoute) rather than read it.
+ */
+export interface RouteRecordWindow {
+  freshUntil: number;
+  staleUntil: number;
+  ttl: number;
+  swr: number;
+  written: boolean;
+}
+
 /**
  * Public view of RequestContext, without internal methods and fields.
  *
@@ -751,16 +884,23 @@ export type PublicRequestContext<
   | "_shellImplicitCache"
   | "_shellLoaderSeed"
   | "_shellCaptureLoaderRecords"
-  | "_shellCaptureHandleLiveness"
+  | "_shellCaptureUnrecordedLoaderPush"
+  | "_resolvedCacheKeys"
+  | "_shellKey"
+  | "_shellForcedMiss"
+  | "_routeRecordWindow"
   | "_shellFragmentPayload"
   | "_shellCaptureGuardTripped"
   | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
+  | "_recordTagOwners"
+  | "_recordLoaderTags"
   | "_cacheProfiles"
   | "_onResponseCallbacks"
   | "_pendingBackgroundTasks"
   | "_themeConfig"
+  | "_readTheme"
   | "_locationState"
   | "_routeName"
   | "_prevRouteKey"
@@ -795,6 +935,11 @@ export type PublicRequestContext<
   | "_setStatus"
   | "_rotateStateCookie"
   | "_setKeepCacheDirective"
+  | "_freshReads"
+  | "_setFreshReadsCookie"
+  | "_requestRoot"
+  | "_tagInvalidations"
+  | "_responseSent"
   | "_variables"
   | "_classifiedRoute"
   | "_requestMode"
@@ -991,6 +1136,10 @@ export function createRequestContext<TEnv>(
   } = options;
   const cookieHeader = request.headers.get("Cookie");
   let rangoStateRotated = false;
+  const freshCookie = stateCookieName
+    ? freshReadsCookieName(stateCookieName)
+    : undefined;
+  let freshCookieMaxAge = 0;
   let parsedCookies: Record<string, string> | null = null;
 
   let stubResponse = initialResponse
@@ -1144,7 +1293,7 @@ export function createRequestContext<TEnv>(
     _dynamic: false,
     get: ((keyOrVar: any) => {
       if (isNonCacheable(variables, keyOrVar)) {
-        assertNonCacheableReadAllowed(keyOrVar);
+        assertNonCacheableReadAllowed(keyOrVar, _getRequestContext());
       }
       return contextGet(variables, keyOrVar);
     }) as RequestContext<TEnv>["get"],
@@ -1254,6 +1403,48 @@ export function createRequestContext<TEnv>(
       rawStubHeaders.set(KEEP_CACHE_HEADER, "1");
     },
 
+    // The fresh-reads cookie (browser/cookie-name.ts): one Set-Cookie per
+    // response, the longest Max-Age any invalidation asked for. HttpOnly (the
+    // client never reads it), SameSite=Lax, Path=/. rawStubHeaders: an
+    // internal writer, allowed wherever updateTag()/revalidateTag() are. A
+    // shared cache never stores it (Set-Cookie is a per-client signal).
+    _setFreshReadsCookie(maxAgeMs: number): void {
+      if (!freshCookie) return;
+      const maxAge = Math.ceil(maxAgeMs / 1000);
+      // Already set for at least this long (an earlier invalidation in this
+      // request): nothing to add, sent or not.
+      if (maxAge <= freshCookieMaxAge) return;
+      if (ctx._responseSent) {
+        // A streaming loader or render: the headers already left. The
+        // invalidation itself still ran; only the mutating user's bypass of
+        // the stores' isolate memos is lost.
+        if (process.env.NODE_ENV !== "production") {
+          console.warn(
+            `[rango] updateTag()/revalidateTag() ran after the response ` +
+              `headers were sent (from a streaming loader or render), so the ` +
+              `${freshCookie} cookie was not set: this user's next requests ` +
+              `can be served from a store's isolate memo for a few seconds. ` +
+              `Invalidate in a server action, a route handler, or middleware.`,
+          );
+        }
+        return;
+      }
+      const serialized = (age: number) =>
+        `${freshCookie}=1; Max-Age=${age}; Path=/; HttpOnly; SameSite=Lax` +
+        (url.protocol === "https:" ? "; Secure" : "");
+      if (freshCookieMaxAge > 0) {
+        const prior = serialized(freshCookieMaxAge);
+        const kept = rawStubHeaders
+          .getSetCookie()
+          .filter((cookie) => cookie !== prior);
+        rawStubHeaders.delete("Set-Cookie");
+        for (const cookie of kept) rawStubHeaders.append("Set-Cookie", cookie);
+      }
+      freshCookieMaxAge = maxAge;
+      rawStubHeaders.append("Set-Cookie", serialized(maxAge));
+      invalidateResponseCookieCache();
+    },
+
     setStatus(status: number): void {
       assertNotInsideCacheExec(ctx, "setStatus");
       assertResponseWriteAllowed("setStatus");
@@ -1275,6 +1466,9 @@ export function createRequestContext<TEnv>(
     _explicitTaggedStores: explicitTaggedStores,
     _requestTags: new Set<string>(),
     _cacheProfiles: cacheProfiles,
+    _freshReads:
+      freshCookie !== undefined &&
+      getRawCookieValue(cookieHeader, freshCookie) !== null,
 
     waitUntil(fn: () => Promise<void>): void {
       if (ctx.build) return;
@@ -1316,9 +1510,8 @@ export function createRequestContext<TEnv>(
       this._onResponseCallbacks.push(callback);
     },
 
-    get theme() {
-      return themeConfig ? getTheme() : undefined;
-    },
+    // theme: a guarded, non-enumerable getter defined after this literal.
+    _readTheme: getTheme,
     setTheme: themeConfig
       ? (theme: Theme) => {
           assertNotInsideCacheExec(ctx, "setTheme");
@@ -1359,7 +1552,39 @@ export function createRequestContext<TEnv>(
     getContext: () => ctx,
   });
 
+  // getRequestContext().theme is the visitor's cookie, guarded like cookies()
+  // (#971); before it was a plain read that a ppr shell, a cache() entry or a
+  // "use cache" entry stored for every visitor. Non-enumerable like the
+  // handler ctx.theme (handler-context.ts THEME_DESCRIPTOR): serializing the
+  // context (React dev debug info) must not count as a read. The guard reads
+  // the ambient context, as cookies() does, and falls back to the receiver.
+  // _readTheme is the unguarded read: non-enumerable too, so a spread copy of
+  // the context (the fetchable-loader ctx, loader-fetch.ts) cannot carry it.
+  Object.defineProperties(ctx, {
+    theme: {
+      get(this: RequestContext<TEnv>): Theme | undefined {
+        if (!themeConfig) return undefined;
+        assertThemeReadAllowed(
+          _getRequestContext() ?? this,
+          "getRequestContext().theme",
+        );
+        return getTheme();
+      },
+      enumerable: false,
+      configurable: true,
+    },
+    _readTheme: { enumerable: false },
+  });
+
   (ctx as any)[NOCACHE_SYMBOL] = true;
+  // Non-enumerable: a self-reference would make the context circular for
+  // JSON.stringify, spreads and React's dev debug-info serialization of props.
+  Object.defineProperty(ctx, "_requestRoot", {
+    value: ctx,
+    enumerable: false,
+    configurable: true,
+    writable: true,
+  });
   return ctx;
 }
 

package/src/ssr/index.tsx

@@ -2,7 +2,11 @@ import React from "react";
 import { createSsrRootComponent, deserializeSsrPayload } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
 import { runWithPreinitNonce } from "./preinit-client-references.js";
-import { SHELL_CAPTURE_MAX_WAIT_MS } from "../rsc/shell-capture-constants.js";
+import {
+  POST_QUIESCE_TASK_HOPS,
+  SHELL_CAPTURE_MAX_WAIT_MS,
+} from "../rsc/shell-capture-constants.js";
+import { isThenable } from "../handles/is-thenable.js";
 import type { ErrorPhase } from "../types.js";
 import type { HeadScriptsOption } from "../vite/plugin-types.js";
 
@@ -237,28 +241,64 @@ export interface SSRDependencies<TEnv = unknown> {
 }
 
 /**
- * Fixed number of macrotask hops between `quiesce` resolving and the abort. These
- * give React's fizz worker turns to flush the settled shell into the prelude and
- * mark still-pending boundaries as POSTPONED (rather than errored) before
- * controller.abort() lands. Not a wall-clock wait.
- *
- * Why 16 and not the original 2: under the REPLAY-ONLY capture model
- * (docs/design/ppr-shell-resume.md), the capture Flight render serializes ring-3
- * cached segments that are ALREADY serialized, so it emits the whole shell payload
- * in the first tick and the gate declares quiesce almost immediately (~a few ms).
- * On the old fresh-execution path the Flight dribbled out as handlers ran, so
- * Flight-quiet effectively meant "the shell has rendered" and 2 hops sufficed.
- *
- * Hops alone are NOT render-readiness: fizz cannot emit even <html> until the
- * payload root settles, which waits on every referenced client-module LOAD —
- * real module-runner I/O in dev (100ms+ cold), which no fixed count of near-
- * zero-cost task hops can buy. captureShellHTML therefore awaits the payload-
- * settled signal (SsrRootOptions.onPayloadSettled, deadline-bounded) between
- * quiesce and these hops; the hops then only flush the settled tree and mark
- * pending boundaries POSTPONED. Still task-based (masked loaders never emit,
- * so more hops never lets a hole settle). Bounded by maxWaitMs end to end.
+ * One set per running capture, collecting the client-reference module loads
+ * requested while it runs (captureClientLoads). The Flight client resolves a
+ * client component used as an element type lazily, so the payload settles
+ * while its module is still loading, and a shell that renders it outside any
+ * Suspense boundary cannot complete until the load does. On the
+ * cloudflare-basic build a cold load (the module, its imports, its CSS
+ * virtual) settled at +890.1ms, after the payload (+873.4ms) and 1ms before
+ * the abort, and uninstrumented builds lost that race (issue #949). The
+ * Flight client asks the loader again for every import row, even for a
+ * module another render is already loading, so a capture sees each load it
+ * needs; one a concurrent render requests meanwhile is collected too and is
+ * the same bounded I/O. The sets are per capture, their contents isolate-wide:
+ * a load that never settles can only hold the captures running when it was
+ * requested, each until its deadline.
  */
-const POST_QUIESCE_TASK_HOPS = 16;
+const activeCaptureClientLoads = new Set<Set<PromiseLike<unknown>>>();
+
+/** The loader wrapper {@link captureClientLoads} last installed. */
+let recordingClientReferenceLoader: ((id: string) => unknown) | undefined;
+
+/**
+ * Start collecting the client-reference loads requested during a capture;
+ * call the returned `stop` when the capture ends. Wraps plugin-rsc's SSR
+ * loader (`globalThis.__vite_rsc_client_require__`, which
+ * `__vite_rsc_require__` reads per call) on the first capture, so an isolate
+ * that never captures keeps the bare loader. Wraps again when another wrapper
+ * replaced this one (the build shell phase bridges hashed ids the same way,
+ * vite/discovery/shell-prerender-phase.ts). Collects nothing without the
+ * loader.
+ */
+function captureClientLoads(): {
+  loads: Set<PromiseLike<unknown>>;
+  stop: () => void;
+} {
+  const g = globalThis as {
+    __vite_rsc_client_require__?: (id: string) => unknown;
+  };
+  const load = g.__vite_rsc_client_require__;
+  if (typeof load === "function" && load !== recordingClientReferenceLoader) {
+    recordingClientReferenceLoader = (id) => {
+      const loading = load(id);
+      // plugin-rsc memoizes one promise per id and the Flight client stamps
+      // status "fulfilled" on it once loaded: a warm module is not collected.
+      if (
+        activeCaptureClientLoads.size > 0 &&
+        isThenable(loading) &&
+        (loading as { status?: string }).status !== "fulfilled"
+      ) {
+        for (const loads of activeCaptureClientLoads) loads.add(loading);
+      }
+      return loading;
+    };
+    g.__vite_rsc_client_require__ = recordingClientReferenceLoader;
+  }
+  const loads = new Set<PromiseLike<unknown>>();
+  activeCaptureClientLoads.add(loads);
+  return { loads, stop: () => activeCaptureClientLoads.delete(loads) };
+}
 
 /**
  * Route an SSR error through the deps.onError notification callback with the
@@ -421,6 +461,13 @@ interface ShellCaptureOptions {
    * refuses to store the shell (issue #915).
    */
   onError?: (error: unknown) => void;
+  /**
+   * Called with React's errorInfo for each task still pending when the
+   * capture's own abort froze the prelude; its componentStack is computed
+   * when read. The dev no-shell warning prints the stacks: one of them is what
+   * suspended above <body> (issue #941).
+   */
+  onAbortedTask?: (errorInfo: { componentStack?: string } | undefined) => void;
 }
 
 /**
@@ -761,12 +808,13 @@ export function createShellCaptureHandler<TEnv = unknown>(
     const deadline = (await isDebuggerAttached())
       ? { promise: new Promise<void>(() => {}), cancel: () => {} }
       : createCancelableTimeout(maxWaitMs);
+    const clientLoads = captureClientLoads();
     try {
       // No nonce (nonce'd requests never reach capture); no formState.
-      // payloadSettled: fires when the Flight payload root settles — i.e.
-      // every client-module load the payload references completed and fizz
-      // can actually emit the tree. The abort below gates on it (bounded by
-      // the same deadline): Flight byte-quiet alone is NOT render-readiness.
+      // payloadSettled: fires when the Flight payload root settles and fizz
+      // can emit the tree. The abort below gates on it and on the
+      // client-reference loads in flight in the isolate (bounded by the same
+      // deadline): Flight byte-quiet alone is NOT render-readiness.
       let settlePayload!: () => void;
       const payloadSettled = new Promise<void>((resolve) => {
         settlePayload = resolve;
@@ -823,8 +871,9 @@ export function createShellCaptureHandler<TEnv = unknown>(
         // 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) => {
+        onError: (error: unknown, errorInfo?: { componentStack?: string }) => {
           if (error === abortReason) {
+            opts.onAbortedTask?.(errorInfo);
             return;
           }
           opts.onError?.(error);
@@ -846,25 +895,34 @@ export function createShellCaptureHandler<TEnv = unknown>(
       // shell that never goes quiet (a root postpone / hung handle).
       await Promise.race([opts.quiesce, deadline.promise]);
       // Then wait for fizz RENDER-READINESS, bounded by the same deadline:
-      // the payload root settles only after every client-module load the
-      // payload references completed (real module-runner I/O in dev; 100ms+
-      // on a cold graph). Flight byte-quiet does NOT imply this — a fully
+      // the payload root settles, then the client-reference module loads the
+      // capture started settle — a client component used as an element type
+      // resolves lazily, after the payload (real module-runner I/O in dev;
+      // 100ms+ on a cold graph). Flight byte-quiet does NOT imply this — a fully
       // REPLAYED (prerendered) route's Flight stream finishes in ~1-3ms and
       // an abort taken on quiet-plus-task-hops alone landed BEFORE fizz could
       // emit <html>, freezing a zero-byte prelude: the eternal-MISS shape
       // this route class showed on every cold graph (dev cold boots, GH
       // runners) while ordinary routes — whose live handler execution keeps
-      // Flight noisy long enough — never hit it. Masked-loader holes do not
-      // block payload settlement (they postpone below the root), so this
-      // await costs a genuinely hole-y shell nothing; a payload that NEVER
-      // settles (hung handles) degrades at the deadline exactly as before.
-      // A prerender that SETTLES first (early success or a hard rejection)
-      // ends the wait immediately — fizz is already done either way.
+      // Flight noisy long enough — never hit it. Holes the payload carries
+      // block neither wait (masked live loaders and loader-nested promises postpone
+      // below the root and load no module; the Flight input stays frozen),
+      // so this await costs a genuinely hole-y shell nothing; a payload that
+      // NEVER settles (hung handles) degrades at the deadline exactly as
+      // before. A prerender that SETTLES first (early success or a hard
+      // rejection) ends the wait immediately — fizz is already done either
+      // way.
       const prerenderSettled = prerenderPromise.then(
         () => {},
         () => {},
       );
-      await Promise.race([payloadSettled, prerenderSettled, deadline.promise]);
+      // The capture's loads all started when their import rows were parsed,
+      // before the Flight input froze.
+      await Promise.race([
+        payloadSettled.then(() => Promise.allSettled(clientLoads.loads)),
+        prerenderSettled,
+        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 and
@@ -923,6 +981,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
       };
     } finally {
       deadline.cancel();
+      clientLoads.stop();
     }
   };
 }