@rangojs/router 0.22.1 → 0.24.0

package/src/testing/internal/client-urls-projection.ts

@@ -0,0 +1,70 @@
+import {
+  projectClientUrlsModule,
+  setClientUrlProjection,
+  type ClientUrlProjection,
+} from "../../client-urls/server-projection.js";
+import { isHoistedRevalidateRef } from "../../client-urls/hoisted-revalidate.js";
+import { registerClientUrlRevalidators } from "../../client-urls/revalidate-registry.js";
+import type { ClientUrlPatterns } from "../../client-urls/types.js";
+import type { ShouldRevalidateFn } from "../../types.js";
+
+/**
+ * Install the projection of a `"use client"` clientUrls() module under its
+ * client reference id, as discovery installs it for an app
+ * (discoverClientUrlProjections in vite/discovery/client-urls-projection.ts):
+ * the same projection step, into the same registry include() materializes
+ * from. rangoUseClientTransform (testing/vitest.ts) appends a call to every
+ * such module, passing the module's own source evaluated without the
+ * transform, so a router under test mounts the group with no setup.
+ *
+ * A Vitest project runs no hoist plugin, so the source's revalidate()
+ * predicates are plain functions. Each is registered under a key named for
+ * its reference, route and loader, as the plugin's generated module registers
+ * its own, and the projection carries the keys: materialization attaches them
+ * and the server runs them, as in an app.
+ */
+export function installClientUrlsProjection(
+  referenceId: string,
+  source: Readonly<Record<string, unknown>>,
+): void {
+  const projection = projectClientUrlsModule(source);
+  if (!projection) {
+    throw new Error(
+      `Cannot install the client URL projection for reference "${referenceId}": ` +
+        'the module default export must be created by clientUrls() and have __brand === "client-urls"',
+    );
+  }
+  setClientUrlProjection(
+    referenceId,
+    withRevalidateKeys(
+      referenceId,
+      source.default as ClientUrlPatterns,
+      projection,
+    ),
+  );
+}
+
+function withRevalidateKeys(
+  referenceId: string,
+  definition: ClientUrlPatterns,
+  projection: ClientUrlProjection,
+): ClientUrlProjection {
+  const fns: Record<string, ShouldRevalidateFn<any, any>> = {};
+  const routes = projection.routes.map((route) => {
+    const record = definition.routes.find(({ id }) => id === route.id);
+    const loaderRevalidate = (record?.loaders ?? []).map(
+      ({ revalidate }, loaderIndex) =>
+        revalidate.map((entry, index) => {
+          if (isHoistedRevalidateRef(entry)) return entry.$$rangoRevalidate;
+          const key = `${referenceId}:${route.id}:${loaderIndex}:${index}`;
+          fns[key] = entry;
+          return key;
+        }),
+    );
+    return loaderRevalidate.some((keys) => keys.length > 0)
+      ? { ...route, loaderRevalidate }
+      : route;
+  });
+  registerClientUrlRevalidators(fns);
+  return { ...projection, routes };
+}

package/src/testing/internal/test-action.ts

@@ -0,0 +1,25 @@
+import * as RSDServer from "@vitejs/plugin-rsc/vendor/react-server-dom/server.edge";
+import { registerServerModule } from "./server-modules.js";
+
+/**
+ * Register `action` under its reference id, `<module id>#<export name>`,
+ * tagged as a server reference like a built "use server" export so it keeps
+ * its `$$id`, where the plugin-rsc stub's decodeAction / loadServerAction
+ * resolve it. `primitive` names the caller in the error for a malformed id.
+ * Loads the react-server build: callers run under the react-server condition.
+ */
+export function registerTestAction(
+  action: (...args: any[]) => unknown,
+  id: string,
+  primitive: string,
+): void {
+  const [moduleId, name] = id.split("#");
+  if (!moduleId || !name) {
+    throw new Error(
+      `${primitive}: id must be "<module id>#<export name>", received ${JSON.stringify(id)}`,
+    );
+  }
+  registerServerModule(moduleId, {
+    [name]: RSDServer.registerServerReference(action, moduleId, name),
+  });
+}

package/src/testing/render-route.tsx

@@ -382,6 +382,14 @@ export interface RenderRouteOptions {
    * - Needs @testing-library/react >= 16.2.0; throws on older versions.
    */
   hydrate?: boolean;
+  /**
+   * The path middleware rewrote `request` to (`throw rewrite()`): the leaf
+   * route is matched against it for params, while the location stays
+   * `request`, as on a rewritten document. The server pass and hydration
+   * both see `request` (`usePathname()`, `useSearchParams()`), as production
+   * renders a rewritten page with the visitor's URL (`/middleware` skill).
+   */
+  rewrite?: string;
 }
 
 /**
@@ -687,7 +695,12 @@ export async function renderRoute(
       pathname,
     };
   };
-  const initialMatch = resolve(url.pathname);
+  // A rewritten request renders the target's route at the visitor's URL.
+  const renderedPathname =
+    options.rewrite === undefined
+      ? url.pathname
+      : new URL(options.rewrite, url).pathname;
+  const initialMatch = resolve(renderedPathname);
 
   const historyKey = generateHistoryKey(url.href);
   const mount = normalizeBasename(options.mount);
@@ -706,10 +719,10 @@ export async function renderRoute(
     options.request !== undefined &&
     Object.keys(options.params ?? {}).length === 0 &&
     isUnderTestRunner() &&
-    matchLeaf(leaf.path, url.pathname) === null
+    matchLeaf(leaf.path, renderedPathname) === null
   ) {
     throw new Error(
-      `renderRoute: request "${url.pathname}" does not match the leaf route ` +
+      `renderRoute: request "${renderedPathname}" does not match the leaf route ` +
         `"${leaf.path}"${mount ? ` (mount "${mount}")` : ""}. renderRoute paths ` +
         `are include-RELATIVE: pass a request that matches "${leaf.path}" ` +
         `(e.g. "${staticPrefix(leaf.path)}"). A mount does NOT auto-rewrite the ` +

package/src/testing/run-loader.ts

@@ -20,8 +20,9 @@
  * - `ctx.reverse()` throws unless `routeMap` is provided (it does NOT fall back
  *   to the global route map — that would leak whichever routes another test
  *   registered).
- * - `ctx.use(handle)` follows the production rule: reading a handle before
+ * - `ctx.get(handle)` follows the production rule: reading a handle before
  *   `await ctx.rendered()` throws (pass `rendered` to mock the barrier).
+ *   `ctx.use(handle)` is the push and needs no barrier.
  * - `use cache` functions only cache (and only fire their taint/profile guards)
  *   when a `cacheStore` is provided — without one, registerCachedFunction
  *   bypasses (it checks for a store first). Pass `cacheStore`/`cacheProfiles`
@@ -39,6 +40,7 @@ import {
 } from "../server/request-context.js";
 import { createReverseFunction } from "../router/handler-context.js";
 import { NOCACHE_SYMBOL } from "../cache/taint.js";
+import { defineRewrittenFrom } from "../server/rewrite-trail.js";
 import { getFetchableLoader } from "../server/fetchable-loader-store.js";
 import type { LoaderContext, LoaderDefinition } from "../types.js";
 import type { ContextVar } from "../context-var.js";
@@ -365,6 +367,7 @@ function runWithLoaderContext<R>(
     };
 
     // Request-scoped for "use cache" keys, as production brands it (#940).
+    defineRewrittenFrom(loaderCtx, reqCtx);
     (loaderCtx as Record<symbol, unknown>)[NOCACHE_SYMBOL] = true;
     return fn(loaderCtx);
   });

package/src/testing/run-middleware.ts

@@ -13,6 +13,10 @@
  *
  * `nextCalled` counts how many times the terminal `next()` (the finalHandler)
  * ran: 0 when the chain short-circuited, 1 when it ran to completion.
+ *
+ * A `throw rewrite(target)` is reported as `result.rewrite` (the resolved
+ * target) instead of failing the run: production re-dispatches the request
+ * there, which this primitive does not do.
  */
 
 import {
@@ -31,6 +35,9 @@ import {
   type StateCookieSeed,
 } from "./internal/context.js";
 import type { ThemeConfig } from "../theme/types.js";
+import { isRewrite } from "../route-definition/rewrite.js";
+import { resolveRewriteTarget } from "../rsc/rewrite-passes.js";
+import { getGlobalRouteMap } from "../route-map-builder.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { CacheProfile } from "../cache/profile-registry.js";
 
@@ -94,6 +101,13 @@ export interface RunMiddlewareOptions<TEnv = any> {
   stateCookie?: StateCookieSeed;
 }
 
+/** A rewrite the chain threw (RunMiddlewareResult.rewrite). */
+export interface RunMiddlewareRewrite {
+  pathname: string;
+  search: string;
+  routeName?: string;
+}
+
 /**
  * Result of runMiddleware.
  */
@@ -109,6 +123,16 @@ export interface RunMiddlewareResult<TEnv = any> {
   ctx: RequestContext<TEnv>;
   /** Number of times the terminal handler ran (0 = short-circuited, 1 = passed through). */
   nextCalled: number;
+  /**
+   * The target of a `throw rewrite(...)` from the chain, resolved as
+   * production resolves it (a path basename-prefixed, a route name through
+   * `routeMap`): `pathname` and `search` of the URL the request would render,
+   * and `routeName` when the rewrite named a route. `undefined` when the chain
+   * did not rewrite. On a rewrite, `response` carries what the chain set
+   * before the throw (status, headers, cookies), which production keeps for
+   * the target's response.
+   */
+  rewrite?: RunMiddlewareRewrite;
   /**
    * Whether the chain called `ctx.dynamic()` (the PPR shell opt-out). The public
    * way to assert the opt-out without reading the `@internal` `ctx._dynamic`.
@@ -192,17 +216,37 @@ export async function runMiddleware<TEnv = any>(
       reverse as RequestContext<TEnv>["reverse"];
   }
 
-  const response = await runWithRequestContext(ctx, () =>
-    executeLoaderMiddleware<TEnv>(
-      mwArray,
-      builtRequest,
-      (opts.env ?? {}) as TEnv,
-      opts.params ?? {},
-      variables,
-      finalHandler,
-      reverse,
-    ),
-  );
+  let rewrite: RunMiddlewareRewrite | undefined;
+  const response = await runWithRequestContext(ctx, async () => {
+    try {
+      return await executeLoaderMiddleware<TEnv>(
+        mwArray,
+        builtRequest,
+        (opts.env ?? {}) as TEnv,
+        opts.params ?? {},
+        variables,
+        finalHandler,
+        reverse,
+      );
+    } catch (error) {
+      if (!isRewrite(error)) throw error;
+      const target = resolveRewriteTarget(
+        error,
+        opts.routeMap ?? getGlobalRouteMap(),
+        new URL(builtRequest.url),
+        ctx._basename,
+      );
+      rewrite = {
+        pathname: target.pathname,
+        search: target.search,
+        ...("name" in error.target && { routeName: error.target.name }),
+      };
+      return new Response(null, {
+        status: ctx.res.status,
+        headers: ctx.res.headers,
+      });
+    }
+  });
 
   const { cookies, locationState } = snapshotRunEffects(ctx);
   const headers = headersToObject(response.headers);
@@ -210,6 +254,7 @@ export async function runMiddleware<TEnv = any>(
     response,
     ctx,
     nextCalled,
+    ...(rewrite && { rewrite }),
     dynamic: ctx._dynamic === true,
     cookies,
     headers,

package/src/testing/run-revalidate.ts

@@ -0,0 +1,142 @@
+/**
+ * runRevalidate — unit-test revalidate() predicates: a urls() segment's, or a
+ * clientUrls() loader's (which the build moves to the server, where it runs
+ * the same way).
+ *
+ * Evaluates the predicate(s) through the router's own evaluateRevalidation
+ * (router/revalidation.ts) inside a seeded request context: the default
+ * decision, the argument object, boolean short-circuit, soft-verdict
+ * threading and the fail-open on a throw are the production code paths, not
+ * a re-implementation. Pass an array to test a chain in declaration order.
+ */
+
+import { evaluateRevalidation } from "../router/revalidation.js";
+import { runWithRequestContext } from "../server/request-context.js";
+import type { ResolvedSegment, ShouldRevalidateFn } from "../types.js";
+import {
+  normalizeTestAction,
+  resolveTestActionId,
+  type ImportedAction,
+} from "./internal/action-id.js";
+import { createTestRequestContext } from "./internal/context.js";
+import type { VarsInit } from "./internal/seed-vars.js";
+import { toURL } from "./to-url.js";
+
+type RevalidateArgs = Parameters<ShouldRevalidateFn<any, any>>[0];
+
+/** The action fields a predicate receives on an action request. */
+export interface RunRevalidateAction {
+  /** The triggering action: an imported server action or its actionId. */
+  ref?: ImportedAction | string;
+  /** `actionResult`: the action's return value. */
+  result?: unknown;
+  /** `formData`: the action's FormData argument. */
+  formData?: FormData;
+  /** `actionUrl`. Defaults to `currentUrl`. */
+  url?: string | URL;
+}
+
+/**
+ * Options for {@link runRevalidate}. Defaults model a same-URL navigation
+ * with no action, for a route-owned loader segment.
+ */
+export interface RunRevalidateOptions<TEnv = any> {
+  /** The page being left. Defaults to `http://localhost/`. */
+  currentUrl?: string | URL;
+  /** The destination. Defaults to `currentUrl`. */
+  nextUrl?: string | URL;
+  currentParams?: Record<string, string>;
+  /** Defaults to `currentParams`. */
+  nextParams?: Record<string, string>;
+  /**
+   * The triggering action: an imported server action (id via
+   * `$id ?? $$id`), an actionId string, or `{ ref, result, formData, url }`.
+   * Makes the request a POST, as an action request is.
+   */
+  action?: ImportedAction | string | RunRevalidateAction;
+  /** Overrides the request method (`POST` with `action`, else `GET`). */
+  method?: string;
+  /** The segment the predicate is attached to. Defaults to `"loader"`. */
+  segmentType?: RevalidateArgs["segmentType"];
+  /**
+   * The segment belongs to the matched route (a route's own loaders, a
+   * clientUrls() group loader). Defaults to true; false models a layout's
+   * loader, which a navigation keeps by default.
+   */
+  belongsToRoute?: boolean;
+  /** `stale`: a history-entry background revalidation. */
+  stale?: boolean;
+  /** `toRouteName` (and `routeName`). */
+  routeName?: string;
+  /** `fromRouteName`. */
+  fromRouteName?: string;
+  /** Environment bindings of the seeded context. */
+  env?: TEnv;
+  /** Variables a middleware would have set, readable with `context.get()`. */
+  vars?: VarsInit;
+  /** `context`, in place of the seeded request context. */
+  context?: RevalidateArgs["context"];
+}
+
+const DEFAULT_URL = "http://localhost/";
+
+/**
+ * Run one revalidate() predicate, or a chain in declaration order, the way
+ * the router does for a request. Resolves to the final decision: true
+ * re-runs the segment, false keeps the client's copy.
+ */
+export async function runRevalidate<TEnv = any>(
+  fn: ShouldRevalidateFn<any, TEnv> | readonly ShouldRevalidateFn<any, TEnv>[],
+  opts: RunRevalidateOptions<TEnv> = {},
+): Promise<boolean> {
+  const currentUrl = toURL(opts.currentUrl, new URL(DEFAULT_URL));
+  const nextUrl = toURL(opts.nextUrl, currentUrl);
+  const currentParams = opts.currentParams ?? {};
+  const nextParams = opts.nextParams ?? currentParams;
+  const action = normalizeTestAction(opts.action);
+  const method = opts.method ?? (action ? "POST" : "GET");
+  const request = new Request(nextUrl, { method });
+  const { ctx } = createTestRequestContext<TEnv>({
+    env: opts.env,
+    request,
+    vars: opts.vars,
+    params: nextParams,
+  });
+  if (opts.fromRouteName !== undefined) ctx._prevRouteKey = opts.fromRouteName;
+
+  const segment: ResolvedSegment = {
+    id: "runRevalidate",
+    namespace: "runRevalidate",
+    type: opts.segmentType ?? "loader",
+    index: 0,
+    component: null,
+    params: nextParams,
+    belongsToRoute: opts.belongsToRoute ?? true,
+  };
+  const fns = Array.isArray(fn) ? fn : [fn];
+  return runWithRequestContext(ctx as never, () =>
+    evaluateRevalidation({
+      segment,
+      prevParams: currentParams,
+      getPrevSegment: null,
+      request,
+      prevUrl: currentUrl,
+      nextUrl,
+      revalidations: fns.map((entry, index) => ({
+        name: `runRevalidate#${index}`,
+        fn: entry,
+      })),
+      routeKey: opts.routeName ?? "",
+      context: (opts.context ?? ctx) as RevalidateArgs["context"],
+      actionContext: action
+        ? {
+            actionId: resolveTestActionId(action.ref, "runRevalidate") ?? "",
+            actionUrl: toURL(action.url, currentUrl),
+            actionResult: action.result,
+            formData: action.formData,
+          }
+        : undefined,
+      stale: opts.stale ?? false,
+    }),
+  );
+}

package/src/testing/run-transition-when.ts

@@ -22,7 +22,11 @@ import {
   resolveNavigationState,
 } from "../browser/history-state.js";
 import { isLocationStateEntry } from "../browser/react/location-state-shared.js";
-import { resolveTestActionId } from "./internal/action-id.js";
+import {
+  normalizeTestAction,
+  resolveTestActionId,
+  type ImportedAction,
+} from "./internal/action-id.js";
 import type {
   RouteLocation,
   TransitionConfig,
@@ -31,8 +35,6 @@ import type {
   TransitionWhenKind,
 } from "../types/segments.js";
 
-type ImportedAction = (...args: never[]) => unknown;
-
 /** A navigation side: a URL, or a partial RouteLocation. */
 export type RunTransitionWhenLocation =
   | string
@@ -58,7 +60,7 @@ export interface RunTransitionWhenOptions {
   /** The destination. Defaults to `from`; always `from` for "action" and "revalidate". */
   to?: RunTransitionWhenLocation;
   /**
-   * The triggering action (like runClientRevalidate's): an imported server
+   * The triggering action (like runRevalidate's): an imported server
    * action (id via `$id ?? $$id`), an actionId string, or
    * `{ ref, formData, result, error }`.
    */
@@ -105,10 +107,7 @@ export function runTransitionWhen(
   whenOrConfig: TransitionWhenFn | TransitionConfig,
   opts: RunTransitionWhenOptions = {},
 ): RunTransitionWhenResult {
-  const actionOption =
-    typeof opts.action === "function" || typeof opts.action === "string"
-      ? { ref: opts.action }
-      : opts.action;
+  const actionOption = normalizeTestAction(opts.action);
   const from = toLocation(opts.from, DEFAULT_URL);
   const context = createTransitionWhenContext({
     kind: opts.kind ?? (actionOption ? "action" : "push"),

package/src/testing/serve-shell-request.ts

@@ -29,7 +29,8 @@
  *
  * A `Prerender` route serves its handler layer from the artifact
  * `router.matchForPrerender` bakes for the URL (on its first request, kept
- * until resetShellTestState), through the production prerender store. Its
+ * until resetShellTestState), through the production prerender store; an
+ * intercept of it serves from the intercept variant the bake keeps. Its
  * first `ppr` request is a MISS with a runtime capture, as a URL without a
  * build-time shell is in production; build-time shells are e2e-only. An
  * on-demand route (`Prerender(..., { onDemand })`) bakes nothing here: it
@@ -57,7 +58,9 @@ import {
   SHELL_CAPTURE_MAX_WAIT_MS,
 } from "../rsc/shell-capture-constants.js";
 import { SEGMENT_FRAGMENT_CAPABILITY_HEADER } from "../segment-fragments.js";
+import { FILL_PARAM, PREFETCH_HEADER } from "../prefetch-markers.js";
 import { resolveDeferredHandleValues } from "../handles/deferred-resolution.js";
+import { withoutPushedBy } from "../handles/pushed-by.js";
 import type { HandleData } from "../server/handle-store.js";
 import { _getRequestContext } from "../server/request-context.js";
 import {
@@ -88,8 +91,22 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * of a document GET: from `from` (default `/`) with `segments` mounted
    * (default none), advertising fragment passthrough. The replay decision is
    * `result.replayStatus`.
+   *
+   * `prefetch: true` sends it as a `<Link>` prefetch does (the
+   * `X-Rango-Prefetch` header), so `prefetch: false` loaders and `loading()`
+   * entries are deferred: `result.readDeferred()` lists them. `fill: true`
+   * sends the request the browser follows an adopted prefetch with
+   * (`_rsc_fill`): pass the ids the prefetch delivered, without the deferred
+   * ones, as `segments`, and the same URL as `from`.
    */
-  partial?: true | { from?: string; segments?: readonly string[] };
+  partial?:
+    | true
+    | {
+        from?: string;
+        segments?: readonly string[];
+        prefetch?: boolean;
+        fill?: boolean;
+      };
   /**
    * POST this form as a submit before hydration: the no-JS request the
    * progressive-enhancement path runs the action for and re-renders the page
@@ -98,6 +115,30 @@ export interface ServeShellRequestOptions<TEnv = any> {
    * Not with `partial`.
    */
   form?: FormData;
+  /**
+   * Send the request a JS server action call makes from the page at `url`:
+   * a POST of `args` (encoded as the browser encodes them) for `ref`, with
+   * the page's mounted `segments` (default none), as
+   * browser/server-action-bridge.ts sends it. The response is the action's
+   * Flight payload (its return value and the re-rendered segments).
+   * Not with `partial` or `form`.
+   */
+  action?: ServeShellRequestAction;
+}
+
+/** The JS server action call of {@link ServeShellRequestOptions.action}. */
+export interface ServeShellRequestAction {
+  /** The server action. */
+  ref: (...args: any[]) => unknown;
+  /**
+   * Its reference id, `<module id>#<export name>`, as the build gives a
+   * "use server" export; registered so the handler loads `ref` by it.
+   */
+  id: string;
+  /** The arguments the page calls it with. */
+  args?: readonly unknown[];
+  /** The segment ids the page holds (`_rsc_segments`). */
+  segments?: readonly string[];
 }
 
 /** A response's handle data, as the browser consumes it. */
@@ -157,6 +198,12 @@ export interface ServeShellRequestResult {
    * values resolved. Undefined when no Flight was rendered.
    */
   readHandles(): Promise<ShellRequestHandles | undefined>;
+  /**
+   * The ids of the segments `flight` marks deferred (a prefetch skipped
+   * them; the fill request renders them), in payload order. Empty when
+   * nothing was deferred, undefined when no Flight was rendered.
+   */
+  readDeferred(): Promise<string[] | undefined>;
   /**
    * The form state the SSR render received (the `formState` render option),
    * or undefined when it received none.
@@ -297,9 +344,22 @@ async function decodePayloadHandles(
   for await (const data of metadata?.handles ?? []) hydration = data;
   const late: HandleData[] = [];
   for await (const data of metadata?.handlesLate ?? []) {
-    late.push(await resolveDeferredHandleValues(data));
+    late.push(withoutPushedBy(await resolveDeferredHandleValues(data)));
   }
-  return { hydration: await resolveDeferredHandleValues(hydration), late };
+  return {
+    hydration: withoutPushedBy(await resolveDeferredHandleValues(hydration)),
+    late,
+  };
+}
+
+/** The ids of the segments a payload marks deferred. */
+async function decodeDeferredIds(flight: string): Promise<string[]> {
+  const { metadata } = await decodePayload<{
+    metadata?: { segments?: Array<{ id: string; deferred?: boolean }> };
+  }>(flight);
+  return (metadata?.segments ?? [])
+    .filter((segment) => segment.deferred === true)
+    .map((segment) => segment.id);
 }
 
 /**
@@ -356,10 +416,22 @@ async function servePrerenderArtifacts(
     const { hashParams } = await import("../prerender/param-hash.js");
     baked.add(pathname);
     if (result && !result.passthrough) {
+      const key = `${result.routeName}/${hashParams(result.params)}`;
       payloads.set(
-        `${result.routeName}/${hashParams(result.params)}`,
+        key,
         JSON.stringify({ segments: result.segments, handles: result.handles }),
       );
+      // The intercept variant, keyed and shaped as the build writes it
+      // (vite/discovery/prerender-collection.ts).
+      if (result.interceptSegments?.length) {
+        payloads.set(
+          `${key}/i`,
+          JSON.stringify({
+            segments: [...result.segments, ...result.interceptSegments],
+            handles: result.interceptHandles ?? "",
+          }),
+        );
+      }
     }
   }
   const [{ createPrerenderStore }, { setPrerenderStoreForTests }] =
@@ -435,9 +507,46 @@ async function getHandler(
   return handler;
 }
 
-function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
+async function buildActionRequest(
+  url: URL,
+  headers: Headers,
+  action: ServeShellRequestAction,
+): Promise<Request> {
+  const [{ registerTestAction }] = await Promise.all([
+    import("./internal/test-action.js"),
+    import("./internal/flight-client-globals.js"),
+  ]);
+  const { encodeReply } =
+    await import("@vitejs/plugin-rsc/vendor/react-server-dom/client.edge");
+  registerTestAction(action.ref, action.id, "serveShellRequest");
+  const target = new URL(url);
+  target.searchParams.set("_rsc_action", action.id);
+  target.searchParams.set("_rsc_segments", (action.segments ?? []).join(","));
+  headers.set("rsc-action", action.id);
+  if (!headers.has("X-RSC-Router-Client-Path")) {
+    headers.set("X-RSC-Router-Client-Path", url.href);
+  }
+  return new Request(target, {
+    method: "POST",
+    headers,
+    body: await encodeReply([...(action.args ?? [])]),
+  });
+}
+
+async function buildRequest(
+  url: URL,
+  options: ServeShellRequestOptions,
+): Promise<Request> {
   const headers = new Headers(options.headers);
   const partial = options.partial;
+  if (options.action) {
+    if (partial || options.form) {
+      throw new Error(
+        "serveShellRequest: action cannot be combined with partial or form",
+      );
+    }
+    return buildActionRequest(url, headers, options.action);
+  }
   if (options.form) {
     if (partial) {
       throw new Error(
@@ -454,10 +563,21 @@ function buildRequest(url: URL, options: ServeShellRequestOptions): Request {
     if (!headers.has("accept")) headers.set("accept", "text/html");
     return new Request(url, { headers });
   }
-  const { from = "/", segments = [] } = partial === true ? {} : partial;
+  const {
+    from = "/",
+    segments = [],
+    prefetch = false,
+    fill = false,
+  } = partial === true ? {} : partial;
   const target = new URL(url);
   target.searchParams.set("_rsc_partial", "true");
   target.searchParams.set("_rsc_segments", segments.join(","));
+  // As the browser sends them: browser/navigation-client.ts (fill) and
+  // browser/prefetch/fetch.ts (prefetch).
+  if (fill) target.searchParams.set(FILL_PARAM, "1");
+  if (prefetch && !headers.has(PREFETCH_HEADER)) {
+    headers.set(PREFETCH_HEADER, "1");
+  }
   if (!headers.has("X-RSC-Router-Client-Path")) {
     headers.set("X-RSC-Router-Client-Path", new URL(from, url).href);
   }
@@ -536,7 +656,7 @@ export async function serveShellRequest<TEnv = any>(
   const target = new URL(url, "http://localhost");
   await ensureRouterManifest(router.id);
   const handler = await getHandler(router, options.cacheStore);
-  const request = buildRequest(target, options);
+  const request = await buildRequest(target, options);
   const executionContext = createCollectingExecutionContext();
   const { tasks } = executionContext;
   const recorder: Recorder = {};
@@ -594,6 +714,9 @@ export async function serveShellRequest<TEnv = any>(
     async readHandles() {
       return flight ? decodePayloadHandles(flight) : undefined;
     },
+    async readDeferred() {
+      return flight ? decodeDeferredIds(flight) : undefined;
+    },
     formState: recorder.formState,
     async readPayloadFormState() {
       if (!flight) return undefined;