@rangojs/router 0.16.0 → 0.17.0

package/src/ssr/index.tsx

@@ -27,6 +27,7 @@ interface RenderToReadableStreamOptions {
   nonce?: string;
   formState?: unknown;
   progressiveChunkSize?: number;
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -124,6 +125,13 @@ export interface SSRRenderOptions {
    * prerender pass (host-agnostic bare captures).
    */
   origin?: string;
+
+  /**
+   * Called for each error Fizz reports through its onError: a component that
+   * threw inside a Suspense boundary, which leaves the boundary errored in an
+   * otherwise completed document. React's default console.error is kept.
+   */
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -407,6 +415,12 @@ interface ShellCaptureOptions {
    * capture, resume, and browser hydration.
    */
   origin?: string;
+  /**
+   * Called for each component error the prerender reports (an errored
+   * boundary in the prelude), never for the capture's own abort. The caller
+   * refuses to store the shell (issue #915).
+   */
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -437,6 +451,8 @@ interface ShellResumeOptions {
   search?: string;
   /** The HIT request's origin — same host as the capture's (key-scoped). */
   origin?: string;
+  /** Called for each component error the resumed holes report. */
+  onError?: (error: unknown) => void;
 }
 
 /**
@@ -601,7 +617,14 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
     rscStream: ReadableStream<Uint8Array>,
     options?: SSRRenderOptions,
   ): Promise<ReadableStream<Uint8Array>> {
-    const { nonce, formState, streamMode, search, origin } = options ?? {};
+    const {
+      nonce,
+      formState,
+      streamMode,
+      search,
+      origin,
+      onError: onRenderError,
+    } = options ?? {};
 
     try {
       // Tee the stream:
@@ -659,6 +682,13 @@ export function createSSRHandler<TEnv = unknown>(deps: SSRDependencies<TEnv>) {
           formState,
           nonce,
           ...(progressiveChunkSize !== undefined && { progressiveChunkSize }),
+          ...(onRenderError && {
+            onError: (error: unknown) => {
+              onRenderError(error);
+              // What React's default onError does (it only logs).
+              console.error(error);
+            },
+          }),
         }),
       );
 
@@ -797,6 +827,7 @@ export function createShellCaptureHandler<TEnv = unknown>(
           if (error === abortReason) {
             return;
           }
+          opts.onError?.(error);
           reportRenderError(onError, error);
         },
       });
@@ -877,11 +908,10 @@ export function createShellCaptureHandler<TEnv = unknown>(
 
       // Sanity gate: a prelude with no `<body` is the no-shell failure mode.
       // Return null and store nothing; the request falls back to axis 1 and a
-      // later request re-captures. The dominant real-world cause is a loader
-      // route WITHOUT a route-level loading() boundary: renderSegments' loading-
-      // less branch awaits loader data at TREE-BUILD, so the masked loader pins
-      // the whole tree above <body> (root postpone). Root-postponing layouts and
-      // hung handles degrade the same way. shell-capture.ts logs a once-per-key
+      // later request re-captures. The dominant real-world cause is a masked
+      // live-loader read with no boundary above it (lane rule: see
+      // resolveLoaderData, loader-cache.ts), which root-postpones above
+      // <body>. Root-postponing layouts and hung handles degrade the same way. shell-capture.ts logs a once-per-key
       // warning so the eternal-MISS shape is diagnosable.
       if (!new TextDecoder().decode(prelude).includes("<body")) {
         return null;
@@ -982,7 +1012,10 @@ export function createShellResumeHandler<TEnv = unknown>(
           // resumed stream and need the per-request nonce.
           const resumed = await runWithPreinitNonce(nonce, () =>
             resume(<SsrRoot />, JSON.parse(postponed), {
-              onError: (error) => reportRenderError(onError, error),
+              onError: (error) => {
+                opts.onError?.(error);
+                reportRenderError(onError, error);
+              },
               nonce,
             }),
           );

package/src/static-handler.ts

@@ -21,11 +21,14 @@
  * ```ts
  * export const DocsNav = Static((ctx) => <Nav docs={readDocsSync()} />);
  * export const DocShell = Static((ctx) => <Shell />);
+ * // Prerender/Static must be exported consts; an inline call inside path()
+ * // gets no build-injected $$id and throws.
+ * export const DocPage = Prerender(getParams, DocPageHandler);
  *
  * urls(({ path, layout }) => [
  *   layout(DocsNav, () => [
  *     path("/getting-started", DocShell, { name: "doc.gs" }),
- *     path("/:slug", Prerender(getParams, DocPageHandler)),
+ *     path("/:slug", DocPage),
  *   ]),
  * ]);
  * ```

package/src/testing/flight-runtime.d.ts

@@ -19,6 +19,9 @@ declare module "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge" {
     options?: { onError?: (error: unknown) => string | void },
   ): ReadableStream<Uint8Array>;
 
+  /** Server-side temporary-reference set (a WeakMap). */
+  export function createTemporaryReferenceSet(): unknown;
+
   /**
    * Tag a value as a client reference. Mutates `impl` in place (defining
    * `$$typeof`/`$$id`/`$$async`) and returns it, so a server tree that imports
@@ -55,3 +58,21 @@ declare module "@vitejs/plugin-rsc/core/browser" {
     load: (id: string) => unknown;
   }): void;
 }
+
+/**
+ * The vendored react-server-dom CLIENT build the RSC environment decodes with
+ * (plugin-rsc `react/rsc/client`). The plugin-rsc stub runs the "use cache"
+ * codec on it under the react-server condition.
+ */
+declare module "@vitejs/plugin-rsc/vendor/react-server-dom/client.edge" {
+  export function createFromReadableStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: object,
+  ): Promise<T>;
+  export function encodeReply(
+    value: unknown,
+    options?: object,
+  ): Promise<string | FormData>;
+  /** Client-side temporary-reference set (a Map). */
+  export function createTemporaryReferenceSet(): unknown;
+}

package/src/testing/generated-routes.ts

@@ -158,10 +158,10 @@ export async function diffGeneratedRoutes(
  *
  * @example
  * ```ts
- * import generated from "./router.named-routes.gen";
+ * import { NamedRoutes } from "./router.named-routes.gen";
  * import { router } from "./router";
  *
- * await assertGeneratedRoutesMatch(router, generated);
+ * await assertGeneratedRoutesMatch(router, NamedRoutes);
  * ```
  */
 export async function assertGeneratedRoutesMatch(

package/src/testing/internal/context.ts

@@ -347,7 +347,7 @@ export function buildRunSnapshot<TEnv>(
  *
  * @example
  * ```ts
- * const { result, cookies, response, thrown } = await runInRequestContext(
+ * const { cookies, headers, response, thrown } = await runInRequestContext(
  *   () => loginAction(input), // sets a session cookie, then `throw redirect("/app")`
  *   {
  *     env,

package/src/testing/internal/flight-client-globals.ts

@@ -7,9 +7,11 @@
  * (@vitejs/plugin-rsc `core/plugin.js`). That transform does NOT run in a bare
  * Vitest process, so the vendored client's free `__webpack_require__` /
  * `__webpack_chunk_load__` references would be undefined. We provide minimal
- * shims: `__webpack_require__` routes to the loader installed via
- * `setRequireModule`, and `__webpack_chunk_load__` is a no-op (renderServerTree
- * serializes with empty `chunks`, so no chunk fetch ever happens).
+ * shims: `__webpack_require__` forwards to `__vite_rsc_require__` (the build's
+ * rename), which plugin-rsc's `setRequireModule` installs (core/browser from
+ * renderServerTree, core/rsc from the plugin-rsc stub), and
+ * `__webpack_chunk_load__` is a no-op (the test manifests use empty `chunks`,
+ * so no chunk fetch ever happens).
  *
  * MUST be imported (for side effect) BEFORE `@vitejs/plugin-rsc/react/browser`,
  * which is why flight-tree.ts lists it first.
@@ -17,11 +19,11 @@
 const g = globalThis as unknown as {
   __webpack_require__?: ((id: string) => unknown) & { u?: unknown };
   __webpack_chunk_load__?: (chunkId: string) => Promise<unknown>;
-  __vite_rsc_client_require__?: (id: string) => unknown;
+  __vite_rsc_require__?: (id: string) => unknown;
 };
 
 if (!g.__webpack_require__) {
-  g.__webpack_require__ = (id: string) => g.__vite_rsc_client_require__!(id);
+  g.__webpack_require__ = (id: string) => g.__vite_rsc_require__!(id);
 }
 if (!g.__webpack_chunk_load__) {
   g.__webpack_chunk_load__ = async () => {};

package/src/testing/render-route.tsx

@@ -23,10 +23,13 @@
  *     SEEDED directly into client context (see the `loaders` / `locationState` /
  *     `handles` / `outletPending` options) — nothing is executed on the server.
  *     This exercises the context read path, not the run path.
- *   - navigate() commits synchronously, so it does NOT drive the navigation
- *     lifecycle: useNavigation().state, useLinkStatus().pending, and
- *     useAction().state stay "idle". Assert pending/loading/submitting transition
- *     states with renderServerTree / e2e instead (navigate() warns once if used).
+ *   - navigate() does NOT drive the navigation lifecycle: useNavigation().state,
+ *     useLinkStatus().pending, and useAction().state stay "idle". Assert
+ *     pending/loading/submitting transition states with renderServerTree / e2e
+ *     instead (navigate() warns once if used). The one pending state it does
+ *     model is the held-navigation useLoader().isLoading: a `transition` spec
+ *     plus a pending Promise seeded via navigate(url, { loaders }) commits
+ *     through production's commitInTransition (browser/partial-update.ts).
  * What it DOES cover: client hooks that read NavigationProvider /
  * OutletContext — useParams, useReverse, useHref, useMount, useNavigation,
  * useRouter, usePathname, useSearchParams, Outlet/useOutlet nesting and seeded
@@ -48,7 +51,15 @@ import {
 } from "../browser/navigation-store.js";
 import { createEventController } from "../browser/event-controller.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
-import type { NavigationStore, NavigationBridge } from "../browser/types.js";
+import {
+  commitInTransition,
+  shouldStartViewTransition,
+} from "../browser/partial-update.js";
+import type {
+  NavigationStore,
+  NavigationBridge,
+  UpdateSubscriber,
+} from "../browser/types.js";
 import type { EventController } from "../browser/event-controller.js";
 import type { ResolvedSegment, RscMetadata } from "../browser/types.js";
 import { NavigationProvider } from "../browser/react/NavigationProvider.js";
@@ -57,7 +68,7 @@ import {
   buildParamsFromMatch,
 } from "../router/pattern-matching.js";
 import { normalizeBasename } from "../router/basename.js";
-import type { LoaderDefinition } from "../types.js";
+import type { LoaderDefinition, TransitionConfig } from "../types.js";
 import type { LocationStateDefinition } from "../browser/react/location-state-shared.js";
 import type { Handle } from "../handle.js";
 import type { ThemeConfig } from "../theme/types.js";
@@ -130,6 +141,14 @@ export interface RenderRouteSpec {
   loaderIds?: string[];
   /** Optional route name (informational; not used for matching). */
   name?: string;
+  /**
+   * The `transition()` config this node declares (`{}` for a bare
+   * `transition()`), attached to its segment as the DSL does. Puts the chain in
+   * a transition scope: param-agnostic keys (segment-system.tsx) and a held
+   * navigate() commit, so a pending loader seed passed to
+   * `router.navigate(url, { loaders })` pins `useLoader().isLoading`.
+   */
+  transition?: TransitionConfig;
 }
 
 /**
@@ -303,8 +322,26 @@ export interface TestRouterHandle {
    * updates params + location, and re-renders the segment tree. This is a
    * client-only navigation: no server fetch occurs, so only the components in
    * `routes` can be reached.
+   *
+   * `options.loaders` seeds loader data for THIS navigation, merged over the
+   * render-time seeds (the data a real navigation's response would carry). A
+   * pending Promise suspends the read like a streaming Flight chunk. When a
+   * spec in the chain has `transition`, the commit goes through production's
+   * commitInTransition: the reader stays on screen with
+   * `useLoader().isLoading === true` until the promise settles. Settle it
+   * inside RTL's `act()` to flush the commit. Without `transition` the commit
+   * is urgent and the read suspends to the nearest Suspense boundary.
+   *
+   * @example
+   * await router.navigate("/products/2", { loaders: [[ProductLoader, next]] });
+   * // reader: isLoading true, old data
+   * await act(async () => resolve({ name: "Product 2" }));
+   * // reader: isLoading false, new data
    */
-  navigate(url: string): Promise<void>;
+  navigate(
+    url: string,
+    options?: Pick<RenderRouteOptions, "loaders">,
+  ): Promise<void>;
   /** The current committed pathname. */
   pathname(): string;
   /** The current committed params. */
@@ -413,6 +450,7 @@ function buildSegments(
       belongsToRoute: true,
     };
     if (mount) node.mountPath = mount;
+    if (spec.transition) node.transition = spec.transition;
     if (isLeaf && spec.layout) {
       const Layout = spec.layout;
       node.layout = <Layout />;
@@ -464,10 +502,17 @@ export async function renderRoute(
   const initialUrl = requestUrl ?? staticPrefix(leaf.path) ?? "/";
   const url = new URL(initialUrl, TEST_ORIGIN);
 
-  const loaderData: Record<string, unknown> = { ...(options.loaderData ?? {}) };
-  for (const [loader, data] of options.loaders ?? []) {
-    loaderData[ensureSyntheticId(loader as object, "$$id")] = data;
-  }
+  const seedLoaders = (
+    base: Record<string, unknown>,
+    loaders: RenderRouteOptions["loaders"],
+  ): Record<string, unknown> => {
+    const out = { ...base };
+    for (const [loader, data] of loaders ?? []) {
+      out[ensureSyntheticId(loader as object, "$$id")] = data;
+    }
+    return out;
+  };
+  const loaderData = seedLoaders(options.loaderData ?? {}, options.loaders);
 
   if (typeof window !== "undefined") {
     const stateObj: Record<string, unknown> = {};
@@ -550,25 +595,33 @@ export async function renderRoute(
   );
 
   let warnedNavLifecycle = false;
-  const navigate = async (target: string): Promise<void> => {
-    // renderRoute commits navigations synchronously (no server fetch, no Flight
-    // stream), so it never drives the navigation lifecycle. The transition state
-    // useNavigation()/useLinkStatus()/useAction() read stays "idle" — asserting a
-    // pending/loading/submitting state here proves nothing. Warn once (per render)
-    // under the test runner so that false-confidence trap is loud, not silent.
+  const navigate = async (
+    target: string,
+    navOptions?: Pick<RenderRouteOptions, "loaders">,
+  ): Promise<void> => {
+    // No server fetch, so the navigation lifecycle never starts: the state
+    // useNavigation()/useLinkStatus()/useAction() read stays "idle" — asserting
+    // a pending/loading/submitting state here proves nothing. Warn once (per
+    // render) under the test runner so that false-confidence trap is loud.
     if (isUnderTestRunner() && !warnedNavLifecycle) {
       warnedNavLifecycle = true;
       console.warn(
-        "renderRoute: navigate()/useRouter().push commit synchronously and do " +
-          "NOT drive the navigation lifecycle. useNavigation().state, " +
-          'useLinkStatus().pending, and useAction().state stay "idle" here. ' +
-          "Assert params/pathname/content after navigate(); use renderServerTree " +
-          "or e2e to assert pending/loading/submitting transition states.",
+        "renderRoute: navigate()/useRouter().push do NOT drive the navigation " +
+          "lifecycle. useNavigation().state, useLinkStatus().pending, and " +
+          'useAction().state stay "idle" here. Assert params/pathname/content ' +
+          "after navigate(); use renderServerTree or e2e to assert " +
+          "pending/loading/submitting transition states. A held " +
+          "useLoader().isLoading is modeled: see navigate(url, { loaders }).",
       );
     }
     const nextUrl = new URL(target, TEST_ORIGIN);
     const match = resolve(nextUrl.pathname);
-    const segments = buildSegments(routes, match.params, loaderData, mount);
+    const segments = buildSegments(
+      routes,
+      match.params,
+      seedLoaders(loaderData, navOptions?.loaders),
+      mount,
+    );
     const metadata = makeMetadata(nextUrl.pathname, segments, match.params);
     const root = await renderSegments(segments, {
       outletPending: options.outletPending,
@@ -577,8 +630,16 @@ export async function renderRoute(
     eventController.setParams(match.params);
     store.setCurrentUrl(nextUrl.href);
     store.setSegmentIds(segments.map((s) => s.id));
+    const emit: UpdateSubscriber = (update) => store.emitUpdate(update);
     await act(async () => {
-      store.emitUpdate({ root, metadata });
+      // Production's transition() lane (browser/partial-update.ts). Its
+      // same-structure / fully-prefetched / optimistic hold lanes are not
+      // modeled: without transition() the commit stays urgent.
+      if (shouldStartViewTransition(segments)) {
+        commitInTransition(emit, segments, { root, metadata }, ["navigation"]);
+      } else {
+        emit({ root, metadata });
+      }
     });
   };
 

package/src/testing/run-loader.ts

@@ -38,6 +38,7 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { createReverseFunction } from "../router/handler-context.js";
+import { NOCACHE_SYMBOL } from "../cache/taint.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import type { LoaderContext, LoaderDefinition } from "../types.js";
 import type { ContextVar } from "../context-var.js";
@@ -268,7 +269,7 @@ function runWithLoaderContext<R>(
           );
         }) as TestLoaderContext["reverse"]);
 
-    const loaderCtx: TestLoaderContext = {
+    const loaderCtx: TestLoaderContext & { _routeName?: string } = {
       params: opts.params ?? {},
       routeParams: (opts.params ?? {}) as Record<string, string>,
       request: reqCtx.request,
@@ -324,6 +325,7 @@ function runWithLoaderContext<R>(
       body: opts.body,
       formData: opts.formData,
       reverse: reverse as TestLoaderContext["reverse"],
+      _routeName: reqCtx._routeName,
       rendered:
         opts.rendered !== undefined && opts.rendered !== false
           ? async () => {
@@ -344,6 +346,8 @@ function runWithLoaderContext<R>(
             },
     };
 
+    // Request-scoped for "use cache" keys, as production brands it (#940).
+    (loaderCtx as Record<symbol, unknown>)[NOCACHE_SYMBOL] = true;
     return fn(loaderCtx);
   });
 }

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

@@ -1,24 +1,127 @@
-// 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");
-};
-export const renderToReadableStream = (): never => {
-  throw new Error("plugin-rsc stub: renderToReadableStream not available");
-};
+/// <reference path="../flight-runtime.d.ts" />
+/**
+ * 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(...)`.
+ * The real entries top-level import Vite virtuals that do not resolve in plain
+ * node.
+ *
+ * Under the `react-server` condition (the Flight project) the "use cache"
+ * codec runs on real Flight: the vendored react-server-dom `server.edge` /
+ * `client.edge` builds that plugin-rsc's `react/rsc/server` and
+ * `react/rsc/client` wrap, with the same manifests and the same server-side
+ * reference loader (`@vitejs/plugin-rsc/core/rsc` `setRequireModule`), so
+ * keys, writes, hits, value round trips and error rows match a build. The
+ * wrappers are not reused: their manifests read `import.meta.env.DEV`, which
+ * is undefined in a module node loads directly (vitest externalizes
+ * node_modules).
+ *
+ * Without the condition React's server build refuses to load, so the codec
+ * functions throw and a "use cache" call runs uncached. Any other load failure
+ * (a moved vendored path, a missing peer) throws. The action entries stay
+ * inert either way: no primitive decodes an action request.
+ */
+
+/** React's server build throws this on load without the react-server condition. */
+const MISSING_REACT_SERVER_CONDITION =
+  /"react-server" condition must be enabled/;
+
+async function loadFlightRuntime() {
+  // The server build first, alone. `@vitejs/plugin-rsc/core/rsc` statically
+  // imports it, and importing that ESM module after the CJS build failed to
+  // load leaks an unhandled rejection from Node's module loader even when every
+  // import() is caught (Node 22 and 24). So core/rsc loads only once the server
+  // build has.
+  const server =
+    await import("@vitejs/plugin-rsc/vendor/react-server-dom/server.edge").catch(
+      (error: unknown) => {
+        if (
+          error instanceof Error &&
+          MISSING_REACT_SERVER_CONDITION.test(error.message)
+        ) {
+          return undefined;
+        }
+        throw error;
+      },
+    );
+  if (!server) return undefined;
+  const [client, core] = await Promise.all([
+    import("@vitejs/plugin-rsc/vendor/react-server-dom/client.edge"),
+    import("@vitejs/plugin-rsc/core/rsc"),
+  ]);
+  await import("../internal/flight-client-globals.js");
+  // Resolves the `$$decode-client:` / `$$preserve:` ids a cached value's client
+  // and server references decode to; any other id would load a server module.
+  core.setRequireModule({
+    load: (id) => {
+      throw new Error(
+        `plugin-rsc stub: server reference module "${id}" is not loadable in a test`,
+      );
+    },
+  });
+  return { server, client, core };
+}
+
+const runtime = await loadFlightRuntime();
+
+/** `<module id>#<export name>` -> manifest entry, as plugin-rsc builds it. */
+function referenceManifest(prefix: string): Record<string, unknown> {
+  return new Proxy(
+    {},
+    {
+      get(_target, $$id) {
+        if (typeof $$id !== "string") return undefined;
+        const [id, name] = $$id.split("#");
+        return { id: prefix + id, name, chunks: [], async: true };
+      },
+    },
+  );
+}
+
+const CLIENT_MANIFEST = referenceManifest("");
+
+function unavailable(name: string): never {
+  throw new Error(
+    `plugin-rsc stub: ${name} needs the react-server condition (the Flight test project)`,
+  );
+}
+
+export const renderToReadableStream = (
+  value: unknown,
+  options?: object,
+): ReadableStream<Uint8Array> =>
+  runtime
+    ? runtime.server.renderToReadableStream(value, CLIENT_MANIFEST, options)
+    : unavailable("renderToReadableStream");
+export const createTemporaryReferenceSet = (): unknown =>
+  runtime ? runtime.server.createTemporaryReferenceSet() : {};
+export const createFromReadableStream = (
+  stream: ReadableStream<Uint8Array>,
+  options?: object,
+  extraOptions?: { preserveServerReferences?: boolean },
+): Promise<unknown> =>
+  runtime
+    ? runtime.client.createFromReadableStream(stream, {
+        serverConsumerManifest: {
+          serverModuleMap: referenceManifest(
+            extraOptions?.preserveServerReferences
+              ? "$$server:$$preserve:"
+              : "$$server:",
+          ),
+          moduleMap: runtime.core.createServerDecodeClientManifest(),
+        },
+        ...options,
+      })
+    : unavailable("createFromReadableStream");
+export const encodeReply = (
+  value: unknown,
+  options?: object,
+): Promise<string | FormData> =>
+  runtime
+    ? runtime.client.encodeReply(value, options)
+    : unavailable("encodeReply");
+export const createClientTemporaryReferenceSet = (): unknown =>
+  runtime ? runtime.client.createTemporaryReferenceSet() : {};
 export const loadServerAction = (): undefined => undefined;
 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

@@ -78,6 +78,10 @@
 
 import { createRequire } from "node:module";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  isUseCacheCandidate,
+  transformUseCache,
+} from "../vite/plugins/use-cache-transform.js";
 
 /** A single Vite/Vitest resolve alias entry. Structurally a Vite `Alias`. */
 export interface TestAlias {
@@ -262,6 +266,7 @@ interface FlightTransformPlugin {
  * import { defineConfig } from "vitest/config";
  * import {
  *   rangoUseClientTransform,
+ *   rangoUseCacheTransform,
  *   rangoTestAliases,
  *   rangoInlineDeps,
  * } from "@rangojs/router/testing/vitest";
@@ -271,7 +276,7 @@ interface FlightTransformPlugin {
  * process.env.NODE_ENV = "production";
  *
  * export default defineConfig({
- *   plugins: [rangoUseClientTransform()],
+ *   plugins: [rangoUseClientTransform(), rangoUseCacheTransform()],
  *   resolve: {
  *     conditions: ["react-server"],
  *     // Bare `@rangojs/router` -> its react-server build, so a handler/component
@@ -340,3 +345,59 @@ export function rangoUseClientTransform(): FlightTransformPlugin {
     },
   };
 }
+
+/** The Vite plugin shape {@link rangoUseCacheTransform} returns. */
+interface UseCacheTransformPlugin {
+  name: string;
+  enforce: "post";
+  configResolved(config: { root: string }): void;
+  transform(
+    this: { warn(message: string): void },
+    code: string,
+    id: string,
+  ): Promise<{ code: string; map: unknown } | undefined>;
+}
+
+/**
+ * A Vite plugin that applies the rango plugin's `"use cache"` transform in a
+ * Vitest project, so a function written with the directive is wrapped with
+ * `registerCachedFunction` as in dev and a build. `rango()` runs that transform
+ * only in its `rsc` environment and Vitest transforms in `ssr`, so without this
+ * plugin the directive is an inert string and the function runs on every call.
+ *
+ * Add it to the react-server project next to {@link rangoUseClientTransform}
+ * (see that function's config). There, with a seeded `cacheStore`,
+ * `renderHandler` / `runLoader` observe real hits. In the node project the
+ * wrap applies too, but the stubbed Flight serializer cannot write an entry.
+ *
+ * Ids are the ones `vite dev` emits: `<path relative to the Vitest root>#<name>`
+ * (a function-level directive gives `src/data.ts#$$hoist_0_getData`), not the
+ * build's hashed path, so store keys stay readable. `configResolved` sets that
+ * root. If `@vitejs/plugin-rsc/transforms` fails to load, the transform throws
+ * instead of leaving the module unwrapped (which the rango plugin does).
+ */
+export function rangoUseCacheTransform(): UseCacheTransformPlugin {
+  let root = process.cwd();
+  return {
+    name: "rango:testing-use-cache",
+    enforce: "post",
+    configResolved(config) {
+      root = config.root;
+    },
+    async transform(code, id) {
+      if (!isUseCacheCandidate(code, id)) return undefined;
+      return transformUseCache(code, id, {
+        root,
+        isBuild: false,
+        warn: (message) => this.warn(message),
+        onTransformsError: (error) => {
+          throw new Error(
+            `rangoUseCacheTransform: @vitejs/plugin-rsc/transforms failed to ` +
+              `load, so "use cache" functions in ${id} would run unwrapped.`,
+            { cause: error },
+          );
+        },
+      });
+    },
+  };
+}