@noego/wood 0.4.6 → 0.4.7

package/dist/testing/browser.d.cts

@@ -1,5 +1,6 @@
-import { TraceLevel } from '../tracing/trace_hub.cjs';
+import { c as TraceLevel } from '../trace_hub-Cob54qRx.cjs';
 import { TraceRecorder } from '../trace-testing/trace_recorder.cjs';
+import { WoodRpcTransport } from '../transport/wood_rpc_transport.cjs';
 import 'rxjs';
 import '@noego/trace/testing';
 import '../tracing/trace_provider.cjs';
@@ -31,6 +32,30 @@ interface WoodBridgeFixtureInput {
     operations?: Record<string, OperationHandler>;
     events?: Record<string, unknown | unknown[]>;
     record?: boolean;
+    /**
+     * Real-backend mode. When supplied, page `invoke` is routed through this
+     * `WoodRpcTransport` (dispatching through the REAL WoodRouter — full schema
+     * validation) instead of the fixture `operations` Map, and page `bridge.on(...)`
+     * subscriptions are relayed to `transport.subscribe(...)` so main-process push
+     * events reach page subscribers. Fixture `operations` still act as a fallback
+     * for any channel not registered on the transport, so hybrid fixtures work.
+     * Omit for the legacy fixture-only bridge (spec §4: labeled visual tests).
+     */
+    transport?: WoodRpcTransport;
+    /**
+     * Full RPC manifest to build the page bridge tree from. Required in transport
+     * mode so every real channel is exposed on the bridge (in fixture mode the
+     * manifest is derived from `operations`). Supply the app's complete operations
+     * manifest (channel/controller/action/path/hasInput per operation).
+     */
+    rpcManifest?: WoodRpcManifestEntryInput[];
+}
+interface WoodRpcManifestEntryInput {
+    channel: string;
+    controller: string;
+    action: string;
+    path: string[];
+    hasInput: boolean;
 }
 interface WoodBrowserPageContext {
     page: any;
@@ -120,6 +145,43 @@ interface MountedWoodNavigation {
     go(page: string, params?: Record<string, string>, query?: Record<string, string>): Promise<void>;
     replace(page: string, params?: Record<string, string>, query?: Record<string, string>): Promise<void>;
 }
+/** Snapshot of one element's viewport-space box, tagged with its source selector. */
+interface WoodRectSnapshot {
+    selector: string;
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+/** Axis along which edge-to-edge spacing is measured. */
+type WoodSpacingAxis = 'horizontal' | 'vertical';
+/**
+ * Description of the top-most element painted at a hit-test point, plus its
+ * relationship to the queried target. `document.elementFromPoint` honours
+ * `pointer-events`, so an element with `pointer-events: none` is transparent to
+ * the hit test even when it is painted on top (see `hitTest`/`unoccluded`).
+ */
+interface WoodHitTestResult {
+    /** False when no element is painted at the point (e.g. outside the document). */
+    found: boolean;
+    tag: string | null;
+    id: string | null;
+    classes: string[];
+    /** The hit element is exactly the target. */
+    isTarget: boolean;
+    /** The hit element is a descendant of the target (target paints through it). */
+    isDescendantOfTarget: boolean;
+    /** The hit element is an ancestor of the target. */
+    isAncestorOfTarget: boolean;
+    point: {
+        x: number;
+        y: number;
+    };
+    /** Human-readable one-line description of the hit element. */
+    description: string;
+}
 interface WoodBrowserExpect {
     visible(selector: string): Promise<void>;
     hidden(selector: string): Promise<void>;
@@ -128,6 +190,12 @@ interface WoodBrowserExpect {
     }): Promise<void>;
     notClipped(selector: string): Promise<void>;
     notOverlapping(firstSelector: string, secondSelector: string): Promise<void>;
+    /**
+     * @deprecated Compares numeric computed `z-index` only, so it lies whenever
+     * stacking contexts, DOM paint order (auto/equal z-index), or
+     * transform/opacity contexts decide the real front-to-back order. Prefer
+     * `inFrontOf`, which hit-tests the actual painted pixel.
+     */
     zIndexAbove(topSelector: string, lowerSelector: string): Promise<void>;
     stableAfterAnimation(selector?: string, options?: {
         timeoutMs?: number;
@@ -138,6 +206,142 @@ interface WoodBrowserExpect {
         mask?: string[];
         threshold?: number;
     }): Promise<void>;
+    /** Batch `getBoundingClientRect` reader — one snapshot per selector, in order. */
+    rects(selectors: string[]): Promise<WoodRectSnapshot[]>;
+    /**
+     * Hit-test at a point (default the target's center) and describe the top-most
+     * painted element and how it relates to the target.
+     */
+    hitTest(selector: string, point?: {
+        x: number;
+        y: number;
+    } | 'center'): Promise<WoodHitTestResult>;
+    /** Assert two elements share the given edge coordinate within `tolerance` px. */
+    sharedEdge(a: string, b: string, edge: 'left' | 'right' | 'top' | 'bottom', options?: {
+        tolerance?: number;
+    }): Promise<void>;
+    /** Assert two elements share a center axis (centerX/centerY) within `tolerance` px. */
+    sharedAxis(a: string, b: string, axis: 'centerX' | 'centerY', options?: {
+        tolerance?: number;
+    }): Promise<void>;
+    /**
+     * Point-specific "does a click land here" check. Asserts the target receives
+     * the hit test at `point` (default center): the hit-test element is the target
+     * or a descendant of it. Ancestors are accepted only when the target is
+     * empty/zero-content at that point and the ancestor is what paints there — but a
+     * foreign overlay (not in the target's ancestry) fails. Honours
+     * `pointer-events: none`: an overlay so styled does not occlude, because it does
+     * not intercept the click.
+     *
+     * This is NOT the general visibility check — a `pointer-events: none` overlay
+     * that visually hides the element still passes here. For "is any foreign layer
+     * painted on top of the element", prefer `notCovered` (paint-order coverage).
+     */
+    unoccluded(selector: string, options?: {
+        point?: {
+            x: number;
+            y: number;
+        } | 'center';
+    }): Promise<void>;
+    /**
+     * Honest front/behind primitive. DEFAULT (recommended): a whole-element
+     * paint-order comparison backed by Chromium's real paint tree (CDP
+     * `DOMSnapshot.captureSnapshot` with paint order). Passes when `topSelector`
+     * has a strictly greater global paint-order index than `lowerSelector` — i.e.
+     * it is painted later, so it is on top. This answers "which layer paints on
+     * top" for the whole element, independent of overlap or `pointer-events`, and
+     * is Chromium-only.
+     *
+     * Opt-in point form `inFrontOf(top, lower, { at })`: hit-tests a single painted
+     * pixel (`at` defaults to the center of the two rects' intersection) and passes
+     * when the painted element there is the top element (or its descendant) and is
+     * NOT the lower element. Use this only for the point-specific question ("is the
+     * top element the one painted AT THIS SPOT"); it honours `pointer-events` and
+     * requires the rects to intersect when no explicit `at` is given.
+     *
+     * If an element has multiple paint fragments, its maximum paint-order index is
+     * used. When the rects do not overlap the paint-order verdict is still valid
+     * (paint order is global), but the failure message notes there is no shared
+     * pixel where front/behind is visually observable.
+     */
+    inFrontOf(topSelector: string, lowerSelector: string, options?: {
+        at?: {
+            x: number;
+            y: number;
+        };
+    }): Promise<void>;
+    /**
+     * Whole-element painted-coverage check: assert that NO foreign element paints
+     * on top of the target anywhere its rect overlaps. Backed by Chromium's real
+     * paint tree (CDP `DOMSnapshot.captureSnapshot` with paint order + computed
+     * styles + DOM rects), it is the honest, INSPECTABLE replacement for the old
+     * IntersectionObserver-v2 `fullyVisible` matcher, whose `isVisible` field is a
+     * black box that silently reports not-visible for any element painted on top —
+     * even a fully transparent one (see "why not IntersectionObserver v2" in the
+     * geometry docs).
+     *
+     * Algorithm (Chromium-only):
+     *  1. Find every laid-out element whose layout rect intersects the target's rect.
+     *  2. Exclude the target itself and its ancestors/descendants (they are not
+     *     foreign coverage — the target paints through its own subtree).
+     *  3. Exclude candidates that paint nothing visible in the overlap, per an
+     *     explicit transparent-wrapper heuristic: computed `opacity: 0` OR
+     *     `visibility: hidden`, OR (no background-color alpha AND
+     *     `background-image: none` AND all four border widths `0px` AND no own text
+     *     or replaced/image content). This is the ONE rule that lets a transparent
+     *     positioning wrapper spanning the target pass; it is intentionally
+     *     documented and testable, unlike IOv2's opaque verdict. (`box-shadow`,
+     *     `outline` and other purely decorative paints are NOT counted as coverage.)
+     *  4. Fail if any remaining foreign candidate has a strictly HIGHER max paint
+     *     order than the target (painted later == on top). The failure names the
+     *     covering element (tag/id/classes), its rect, and both paint indices.
+     *
+     * Note this tracks PAINTED coverage, so an opaque `pointer-events: none` overlay
+     * DOES fail `notCovered` (it paints pixels on top) while `unoccluded` still
+     * passes (it is transparent to hit testing) — the complementary pair of
+     * "painted coverage" vs "click reachability".
+     */
+    notCovered(selector: string): Promise<void>;
+    /**
+     * Assert the edge-to-edge gap between two elements along `axis` satisfies a
+     * numeric constraint. The order is derived from the rects, not the argument
+     * order: the box with the smaller leading edge (left for `'horizontal'`, top
+     * for `'vertical'`) is treated as the earlier box and the gap is
+     * `later.leading - earlier.trailing` (horizontal: `later.left - earlier.right`;
+     * vertical: `later.top - earlier.bottom`).
+     *
+     * At least one of `equals` / `min` / `max` is required. `equals` passes when
+     * `|gap - equals| <= tolerance`; `min`/`max` are inclusive within `tolerance`.
+     * A negative gap means the border boxes OVERLAP along the axis; that fails
+     * clearly UNLESS the constraint explicitly allows negatives (a negative
+     * `equals` or `min`). The failure message states both rects, the computed gap,
+     * and the expected constraint.
+     *
+     * BORDER-BOX CAVEAT: rects are border boxes (`getBoundingClientRect`), so the
+     * gap is the distance between the elements' outer borders and EXCLUDES any
+     * padding inside either element. To assert visual whitespace between inner
+     * content, target the inner content elements instead of their padded wrappers.
+     */
+    gapBetween(a: string, b: string, axis: WoodSpacingAxis, options: {
+        equals?: number;
+        min?: number;
+        max?: number;
+        tolerance?: number;
+    }): Promise<void>;
+    /**
+     * Assert three or more elements are evenly spaced along `axis`. Requires at
+     * least 3 selectors; the elements are sorted by their leading edge along the
+     * axis, adjacent edge-to-edge gaps are computed, and the assertion passes when
+     * `max gap - min gap <= tolerance`. The failure message lists every adjacent
+     * gap in sorted order and names the widest and narrowest (offending) pairs.
+     *
+     * BORDER-BOX CAVEAT: gaps are measured between border boxes
+     * (`getBoundingClientRect`), so they exclude padding inside the elements. Tests
+     * that care about visual whitespace should target inner content elements.
+     */
+    evenlySpaced(selectors: string[], axis: WoodSpacingAxis, options?: {
+        tolerance?: number;
+    }): Promise<void>;
 }
 interface MountedWoodSurface {
     page: any;
@@ -161,6 +365,12 @@ interface WoodBrowserHarness {
     mountRoute(routeKey: string, options?: MountRouteOptions): Promise<MountedWoodRoute>;
     mountComponent(component: string, options?: MountComponentOptions): Promise<MountedWoodComponent>;
     mountTree(tree: MountTreeOptions): Promise<MountedWoodTree>;
+    /**
+     * Drain in-flight renderer `__trace` exposeBinding round-trips so the caller's
+     * trace-flush barrier (e.g. `TraceCommitWriter.requestRendererFlush`) has a
+     * definite quiescent point. Resolves immediately when no page is mounted.
+     */
+    flushRendererTraces(): Promise<void>;
     destroy(): Promise<void>;
 }
 type BridgeState = {
@@ -169,6 +379,8 @@ type BridgeState = {
     calls: WoodBridgeRecordedCall[];
     emittedEvents: WoodBridgeRecordedEvent[];
     record: boolean;
+    transport?: WoodRpcTransport;
+    rpcManifest?: WoodRpcManifestEntryInput[];
 };
 type RuntimeBridgeManifestEntry = {
     channel: string;
@@ -190,11 +402,15 @@ declare global {
     interface Window {
         __WOOD_BROWSER_APP__?: unknown;
         __WOOD_BROWSER_DEFAULT_ROUTE__?: string;
+        __WOOD_BROWSER_NAV__?: unknown;
         __WOOD_BROWSER_BRIDGE_MANIFEST__?: RuntimeBridgeManifestEntry[];
         __woodBrowserInvoke?: (channel: string, input: unknown) => Promise<unknown>;
+        __woodBrowserSubscribe?: (channel: string) => void;
         __woodBrowserEmit?: (channel: string, payload: unknown) => void;
-        __woodBrowserTrace?: (payload: unknown) => void;
+        __woodBrowserTrace?: (payload: unknown) => Promise<unknown> | void;
+        __woodBrowserTracePending?: Set<Promise<unknown>>;
+        __woodBrowserTraceFlush?: () => Promise<void>;
     }
 }
 
-export { type MountComponentOptions, type MountRouteOptions, type MountTreeOptions, type MountedWoodBridge, type MountedWoodComponent, type MountedWoodNavigation, type MountedWoodRoute, type MountedWoodSurface, type MountedWoodTree, type WoodBridgeFixtureContext, type WoodBridgeFixtureInput, type WoodBridgeRecordedCall, type WoodBridgeRecordedEvent, type WoodBrowserExpect, type WoodBrowserHarness, type WoodBrowserHarnessConfig, type WoodBrowserPageContext, type WoodBrowserTraceConfig, type WoodViewport, browser, createBrowserBridgeFixture };
+export { type MountComponentOptions, type MountRouteOptions, type MountTreeOptions, type MountedWoodBridge, type MountedWoodComponent, type MountedWoodNavigation, type MountedWoodRoute, type MountedWoodSurface, type MountedWoodTree, type WoodBridgeFixtureContext, type WoodBridgeFixtureInput, type WoodBridgeRecordedCall, type WoodBridgeRecordedEvent, type WoodBrowserExpect, type WoodBrowserHarness, type WoodBrowserHarnessConfig, type WoodBrowserPageContext, type WoodBrowserTraceConfig, type WoodHitTestResult, type WoodRectSnapshot, type WoodRpcManifestEntryInput, type WoodSpacingAxis, type WoodViewport, browser, createBrowserBridgeFixture };

package/dist/testing/browser.d.ts

@@ -1,5 +1,6 @@
-import { TraceLevel } from '../tracing/trace_hub.js';
+import { c as TraceLevel } from '../trace_hub-Cob54qRx.js';
 import { TraceRecorder } from '../trace-testing/trace_recorder.js';
+import { WoodRpcTransport } from '../transport/wood_rpc_transport.js';
 import 'rxjs';
 import '@noego/trace/testing';
 import '../tracing/trace_provider.js';
@@ -31,6 +32,30 @@ interface WoodBridgeFixtureInput {
     operations?: Record<string, OperationHandler>;
     events?: Record<string, unknown | unknown[]>;
     record?: boolean;
+    /**
+     * Real-backend mode. When supplied, page `invoke` is routed through this
+     * `WoodRpcTransport` (dispatching through the REAL WoodRouter — full schema
+     * validation) instead of the fixture `operations` Map, and page `bridge.on(...)`
+     * subscriptions are relayed to `transport.subscribe(...)` so main-process push
+     * events reach page subscribers. Fixture `operations` still act as a fallback
+     * for any channel not registered on the transport, so hybrid fixtures work.
+     * Omit for the legacy fixture-only bridge (spec §4: labeled visual tests).
+     */
+    transport?: WoodRpcTransport;
+    /**
+     * Full RPC manifest to build the page bridge tree from. Required in transport
+     * mode so every real channel is exposed on the bridge (in fixture mode the
+     * manifest is derived from `operations`). Supply the app's complete operations
+     * manifest (channel/controller/action/path/hasInput per operation).
+     */
+    rpcManifest?: WoodRpcManifestEntryInput[];
+}
+interface WoodRpcManifestEntryInput {
+    channel: string;
+    controller: string;
+    action: string;
+    path: string[];
+    hasInput: boolean;
 }
 interface WoodBrowserPageContext {
     page: any;
@@ -120,6 +145,43 @@ interface MountedWoodNavigation {
     go(page: string, params?: Record<string, string>, query?: Record<string, string>): Promise<void>;
     replace(page: string, params?: Record<string, string>, query?: Record<string, string>): Promise<void>;
 }
+/** Snapshot of one element's viewport-space box, tagged with its source selector. */
+interface WoodRectSnapshot {
+    selector: string;
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+}
+/** Axis along which edge-to-edge spacing is measured. */
+type WoodSpacingAxis = 'horizontal' | 'vertical';
+/**
+ * Description of the top-most element painted at a hit-test point, plus its
+ * relationship to the queried target. `document.elementFromPoint` honours
+ * `pointer-events`, so an element with `pointer-events: none` is transparent to
+ * the hit test even when it is painted on top (see `hitTest`/`unoccluded`).
+ */
+interface WoodHitTestResult {
+    /** False when no element is painted at the point (e.g. outside the document). */
+    found: boolean;
+    tag: string | null;
+    id: string | null;
+    classes: string[];
+    /** The hit element is exactly the target. */
+    isTarget: boolean;
+    /** The hit element is a descendant of the target (target paints through it). */
+    isDescendantOfTarget: boolean;
+    /** The hit element is an ancestor of the target. */
+    isAncestorOfTarget: boolean;
+    point: {
+        x: number;
+        y: number;
+    };
+    /** Human-readable one-line description of the hit element. */
+    description: string;
+}
 interface WoodBrowserExpect {
     visible(selector: string): Promise<void>;
     hidden(selector: string): Promise<void>;
@@ -128,6 +190,12 @@ interface WoodBrowserExpect {
     }): Promise<void>;
     notClipped(selector: string): Promise<void>;
     notOverlapping(firstSelector: string, secondSelector: string): Promise<void>;
+    /**
+     * @deprecated Compares numeric computed `z-index` only, so it lies whenever
+     * stacking contexts, DOM paint order (auto/equal z-index), or
+     * transform/opacity contexts decide the real front-to-back order. Prefer
+     * `inFrontOf`, which hit-tests the actual painted pixel.
+     */
     zIndexAbove(topSelector: string, lowerSelector: string): Promise<void>;
     stableAfterAnimation(selector?: string, options?: {
         timeoutMs?: number;
@@ -138,6 +206,142 @@ interface WoodBrowserExpect {
         mask?: string[];
         threshold?: number;
     }): Promise<void>;
+    /** Batch `getBoundingClientRect` reader — one snapshot per selector, in order. */
+    rects(selectors: string[]): Promise<WoodRectSnapshot[]>;
+    /**
+     * Hit-test at a point (default the target's center) and describe the top-most
+     * painted element and how it relates to the target.
+     */
+    hitTest(selector: string, point?: {
+        x: number;
+        y: number;
+    } | 'center'): Promise<WoodHitTestResult>;
+    /** Assert two elements share the given edge coordinate within `tolerance` px. */
+    sharedEdge(a: string, b: string, edge: 'left' | 'right' | 'top' | 'bottom', options?: {
+        tolerance?: number;
+    }): Promise<void>;
+    /** Assert two elements share a center axis (centerX/centerY) within `tolerance` px. */
+    sharedAxis(a: string, b: string, axis: 'centerX' | 'centerY', options?: {
+        tolerance?: number;
+    }): Promise<void>;
+    /**
+     * Point-specific "does a click land here" check. Asserts the target receives
+     * the hit test at `point` (default center): the hit-test element is the target
+     * or a descendant of it. Ancestors are accepted only when the target is
+     * empty/zero-content at that point and the ancestor is what paints there — but a
+     * foreign overlay (not in the target's ancestry) fails. Honours
+     * `pointer-events: none`: an overlay so styled does not occlude, because it does
+     * not intercept the click.
+     *
+     * This is NOT the general visibility check — a `pointer-events: none` overlay
+     * that visually hides the element still passes here. For "is any foreign layer
+     * painted on top of the element", prefer `notCovered` (paint-order coverage).
+     */
+    unoccluded(selector: string, options?: {
+        point?: {
+            x: number;
+            y: number;
+        } | 'center';
+    }): Promise<void>;
+    /**
+     * Honest front/behind primitive. DEFAULT (recommended): a whole-element
+     * paint-order comparison backed by Chromium's real paint tree (CDP
+     * `DOMSnapshot.captureSnapshot` with paint order). Passes when `topSelector`
+     * has a strictly greater global paint-order index than `lowerSelector` — i.e.
+     * it is painted later, so it is on top. This answers "which layer paints on
+     * top" for the whole element, independent of overlap or `pointer-events`, and
+     * is Chromium-only.
+     *
+     * Opt-in point form `inFrontOf(top, lower, { at })`: hit-tests a single painted
+     * pixel (`at` defaults to the center of the two rects' intersection) and passes
+     * when the painted element there is the top element (or its descendant) and is
+     * NOT the lower element. Use this only for the point-specific question ("is the
+     * top element the one painted AT THIS SPOT"); it honours `pointer-events` and
+     * requires the rects to intersect when no explicit `at` is given.
+     *
+     * If an element has multiple paint fragments, its maximum paint-order index is
+     * used. When the rects do not overlap the paint-order verdict is still valid
+     * (paint order is global), but the failure message notes there is no shared
+     * pixel where front/behind is visually observable.
+     */
+    inFrontOf(topSelector: string, lowerSelector: string, options?: {
+        at?: {
+            x: number;
+            y: number;
+        };
+    }): Promise<void>;
+    /**
+     * Whole-element painted-coverage check: assert that NO foreign element paints
+     * on top of the target anywhere its rect overlaps. Backed by Chromium's real
+     * paint tree (CDP `DOMSnapshot.captureSnapshot` with paint order + computed
+     * styles + DOM rects), it is the honest, INSPECTABLE replacement for the old
+     * IntersectionObserver-v2 `fullyVisible` matcher, whose `isVisible` field is a
+     * black box that silently reports not-visible for any element painted on top —
+     * even a fully transparent one (see "why not IntersectionObserver v2" in the
+     * geometry docs).
+     *
+     * Algorithm (Chromium-only):
+     *  1. Find every laid-out element whose layout rect intersects the target's rect.
+     *  2. Exclude the target itself and its ancestors/descendants (they are not
+     *     foreign coverage — the target paints through its own subtree).
+     *  3. Exclude candidates that paint nothing visible in the overlap, per an
+     *     explicit transparent-wrapper heuristic: computed `opacity: 0` OR
+     *     `visibility: hidden`, OR (no background-color alpha AND
+     *     `background-image: none` AND all four border widths `0px` AND no own text
+     *     or replaced/image content). This is the ONE rule that lets a transparent
+     *     positioning wrapper spanning the target pass; it is intentionally
+     *     documented and testable, unlike IOv2's opaque verdict. (`box-shadow`,
+     *     `outline` and other purely decorative paints are NOT counted as coverage.)
+     *  4. Fail if any remaining foreign candidate has a strictly HIGHER max paint
+     *     order than the target (painted later == on top). The failure names the
+     *     covering element (tag/id/classes), its rect, and both paint indices.
+     *
+     * Note this tracks PAINTED coverage, so an opaque `pointer-events: none` overlay
+     * DOES fail `notCovered` (it paints pixels on top) while `unoccluded` still
+     * passes (it is transparent to hit testing) — the complementary pair of
+     * "painted coverage" vs "click reachability".
+     */
+    notCovered(selector: string): Promise<void>;
+    /**
+     * Assert the edge-to-edge gap between two elements along `axis` satisfies a
+     * numeric constraint. The order is derived from the rects, not the argument
+     * order: the box with the smaller leading edge (left for `'horizontal'`, top
+     * for `'vertical'`) is treated as the earlier box and the gap is
+     * `later.leading - earlier.trailing` (horizontal: `later.left - earlier.right`;
+     * vertical: `later.top - earlier.bottom`).
+     *
+     * At least one of `equals` / `min` / `max` is required. `equals` passes when
+     * `|gap - equals| <= tolerance`; `min`/`max` are inclusive within `tolerance`.
+     * A negative gap means the border boxes OVERLAP along the axis; that fails
+     * clearly UNLESS the constraint explicitly allows negatives (a negative
+     * `equals` or `min`). The failure message states both rects, the computed gap,
+     * and the expected constraint.
+     *
+     * BORDER-BOX CAVEAT: rects are border boxes (`getBoundingClientRect`), so the
+     * gap is the distance between the elements' outer borders and EXCLUDES any
+     * padding inside either element. To assert visual whitespace between inner
+     * content, target the inner content elements instead of their padded wrappers.
+     */
+    gapBetween(a: string, b: string, axis: WoodSpacingAxis, options: {
+        equals?: number;
+        min?: number;
+        max?: number;
+        tolerance?: number;
+    }): Promise<void>;
+    /**
+     * Assert three or more elements are evenly spaced along `axis`. Requires at
+     * least 3 selectors; the elements are sorted by their leading edge along the
+     * axis, adjacent edge-to-edge gaps are computed, and the assertion passes when
+     * `max gap - min gap <= tolerance`. The failure message lists every adjacent
+     * gap in sorted order and names the widest and narrowest (offending) pairs.
+     *
+     * BORDER-BOX CAVEAT: gaps are measured between border boxes
+     * (`getBoundingClientRect`), so they exclude padding inside the elements. Tests
+     * that care about visual whitespace should target inner content elements.
+     */
+    evenlySpaced(selectors: string[], axis: WoodSpacingAxis, options?: {
+        tolerance?: number;
+    }): Promise<void>;
 }
 interface MountedWoodSurface {
     page: any;
@@ -161,6 +365,12 @@ interface WoodBrowserHarness {
     mountRoute(routeKey: string, options?: MountRouteOptions): Promise<MountedWoodRoute>;
     mountComponent(component: string, options?: MountComponentOptions): Promise<MountedWoodComponent>;
     mountTree(tree: MountTreeOptions): Promise<MountedWoodTree>;
+    /**
+     * Drain in-flight renderer `__trace` exposeBinding round-trips so the caller's
+     * trace-flush barrier (e.g. `TraceCommitWriter.requestRendererFlush`) has a
+     * definite quiescent point. Resolves immediately when no page is mounted.
+     */
+    flushRendererTraces(): Promise<void>;
     destroy(): Promise<void>;
 }
 type BridgeState = {
@@ -169,6 +379,8 @@ type BridgeState = {
     calls: WoodBridgeRecordedCall[];
     emittedEvents: WoodBridgeRecordedEvent[];
     record: boolean;
+    transport?: WoodRpcTransport;
+    rpcManifest?: WoodRpcManifestEntryInput[];
 };
 type RuntimeBridgeManifestEntry = {
     channel: string;
@@ -190,11 +402,15 @@ declare global {
     interface Window {
         __WOOD_BROWSER_APP__?: unknown;
         __WOOD_BROWSER_DEFAULT_ROUTE__?: string;
+        __WOOD_BROWSER_NAV__?: unknown;
         __WOOD_BROWSER_BRIDGE_MANIFEST__?: RuntimeBridgeManifestEntry[];
         __woodBrowserInvoke?: (channel: string, input: unknown) => Promise<unknown>;
+        __woodBrowserSubscribe?: (channel: string) => void;
         __woodBrowserEmit?: (channel: string, payload: unknown) => void;
-        __woodBrowserTrace?: (payload: unknown) => void;
+        __woodBrowserTrace?: (payload: unknown) => Promise<unknown> | void;
+        __woodBrowserTracePending?: Set<Promise<unknown>>;
+        __woodBrowserTraceFlush?: () => Promise<void>;
     }
 }
 
-export { type MountComponentOptions, type MountRouteOptions, type MountTreeOptions, type MountedWoodBridge, type MountedWoodComponent, type MountedWoodNavigation, type MountedWoodRoute, type MountedWoodSurface, type MountedWoodTree, type WoodBridgeFixtureContext, type WoodBridgeFixtureInput, type WoodBridgeRecordedCall, type WoodBridgeRecordedEvent, type WoodBrowserExpect, type WoodBrowserHarness, type WoodBrowserHarnessConfig, type WoodBrowserPageContext, type WoodBrowserTraceConfig, type WoodViewport, browser, createBrowserBridgeFixture };
+export { type MountComponentOptions, type MountRouteOptions, type MountTreeOptions, type MountedWoodBridge, type MountedWoodComponent, type MountedWoodNavigation, type MountedWoodRoute, type MountedWoodSurface, type MountedWoodTree, type WoodBridgeFixtureContext, type WoodBridgeFixtureInput, type WoodBridgeRecordedCall, type WoodBridgeRecordedEvent, type WoodBrowserExpect, type WoodBrowserHarness, type WoodBrowserHarnessConfig, type WoodBrowserPageContext, type WoodBrowserTraceConfig, type WoodHitTestResult, type WoodRectSnapshot, type WoodRpcManifestEntryInput, type WoodSpacingAxis, type WoodViewport, browser, createBrowserBridgeFixture };