@rangojs/router 0.0.0-experimental.debug-cache-fix → 0.0.0-experimental.df410dd5

package/src/testing/generated-routes.ts

@@ -0,0 +1,223 @@
+/**
+ * assertGeneratedRoutesMatch — pin the generated named-routes map against the
+ * router's runtime route map.
+ *
+ * The Vite plugin writes a `*.named-routes.gen.ts` file mapping route names to
+ * URL patterns; consumers import that map and pass it here. The check compares
+ * it to the router's runtime `routeMap`, catching drift when a route is added,
+ * removed, renamed, or its pattern changes without regenerating the file.
+ *
+ * Directionality (relative to the generated map):
+ * - missing:  present in the generated map but NOT at runtime (stale entry).
+ * - extra:    present at runtime but NOT in the generated map (ungenerated route).
+ *             Auto-generated internal names (the "$path_" / "$prefix_" prefixes)
+ *             are excluded — they live in the runtime map but are never written
+ *             to the generated file, so they are not drift.
+ * - mismatch: present in both under the same name, but the patterns differ.
+ *
+ * When `generatedMap` is omitted, the global route map (getGlobalRouteMap()) is
+ * used as the generated side — useful when a single router has registered into
+ * the global map.
+ */
+
+import { getGlobalRouteMap } from "../route-map-builder.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+
+/**
+ * Router shape this check depends on: a runtime route map, plus the optional
+ * `findMatch` used to force-expand lazy `include()`d routes (see below).
+ */
+interface RouterWithRouteMap {
+  routeMap: Record<string, unknown>;
+  findMatch?: (pathname: string) => unknown;
+}
+
+/**
+ * Derive a best-effort concrete path from a route pattern so `findMatch` can be
+ * invoked to expand a lazy include. `:param`, `:param(constraint)`, optional
+ * `:param?`, and `*` are all replaced with a literal segment. A constrained
+ * param may not match its constraint (so that one route's match fails), but
+ * since matching ANY route in an include expands ALL of the include's routes,
+ * a sibling route in the same include will still trigger expansion.
+ */
+function concretePath(pattern: string): string {
+  return (
+    pattern
+      .replace(/:[A-Za-z0-9_]+\([^)]*\)\??/g, "x") // :p(constraint) / optional
+      .replace(/:[A-Za-z0-9_]+\??/g, "x") // :p or :p?
+      .replace(/\*/g, "x") // wildcard
+      .replace(/\/{2,}/g, "/") || "/"
+  );
+}
+
+/**
+ * Force-expand the router's lazy `include()`d routes into `router.routeMap`.
+ *
+ * All Rango includes are lazy — their child routes only populate `routeMap` when
+ * the router first matches a path inside them (in production the build-time
+ * manifest virtual carries the full map; in a bare test that virtual is absent).
+ * To make the whole-app drift check work in a unit test, we trigger expansion by
+ * calling `findMatch` on a concrete path derived from each known pattern. This is
+ * idempotent and side-effect-free beyond populating the route map. Routers that
+ * don't expose `findMatch` (e.g. a plain `{ routeMap }` object) are left as-is.
+ */
+function expandLazyIncludes(
+  router: RouterWithRouteMap,
+  patterns: Iterable<string>,
+): void {
+  const findMatch = router.findMatch;
+  if (typeof findMatch !== "function") return;
+  for (const pattern of patterns) {
+    try {
+      findMatch.call(router, concretePath(pattern));
+    } catch {
+      // A pattern that fails to match (constrained param, etc.) is fine — a
+      // sibling route in the same include still triggers expansion.
+    }
+  }
+}
+
+/**
+ * A single name/pattern mismatch: [routeName, generatedPattern, runtimePattern].
+ */
+export type GeneratedRouteMismatch = [
+  name: string,
+  generated: string,
+  runtime: string,
+];
+
+/**
+ * Structured diff between the generated route map and the runtime route map.
+ */
+export interface GeneratedRoutesDiff {
+  /** Names in the generated map but absent at runtime. */
+  missing: string[];
+  /** Names at runtime but absent from the generated map. */
+  extra: string[];
+  /** Names in both with differing patterns. */
+  mismatch: GeneratedRouteMismatch[];
+  /** True when missing, extra, and mismatch are all empty. */
+  ok: boolean;
+}
+
+/**
+ * Normalize a route map value to its pattern string. Route maps may carry
+ * either a bare pattern string or a `{ path, ... }` object (for response/search
+ * routes); compare on the `path`.
+ */
+function patternOf(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (
+    value &&
+    typeof value === "object" &&
+    "path" in value &&
+    typeof (value as { path: unknown }).path === "string"
+  ) {
+    return (value as { path: string }).path;
+  }
+  return String(value);
+}
+
+/**
+ * Compute the diff between a router's runtime route map and a generated map.
+ */
+export function diffGeneratedRoutes(
+  router: RouterWithRouteMap,
+  generatedMap?: Record<string, unknown>,
+): GeneratedRoutesDiff {
+  const generated = generatedMap ?? getGlobalRouteMap();
+
+  // Lazy `include()`d routes are absent from `routeMap` until first matched, so
+  // expand them first (using the generated patterns to drive the matches) —
+  // otherwise every included route is a false `missing`. No-op for plain
+  // `{ routeMap }` objects that don't expose `findMatch`.
+  expandLazyIncludes(
+    router,
+    Object.values(generated).map((v) => patternOf(v)),
+  );
+
+  const runtime = router.routeMap as Record<string, unknown>;
+
+  const missing: string[] = [];
+  const extra: string[] = [];
+  const mismatch: GeneratedRouteMismatch[] = [];
+
+  for (const name of Object.keys(generated)) {
+    if (!(name in runtime)) {
+      missing.push(name);
+      continue;
+    }
+    const gen = patternOf(generated[name]);
+    const run = patternOf(runtime[name]);
+    if (gen !== run) {
+      mismatch.push([name, gen, run]);
+    }
+  }
+
+  for (const name of Object.keys(runtime)) {
+    // Auto-generated internal names ($path_*/$prefix_*) live in the runtime
+    // mergedRouteMap but are deliberately excluded from the generated
+    // *.named-routes.gen.ts file (route-types-writer / runtime-discovery skip
+    // them). Reporting them as `extra` would throw on a perfectly in-sync app
+    // that simply uses an unnamed path()/include() route, so skip them here to
+    // match exactly the surface the generator emits.
+    if (isAutoGeneratedRouteName(name)) continue;
+    if (!(name in generated)) {
+      extra.push(name);
+    }
+  }
+
+  return {
+    missing,
+    extra,
+    mismatch,
+    ok: missing.length === 0 && extra.length === 0 && mismatch.length === 0,
+  };
+}
+
+/**
+ * Assert the router's runtime route map matches the generated map. Throws a
+ * descriptive Error listing every missing, extra, and mismatched route when
+ * they diverge.
+ *
+ * @example
+ * ```ts
+ * import generated from "./router.named-routes.gen";
+ * import { router } from "./router";
+ *
+ * assertGeneratedRoutesMatch(router, generated);
+ * ```
+ */
+export function assertGeneratedRoutesMatch(
+  router: RouterWithRouteMap,
+  generatedMap?: Record<string, unknown>,
+): void {
+  const diff = diffGeneratedRoutes(router, generatedMap);
+  if (diff.ok) return;
+
+  const lines: string[] = [
+    "Generated routes do not match the router's runtime route map.",
+  ];
+
+  if (diff.missing.length > 0) {
+    lines.push(
+      `  Missing (generated but not at runtime): ${diff.missing.join(", ")}`,
+    );
+  }
+  if (diff.extra.length > 0) {
+    lines.push(
+      `  Extra (at runtime but not generated): ${diff.extra.join(", ")}`,
+    );
+  }
+  if (diff.mismatch.length > 0) {
+    lines.push("  Pattern mismatches (name: generated -> runtime):");
+    for (const [name, gen, run] of diff.mismatch) {
+      lines.push(`    ${name}: ${gen} -> ${run}`);
+    }
+  }
+  lines.push(
+    "Re-run the build / `rango` route generation to regenerate the *.named-routes.gen.ts file.",
+  );
+
+  throw new Error(lines.join("\n"));
+}

package/src/testing/index.ts

@@ -0,0 +1,106 @@
+/**
+ * @rangojs/router/testing
+ *
+ * Consumer-facing testing primitives for apps built on @rangojs/router.
+ *
+ * This is the entry for UNIT and INTEGRATION tests, meant to run under a
+ * Vite-driven Vitest project (the rango Vite plugin must be active so the
+ * `@rangojs/router:version` and related virtual modules the router internals
+ * import can resolve; alternatively alias `@rangojs/router:version`). Importing
+ * this module references neither React, @testing-library/react, @playwright/test,
+ * nor the RSC runtime — a unit suite testing only loaders/middleware/dispatch
+ * pulls in none of them.
+ *
+ * The other surfaces are SEPARATE entries because each pulls a dependency or
+ * runtime this barrel deliberately keeps out:
+ * - `@rangojs/router/testing/dom` — `renderRoute` (the RTL component stub). Kept
+ *   separate so this barrel never references React, the browser runtime, or
+ *   `@testing-library/react` types — a unit suite testing only loaders/middleware
+ *   needs none of them.
+ * - `@rangojs/router/testing/e2e` — the Playwright harness (createRangoE2E,
+ *   useFixture, parityDescribe, expectParity, matchers). Kept separate so it is
+ *   loadable in a plain (non-Vite) Playwright runner, which cannot resolve the
+ *   router-manifest virtual modules this barrel pulls in.
+ * - `@rangojs/router/testing/flight` — real Flight rendering. Its serializer
+ *   (vendored react-server-dom) loads only under the `react-server` node
+ *   condition and would throw if pulled into this barrel.
+ *
+ * Layers:
+ * - Unit:        runMiddleware, runLoader
+ * - Integration: dispatch (request -> Response)
+ * - Cross-cut:   assertCacheStatus, assertGeneratedRoutesMatch
+ * - Component:   see @rangojs/router/testing/dom (renderRoute)
+ * - E2E:         see @rangojs/router/testing/e2e
+ * - RSC:         see @rangojs/router/testing/flight
+ */
+
+// Unit
+export { runMiddleware } from "./run-middleware.js";
+export type {
+  RunMiddlewareOptions,
+  RunMiddlewareResult,
+} from "./run-middleware.js";
+export { runLoader } from "./run-loader.js";
+export type {
+  RunLoaderOptions,
+  UseResolver,
+  TestLoaderContext,
+} from "./run-loader.js";
+
+// Integration
+export { dispatch } from "./dispatch.js";
+export type { DispatchOptions } from "./dispatch.js";
+
+// renderRoute lives at `@rangojs/router/testing/dom` — it pulls React, the
+// browser runtime, and @testing-library/react types, which this barrel keeps
+// out so node-only unit suites depend on none of them.
+
+// Cross-cutting: cache/prerender status
+export {
+  assertCacheStatus,
+  parseCacheHeader,
+  createCacheSink,
+  filterCacheDecisions,
+} from "./cache-status.js";
+export type {
+  ExpectedCacheStatus,
+  CacheStatusTarget,
+  CacheSink,
+} from "./cache-status.js";
+
+// Cross-cutting: handle collect/accumulator
+export { collectHandle } from "./collect-handle.js";
+
+// Cross-cutting: generated-route drift
+export {
+  diffGeneratedRoutes,
+  assertGeneratedRoutesMatch,
+} from "./generated-routes.js";
+export type {
+  GeneratedRoutesDiff,
+  GeneratedRouteMismatch,
+} from "./generated-routes.js";
+
+// Advanced: build a real RequestContext for bespoke loader/middleware setups
+export {
+  createTestRequestContext,
+  runInRequestContext,
+  toRequest,
+  seedVariables,
+} from "./internal/context.js";
+export type {
+  CreateTestContextOptions,
+  TestRequestContext,
+  RunInRequestContextResult,
+  VarsInit,
+} from "./internal/context.js";
+
+// The low-level context runner that enters a RequestContext (the same one the
+// RSC handler uses for server actions). Re-exported so a ctx built with
+// createTestRequestContext can be entered directly; runInRequestContext is the
+// one-call convenience over createTestRequestContext + runWithRequestContext.
+export { runWithRequestContext } from "../server/request-context.js";
+
+// The E2E harness is NOT re-exported here: it must be imported from
+// `@rangojs/router/testing/e2e` so it stays loadable in a plain Playwright
+// runner (this barrel pulls in router-manifest code that needs Vite virtuals).

package/src/testing/internal/context.ts

@@ -0,0 +1,304 @@
+/**
+ * Shared internals for the consumer testing primitives.
+ *
+ * Builds a real RequestContext via the same createRequestContext the RSC
+ * handler uses, with test-friendly defaults, so loaders and middleware run
+ * with production-fidelity context (cookies, headers, get/set, use, reverse)
+ * instead of a hand-rolled mock.
+ */
+
+import {
+  createRequestContext,
+  runWithRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
+import { resolveLocationStateEntries } from "../../browser/react/location-state-shared.js";
+import { createReverseFunction } from "../../router/handler-context.js";
+import { normalizeBasename } from "../../router/basename.js";
+import { contextSet, type ContextVar } from "../../context-var.js";
+import type { ThemeConfig } from "../../theme/types.js";
+import { resolveThemeConfig } from "../../theme/constants.js";
+import type { SegmentCacheStore } from "../../cache/types.js";
+import type { CacheProfile } from "../../cache/profile-registry.js";
+
+const DEFAULT_ORIGIN = "http://localhost/";
+
+/**
+ * Initializer for seeded context variables (as a prior middleware would have
+ * set). Either a plain object keyed by var name (the common, best-inferring
+ * form: `{ user: u }`) or a list of `[key, value]` tuples where the key may be a
+ * `createVar()` handle or a string (`[[userVar, u], ["flag", true]]`).
+ */
+export type VarsInit =
+  | Record<string, unknown>
+  | ReadonlyArray<readonly [ContextVar<unknown> | string, unknown]>;
+
+/** Normalize a Request | string | undefined into a concrete Request. */
+export function toRequest(
+  request: Request | string | undefined,
+  init?: RequestInit,
+): Request {
+  if (request instanceof Request) return request;
+  if (typeof request === "string") {
+    return new Request(new URL(request, DEFAULT_ORIGIN), init);
+  }
+  return new Request(DEFAULT_ORIGIN, init);
+}
+
+/**
+ * Preload variables as if set by upstream middleware. Accepts entries keyed by
+ * either a ContextVar (from createVar) or a string, matching ctx.set().
+ */
+export function seedVariables(
+  variables: Record<string, unknown>,
+  vars?: VarsInit,
+): Record<string, unknown> {
+  if (!vars) return variables;
+  // Array/iterable form -> use the tuples as-is; plain object -> its entries.
+  const entries: Iterable<readonly [ContextVar<unknown> | string, unknown]> =
+    Symbol.iterator in (vars as object)
+      ? (vars as ReadonlyArray<
+          readonly [ContextVar<unknown> | string, unknown]
+        >)
+      : Object.entries(vars as Record<string, unknown>);
+  for (const [key, value] of entries) {
+    contextSet(variables, key as ContextVar<unknown>, value);
+  }
+  return variables;
+}
+
+export interface CreateTestContextOptions<TEnv> {
+  env?: TEnv;
+  request?: Request | string;
+  requestInit?: RequestInit;
+  /** Backing store for ctx.get()/ctx.set(); pre-seeded from `vars`. */
+  variables?: Record<string, unknown>;
+  /** Variables a prior middleware would have set (object or [key, value] list). */
+  vars?: VarsInit;
+  /** Route name -> pattern map enabling ctx.reverse() without global state. */
+  routeMap?: Record<string, string>;
+  routeName?: string;
+  params?: Record<string, string>;
+  /**
+   * Router basename for this request (what the RSC handler stores on the
+   * context). Drives redirect() prefixing. Normalized exactly like
+   * createRouter({ basename }) (leading slash forced, trailing stripped, bare
+   * "/" -> undefined) so passing the same value your router takes yields the
+   * same redirect Location. Defaults to undefined (no basename).
+   */
+  basename?: string;
+  /**
+   * Cache store backing `use cache` functions invoked during the test, the
+   * same shape `createRouter({ cache })` resolves. Without it,
+   * registerCachedFunction bypasses (it checks for a store FIRST), so a cached
+   * function runs uncached and its taint/profile guards never fire. Wire one
+   * (e.g. `new MemorySegmentCacheStore()`) to exercise real cache behavior.
+   */
+  cacheStore?: SegmentCacheStore;
+  /**
+   * Cache profiles in the `createRouter({ cacheProfiles })` shape. Required for
+   * a `use cache: "profileName"` function to resolve its profile (an unknown
+   * profile throws), once a `cacheStore` is wired.
+   */
+  cacheProfiles?: Record<string, CacheProfile>;
+  /**
+   * Theme config in the same shape `createRouter({ theme })` takes (resolved
+   * internally). Without it `ctx.theme`/`ctx.setTheme` are inert (undefined),
+   * mirroring an app with no theme configured. Pass one (e.g. `true`, or
+   * `{ themes: [...] }`) to exercise a handler that reads them.
+   */
+  theme?: ThemeConfig | true;
+}
+
+export interface TestRequestContext<TEnv> {
+  ctx: RequestContext<TEnv>;
+  request: Request;
+  url: URL;
+  variables: Record<string, unknown>;
+}
+
+/**
+ * Create a real RequestContext for unit-testing loaders/middleware.
+ *
+ * The returned `ctx` must be ENTERED before use — wrap your call in
+ * `runWithRequestContext(ctx, fn)` (re-exported from `@rangojs/router/testing`)
+ * so that cookie/header mutations and `getRequestContext()` resolve. For the
+ * common case prefer {@link runInRequestContext}, which builds AND enters the
+ * context in a single call.
+ */
+export function createTestRequestContext<TEnv>(
+  opts: CreateTestContextOptions<TEnv> = {},
+): TestRequestContext<TEnv> {
+  const request = toRequest(opts.request, opts.requestInit);
+  const url = new URL(request.url);
+  const variables = seedVariables(opts.variables ?? {}, opts.vars);
+  const ctx = createRequestContext<TEnv>({
+    env: (opts.env ?? {}) as TEnv,
+    request,
+    url,
+    variables,
+    themeConfig:
+      opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
+    cacheStore: opts.cacheStore,
+    cacheProfiles: opts.cacheProfiles,
+  });
+  if (opts.basename !== undefined)
+    ctx._basename = normalizeBasename(opts.basename);
+  if (opts.params) ctx.params = opts.params;
+  if (opts.routeMap) {
+    ctx._routeName = opts.routeName;
+    ctx.reverse = createReverseFunction(
+      opts.routeMap,
+      opts.routeName,
+      opts.params ?? {},
+    ) as RequestContext<TEnv>["reverse"];
+  }
+  return { ctx, request, url, variables };
+}
+
+/**
+ * What a run accumulated on the request context, surfaced as PUBLIC values so a
+ * test never has to cast through the `@internal` `ctx.res` / `ctx.cookies()` to
+ * assert what an action produced.
+ */
+export interface RunInRequestContextResult<T> {
+  /**
+   * The value `fn` returned (awaited), or `undefined` if `fn` threw — in which
+   * case the thrown value is on {@link thrown}. The snapshot below is captured
+   * either way.
+   */
+  result: T | undefined;
+  /**
+   * The value `fn` threw, or `undefined` if it returned normally. Commonly a
+   * `Response` from `throw redirect(...)` / `throw notFound()` — the dominant
+   * cookie+flash case is an action that sets them then throws a redirect — so
+   * this (and the snapshot below) is observable WITHOUT wrapping the action in
+   * your own try/catch. NOTE: the value is captured, NOT re-thrown; assert on it
+   * for a throwing action.
+   */
+  thrown: unknown;
+  /**
+   * A Response carrying the status, headers, and Set-Cookie the run set (via
+   * `cookies().set()`, `ctx.header()`, etc.). Assert Set-Cookie with
+   * `response.headers.getSetCookie()`. When `fn` threw a `Response` (a redirect),
+   * THIS is that Response with the accumulated Set-Cookie/headers merged in
+   * (mirroring how the framework merges them in production), so a redirect's
+   * Location AND the cookies it set are both observable here.
+   */
+  response: Response;
+  /**
+   * The effective cookie view after the run: request cookies merged with
+   * anything the run set or deleted (last-write-wins), as `{ name: value }`.
+   */
+  cookies: Record<string, string>;
+  /**
+   * Location state the run set via `ctx.setLocationState()` / `redirect({ state })`,
+   * resolved to the flat `{ key: value }` shape the client reads off
+   * `history.state` (empty object when none) — so a post-action flash ("Saved!")
+   * is assertable at the unit layer.
+   */
+  locationState: Record<string, unknown>;
+}
+
+/**
+ * Snapshot the observable effects a run left on `ctx` (cookies + location
+ * state). Reads the fields directly off the ctx object, so it works both inside
+ * and outside the AsyncLocalStorage scope (no `getRequestContext()`).
+ */
+export function snapshotRunEffects<TEnv>(ctx: RequestContext<TEnv>): {
+  cookies: Record<string, string>;
+  locationState: Record<string, unknown>;
+} {
+  return {
+    cookies: { ...ctx.cookies() },
+    locationState: resolveLocationStateEntries(ctx._locationState ?? []),
+  };
+}
+
+/**
+ * Build the observable response from what the run accumulated on `ctx.res`. When
+ * `fn` threw a `Response` (a `redirect()`/`notFound()`), that Response IS the
+ * response — merge the accumulated Set-Cookie/other headers into it (the
+ * framework does this when it catches the thrown Response in production), with
+ * its status/Location preserved. Otherwise snapshot the stub (status + headers).
+ * The `Response`/`Headers` constructors copy, so the result is immutable.
+ */
+function buildRunResponse<TEnv>(
+  ctx: RequestContext<TEnv>,
+  thrown: unknown,
+): Response {
+  const stub = ctx.res;
+  if (thrown instanceof Response) {
+    const headers = new Headers(thrown.headers);
+    for (const cookie of stub.headers.getSetCookie()) {
+      headers.append("set-cookie", cookie);
+    }
+    stub.headers.forEach((value, name) => {
+      if (name.toLowerCase() === "set-cookie") return;
+      if (!headers.has(name)) headers.set(name, value);
+    });
+    return new Response(null, { status: thrown.status, headers });
+  }
+  return new Response(null, { status: stub.status, headers: stub.headers });
+}
+
+/**
+ * Build a seeded RequestContext (via {@link createTestRequestContext}) and run
+ * `fn` inside it, so code under test that calls `getRequestContext()`,
+ * `cookies()`, or reads/mutates request headers resolves exactly as in
+ * production.
+ *
+ * This is the entry point for the advanced cases the unit wrappers
+ * (`runLoader` / `runMiddleware`) do not model — most notably a server ACTION
+ * that authenticates off the request cookie or sets a session cookie / flash:
+ * an action has no loader context, so `runLoader` is the wrong shape, yet it
+ * still needs a real request context to read the cookie and resolve
+ * `getRequestContext()`.
+ *
+ * Returns `{ result, thrown, response, cookies, locationState }` so the action's
+ * OUTPUT (Set-Cookie, headers, flash) is assertable without casting through the
+ * `@internal` `ctx.res` / `ctx.cookies()`. `fn` may be async — the context stays
+ * active across its awaits (AsyncLocalStorage), and the snapshot is captured
+ * whether `fn` returns OR throws. The throw path matters: the most common
+ * cookie+flash case is an auth action that sets a cookie + flash then
+ * `throw redirect(...)` on success — the thrown redirect is on `thrown` (NOT
+ * re-thrown) and its Location plus the cookies are on `response`/`cookies`.
+ *
+ * @example
+ * ```ts
+ * const { result, cookies, response, thrown } = await runInRequestContext(
+ *   () => loginAction(input), // sets a session cookie, then `throw redirect("/app")`
+ *   {
+ *     env,
+ *     request: new Request("https://app.test/", {
+ *       headers: { Cookie: "sid=abc" },
+ *     }),
+ *   },
+ * );
+ * expect(cookies.session).toBe("new-token");
+ * expect((thrown as Response).headers.get("Location")).toBe("/app");
+ * expect(response.headers.getSetCookie()).toContainEqual(
+ *   expect.stringContaining("session="),
+ * );
+ * ```
+ */
+export async function runInRequestContext<T, TEnv = unknown>(
+  fn: (ctx: RequestContext<TEnv>) => T | Promise<T>,
+  opts: CreateTestContextOptions<TEnv> = {},
+): Promise<RunInRequestContextResult<T>> {
+  const { ctx } = createTestRequestContext<TEnv>(opts);
+  let result: T | undefined;
+  let thrown: unknown;
+  let didThrow = false;
+  try {
+    result = (await runWithRequestContext(ctx, () => fn(ctx))) as T;
+  } catch (error) {
+    // Capture (do NOT re-throw): a redirect/notFound action throws its Response
+    // on the SUCCESS path, and its cookie/flash output must stay observable.
+    didThrow = true;
+    thrown = error;
+  }
+  const { cookies, locationState } = snapshotRunEffects(ctx);
+  const response = buildRunResponse(ctx, didThrow ? thrown : undefined);
+  return { result, thrown, response, cookies, locationState };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Side-effect module: define the webpack-style globals the vendored
+ * react-server-dom CLIENT deserializer reads at module-eval time.
+ *
+ * In a real app the plugin-rsc Vite plugin rewrites `__webpack_require__` ->
+ * `__vite_rsc_require__` and `__webpack_require__.u` -> `({}).u`
+ * (@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).
+ *
+ * MUST be imported (for side effect) BEFORE `@vitejs/plugin-rsc/react/browser`,
+ * which is why flight-tree.ts lists it first.
+ */
+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;
+};
+
+if (!g.__webpack_require__) {
+  g.__webpack_require__ = (id: string) => g.__vite_rsc_client_require__!(id);
+}
+if (!g.__webpack_chunk_load__) {
+  g.__webpack_chunk_load__ = async () => {};
+}
+
+export {};