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

package/src/vite/discovery/shell-prerender-phase.ts

@@ -0,0 +1,395 @@
+/**
+ * Post-build PPR shell capture phase (producer B, issue #699).
+ *
+ * Runs from the buildApp post hook, AFTER every environment bundle is written
+ * — the shell prelude embeds built client asset URLs (the bootstrap entry),
+ * which do not exist during buildStart discovery. Reuses the buildStart temp
+ * server kept alive on DiscoveryState (its realm already has tries installed
+ * and routers registered), seeds an in-realm prerender store from the
+ * retained phase-A Flight payloads, and drives the shared capture core
+ * (prerender/build-shell-capture.ts) once per Prerender+ppr candidate. The
+ * SSR half is composed from the temp server's SSR environment runner with
+ * the BUILT client entry as bootstrap.
+ *
+ * Stored entries are staged as __ps-*.js asset modules under the RSC out
+ * dir with a lazy __shell-manifest.js (mirroring the prerender manifest);
+ * the runtime read-through (rsc/shell-build-manifest.ts) serves them on a
+ * shell-store MISS. A candidate whose capture is refused, produces no shell,
+ * or never consulted the prerender store is SKIPPED loudly — the route keeps
+ * producer A (runtime capture) semantics, never a wrong-lane bake.
+ */
+
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { jsonParseExpression } from "../utils/manifest-utils.js";
+import { writeBuildAssetModule } from "../utils/prerender-utils.js";
+import { buildShellManifestKey } from "../../prerender/shell-manifest-key.js";
+// Type-only: the producer stages exactly the record shape the runtime
+// read-through consumes, so the contract cannot drift (the KEY half of that
+// contract is shell-manifest-key.ts). No runtime coupling — the RSC-runtime
+// module is never imported by plugin code.
+import type { BuildShellEntry } from "../../rsc/shell-build-manifest.js";
+import type { DiscoveryState, ShellPrerenderCandidate } from "./state.js";
+import { createRangoDebugger, NS } from "../debug.js";
+
+const debug = createRangoDebugger(NS.prerender);
+
+/**
+ * Minimal builder surface the phase reads: resolved plugins (for the main
+ * build's version plugin) and per-environment outDirs.
+ */
+interface BuilderLike {
+  config?: {
+    base?: string;
+    plugins?: readonly unknown[];
+  };
+  environments?: Record<
+    string,
+    { config?: { build?: { outDir?: string } } } | undefined
+  >;
+}
+
+export async function runShellPrerenderPhase(
+  s: DiscoveryState,
+  builder: BuilderLike | undefined,
+): Promise<void> {
+  // The kept temp server (and the buildEnv deferred with it) is OWNED by the
+  // callers — the buildApp post hook's finally on success, buildEnd on an
+  // aborted build — so this function stays a pure producer: it only tears
+  // down the globals it installs itself.
+  const tempServer = s.shellPhaseTempServer;
+  if (!s.isBuildMode || !s.shellCandidates?.length || !tempServer) return;
+
+  const candidates: ShellPrerenderCandidate[] = s.shellCandidates;
+  const startTotal = performance.now();
+  console.log(`[rango] Shell-prerendering ${candidates.length} URL(s)...`);
+
+  let restoreClientRequire: (() => void) | undefined;
+  try {
+    // Runner access needs the RunnableDevEnvironment surface; the environments
+    // map types as DevEnvironment (same cast the dev endpoints use).
+    const rscEnv = (tempServer.environments as any)?.rsc;
+    const ssrEnv = (tempServer.environments as any)?.ssr;
+    if (!rscEnv?.runner || !ssrEnv?.runner) {
+      console.warn(
+        "[rango] shell prerender: temp server runners unavailable " +
+          `(rsc=${String(!!rscEnv?.runner)}, ssr=${String(!!ssrEnv?.runner)}); ` +
+          "skipping — routes keep runtime shell capture.",
+      );
+      return;
+    }
+
+    // The MAIN build's version (the value folded into the shipped worker) —
+    // never the temp server's own version-plugin stamp, which is a different
+    // Date.now() and would fail the serve-side isValidShellHit gate forever.
+    const versionPlugin = (builder?.config?.plugins ?? []).find(
+      (p: any) => p?.name === "@rangojs/router:version",
+    ) as { api?: { getBuildVersion?: () => string } } | undefined;
+    const buildVersion = versionPlugin?.api?.getBuildVersion?.();
+    if (!buildVersion) {
+      console.warn(
+        "[rango] shell prerender: main build version unavailable; skipping — " +
+          "routes keep runtime shell capture.",
+      );
+      return;
+    }
+
+    // In-realm prerender store over the retained phase-A payloads, so the
+    // capture's match() re-enters withCacheLookup and REPLAYS the build-time
+    // segments (globalThis is shared between the plugin process and the temp
+    // server's module-runner realms). `fetchedKeys` doubles as the replay
+    // assertion: a capture whose candidate key was never fetched rendered
+    // something else (live handler, wrong route) and must not be baked.
+    const payloads = s.prerenderPayloadValues ?? new Map<string, string>();
+    const fetchedKeys = new Set<string>();
+    (globalThis as any).__loadPrerenderManifestModule = async () => ({
+      default: Object.fromEntries([...payloads.keys()].map((k) => [k, k])),
+      loadPrerenderAsset: async (spec: string) => {
+        fetchedKeys.add(spec);
+        return { default: JSON.parse(payloads.get(spec)!) };
+      },
+    });
+
+    // SSR half from the temp server's SSR environment runner. react-dom's
+    // edge builds surface as default-only namespaces through the runner.
+    const ssrRunner = ssrEnv.runner;
+    const ssrPkg = await ssrRunner.import("@rangojs/router/ssr");
+    const ssrDeps = await ssrRunner.import("@rangojs/router/internal/deps/ssr");
+    const reactDomServer = await ssrRunner.import("react-dom/server.edge");
+    const reactDomStatic = await ssrRunner.import("react-dom/static.edge");
+    const htmlStream = await ssrRunner.import(
+      "@rangojs/router/internal/deps/html-stream-server",
+    );
+
+    // Built client bootstrap: the prelude must embed the BUILT entry URL.
+    const clientOutDir =
+      builder?.environments?.client?.config?.build?.outDir ??
+      resolve(s.projectRoot, "dist/client");
+    const clientAssetsDir = join(clientOutDir, "assets");
+    const entryFile = existsSync(clientAssetsDir)
+      ? readdirSync(clientAssetsDir).find((f) => /^index-.*\.js$/.test(f))
+      : undefined;
+    if (!entryFile) {
+      console.warn(
+        `[rango] shell prerender: built client entry not found under ${clientAssetsDir}; ` +
+          "skipping — routes keep runtime shell capture.",
+      );
+      return;
+    }
+    const base = builder?.config?.base ?? "/";
+    const normalizedBase = base.endsWith("/") ? base : `${base}/`;
+    const bootstrapContent = `import("${normalizedBase}assets/${entryFile}")`;
+    debug?.("shell prerender bootstrap: %s", bootstrapContent);
+
+    // The Flight payloads carry PRODUCTION-HASHED client reference ids
+    // (hashClientRefs, forceBuild) — resolvable only in the built bundles.
+    // The temp server's SSR loader receives those hashes and can neither
+    // validate nor import them (dev refKeys are module URLs). Bridge: wrap
+    // the SSR realm's late-bound client require (__vite_rsc_client_require__,
+    // read per call by plugin-rsc's __vite_rsc_require__) with a hash ->
+    // dev-refKey reverse map computed from plugin-rsc's manager using the
+    // SAME hashing (computeProductionHash). Lazy rebuild on miss: a client
+    // module first transformed DURING capture registers after the map was
+    // built. The RSC realm needs no bridge — its $$decode-client lane
+    // re-registers references by id without loading modules.
+    const minimalPlugin = (tempServer.config?.plugins ?? []).find(
+      (p: any) => p?.name === "rsc:minimal",
+    );
+    const rscManager = minimalPlugin?.api?.manager;
+    const { computeProductionHash } =
+      await import("../plugins/client-ref-hashing.js");
+    let hashToDevKey = new Map<string, string>();
+    const rebuildHashMap = (): void => {
+      hashToDevKey = new Map();
+      const metaMap = rscManager?.clientReferenceMetaMap ?? {};
+      for (const meta of Object.values(metaMap) as Array<{
+        referenceKey: string;
+      }>) {
+        hashToDevKey.set(
+          computeProductionHash(s.projectRoot, meta.referenceKey),
+          meta.referenceKey,
+        );
+      }
+    };
+    const origClientRequire = (globalThis as any).__vite_rsc_client_require__;
+    if (typeof origClientRequire === "function") {
+      restoreClientRequire = () => {
+        (globalThis as any).__vite_rsc_client_require__ = origClientRequire;
+      };
+      (globalThis as any).__vite_rsc_client_require__ = (id: string) => {
+        const base = id.split("$$cache=")[0]!;
+        let mapped = hashToDevKey.get(base);
+        if (mapped === undefined) {
+          rebuildHashMap();
+          mapped = hashToDevKey.get(base);
+        }
+        return origClientRequire(mapped ?? id);
+      };
+    }
+
+    const captureShellHTML = ssrPkg.createShellCaptureHandler({
+      createFromReadableStream: ssrDeps.createFromReadableStream,
+      renderToReadableStream:
+        reactDomServer.renderToReadableStream ??
+        reactDomServer.default?.renderToReadableStream,
+      resume: reactDomServer.resume ?? reactDomServer.default?.resume,
+      prerender: reactDomStatic.prerender ?? reactDomStatic.default?.prerender,
+      injectRSCPayload: htmlStream.injectRSCPayload,
+      headScripts: "preinit",
+      loadBootstrapScriptContent: async () => bootstrapContent,
+    });
+
+    // RSC half: the shared capture core in the RSC realm.
+    const rscRunner = rscEnv.runner;
+    const captureMod = await rscRunner.import(
+      "@rangojs/router/build/shell-capture",
+    );
+    const serverMod = await rscRunner.import("@rangojs/router/server");
+    const registry: Map<string, any> = serverMod.RouterRegistry;
+
+    const staged: Array<{ key: string; value: string }> = [];
+    let skipCount = 0;
+
+    // Manifest keys are pathname-only (see shell-manifest-key.ts): two
+    // candidates on one pathname (two routers prerendering the same path)
+    // would be ambiguous at serve time — decline ALL of that pathname's
+    // entries rather than bake a wrong-router shell.
+    const pathCounts = new Map<string, number>();
+    for (const cand of candidates) {
+      pathCounts.set(cand.urlPath, (pathCounts.get(cand.urlPath) ?? 0) + 1);
+    }
+
+    for (const cand of candidates) {
+      if ((pathCounts.get(cand.urlPath) ?? 0) > 1) {
+        console.warn(
+          `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} - pathname claimed by multiple prerender routes; routes keep runtime capture`,
+        );
+        skipCount++;
+        continue;
+      }
+      const startUrl = performance.now();
+      const policy = captureMod.resolveBuildPprConfig(cand.ppr);
+      const mainKey = `${cand.routeName}/${cand.paramHash}`;
+      let handled = false;
+      const mismatches: string[] = [];
+      for (const [, routerInstance] of registry) {
+        if (typeof routerInstance.match !== "function") continue;
+        try {
+          const res = await captureMod.captureShellForBuild({
+            router: routerInstance,
+            urlPath: cand.urlPath,
+            routeName: cand.routeName,
+            key: `${cand.urlPath}:shell`,
+            ttl: policy.ttl,
+            swr: policy.swr,
+            tags: policy.tags,
+            buildEnv: s.resolvedBuildEnv,
+            buildVersion,
+            captureShellHTML,
+            debug: !!debug,
+          });
+          if (res.outcome === "route-mismatch") {
+            mismatches.push(res.matchedRouteName ?? "(no match)");
+            continue;
+          }
+          handled = true;
+          const elapsed = (performance.now() - startUrl).toFixed(0);
+          if (res.outcome !== "stored" || !res.entry) {
+            console.warn(
+              `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} (${elapsed}ms) - capture ${res.outcome}; route keeps runtime capture`,
+            );
+            skipCount++;
+            break;
+          }
+          // Replay assertion: the capture must have fetched THIS candidate's
+          // prerender payload — otherwise it rendered outside the store
+          // (live handler in the source realm) and baking it would encode a
+          // lane production never serves.
+          if (!fetchedKeys.has(mainKey)) {
+            console.warn(
+              `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} (${elapsed}ms) - capture did not replay the prerender store; route keeps runtime capture`,
+            );
+            skipCount++;
+            break;
+          }
+          const value: BuildShellEntry = {
+            entry: res.entry,
+            ttl: policy.ttl,
+            swr: policy.swr,
+            tags: res.tags,
+            routeName: cand.routeName,
+          };
+          staged.push({
+            key: buildShellManifestKey(cand.urlPath),
+            value: JSON.stringify(value),
+          });
+          console.log(
+            `[rango]   SHELL OK   ${cand.urlPath.padEnd(34)} (${elapsed}ms)`,
+          );
+          break;
+        } catch (err: any) {
+          handled = true;
+          const elapsed = (performance.now() - startUrl).toFixed(0);
+          console.warn(
+            `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} (${elapsed}ms) - ${err?.message ?? err}; route keeps runtime capture`,
+          );
+          skipCount++;
+          break;
+        }
+      }
+      if (!handled) {
+        console.warn(
+          `[rango]   SHELL SKIP ${cand.urlPath.padEnd(34)} - no router matched "${cand.routeName}"` +
+            (mismatches.length > 0
+              ? ` (matched: ${mismatches.join(", ")})`
+              : "") +
+            "; route keeps runtime capture",
+        );
+        skipCount++;
+      }
+    }
+
+    if (staged.length > 0) {
+      const rscOutDir =
+        builder?.environments?.rsc?.config?.build?.outDir ??
+        resolve(s.projectRoot, "dist/rsc");
+      writeShellManifest(s, rscOutDir, staged);
+    }
+
+    const totalElapsed = (performance.now() - startTotal).toFixed(0);
+    const parts = [`${staged.length} done`];
+    if (skipCount > 0) parts.push(`${skipCount} skipped`);
+    console.log(
+      `[rango] Shell prerender complete: ${parts.join(", ")} (${totalElapsed}ms total)`,
+    );
+  } catch (err: any) {
+    // The shell phase is an optimization over runtime capture — a failure
+    // must never fail an otherwise-good build. Loud, so a first-request-HIT
+    // expectation is never silently degraded.
+    console.warn(
+      `[rango] shell prerender phase failed: ${err?.message ?? err}; ` +
+        "routes keep runtime shell capture.",
+    );
+  } finally {
+    // Tear down only what THIS function installed (its globals). The kept
+    // temp server + deferred buildEnv pair is owned by the callers: the
+    // buildApp post hook's finally on success, buildEnd on an aborted build.
+    delete (globalThis as any).__loadPrerenderManifestModule;
+    restoreClientRequire?.();
+  }
+}
+
+/**
+ * Write staged shell entries as content-hashed asset modules + the lazy
+ * manifest, and inject the loader global into the built RSC entry. Mirrors
+ * postprocessBundle's prerender manifest mechanics, but runs POST-buildApp
+ * (the RSC entry on disk was already postprocessed — read-modify-write with
+ * an idempotence guard).
+ */
+function writeShellManifest(
+  s: DiscoveryState,
+  rscOutDir: string,
+  staged: Array<{ key: string; value: string }>,
+): void {
+  const rscEntryPath = resolve(rscOutDir, s.rscEntryFileName ?? "index.js");
+  if (!existsSync(rscEntryPath)) {
+    console.warn(
+      `[rango] shell prerender: RSC entry not found at ${rscEntryPath}; ` +
+        "entries not persisted — routes keep runtime capture.",
+    );
+    return;
+  }
+  const assetsDir = resolve(rscOutDir, "assets");
+
+  let totalBytes = 0;
+  const manifestMap: Record<string, string> = {};
+  const countedFiles = new Set<string>();
+  for (const { key, value } of staged) {
+    const fileName = writeBuildAssetModule(assetsDir, "__ps", value);
+    if (!countedFiles.has(fileName)) {
+      countedFiles.add(fileName);
+      totalBytes += Buffer.byteLength(value) + "export default ;\n".length;
+    }
+    manifestMap[key] = `./assets/${fileName}`;
+  }
+
+  const manifestCode = [
+    `const m=${jsonParseExpression(manifestMap)};`,
+    `export function loadShellAsset(s){return import(s)}`,
+    `export default m;`,
+    "",
+  ].join("\n");
+  writeFileSync(resolve(rscOutDir, "__shell-manifest.js"), manifestCode);
+  totalBytes += Buffer.byteLength(manifestCode);
+
+  const rscCode = readFileSync(rscEntryPath, "utf-8");
+  if (!rscCode.includes("__shell-manifest.js")) {
+    const injection = `globalThis.__loadShellManifestModule = () => import("./__shell-manifest.js");\n`;
+    writeFileSync(rscEntryPath, injection + rscCode);
+  }
+
+  const totalKB = (totalBytes / 1024).toFixed(1);
+  console.log(
+    `[rango] Wrote shell assets (${totalKB} KB total, ${staged.length} entries)`,
+  );
+}

package/src/vite/discovery/state.ts

@@ -38,6 +38,12 @@ export interface PluginOptions {
    * (`clientChunks: true`/default); undefined for `false` or a custom function.
    */
   clientChunkCtx?: import("../utils/client-chunks.js").ClientChunkContext;
+  /**
+   * rango({ headScripts }) — threaded so the dev temp server can serve the
+   * REAL virtual SSR entry (getVirtualEntrySSR) for the on-demand shell
+   * capture endpoint with the app's configured head-script strategy.
+   */
+  headScripts?: import("../plugin-types.js").HeadScriptsOption;
 }
 
 export interface PrecomputedEntry {
@@ -58,6 +64,18 @@ export interface PerRouterManifestEntry {
   factoryOnlyPrefixes?: Set<string>;
 }
 
+/**
+ * One Prerender+ppr URL the build must additionally produce a PPR shell entry
+ * for (issue #699 producer B). `ppr` is the route's raw path option, already
+ * filtered to truthy by the collector.
+ */
+export interface ShellPrerenderCandidate {
+  urlPath: string;
+  routeName: string;
+  paramHash: string;
+  ppr: true | { ttl?: number; swr?: number; tags?: string[] };
+}
+
 export interface DiscoveryState {
   resolvedEntryPath: string | undefined;
   projectRoot: string;
@@ -93,6 +111,27 @@ export interface DiscoveryState {
 
   prerenderManifestEntries: Record<string, string> | null;
   staticManifestEntries: Record<string, string> | null;
+  /**
+   * Build-time PPR shell candidates: prerender routes that ALSO declare the
+   * `ppr` path option (issue #699 producer B). Collected by
+   * expandPrerenderRoutes; consumed by the post-build shell capture phase.
+   */
+  shellCandidates: ShellPrerenderCandidate[] | null;
+  /**
+   * Raw prerender payload JSON strings keyed by manifest key, retained in
+   * memory so the shell capture phase can seed an in-realm prerender store
+   * without re-reading staged asset files.
+   */
+  prerenderPayloadValues: Map<string, string> | null;
+  /**
+   * The buildStart temp RSC server, kept alive past discovery when shell
+   * candidates exist: the shell capture phase (buildApp post) reuses its
+   * realm — tries installed, registry populated — after the client build has
+   * produced the asset URLs the prelude must embed. Deferred as a PAIR with
+   * the buildEnv; closed by the buildApp post hook's finally (success) or
+   * buildEnd (aborted build).
+   */
+  shellPhaseTempServer: import("vite").ViteDevServer | null;
   handlerChunkInfoMap: Map<string, ChunkInfo>;
   staticHandlerChunkInfoMap: Map<string, ChunkInfo>;
   rscEntryFileName: string | null;
@@ -145,6 +184,9 @@ export function createDiscoveryState(
 
     prerenderManifestEntries: null,
     staticManifestEntries: null,
+    shellCandidates: null,
+    prerenderPayloadValues: null,
+    shellPhaseTempServer: null,
     handlerChunkInfoMap: new Map(),
     staticHandlerChunkInfoMap: new Map(),
     rscEntryFileName: null,

package/src/vite/index.ts

@@ -24,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/version-plugin.ts

@@ -142,6 +142,14 @@ export function createVersionPlugin(): Plugin {
     name: "@rangojs/router:version",
     enforce: "pre",
 
+    // The build-time shell capture phase (producer B, #699) stamps entries
+    // with THIS instance's version — the value folded into the shipped worker
+    // — never the discovery temp server's own version-plugin value (a
+    // different Date.now() stamp that would fail the serve-side gate).
+    api: {
+      getBuildVersion: (): string => currentVersion,
+    },
+
     configResolved(config) {
       isDev = config.command === "serve";
       resolvedCacheDir = config.cacheDir

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({
@@ -536,6 +544,7 @@ export async function rango(options?: RangoOptions): Promise<PluginOption[]> {
       prerenderOnError: options?.prerender?.onError,
       discovery: options?.discovery,
       clientChunkCtx,
+      headScripts: resolvedOptions.headScripts,
     }),
   );