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

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

@@ -8,6 +8,13 @@
 
 export { rango } from "./rango.js";
 export { poke } from "./plugins/refresh-cmd.js";
+// The built-in clientChunks strategy, exported so a custom `clientChunks`
+// function can OVERLAY it (route a few modules to a dedicated chunk, delegate
+// the rest) instead of replacing the whole route/marker grouping. Without this
+// a consumer override silently loses app-fallback/route splitting for the
+// entire app. Note: called without a ClientChunkContext the fallbackRefs-based
+// `app-fallback` split is inactive — discovery wires it only for the built-in.
+export { directoryClientChunks } from "./utils/client-chunks.js";
 
 export type {
   RangoNodeOptions,
@@ -17,6 +24,7 @@ export type {
   RangoOptions,
   ClientChunks,
   ClientChunkMeta,
+  HeadScriptsOption,
   BuildEnvOption,
   BuildEnvFactory,
   BuildEnvFactoryContext,

package/src/vite/plugin-types.ts

@@ -107,6 +107,11 @@ export type ClientChunks =
 
 // -- Plugin options ---------------------------------------------------------
 
+/**
+ * Document script strategy. See {@link RangoBaseOptions.headScripts}.
+ */
+export type HeadScriptsOption = "preinit" | "preload";
+
 /**
  * Base options shared by all presets
  */
@@ -126,6 +131,34 @@ interface RangoBaseOptions {
    */
   clientChunks?: ClientChunks;
 
+  /**
+   * How the document ships its JavaScript.
+   *
+   * - `"preinit"` (**default**): client-reference chunks render as EXECUTING
+   *   `<script type="module" async>` tags hoisted into `<head>` (upgrading
+   *   plugin-rsc's modulepreload hints in place), and the browser entry ships
+   *   as Fizz `bootstrapModules` — a head `modulepreload fetchpriority=low`
+   *   hint plus the executing end-of-shell `id="_R_"` module script. Chunk
+   *   execution overlaps body streaming instead of waiting for the hydration
+   *   import walk; under PPR everything lands in the stored shell prelude.
+   * - `"preload"`: the previous behavior — `<link rel="modulepreload">` hints
+   *   only, entry as an inline `import()` script at end of shell. Chunks
+   *   fetch+compile early but execute only when hydration imports them.
+   *
+   * Build-only for the chunk half: plugin-rsc resolves no JS deps per client
+   * reference in dev, so dev documents carry no head chunk scripts in either
+   * mode (the bootstrap conversion does apply in dev). Trades and upstream
+   * limits are documented in src/ssr/preinit-client-references.ts.
+   *
+   * Wired in the generated virtual SSR entry
+   * (`src/ssr/preinit-client-references.ts` has the mechanism); apps with a
+   * custom SSR entry choose per-handler via `SSRDependencies.headScripts` and
+   * `installClientReferencePreinit`.
+   *
+   * @default "preinit"
+   */
+  headScripts?: HeadScriptsOption;
+
   /**
    * Filter which files route discovery scans, by glob. Paths are matched
    * root-relative (e.g. `src/routes/**`). `include` restricts discovery to

package/src/vite/plugins/virtual-entries.ts

@@ -1,3 +1,5 @@
+import type { HeadScriptsOption } from "../plugin-types.js";
+
 export const VIRTUAL_ENTRY_BROWSER: string = `
 import {
   createFromReadableStream,
@@ -36,21 +38,49 @@ async function initializeApp() {
 initializeApp().catch(console.error);
 `.trim();
 
-export const VIRTUAL_ENTRY_SSR: string = `
-import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+/**
+ * Generate the virtual SSR entry. `headScripts` mirrors the rango() plugin
+ * option: "preinit" (default) installs the client-reference preinit hook and
+ * lets the SSR handlers convert the bootstrap to `bootstrapModules`;
+ * "preload" omits the hook and pins the handlers to the hint-only strategy.
+ */
+export function getVirtualEntrySSR(
+  headScripts: HeadScriptsOption = "preinit",
+): string {
+  const preinit = headScripts !== "preload";
+  // The preload variant drops exactly three preinit-only lines, all built
+  // here so the template below stays a single unconditional shape.
+  const depsImportNames = preinit
+    ? "createFromReadableStream,\n  setOnClientReference,"
+    : "createFromReadableStream,";
+  const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
+  const install = preinit
+    ? `
+// Upgrade client-reference modulepreload hints to executing module scripts in
+// the document head, for every render pass (live SSR, shell capture, resume).
+// See src/ssr/preinit-client-references.ts for the full rationale.
+installClientReferencePreinit(setOnClientReference);
+`
+    : "";
+  const hs = JSON.stringify(headScripts);
+  return `
+import {
+  ${depsImportNames}
+} from "@rangojs/router/internal/deps/ssr";
 import { renderToReadableStream, resume } from "react-dom/server.edge";
 import { prerender } from "react-dom/static.edge";
 import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
 import {
   createSSRHandler,
   createShellCaptureHandler,
-  createShellResumeHandler,
+  createShellResumeHandler,${ssrImportNames}
 } from "@rangojs/router/ssr";
-
+${install}
 export const renderHTML = createSSRHandler({
   createFromReadableStream,
   renderToReadableStream,
   injectRSCPayload,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -61,6 +91,7 @@ export const captureShellHTML = createShellCaptureHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
@@ -71,10 +102,12 @@ export const resumeShellHTML = createShellResumeHandler({
   injectRSCPayload,
   prerender,
   resume,
+  headScripts: ${hs},
   loadBootstrapScriptContent: () =>
     import.meta.viteRsc.loadBootstrapScriptContent("index"),
 });
 `.trim();
+}
 
 /**
  * Virtual modules an RSC entry must import at startup to register the data the

package/src/vite/rango.ts

@@ -239,7 +239,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       },
     });
 
-    plugins.push(createVirtualEntriesPlugin(finalEntries));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, undefined, {
+        headScripts: resolvedOptions.headScripts,
+      }),
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({
@@ -476,7 +480,11 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       },
     });
 
-    plugins.push(createVirtualEntriesPlugin(finalEntries, routerRef));
+    plugins.push(
+      createVirtualEntriesPlugin(finalEntries, routerRef, {
+        headScripts: resolvedOptions.headScripts,
+      }),
+    );
     plugins.push(performanceTracksPlugin());
     plugins.push(
       rsc({

package/src/vite/utils/shared-utils.ts

@@ -5,12 +5,13 @@ import { getPublishedPackageName } from "./package-resolution.js";
 import { performanceTracksOptimizeDepsPlugin } from "../plugins/performance-tracks.js";
 import {
   VIRTUAL_ENTRY_BROWSER,
-  VIRTUAL_ENTRY_SSR,
+  getVirtualEntrySSR,
   getVirtualEntryRSC,
   getVirtualEntryRSCHost,
   getVirtualVersionContent,
   VIRTUAL_IDS,
 } from "../plugins/virtual-entries.js";
+import type { HeadScriptsOption } from "../plugin-types.js";
 
 // Cloudflare preset: @cloudflare/vite-plugin sets optimizeDeps.entries (string
 // or array) on the rsc environment. Single source for both the discovery plugin
@@ -109,6 +110,7 @@ export function normalizeHostRouterEntry(
 export function createVirtualEntriesPlugin(
   entries: { client: string; ssr: string; rsc?: string },
   routerPathRef?: { path?: string; kind?: "router" | "host" },
+  options?: { headScripts?: HeadScriptsOption },
 ): Plugin {
   // Build virtual modules map based on which entries use virtual IDs
   const virtualModules: Record<string, string> = {};
@@ -117,7 +119,7 @@ export function createVirtualEntriesPlugin(
     virtualModules[VIRTUAL_IDS.browser] = VIRTUAL_ENTRY_BROWSER;
   }
   if (entries.ssr === VIRTUAL_IDS.ssr) {
-    virtualModules[VIRTUAL_IDS.ssr] = VIRTUAL_ENTRY_SSR;
+    virtualModules[VIRTUAL_IDS.ssr] = getVirtualEntrySSR(options?.headScripts);
   }
 
   // RSC entry is resolved lazily in load() because routerPath may be