@rangojs/router 0.0.0-experimental.tapabs3 → 0.1.0

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 { 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 { assertShellStatus, parseShellStatus, shellCacheKey, SHELL_STATUS_HEADER, type ShellStatus, type ShellStatusTarget, } from "../shell-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/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,62 @@
+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/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;

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;