@rangojs/router 0.0.0-experimental.bd6e11bc → 0.0.0-experimental.bdaf10aa

package/src/testing/flight.entry.ts

@@ -12,6 +12,12 @@
  * `toMatchFlightSnapshot` matchers (which import `vitest`) live at the separate
  * `@rangojs/router/testing/flight-matchers` subpath, so a consumer can import
  * `renderToFlightString` without taking a hard dependency on Vitest.
+ *
+ * `renderToFlightString` returns the wire STRING (for `toMatchFlight`).
+ * `renderServerTree` additionally deserializes it back to an inspectable React
+ * element tree, so you can assert typed prop fidelity across the client boundary
+ * (a `Date` comes back a `Date`) and detect inlined-vs-island. Serialize +
+ * deserialize only — no hydration/interaction (that is the e2e tier).
  */
 
 export {
@@ -20,3 +26,27 @@ export {
   assertFlightRuntimeAvailable,
 } from "./flight.js";
 export type { RenderToFlightStringOptions } from "./flight.js";
+
+export {
+  renderServerTree,
+  findClientBoundaries,
+  findElements,
+  textContent,
+  assertFlightTreeRuntimeAvailable,
+} from "./flight-tree.js";
+export type {
+  RenderServerTreeOptions,
+  RenderServerTreeResult,
+  ClientBoundary,
+  BoundarySelector,
+  FoundElement,
+  ElementSelector,
+} from "./flight-tree.js";
+
+export { renderHandler } from "./render-handler.js";
+export type {
+  TestableHandler,
+  RenderHandlerOptions,
+  RenderHandlerResult,
+  StateCookieSeed,
+} from "./render-handler.js";

package/src/testing/flight.ts

@@ -19,9 +19,9 @@
  * Scope / limitations (v1):
  * - Server-only / leaf trees. A tree containing a CLIENT component emits an
  *   `I[...]` import row whose module id will not resolve against the empty `{}`
- *   client manifest used here — fine for snapshotting the SHAPE of the payload,
- *   but the client reference cannot be executed/hydrated. The interactive DOM
- *   render (`renderServer`) is deferred (see module TODO at bottom of report).
+ *   client manifest used here — fine for snapshotting the SHAPE of the payload.
+ *   To inspect a client boundary's deserialized props instead, use
+ *   `renderServerTree` (flight-tree.ts). Interactive hydration stays at the e2e tier.
  * - The vendored subpath is a private plugin-rsc path; a minor bump could move
  *   it. `assertFlightRuntimeAvailable()` provides a smoke check.
  * - For stable snapshots, run under NODE_ENV=production: the production
@@ -41,16 +41,32 @@ import {
   runWithRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import { seedVariables, type VarsInit } from "./internal/seed-vars.js";
+import { normalizeFlight } from "./flight-normalize.js";
+import { resolveThemeConfig } from "../theme/constants.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
 import type { RscPayload } from "../rsc/types.js";
 import type { ResolvedSegment } from "../types.js";
 
+// Re-export from the serializer-free module so this entry's public surface is
+// unchanged while flight-matchers can import normalizeFlight without pulling in
+// the vendored serializer (which throws outside the react-server condition).
+export { normalizeFlight };
+
 /**
  * Options for {@link renderToFlightString}.
  */
 export interface RenderToFlightStringOptions {
-  /** Request URL. Defaults to `http://localhost/`. */
-  url?: string;
-  /** Request headers (e.g. Cookie) visible to the server tree. */
+  /**
+   * The request the render runs under: a `Request`, or a URL string (absolute or
+   * path). Defaults to `http://localhost/`. A server component reading
+   * `getRequestContext()` sees this request's url/cookies. When a `Request` is
+   * passed, its headers are used and `headers` below is ignored.
+   */
+  request?: Request | string;
+  /** Request headers (e.g. Cookie) visible to the server tree (when `request` is a string). */
   headers?: HeadersInit;
   /** Env / bindings exposed as `ctx.env`. Defaults to `{}`. */
   env?: unknown;
@@ -58,15 +74,92 @@ export interface RenderToFlightStringOptions {
   params?: Record<string, string>;
   /** Matched route name (drives `ctx.routeName` and scoped reverse). */
   routeName?: string;
+  /**
+   * Route name -> pattern map enabling a SCOPED `ctx.reverse()` (like
+   * `renderHandler`). Without it, a server component that reverses resolves
+   * against the GLOBAL route map and is order-dependent on whatever router
+   * registered last. Pass the router-under-test's map to make reversing
+   * deterministic.
+   */
+  routeMap?: Record<string, string>;
+  /**
+   * Context variables visible to the rendered tree via `ctx.get(...)` — as a
+   * prior middleware would have set them. Seeds the SAME way the handler-test
+   * primitives (`runInRequestContext`/`runLoader`) do, so a server component
+   * that reads `getRequestContext().get(MyVar)` during render is testable.
+   * Object form (`{ user }`) or `[key, value]` tuples (`[[userVar, u]]`).
+   */
+  vars?: VarsInit;
+  /**
+   * Theme config in the same shape `createRouter({ theme })` takes (e.g. `true`
+   * or `{ themes: [...] }`). Without it `getRequestContext().theme` is `undefined`
+   * and `ctx.setTheme` is inert — pass one to render a server component that
+   * reads `ctx.theme`. Threaded into the SAME createRequestContext renderHandler
+   * uses, so the two Flight primitives expose theme identically.
+   */
+  theme?: ThemeConfig | true;
+  /**
+   * Cache store backing a `"use cache"` function the rendered server tree
+   * invokes. Without it, `registerCachedFunction` takes the uncached bypass and
+   * the cached path is NOT exercised. Pair with `cacheProfiles` so a
+   * `"use cache: profileName"` directive resolves its profile.
+   */
+  cacheStore?: SegmentCacheStore;
+  /** Cache profiles in the `createRouter({ cacheProfiles })` shape. */
+  cacheProfiles?: Record<string, CacheProfile>;
 }
 
 const DEFAULT_URL = "http://localhost/";
 
 /**
- * Wrap a single element in the minimal ResolvedSegment + RscPayload shape that
- * mirrors Rango's wire format, so the serialized output matches what a real
- * route segment would emit.
+ * True when `error` is the out-of-react-server stub thrown by index.ts's
+ * server-only exports (getRequestContext/cookies/headers/...) — i.e. the bare
+ * `@rangojs/router` specifier resolved to index.ts, not index.rsc.ts, because
+ * the rsc Vitest project is missing the `rangoTestAliases` alias. Matches both
+ * substrings of `serverOnlyStubError` (index.ts) so a normal app error cannot
+ * over-match. Shared with render-handler.ts so the two Flight primitives report
+ * the same misconfiguration identically.
+ */
+export function isServerOnlyStubError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.message.includes("is only available from") &&
+    error.message.includes("react-server")
+  );
+}
+
+/**
+ * Rethrow a server tree render error. When it is the missing-rsc-alias stub
+ * (above), rethrow an actionable message naming `rangoTestAliases` instead of
+ * the opaque stub text; otherwise rethrow the original unchanged. Classify the
+ * ORIGINAL error before constructing the wrapper so the wrapper's `Original: ...`
+ * echo (which re-embeds the matched substrings) never re-triggers the predicate.
  */
+function rethrowFlightRenderError(error: unknown): never {
+  if (isServerOnlyStubError(error)) {
+    throw new Error(
+      `The server component called a server-only API ` +
+        `(getRequestContext/cookies/headers/...) but "@rangojs/router" resolved to ` +
+        `the out-of-react-server stub. Add rangoTestAliases({ preset }) to your ` +
+        `vitest.rsc.config.ts \`resolve.alias\` so the bare specifier maps to ` +
+        `index.rsc.ts (the real react-server implementations). ` +
+        `Original: ${(error as Error).message}`,
+    );
+  }
+  throw error;
+}
+
+export function assertNoLegacyUrlOption(opts: object, fnName: string): void {
+  if ("url" in opts) {
+    throw new Error(
+      `${fnName}: the \`url\` option was renamed to \`request\`. Pass ` +
+        `{ request: "<url-or-path>" } (or a Request) instead of { url }. ` +
+        `The legacy \`url\` key is ignored, so the render would silently use ` +
+        `the default origin.`,
+    );
+  }
+}
+
 function wrapAsPayload(element: ReactNode, pathname: string): RscPayload {
   const segment: ResolvedSegment = {
     id: "test",
@@ -98,78 +191,60 @@ export async function renderToFlightString(
   element: ReactNode,
   opts: RenderToFlightStringOptions = {},
 ): Promise<string> {
-  const url = new URL(opts.url ?? DEFAULT_URL);
-  const request = new Request(url, { headers: opts.headers });
+  assertNoLegacyUrlOption(opts, "renderToFlightString");
+  return serializeToFlightString(element, opts, {});
+}
+
+export async function serializeToFlightString(
+  element: ReactNode,
+  opts: RenderToFlightStringOptions,
+  clientManifest: unknown,
+): Promise<string> {
+  const request =
+    opts.request instanceof Request
+      ? opts.request
+      : new Request(new URL(opts.request ?? DEFAULT_URL, DEFAULT_URL), {
+          headers: opts.headers,
+        });
+  const url = new URL(request.url);
   const ctx = createRequestContext({
     env: opts.env ?? {},
     request,
     url,
-    variables: {},
+    variables: seedVariables({}, opts.vars),
+    themeConfig:
+      opts.theme === undefined ? undefined : resolveThemeConfig(opts.theme),
+    cacheStore: opts.cacheStore,
+    cacheProfiles: opts.cacheProfiles,
   });
 
-  const payload = wrapAsPayload(element, url.pathname);
-
-  return runWithRequestContext(ctx, async () => {
-    setRequestContextParams(opts.params ?? {}, opts.routeName);
-    // Capture (do NOT rethrow) the first render error. The serializer calls
-    // onError from its own scheduled work; throwing there escapes as an
-    // unhandled rejection AND leaves the stream un-closed, so the drain below
-    // would hang until the test times out. Production's onError returns void
-    // (rsc-rendering.ts) so the stream completes with an error row. We mirror
-    // that — let the stream finish — then surface the error as a clean
-    // rejection after draining, so `await expect(...).rejects.toThrow()` works.
-    let renderError: unknown;
-    let didError = false;
-    const stream = RSDServer.renderToReadableStream(
-      payload,
-      {},
-      {
-        onError(error: unknown) {
-          if (!didError) {
-            didError = true;
-            renderError = error;
-          }
-        },
-      },
-    );
-    // Drain inside the context so async components see ctx during streaming.
-    const text = await new Response(stream).text();
-    if (didError) throw renderError;
-    return text;
+  return runWithRequestContext(ctx, () => {
+    setRequestContextParams(opts.params ?? {}, opts.routeName, opts.routeMap);
+    return serializeNodeToFlight(element, clientManifest, url.pathname);
   });
 }
 
-// Volatile leading reference row: `:N<timestamp>` (dev debug-info anchor).
-const REFERENCE_ROW_RE = /^:N[\d.]+\n/;
-// Absolute file:// paths embedded in dev STACK rows. The serializer emits stack
-// frames as `["Component","file:///abs/path.tsx",<line>,<col>,...]`, so the
-// path is a quoted JSON string immediately followed by `",<line>,<col>`. The
-// lookahead scopes the scrub to exactly that frame shape, leaving a legitimate
-// `file://` href in RENDERED content (e.g. `{"href":"file:///x"}`) untouched.
-const FILE_URL_RE = /file:\/\/[^"\\]+(?=",\d+,\d+)/g;
-
-/**
- * Scrub volatile bits from a Flight string so snapshots are stable across runs
- * and machines:
- * - the leading `:N<timestamp>` reference row (dev only),
- * - absolute `file://...` paths inside dev stack rows.
- *
- * Under NODE_ENV=production these rows are already absent; normalize is a
- * no-op safety net there. In dev mode it removes the machine/clock-specific
- * noise while leaving the rendered tree intact.
- */
-export function normalizeFlight(flight: string): string {
-  return flight
-    .replace(REFERENCE_ROW_RE, "")
-    .replace(FILE_URL_RE, "file://<path>");
+export async function serializeNodeToFlight(
+  node: ReactNode,
+  clientManifest: unknown,
+  pathname: string,
+): Promise<string> {
+  const payload = wrapAsPayload(node, pathname);
+  let renderError: unknown;
+  let didError = false;
+  const stream = RSDServer.renderToReadableStream(payload, clientManifest, {
+    onError(error: unknown) {
+      if (!didError) {
+        didError = true;
+        renderError = error;
+      }
+    },
+  });
+  const text = await new Response(stream).text();
+  if (didError) rethrowFlightRenderError(renderError);
+  return text;
 }
 
-/**
- * Smoke check that the vendored serializer subpath still resolves and exposes
- * `renderToReadableStream`. The vendored path is private to plugin-rsc; a minor
- * bump could relocate it. Call this in a test to fail loudly with a clear
- * message instead of an opaque import error.
- */
 export function assertFlightRuntimeAvailable(): void {
   if (typeof RSDServer.renderToReadableStream !== "function") {
     throw new Error(

package/src/testing/generated-routes.ts

@@ -29,17 +29,13 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
  */
 interface RouterWithRouteMap {
   routeMap: Record<string, unknown>;
+  // findMatch is async (it may await an async include provider's import before
+  // the route's names are spliced into routeMap), so expandLazyIncludes awaits
+  // it. Typed `unknown` (not `unknown | Promise<unknown>`, which collapses to
+  // the same thing) — the awaited value is never read, only its side effect.
   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
@@ -50,29 +46,27 @@ function concretePath(pattern: string): string {
   );
 }
 
-/**
- * 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(
+async function expandLazyIncludes(
   router: RouterWithRouteMap,
   patterns: Iterable<string>,
-): void {
+): Promise<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.
+      // Await: an async include(`() => import()`) resolves its module + splices
+      // its routes into routeMap only after findMatch's Promise settles. Without
+      // the await, the routeMap read below races the import and reports the
+      // split-group routes as missing.
+      await findMatch.call(router, concretePath(pattern));
+    } catch (e) {
+      // A findMatch throw here is almost always a failing async include()
+      // provider (its `() => import()` rejected). Surface it — swallowed, it
+      // resurfaces downstream as a misleading "missing route" in the diff.
+      console.warn(
+        `[@rangojs/router] assertGeneratedRoutesMatch: could not expand include ` +
+          `for "${pattern}": ${(e as Error)?.message ?? String(e)}`,
+      );
     }
   }
 }
@@ -100,11 +94,6 @@ export interface GeneratedRoutesDiff {
   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 (
@@ -118,20 +107,13 @@ function patternOf(value: unknown): string {
   return String(value);
 }
 
-/**
- * Compute the diff between a router's runtime route map and a generated map.
- */
-export function diffGeneratedRoutes(
+export async function diffGeneratedRoutes(
   router: RouterWithRouteMap,
   generatedMap?: Record<string, unknown>,
-): GeneratedRoutesDiff {
+): Promise<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(
+  await expandLazyIncludes(
     router,
     Object.values(generated).map((v) => patternOf(v)),
   );
@@ -155,12 +137,6 @@ export function diffGeneratedRoutes(
   }
 
   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);
@@ -185,14 +161,14 @@ export function diffGeneratedRoutes(
  * import generated from "./router.named-routes.gen";
  * import { router } from "./router";
  *
- * assertGeneratedRoutesMatch(router, generated);
+ * await assertGeneratedRoutesMatch(router, generated);
  * ```
  */
-export function assertGeneratedRoutesMatch(
+export async function assertGeneratedRoutesMatch(
   router: RouterWithRouteMap,
   generatedMap?: Record<string, unknown>,
-): void {
-  const diff = diffGeneratedRoutes(router, generatedMap);
+): Promise<void> {
+  const diff = await diffGeneratedRoutes(router, generatedMap);
   if (diff.ok) return;
 
   const lines: string[] = [

package/src/testing/index.ts

@@ -34,30 +34,31 @@
  * - 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 { runLoader, runLoaderResult } from "./run-loader.js";
 export type {
   RunLoaderOptions,
+  RunLoaderResult,
   UseResolver,
   TestLoaderContext,
 } from "./run-loader.js";
 
-// Integration
+export { runTransitionWhen } from "./run-transition-when.js";
+export type {
+  RunTransitionWhenOptions,
+  RunTransitionWhenResult,
+} from "./run-transition-when.js";
+
 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,
+  assertCacheDecision,
   parseCacheHeader,
   createCacheSink,
   filterCacheDecisions,
@@ -67,11 +68,16 @@ export type {
   CacheStatusTarget,
   CacheSink,
 } from "./cache-status.js";
+export type {
+  TelemetryEvent,
+  TelemetrySink,
+  CacheDecisionEvent,
+  CacheSegmentSignal,
+  CacheSegmentStatus,
+} from "../router/telemetry.js";
 
-// Cross-cutting: handle collect/accumulator
 export { collectHandle } from "./collect-handle.js";
 
-// Cross-cutting: generated-route drift
 export {
   diffGeneratedRoutes,
   assertGeneratedRoutesMatch,
@@ -81,7 +87,6 @@ export type {
   GeneratedRouteMismatch,
 } from "./generated-routes.js";
 
-// Advanced: build a real RequestContext for bespoke loader/middleware setups
 export {
   createTestRequestContext,
   runInRequestContext,
@@ -91,16 +96,10 @@ export {
 export type {
   CreateTestContextOptions,
   TestRequestContext,
+  TestRequestContextObject,
   RunInRequestContextResult,
   VarsInit,
+  StateCookieSeed,
 } 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).