@rangojs/router 0.0.0-experimental.f3c21dba → 0.0.0-experimental.f4a8e8de

package/dist/types/testing/flight-tree.d.ts

@@ -0,0 +1,192 @@
+/**
+ * renderServerTree — REAL Flight serialize -> deserialize round-trip for unit
+ * tests, returning an INSPECTABLE React element tree (not just the wire string).
+ *
+ * Where it sits:
+ * - `renderRoute` (testing/dom): a synthetic CLIENT tree, no Flight at all.
+ * - `renderToFlightString` (testing/flight): the real Flight WIRE STRING, for
+ *   `toMatchFlight` substring/snapshot assertions.
+ * - `renderServerTree` (here): serializes the real Flight, then deserializes it
+ *   back to a React element tree you can traverse — so you can assert TYPED prop
+ *   fidelity across the server/client boundary (a `Date` comes back a `Date`,
+ *   not the opaque `$D...` wire encoding) and detect whether a `"use client"`
+ *   component actually crossed the boundary (an `I` row) or was inlined.
+ *
+ * Scope (deliberate): serialize + deserialize ONLY. There is NO hydration and
+ * NO interaction — the deserialized client boundaries are inert placeholders
+ * carrying their props. Real interaction/hydration-mismatch testing stays at the
+ * e2e tier; in-process happy-dom hydration re-tests React more than your app and
+ * misses the only hydration bug worth a dedicated test (server/client divergence
+ * needs a real browser).
+ *
+ * Runs under the `react-server` export condition, in the SAME worker as the
+ * serializer (the client deserializer's react/react-dom imports are inert here
+ * because deserialize-only never renders). Use it from the rsc Vitest project
+ * (vitest.rsc.config.ts); name files `*.rsc-test.{ts,tsx}`.
+ */
+import "./internal/flight-client-globals.js";
+import type { ReactNode } from "react";
+import type { RenderToFlightStringOptions } from "./flight.js";
+/** Options for {@link renderServerTree}. */
+export interface RenderServerTreeOptions extends RenderToFlightStringOptions {
+    /**
+     * The `"use client"` components reachable from the server tree, keyed by the
+     * name you want each boundary to have — usually the components you already
+     * import to render them: `{ clientComponents: { Counter, PriceTag } }`.
+     *
+     * The rsc Vitest project does NOT apply the `"use client"` transform, so a
+     * plainly-imported island is just a function the serializer would render
+     * server-side (and likely throw on a hook). Listing them here registers each as
+     * a client reference (in place) so it serializes as a real boundary (`I` row).
+     * This depends on NO filename convention — `"use client"` is marked by the
+     * directive, not the name, and you already import these to render them.
+     *
+     * Omit it for pure server-only trees. Components already registered as client
+     * references (e.g. by a transform) are left untouched. Registration is in place
+     * and per-worker first-wins: a component keeps the first name it is registered
+     * under for the rest of the test file.
+     */
+    clientComponents?: Record<string, unknown>;
+}
+/** Result of {@link renderServerTree}. */
+export interface RenderServerTreeResult {
+    /** The raw Flight wire string (so `toMatchFlight` assertions still apply). */
+    flight: string;
+    /**
+     * The deserialized React element tree. Server elements are plain React
+     * elements; each client boundary is an inert placeholder element whose `props`
+     * are the real, deserialized JS values that crossed the boundary. Use
+     * {@link findClientBoundaries} to locate them.
+     */
+    tree: unknown;
+}
+/** A client boundary located in a deserialized tree. */
+export interface ClientBoundary {
+    /** The id the boundary was registered under (the `clientComponents` key). */
+    id: string;
+    /** The boundary name (the `clientComponents` key). */
+    name: string;
+    /**
+     * The props that crossed the boundary, as real deserialized JS values
+     * (EXCLUDES `children` — read it off {@link ClientBoundary.children}, mirroring
+     * {@link FoundElement}).
+     */
+    props: Record<string, unknown>;
+    /** The boundary's `props.children` (what was nested inside the island). */
+    children: unknown;
+    /** The raw deserialized element (for advanced assertions). */
+    element: unknown;
+}
+/**
+ * A selector for {@link findClientBoundaries}. Pass a string to match by export
+ * name (the back-compatible form), or this object to also filter by props /
+ * test id / an arbitrary predicate. All provided criteria are AND-ed.
+ *
+ * Only CLIENT boundaries are matched — a `data-testid` on a `"use client"`
+ * island is a prop that crossed the boundary (so `testId` finds it), but a
+ * `data-testid` on a plain server host element is NOT a boundary and is not
+ * matched here.
+ */
+export interface BoundarySelector {
+    /** Match the boundary's export name (same as passing a bare string). */
+    name?: string;
+    /** Match `props["data-testid"]` exactly (sugar over `props: { "data-testid": ... }`). */
+    testId?: string;
+    /**
+     * Subset match: every listed prop must DEEP-EQUAL the boundary's prop of the
+     * same key (Date/Map/Set/array/nested-object aware). Props not listed are
+     * ignored, so `{ amount: 12.5 }` matches a boundary that also has other props.
+     */
+    props?: Record<string, unknown>;
+    /** Arbitrary predicate, AND-ed with the criteria above. */
+    where?: (boundary: ClientBoundary) => boolean;
+}
+/** Register `{ name: Component }` entries, keyed by name (id === name). */
+export declare function registerClientComponents(components: Record<string, unknown>): void;
+/**
+ * A client manifest that resolves ANY registered client reference without
+ * needing to enumerate them. `$$id` is `${id}#${exportName}`; the serializer
+ * looks it up here. We omit `async`, so each `I` row is a 3-element row and the
+ * deserialized boundary's payload is a clean `resolved_module` whose value is
+ * `[id, [], name]` — synchronously readable by {@link findClientBoundaries}.
+ */
+export declare function makeClientManifest(): unknown;
+/**
+ * Serialize a server component to real Flight, then deserialize it back to an
+ * inspectable React element tree. See the module header for scope.
+ *
+ * Must run under the `react-server` export condition.
+ */
+export declare function renderServerTree(element: ReactNode, opts?: RenderServerTreeOptions): Promise<RenderServerTreeResult>;
+/**
+ * Deserialize a Flight wire string back to an inspectable React element tree:
+ * `createFromReadableStream` (vendored client), then unwrap Rango's payload
+ * wrapper and resolve the top server chunk so the consumer gets their element,
+ * not a lazy. Reused by renderServerTree AND renderHandler. Client references
+ * stay as inert boundary markers ({@link findClientBoundaries} reads them).
+ */
+export declare function deserializeFlight(flight: string): Promise<unknown>;
+export declare function findClientBoundaries(tree: unknown, selector?: string | BoundarySelector): ClientBoundary[];
+/** A server/host element located in a deserialized tree by {@link findElements}. */
+export interface FoundElement {
+    /** The host tag name (`"article"`, `"h2"`). Always a host element. */
+    tag: string;
+    /** The element's props, as real deserialized JS values (excludes `children`). */
+    props: Record<string, unknown>;
+    /** The element's `props.children` (the rendered child tree), for convenience. */
+    children: unknown;
+    /** Concatenated text content of this element's subtree. */
+    text: string;
+    /** The raw deserialized element (for advanced assertions). */
+    element: unknown;
+}
+/**
+ * A selector for {@link findElements}. Pass a string to match a host tag name
+ * (`"h2"`), or this object for finer matches. All provided criteria are AND-ed.
+ *
+ * Mirrors {@link BoundarySelector} but keys on `tag` (the host tag) rather than
+ * `name` (a client component's export identity) — by design, since a host element
+ * has no component name. It also adds `text`, which a boundary selector lacks: a
+ * host element has rendered text, whereas a client boundary is an inert
+ * placeholder with no rendered children to match against.
+ */
+export interface ElementSelector {
+    /** Match the host tag name (`"article"`, `"h2"`). */
+    tag?: string;
+    /** Match `props["data-testid"]` exactly. */
+    testId?: string;
+    /** Subset deep-equal match on props (Date/Map/Set/array/nested aware). */
+    props?: Record<string, unknown>;
+    /** Match the element's text content (substring for a string, `.test()` for a RegExp). */
+    text?: string | RegExp;
+    /** Arbitrary predicate, AND-ed with the criteria above. */
+    where?: (element: FoundElement) => boolean;
+}
+/**
+ * Concatenate the text content of a deserialized node's subtree — every string
+ * and number leaf, in document order, space-free (`<h2>Wine {2}</h2>` ->
+ * `"Wine 2"` only if the source had the space). Use it to assert rendered text
+ * without reaching for `JSON.stringify(tree).toContain(...)`.
+ */
+export declare function textContent(node: unknown): string;
+/**
+ * Walk a deserialized tree and return every SERVER/HOST element (the output a
+ * server component rendered), in document order. The optional second arg filters:
+ * - a STRING matches a host tag name (`findElements(tree, "h2")`);
+ * - an {@link ElementSelector} filters by `tag` / `testId` / `props` (subset
+ *   deep-equal) / `text` (substring or RegExp) / `where`, AND-ed.
+ *
+ * Caveat: server COMPONENTS do not survive Flight as identities — they are
+ * executed during serialization, so only the host elements they produced remain.
+ * Match those host elements (by tag/props/text), not the component function. For
+ * CLIENT islands (which DO keep identity) use {@link findClientBoundaries}.
+ *
+ * Always returns an array (destructure the first for a single expected match).
+ */
+export declare function findElements(tree: unknown, selector?: string | ElementSelector): FoundElement[];
+/**
+ * Smoke check that the vendored client deserializer subpaths still resolve. The
+ * paths are private to plugin-rsc; a minor bump could relocate them. Call this in
+ * a test to fail loudly with a clear message instead of an opaque import error.
+ */
+export declare function assertFlightTreeRuntimeAvailable(): void;

package/dist/types/testing/flight.d.ts

@@ -0,0 +1,115 @@
+/**
+ * renderToFlightString — REAL React Server Component (Flight) rendering for
+ * unit tests of @rangojs/router consumer apps.
+ *
+ * This module renders a server component tree to its Flight wire string using
+ * the same react-server-dom serializer the router uses at runtime. It runs in
+ * plain node (no Vite, no browser), but ONLY under the `react-server` export
+ * condition. The serializer is the VENDORED build shipped with
+ * @vitejs/plugin-rsc — the public `@vitejs/plugin-rsc/rsc` entry top-level
+ * imports Vite virtual modules and is not usable outside a Vite build.
+ *
+ * Run the example/tests for this module via the dedicated rsc vitest project
+ * (vitest.rsc.config.ts), which forces `--conditions=react-server` on the
+ * worker. The main vitest project must NOT use that condition (it would flip
+ * React to the no-hooks server build and break the ~50 tests that mock
+ * @vitejs/plugin-rsc/rsc).
+ *
+ * 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.
+ *   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
+ *   serializer drops the dev-only debug-info rows (the `N<timestamp>` reference
+ *   row, the per-component `stack`/`env` rows, and `D{...}` timing rows),
+ *   leaving just the rendered tree row(s).
+ */
+import type { ReactNode } from "react";
+import { type VarsInit } from "./internal/seed-vars.js";
+import { normalizeFlight } from "./flight-normalize.js";
+import type { ThemeConfig } from "../theme/types.js";
+import type { SegmentCacheStore } from "../cache/types.js";
+import type { CacheProfile } from "../cache/profile-registry.js";
+export { normalizeFlight };
+/**
+ * Options for {@link renderToFlightString}.
+ */
+export interface RenderToFlightStringOptions {
+    /**
+     * 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;
+    /** Route params exposed via `ctx.params` and loader contexts. */
+    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>;
+}
+/**
+ * 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 declare function isServerOnlyStubError(error: unknown): boolean;
+export declare function assertNoLegacyUrlOption(opts: object, fnName: string): void;
+/**
+ * Render a server component (or any ReactNode) to its Flight wire string.
+ *
+ * The element is wrapped in a minimal Rango segment + payload, then serialized
+ * with the vendored react-server-dom server. A request context is active for
+ * the duration of the render (drained INSIDE runWithRequestContext) so async
+ * server components can call getRequestContext(), read params, cookies, etc.
+ *
+ * Must run under the `react-server` export condition (see module header).
+ */
+export declare function renderToFlightString(element: ReactNode, opts?: RenderToFlightStringOptions): Promise<string>;
+export declare function serializeToFlightString(element: ReactNode, opts: RenderToFlightStringOptions, clientManifest: unknown): Promise<string>;
+export declare function serializeNodeToFlight(node: ReactNode, clientManifest: unknown, pathname: string): Promise<string>;
+export declare function assertFlightRuntimeAvailable(): void;

package/dist/types/testing/flight.entry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @rangojs/router/testing/flight
+ *
+ * Real React Server Component (Flight) rendering for unit tests. This entry is
+ * SEPARATE from the main ./testing barrel because its serializer (the vendored
+ * react-server-dom build) can only be imported under the `react-server` node
+ * condition; importing it elsewhere throws. Use it only from a Vitest project
+ * configured with that condition (see vitest.rsc.config.ts) — name those test
+ * files `*.rsc-test.{ts,tsx}` and run `pnpm test:unit:rsc`.
+ *
+ * This entry deliberately does NOT pull in Vitest. The `toMatchFlight` /
+ * `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 { renderToFlightString, normalizeFlight, 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/dist/types/testing/generated-routes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+export declare function diffGeneratedRoutes(router: RouterWithRouteMap, generatedMap?: Record<string, unknown>): Promise<GeneratedRoutesDiff>;
+/**
+ * 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";
+ *
+ * await assertGeneratedRoutesMatch(router, generated);
+ * ```
+ */
+export declare function assertGeneratedRoutesMatch(router: RouterWithRouteMap, generatedMap?: Record<string, unknown>): Promise<void>;
+export {};

package/dist/types/testing/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @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, assertShellStatus, assertGeneratedRoutesMatch
+ * - Component:   see @rangojs/router/testing/dom (renderRoute)
+ * - E2E:         see @rangojs/router/testing/e2e
+ * - RSC:         see @rangojs/router/testing/flight
+ */
+export { runMiddleware } from "./run-middleware.js";
+export type { RunMiddlewareOptions, RunMiddlewareResult, } from "./run-middleware.js";
+export { runLoader, runLoaderResult } from "./run-loader.js";
+export type { RunLoaderOptions, RunLoaderResult, UseResolver, TestLoaderContext, } from "./run-loader.js";
+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";
+export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, } from "./cache-status.js";
+export type { ExpectedCacheStatus, CacheStatusTarget, CacheSink, } from "./cache-status.js";
+export type { TelemetryEvent, TelemetrySink, CacheDecisionEvent, CacheSegmentSignal, CacheSegmentStatus, } from "../router/telemetry.js";
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, } from "./shell-status.js";
+export type { PprReplayBypassReason, PprReplayStatus, ShellStatus, ShellStatusTarget, } from "./shell-status.js";
+export { collectHandle } from "./collect-handle.js";
+export { diffGeneratedRoutes, assertGeneratedRoutesMatch, } from "./generated-routes.js";
+export type { GeneratedRoutesDiff, GeneratedRouteMismatch, } from "./generated-routes.js";
+export { createTestRequestContext, runInRequestContext, toRequest, seedVariables, } from "./internal/context.js";
+export type { CreateTestContextOptions, TestRequestContext, TestRequestContextObject, RunInRequestContextResult, VarsInit, StateCookieSeed, } from "./internal/context.js";
+export { runWithRequestContext } from "../server/request-context.js";