@rangojs/router 0.15.1 → 0.17.0

package/src/rsc/response-route-handler.ts

@@ -8,7 +8,7 @@
 
 import { RouterError } from "../errors.js";
 import { getRequestContext } from "../server/request-context.js";
-import { contextGet } from "../context-var.js";
+import { contextGet, isNonCacheable } from "../context-var.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { RESPONSE_TYPE_MIME } from "../router/content-negotiation.js";
 import { createCacheScope, resolveCacheTags } from "../cache/cache-scope.js";
@@ -19,7 +19,10 @@ import {
   stripInternalParams,
 } from "../router/handler-context.js";
 import type { MiddlewareFn } from "../router/middleware.js";
-import type { EntryData } from "../server/context.js";
+import {
+  assertNonCacheableReadAllowed,
+  type EntryData,
+} from "../server/context.js";
 import type { HandlerContext } from "./handler-context.js";
 import { createProblemDetails } from "./response-error.js";
 import {
@@ -85,7 +88,12 @@ export async function handleResponseRoute<TEnv>(
     originalUrl: reqCtx.originalUrl,
     pathname: url.pathname,
     reverse: createReverseFunction(handlerCtx.getRequiredRouteMap()),
-    get: ((keyOrVar: any) => contextGet(variables, keyOrVar)) as any,
+    get: ((keyOrVar: any) => {
+      if (isNonCacheable(variables, keyOrVar)) {
+        assertNonCacheableReadAllowed(keyOrVar);
+      }
+      return contextGet(variables, keyOrVar);
+    }) as any,
     header: (name: string, value: string) => reqCtx.header(name, value),
     waitUntil: reqCtx.waitUntil.bind(reqCtx),
     executionContext: reqCtx.executionContext,

package/src/rsc/rsc-rendering.ts

@@ -2,8 +2,7 @@
  * RSC Rendering Handler (Navigation)
  *
  * Handles RSC rendering for both partial (client-side navigation) and full
- * (initial page load) requests. Includes prerender collection for build-time
- * static generation.
+ * (initial page load) requests.
  */
 
 import {
@@ -394,8 +393,8 @@ function* requestRenderPlan<TEnv>(
   const shell = yield* scope("shell-serve", shellServePlan(input));
   if (shell.kind === "serve") return shell.response;
 
-  // Match + payload. A control response (redirect, prerender collection)
-  // ends the plan before any rendering.
+  // Match + payload. A control response (redirect) ends the plan before any
+  // rendering.
   const prepared = yield* scope(
     isPartial ? "prepare:partial" : "prepare:full",
     preparePayloadPlan(input),
@@ -470,7 +469,6 @@ function* shellServePlan<TEnv>(
   if (
     isPartial ||
     request.method !== "GET" ||
-    url.searchParams.has("__prerender_collect") ||
     isRscRequest(request, url, false) ||
     reqCtx._dynamic
   ) {
@@ -639,7 +637,7 @@ function* shellServePlan<TEnv>(
 
 /**
  * Match the request and assemble the RSC payload, or produce a control
- * response (redirect, prerender collection) that ends the request plan.
+ * response (redirect) that ends the request plan.
  */
 function* preparePayloadPlan<TEnv>(
   input: RequestRenderInput<TEnv>,
@@ -750,13 +748,6 @@ function* preparePayloadPlan<TEnv>(
   // Caching is now handled in router.match() via cache provider in request context
   // match.segments already contains cached or fresh segments as appropriate
 
-  if (url.searchParams.has("__prerender_collect")) {
-    const response = yield* step("prerender-collect", () =>
-      collectPrerenderArtifacts(match, handleStore),
-    );
-    return { kind: "control", response };
-  }
-
   return {
     kind: "payload",
     payload: buildFullPayload(match, ctx, url, reqCtx, handleStore),
@@ -869,38 +860,6 @@ function mirrorPprServerTimingsForDev(
   }
 }
 
-/**
- * Build-time prerender collection: serialize segments and handle data
- * to JSON for storage as build artifacts. At runtime the worker
- * deserializes these and feeds them through the normal segment pipeline.
- */
-async function collectPrerenderArtifacts<TEnv>(
-  match: Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>,
-  handleStore: ReturnType<typeof getRequestContext>["_handleStore"],
-): Promise<Response> {
-  const nonLoaderSegments = match.segments.filter((s) => s.type !== "loader");
-  handleStore.seal();
-  await handleStore.settled;
-  const { serializeSegments } = await import("../cache/segment-codec.js");
-  const serializedSegments = await serializeSegments(nonLoaderSegments);
-  const handles: Record<string, Record<string, unknown[]>> = {};
-  for (const seg of nonLoaderSegments) {
-    const segHandles = handleStore.getDataForSegment(seg.id);
-    if (Object.keys(segHandles).length > 0) {
-      handles[seg.id] = segHandles;
-    }
-  }
-  return new Response(
-    JSON.stringify({
-      segments: serializedSegments,
-      handles,
-      routeName: match.routeName,
-      params: match.params,
-    }),
-    { headers: { "Content-Type": "application/json" } },
-  );
-}
-
 /** Assemble headers + tracking and run the foreground stage-driver render. */
 function renderPreparedRscResponse<TEnv>(
   input: RequestRenderInput<TEnv>,
@@ -1534,6 +1493,10 @@ function serveShellHit(
         search: shellSearchSeed(url, reqCtx._searchParamsFilter),
         // The HIT request's origin — same host as the capture's (key-scoped).
         origin: url.origin,
+        // The document cache reads the list before storing this composite.
+        onError: (error) => {
+          reqCtx._renderErrors?.push(error);
+        },
       }),
     );
   };

package/src/rsc/shell-capture-constants.ts

@@ -43,3 +43,16 @@ export const SHELL_CAPTURE_MAX_WAIT_MS = 15_000;
  * check on the stampede guard, keyed off the same constant.
  */
 export const SHELL_CAPTURE_TASK_HARD_CAP_MS = 25_000;
+
+/**
+ * Shared PPR loader-lane hint, appended to every capture warning or error
+ * whose fix depends on the lane (shell-capture.ts warnings, the cookie-store.ts
+ * capture guard). Lives in this import-free leaf so cookie-store.ts can import
+ * it without pulling the capture orchestration module. Source anchor for the
+ * rule: resolveLoaderData (router/segment-resolution/loader-cache.ts).
+ */
+export const PPR_LANE_HINT: string =
+  "Lane rule: only loader(Def, { ssr: false }) executes at capture and bakes its " +
+  "non-promise data; every other loader is live (masked at capture, fresh per " +
+  "request) and needs loading() or an inline <Suspense> above its reader. See the " +
+  '/ppr skill, "The loader lane rule" (node_modules/@rangojs/router/skills/ppr/SKILL.md).';

package/src/rsc/shell-capture.ts

@@ -28,6 +28,7 @@ import {
   enqueueSerializedCapture,
 } from "./capture-queue.js";
 import {
+  PPR_LANE_HINT,
   SHELL_CAPTURE_MAX_WAIT_MS,
   SHELL_CAPTURE_TASK_HARD_CAP_MS,
 } from "./shell-capture-constants.js";
@@ -257,10 +258,11 @@ function releaseCaptureGuard(key: string, token: CaptureGuardToken): void {
  * mode's ceiling (60s in production, {@link REFUSED_CAPTURE_DEV_MAX_MS} in dev).
  *
  * Why exponential and not a flat 60s: a flat long window conflates two very
- * different failures. A STRUCTURALLY ineligible route (no loading(), a cookie
- * reader) fails forever and wants the long 60s cap. But a cold-but-ELIGIBLE route
- * can also fail the in-place retry under a truly cold graph (dev module transform,
- * or a cold worker under parallel load) — and it must recover FAST, on the next
+ * different failures. A STRUCTURALLY ineligible route (a boundary-less live
+ * loader read, a cookie reader) fails forever and wants the long 60s cap. But a
+ * cold-but-ELIGIBLE route can also fail the in-place retry under a truly cold
+ * graph (dev module transform, or a cold worker under parallel load) — and it
+ * must recover FAST, on the next
  * request or two, not be frozen for 60s (that would re-break the very cold-start DX
  * the retry fixes; it bit the cloudflare dev e2e). Escalating from 1s means the
  * eligible route re-probes almost immediately (warm now → HIT and clear), while the
@@ -366,9 +368,8 @@ const warnedNullCaptures = new Set<string>();
  * usually healed, so a firing warning leans toward the structural cause — but we
  * still name both so a cold-start straggler is not misdiagnosed.
  *
- * The pointer is shipped-path-safe (a05c8251 convention): the /ppr skill ships in
- * the npm tarball, but docs/design/ is repo-only, so link it by absolute GitHub URL
- * rather than a relative path that dead-ends for consumers.
+ * The pointer is the shared PPR_LANE_HINT: the /ppr skill ships in the npm
+ * tarball, so the path resolves for consumers (a05c8251 convention).
  */
 function warnNullCaptureOnce(key: string): void {
   if (warnedNullCaptures.has(key)) return;
@@ -379,18 +380,13 @@ function warnNullCaptureOnce(key: string): void {
       "by whether the route ever flips to HIT:\n" +
       "  1. Cold-start warmup (dev module transform, or a cold worker): the capture raced " +
       "an unfinished shell render. This SELF-HEALS — the route flips to HIT once a later " +
-      "request warms the modules. Usually nothing to do.\n" +
+      "request warms the modules.\n" +
       "  2. Something suspends above <body> with no Suspense boundary and never settles " +
-      "within the capture window: a slower-than-the-capture-guard bake-lane loader " +
-      "(loaders on entries WITHOUT loading() execute at capture and their containers " +
-      "bake — the boundary-less await must settle for a shell to exist), or a pending " +
-      "promise consumed without a <Suspense> above it. The boundary belongs on the " +
-      "entry/component that OWNS the data: loading() on the entry that registers the " +
-      "loader (a child route's loading() does not unpin a parent layout's loaders), or " +
-      "a <Suspense> above the consuming component.\n" +
-      'See the /ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md), "The hole ' +
-      'doctrine" and "The layout-with-loaders playbook", or the design docs: ' +
-      "https://github.com/rangojs/rango/blob/main/packages/rangojs-router/docs/design/ppr-shell-resume.md",
+      "within the capture window: a live loader (no ssr: false) read without loading() or " +
+      "an inline <Suspense>; a loader(Def, { ssr: false }) or top-level push (e.g. Meta) " +
+      "slower than ppr.captureTimeout; or a pending promise with no Suspense above it. The " +
+      "boundary belongs to the entry or component that owns the data.\n" +
+      PPR_LANE_HINT,
   );
 }
 
@@ -399,19 +395,23 @@ const warnedRefusedCaptures = new Set<string>();
 
 /**
  * Warn once per key that the capture was REFUSED for a deterministic reason
- * (identity-guard trip or a rejected bake-lane loader). Distinct from
- * warnNullCaptureOnce: these are not cold-start shapes, the retry is skipped,
- * and the message carries the concrete cause instead of a differential.
+ * (identity-guard trip, a rejected or signal-settled bake-lane loader, a store
+ * refusal). Distinct from warnNullCaptureOnce: these are not cold-start
+ * shapes, the retry is skipped, and the message carries the concrete cause
+ * instead of a differential. Lane-dependent causes pass PPR_LANE_HINT as the
+ * trailing pointer; the rest keep the plain skill pointer.
  */
-function warnCaptureRefusedOnce(key: string, reason: string): void {
+function warnCaptureRefusedOnce(
+  key: string,
+  reason: string,
+  pointer: string = "See the /ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md).",
+): void {
   if (warnedRefusedCaptures.has(key)) return;
   warnedRefusedCaptures.add(key);
   console.warn(
     `[rango] Shell capture for "${key}" was refused: ${reason}\n` +
       "The route stays on MISS (axis 1) — the page keeps working, only the shell " +
-      "cache is off. See the /ppr skill " +
-      "(node_modules/@rangojs/router/skills/ppr/SKILL.md) and " +
-      "docs/design/loader-container-bake.md.",
+      `cache is off. ${pointer}`,
   );
 }
 
@@ -489,13 +489,11 @@ function warnBakeCostOnce(key: string, source: string, ms: number): void {
     `[rango] Shell capture for "${key}" waited ${ms}ms for ${source} to ` +
       "settle before the shell could freeze. This cost recurs on every capture " +
       "of the route and occupies the per-isolate capture queue; the served " +
-      "response never shows it. Top-level promises BAKE by design (the " +
-      "container settles; nested promises stay live). To make the value " +
-      "per-request instead, nest it ({ data: promise }) and read it with use() " +
-      "under Suspense; to keep it baked but cheap, wrap the work in cache() " +
-      "(the capture replays the cached value); for a segment loader, add a " +
-      "loading() boundary to its entry (live lane, masked at capture). See the " +
-      "/ppr skill (node_modules/@rangojs/router/skills/ppr/SKILL.md).",
+      "response never shows it. To make the value per-request, nest it " +
+      "({ data: promise }) and read it with use() under Suspense; to keep it " +
+      "baked but cheap, wrap the work in cache(); for a loader(Def, { ssr: false }), " +
+      "drop ssr: false to move it to the live lane. " +
+      PPR_LANE_HINT,
   );
 }
 
@@ -1328,8 +1326,9 @@ async function runShellCapture(
   if (second !== "no-shell") return second;
 
   // Both attempts came back with no usable shell. Cold-start would have healed by
-  // now, so the eternal-MISS structural shape (a loader route without loading()) is
-  // the likely cause — warn once per key. Ordering matters: because the retry
+  // now, so the eternal-MISS structural shape (a boundary-less live-loader read;
+  // lane rule: see resolveLoaderData, loader-cache.ts) is the likely cause —
+  // warn once per key. Ordering matters: because the retry
   // absorbs cold-start, cold-start routes almost never reach this warning. The
   // caller (scheduleShellCapture) reads this `no-shell` return to back the key off.
   log(
@@ -1507,29 +1506,34 @@ export function deriveShellCaptureContext(
   //    re-run can fill, so the entry must not serve handler-free
   //    (ShellCacheEntry.handlerLiveHoles). Still-pending top-level handler
   //    pushes at the putShell barrier count too — their liveness is unknowable.
-  //  - loaderScopedPushValues: DSL-loader pushes re-run fresh on every HIT, so
-  //    their captured values must NOT enter a segment record's handle snapshot
+  //  - loader-push tag: DSL-loader pushes re-run fresh on every HIT, so their
+  //    captured values must NOT enter a segment record's handle snapshot
   //    (replay would duplicate the fresh push, and their masked nested
-  //    promises would stall the Flight handle encode to its timeout). The set
-  //    rides the derived context (_shellCaptureLoaderHandleValues) and is
-  //    applied ONLY at the captureHandles cache-write call site — every other
-  //    getDataForSegment consumer (the render-barrier snapshot, prerender)
-  //    sees every push.
+  //    promises would stall the Flight handle encode to its timeout). The
+  //    store tags them by array position (HandleStore.push loaderPush), which
+  //    covers primitives, and only the captureHandles cache-write call site
+  //    excludes tagged pushes — every other getDataForSegment consumer (the
+  //    render-barrier snapshot, prerender) sees every push. Unflagged loaders
+  //    never execute at capture; the tagged pushes come from loaders an
+  //    ssr:false loader awaits via ctx.use and from loader-cache replays
+  //    (loader-cache.ts replayLoaderHandles), both re-run on a HIT.
   //    EXCEPTION — bake-lane { ssr: false } loaders: they execute at capture
-  //    and never re-run on a HIT, so neither exclusion rationale applies. The
-  //    capture awaits them (fresh.ts), their pushes are in the captured HTML
-  //    (<head> title/meta, useHandle echoes), and the stored snapshot MUST
-  //    carry the same values or HIT hydration mismatches against its own
-  //    prelude (server text present, client handle empty). Only their
-  //    settled, thenable-free pushes qualify — a deferred (thenable) push or
-  //    one with masked nested promises keeps the exclusion so the handle
-  //    encode cannot stall on a never-resolving mask.
+  //    (fresh.ts awaits them), their pushes are in the captured HTML (<head>
+  //    title/meta, useHandle echoes), and the stored snapshot carries the same
+  //    values so a HIT's handle data is guaranteed to match its own prelude.
+  //    They still re-run on every HIT (resolveLoaderData, loader-cache.ts), so
+  //    each kept push carries its loader as `owner` (HandleStore.push): the
+  //    record stores it (CachedEntryData.handleOwners), the HIT restores it
+  //    through pushReplayed, and the re-run's live pushes replace the
+  //    restored copies in place. Only settled, thenable-free pushes
+  //    qualify — a deferred (thenable) push or one with masked nested promises
+  //    keeps the exclusion so the handle encode cannot stall on a
+  //    never-resolving mask.
   const handleLiveness = {
     holes: false,
     pendingPushes: 0,
     handlerInvokedLoader: false,
   };
-  const loaderScopedPushValues = new WeakSet<object>();
   const rawCapturePush = freshHandleStore.push.bind(freshHandleStore);
   freshHandleStore.push = (
     handleName: string,
@@ -1550,42 +1554,36 @@ export function deriveShellCaptureContext(
       return masked;
     };
     let masked: unknown;
+    let loaderPush = pushedInLoaderScope;
+    let owner: string | undefined;
     if (isThenable(value)) {
       if (!pushedInLoaderScope) {
         handleLiveness.pendingPushes++;
         const settle = () => handleLiveness.pendingPushes--;
         value.then(settle, settle);
       }
-      masked = value.then(maskWithLiveness);
-      // Deferred (thenable) loader pushes always keep the exclusion — the
+      // Deferred (thenable) loader pushes always keep the tag — the
       // bake-lane carve-out below is for settled values only.
-      if (pushedInLoaderScope) {
-        loaderScopedPushValues.add(masked as object);
-      }
+      masked = value.then(maskWithLiveness);
     } else {
       masked = maskWithLiveness(value);
-      if (
-        pushedInLoaderScope &&
-        typeof masked === "object" &&
-        masked !== null
-      ) {
+      if (loaderPush && !maskedNestedThenable) {
         // Bake-lane { ssr: false } loader pushes are shell material (see the
-        // funnel comment above): keep them IN the stored snapshot when
-        // settled and thenable-free; everything else stays excluded.
+        // funnel comment above): untagged, the stored snapshot keeps them
+        // when settled and thenable-free; everything else stays tagged.
         const bodyLoaderId = getCurrentLoaderBodyId();
-        const baked =
-          bodyLoaderId !== undefined &&
-          !maskedNestedThenable &&
-          derivedCtx._awaitBeforeFlushLoaderIds?.has(bodyLoaderId) === true;
-        if (!baked) {
-          loaderScopedPushValues.add(masked);
-        }
+        loaderPush =
+          bodyLoaderId === undefined ||
+          derivedCtx._awaitBeforeFlushLoaderIds?.has(bodyLoaderId) !== true;
+        if (!loaderPush) owner = bodyLoaderId;
       }
     }
-    rawCapturePush(handleName, segmentId, masked);
+    rawCapturePush(handleName, segmentId, masked, loaderPush, owner);
   };
 
-  const derivedCtx: RequestContext = Object.create(reqCtx);
+  const derivedCtx: RequestContext = Object.assign(Object.create(reqCtx), {
+    _handleStore: freshHandleStore,
+  });
   if (identity) {
     derivedCtx.request = identity.request;
     derivedCtx.url = identity.url;
@@ -1593,7 +1591,6 @@ export function deriveShellCaptureContext(
     derivedCtx.pathname = identity.url.pathname;
     derivedCtx.searchParams = identity.url.searchParams;
   }
-  derivedCtx._handleStore = freshHandleStore;
   // Own render barrier, closure-bound to the derived ctx and the fresh store
   // (issue #684, plan 009). Without this every _renderBarrier* read fell
   // through the prototype to the foreground's ALREADY-RESOLVED barrier: a
@@ -1603,7 +1600,6 @@ export function deriveShellCaptureContext(
   // also resets _treeHasStreaming (recomputed for the capture's tree) and the
   // deadlock-guard fields as own properties.
   wireRenderBarrier(derivedCtx, freshHandleStore);
-  derivedCtx._shellCaptureLoaderHandleValues = loaderScopedPushValues;
   derivedCtx._requestTags = new Set<string>();
   // Own explicit-store registry: cache-store resolutions during the capture
   // (the implicit scope's SnapshotOnlySegmentStore, any per-capture explicit
@@ -1614,6 +1610,9 @@ export function deriveShellCaptureContext(
   // context; module-singleton stores stay registered by normal renders.
   derivedCtx._explicitTaggedStores = new Set();
   derivedCtx._transitionWhen = [];
+  // Own list: the capture's render errors refuse the capture only, and the
+  // foreground's never reach it.
+  derivedCtx._renderErrors = [];
   derivedCtx._shellCaptureRun = true;
   // Own-property reset: an inherited flag would make serializeSegments store
   // a double-encoded fragment. No current arming site reaches a capture
@@ -1714,8 +1713,9 @@ async function captureAndStoreShell(
   // generator has not yielded, SsrRoot suspends at the root (consumeAsyncGenerator
   // sits above every boundary), the prelude comes back trivial, and
   // captureShellHTML's sanity gate returns null: the designed fail-safe no-op, not
-  // an error. This mirrors the __prerender_collect seal+settled regime, which also
-  // excludes loaders. See docs/design/ppr-shell-resume.md ("Loaders and handles").
+  // an error. This mirrors the matchForPrerender (router/prerender-match.ts)
+  // seal+settled regime, which also excludes loaders. See
+  // docs/design/ppr-shell-resume.md ("Loaders and handles").
   handleStore.seal();
 
   // Handles contract, shell half ("nesting = liveness"): TOP-LEVEL pushed handle
@@ -1794,13 +1794,12 @@ async function captureAndStoreShell(
       : "handler/render code (no loader body was executing)";
     warnCaptureRefusedOnce(
       capture.key,
-      `${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).",
+      `${origin} called ${fnName}() during capture; identity must not bake into the shared shell. ` +
+        "Segment loader: drop ssr: false and read it under loading() or an inline <Suspense> " +
+        "(a nested promise does not help: its body still runs at capture). Handler/render " +
+        "code: read it in a live loader and consume it with useLoader. Exception: " +
+        "await ctx.use(loader) in a HANDLER bakes as a capture-time copy.",
+      PPR_LANE_HINT,
     );
     return "refused";
   };
@@ -1819,6 +1818,9 @@ async function captureAndStoreShell(
           // static-part search reads bake what the key names.
           search: capture.searchSeed,
           origin: capture.originSeed,
+          onError: (error) => {
+            reqCtx._renderErrors?.push(error);
+          },
         }),
       );
     } catch (error) {
@@ -1835,9 +1837,9 @@ async function captureAndStoreShell(
     // null = sanity gate refused (trivial/empty prelude, no <body>). Store nothing
     // and report `no-shell` so the caller (runShellCapture) can retry once and, if
     // that also fails, warn once per key. On a cold render this is the shell not
-    // yet finished; on a loader route WITHOUT a route-level loading() boundary it is
-    // the structural eternal-MISS shape (the masked loader pins the tree above
-    // <body> at tree-build). The caller's warning names both.
+    // yet finished; a boundary-less live-loader read (lane rule: see
+    // resolveLoaderData, loader-cache.ts) is the structural eternal-MISS shape.
+    // The caller's warning names both.
     // Guard check first — BEFORE the trivial-prelude retry path. A guard trip
     // is deterministic (retrying re-trips it), and when the tripping loader's
     // error UI still completed a shell, storing it would bake the failure into
@@ -1938,7 +1940,8 @@ async function captureAndStoreShell(
           warnCaptureRefusedOnce(
             capture.key,
             `the loader for segment "${segmentKey}" rejected during capture; its error UI must not bake into the shared shell. ` +
-              "Fix the loader, or give its entry a loading() boundary so it stays on the live lane.",
+              "Fix the loader, or drop its ssr: false to move it to the live lane.",
+            PPR_LANE_HINT,
           );
           return "refused";
         }
@@ -1954,7 +1957,8 @@ async function captureAndStoreShell(
           warnCaptureRefusedOnce(
             capture.key,
             `the loader for segment "${segmentKey}" settled with redirect()/notFound() during capture; a request-specific signal must not bake into the shared shell. ` +
-              "Give its entry a loading() boundary so it stays on the live lane, or move the decision into middleware.",
+              "Drop its ssr: false to move it to the live lane, or move the decision into middleware.",
+            PPR_LANE_HINT,
           );
           return "refused";
         }
@@ -1966,7 +1970,14 @@ async function captureAndStoreShell(
           // must round-trip; serializeResult preserves it through Flight.
           serializeContainer ??= (await import("../cache/segment-codec.js"))
             .serializeResult;
-          const serialized = await serializeContainer(elided.value);
+          // A value Flight cannot encode (an async component that throws, a
+          // rejected promise the elide walk does not reach, a function, a
+          // class instance) completes with an error row instead of rejecting
+          // (issue #927). Collected with the render's errors, so the check
+          // after this drain refuses the capture.
+          const serialized = await serializeContainer(elided.value, (error) => {
+            reqCtx._renderErrors?.push(error);
+          });
           if (serialized !== null) {
             (snapshot ??= []).push({
               family: "loader",
@@ -1979,12 +1990,22 @@ async function captureAndStoreShell(
             });
           }
         } catch {
-          // Non-serializable container: leave it unpinned (it drifts on a HIT,
-          // the pre-snapshot behavior) rather than failing the capture.
+          // Codec import failed: leave it unpinned (it drifts on a HIT, the
+          // pre-snapshot behavior) rather than failing the capture.
         }
       }
     }
 
+    // A shell component that threw inside a Suspense boundary does not reject
+    // the capture: Flight and Fizz report it through onError and the prelude
+    // carries the errored boundary, which every HIT would serve (issue #915).
+    // The drain's container encode adds its Flight errors here too (#927).
+    // After the loader drain so a rejected bake-lane loader keeps its specific
+    // refusal. Thrown like a fatal shell error: no retry, reportCacheError and
+    // backoff in scheduleShellCapture.
+    const renderErrors = reqCtx._renderErrors;
+    if (renderErrors && renderErrors.length > 0) throw renderErrors[0];
+
     // Snapshot size guard (issue #651): the snapshot duplicates every pinned
     // cache value inside the shell entry, so a page over a large cache()
     // segment can push the stored envelope toward store value limits (KV caps

package/src/rsc/ssr-setup.ts

@@ -82,11 +82,11 @@ export interface SsrHtmlStageOptions<TEnv> {
   /** Metrics store for ssr:module-load / ssr:stream-mode timing (per call site). */
   metricsStore: MetricsStore | undefined;
   /**
-   * renderHTML options minus streamMode (the stage resolves streamMode). Carries
-   * the per-site nonce and, for the PE action re-render, formState. Spread
-   * verbatim so each call site's exact key set is preserved.
+   * renderHTML options minus streamMode and onError (the stage owns both).
+   * Carries the per-site nonce and, for the PE action re-render, formState.
+   * Spread verbatim so each call site's exact key set is preserved.
    */
-  render: Omit<SSRRenderOptions, "streamMode">;
+  render: Omit<SSRRenderOptions, "streamMode" | "onError">;
   /** ResponseInit merged into the prepared render (e.g. content-type). */
   init?: ResponseInit;
 }
@@ -109,6 +109,7 @@ export function createSsrHtmlStage<TEnv>(
       options.url,
       options.metricsStore,
     );
+    const renderErrors = _getRequestContext()?._renderErrors;
     return {
       render: () =>
         // search: the LIVE request's query string, threaded out-of-band into
@@ -124,6 +125,12 @@ export function createSsrHtmlStage<TEnv>(
           // so origin-dependent markup (Link's data-external) agrees with the
           // browser's window.location across hydration.
           origin: options.url.origin,
+          // A component that throws inside a Suspense boundary leaves an
+          // errored boundary in a completed document; the document cache
+          // reads the list before storing it.
+          onError: (error) => {
+            renderErrors?.push(error);
+          },
         }),
       ...(options.init && { init: options.init }),
     };
@@ -185,8 +192,8 @@ function acceptsFlightExplicitly(request: Request, url: URL): boolean {
  * Classify whether a request may require SSR (HTML rendering).
  *
  * Returns false for requests that are definitively RSC-only: transport
- * params (partial/action/loader/__rsc), prerender collection, or an explicit
- * Accept: text/x-component. Must never return false for a request whose
+ * params (partial/action/loader/__rsc) or an explicit Accept:
+ * text/x-component. Must never return false for a request whose
  * render-time decision (isRscRequest) will be HTML — the two share
  * acceptsFlightExplicitly so the Accept rule cannot drift. document-cache.ts
  * keys its HTML/RSC response slots off this function, so any divergence from
@@ -201,8 +208,7 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
     url.searchParams.has("_rsc_action") ||
     request.headers.has("rsc-action") ||
     url.searchParams.has("_rsc_loader") ||
-    url.searchParams.has("__rsc") ||
-    url.searchParams.has("__prerender_collect")
+    url.searchParams.has("__rsc")
   ) {
     return false;
   }

package/src/rsc/types.ts

@@ -193,6 +193,13 @@ export interface SSRRenderOptions {
    * the browser across hydration. Absent on host-agnostic build captures.
    */
   origin?: string;
+
+  /**
+   * Called for each error Fizz reports through its onError: a component that
+   * threw inside a Suspense boundary, which leaves the boundary errored in an
+   * otherwise completed document. React's default console.error is kept.
+   */
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -219,6 +226,8 @@ export interface SSRModule {
       maxWaitMs?: number;
       search?: string;
       origin?: string;
+      /** Each component error the prerender reports (never the capture's own abort). */
+      onError?: (error: unknown) => void;
     },
   ) => Promise<{ prelude: Uint8Array; postponed: string | null } | null>;
 
@@ -237,6 +246,8 @@ export interface SSRModule {
       nonce?: string;
       search?: string;
       origin?: string;
+      /** Each component error the resumed holes report. */
+      onError?: (error: unknown) => void;
     },
   ) => Promise<ReadableStream<Uint8Array>>;
 }