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

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

@@ -0,0 +1,127 @@
+/**
+ * dispatch — in-process request -> Response for unit/integration tests,
+ * WITHOUT the Flight RSC runtime.
+ *
+ * dispatch runs the router's real matching and middleware execution so that
+ * redirects, 404s, response routes (path.json / path.text / path.html / ...),
+ * and middleware short-circuits behave exactly as in production. It deliberately
+ * does NOT render React Server Components: there is no Flight stream, no SSR,
+ * and no DOM. Hit an RSC (component) route and dispatch throws a clear error
+ * directing you to renderToFlightString/renderServerTree/renderHandler or an e2e test.
+ *
+ * What dispatch DOES support:
+ * - Trailing-slash and other findMatch() redirects   -> 308 with Location
+ * - Unmatched paths                                  -> 404 Response
+ *   Both the 308 and the 404 are produced INSIDE the global middleware chain
+ *   (mirroring production, where coreHandler runs wrapped by executeMiddleware),
+ *   so a global auth middleware can 401/redirect them and middleware-set
+ *   cookies/headers merge onto the 308/404 the way createResponseWithMergedHeaders
+ *   merges them in production.
+ * - Response routes (non-RSC)                         -> serialized Response
+ *   - json:           JSON.stringify(result) (bare value) with application/json
+ *   - text/html/xml/md: String(result) with the mapped MIME type
+ *   - handler returning or throwing a Response:         re-wrapped like
+ *     handleResponseRoute (stub headers/cookies merged, Set-Cookie preserved,
+ *     WebSocket upgrade passed through without reconstruction)
+ *   - handler throwing a non-Response error:            typed 500 / RouterError
+ *     status, matching handleResponseRoute (RFC 9457 problem+json body with
+ *     application/problem+json for json routes, text/plain message otherwise)
+ *   - content-negotiated route:                         Vary: Accept appended
+ *   - cached response route (cache({...})):             getResponse/putResponse
+ *     hit/SWR/tag write, resolved from the matched entry tree exactly as
+ *     handleResponseRoute does. The write is scheduled via ctx.waitUntil
+ *     (a microtask without an executionContext), so a HIT-asserting test must
+ *     flush microtasks between the seeding dispatch and the asserting one.
+ * - Global middleware (router.use(...)) AND route-level middleware, with full
+ *   next()/short-circuit/throw-Response/header+cookie-merge fidelity.
+ * - Partial (client-navigation) requests to a RESPONSE route (?_rsc_partial):
+ *   global middleware runs first (so an auth gate can still 401/redirect),
+ *   then — if it passes through — an X-RSC-Reload is returned. Route-level
+ *   middleware is skipped on a partial, exactly as production skips it.
+ * - A middleware redirect (3xx + Location) on a partial/action request
+ *   (?_rsc_partial / ?_rsc_action): converted to a 204 + X-RSC-Redirect via the
+ *   real interceptRedirectForPartial, so fetch() does not auto-follow the 3xx —
+ *   identical to production's no-location-state path.
+ * - The open-redirect guard (rsc/redirect-guard.ts) on full (browser-followed)
+ *   redirects: a cross-origin Location is rewritten to the basename root unless
+ *   redirect(url, { external: true }) opted out, mirroring production's single
+ *   handler chokepoint. Soft partial/action redirects are 204 and pass through.
+ * - createRouter({ onError }) for CACHE / background-error degradation. dispatch
+ *   wires the request context's _reportBackgroundError to the router's onError the
+ *   same way the production RSC handler does, so a cache-read/cache-write/
+ *   stale-revalidation failure on a cached response route (a throwing route
+ *   cache({ key })/cache({ tags }), or a custom store whose keyGenerator/
+ *   getResponse/putResponse throws) fires onError with phase "cache" and
+ *   metadata.category, while the request still degrades-to-miss exactly as before.
+ *   (A thrown non-Response route HANDLER error is the one onError path NOT covered —
+ *   see "DOES NOT support" below.)
+ * - createRouter({ telemetry }) match-transaction lifecycle: request.start opens
+ *   the transaction before the global middleware chain, request.end closes it
+ *   after finalizeResponse (segmentCount 0 / cacheHit false — dispatch renders no
+ *   RSC segments and holds no match-cache state), and a thrown non-Response error
+ *   emits request.error with phase "routing". All three carry the same requestId
+ *   (getRequestId). Emission is gated entirely on a configured sink; with none,
+ *   dispatch does zero new work and stays byte-identical for existing callers.
+ *   Lets a consumer unit-test their sink wiring in-process instead of only at e2e.
+ * - Response-route `renderStartMs` timeouts and `onTimeout`: dispatch races the
+ *   same terminal response work, reports the timeout through onError/telemetry,
+ *   and invokes the configured callback. `context.render` is absent because this
+ *   primitive deliberately does not run the Flight/HTML render driver.
+ *
+ * What dispatch DOES NOT support (and why):
+ * - RSC component routes — rendering requires the Flight serializer + React
+ *   server runtime, which is the boundary this primitive is defined to avoid.
+ *   This includes partial requests that resolve to a component route.
+ * - Server actions (?_rsc_action) — RSC protocol concerns handled by
+ *   router.fetch().
+ * - createRouter({ onError }) on a thrown non-Response route HANDLER error: the
+ *   error is serialized into the same typed 500 / RouterError Response as
+ *   production, but onError is NOT invoked for that path here. Cover handler-error
+ *   onError side effects with an e2e test. (This is the unchanged boundary; cache
+ *   and other background errors DO route through onError — see below.)
+ * - Location-state-carrying redirects on a partial/action request: production
+ *   embeds a Flight payload (createRedirectFlightResponse) so the client can
+ *   restore location state across the redirect. dispatch is RSC-free, so it
+ *   cannot emit that Flight stream. It falls back to the no-state behavior — a
+ *   204 + X-RSC-Redirect via createSimpleRedirectResponse — dropping the
+ *   embedded location state. The 204 status, the X-RSC-Redirect header, and the
+ *   merged cookies/headers all match production; only the Flight-embedded
+ *   location-state entries are absent. Cover location-state restoration across a
+ *   partial redirect with an e2e test.
+ * - Telemetry cache.decision / loader.* / handler.error events: these fire from
+ *   the real match()/matchPartial() + RSC render + loader pipeline (match-
+ *   handlers.ts, loader-resolution.ts, segment-resolution), none of which
+ *   dispatch runs. Synthesizing them here would be faking (the events would not
+ *   reflect a real cache lookup or loader run), so dispatch emits only the
+ *   request.start/end/error lifecycle above; cover cache/loader telemetry with an
+ *   e2e test driving a real RSC request.
+ *
+ * dispatch reuses router.previewMatch(), which itself runs content negotiation
+ * and resolves route middleware from the matched entry tree, so dispatch's
+ * route-middleware collection is exactly the router's, not a re-implementation.
+ */
+import type { Rango } from "../router/router-interfaces.js";
+/**
+ * Options for dispatch.
+ */
+export interface DispatchOptions<TEnv = any> {
+    /** The request to dispatch: a `Request`, or a URL string (absolute or path). */
+    request: Request | string;
+    /** Environment bindings forwarded to matching and middleware. */
+    env?: TEnv;
+}
+/**
+ * Run a request through the router in-process and return the Response.
+ *
+ * @example
+ * ```ts
+ * const router = createRouter<Env>({}).routes(urls(({ path }) => [
+ *   path.json("/api/health", () => ({ ok: true }), { name: "health" }),
+ * ]));
+ *
+ * const res = await dispatch(router, { request: "/api/health" });
+ * expect(res.status).toBe(200);
+ * expect(await res.json()).toEqual({ ok: true });
+ * ```
+ */
+export declare function dispatch<TEnv = any>(publicRouter: Rango<TEnv, any>, opts: DispatchOptions<TEnv>): Promise<Response>;

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

@@ -0,0 +1,15 @@
+/**
+ * @rangojs/router/testing/dom
+ *
+ * Component-render testing: `renderRoute`, the React-Testing-Library-style stub
+ * for client components that read router context (useParams / useReverse /
+ * Outlet / useOutlet / useNavigation / useLoader).
+ *
+ * Separate from the main `@rangojs/router/testing` barrel so unit suites that
+ * only test loaders, middleware, or `dispatch` never reference React, the
+ * browser runtime, or `@testing-library/react` (an optional peer that
+ * `renderRoute` lazy-loads at call time). Run these tests in a DOM environment
+ * (`happy-dom` or `jsdom`).
+ */
+export { renderRoute } from "./render-route.js";
+export type { RenderRouteSpec, RenderRouteOptions, TestRouterHandle, RenderRouteResult, HandleDataSeed, } from "./render-route.js";

package/dist/types/testing/e2e/fixture.d.ts

@@ -0,0 +1,37 @@
+import type { TestType } from "@playwright/test";
+import { type RunCliHandle, type SpawnOptions } from "./server.js";
+export interface FixtureOptions {
+    /** Absolute or cwd-relative path to the consumer app under test. */
+    root: string;
+    /**
+     * Server mode. Required: omitting it would spawn no server in beforeAll and
+     * surface only as a bare "Invalid URL" from `url()` at first use, so we fail
+     * eagerly at useFixture time instead.
+     */
+    mode: "dev" | "build";
+    /** Override the server command (default: `pnpm dev` for dev, `pnpm preview` for build). */
+    command?: string;
+    /** Override the build command (default: `pnpm build`). */
+    buildCommand?: string;
+    cliOptions?: SpawnOptions;
+    /** Spawn a per-suite server with an isolated Vite cache dir (dev only warmup). */
+    isolatedServer?: boolean;
+    /** Path to poll for readiness (default: "/"). Use when a basename moves routes off "/". */
+    readyPath?: string;
+    /** Skip the production build step (assumes an existing build). */
+    skipBuild?: boolean;
+}
+export interface Fixture {
+    mode: "dev" | "build";
+    root: string;
+    /** Resolve a path against the running server's base URL. */
+    url: (url?: string) => string;
+    /** The underlying spawned process handle (undefined before beforeAll). */
+    proc: () => RunCliHandle | undefined;
+}
+/**
+ * Build a `useFixture` bound to a consumer-provided Playwright `test` object.
+ * The returned function registers `beforeAll`/`afterAll` hooks that spawn and
+ * tear down a dev or preview server for the app at `options.root`.
+ */
+export declare function createUseFixture(test: TestType<any, any>): (options: FixtureOptions) => Fixture;

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

@@ -0,0 +1,31 @@
+import type { Expect, TestType } from "@playwright/test";
+import { createUseFixture, type Fixture, type FixtureOptions } from "./fixture.js";
+import { blockPrefetch, unblockPrefetch, createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, isPrefetchRequest, isVisibleInViewport, measureTime, type PageHelpers, parseNumber, type Stopwatch, testId, waitForElement, waitForHydration, waitForNavigation } from "./page-helpers.js";
+import { createParity, type ExpectParityOptions, type Parity, type ParityDescribeOptions, type ParityIntent } from "./parity.js";
+import { createRangoMatchers, type RangoMatchers } from "./matchers.js";
+export { assertCacheStatus, assertCacheDecision, parseCacheHeader, createCacheSink, filterCacheDecisions, type CacheSink, type ExpectedCacheStatus, type CacheStatusTarget, } from "../cache-status.js";
+export { assertPprReplayStatus, assertShellStatus, parsePprReplayStatus, parseShellStatus, PPR_REPLAY_STATUS_HEADER, shellCacheKey, SHELL_STATUS_HEADER, type PprReplayBypassReason, type PprReplayStatus, type ShellStatus, type ShellStatusTarget, } from "../shell-status.js";
+export { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, isPrefetchRequest, blockPrefetch, unblockPrefetch, parseNumber, getNumericContent, createStopwatch, measureTime, createPageHelpers, createUseFixture, createParity, createRangoMatchers, };
+export type { Fixture, FixtureOptions, PageHelpers, Stopwatch, Parity, ParityIntent, ParityDescribeOptions, ExpectParityOptions, RangoMatchers, };
+export interface RangoE2E extends PageHelpers, Parity {
+    useFixture: (options: FixtureOptions) => Fixture;
+    testNoJs: TestType<any, any>;
+    rangoMatchers: RangoMatchers;
+    testId: typeof testId;
+    waitForHydration: typeof waitForHydration;
+    waitForNavigation: typeof waitForNavigation;
+    goBack: typeof goBack;
+    goForward: typeof goForward;
+    getHistoryState: typeof getHistoryState;
+    waitForElement: typeof waitForElement;
+    isVisibleInViewport: typeof isVisibleInViewport;
+    parseNumber: typeof parseNumber;
+    getNumericContent: typeof getNumericContent;
+    createStopwatch: typeof createStopwatch;
+    measureTime: typeof measureTime;
+}
+export declare function createRangoE2E({ test, expect, defaultRoot, }: {
+    test: TestType<any, any>;
+    expect: Expect;
+    defaultRoot?: string;
+}): RangoE2E;

package/dist/types/testing/e2e/matchers.d.ts

@@ -0,0 +1,17 @@
+import type { Expect, Page } from "@playwright/test";
+interface MatcherResult {
+    pass: boolean;
+    message: () => string;
+}
+export interface RangoMatchers {
+    toHaveRangoPathname: (page: Page, expected: string) => MatcherResult;
+}
+export declare function createRangoMatchers(_expect: Expect): RangoMatchers;
+declare global {
+    namespace PlaywrightTest {
+        interface Matchers<R, T> {
+            toHaveRangoPathname(expected: string): R;
+        }
+    }
+}
+export {};

package/dist/types/testing/e2e/page-helpers.d.ts

@@ -0,0 +1,86 @@
+import type { Expect, Locator, Page } from "@playwright/test";
+/** Get a locator by data-testid attribute. */
+export declare function testId(page: Page, id: string): Locator;
+/**
+ * Wait for React hydration to complete and verify no hydration errors.
+ * Rango sets `data-hydrated` on `<html>` after hydration via useEffect; this
+ * is a stable readiness signal that does not rely on React internals.
+ */
+export declare function waitForHydration(page: Page): Promise<void>;
+/** Wait for navigation to complete (URL change + network idle). */
+export declare function waitForNavigation(page: Page, expectedUrl: string | RegExp): Promise<void>;
+/** Navigate back and wait for navigation to complete. */
+export declare function goBack(page: Page): Promise<void>;
+/** Navigate forward and wait for navigation to complete. */
+export declare function goForward(page: Page): Promise<void>;
+/** Get the current history state. */
+export declare function getHistoryState(page: Page): Promise<unknown>;
+/** Wait for an element to appear and be visible. */
+export declare function waitForElement(page: Page, selector: string, timeout?: number): Promise<void>;
+/** Check if an element is visible. */
+export declare function isVisibleInViewport(page: Page, selector: string): Promise<boolean>;
+/**
+ * Parse a number from text content (finds first number in string).
+ *
+ * @example
+ * parseNumber("Load count: 42") // 42
+ * parseNumber(null) // 0
+ */
+export declare function parseNumber(text: string | null | undefined): number;
+/** Get the numeric value from an element's text content. */
+export declare function getNumericContent(locator: Locator): Promise<number>;
+export interface Stopwatch {
+    elapsed: () => number;
+    checkpoint: () => number;
+}
+/** Create a stopwatch for timing multiple checkpoints. */
+export declare function createStopwatch(): Stopwatch;
+/**
+ * Measure elapsed time for an async operation. Returns `{ elapsed, result }`
+ * where `elapsed` is in milliseconds.
+ */
+export declare function measureTime<T>(fn: () => Promise<T>): Promise<{
+    elapsed: number;
+    result: T;
+}>;
+/**
+ * True when the request is a speculative prefetch (Link viewport/hover/render
+ * strategies or `useRouter().prefetch()`). Every prefetch fetch carries the
+ * `X-Rango-Prefetch` header. Links prefetch by default in production unless
+ * the router opts out, so tests that track `_rsc_partial` requests to pin
+ * NAVIGATION behavior must skip these — a request-count or first-request
+ * assertion otherwise races background prefetch traffic.
+ */
+export declare function isPrefetchRequest(req: {
+    headers: () => Record<string, string>;
+}): boolean;
+/**
+ * Abort every speculative prefetch request on this page. Install BEFORE
+ * `page.goto` so no prefetch can complete first. For tests whose semantics
+ * need a virgin prefetch cache: a click on a Link whose target was already
+ * prefetched ADOPTS the warmed entry and issues no navigation fetch at all —
+ * a `page.route` override, a request waiter, or a Set-Cookie assertion aimed
+ * at the navigation request then sees nothing (or sees the prefetch's side
+ * effects instead). Aborted prefetches are benign by design (evicted, never
+ * adopted, no page error), so the click's real fetch is guaranteed live.
+ */
+export declare function blockPrefetch(page: Page): Promise<void>;
+/** Remove a `blockPrefetch` guard, restoring normal prefetch traffic. */
+export declare function unblockPrefetch(page: Page): Promise<void>;
+export interface PageHelpers {
+    /** Assert that no full page reload occurred between scope entry and exit. */
+    expectNoReload: (page: Page) => AsyncDisposable;
+    /** Collect page errors and assert none occurred on scope exit. */
+    expectNoPageError: (page: Page) => Disposable;
+    /** Wait for an element's text to change from its initial value. */
+    waitForTextChange: (locator: Locator, initialText: string, timeout?: number) => Promise<void>;
+    /** Wait for a numeric value in an element to change. */
+    waitForNumericChange: (locator: Locator, initialValue: number, timeout?: number) => Promise<void>;
+    /** Assert timing is within `expected +/- tolerance`. */
+    expectTiming: (elapsed: number, expected: number, tolerance: number) => void;
+    /** Assert timing is at least `minimum`. */
+    expectMinTiming: (elapsed: number, minimum: number) => void;
+    /** Assert timing is less than `maximum`. */
+    expectMaxTiming: (elapsed: number, maximum: number) => void;
+}
+export declare function createPageHelpers(expect: Expect): PageHelpers;

package/dist/types/testing/e2e/parity.d.ts

@@ -0,0 +1,111 @@
+import type { Expect, Page, TestType } from "@playwright/test";
+import type { Fixture, FixtureOptions } from "./fixture.js";
+export interface ParityDescribeOptions extends Partial<Omit<FixtureOptions, "mode">> {
+}
+export type ParityIntent = {
+    navigate: string;
+} | {
+    submit: {
+        testId: string;
+        data?: Record<string, string>;
+    };
+};
+export interface ExpectParityOptions {
+    /** data-testid values whose text content must match across JS and no-JS. */
+    observe: string[];
+    /** Base URL to resolve a relative `navigate` intent against. */
+    baseURL?: string;
+    /**
+     * Escape hatch invoked after the intent is applied and before the snapshot is
+     * taken, on BOTH the JS and the no-JS transports. When provided for a `submit`
+     * intent it REPLACES the generic settle (the navigation/observed-change wait):
+     * you take responsibility for awaiting the post-submit effect — for example,
+     * awaiting a specific testid to reach a known value, or a network response the
+     * page does not reflect in the observed testids. Receives the page for the
+     * transport being snapshotted.
+     */
+    waitFor?: (page: Page) => Promise<void>;
+    /**
+     * Cookie NAMES to exclude from the JS-vs-no-JS jar comparison, matched exactly
+     * (string) or by pattern (RegExp). The rango state cookie (default prefix
+     * `rango-state`) is ALWAYS excluded — it is written/rotated only by the client
+     * runtime, so it is JS-only by design and never appears in the no-JS jar. Use
+     * this for a custom `stateCookiePrefix` (e.g. `[/^myapp-state_/]`) or any other
+     * volatile/JS-only cookie (analytics, CSRF) that should not break parity.
+     */
+    ignoreCookies?: ReadonlyArray<string | RegExp>;
+}
+export interface Parity {
+    /**
+     * Register a dev describe (title `name`) and a production describe (title
+     * `` `${name} (production)` ``) from one body. The `(production)` suffix is
+     * generated here, so the production suite always lands in the production
+     * bucket regardless of how the consumer names things.
+     *
+     * `options.root` is required, either here or as `defaultRoot` passed to the
+     * factory.
+     */
+    parityDescribe: (name: string, body: (f: Fixture) => void, options?: ParityDescribeOptions) => void;
+    /**
+     * Run a single `intent` over both the JS path (the given `page`) and a
+     * fresh no-JS context, then assert the observed snapshots are equal.
+     *
+     * PE parity only holds if the consumer's submit target is a real `<form>`
+     * that progressively enhances: with JS disabled the browser performs a native
+     * form POST, and the server must produce the same observable result the
+     * enhanced client path produces. Navigation intents must be plain links/URLs
+     * that resolve server-side without JS.
+     *
+     * For a `submit` intent the helper waits for the action's observable effect
+     * before snapshotting: either a navigation away from the form, or a change to
+     * one of the `observe` testids from its pre-submit value (then a brief
+     * stability confirm). A submit that produces neither within ~5s throws —
+     * include the testid that changes in `observe`, or pass `waitFor` to express
+     * the precise wait. This prevents snapshotting the pre-submit DOM when the
+     * action is slow.
+     *
+     * The snapshot is intentionally strict: it compares the text of every
+     * observed `data-testid`, the resulting `page.url()`, and the cookies visible
+     * via `document.cookie`. No ephemeral-value normalization is applied in v1;
+     * if a consumer's page renders nondeterministic values, exclude that testid
+     * from `observe`.
+     *
+     * LIMITATION: cookie parity is read from `document.cookie`, which by design
+     * EXCLUDES HttpOnly cookies. Session/auth cookies (the typical HttpOnly case)
+     * are therefore NOT compared — a PE/JS divergence in an HttpOnly cookie will
+     * not be caught here. Assert on those via `read_network_requests` / response
+     * Set-Cookie headers in a dedicated test, not expectParity.
+     *
+     * Submit-intent requirements (the `submit` path runs the intent TWICE against
+     * the same server, and compares whole cookie jars from two contexts):
+     * - DOUBLE EXECUTION: the JS path submits, then the no-JS pass reloads the
+     *   same `originUrl` in a fresh context and submits AGAIN. Both hit the one
+     *   running server, so a non-idempotent action runs twice. The no-JS snapshot
+     *   then observes BOTH mutations unless the mutated state is per-session /
+     *   per-context — e.g. an add-to-cart count only reaches the same value on
+     *   both transports if the cart is session-scoped (the JS context and the
+     *   fresh no-JS context are distinct sessions). A globally-shared counter
+     *   would read N after the JS submit and N+1 after the no-JS submit and
+     *   false-mismatch. Make the action's observable state session/context-scoped,
+     *   or assert the submit path some other way.
+     * - COOKIE JAR vs DELTA: the cookie check compares the WHOLE `document.cookie`
+     *   of two different contexts. The JS context carries every cookie accumulated
+     *   before the intent (consent, analytics, prior navigations); the fresh no-JS
+     *   context starts empty. Unrelated pre-existing cookies therefore false-
+     *   mismatch — expectParity compares jars, not the per-submit cookie delta.
+     *   Keep the JS context's pre-intent cookie state minimal, or assert the
+     *   specific Set-Cookie elsewhere.
+     * - RANGO STATE COOKIE: the rango state cookie (default prefix `rango-state`)
+     *   is written/rotated only by the client runtime, so it is JS-only by design
+     *   and would always diverge — it is excluded from the comparison
+     *   automatically. A custom `stateCookiePrefix` (or any other volatile/JS-only
+     *   cookie) is excluded via `opts.ignoreCookies`.
+     */
+    expectParity: (page: Page, intent: ParityIntent, opts: ExpectParityOptions) => Promise<void>;
+}
+export declare function createParity({ test: _test, expect, useFixture, defaultRoot, }: {
+    test: TestType<any, any>;
+    expect: Expect;
+    useFixture: (options: FixtureOptions) => Fixture;
+    defaultRoot?: string;
+}): Parity;

package/dist/types/testing/e2e/server.d.ts

@@ -0,0 +1,35 @@
+import { type SpawnOptions } from "node:child_process";
+import { x } from "tinyexec";
+export type { SpawnOptions };
+export interface RunCliHandle {
+    proc: ReturnType<typeof x>["process"];
+    done: Promise<void>;
+    /**
+     * Resolves with the process's exit code (null if killed by signal) when it
+     * exits. Unlike `done`, callers can branch on a nonzero code. Used to fail
+     * the build step loudly; the long-running serve processes never inspect it.
+     */
+    exitCode: Promise<number | null>;
+    findPort: (timeoutMs?: number) => Promise<number>;
+    kill: () => void;
+    stdout: () => string;
+    stderr: () => string;
+}
+export declare function runCli(options: {
+    command: string;
+    label?: string;
+} & SpawnOptions): RunCliHandle;
+export declare function tailOutput(text: string, maxChars?: number): string;
+export declare function createIsolatedViteCacheDir(cwd: string, projectName: string, mode: "dev" | "build" | undefined): string;
+export declare function waitForReady(url: string, getOutput?: () => {
+    stdout: string;
+    stderr: string;
+}, timeoutMs?: number): Promise<void>;
+/**
+ * Warm up an isolated dev server by making real SSR requests.
+ * The first SSR request triggers Vite's dep optimizer to discover SSR deps.
+ * After optimization, modules are re-evaluated and in-memory caches reset.
+ * We retry until the server returns a stable 200, absorbing the dep
+ * optimization cycle so subsequent test requests hit a settled server.
+ */
+export declare function warmupDevServer(url: string): Promise<void>;

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

@@ -0,0 +1,55 @@
+/**
+ * Vitest custom matchers for asserting on REAL Flight wire strings produced by
+ * {@link renderToFlightString}. Register with:
+ *
+ *   import { expect } from "vitest";
+ *   import { flightMatchers } from "@rangojs/router/testing/flight-matchers"; // or local path
+ *   expect.extend(flightMatchers);
+ *
+ * Ergonomic shape (vitest `expect` is single-arg, so the matcher receives the
+ * ALREADY-RENDERED Flight string as `received`):
+ *
+ *   const flight = await renderToFlightString(<Greeting name="Ada" />);
+ *   expect(flight).toMatchFlight("Ada");          // substring containment
+ *   expect(flight).toMatchFlightSnapshot();        // normalized snapshot
+ *
+ * `toMatchFlight(expected)` asserts the NORMALIZED Flight string CONTAINS
+ * `expected`. Containment (not equality) is the v1 contract because the Flight
+ * row prefixes/quoting are an internal serializer detail — tests should pin the
+ * rendered text/shape, not the exact framing. For an exact, drift-detecting
+ * assertion of the whole payload, use `toMatchFlightSnapshot()`.
+ *
+ * Both operate on normalized output (see normalizeFlight): the dev-only
+ * `:N<timestamp>` reference row and absolute `file://` paths are scrubbed so
+ * assertions are stable across runs/machines. Run snapshots under
+ * NODE_ENV=production for the cleanest, most stable payloads.
+ *
+ * Scope: server-only / leaf trees (a client component emits an unresolved
+ * `I[...]` import row against the empty client manifest — see flight.ts).
+ */
+interface MatcherResult {
+    pass: boolean;
+    message: () => string;
+}
+export declare const flightMatchers: {
+    toMatchFlight(received: string, expected: string): MatcherResult;
+    toMatchFlightSnapshot(received: string): MatcherResult;
+};
+/**
+ * Vitest Assertion augmentation so `toMatchFlight` / `toMatchFlightSnapshot`
+ * are typed on `expect(...)`. Imported for its side-effecting type
+ * augmentation; importing flight-matchers (which imports this) is enough.
+ */
+declare module "vitest" {
+    interface Assertion<T = any> {
+        /** Assert the normalized Flight string contains `expected`. */
+        toMatchFlight(expected: string): T;
+        /** Snapshot the normalized Flight string. */
+        toMatchFlightSnapshot(): T;
+    }
+    interface AsymmetricMatchersContaining {
+        toMatchFlight(expected: string): void;
+        toMatchFlightSnapshot(): void;
+    }
+}
+export {};

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

@@ -0,0 +1 @@
+export declare function normalizeFlight(flight: string): string;