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

package/src/server/request-context.ts

@@ -210,6 +210,66 @@ export interface RequestContext<
    */
   _shellLoaderSeed?: Map<string, unknown>;
 
+  /**
+   * @internal Shell fast-path marker: makes the NEXT full match treat the whole
+   * matched route as an implicit doc-level cache() boundary (see
+   * resolveShellImplicitCacheScope in cache/cache-scope.ts). Set ONLY on
+   * (a) the capture's derived context — with a record-only store so the
+   * capture's cacheRoute write lands in the snapshot, never the real store —
+   * and (b) a HIT tail's seeded context when the entry is eligible
+   * (!handlerLiveHoles), where the SeededShellStore serves the recorded doc
+   * entry and the match skips handler execution entirely. Routes with their
+   * own cache() config (including cache(false)) are never overridden: the
+   * marker only applies when the route tree derived NO cache scope.
+   */
+  _shellImplicitCache?: {
+    ttl?: number;
+    swr?: number;
+    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)
+   * when a push made OUTSIDE a DSL loader scope carries a nested thenable
+   * (masked to a never-filling hole); (b) still-pending top-level handler
+   * pushes (liveness unknowable at the barrier); (c) a handler-invoked loader
+   * executing during the capture (loader-resolution.ts — its consumption-lane
+   * value would freeze on a handler-free HIT). captureAndStoreShell folds it
+   * into ShellCacheEntry.handlerLiveHoles at the putShell barrier. Own
+   * property of the capture's derived context only.
+   */
+  _shellCaptureHandleLiveness?: {
+    holes: boolean;
+    pendingPushes: number;
+    handlerInvokedLoader: boolean;
+  };
+
+  /**
+   * @internal Handle values pushed from a DSL loader scope DURING a shell
+   * capture (identity set; populated by the capture push wrapper in
+   * shell-capture.ts). cacheRoute threads it into captureHandles so those
+   * values stay out of cache-write handle records — loaders re-run fresh on
+   * every HIT, so replaying their captured (masked) values would duplicate
+   * the fresh push and stall the Flight handle encode. Own property of the
+   * capture's derived context only; render-time handle consumers are
+   * unaffected (the exclusion applies only at the captureHandles call site).
+   */
+  _shellCaptureLoaderHandleValues?: WeakSet<object>;
+
   /**
    * @internal Set (to the offending fn name) by the cookies()/headers()
    * capture guard when it throws DURING a capture render. Load-bearing for the
@@ -528,6 +588,7 @@ export type PublicRequestContext<
   | "_transitionWhen"
   | "_cacheStore"
   | "_shellCaptureRun"
+  | "_shellFragmentPayload"
   | "_shellCaptureGuardTrippedLoaderId"
   | "_explicitTaggedStores"
   | "_requestTags"
@@ -1058,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 }>,
   ) => {
@@ -1089,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
@@ -1105,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

@@ -1,7 +1,11 @@
 import React from "react";
 import { createSsrRootComponent } from "./ssr-root.js";
 import { injectRSCPayloadEager } from "./inject-rsc-eager.js";
+import { runWithPreinitNonce } from "./preinit-client-references.js";
 import type { ErrorPhase } from "../types.js";
+import type { HeadScriptsOption } from "../vite/plugin-types.js";
+
+export { installClientReferencePreinit } from "./preinit-client-references.js";
 
 /**
  * Options for injectRSCPayload
@@ -18,6 +22,7 @@ export interface InjectRSCPayloadOptions {
  */
 interface RenderToReadableStreamOptions {
   bootstrapScriptContent?: string;
+  bootstrapModules?: string[];
   nonce?: string;
   formState?: unknown;
 }
@@ -35,6 +40,7 @@ interface ReactDOMReadableStream extends ReadableStream<Uint8Array> {
 interface PrerenderOptions {
   signal?: AbortSignal;
   bootstrapScriptContent?: string;
+  bootstrapModules?: string[];
   onError?: (error: unknown) => void;
 }
 
@@ -133,6 +139,17 @@ export interface SSRDependencies<TEnv = unknown> {
    */
   loadBootstrapScriptContent: () => Promise<string>;
 
+  /**
+   * Document script strategy; the generated virtual SSR entry threads the
+   * `rango({ headScripts })` plugin option here (canonical docs on
+   * `RangoBaseOptions.headScripts` in vite/plugin-types.ts). The
+   * bootstrapModules conversion runs ONLY on an explicit `"preinit"`:
+   * undefined keeps the inline bootstrap verbatim, so a custom SSR entry that
+   * never installed the preinit hook cannot drift into the half-converted
+   * state on upgrade (the generated entry always passes an explicit value).
+   */
+  headScripts?: HeadScriptsOption;
+
   /**
    * prerender from react-dom/static.edge. Optional; required only by
    * {@link createShellCaptureHandler} for PPR shell capture.
@@ -184,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;
 
@@ -326,6 +346,47 @@ interface ShellResumeOptions {
   nonce?: string;
 }
 
+/**
+ * The exact shape plugin-rsc's loadBootstrapScriptContent returns in both dev
+ * and build: a single dynamic import of the browser entry, nothing else.
+ * Escapes/other statements never appear in that generated content; anything
+ * that doesn't match falls back to inline bootstrapScriptContent unchanged.
+ */
+const BOOTSTRAP_IMPORT_ONLY_RE =
+  /^\s*import\(\s*(["'])([^"'\\]+)\1\s*\)\s*;?\s*$/;
+
+/**
+ * Prefer bootstrapModules over the inline import() bootstrap. When the content
+ * is exactly `import("<entry-url>")`, hand Fizz the URL instead: React then
+ * emits a `<link rel="modulepreload" fetchpriority="low">` hint in the head
+ * plus the executing `<script type="module" src async>` at end of shell — the
+ * entry fetch starts with the first flushed bytes instead of when the parser
+ * reaches an opaque inline script that only reveals the URL once executed.
+ * Fizz stamps the request nonce on both tags (the inline form needed that
+ * too), and under PPR both land in the stored prelude; on resume React has
+ * already cleared the bootstrap fields from the postponed state, so nothing
+ * re-emits.
+ */
+function resolveBootstrapOptions(
+  content: string,
+  headScripts: SSRDependencies["headScripts"],
+): Pick<
+  RenderToReadableStreamOptions,
+  "bootstrapScriptContent" | "bootstrapModules"
+> {
+  // Explicit opt-in only: undefined (a custom SSR entry that predates the
+  // option, which also never installed the preinit hook) keeps the inline
+  // bootstrap byte-for-byte — converting by default would break CSPs that
+  // allowlist the known inline import() via a script hash.
+  if (headScripts !== "preinit") {
+    return { bootstrapScriptContent: content };
+  }
+  const match = BOOTSTRAP_IMPORT_ONLY_RE.exec(content);
+  return match
+    ? { bootstrapModules: [match[2]!] }
+    : { bootstrapScriptContent: content };
+}
+
 /**
  * Create an SSR handler that converts RSC streams to HTML.
  *
@@ -383,12 +444,16 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
 
       // Render React tree to HTML stream
       // Pass formState for useActionState progressive enhancement if provided
-      // Pass nonce for CSP if provided
-      const htmlStream = await renderToReadableStream(<SsrRoot />, {
-        bootstrapScriptContent,
-        formState,
-        nonce,
-      });
+      // Pass nonce for CSP if provided. runWithPreinitNonce makes the same
+      // nonce visible to the client-reference preinit hook (ALS — the hook is
+      // isolate-global, the nonce per request).
+      const htmlStream = await runWithPreinitNonce(nonce, () =>
+        renderToReadableStream(<SsrRoot />, {
+          ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+          formState,
+          nonce,
+        }),
+      );
 
       // Wait for all Suspense boundaries to resolve when streamMode is "allReady".
       // This buffers the entire HTML before flushing — used for bots that
@@ -455,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
@@ -490,7 +564,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
       const abortReason = { rangoShellCaptureAbort: true };
       const prerenderPromise = prerender(<SsrRoot />, {
         signal: controller.signal,
-        bootstrapScriptContent,
+        ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
         // Abort is how capture WORKS: once the shell is quiet we abort() to
         // freeze the prelude and let the still-pending holes postpone. React
         // reports the abort reason for each pending boundary through onError.
@@ -526,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();
       }
@@ -637,11 +737,6 @@ export function createShellResumeHandler<TEnv = unknown>(
         nonce,
       });
 
-      const resumed = await resume(<SsrRoot />, JSON.parse(postponed), {
-        onError: (error) => reportRenderError(onError, error),
-        nonce,
-      });
-
       // EAGER injection (resume-only): the stored prelude — a complete document
       // through </body></html> — is already on the wire ahead of this stream,
       // so a Flight <script> is valid as the first tail byte. The stock
@@ -649,7 +744,41 @@ export function createShellResumeHandler<TEnv = unknown>(
       // first hole's loaders resolve — parking the whole hydration payload
       // (root row included) behind the slowest live loader. See
       // inject-rsc-eager.ts for the measured failure mode.
-      return resumed.pipeThrough(injectRSCPayloadEager(rscStream2, { nonce }));
+      //
+      // EAGER HANDOVER: return the injector's readable BEFORE awaiting
+      // resume(). react-dom's resume() promise resolves only when the resumed
+      // shell (everything above the postponed holes) completes — which waits
+      // on the live loaders — so `await resume(...).pipeThrough(...)` parked
+      // the already-flowing Flight bytes a second time, behind the handshake
+      // instead of the stream (measured: injector output at +9ms, first tail
+      // byte on the wire at +735ms). Piping fizz in when it materializes lets
+      // serveShellHit start draining Flight immediately; pipeTo closes the
+      // writable on completion, which runs the injector's flush (trailer). A
+      // resume() rejection aborts the writable so the response errors instead
+      // of hanging.
+      const injector = injectRSCPayloadEager(rscStream2, { nonce });
+      void (async () => {
+        try {
+          // Nonce wrap mirrors renderHTML: client references first discovered
+          // during resume (holes the shell never rendered) preinit into the
+          // resumed stream and need the per-request nonce.
+          const resumed = await runWithPreinitNonce(nonce, () =>
+            resume(<SsrRoot />, JSON.parse(postponed), {
+              onError: (error) => reportRenderError(onError, error),
+              nonce,
+            }),
+          );
+          await resumed.pipeTo(injector.writable);
+        } catch (error) {
+          reportRenderError(onError, error);
+          try {
+            await injector.writable.abort(error);
+          } catch {
+            // Writable already errored/closed; the readable side has the error.
+          }
+        }
+      })();
+      return injector.readable;
     } catch (error) {
       reportRenderError(onError, error);
       throw error;

package/src/ssr/inject-rsc-eager.ts

@@ -81,7 +81,7 @@ export function injectRSCPayloadEager(
     if (INTERNAL_RANGO_DEBUG && !loggedFirstHtml && buffered.length > 0) {
       loggedFirstHtml = true;
       console.log(
-        `[Server][ppr] eager-inject: first resumed HTML batch +${Math.round(performance.now() - t0)}ms`,
+        `[Server][ppr] eager-inject: first resumed HTML batch +${Math.round(performance.now() - t0)}ms (abs ${Math.round(performance.now())})`,
       );
     }
     for (const chunk of buffered) {
@@ -123,7 +123,7 @@ export function injectRSCPayloadEager(
         if (INTERNAL_RANGO_DEBUG && !loggedFirstFlight) {
           loggedFirstFlight = true;
           console.log(
-            `[Server][ppr] eager-inject: first flight script +${Math.round(performance.now() - t0)}ms`,
+            `[Server][ppr] eager-inject: first flight script +${Math.round(performance.now() - t0)}ms (abs ${Math.round(performance.now())})`,
           );
         }
         writeScript(controller, jsExpr, nonce);

package/src/ssr/preinit-client-references.ts

@@ -0,0 +1,106 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { preinitModule } from "react-dom";
+
+/**
+ * JS/CSS asset deps plugin-rsc resolves for a client reference. Structural
+ * mirror of @vitejs/plugin-rsc's ResolvedAssetDeps — deliberately not imported:
+ * @rangojs/router/ssr never imports plugin-rsc directly; every plugin binding
+ * is injected by the virtual SSR entry (see SSRDependencies).
+ */
+export interface ClientReferenceDeps {
+  js: string[];
+  css: string[];
+}
+
+/**
+ * Callback shape of @vitejs/plugin-rsc/ssr's setOnClientReference. Fired
+ * (synchronously, inside the Fizz render) whenever a client reference module
+ * is accessed during SSR — the same moment plugin-rsc issues its own
+ * ReactDOM.preloadModule calls for the reference's chunks.
+ */
+export type OnClientReference = (reference: {
+  id: string;
+  deps: ClientReferenceDeps;
+}) => void;
+
+/** setOnClientReference from @vitejs/plugin-rsc/ssr (injected). */
+export type SetOnClientReference = (
+  callback: OnClientReference | undefined,
+) => void;
+
+/**
+ * Per-request CSP nonce channel for the preinit hook. The hook is installed
+ * once per isolate while the nonce is per request, and Fizz interleaves
+ * concurrent renders at task granularity — a module-scoped variable would race
+ * across requests and stamp request A's scripts with request B's nonce. ALS is
+ * the only channel that survives from the render call into the client-reference
+ * proxy access. A lost context degrades to nonce-less preinit (CSP blocks the
+ * head script; hydration still works through the nonce'd bootstrap), never to a
+ * wrong nonce.
+ */
+const preinitNonceStorage = new AsyncLocalStorage<string | undefined>();
+
+/**
+ * Run a Fizz render (renderToReadableStream / prerender / resume) with the
+ * request's nonce visible to the client-reference preinit hook. Nonce-less
+ * requests (the common non-CSP configuration) skip the ALS frame entirely —
+ * getStore() on an unentered storage already returns undefined, so the hook
+ * reads the same value either way.
+ */
+export function runWithPreinitNonce<T>(
+  nonce: string | undefined,
+  fn: () => T,
+): T {
+  return nonce === undefined ? fn() : preinitNonceStorage.run(nonce, fn);
+}
+
+/**
+ * Upgrade plugin-rsc's client-reference modulepreload hints to executing
+ * scripts: for every JS chunk a client reference needs, emit
+ * `<script type="module" src async>` hoisted into the document head instead of
+ * only `<link rel="modulepreload">`.
+ *
+ * Why: modulepreload fetches + compiles but never executes; the chunks then
+ * execute only when the entry's hydration import walks the graph — after the
+ * whole document has streamed. preinitModule starts execution as soon as each
+ * chunk arrives, overlapping it with body streaming (the pattern Next.js uses
+ * via ReactDOM.preinit for all non-bootstrap chunks). Under PPR the preinits
+ * run during shell capture, so the executing tags live in the stored prelude
+ * and chunk execution starts on the first flushed bytes.
+ *
+ * No duplicate tags: plugin-rsc's preloadModule fires first in the same
+ * synchronous block; Fizz's preinitModuleScript then clears the queued preload
+ * chunks for that URL and adopts its credentials (ReactFizzConfigDOM,
+ * renderState.preloads.moduleScripts). Capture→resume double-emission is
+ * prevented the same way: the `moduleScriptResources[src] = null` markers
+ * serialize inside the postponed state, so the resume pass preinits only
+ * references the shell never saw.
+ *
+ * crossOrigin "" matches plugin-rsc's preloadModule creds so the upgrade path
+ * reuses the same resource instead of forking on credential mismatch.
+ *
+ * Known trades (deliberate, measured neutral-to-positive on the e2e apps —
+ * PR #694 has the Lighthouse/hydration numbers):
+ * - Fetch priority: an executing async module script fetches at Chromium's
+ *   async-script priority, below a bare modulepreload hint; preinitModule
+ *   forwards no fetchPriority (react-dom's public API drops it — only
+ *   `preinit` forwards it). Execution-overlap is bought with hint priority,
+ *   the same trade Next.js ships via ReactDOM.preinit.
+ * - Build only: plugin-rsc's dev load path reports `js: []` per reference, so
+ *   dev documents have no head chunk scripts — a client module whose module
+ *   scope assumes body-parsed DOM can break in production only. The
+ *   `rango({ headScripts: "preload" })` escape hatch restores hint-only.
+ * - plugin-rsc's setOnClientReference is a single-slot, last-write-wins
+ *   setter: another registrant in the SSR environment silently replaces this
+ *   hook (or is replaced by it). No composition API exists upstream yet.
+ */
+export function installClientReferencePreinit(
+  setOnClientReference: SetOnClientReference,
+): void {
+  setOnClientReference(({ deps }) => {
+    const nonce = preinitNonceStorage.getStore();
+    for (const href of deps.js) {
+      preinitModule(href, { as: "script", crossOrigin: "", nonce });
+    }
+  });
+}

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