@rangojs/router 0.11.0 → 0.12.1

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,9 +112,9 @@ 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`.
+- 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`. The transform's `registerClientReference` import is resolved from `@rangojs/router`'s `@vitejs/plugin-rsc` — the consumer does not need a direct plugin-rsc dependency.
 
 ## See also
 

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.
  *
@@ -75,7 +76,8 @@
  *   a focused include, or use e2e.
  */
 
-import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 /** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
 export interface TestAlias {
@@ -107,6 +109,32 @@ function here(relativeFromRoot: string): string {
   return fileURLToPath(new URL(`../../${relativeFromRoot}`, import.meta.url));
 }
 
+/**
+ * Spec `rangoUseClientTransform` injects into `"use client"` modules. A
+ * consumer app does not depend on `@vitejs/plugin-rsc`, so the bare specifier
+ * is unresolvable from their `"use client"` files (cloudflare-basic
+ * `server-tree.rsc-test.tsx` on plugin-rsc 0.5.34). Resolve it from THIS
+ * module — `@rangojs/router` does depend on plugin-rsc — and alias / inject
+ * the absolute path.
+ */
+const RSD_SERVER_EDGE_SPEC: string =
+  "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+
+const requireFromHere: ReturnType<typeof createRequire> = createRequire(
+  import.meta.url,
+);
+
+function resolveFromRouter(spec: string): string | undefined {
+  try {
+    return requireFromHere.resolve(spec);
+  } catch {
+    return undefined;
+  }
+}
+
+const rsdServerEdgePath: string | undefined =
+  resolveFromRouter(RSD_SERVER_EDGE_SPEC);
+
 /**
  * Build the `resolve.alias` entries a consumer's node/DOM Vitest project needs to
  * import a real @rangojs/router app's router/loaders/middleware. Spread into a
@@ -126,10 +154,16 @@ 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"),
     },
   ];
+  if (rsdServerEdgePath) {
+    aliases.push({
+      find: RSD_SERVER_EDGE_SPEC,
+      replacement: rsdServerEdgePath,
+    });
+  }
 
   if (opts.preset === "cloudflare") {
     aliases.push(
@@ -291,10 +325,13 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
       });
       if (!result) return undefined;
       const { output } = result;
-      // The vendored server serializer is the one renderToFlightString uses;
-      // resolvable here under the react-server condition.
+      // Absolute file URL, not the bare specifier: the consumer's "use client"
+      // module cannot resolve @vitejs/plugin-rsc (it is a router dependency).
+      const rsdHref = rsdServerEdgePath
+        ? pathToFileURL(rsdServerEdgePath).href
+        : RSD_SERVER_EDGE_SPEC;
       output.prepend(
-        `import * as $$RangoRSD from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";\n`,
+        `import * as $$RangoRSD from ${JSON.stringify(rsdHref)};\n`,
       );
       return {
         code: output.toString(),