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

package/src/rsc/shell-capture.ts

@@ -28,7 +28,11 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { createHandleStore, type HandleStore } from "../server/handle-store.js";
-import { maskNestedContainerThenables } from "../router/segment-resolution/mask-nested.js";
+import {
+  maskNestedContainerThenables,
+  type MaskReport,
+} from "../router/segment-resolution/mask-nested.js";
+import { isInsideLoaderScope } from "../server/context.js";
 import { isThenable } from "../handles/is-thenable.js";
 import type {
   ShellCacheEntry,
@@ -41,6 +45,7 @@ import {
 } from "../router/segment-resolution/loader-snapshot.js";
 import {
   RecordingShellStore,
+  SnapshotOnlySegmentStore,
   getRecordingStore,
 } from "../cache/shell-snapshot.js";
 import type { HandlerContext } from "./handler-context.js";
@@ -701,6 +706,18 @@ async function runShellCapture(
   return "no-shell";
 }
 
+/** Fold the capture's handle-liveness record into the entry flag (true | undefined). */
+function handlerLayerIsLive(
+  liveness: RequestContext["_shellCaptureHandleLiveness"],
+): true | undefined {
+  if (!liveness) return undefined;
+  return liveness.holes ||
+    liveness.pendingPushes > 0 ||
+    liveness.handlerInvokedLoader
+    ? true
+    : undefined;
+}
+
 /**
  * One capture attempt in a DERIVED request context.
  *
@@ -764,21 +781,74 @@ async function attemptCapture(
   // the store exists only for this capture attempt, so every push wrapper
   // (setupLoaderAccess, createUseFunction, prerender) inherits the policy and
   // the foreground store is untouched.
+  // Shell fast path bookkeeping on the same funnel:
+  //  - handleLiveness: a nested thenable in a push made OUTSIDE a DSL loader
+  //    scope (attribution read synchronously at push time — handler bodies,
+  //    handler-invoked ctx.use(loader) callbacks, defers) declares
+  //    handler-layer per-request data. Its mask is a hole only a handler
+  //    re-run can fill, so the entry must not serve handler-free
+  //    (ShellCacheEntry.handlerLiveHoles). Still-pending top-level handler
+  //    pushes at the putShell barrier count too — their liveness is unknowable.
+  //  - loaderScopedPushValues: DSL-loader pushes re-run fresh on every HIT, so
+  //    their captured values must NOT enter a segment record's handle snapshot
+  //    (replay would duplicate the fresh push, and their masked nested
+  //    promises would stall the Flight handle encode to its timeout). The set
+  //    rides the derived context (_shellCaptureLoaderHandleValues) and is
+  //    applied ONLY at the captureHandles cache-write call site — every other
+  //    getDataForSegment consumer (the render-barrier snapshot, prerender)
+  //    sees every push.
+  const handleLiveness = {
+    holes: false,
+    pendingPushes: 0,
+    handlerInvokedLoader: false,
+  };
+  const loaderScopedPushValues = new WeakSet<object>();
   const rawCapturePush = freshHandleStore.push.bind(freshHandleStore);
   freshHandleStore.push = (
     handleName: string,
     segmentId: string,
     value: unknown,
   ) => {
-    const masked = isThenable(value)
-      ? value.then((v: unknown) => maskNestedContainerThenables(v))
-      : maskNestedContainerThenables(value);
+    const pushedInLoaderScope = isInsideLoaderScope();
+    // Single walk: the mask reports whether it masked any nested thenable
+    // (the liveness declaration) while building the capture copy.
+    const maskWithLiveness = (v: unknown): unknown => {
+      const report: MaskReport = { thenable: false };
+      const masked = maskNestedContainerThenables(v, undefined, report);
+      if (!pushedInLoaderScope && report.thenable) {
+        handleLiveness.holes = true;
+      }
+      return masked;
+    };
+    let masked: unknown;
+    if (isThenable(value)) {
+      if (!pushedInLoaderScope) {
+        handleLiveness.pendingPushes++;
+        const settle = () => handleLiveness.pendingPushes--;
+        value.then(settle, settle);
+      }
+      masked = value.then(maskWithLiveness);
+    } else {
+      masked = maskWithLiveness(value);
+    }
+    if (pushedInLoaderScope && typeof masked === "object" && masked !== null) {
+      loaderScopedPushValues.add(masked);
+    }
     rawCapturePush(handleName, segmentId, masked);
   };
 
   const derivedCtx: RequestContext = Object.create(reqCtx);
   derivedCtx._handleStore = freshHandleStore;
+  derivedCtx._shellCaptureLoaderHandleValues = loaderScopedPushValues;
   derivedCtx._requestTags = new Set<string>();
+  // Own explicit-store registry: cache-store resolutions during the capture
+  // (the implicit scope's SnapshotOnlySegmentStore, any per-capture explicit
+  // store instance) must NOT register into the handler-lifetime
+  // _explicitTaggedStores set — a capture-ephemeral store pinned there would
+  // trip the partial-tag-store warning on every later updateTag() and retain
+  // the whole capture snapshot in memory. Capture registrations die with this
+  // context; module-singleton stores stay registered by normal renders.
+  derivedCtx._explicitTaggedStores = new Set();
   derivedCtx._transitionWhen = [];
   derivedCtx._shellCaptureRun = true;
   derivedCtx._metricsStore = undefined;
@@ -812,6 +882,7 @@ async function attemptCapture(
   // forwarding to the parent so the write persists and the worker stays alive),
   // then captureAndStoreShell awaits them before draining. Reads that HIT are
   // recorded synchronously during the render and need none of this.
+  derivedCtx._shellCaptureHandleLiveness = handleLiveness;
   if (reqCtx._cacheStore) {
     const recordingStore = new RecordingShellStore(reqCtx._cacheStore);
     derivedCtx._cacheStore = recordingStore;
@@ -820,6 +891,17 @@ async function attemptCapture(
       recordingStore.trackWrite(p);
       reqCtx.waitUntil(() => p);
     };
+    // Shell fast path (capture side): the implicit doc-cache scope makes the
+    // capture's match write ALL matched non-loader segments as one doc-keyed
+    // segment record — into the snapshot only (SnapshotOnlySegmentStore), so
+    // the record dies with the shell entry and the next capture's lookup
+    // still misses (handlers re-run on recapture). Routes deriving their own
+    // cache scope are untouched (resolveShellImplicitCacheScope).
+    derivedCtx._shellImplicitCache = {
+      ttl: descriptor.ttl,
+      swr: descriptor.swr,
+      store: new SnapshotOnlySegmentStore(recordingStore),
+    };
   }
 
   return runWithRequestContext(derivedCtx, async () => {
@@ -1142,6 +1224,14 @@ async function captureAndStoreShell(
           // ShellCacheEntry.initialTheme.
           initialTheme: reqCtx.theme,
           snapshot,
+          // Handler-layer liveness folded at the barrier: nested thenables in
+          // handler-scoped pushes, handler pushes still pending (liveness
+          // unknowable), or a handler-invoked loader execution — any of them
+          // refuses the FAST PATH, not the capture. See
+          // _shellCaptureHandleLiveness.
+          handlerLiveHoles: handlerLayerIsLive(
+            reqCtx._shellCaptureHandleLiveness,
+          ),
           createdAt: Date.now(),
         };
         await store.putShell(

package/src/segment-system.tsx

@@ -18,14 +18,20 @@ import {
 } from "./segment-loader-promise.js";
 
 /**
- * Client-only debug log for the segment tree build. Gated on the baked flag
- * AND `typeof window` (renderSegments also runs during SSR/RSC, which must
- * stay silent). Timestamped so tree-build steps line up with the
- * `[Browser][boot]` sequence around hydrateRoot.
+ * Debug log for the segment tree build, gated on the baked flag. Runs on BOTH
+ * sides now, environment-tagged: `[Browser][segments]` lines up with the
+ * `[Browser][boot]` sequence around hydrateRoot; `[Server][segments]` exposes
+ * the SSR/RSC tree-build stalls (blocking loader awaits during fizz are what
+ * dominate MISS TTFB) that used to be invisible because the logs were
+ * window-gated. Server lines have no request correlation — segment-system is
+ * shared client code and cannot import request-context (node:async_hooks
+ * would enter the browser bundle) — so on a busy server, correlate by
+ * timestamp + segment ids.
  */
 function segDebugLog(msg: string, details?: Record<string, unknown>): void {
-  if (!(INTERNAL_RANGO_DEBUG && typeof window === "object")) return;
-  const prefix = `[Browser][segments] ${msg} @ ${Math.round(performance.now())}ms`;
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const env = typeof window === "object" ? "[Browser]" : "[Server]";
+  const prefix = `${env}[segments] ${msg} @ ${Math.round(performance.now())}ms`;
   if (details) {
     console.log(prefix, details);
     return;
@@ -228,7 +234,7 @@ export async function renderSegments(
     rootLayout: RootLayout,
   } = options || {};
 
-  const segDebug = INTERNAL_RANGO_DEBUG && typeof window === "object";
+  const segDebug = INTERNAL_RANGO_DEBUG;
   const segDebugStart = segDebug ? performance.now() : 0;
   if (segDebug) {
     segDebugLog("renderSegments start", {
@@ -299,15 +305,7 @@ export async function renderSegments(
       `Expected layout, route, error, or notFound segment, got ${node.segment.type}`,
     );
     const { component, id, params, loading } = node.segment;
-
-    if (segDebug) {
-      segDebugLog(`segment ${id}`, {
-        type: node.segment.type,
-        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
-        hasLoading: loading !== undefined && loading !== null,
-        parallel: node.parallel.map((p) => p.id),
-      });
-    }
+    const segNodeStart = segDebug ? performance.now() : 0;
 
     // Param-agnostic keys are opt-in via the transition() DSL (see
     // inTransitionScope above). A route (and its route-owned layouts) inside a
@@ -350,7 +348,13 @@ export async function renderSegments(
 
     let resolvedComponent = component;
     if (isAction && component instanceof Promise) {
+      const componentAwaitStart = segDebug ? performance.now() : 0;
       resolvedComponent = await component;
+      if (segDebug) {
+        segDebugLog(`segment ${id}: component awaited (action)`, {
+          ms: Math.round(performance.now() - componentAwaitStart),
+        });
+      }
     }
 
     let nodeContent: ReactNode = null;
@@ -367,9 +371,16 @@ export async function renderSegments(
       // suspends on mount inside the content still reveals a fallback (it is not
       // pre-resolved).
       const contentPromise = getMemoizedContentPromise(resolvedComponent);
-      const loadingContent: Promise<ReactNode> | ReactNode = forceAwait
-        ? await contentPromise
-        : contentPromise;
+      let loadingContent: Promise<ReactNode> | ReactNode = contentPromise;
+      if (forceAwait) {
+        const contentAwaitStart = segDebug ? performance.now() : 0;
+        loadingContent = await contentPromise;
+        if (segDebug) {
+          segDebugLog(`segment ${id}: content awaited (forceAwait)`, {
+            ms: Math.round(performance.now() - contentAwaitStart),
+          });
+        }
+      }
       nodeContent = createElement(RouteContentWrapper, {
         key: `suspense-loading-${id}`,
         content: loadingContent,
@@ -492,10 +503,19 @@ export async function renderSegments(
           ms: Math.round(performance.now() - layoutAwaitStart),
         });
       }
+      const decodeStart = segDebug ? performance.now() : 0;
       const { loaderData, errorFallback } = decodeLoaderResults(
         resolvedData,
         layoutLoaderIds,
       );
+      if (segDebug) {
+        const decodeMs = Math.round(performance.now() - decodeStart);
+        if (decodeMs > 0) {
+          segDebugLog(`segment ${id}: loader results decoded`, {
+            ms: decodeMs,
+          });
+        }
+      }
 
       if (parallelOwnedLoaders.length > 0) {
         const loadersByParallelNamespace = new Map<string, ResolvedSegment[]>();
@@ -568,6 +588,16 @@ export async function renderSegments(
         children: content,
       });
     }
+
+    if (segDebug) {
+      segDebugLog(`segment ${id} built`, {
+        type: node.segment.type,
+        ms: Math.round(performance.now() - segNodeStart),
+        loaders: node.loaders.map((l) => l.loaderId).filter(Boolean),
+        hasLoading: loading !== undefined && loading !== null,
+        parallel: node.parallel.map((p) => p.id),
+      });
+    }
   }
 
   const errorBoundaryWrapped = createElement(RootErrorBoundary, {

package/src/server/request-context.ts

@@ -210,6 +210,53 @@ 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 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

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.
@@ -326,6 +343,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 +441,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
@@ -490,7 +552,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.
@@ -637,11 +699,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 +706,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/vite/index.ts

@@ -24,6 +24,7 @@ export type {
   RangoOptions,
   ClientChunks,
   ClientChunkMeta,
+  HeadScriptsOption,
   BuildEnvOption,
   BuildEnvFactory,
   BuildEnvFactoryContext,