@rangojs/router 0.0.0-experimental.146 → 0.0.0-experimental.148

package/src/rsc/shell-serve.ts

@@ -30,11 +30,47 @@ export const SHELL_STATUS_HEADER = "x-rango-shell";
  */
 export const DEFAULT_PPR_TTL_SECONDS = 300;
 
+/**
+ * Timeout for the dev /__rsc_shell endpoint's sequential /__rsc_prerender
+ * pre-flight probe (vite/router-discovery.ts). Hoisted here so the client-side
+ * fetch bound (shell-build-manifest.ts devShellFetchTimeoutMs) enumerates the
+ * SAME term of the endpoint's worst-case envelope — the two cannot drift.
+ */
+export const DEV_SHELL_PROBE_TIMEOUT_MS: number = 10_000;
+
 /** The route's ppr option normalized to a concrete policy. */
 export interface ResolvedPprConfig {
   ttl: number;
   swr?: number;
   tags?: string[];
+  /**
+   * Snapshot size cap, passed through undefaulted (like swr/tags): the single
+   * defaulting site is captureAndStoreShell (DEFAULT_PPR_MAX_SNAPSHOT_BYTES in
+   * shell-capture.ts), so direct descriptor callers and resolved configs
+   * cannot drift.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in ms (`ppr.captureTimeout`). Undefined = the
+   * capture default (SHELL_CAPTURE_MAX_WAIT_MS, 5000) — the default's single
+   * owner stays shell-capture.ts so build/runtime producers cannot drift.
+   */
+  captureTimeout?: number;
+}
+
+/**
+ * Validate the raw `ppr.captureTimeout` option: a finite number >= 1ms passes
+ * through; anything else (including 0/negative/NaN/Infinity/non-number)
+ * resolves to undefined, which means "use the capture default" downstream.
+ * Mirrors the prefetch-limit option policy: invalid values silently fall back
+ * to the default rather than throwing at request time. Also the boundary
+ * re-normalizer for the dev /__rsc_shell endpoint (vite/router-discovery.ts),
+ * whose param crossed an HTTP query string.
+ */
+export function normalizeCaptureTimeout(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1
+    ? value
+    : undefined;
 }
 
 /**
@@ -42,6 +78,12 @@ export interface ResolvedPprConfig {
  * route does not declare `ppr` (or declares `ppr: false`) — the caller then does
  * NOTHING: no store read, no capture, no logs. Pure axis 1, zero cost.
  *
+ * The route's NAME is irrelevant here (and everywhere on the shell lane):
+ * nameless `path()` routes register their EntryData under a synthesized
+ * `$path_*` manifest key with the `ppr` option intact (urls/path-helper.ts),
+ * so a nameless entry resolves exactly like a named one — pinned by the
+ * nameless-ppr e2e in both apps (issue #714).
+ *
  * PPR is a DOCUMENT-level property of the page route; there is no subtree
  * inheritance (declaring it on a layout is not supported — a follow-up).
  */
@@ -56,6 +98,8 @@ export function resolvePprConfig(
     ttl: ppr.ttl ?? DEFAULT_PPR_TTL_SECONDS,
     swr: ppr.swr,
     tags: ppr.tags,
+    maxSnapshotBytes: ppr.maxSnapshotBytes,
+    captureTimeout: normalizeCaptureTimeout(ppr.captureTimeout),
   };
 }
 

package/src/rsc/ssr-setup.ts

@@ -11,6 +11,11 @@ import type { SSRModule } from "./types.js";
 import type { SSRStreamMode } from "../router/router-options.js";
 import type { MetricsStore } from "../server/context.js";
 import { appendMetric } from "../router/metrics.js";
+import {
+  parseAcceptTypes,
+  prefersFlightRepresentation,
+  RSC_WIRE_MIME,
+} from "../router/content-negotiation.js";
 import { _getRequestContext } from "../server/request-context.js";
 
 export type SSRSetup = readonly [SSRModule, SSRStreamMode];
@@ -90,12 +95,42 @@ export function getSSRSetup<TEnv>(
   );
 }
 
+/**
+ * Accept-based flight opt-in: the client explicitly listed the RSC wire
+ * format (text/x-component) in Accept, ranked above the HTML document, and
+ * did not override with __html.
+ *
+ * The flight stream is an internal transport representation — it is served
+ * ONLY on explicit opt-in (this Accept value, or the _rsc_ / __rsc transport
+ * params). Everything else (missing Accept, wildcards, application/json,
+ * browser Accept strings) gets the HTML document, per RFC 9110: a missing
+ * Accept is equivalent to a full wildcard, and a wildcard gets the server's
+ * canonical representation. The old rule ("no text/html substring → flight")
+ * handed the wire format to every generic client — curl, health checks,
+ * link unfurlers.
+ *
+ * The includes() guard is a parse-skipping fast path: the bulk of traffic
+ * (browsers, curl, monitors) never mentions the wire format and pays no
+ * parseAcceptTypes allocation. Ranking lives in prefersFlightRepresentation
+ * (router/content-negotiation.ts), co-located with the candidate MIME set.
+ */
+function acceptsFlightExplicitly(request: Request, url: URL): boolean {
+  if (url.searchParams.has("__html")) return false;
+  const accept = request.headers.get("accept");
+  if (accept === null || !accept.includes(RSC_WIRE_MIME)) return false;
+  return prefersFlightRepresentation(parseAcceptTypes(accept));
+}
+
 /**
  * Classify whether a request may require SSR (HTML rendering).
  *
- * Returns false for requests that are definitively RSC-only, loader fetches,
- * prerender collection, or Accept-based RSC (no text/html). This mirrors
- * the isRscRequest decision in rsc-rendering.ts.
+ * 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
+ * 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
+ * the render decision poisons a cache slot with the wrong representation.
  *
  * Note: response/mime routes are excluded by the caller — this function
  * runs after classifyRequest() determines the request mode.
@@ -112,24 +147,21 @@ export function mayNeedSSR(request: Request, url: URL): boolean {
     return false;
   }
 
-  // Mirror the Accept-based RSC decision from rsc-rendering.ts:
-  // if Accept is present and does not include text/html (and no __html override),
-  // the response will be RSC, not HTML.
-  const accept = request.headers.get("accept");
-  if (
-    accept &&
-    !accept.includes("text/html") &&
-    !url.searchParams.has("__html")
-  ) {
-    return false;
-  }
-
-  return true;
+  return !acceptsFlightExplicitly(request, url);
 }
 
-// Final render-time decision: is the response an RSC stream (vs HTML)? Distinct
-// from mayNeedSSR, which is a conservative pre-classifier (it treats a missing
-// Accept header as needing SSR; this treats it as RSC).
+// Final render-time decision: is the response an RSC stream (vs HTML)?
+// Flight requires explicit opt-in: the partial transport param, __rsc, or
+// Accept: text/x-component. mayNeedSSR is the coarse pre-filter over the
+// transport params; both delegate the Accept call to acceptsFlightExplicitly.
+//
+// _rsc_partial is read from the URL in addition to the plan-derived isPartial
+// flag: the 404 fallback plan hardcodes mode "full-render" even for partial
+// navigations (handler.ts RouteNotFoundError catch), so a partial 404 reaches
+// this decision with isPartial=false. The old Accept rule masked that by
+// classifying */* as flight; without the URL check a client-side navigation
+// to a missing route received an HTML 404 it cannot apply, and the
+// navigation never committed (multi-router soft-404, popstate not-found).
 export function isRscRequest(
   request: Request,
   url: URL,
@@ -137,8 +169,8 @@ export function isRscRequest(
 ): boolean {
   return (
     isPartial ||
-    (!request.headers.get("accept")?.includes("text/html") &&
-      !url.searchParams.has("__html")) ||
-    url.searchParams.has("__rsc")
+    url.searchParams.has("_rsc_partial") ||
+    url.searchParams.has("__rsc") ||
+    acceptsFlightExplicitly(request, url)
   );
 }

package/src/segment-fragments.ts

@@ -0,0 +1,124 @@
+/**
+ * Segment Flight-fragment envelopes (PPR fast-path payload splice, issue #700).
+ *
+ * On a shell-HIT tail, replayed (baked) segments do NOT round-trip through the
+ * server codec (deserialize -> re-serialize) per request. The stored RSC
+ * fragment STRINGS ride the outgoing payload verbatim inside these envelopes
+ * — the outer Flight render copies a string instead of re-serializing a whole
+ * element tree — and the CONSUMER expands each envelope through its own Flight
+ * deserializer: the SSR resume pass (ssr/ssr-root.tsx) and browser hydration
+ * (browser/rsc-router.tsx). Each fragment is its own row space, decoded
+ * independently, exactly like the segment codec's per-record decode — so
+ * there is no Flight row-id collision or shared-row dedupe hazard.
+ *
+ * Envelopes appear ONLY on fields that hold ReactNodes (component / layout /
+ * loading). A plain object is never a valid ReactNode, so the marker cannot
+ * collide with legitimate segment content; loader data fields (consumer data,
+ * any shape) are never enveloped.
+ *
+ * This module is shared client/server code (browser + SSR + RSC import it) —
+ * it must stay dependency-free: no plugin-rsc, no request-context.
+ */
+
+import type { ResolvedSegment } from "./types.js";
+
+/**
+ * One RSC-encoded fragment traveling inside an RscPayload segment field.
+ * `f` is the stored Flight document (segment-codec output) for that field.
+ */
+export interface SegmentFlightFragment {
+  __rangoFragment: 1;
+  f: string;
+}
+
+/** Wrap a stored fragment string for the wire. */
+export function segmentFragment(encoded: string): SegmentFlightFragment {
+  return { __rangoFragment: 1, f: encoded };
+}
+
+/** True iff `value` is a fragment envelope (see collision note in the header). */
+export function isSegmentFragment(
+  value: unknown,
+): value is SegmentFlightFragment {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __rangoFragment?: unknown }).__rangoFragment === 1 &&
+    typeof (value as { f?: unknown }).f === "string"
+  );
+}
+
+/**
+ * A consumer-side Flight deserializer: the browser's or the SSR runtime's
+ * createFromReadableStream (each resolves client references through its own
+ * module map, exactly as it does for the outer payload stream). Non-generic
+ * so both environments' generic createFromReadableStream signatures assign
+ * directly.
+ */
+export type FragmentDecoder = (
+  stream: ReadableStream<Uint8Array>,
+) => Promise<unknown>;
+
+/** One-chunk byte stream over an encoded fragment (local: this module must not
+ *  import segment-codec, which pulls plugin-rsc into client bundles). */
+function fragmentToStream(encoded: string): ReadableStream<Uint8Array> {
+  const bytes = new TextEncoder().encode(encoded);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+/** The segment fields that may carry an envelope (ReactNode fields only). */
+const FRAGMENT_FIELDS = ["component", "layout", "loading"] as const;
+
+/**
+ * Expand every fragment envelope in `segments` IN PLACE via `decode`,
+ * in parallel. A payload with no envelopes (every non-shell-HIT payload) costs
+ * one synchronous field scan. A failing fragment decode rejects the whole
+ * expansion: the caller's payload promise rejects, which on the SSR side
+ * errors the HIT tail (serveShellHit then schedules the healing recapture) —
+ * the same posture as a parseable-but-mismatched postponed blob.
+ */
+export async function expandSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+  decode: FragmentDecoder,
+): Promise<void> {
+  if (!segments || segments.length === 0) return;
+  const decodes: Promise<void>[] = [];
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      const value = segment[field];
+      if (isSegmentFragment(value)) {
+        // Promise.resolve() adoption is load-bearing: some deserializers
+        // (react-server-dom's Flight client) return a THENABLE Chunk whose
+        // .then returns undefined — chaining directly would push undefined
+        // into the barrier and Promise.all would not wait for the decode.
+        decodes.push(
+          Promise.resolve(decode(fragmentToStream(value.f))).then((node) => {
+            segment[field] = node as ResolvedSegment[typeof field];
+          }),
+        );
+      }
+    }
+  }
+  if (decodes.length > 0) await Promise.all(decodes);
+}
+
+/**
+ * True when any segment carries an unexpanded envelope. Cheap scan used by
+ * consumers that only need to know whether an expansion pass is required.
+ */
+export function hasSegmentFragments(
+  segments: ResolvedSegment[] | undefined,
+): boolean {
+  if (!segments) return false;
+  for (const segment of segments) {
+    for (const field of FRAGMENT_FIELDS) {
+      if (isSegmentFragment(segment[field])) return true;
+    }
+  }
+  return false;
+}

package/src/server/context.ts

@@ -27,6 +27,7 @@ export interface PerformanceMetric {
   duration: number; // milliseconds
   startTime: number; // relative to request start
   depth?: number; // nesting level for hierarchical display (0 = top-level)
+  desc?: string; // free-form outcome detail, emitted as Server-Timing desc="..."
 }
 
 /**

package/src/server/request-context.ts

@@ -228,6 +228,19 @@ export interface RequestContext<
     store?: SegmentCacheStore;
   };
 
+  /**
+   * @internal Shell-HIT tail marker: cache/prerender-store hits during THIS
+   * render emit stored segment fragments VERBATIM into the payload
+   * (segment-codec fragmentSegments) instead of deserialize -> re-serialize
+   * per request; the payload consumers (SSR resume + browser hydration)
+   * expand them (segment-fragments.ts, issue #700). Own property of
+   * serveShellHit's derived tail context ONLY — it must never be visible to a
+   * capture render: the capture SSR-prerenders the payload AND serializes
+   * segments into records (cacheRoute), and an envelope reaching
+   * serializeSegments would store a double-encoded fragment.
+   */
+  _shellFragmentPayload?: boolean;
+
   /**
    * @internal Handler-layer liveness observed DURING a shell capture, from
    * three sources: (a) the capture handle-store push wrapper (shell-capture.ts)
@@ -575,6 +588,7 @@ export type PublicRequestContext<
   | "_transitionWhen"
   | "_cacheStore"
   | "_shellCaptureRun"
+  | "_shellFragmentPayload"
   | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
@@ -1105,10 +1119,56 @@ export function createRequestContext<TEnv>(
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };
 
-  // Lazy allocation: only create Promise when a loader calls rendered().
+  wireRenderBarrier(ctx, handleStore);
+
+  ctx.use = createUseFunction({
+    handleStore,
+    loaderPromises,
+    getContext: () => ctx,
+  });
+
+  (ctx as any)[NOCACHE_SYMBOL] = true;
+  return ctx;
+}
+
+/**
+ * Wire a fresh render barrier onto `ctx`, closure-bound to THIS ctx and THIS
+ * handle store. Called by createRequestContext for every fresh context, and by
+ * deriveShellCaptureContext (rsc/shell-capture.ts) for the PPR capture's
+ * derived context.
+ *
+ * The derived-context call is load-bearing (issue #684, plan 009): the capture
+ * context is `Object.create(reqCtx)`, so without its own wiring every
+ * `_renderBarrier*` read fell through the prototype to the FOREGROUND
+ * request's barrier — whose getter and resolver are closure-bound to the
+ * foreground ctx and its handle store, and whose resolver no-ops once
+ * resolved. A bake-lane loader's `await ctx.rendered()` during capture then
+ * resolved instantly against the foreground's barrier and `ctx.use(handle)`
+ * read the foreground's handle snapshot; the capture's fresh `_handleStore`
+ * was invisible, so foreground per-request handle data could bake into the
+ * shared shell.
+ */
+export function wireRenderBarrier(
+  ctx: RequestContext<any, any>,
+  handleStore: HandleStore,
+): void {
+  // Reset the whole barrier family as OWN properties. No-op for a fresh
+  // context; for the derived capture context this shadows the foreground's
+  // resolved state so the capture runs its own barrier lifecycle. In
+  // particular _treeHasStreaming must be recomputed for the CAPTURE's tree
+  // (cache-lookup/segment-resolution only set it when undefined): an
+  // inherited `true` made a capture-lane rendered() seal the capture's fresh
+  // store at loader start and pair it with the foreground's segment order.
+  ctx._renderBarrierSegmentOrder = undefined;
+  ctx._renderBarrierWaiters = undefined;
+  ctx._renderBarrierHandleSnapshot = undefined;
+  ctx._renderBarrierGuardClosed = undefined;
+  ctx._handlerLoaderDeps = undefined;
+  ctx._treeHasStreaming = undefined;
+
+  // Lazy allocation: only create the Promise when a loader calls rendered().
   let barrierResolved = false;
   let resolveBarrier: (() => void) | undefined;
-  ctx._renderBarrier = null as any;
   ctx._resolveRenderBarrier = (
     segments: Array<{ type: string; id: string }>,
   ) => {
@@ -1136,6 +1196,9 @@ export function createRequestContext<TEnv>(
     }
     if (resolveBarrier) resolveBarrier();
   };
+  // defineProperty, not assignment: on a derived context the prototype's
+  // _renderBarrier may already be a non-writable data property (the getter
+  // pins it after first access), which would reject a plain assignment.
   Object.defineProperty(ctx, "_renderBarrier", {
     get() {
       const p = barrierResolved
@@ -1152,15 +1215,6 @@ export function createRequestContext<TEnv>(
     },
     configurable: true,
   });
-
-  ctx.use = createUseFunction({
-    handleStore,
-    loaderPromises,
-    getContext: () => ctx,
-  });
-
-  (ctx as any)[NOCACHE_SYMBOL] = true;
-  return ctx;
 }
 
 // Capture the Max-Age value so it can be parsed numerically. A leading zero

package/src/ssr/index.tsx

@@ -201,13 +201,16 @@ const DEFAULT_SHELL_CAPTURE_MAX_WAIT_MS = 5000;
  * 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. Under
- * replay, Flight-quiet fires BEFORE the fizz side has consumed the instant payload
- * and rendered the shell to `<body>`, so the fizz needs a real buffer of turns after
- * quiesce — otherwise the abort lands on an unrendered tree (empty prelude, root
- * postpone) and the sanity gate refuses. Still task-based (masked loaders never
- * emit, so more hops never lets a hole settle); a cold worker whose first
- * attempt still under-renders heals on the in-place retry. Bounded by maxWaitMs.
+ * 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.
  */
 const POST_QUIESCE_TASK_HOPS = 16;
 
@@ -517,9 +520,18 @@ export function createShellCaptureHandler<TEnv = unknown>(
     const deadline = createCancelableTimeout(maxWaitMs);
     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.
+      let settlePayload!: () => void;
+      const payloadSettled = new Promise<void>((resolve) => {
+        settlePayload = resolve;
+      });
       const SsrRoot = createSsrRootComponent({
         createFromReadableStream,
         rscStream,
+        onPayloadSettled: settlePayload,
       });
 
       // Bootstrap load raced against the deadline. A load that never resolves
@@ -588,10 +600,36 @@ export function createShellCaptureHandler<TEnv = unknown>(
       // 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]);
+      // 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
+      // 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.
+      const prerenderSettled = prerenderPromise.then(
+        () => {},
+        () => {},
+      );
+      await Promise.race([payloadSettled, 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), so a
-      // fixed count of turns suffices — no wall-clock.
+      // rather than errored. Deterministic (the byte set is already frozen and
+      // the payload is settled), so a fixed count of turns suffices — no
+      // wall-clock. Ready-but-queued fizz render work (however large — a multi-MB
+      // outlined boundary) can never lose this race: tracked-postpones pings run
+      // on scheduleMicrotask, so every runnable task drains before the FIRST
+      // setTimeout hop fires; only tasks parked on genuinely pending promises
+      // (masked loaders, real per-request I/O) remain, and those are exactly the
+      // holes that must postpone (issue #702).
       for (let i = 0; i < POST_QUIESCE_TASK_HOPS; i++) {
         await macrotask();
       }

package/src/ssr/ssr-root.tsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { expandSegmentFragments } from "../segment-fragments.js";
 import { renderSegments } from "../segment-system.js";
 import {
   filterSegmentOrder,
@@ -128,6 +129,18 @@ export interface SsrRootOptions {
   rscStream: ReadableStream<Uint8Array>;
   /** Nonce for CSP; propagated to NonceContext. */
   nonce?: string;
+  /**
+   * Fires once when the Flight payload root settles (resolve OR reject) — the
+   * signal that every client-module load the payload references completed and
+   * fizz can start emitting the tree. The capture pass gates its abort on
+   * this: a fully REPLAYED (prerendered) route's Flight stream goes
+   * byte-quiet in ~1-3ms, but fizz cannot render even <html> until the
+   * module loads finish (real module-runner I/O in dev; 100ms+ on a cold
+   * graph), so an abort gated on Flight quiet alone fires first and freezes
+   * a zero-byte prelude. Masked-loader holes do NOT block this signal —
+   * they postpone below the root.
+   */
+  onPayloadSettled?: () => void;
 }
 
 /**
@@ -148,7 +161,7 @@ export interface SsrRootOptions {
  * re-running the whole segment-tree build unless the promise is memoized.
  */
 export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
-  const { createFromReadableStream, rscStream, nonce } = opts;
+  const { createFromReadableStream, rscStream, nonce, onPayloadSettled } = opts;
 
   let payload: Promise<RscPayload> | undefined;
   let handlesPromise: Promise<HandleData> | undefined;
@@ -156,7 +169,27 @@ export function createSsrRootComponent(opts: SsrRootOptions): React.FC {
   let rootPromise: Promise<React.ReactNode> | undefined;
 
   return function SsrRoot() {
-    payload ??= createFromReadableStream<RscPayload>(rscStream);
+    if (payload === undefined) {
+      // Shell-HIT tails carry replayed segments as VERBATIM stored fragments
+      // (segment-fragments.ts, issue #700); expand them through this
+      // environment's deserializer before anything reads the segments. Every
+      // other payload (full render, capture, actions) has no envelopes and
+      // pays one field scan. onPayloadSettled fires AFTER expansion: the
+      // capture's fizz-readiness gate must include fragment module loads.
+      // Promise.resolve() adoption is load-bearing: some wirings (the build
+      // temp server's vendored Flight client) return a THENABLE Chunk whose
+      // .then returns undefined — chaining on it directly yields undefined.
+      payload = Promise.resolve(
+        createFromReadableStream<RscPayload>(rscStream),
+      ).then(async (resolvedPayload) => {
+        await expandSegmentFragments(
+          resolvedPayload.metadata?.segments,
+          createFromReadableStream,
+        );
+        return resolvedPayload;
+      });
+      if (onPayloadSettled) payload.then(onPayloadSettled, onPayloadSettled);
+    }
     const resolved = React.use(payload);
 
     const themeConfig = resolved.metadata?.themeConfig ?? null;

package/src/urls/pattern-types.ts

@@ -62,6 +62,33 @@ export interface PartialPrerenderProps {
    * capture render auto-collects (the shell's own non-loader request tags).
    */
   tags?: string[];
+  /**
+   * Upper bound (serialized UTF-8 bytes) on the capture data snapshot riding
+   * inside the shell entry. The snapshot duplicates every cache-store value
+   * the capture pinned, so a page over a large cache() segment can push the
+   * entry toward store value limits (Cloudflare KV caps a value at 25 MiB).
+   * Over the cap the snapshot is skipped: the shell is still stored and
+   * served, but pinned reads fall back to the live store, so drifted cached
+   * content can hydration-mismatch and be repaired client-side (the
+   * pre-snapshot behavior). Reported once per key. Defaults to 8 MiB.
+   */
+  maxSnapshotBytes?: number;
+  /**
+   * Capture settle budget in MILLISECONDS (default 5000). Bounds the whole
+   * background capture: the wait for deferred shell material — top-level
+   * pushed handle promises (`ctx.use(Meta)(promise.then(...))` and friends)
+   * are AWAITED and their settled values baked into the stored shell — AND
+   * the fizz prerender deadline. Declare it when a route's shell material
+   * takes longer than 5s to settle. A budget that expires with pushes still
+   * pending REFUSES the capture (the route stays MISS with the once-per-key
+   * warning) — a shell with missing head material is never stored. Capture
+   * is background work (waitUntil), so a longer budget costs latency-to-HIT
+   * only, never a served response; the platform waitUntil lifetime (workerd:
+   * ~30s past response completion) is the physical ceiling. Build-time
+   * captures (Prerender+ppr, producer B) honor the same budget with no
+   * platform ceiling. Non-finite or sub-1ms values fall back to the default.
+   */
+  captureTimeout?: number;
 }
 
 export interface PathOptions<

package/src/vite/discovery/discover-routers.ts

@@ -381,6 +381,33 @@ export async function discoverRouters(
   state.perRouterTrieMap = newPerRouterTrieMap;
   state.mergedRouteTrie = newMergedRouteTrie;
 
+  // Install the route tries into the RSC realm BEFORE prerender collection.
+  // matchForPrerender resolves each enumerated URL via findMatch, and without
+  // a trie findMatch silently falls back to the insertion-order regex matcher
+  // — a root `path("/*")` declared before a nested static route then wins the
+  // match, and the artifact bakes the CATCH-ALL page under `catchAll/<hash>`
+  // while runtime (trie-ranked: wildcard last) matches the real route and
+  // misses the manifest — wrong-content bake for plain Prerender routes, a
+  // guaranteed 404 once handler eviction runs. Dev never hits this because
+  // propagateDiscoveryState (router-discovery.ts) pushes the same setters on
+  // every discovery/HMR pass; configureServer early-returns in build mode, so
+  // collection was the one findMatch consumer running trieless. Mirrors the
+  // dev perRouterSetters loop; deliberately does NOT markRouterTrieAuthoritative
+  // so a genuine trie gap keeps the regex fallback, exactly as in dev.
+  if (serverMod.setRouteTrie && newMergedRouteTrie) {
+    serverMod.setRouteTrie(newMergedRouteTrie);
+  }
+  const perRouterSetters: Array<[Map<string, unknown>, string]> = [
+    [newPerRouterManifestDataMap, "setRouterManifest"],
+    [newPerRouterTrieMap, "setRouterTrie"],
+    [newPerRouterPrecomputedMap, "setRouterPrecomputedEntries"],
+  ];
+  for (const [map, fn] of perRouterSetters) {
+    const setter = serverMod[fn];
+    if (typeof setter !== "function") continue;
+    for (const [routerId, value] of map) setter(routerId, value);
+  }
+
   // Expand prerender routes and render static handlers (build mode only)
   await expandPrerenderRoutes(state, rscEnv, registry, allManifests);
   await renderStaticHandlers(state, rscEnv, registry);

package/src/vite/discovery/prerender-collection.ts

@@ -281,6 +281,22 @@ export async function expandPrerenderRoutes(
               "__pr",
               mainValue,
             );
+            // Prerender + ppr composition: flag the URL as a build-time shell
+            // candidate for the post-build capture phase (producer B, #699).
+            // The payload JSON is retained in memory so that phase can seed an
+            // in-realm prerender store the capture's match() will HIT.
+            if (result.ppr !== undefined && result.ppr !== false) {
+              (state.shellCandidates ??= []).push({
+                urlPath: entry.urlPath,
+                routeName: result.routeName,
+                paramHash,
+                ppr: result.ppr === true ? true : result.ppr,
+              });
+              (state.prerenderPayloadValues ??= new Map()).set(
+                mainKey,
+                mainValue,
+              );
+            }
             if (result.interceptSegments?.length) {
               const interceptKey = `${result.routeName}/${paramHash}/i`;
               const interceptValue = JSON.stringify({