@rangojs/router 0.11.0 → 0.12.0

package/dist/testing/vitest.js

@@ -14,7 +14,7 @@ function rangoTestAliases(opts = {}) {
       replacement: here("src/testing/vitest-stubs/version.ts")
     },
     {
-      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      find: /^@vitejs\/plugin-rsc\/rsc(\/(server|client))?$/,
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts")
     }
   ];

package/dist/types/deps/rsc-client.d.ts

@@ -0,0 +1 @@
+export { createFromReadableStream, encodeReply, createClientTemporaryReferenceSet, } from "@vitejs/plugin-rsc/rsc/client";

package/dist/types/deps/rsc.d.ts

@@ -1 +1 @@
-export { renderToReadableStream, decodeReply, createTemporaryReferenceSet, loadServerAction, decodeAction, decodeFormState, } from "@vitejs/plugin-rsc/rsc";
+export { renderToReadableStream, decodeReply, createTemporaryReferenceSet, loadServerAction, decodeAction, decodeFormState, } from "@vitejs/plugin-rsc/rsc/server";

package/dist/types/deps/ssr.d.ts

@@ -1 +1 @@
-export { createFromReadableStream, setOnClientReference, } from "@vitejs/plugin-rsc/ssr";
+export { createFromReadableStream, setOnClientReference, getClientEntryUrl, } from "@vitejs/plugin-rsc/ssr";

package/dist/types/rsc/types.d.ts

@@ -107,37 +107,37 @@ export interface RscPayload {
  */
 export type ReactFormState = unknown;
 /**
- * RSC dependencies from @vitejs/plugin-rsc/rsc
+ * RSC dependencies from @vitejs/plugin-rsc/rsc/server
  */
 export interface RSCDependencies {
     /**
-     * renderToReadableStream from @vitejs/plugin-rsc/rsc
+     * renderToReadableStream from @vitejs/plugin-rsc/rsc/server
      */
     renderToReadableStream: <T>(payload: T, options?: {
         temporaryReferences?: unknown;
         onError?: (error: unknown) => string | void;
     }) => ReadableStream<Uint8Array>;
     /**
-     * decodeReply from @vitejs/plugin-rsc/rsc
+     * decodeReply from @vitejs/plugin-rsc/rsc/server
      */
     decodeReply: (body: FormData | string, options?: {
         temporaryReferences?: unknown;
     }) => Promise<unknown[]>;
     /**
-     * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc
+     * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc/server
      */
     createTemporaryReferenceSet: () => unknown;
     /**
-     * loadServerAction from @vitejs/plugin-rsc/rsc
+     * loadServerAction from @vitejs/plugin-rsc/rsc/server
      */
     loadServerAction: (actionId: string) => Promise<Function>;
     /**
-     * decodeAction from @vitejs/plugin-rsc/rsc
+     * decodeAction from @vitejs/plugin-rsc/rsc/server
      * Decodes a FormData into a bound action function (for useActionState forms)
      */
     decodeAction: (body: FormData) => Promise<() => Promise<unknown>>;
     /**
-     * decodeFormState from @vitejs/plugin-rsc/rsc
+     * decodeFormState from @vitejs/plugin-rsc/rsc/server
      * Decodes the action result into a ReactFormState for useActionState progressive enhancement
      */
     decodeFormState: (actionResult: unknown, body: FormData) => Promise<ReactFormState | null>;
@@ -268,8 +268,8 @@ export interface CreateRSCHandlerOptions<TEnv = unknown, TRoutes extends Record<
      */
     router: RangoInternal<TEnv, TRoutes>;
     /**
-     * RSC dependencies from @vitejs/plugin-rsc/rsc.
-     * Defaults to the exports from @vitejs/plugin-rsc/rsc.
+     * RSC dependencies from @vitejs/plugin-rsc/rsc/server.
+     * Defaults to the exports from @vitejs/plugin-rsc/rsc/server.
      */
     deps?: RSCDependencies;
     /**

package/dist/types/ssr/index.d.ts

@@ -117,10 +117,19 @@ export interface SSRDependencies<TEnv = unknown> {
      */
     injectRSCPayload: (rscStream: ReadableStream<Uint8Array>, options?: InjectRSCPayloadOptions) => TransformStream<Uint8Array, Uint8Array>;
     /**
-     * Function to load bootstrap script content
-     * Typically: () => import.meta.viteRsc.loadBootstrapScriptContent("index")
+     * Function to load bootstrap script content.
+     * Required unless `getClientEntryUrl` is provided with `headScripts: "preinit"`.
+     * Custom SSR entries typically: `() => import.meta.viteRsc.loadBootstrapScriptContent("index")`
+     * (deprecated in `@vitejs/plugin-rsc` 0.5.33 in favor of `getClientEntryUrl`).
      */
-    loadBootstrapScriptContent: () => Promise<string>;
+    loadBootstrapScriptContent?: () => Promise<string>;
+    /**
+     * Client entry URL from `@vitejs/plugin-rsc/ssr` `getClientEntryUrl()`.
+     * Preferred when `headScripts` is `"preinit"`: Fizz receives `bootstrapModules`
+     * without the deprecated `loadBootstrapScriptContent` round-trip. Custom SSR
+     * entries can omit this and keep the inline bootstrap path.
+     */
+    getClientEntryUrl?: () => string;
     /**
      * Document script strategy; the generated virtual SSR entry threads the
      * `rango({ headScripts })` plugin option here (canonical docs on
@@ -251,7 +260,10 @@ interface ShellResumeOptions {
  * @example
  * ```tsx
  * import { createSSRHandler } from "@rangojs/router/ssr";
- * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+ * import {
+ *   createFromReadableStream,
+ *   getClientEntryUrl,
+ * } from "@rangojs/router/internal/deps/ssr";
  * import { renderToReadableStream } from "react-dom/server.edge";
  * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
  *
@@ -259,6 +271,17 @@ interface ShellResumeOptions {
  *   createFromReadableStream,
  *   renderToReadableStream,
  *   injectRSCPayload,
+ *   getClientEntryUrl,
+ *   headScripts: "preinit", // getClientEntryUrl is only used under "preinit"
+ * });
+ * ```
+ *
+ * Custom SSR entries that still use the deprecated bootstrap helper:
+ * ```tsx
+ * export const renderHTML = createSSRHandler({
+ *   createFromReadableStream,
+ *   renderToReadableStream,
+ *   injectRSCPayload,
  *   loadBootstrapScriptContent: () =>
  *     import.meta.viteRsc.loadBootstrapScriptContent("index"),
  * });

package/dist/types/testing/flight.d.ts

@@ -6,14 +6,15 @@
  * the same react-server-dom serializer the router uses at runtime. It runs in
  * plain node (no Vite, no browser), but ONLY under the `react-server` export
  * condition. The serializer is the VENDORED build shipped with
- * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc` entry top-level
- * imports Vite virtual modules and is not usable outside a Vite build.
+ * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc/server` entry
+ * top-level imports Vite virtual modules and is not usable outside a Vite
+ * build.
  *
  * Run the example/tests for this module via the dedicated rsc vitest project
  * (vitest.rsc.config.ts), which forces `--conditions=react-server` on the
  * worker. The main vitest project must NOT use that condition (it would flip
  * React to the no-hooks server build and break the ~50 tests that mock
- * @vitejs/plugin-rsc/rsc).
+ * @vitejs/plugin-rsc/rsc/server).
  *
  * Scope / limitations (v1):
  * - Server-only / leaf trees. A tree containing a CLIENT component emits an

package/dist/types/testing/vitest-stubs/plugin-rsc.d.ts

@@ -5,3 +5,5 @@ export declare const decodeReply: () => undefined;
 export declare const decodeAction: () => undefined;
 export declare const decodeFormState: () => undefined;
 export declare const createTemporaryReferenceSet: () => Record<string, never>;
+export declare const encodeReply: () => never;
+export declare const createClientTemporaryReferenceSet: () => Record<string, never>;

package/dist/types/testing/vitest.d.ts

@@ -18,7 +18,8 @@
  *   `@rangojs/router` specifier to its react-server entry (real impls) while
  *   leaving React as the client build — which is exactly what this helper does.
  * - The build-only `@rangojs/router:version` virtual and `@vitejs/plugin-rsc/rsc`
- *   (whose real body imports unresolvable Vite virtuals) are stubbed.
+ *   plus `/rsc/server`, `/rsc/client` (whose real body imports unresolvable
+ *   Vite virtuals) are stubbed.
  * - Cloudflare apps additionally import the `cloudflare:workers` /
  *   `cloudflare:email` runtime virtuals; pass `{ preset: "cloudflare" }` to stub them.
  *

package/dist/types/vite/plugins/virtual-entries.d.ts

@@ -3,8 +3,9 @@ export declare const VIRTUAL_ENTRY_BROWSER: string;
 /**
  * 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.
+ * threads `getClientEntryUrl` so Fizz emits `bootstrapModules`;
+ * "preload" omits the hook and uses the deprecated inline
+ * `loadBootstrapScriptContent` bootstrap.
  */
 export declare function getVirtualEntrySSR(headScripts?: HeadScriptsOption, progressiveChunkSize?: number): string;
 /**

package/dist/vite/index.js

@@ -3048,6 +3048,7 @@ function useCacheTransform() {
         } catch {
           return;
         }
+        stripNullDirectiveFields(ast);
         const filePath = normalizePath(path5.relative(projectRoot, id));
         const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
         if (hasDirective(ast.body, "use cache")) {
@@ -3058,7 +3059,8 @@ function useCacheTransform() {
             id,
             isBuild,
             isLayoutOrTemplate,
-            transformWrapExport
+            transformWrapExport,
+            hasDirective
           );
         }
         const functionResult = transformFunctionLevelUseCache(
@@ -3077,7 +3079,7 @@ function useCacheTransform() {
     }
   };
 }
-function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport) {
+function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLayoutOrTemplate, transformWrapExport, hasDirective) {
   const unconfirmedExports = [];
   const { exportNames, output } = transformWrapExport(code, ast, {
     runtime: (value, name) => {
@@ -3087,6 +3089,11 @@ function transformFileLevelUseCache(code, ast, filePath, sourceId, isBuild, isLa
     rejectNonAsyncFunction: false,
     filter: (name, meta) => {
       if (name === "default" && isLayoutOrTemplate) return false;
+      if (name.startsWith("$$hoist_")) return false;
+      if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective)) {
+        return false;
+      }
       if (meta.isFunction !== true) {
         unconfirmedExports.push(name);
         return false;
@@ -3158,6 +3165,36 @@ function transformFunctionLevelUseCache(code, ast, filePath, sourceId, isBuild,
     return;
   }
 }
+function stripNullDirectiveFields(node) {
+  if (!node || typeof node !== "object") return;
+  const rec = node;
+  if (rec.type === "ExpressionStatement" && typeof rec.directive !== "string") {
+    delete rec.directive;
+  }
+  for (const value of Object.values(rec)) {
+    if (Array.isArray(value)) {
+      for (const item of value) stripNullDirectiveFields(item);
+    } else if (value && typeof value === "object" && "type" in value) {
+      stripNullDirectiveFields(value);
+    }
+  }
+}
+function isHoistedServerReferenceRebind(valueNode) {
+  if (!valueNode || valueNode.type !== "CallExpression") return false;
+  const first = valueNode.arguments[0];
+  return first !== void 0 && first.type === "Identifier" && first.name.startsWith("$$hoist_");
+}
+function functionHasUseServerDirective(valueNode, hasDirective) {
+  if (!valueNode || !("body" in valueNode)) return false;
+  const { body } = valueNode;
+  if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
+    return false;
+  }
+  return hasDirective(
+    body.body,
+    "use server"
+  );
+}
 function findFileLevelDirective(ast) {
   for (const node of ast.body ?? []) {
     if (node.type === "ExpressionStatement" && node.expression?.type === "Literal" && typeof node.expression.value === "string" && node.expression.value.startsWith("use cache")) {
@@ -3501,7 +3538,7 @@ function emitProgressiveChunkSize(value) {
 }
 function getVirtualEntrySSR(headScripts = "preinit", progressiveChunkSize) {
   const preinit = headScripts !== "preload";
-  const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference," : "createFromReadableStream,";
+  const depsImportNames = preinit ? "createFromReadableStream,\n  setOnClientReference,\n  getClientEntryUrl," : "createFromReadableStream,";
   const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
   const install = preinit ? `
 // Upgrade client-reference modulepreload hints to executing module scripts in
@@ -3509,6 +3546,8 @@ function getVirtualEntrySSR(headScripts = "preinit", progressiveChunkSize) {
 // See src/ssr/preinit-client-references.ts for the full rationale.
 installClientReferencePreinit(setOnClientReference);
 ` : "";
+  const bootstrapDep = preinit ? "getClientEntryUrl," : `loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),`;
   const hs = JSON.stringify(headScripts);
   const pcs = progressiveChunkSize !== void 0 ? `
   progressiveChunkSize: ${emitProgressiveChunkSize(progressiveChunkSize)},` : "";
@@ -3530,8 +3569,7 @@ export const renderHTML = createSSRHandler({
   renderToReadableStream,
   injectRSCPayload,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 
 export const captureShellHTML = createShellCaptureHandler({
@@ -3541,8 +3579,7 @@ export const captureShellHTML = createShellCaptureHandler({
   prerender,
   resume,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 
 export const resumeShellHTML = createShellResumeHandler({
@@ -3552,8 +3589,7 @@ export const resumeShellHTML = createShellResumeHandler({
   prerender,
   resume,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 `.trim();
 }
@@ -3710,7 +3746,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.11.0",
+  version: "0.12.0",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",
@@ -3798,6 +3834,11 @@ var package_default = {
       "react-server": "./src/deps/rsc.ts",
       default: "./src/deps/rsc.ts"
     },
+    "./internal/deps/rsc-client": {
+      types: "./dist/types/deps/rsc-client.d.ts",
+      "react-server": "./src/deps/rsc-client.ts",
+      default: "./src/deps/rsc-client.ts"
+    },
     "./internal/deps/html-stream-client": {
       types: "./dist/types/deps/html-stream-client.d.ts",
       default: "./src/deps/html-stream-client.ts"
@@ -3903,7 +3944,7 @@ var package_default = {
   },
   dependencies: {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     debug: "^4.4.1",
     "magic-string": "^0.30.17",
     picomatch: "^4.0.4",
@@ -3936,7 +3977,7 @@ var package_default = {
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     react: ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     vite: "^8.0.16",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",
@@ -88,6 +88,11 @@
       "react-server": "./src/deps/rsc.ts",
       "default": "./src/deps/rsc.ts"
     },
+    "./internal/deps/rsc-client": {
+      "types": "./dist/types/deps/rsc-client.d.ts",
+      "react-server": "./src/deps/rsc-client.ts",
+      "default": "./src/deps/rsc-client.ts"
+    },
     "./internal/deps/html-stream-client": {
       "types": "./dist/types/deps/html-stream-client.d.ts",
       "default": "./src/deps/html-stream-client.ts"
@@ -179,7 +184,7 @@
   },
   "dependencies": {
     "@types/debug": "^4.1.12",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     "debug": "^4.4.1",
     "magic-string": "^0.30.17",
     "picomatch": "^4.0.4",
@@ -212,7 +217,7 @@
     "@playwright/test": "^1.49.1",
     "@testing-library/react": ">=16",
     "@vercel/functions": "^3.0.0",
-    "@vitejs/plugin-rsc": "^0.5.31",
+    "@vitejs/plugin-rsc": "^0.5.34",
     "react": ">=19.2.8 <20",
     "react-dom": ">=19.2.8 <20",
     "vite": "^8.0.16",

package/skills/testing/setup.md

@@ -14,11 +14,11 @@ Real machinery: Vite transpiles `@rangojs/router`'s shipped TS source and resolv
 
 ### Functions
 
-| Function                    | Returns                                   | Use                                                                                                                                                                                                         |
-| --------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                         |
-| `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
-| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                  |
+| Function                    | Returns                                   | Use                                                                                                                                                                                                                                        |
+| --------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `rangoTestConfig(opts?)`    | `{ alias, server: { deps: { inline } } }` | Recommended. Spread into the node/DOM project's `test` block. Bundles the resolve aliases AND `server.deps.inline`.                                                                                                                        |
+| `rangoTestAliases(opts?)`   | `TestAlias[]` (`{ find, replacement }[]`) | Lower-level. The bare `@rangojs/router` -> `index.rsc.ts` alias plus the `:version` / `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) stubs (and CF stubs under `preset:"cloudflare"`). Used in the rsc project's `resolve.alias`. |
+| `rangoUseClientTransform()` | a Vite plugin (`{ name, transform }`)     | Add to the rsc project `plugins`. Applies the `"use client"` transform so `renderServerTree` auto-discovers client islands from the server tree's imports.                                                                                 |
 
 ### Returns — `RangoTestConfig` (from `rangoTestConfig`)
 
@@ -112,7 +112,7 @@ Scripts:
 - The rsc project needs BOTH `resolve.conditions: ["react-server"]` AND the bare `@rangojs/router` -> `index.rsc.ts` alias from `rangoTestAliases({ preset })`. `resolve.conditions` alone is not reliably applied to bare-package export resolution; without the alias a handler/component reading `getRequestContext()` / `cookies()` resolves the throwing out-of-react-server stub (symptom: `renderHandler` returns `tree: undefined`). `renderToFlightString` / `renderServerTree` now self-diagnose this exact misconfiguration — they reject with an actionable message naming `rangoTestAliases`, rather than surfacing the opaque stub error.
 - `NODE_ENV` must be `"production"` in the rsc project. Dev `NODE_ENV` crashes the bare worker (jsxDEV owner-stack machinery uninitialized) and emits volatile debug rows that defeat stable Flight snapshots.
 - The forked rsc worker (`pool: "forks"`) must force the condition via `execArgv: ["--conditions=react-server"]`, or React throws "the react-server condition must be enabled".
-- The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
+- The `@rangojs/router:version` and `@vitejs/plugin-rsc/rsc` (`/rsc/server`, `/rsc/client`) virtuals must be stubbed; the preset does it. A bare router import without stubbing throws.
 - The rango fragment goes under `test` (`test.alias` + `test.server.deps.inline`, both returned by `rangoTestConfig`), NOT under top-level `resolve`.
 - Wire `rangoUseClientTransform()` into the rsc project `plugins` so islands auto-discover from the server tree imports (see `./server-tree.md`); without it, register islands explicitly with `clientComponents`.
 

package/src/cache/cache-runtime.ts

@@ -19,7 +19,7 @@
 import {
   encodeReply,
   createClientTemporaryReferenceSet,
-} from "@vitejs/plugin-rsc/rsc";
+} from "../deps/rsc-client.js";
 import {
   getRequestContext,
   runWithRequestContext,

package/src/cache/segment-codec.ts

@@ -15,8 +15,8 @@ import { segmentFragment } from "../segment-fragments.js";
 import {
   renderToReadableStream,
   createTemporaryReferenceSet,
-} from "@vitejs/plugin-rsc/rsc";
-import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
+} from "../deps/rsc.js";
+import { createFromReadableStream } from "../deps/rsc-client.js";
 
 // Preserve embedded server references on a cache/prerender HIT so they
 // re-serialize to the client instead of resolving to a raw function React

package/src/deps/rsc-client.ts

@@ -0,0 +1,8 @@
+/// <reference types="@vitejs/plugin-rsc/types" />
+// RSC-environment *client* protocol (deserialize / encodeReply). Kept as its
+// own module so a server-only importer of `./rsc.ts` does not pull this side.
+export {
+  createFromReadableStream,
+  encodeReply,
+  createClientTemporaryReferenceSet,
+} from "@vitejs/plugin-rsc/rsc/client";

package/src/deps/rsc.ts

@@ -1,5 +1,7 @@
 /// <reference types="@vitejs/plugin-rsc/types" />
-// Re-export @vitejs/plugin-rsc/rsc for internal use by virtual entries
+// Re-export the RSC-environment *server* runtime for virtual entries.
+// Prefer `@vitejs/plugin-rsc/rsc/server` over the combined `/rsc` barrel so
+// Vite can skip bundling the unused `react-server-dom` client protocol.
 export {
   renderToReadableStream,
   decodeReply,
@@ -7,4 +9,4 @@ export {
   loadServerAction,
   decodeAction,
   decodeFormState,
-} from "@vitejs/plugin-rsc/rsc";
+} from "@vitejs/plugin-rsc/rsc/server";

package/src/deps/ssr.ts

@@ -1,4 +1,5 @@
 export {
   createFromReadableStream,
   setOnClientReference,
+  getClientEntryUrl,
 } from "@vitejs/plugin-rsc/ssr";

package/src/rsc/handler.ts

@@ -16,7 +16,7 @@ import {
   _getRequestContext,
   createRequestContext,
 } from "../server/request-context.js";
-import * as rscDeps from "@vitejs/plugin-rsc/rsc";
+import * as rscDeps from "@vitejs/plugin-rsc/rsc/server";
 import type {
   RscPayload,
   CreateRSCHandlerOptions,
@@ -137,7 +137,7 @@ import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
  * @example With custom deps (advanced)
  * ```tsx
  * import { createRSCHandler } from "@rangojs/router/rsc";
- * import * as rsc from "@vitejs/plugin-rsc/rsc";
+ * import * as rsc from "@vitejs/plugin-rsc/rsc/server";
  * import { router } from "./router.js";
  *
  * export default createRSCHandler({
@@ -176,7 +176,7 @@ export function createRSCHandler<
   // stores not covered by the app-level ctx._cacheStore.
   const explicitTaggedStores = new Set<SegmentCacheStore>();
 
-  // Use provided deps or default to @vitejs/plugin-rsc/rsc exports
+  // Use provided deps or default to @vitejs/plugin-rsc/rsc/server exports
   const deps = options.deps ?? rscDeps;
   const {
     renderToReadableStream,

package/src/rsc/types.ts

@@ -103,11 +103,11 @@ export interface RscPayload {
 export type ReactFormState = unknown;
 
 /**
- * RSC dependencies from @vitejs/plugin-rsc/rsc
+ * RSC dependencies from @vitejs/plugin-rsc/rsc/server
  */
 export interface RSCDependencies {
   /**
-   * renderToReadableStream from @vitejs/plugin-rsc/rsc
+   * renderToReadableStream from @vitejs/plugin-rsc/rsc/server
    */
   renderToReadableStream: <T>(
     payload: T,
@@ -118,7 +118,7 @@ export interface RSCDependencies {
   ) => ReadableStream<Uint8Array>;
 
   /**
-   * decodeReply from @vitejs/plugin-rsc/rsc
+   * decodeReply from @vitejs/plugin-rsc/rsc/server
    */
   decodeReply: (
     body: FormData | string,
@@ -126,23 +126,23 @@ export interface RSCDependencies {
   ) => Promise<unknown[]>;
 
   /**
-   * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc
+   * createTemporaryReferenceSet from @vitejs/plugin-rsc/rsc/server
    */
   createTemporaryReferenceSet: () => unknown;
 
   /**
-   * loadServerAction from @vitejs/plugin-rsc/rsc
+   * loadServerAction from @vitejs/plugin-rsc/rsc/server
    */
   loadServerAction: (actionId: string) => Promise<Function>;
 
   /**
-   * decodeAction from @vitejs/plugin-rsc/rsc
+   * decodeAction from @vitejs/plugin-rsc/rsc/server
    * Decodes a FormData into a bound action function (for useActionState forms)
    */
   decodeAction: (body: FormData) => Promise<() => Promise<unknown>>;
 
   /**
-   * decodeFormState from @vitejs/plugin-rsc/rsc
+   * decodeFormState from @vitejs/plugin-rsc/rsc/server
    * Decodes the action result into a ReactFormState for useActionState progressive enhancement
    */
   decodeFormState: (
@@ -300,8 +300,8 @@ export interface CreateRSCHandlerOptions<
   router: RangoInternal<TEnv, TRoutes>;
 
   /**
-   * RSC dependencies from @vitejs/plugin-rsc/rsc.
-   * Defaults to the exports from @vitejs/plugin-rsc/rsc.
+   * RSC dependencies from @vitejs/plugin-rsc/rsc/server.
+   * Defaults to the exports from @vitejs/plugin-rsc/rsc/server.
    */
   deps?: RSCDependencies;
 

package/src/ssr/index.tsx

@@ -154,10 +154,20 @@ export interface SSRDependencies<TEnv = unknown> {
   ) => TransformStream<Uint8Array, Uint8Array>;
 
   /**
-   * Function to load bootstrap script content
-   * Typically: () => import.meta.viteRsc.loadBootstrapScriptContent("index")
+   * Function to load bootstrap script content.
+   * Required unless `getClientEntryUrl` is provided with `headScripts: "preinit"`.
+   * Custom SSR entries typically: `() => import.meta.viteRsc.loadBootstrapScriptContent("index")`
+   * (deprecated in `@vitejs/plugin-rsc` 0.5.33 in favor of `getClientEntryUrl`).
    */
-  loadBootstrapScriptContent: () => Promise<string>;
+  loadBootstrapScriptContent?: () => Promise<string>;
+
+  /**
+   * Client entry URL from `@vitejs/plugin-rsc/ssr` `getClientEntryUrl()`.
+   * Preferred when `headScripts` is `"preinit"`: Fizz receives `bootstrapModules`
+   * without the deprecated `loadBootstrapScriptContent` round-trip. Custom SSR
+   * entries can omit this and keep the inline bootstrap path.
+   */
+  getClientEntryUrl?: () => string;
 
   /**
    * Document script strategy; the generated virtual SSR entry threads the
@@ -438,36 +448,105 @@ interface ShellResumeOptions {
 const BOOTSTRAP_IMPORT_ONLY_RE =
   /^\s*import\(\s*(["'])([^"'\\]+)\1\s*\)\s*;?\s*$/;
 
+const MISSING_BOOTSTRAP_MSG =
+  "[ssr] Missing bootstrap dependency: provide loadBootstrapScriptContent(), " +
+  'or getClientEntryUrl with headScripts: "preinit".';
+
 /**
- * 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.
+ * Construction-time guard for {@link resolveBootstrap}: a handler whose deps
+ * can never produce a bootstrap must fail at startup, not 500 per request.
+ * getClientEntryUrl only counts under an explicit `headScripts: "preinit"` —
+ * any other headScripts keeps the inline path, so its presence alone is a
+ * misconfiguration worth flagging rather than silently ignoring.
  */
-function resolveBootstrapOptions(
-  content: string,
-  headScripts: SSRDependencies["headScripts"],
-): Pick<
+function assertBootstrapDeps(deps: SSRDependencies): void {
+  const preinit = deps.headScripts === "preinit";
+  if (deps.getClientEntryUrl && !preinit) {
+    console.warn(
+      '[ssr] getClientEntryUrl is ignored without headScripts: "preinit"; ' +
+        "the inline loadBootstrapScriptContent path is used instead.",
+    );
+  }
+  if (
+    !(preinit && deps.getClientEntryUrl) &&
+    !deps.loadBootstrapScriptContent
+  ) {
+    throw new Error(MISSING_BOOTSTRAP_MSG);
+  }
+}
+
+type BootstrapOptions = 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 };
+>;
+
+/**
+ * Resolve Fizz's bootstrap options from the deps.
+ *
+ * Prefer bootstrapModules over the inline import() bootstrap: with
+ * `headScripts: "preinit"`, getClientEntryUrl() (sync — nothing to race)
+ * short-circuits to bootstrapModules, and inline content that is exactly
+ * `import("<entry-url>")` converts to the URL. 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, 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. The conversion is an explicit opt-in:
+ * undefined headScripts (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.
+ *
+ * With `deadline` (shell capture), the inline load races it: a load that never
+ * resolves within the deadline is the same bounded no-shell degrade as a shell
+ * that never goes quiet — resolves `null`, the caller's degrade sentinel
+ * (disjoint from the load's string). A load that REJECTS is a genuine error
+ * and still propagates. The no-op catch keeps a late rejection off the
+ * unhandledRejection path when the deadline already won; a rejection that
+ * lands first still propagates out.
+ */
+async function resolveBootstrap(
+  deps: SSRDependencies,
+): Promise<BootstrapOptions>;
+async function resolveBootstrap(
+  deps: SSRDependencies,
+  deadline: Promise<void>,
+): Promise<BootstrapOptions | null>;
+async function resolveBootstrap(
+  deps: SSRDependencies,
+  deadline?: Promise<void>,
+): Promise<BootstrapOptions | null> {
+  const preinit = deps.headScripts === "preinit";
+  if (preinit) {
+    // Truthy on purpose, and the ONLY predicate on the URL: an empty string is
+    // an unusable entry URL and falls through to the inline path.
+    const url = deps.getClientEntryUrl?.();
+    if (url) {
+      return { bootstrapModules: [url] };
+    }
+  }
+  if (!deps.loadBootstrapScriptContent) {
+    throw new Error(MISSING_BOOTSTRAP_MSG);
+  }
+  let content: string;
+  if (deadline) {
+    const load = deps.loadBootstrapScriptContent();
+    load.catch(() => {});
+    const raced = await Promise.race([load, deadline.then(() => null)]);
+    if (raced === null) return null;
+    content = raced;
+  } else {
+    content = await deps.loadBootstrapScriptContent();
+  }
+  if (preinit) {
+    const match = BOOTSTRAP_IMPORT_ONLY_RE.exec(content);
+    return match
+      ? { bootstrapModules: [match[2]!] }
+      : { bootstrapScriptContent: content };
   }
-  const match = BOOTSTRAP_IMPORT_ONLY_RE.exec(content);
-  return match
-    ? { bootstrapModules: [match[2]!] }
-    : { bootstrapScriptContent: content };
+  return { bootstrapScriptContent: content };
 }
 
 /**
@@ -476,7 +555,10 @@ function resolveBootstrapOptions(
  * @example
  * ```tsx
  * import { createSSRHandler } from "@rangojs/router/ssr";
- * import { createFromReadableStream } from "@rangojs/router/internal/deps/ssr";
+ * import {
+ *   createFromReadableStream,
+ *   getClientEntryUrl,
+ * } from "@rangojs/router/internal/deps/ssr";
  * import { renderToReadableStream } from "react-dom/server.edge";
  * import { injectRSCPayload } from "@rangojs/router/internal/deps/html-stream-server";
  *
@@ -484,6 +566,17 @@ function resolveBootstrapOptions(
  *   createFromReadableStream,
  *   renderToReadableStream,
  *   injectRSCPayload,
+ *   getClientEntryUrl,
+ *   headScripts: "preinit", // getClientEntryUrl is only used under "preinit"
+ * });
+ * ```
+ *
+ * Custom SSR entries that still use the deprecated bootstrap helper:
+ * ```tsx
+ * export const renderHTML = createSSRHandler({
+ *   createFromReadableStream,
+ *   renderToReadableStream,
+ *   injectRSCPayload,
  *   loadBootstrapScriptContent: () =>
  *     import.meta.viteRsc.loadBootstrapScriptContent("index"),
  * });
@@ -494,9 +587,9 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     createFromReadableStream,
     renderToReadableStream,
     injectRSCPayload,
-    loadBootstrapScriptContent,
     onError,
   } = deps;
+  assertBootstrapDeps(deps);
 
   /**
    * Render RSC stream to HTML stream
@@ -541,8 +634,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
         origin,
       });
 
-      // Get bootstrap script content
-      const bootstrapScriptContent = await loadBootstrapScriptContent();
+      const bootstrap = await resolveBootstrap(deps);
 
       // ssr:false auto-raise (see SSRDependencies.progressiveChunkSize).
       // Awaiting the payload here is latency-neutral: fizz cannot emit even
@@ -563,7 +655,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
       // isolate-global, the nonce per request).
       const htmlStream = await runWithPreinitNonce(nonce, () =>
         renderToReadableStream(<SsrRoot />, {
-          ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+          ...bootstrap,
           formState,
           nonce,
           ...(progressiveChunkSize !== undefined && { progressiveChunkSize }),
@@ -600,8 +692,7 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
 export function createShellCaptureHandler<TEnv = unknown>(
   deps: SSRDependencies<TEnv>,
 ) {
-  const { createFromReadableStream, loadBootstrapScriptContent, prerender } =
-    deps;
+  const { createFromReadableStream, prerender } = deps;
   const onError = deps.onError;
 
   if (!prerender) {
@@ -610,6 +701,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
         "PPR shell capture requires the prerender export; wire it in the SSR virtual entry.",
     );
   }
+  assertBootstrapDeps(deps);
 
   /**
    * Prerender the shell and return the stored artifacts, or null when the
@@ -659,21 +751,10 @@ export function createShellCaptureHandler<TEnv = unknown>(
         origin: opts.origin,
       });
 
-      // Bootstrap load raced against the deadline. A load that never resolves
-      // within maxWaitMs is the same bounded no-shell degrade as a shell that
-      // never goes quiet: return null, do not hang. A load that REJECTS is a
-      // genuine error and still propagates (it is not the deadline). `null` is
-      // the deadline sentinel — disjoint from the load's `Promise<string>`, so
-      // the race narrows to `string | null` with no wrapper. The no-op catch
-      // keeps a late rejection off the unhandledRejection path when the deadline
-      // already won; a rejection that lands first still propagates out.
-      const load = loadBootstrapScriptContent();
-      load.catch(() => {});
-      const bootstrapScriptContent = await Promise.race([
-        load,
-        deadline.promise.then(() => null),
-      ]);
-      if (bootstrapScriptContent === null) {
+      // Bootstrap resolution raced against the deadline (see resolveBootstrap):
+      // null means the deadline won — the bounded no-shell degrade.
+      const bootstrap = await resolveBootstrap(deps, deadline.promise);
+      if (bootstrap === null) {
         return null;
       }
 
@@ -689,7 +770,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
       const abortReason = { rangoShellCaptureAbort: true };
       const prerenderPromise = prerender(<SsrRoot />, {
         signal: controller.signal,
-        ...resolveBootstrapOptions(bootstrapScriptContent, deps.headScripts),
+        ...bootstrap,
         // Explicit option only — the ssr:false auto-raise is live-SSR scoped
         // (RangoBaseOptions.progressiveChunkSize documents the contract); the
         // capture handler starts prerender without deserializing the payload,

package/src/testing/flight.ts

@@ -7,14 +7,15 @@
  * the same react-server-dom serializer the router uses at runtime. It runs in
  * plain node (no Vite, no browser), but ONLY under the `react-server` export
  * condition. The serializer is the VENDORED build shipped with
- * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc` entry top-level
- * imports Vite virtual modules and is not usable outside a Vite build.
+ * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc/server` entry
+ * top-level imports Vite virtual modules and is not usable outside a Vite
+ * build.
  *
  * Run the example/tests for this module via the dedicated rsc vitest project
  * (vitest.rsc.config.ts), which forces `--conditions=react-server` on the
  * worker. The main vitest project must NOT use that condition (it would flip
  * React to the no-hooks server build and break the ~50 tests that mock
- * @vitejs/plugin-rsc/rsc).
+ * @vitejs/plugin-rsc/rsc/server).
  *
  * Scope / limitations (v1):
  * - Server-only / leaf trees. A tree containing a CLIENT component emits an

package/src/testing/vitest-stubs/plugin-rsc.ts

@@ -1,8 +1,9 @@
-// Stub for `@vitejs/plugin-rsc/rsc`, shipped so consumers do not have to write a
-// per-file `vi.mock(...)`. Importing a router internal transitively pulls this
-// module, whose real top-level body imports Vite virtuals that do not resolve in
-// plain node. The unit/integration primitives (dispatch/runLoader/runMiddleware)
-// never render RSC, so empty fns suffice.
+// Stub for `@vitejs/plugin-rsc/rsc` and the split `/rsc/server`, `/rsc/client`
+// entries, shipped so consumers do not have to write a per-file `vi.mock(...)`.
+// Importing a router internal transitively pulls this module, whose real
+// top-level body imports Vite virtuals that do not resolve in plain node. The
+// unit/integration primitives (dispatch/runLoader/runMiddleware) never render
+// RSC, so empty fns suffice.
 export const createFromReadableStream = (): never => {
   throw new Error("plugin-rsc stub: createFromReadableStream not available");
 };
@@ -14,3 +15,10 @@ export const decodeReply = (): undefined => undefined;
 export const decodeAction = (): undefined => undefined;
 export const decodeFormState = (): undefined => undefined;
 export const createTemporaryReferenceSet = (): Record<string, never> => ({});
+export const encodeReply = (): never => {
+  throw new Error("plugin-rsc stub: encodeReply not available");
+};
+export const createClientTemporaryReferenceSet = (): Record<
+  string,
+  never
+> => ({});

package/src/testing/vitest.ts

@@ -18,7 +18,8 @@
  *   `@rangojs/router` specifier to its react-server entry (real impls) while
  *   leaving React as the client build — which is exactly what this helper does.
  * - The build-only `@rangojs/router:version` virtual and `@vitejs/plugin-rsc/rsc`
- *   (whose real body imports unresolvable Vite virtuals) are stubbed.
+ *   plus `/rsc/server`, `/rsc/client` (whose real body imports unresolvable
+ *   Vite virtuals) are stubbed.
  * - Cloudflare apps additionally import the `cloudflare:workers` /
  *   `cloudflare:email` runtime virtuals; pass `{ preset: "cloudflare" }` to stub them.
  *
@@ -126,7 +127,7 @@ export function rangoTestAliases(
       replacement: here("src/testing/vitest-stubs/version.ts"),
     },
     {
-      find: /^@vitejs\/plugin-rsc\/rsc$/,
+      find: /^@vitejs\/plugin-rsc\/rsc(\/(server|client))?$/,
       replacement: here("src/testing/vitest-stubs/plugin-rsc.ts"),
     },
   ];

package/src/vite/plugins/use-cache-transform.ts

@@ -17,6 +17,7 @@
  */
 
 import type { Plugin } from "vite";
+import type { ModuleExportMeta } from "@vitejs/plugin-rsc/transforms";
 import path from "node:path";
 import MagicString from "magic-string";
 import { normalizePath, hashId } from "./expose-id-utils.js";
@@ -89,6 +90,13 @@ export function useCacheTransform(): Plugin {
           return;
         }
 
+        // plugin-rsc 0.5.34 `matchDirective` does `stmt.directive.match(...)`
+        // after `"directive" in node`. Vite/oxc parseAst now emits
+        // `directive: null` on ordinary ExpressionStatements, so a file that
+        // mixes a `"use cache"` function with a sibling handler whose first
+        // statement is an expression throws and the wrap is dropped.
+        stripNullDirectiveFields(ast);
+
         const filePath = normalizePath(path.relative(projectRoot, id));
         const isLayoutOrTemplate = LAYOUT_TEMPLATE_PATTERN.test(id);
 
@@ -101,6 +109,7 @@ export function useCacheTransform(): Plugin {
             isBuild,
             isLayoutOrTemplate,
             transformWrapExport,
+            hasDirective,
           );
         }
 
@@ -131,6 +140,7 @@ function transformFileLevelUseCache(
   isBuild: boolean,
   isLayoutOrTemplate: boolean,
   transformWrapExport: (typeof import("@vitejs/plugin-rsc/transforms"))["transformWrapExport"],
+  hasDirective: (typeof import("@vitejs/plugin-rsc/transforms"))["hasDirective"],
 ) {
   const unconfirmedExports: string[] = [];
 
@@ -140,8 +150,18 @@ function transformFileLevelUseCache(
       return `__rango_registerCachedFunction(${value}, ${JSON.stringify(funcId)}, "default")`;
     },
     rejectNonAsyncFunction: false,
-    filter: (name: string, meta: { isFunction?: boolean }) => {
+    filter: (name: string, meta: ModuleExportMeta) => {
       if (name === "default" && isLayoutOrTemplate) return false;
+      // plugin-rsc 0.5.34 hoists mixed inline `"use server"` out of a
+      // file-level `"use cache"` module as `$$hoist_*` exports and rebinds the
+      // original name to `registerServerReference($$hoist_*, ...)`. Both are
+      // server references, not cached functions. The directive check covers
+      // the pre-hoist shape (this plugin seeing the source first).
+      if (name.startsWith("$$hoist_")) return false;
+      if (isHoistedServerReferenceRebind(meta.valueNode)) return false;
+      if (functionHasUseServerDirective(meta.valueNode, hasDirective)) {
+        return false;
+      }
       // isFunction is boolean | undefined: true = confirmed function, false =
       // confirmed non-function, undefined = cannot tell statically (e.g. a
       // factory/HOF initializer `const x = makeCached(fn)`). Deliberate policy:
@@ -250,6 +270,50 @@ function transformFunctionLevelUseCache(
   }
 }
 
+function stripNullDirectiveFields(node: unknown): void {
+  if (!node || typeof node !== "object") return;
+  const rec = node as Record<string, unknown>;
+  if (rec.type === "ExpressionStatement" && typeof rec.directive !== "string") {
+    delete rec.directive;
+  }
+  for (const value of Object.values(rec)) {
+    if (Array.isArray(value)) {
+      for (const item of value) stripNullDirectiveFields(item);
+    } else if (value && typeof value === "object" && "type" in value) {
+      stripNullDirectiveFields(value);
+    }
+  }
+}
+
+function isHoistedServerReferenceRebind(
+  valueNode: ModuleExportMeta["valueNode"],
+): boolean {
+  if (!valueNode || valueNode.type !== "CallExpression") return false;
+  const first = valueNode.arguments[0];
+  return (
+    first !== undefined &&
+    first.type === "Identifier" &&
+    first.name.startsWith("$$hoist_")
+  );
+}
+
+function functionHasUseServerDirective(
+  valueNode: ModuleExportMeta["valueNode"],
+  hasDirective: (typeof import("@vitejs/plugin-rsc/transforms"))["hasDirective"],
+): boolean {
+  if (!valueNode || !("body" in valueNode)) return false;
+  const { body } = valueNode;
+  if (!body || Array.isArray(body) || body.type !== "BlockStatement") {
+    return false;
+  }
+  // plugin-rsc types valueNode with plain estree nodes but hasDirective with
+  // its oxc-flavored AST; the flavors differ only in position/extra fields.
+  return hasDirective(
+    body.body as Parameters<typeof hasDirective>[0],
+    "use server",
+  );
+}
+
 function findFileLevelDirective(
   ast: any,
 ): { start: number; end: number } | null {

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

@@ -63,18 +63,20 @@ function emitProgressiveChunkSize(value: number): string {
 /**
  * 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.
+ * threads `getClientEntryUrl` so Fizz emits `bootstrapModules`;
+ * "preload" omits the hook and uses the deprecated inline
+ * `loadBootstrapScriptContent` bootstrap.
  */
 export function getVirtualEntrySSR(
   headScripts: HeadScriptsOption = "preinit",
   progressiveChunkSize?: number,
 ): 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.
+  // The preload variant drops the preinit-only imports/install and swaps the
+  // bootstrap dep, all built here so the template below stays a single
+  // unconditional shape.
   const depsImportNames = preinit
-    ? "createFromReadableStream,\n  setOnClientReference,"
+    ? "createFromReadableStream,\n  setOnClientReference,\n  getClientEntryUrl,"
     : "createFromReadableStream,";
   const ssrImportNames = preinit ? "\n  installClientReferencePreinit," : "";
   const install = preinit
@@ -85,6 +87,10 @@ export function getVirtualEntrySSR(
 installClientReferencePreinit(setOnClientReference);
 `
     : "";
+  const bootstrapDep = preinit
+    ? "getClientEntryUrl,"
+    : `loadBootstrapScriptContent: () =>
+    import.meta.viteRsc.loadBootstrapScriptContent("index"),`;
   const hs = JSON.stringify(headScripts);
   // Emitted into all three handlers: live SSR and shell capture consume it
   // directly; the resume handler receives it for dep-shape uniformity (resume()
@@ -114,8 +120,7 @@ export const renderHTML = createSSRHandler({
   renderToReadableStream,
   injectRSCPayload,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 
 export const captureShellHTML = createShellCaptureHandler({
@@ -125,8 +130,7 @@ export const captureShellHTML = createShellCaptureHandler({
   prerender,
   resume,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 
 export const resumeShellHTML = createShellResumeHandler({
@@ -136,8 +140,7 @@ export const resumeShellHTML = createShellResumeHandler({
   prerender,
   resume,
   headScripts: ${hs},${pcs}
-  loadBootstrapScriptContent: () =>
-    import.meta.viteRsc.loadBootstrapScriptContent("index"),
+  ${bootstrapDep}
 });
 `.trim();
 }