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

package/src/rsc/shell-capture.ts

@@ -20,10 +20,12 @@ import React from "react";
 import { bufferToBase64 } from "../cache/cf/cf-base64.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { runBackground } from "../cache/background-task.js";
+import { enqueueSerializedCapture } from "./capture-queue.js";
 import { observePhase, PHASES } from "../router/instrument.js";
 import {
   runWithRequestContext,
   setRequestContextParams,
+  wireRenderBarrier,
   UNTRACKED_BACKGROUND_TASK,
   type RequestContext,
 } from "../server/request-context.js";
@@ -604,14 +606,20 @@ export function scheduleShellCapture(
       inFlightCaptures.delete(key);
     }
   };
+  // Serialize capture EXECUTION per isolate (capture-queue.ts): concurrent
+  // captures starve each other's task-quantized quiet windows — one grinding
+  // capture makes the sibling freeze a trivial prelude and store nothing
+  // (rotating eternal-MISS victims on GH runners). The stampede guard above
+  // stays per-key (dedupe while queued); the queue is cross-key.
+  const serializedTask = () => enqueueSerializedCapture(captureTask);
   // The capture's own task must NOT enter reqCtx._pendingBackgroundTasks: the
   // capture drains that list before rendering (the write-barrier ordering edge),
   // and awaiting its own still-running promise would burn the whole barrier
   // deadline on every capture.
-  (captureTask as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
+  (serializedTask as { [UNTRACKED_BACKGROUND_TASK]?: boolean })[
     UNTRACKED_BACKGROUND_TASK
   ] = true;
-  runBackground(reqCtx, captureTask);
+  runBackground(reqCtx, serializedTask);
 }
 
 /**
@@ -737,6 +745,9 @@ function handlerLayerIsLive(
  *   - _shellCaptureRun: true — the switch loaders/cookies/headers guards read.
  *   - _metricsStore: undefined so the capture never appends to the foreground's
  *     (already-finalized) metrics.
+ *   - _renderBarrier family: an own barrier wired to the fresh handle store
+ *     (wireRenderBarrier), plus _treeHasStreaming/deadlock-guard resets — the
+ *     capture's rendered() lifecycle is its own, not the foreground's.
  *
  * The capture is MIXED-CHAIN: its match() behaves like a normal render with
  * respect to the segment cache — cache()'d segments replay from ring 3, UNCACHED
@@ -768,6 +779,74 @@ async function attemptCapture(
   // attempt (the retry re-checks; already-settled promises are free).
   await settleTrackedBackgroundTasks(reqCtx, SHELL_CAPTURE_WRITE_BARRIER_MS);
 
+  const { derivedCtx, freshHandleStore } = deriveShellCaptureContext(
+    reqCtx,
+    descriptor,
+  );
+
+  return runWithRequestContext(derivedCtx, async () => {
+    const match = await ctx.router.match(request, { env });
+    // A route that redirects has no shell to capture — bail (no store write, no
+    // retry: a redirect is deterministic).
+    if (match.redirect) return "redirect";
+
+    setRequestContextParams(match.params, match.routeName);
+
+    const payload = buildFullPayload(
+      match,
+      ctx,
+      url,
+      derivedCtx,
+      freshHandleStore,
+    );
+    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
+      onError: (error: unknown) => {
+        ctx.callOnError(error, "rendering", { request, url, env });
+      },
+    });
+
+    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
+    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
+    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
+    // content (and tags propagated by async cache()/"use cache" reads) lands after
+    // this synchronous construction point, so snapshotting here dropped it — the
+    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
+    return captureAndStoreShell(
+      ssrModule,
+      rscStream,
+      freshHandleStore,
+      derivedCtx,
+      descriptor,
+    );
+  });
+}
+
+/**
+ * The derived capture context and its fresh (mask-funneled) handle store,
+ * shared by BOTH shell producers: the runtime background capture
+ * (attemptCapture, producer A) and the build-time prerender shell capture
+ * (prerender/build-shell-capture.ts, producer B — issue #699). One
+ * implementation so the capture semantics — the nested-thenable mask funnel,
+ * handler-liveness bookkeeping, snapshot recording, the implicit doc-cache
+ * scope — cannot drift between producers.
+ */
+export interface CaptureContextDerivation {
+  derivedCtx: RequestContext;
+  freshHandleStore: HandleStore;
+}
+
+/**
+ * Derive the capture request context from a base context. Producer A passes
+ * the foreground request's post-middleware context (the derived context
+ * inherits its variables/env/cookie machinery through the prototype);
+ * producer B passes a synthetic build-request context created by
+ * createRequestContext over the build env, with a fresh MemorySegmentCacheStore
+ * as `_cacheStore` so the recording/snapshot machinery arms identically.
+ */
+export function deriveShellCaptureContext(
+  reqCtx: RequestContext<any>,
+  descriptor: Pick<ShellCaptureDescriptor, "ttl" | "swr">,
+): CaptureContextDerivation {
   const freshHandleStore = createHandleStore();
   freshHandleStore.onError = reqCtx._handleStore.onError;
   // Shape = liveness for handles, exactly as for bake-lane loader containers
@@ -839,6 +918,15 @@ async function attemptCapture(
 
   const derivedCtx: RequestContext = Object.create(reqCtx);
   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
+  // bake-lane loader's `await ctx.rendered()` resolved instantly and
+  // ctx.use(handle) read the FOREGROUND handle snapshot — foreground
+  // per-request handle data could bake into the shared shell. wireRenderBarrier
+  // 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
@@ -904,41 +992,7 @@ async function attemptCapture(
     };
   }
 
-  return runWithRequestContext(derivedCtx, async () => {
-    const match = await ctx.router.match(request, { env });
-    // A route that redirects has no shell to capture — bail (no store write, no
-    // retry: a redirect is deterministic).
-    if (match.redirect) return "redirect";
-
-    setRequestContextParams(match.params, match.routeName);
-
-    const payload = buildFullPayload(
-      match,
-      ctx,
-      url,
-      derivedCtx,
-      freshHandleStore,
-    );
-    const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
-      onError: (error: unknown) => {
-        ctx.callOnError(error, "rendering", { request, url, env });
-      },
-    });
-
-    // Pass the descriptor with its STATIC ppr.tags unchanged. The shell's own
-    // render-recorded tags are snapshotted at the putShell WRITE BARRIER inside
-    // captureAndStoreShell, not here: a tag recorded AFTER an await in async shell
-    // content (and tags propagated by async cache()/"use cache" reads) lands after
-    // this synchronous construction point, so snapshotting here dropped it — the
-    // shell-tag snapshot must sit behind the quiesce gate (issue #676).
-    return captureAndStoreShell(
-      ssrModule,
-      rscStream,
-      freshHandleStore,
-      derivedCtx,
-      descriptor,
-    );
-  });
+  return { derivedCtx, freshHandleStore };
 }
 
 /**
@@ -1262,8 +1316,15 @@ async function captureAndStoreShell(
   }
 }
 
-// Exported for unit tests that drive the capture core directly.
-export { runShellCapture, captureAndStoreShell };
+// Exported for unit tests that drive the capture core directly, and — with the
+// cold-graph retry pieces — for producer B (prerender/build-shell-capture.ts),
+// which mirrors the runtime capture's retry-in-place with the same delay.
+export {
+  runShellCapture,
+  captureAndStoreShell,
+  delay,
+  SHELL_CAPTURE_RETRY_DELAY_MS,
+};
 
 // Exported for unit tests that pin the refused-capture backoff policy directly
 // (dev cap vs production exponential growth, stored-clears, cold-start re-probe).

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/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/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({