@rangojs/router 0.4.0 → 0.4.1

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

@@ -1,37 +0,0 @@
-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.backup/testing/e2e/index.d.ts

@@ -1,30 +0,0 @@
-import type { Expect, TestType } from "@playwright/test";
-import { createUseFixture, type Fixture, type FixtureOptions } from "./fixture.js";
-import { createPageHelpers, createStopwatch, getHistoryState, getNumericContent, goBack, goForward, 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 { testId, waitForHydration, waitForNavigation, goBack, goForward, getHistoryState, waitForElement, isVisibleInViewport, 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.backup/testing/e2e/matchers.d.ts

@@ -1,17 +0,0 @@
-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.backup/testing/e2e/page-helpers.d.ts

@@ -1,62 +0,0 @@
-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;
-}>;
-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.backup/testing/e2e/parity.d.ts

@@ -1,111 +0,0 @@
-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.backup/testing/e2e/server.d.ts

@@ -1,35 +0,0 @@
-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.backup/testing/flight-matchers.d.ts

@@ -1,55 +0,0 @@
-/**
- * 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.backup/testing/flight-normalize.d.ts

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

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

@@ -1,192 +0,0 @@
-/**
- * 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.backup/testing/flight.d.ts

@@ -1,115 +0,0 @@
-/**
- * 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;