@react-three-dom/playwright 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _playwright_test from '@playwright/test';
-import { Page } from '@playwright/test';
+import { Page, Locator } from '@playwright/test';
 
 interface ObjectMetadata {
     uuid: string;
@@ -12,6 +12,10 @@ interface ObjectMetadata {
     vertexCount?: number;
     triangleCount?: number;
     instanceCount?: number;
+    fov?: number;
+    near?: number;
+    far?: number;
+    zoom?: number;
     position: [number, number, number];
     rotation: [number, number, number];
     scale: [number, number, number];
@@ -19,6 +23,10 @@ interface ObjectMetadata {
     childrenUuids: string[];
     boundsDirty: boolean;
 }
+/** Options for inspect(). Set includeGeometryData: true to get vertex/index buffers (higher cost). */
+interface InspectOptions {
+    includeGeometryData?: boolean;
+}
 interface ObjectInspection {
     metadata: ObjectMetadata;
     worldMatrix: number[];
@@ -39,6 +47,10 @@ interface ObjectInspection {
             center: [number, number, number];
             radius: number;
         };
+        /** Vertex positions (x,y,z per vertex). Only when inspect(..., { includeGeometryData: true }). */
+        positionData?: number[];
+        /** Triangle indices. Only when inspect(..., { includeGeometryData: true }) and geometry is indexed. */
+        indexData?: number[];
     };
     material?: {
         type: string;
@@ -67,12 +79,139 @@ interface SceneSnapshot {
     objectCount: number;
     tree: SnapshotNode;
 }
+interface CameraState {
+    type: string;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    target: [number, number, number];
+    fov?: number;
+    near: number;
+    far: number;
+    zoom: number;
+    aspect?: number;
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+interface BridgeDiagnostics {
+    version: string;
+    ready: boolean;
+    error?: string;
+    objectCount: number;
+    meshCount: number;
+    groupCount: number;
+    lightCount: number;
+    cameraCount: number;
+    materializedDomNodes: number;
+    maxDomNodes: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    webglRenderer: string;
+    dirtyQueueSize: number;
+}
 declare global {
     interface Window {
         __R3F_DOM_DEBUG__?: boolean;
     }
 }
 
+/**
+ * @module reporter
+ *
+ * Rich terminal reporter for Playwright tests. Outputs ANSI-colored status
+ * messages for bridge lifecycle events (waiting, connected, error), scene
+ * readiness, object lookups (with fuzzy-match suggestions on miss),
+ * interaction timings, assertion failures, and full bridge diagnostics.
+ */
+
+/**
+ * Formatted terminal reporter for react-three-dom Playwright tests.
+ * Logs bridge lifecycle, scene readiness, interaction timings, assertion
+ * failures, and full diagnostics with ANSI colors.
+ */
+declare class R3FReporter {
+    private readonly _page;
+    private _enabled;
+    private _canvasId?;
+    constructor(_page: Page, enabled?: boolean, canvasId?: string);
+    logBridgeWaiting(): void;
+    logBridgeConnected(diag?: BridgeDiagnostics): void;
+    logBridgeError(error: string): void;
+    logSceneReady(objectCount: number): void;
+    logObjectFound(idOrUuid: string, type: string, name?: string): void;
+    logObjectNotFound(idOrUuid: string, suggestions?: Array<{
+        testId?: string;
+        name: string;
+        uuid: string;
+    }>): void;
+    logInteraction(action: string, idOrUuid: string, extra?: string): void;
+    logInteractionDone(action: string, idOrUuid: string, durationMs: number): void;
+    logAssertionFailure(matcherName: string, id: string, detail: string, diag?: BridgeDiagnostics): void;
+    logDiagnostics(): Promise<void>;
+    fetchDiagnostics(): Promise<BridgeDiagnostics | null>;
+    fetchFuzzyMatches(query: string, limit?: number): Promise<Array<{
+        testId?: string;
+        name: string;
+        uuid: string;
+    }>>;
+    private _printDiagnosticsSummary;
+    private _printDiagnosticsFull;
+}
+
+/**
+ * @module diffSnapshots
+ *
+ * Pure scene-diff utility. Compares two {@link SceneSnapshot}s by UUID and
+ * returns added nodes, removed nodes, and per-field property changes
+ * (name, type, testId, visible, position, rotation, scale).
+ *
+ * Stateless and side-effect-free — safe to call from any context.
+ */
+
+/** Describes a single property change on an object that exists in both snapshots. */
+interface SceneDiffChange {
+    uuid: string;
+    field: string;
+    from: unknown;
+    to: unknown;
+}
+/** Result of diffing two scene snapshots. */
+interface SceneDiff {
+    /** Nodes present in `after` but not in `before` (from `after` tree). */
+    added: SnapshotNode[];
+    /** Nodes present in `before` but not in `after` (from `before` tree). */
+    removed: SnapshotNode[];
+    /** Property changes for nodes that exist in both; each entry is one field that changed. */
+    changed: SceneDiffChange[];
+}
+/**
+ * Compare two scene snapshots and return added nodes, removed nodes, and
+ * property changes for nodes that exist in both.
+ *
+ * - **added**: nodes in `after` whose uuid was not in `before`.
+ * - **removed**: nodes in `before` whose uuid was not in `after`.
+ * - **changed**: for each uuid present in both, lists field-level changes
+ *   (name, type, testId, visible, position, rotation, scale).
+ */
+declare function diffSnapshots(before: SceneSnapshot, after: SceneSnapshot): SceneDiff;
+
+/**
+ * @module waiters
+ *
+ * Polling-based wait utilities for Playwright tests. Each waiter polls the
+ * `window.__R3F_DOM__` bridge until a condition is met or a timeout fires.
+ *
+ * - {@link waitForSceneReady} — bridge ready + object count stabilised
+ * - {@link waitForObject} — bridge ready + specific object exists
+ * - {@link waitForIdle} — no property changes for N consecutive frames
+ * - {@link waitForNewObject} — new object(s) appear after a baseline snapshot
+ * - {@link waitForObjectRemoved} — object no longer in the scene
+ *
+ * All waiters fail fast with a rich diagnostic if the bridge reports an
+ * `_error` state, preventing silent timeouts.
+ */
+
 interface WaitForSceneReadyOptions {
     /** How many consecutive stable polls are required. Default: 3 */
     stableChecks?: number;
@@ -88,7 +227,9 @@ interface WaitForSceneReadyOptions {
  * If the bridge exists but `_ready` is false and `_error` is set, this
  * fails immediately with a rich diagnostic message instead of timing out.
  */
-declare function waitForSceneReady(page: Page, options?: WaitForSceneReadyOptions): Promise<void>;
+declare function waitForSceneReady(page: Page, options?: WaitForSceneReadyOptions & {
+    canvasId?: string;
+}): Promise<void>;
 interface WaitForObjectOptions {
     /** Time to wait for the bridge to appear. Default: 30_000 */
     bridgeTimeout?: number;
@@ -107,7 +248,9 @@ interface WaitForObjectOptions {
  *
  * Fails fast if the bridge reports `_ready: false` with an `_error`.
  */
-declare function waitForObject(page: Page, idOrUuid: string, options?: WaitForObjectOptions): Promise<void>;
+declare function waitForObject(page: Page, idOrUuid: string, options?: WaitForObjectOptions & {
+    canvasId?: string;
+}): Promise<void>;
 interface WaitForIdleOptions {
     /** Number of consecutive idle frames required. Default: 10 */
     idleFrames?: number;
@@ -124,7 +267,9 @@ interface WaitForIdleOptions {
  *
  * Checks `_ready === true` before starting. Fails fast if `_error` is set.
  */
-declare function waitForIdle(page: Page, options?: WaitForIdleOptions): Promise<void>;
+declare function waitForIdle(page: Page, options?: WaitForIdleOptions & {
+    canvasId?: string;
+}): Promise<void>;
 interface WaitForNewObjectOptions {
     /**
      * Only consider new objects of this Three.js type (e.g. "Mesh", "Line").
@@ -175,19 +320,88 @@ interface WaitForNewObjectResult {
  * expect(result.count).toBe(1);
  * ```
  */
-declare function waitForNewObject(page: Page, options?: WaitForNewObjectOptions): Promise<WaitForNewObjectResult>;
+declare function waitForNewObject(page: Page, options?: WaitForNewObjectOptions & {
+    canvasId?: string;
+}): Promise<WaitForNewObjectResult>;
+interface WaitForObjectRemovedOptions {
+    /** Time to wait for the bridge to appear. Default: 30_000 */
+    bridgeTimeout?: number;
+    /** Poll interval in ms. Default: 100 */
+    pollIntervalMs?: number;
+    /** Overall timeout in ms (after bridge is ready). Default: 10_000 */
+    timeout?: number;
+}
+/**
+ * Wait until the bridge is ready and an object with the given testId or uuid
+ * is no longer in the scene. Use for delete flows (e.g. user deletes an object,
+ * then you assert it's gone).
+ *
+ * @param page      Playwright Page instance
+ * @param idOrUuid  testId or uuid of the object that should be removed
+ * @param options   Timing options
+ * @throws          If the object is still present after the timeout
+ *
+ * @example
+ * ```ts
+ * await r3f.click('delete-button');
+ * await r3f.waitForObjectRemoved('item-to-delete');
+ * await expect(r3f).not.toExist('item-to-delete');
+ * ```
+ */
+declare function waitForObjectRemoved(page: Page, idOrUuid: string, options?: WaitForObjectRemovedOptions & {
+    canvasId?: string;
+}): Promise<void>;
 
 /** Options for R3FFixture constructor. */
 interface R3FFixtureOptions {
     /** Auto-enable debug logging (forwards browser [r3f-dom:*] logs to test terminal). */
     debug?: boolean;
+    /**
+     * Enable rich diagnostic reporting in the terminal.
+     * Logs bridge status, scene readiness, interaction details, and
+     * failure context automatically. Default: true.
+     */
+    report?: boolean;
+    /** Target a specific canvas by its canvasId. When omitted, uses the default bridge. */
+    canvasId?: string;
 }
+/**
+ * Main API object provided to Playwright tests for interacting with a
+ * react-three-dom scene. Wraps queries, interactions, waiters, snapshot
+ * diffing, and rich terminal diagnostics. Supports multi-canvas apps
+ * via {@link R3FFixture.forCanvas}.
+ */
 declare class R3FFixture {
     private readonly _page;
     private _debugListenerAttached;
+    private readonly _reporter;
+    /** Canvas ID for multi-canvas apps. Undefined = default bridge. */
+    readonly canvasId?: string;
     constructor(_page: Page, opts?: R3FFixtureOptions);
     /** The underlying Playwright Page. */
     get page(): Page;
+    /** Access the reporter for custom diagnostic logging. */
+    get reporter(): R3FReporter;
+    /**
+     * Create a scoped fixture targeting a specific canvas instance.
+     * All queries, interactions, and assertions on the returned fixture
+     * will use `window.__R3F_DOM_INSTANCES__[canvasId]` instead of
+     * `window.__R3F_DOM__`.
+     *
+     * @example
+     * ```typescript
+     * const mainR3f = r3f.forCanvas('main-viewport');
+     * const minimapR3f = r3f.forCanvas('minimap');
+     * await mainR3f.click('building-42');
+     * await expect(minimapR3f).toExist('building-42-marker');
+     * ```
+     */
+    forCanvas(canvasId: string): R3FFixture;
+    /**
+     * List all active canvas IDs registered on the page.
+     * Returns an empty array if only the default (unnamed) bridge is active.
+     */
+    getCanvasIds(): Promise<string[]>;
     /**
      * Enable debug logging. Turns on `window.__R3F_DOM_DEBUG__` in the browser
      * and forwards all `[r3f-dom:*]` console messages to the Node.js test terminal.
@@ -199,41 +413,72 @@ declare class R3FFixture {
     private _attachDebugListener;
     /** Get object metadata by testId or uuid. Returns null if not found. */
     getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
-    /** Get heavy inspection data (Tier 2) by testId or uuid. */
-    inspect(idOrUuid: string): Promise<ObjectInspection | null>;
+    /** Get object metadata by testId (userData.testId). Returns null if not found. */
+    getByTestId(testId: string): Promise<ObjectMetadata | null>;
+    /** Get object metadata by UUID. Returns null if not found. */
+    getByUuid(uuid: string): Promise<ObjectMetadata | null>;
+    /** Get all objects with the given name (names are not unique in Three.js). */
+    getByName(name: string): Promise<ObjectMetadata[]>;
+    /** Get direct children of an object by testId or uuid. */
+    getChildren(idOrUuid: string): Promise<ObjectMetadata[]>;
+    /** Get parent of an object by testId or uuid. Returns null if root or not found. */
+    getParent(idOrUuid: string): Promise<ObjectMetadata | null>;
+    /** Get heavy inspection data (Tier 2) by testId or uuid. Pass { includeGeometryData: true } to include vertex positions and triangle indices. */
+    inspect(idOrUuid: string, options?: {
+        includeGeometryData?: boolean;
+    }): Promise<ObjectInspection | null>;
+    /**
+     * Get world-space position [x, y, z] of an object (from its world matrix).
+     * Use for nested objects where local position differs from world position.
+     */
+    getWorldPosition(idOrUuid: string): Promise<[number, number, number] | null>;
     /** Take a full scene snapshot. */
     snapshot(): Promise<SceneSnapshot | null>;
+    /**
+     * Compare two scene snapshots: returns added nodes, removed nodes, and
+     * property changes (name, type, testId, visible, position, rotation, scale).
+     * Use after taking snapshots before/after an action to assert on scene changes.
+     */
+    diffSnapshots(before: SceneSnapshot, after: SceneSnapshot): SceneDiff;
+    /**
+     * Run an async action and return how many objects were added and removed
+     * compared to before the action. Uses snapshots before/after so add and
+     * remove are both counted correctly when both happen.
+     */
+    trackObjectCount(action: () => Promise<void>): Promise<{
+        added: number;
+        removed: number;
+    }>;
     /** Get the total number of tracked objects. */
     getCount(): Promise<number>;
+    /**
+     * Return a Playwright locator for the R3F canvas element the bridge is attached to.
+     * The canvas has `data-r3f-canvas` set by the bridge (value is the canvasId or "true").
+     */
+    getCanvasLocator(): Locator;
     /**
      * Get all objects of a given Three.js type (e.g. "Mesh", "Group", "Line").
-     * Useful for BIM/CAD apps to find all walls, doors, etc. by object type.
      */
     getByType(type: string): Promise<ObjectMetadata[]>;
+    /**
+     * Get all objects with a given geometry type (e.g. "BoxGeometry", "BufferGeometry").
+     */
+    getByGeometryType(type: string): Promise<ObjectMetadata[]>;
+    /**
+     * Get all objects with a given material type (e.g. "MeshStandardMaterial").
+     */
+    getByMaterialType(type: string): Promise<ObjectMetadata[]>;
     /**
      * Get objects that have a specific userData key (and optionally matching value).
-     * Useful for BIM/CAD apps where objects are tagged with metadata like
-     * `userData.category = "wall"` or `userData.floorId = 2`.
      */
     getByUserData(key: string, value?: unknown): Promise<ObjectMetadata[]>;
     /**
      * Count objects of a given Three.js type.
-     * More efficient than `getByType(type).then(arr => arr.length)`.
      */
     getCountByType(type: string): Promise<number>;
     /**
      * Batch lookup: get metadata for multiple objects by testId or uuid in a
-     * single browser round-trip. Returns a record from id to metadata (or null).
-     *
-     * Much more efficient than calling `getObject()` in a loop for BIM/CAD
-     * scenes with many objects.
-     *
-     * @example
-     * ```typescript
-     * const results = await r3f.getObjects(['wall-1', 'door-2', 'window-3']);
-     * expect(results['wall-1']).not.toBeNull();
-     * expect(results['door-2']?.type).toBe('Mesh');
-     * ```
+     * single browser round-trip.
      */
     getObjects(ids: string[]): Promise<Record<string, ObjectMetadata | null>>;
     /**
@@ -272,6 +517,11 @@ declare class R3FFixture {
      * Auto-waits for the object to exist.
      */
     hover(idOrUuid: string, timeout?: number): Promise<void>;
+    /**
+     * Unhover / pointer-leave — resets hover state by moving pointer off-canvas.
+     * Auto-waits for the bridge to be ready.
+     */
+    unhover(timeout?: number): Promise<void>;
     /**
      * Drag a 3D object with a world-space delta vector.
      * Auto-waits for the object to exist.
@@ -316,9 +566,15 @@ declare class R3FFixture {
         eventCount: number;
         pointCount: number;
     }>;
+    /**
+     * Get the current camera state (position, rotation, fov, near, far, zoom, target).
+     * Auto-waits for the bridge to be ready.
+     */
+    getCameraState(timeout?: number): Promise<CameraState>;
     /**
      * Wait until the scene is ready — `window.__R3F_DOM__` is available and
      * the object count has stabilised across several consecutive checks.
+     * Logs bridge connection and scene readiness to the terminal.
      */
     waitForSceneReady(options?: WaitForSceneReadyOptions): Promise<void>;
     /**
@@ -341,10 +597,25 @@ declare class R3FFixture {
      * @returns        Metadata of the newly added object(s)
      */
     waitForNewObject(options?: WaitForNewObjectOptions): Promise<WaitForNewObjectResult>;
+    /**
+     * Wait until an object (by testId or uuid) is no longer in the scene.
+     * Use for delete flows: trigger removal, then wait until the object is gone.
+     */
+    waitForObjectRemoved(idOrUuid: string, options?: WaitForObjectRemovedOptions): Promise<void>;
     /** Select a 3D object by testId or uuid (highlights in scene). */
     select(idOrUuid: string): Promise<void>;
     /** Clear the current selection. */
     clearSelection(): Promise<void>;
+    /**
+     * Fetch full bridge diagnostics (version, object counts, GPU info, etc.).
+     * Returns null if the bridge is not available.
+     */
+    getDiagnostics(): Promise<BridgeDiagnostics | null>;
+    /**
+     * Print a full diagnostics report to the terminal.
+     * Useful at the start of a test suite or when debugging failures.
+     */
+    logDiagnostics(): Promise<void>;
 }
 declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
     r3f: R3FFixture;
@@ -361,11 +632,43 @@ declare function createR3FTest(options?: R3FFixtureOptions): _playwright_test.Te
     r3f: R3FFixture;
 }, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
 
+/**
+ * @module assertions
+ *
+ * Custom Playwright `expect` matchers for 3D scene testing via react-three-dom.
+ *
+ * Every matcher auto-retries until the assertion passes or the timeout
+ * expires, matching Playwright's built-in assertion behaviour.
+ *
+ * **Tier 1 — Metadata:** toExist, toBeVisible, toHavePosition,
+ * toHaveWorldPosition, toHaveRotation, toHaveScale, toHaveType, toHaveName,
+ * toHaveGeometryType, toHaveMaterialType, toHaveChildCount, toHaveParent,
+ * toHaveInstanceCount
+ *
+ * **Tier 2 — Inspection:** toBeInFrustum, toHaveBounds, toHaveColor,
+ * toHaveOpacity, toBeTransparent, toHaveVertexCount, toHaveTriangleCount,
+ * toHaveUserData, toHaveMapTexture
+ *
+ * **Scene-level:** toHaveObjectCount, toHaveObjectCountGreaterThan,
+ * toHaveCountByType, toHaveTotalTriangleCount,
+ * toHaveTotalTriangleCountLessThan
+ *
+ * **Camera:** toHaveCameraPosition, toHaveCameraFov, toHaveCameraNear,
+ * toHaveCameraFar, toHaveCameraZoom
+ *
+ * **Batch:** toAllExist, toAllBeVisible, toNoneExist
+ */
+
 interface R3FMatcherReceiver {
     page: Page;
+    canvasId?: string;
     getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
     inspect(idOrUuid: string): Promise<ObjectInspection | null>;
 }
+/** Context provided by Playwright when the matcher is invoked via expect().extend() */
+interface ExpectMatcherContext {
+    isNot?: boolean;
+}
 interface MatcherOptions {
     timeout?: number;
     interval?: number;
@@ -373,15 +676,15 @@ interface MatcherOptions {
 type Vec3Opts = MatcherOptions & {
     tolerance?: number;
 };
-declare const expect: _playwright_test.Expect<{
-    toExist(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
+declare const r3fMatchers: {
+    toExist(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: null;
     }>;
-    toBeVisible(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
+    toBeVisible(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
@@ -392,84 +695,95 @@ declare const expect: _playwright_test.Expect<{
         expected: boolean;
         actual: boolean;
     }>;
-    toHavePosition(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
+    toHavePosition(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: [number, number, number];
         actual: [number, number, number];
     }>;
-    toHaveRotation(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
+    toHaveWorldPosition(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: [number, number, number];
         actual: [number, number, number];
     }>;
-    toHaveScale(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
+    toHaveRotation(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: [number, number, number];
         actual: [number, number, number];
     }>;
-    toHaveType(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedType: string, opts?: MatcherOptions): Promise<{
+    toHaveScale(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: [number, number, number];
+        actual: [number, number, number];
+    }>;
+    toHaveType(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedType: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: string;
     }>;
-    toHaveName(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedName: string, opts?: MatcherOptions): Promise<{
+    toHaveName(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedName: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: string;
     }>;
-    toHaveGeometryType(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedGeo: string, opts?: MatcherOptions): Promise<{
+    toHaveGeometryType(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedGeo: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: string | undefined;
     }>;
-    toHaveMaterialType(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedMat: string, opts?: MatcherOptions): Promise<{
+    toHaveMaterialType(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedMat: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: string | undefined;
     }>;
-    toHaveChildCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+    toHaveChildCount(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
@@ -480,18 +794,18 @@ declare const expect: _playwright_test.Expect<{
         expected: number;
         actual: number;
     }>;
-    toHaveParent(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedParent: string, opts?: MatcherOptions): Promise<{
+    toHaveParent(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedParent: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: string | null;
     }>;
-    toHaveInstanceCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+    toHaveInstanceCount(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
@@ -502,12 +816,12 @@ declare const expect: _playwright_test.Expect<{
         expected: number;
         actual: number;
     }>;
-    toBeInFrustum(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
+    toBeInFrustum(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
@@ -516,7 +830,7 @@ declare const expect: _playwright_test.Expect<{
             max: [number, number, number];
         };
     }>;
-    toHaveBounds(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expected: {
+    toHaveBounds(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expected: {
         min: [number, number, number];
         max: [number, number, number];
     }, tolOpts?: number | Vec3Opts): Promise<{
@@ -524,7 +838,7 @@ declare const expect: _playwright_test.Expect<{
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: {
@@ -536,40 +850,40 @@ declare const expect: _playwright_test.Expect<{
             max: [number, number, number];
         };
     }>;
-    toHaveColor(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedColor: string, opts?: MatcherOptions): Promise<{
+    toHaveColor(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedColor: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: string | undefined;
     }>;
-    toHaveOpacity(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedOpacity: number, tolOpts?: number | Vec3Opts): Promise<{
+    toHaveOpacity(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedOpacity: number, tolOpts?: number | Vec3Opts): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: number;
         actual: number | undefined;
     }>;
-    toBeTransparent(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
+    toBeTransparent(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: boolean;
         actual: boolean | undefined;
     }>;
-    toHaveVertexCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+    toHaveVertexCount(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
@@ -580,7 +894,7 @@ declare const expect: _playwright_test.Expect<{
         expected: number;
         actual: number;
     }>;
-    toHaveTriangleCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+    toHaveTriangleCount(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
@@ -591,23 +905,23 @@ declare const expect: _playwright_test.Expect<{
         expected: number;
         actual: number;
     }>;
-    toHaveUserData(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, key: string, expectedValue?: unknown, opts?: MatcherOptions): Promise<{
+    toHaveUserData(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, key: string, expectedValue?: unknown, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: {};
         actual: unknown;
     }>;
-    toHaveMapTexture(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedName?: string, opts?: MatcherOptions): Promise<{
+    toHaveMapTexture(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, id: string, expectedName?: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
     } | {
-        pass: false;
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
@@ -620,8 +934,8 @@ declare const expect: _playwright_test.Expect<{
      * @example expect(r3f).toHaveObjectCount(42);
      * @example expect(r3f).toHaveObjectCount(42, { timeout: 10_000 });
      */
-    toHaveObjectCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, expected: number, options?: MatcherOptions): Promise<{
-        pass: false;
+    toHaveObjectCount(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, expected: number, options?: MatcherOptions): Promise<{
+        pass: boolean;
         message: () => string;
         name: string;
         expected: number;
@@ -633,8 +947,8 @@ declare const expect: _playwright_test.Expect<{
      *
      * @example expect(r3f).toHaveObjectCountGreaterThan(10);
      */
-    toHaveObjectCountGreaterThan(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, min: number, options?: MatcherOptions): Promise<{
-        pass: false;
+    toHaveObjectCountGreaterThan(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, min: number, options?: MatcherOptions): Promise<{
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
@@ -647,8 +961,8 @@ declare const expect: _playwright_test.Expect<{
      * @example expect(r3f).toHaveCountByType('Mesh', 5);
      * @example expect(r3f).toHaveCountByType('Line', 10, { timeout: 10_000 });
      */
-    toHaveCountByType(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, type: string, expected: number, options?: MatcherOptions): Promise<{
-        pass: false;
+    toHaveCountByType(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, type: string, expected: number, options?: MatcherOptions): Promise<{
+        pass: boolean;
         message: () => string;
         name: string;
         expected: number;
@@ -661,8 +975,8 @@ declare const expect: _playwright_test.Expect<{
      * @example expect(r3f).toHaveTotalTriangleCount(50000);
      * @example expect(r3f).not.toHaveTotalTriangleCountGreaterThan(100000); // budget guard
      */
-    toHaveTotalTriangleCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, expected: number, options?: MatcherOptions): Promise<{
-        pass: false;
+    toHaveTotalTriangleCount(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, expected: number, options?: MatcherOptions): Promise<{
+        pass: boolean;
         message: () => string;
         name: string;
         expected: number;
@@ -674,36 +988,160 @@ declare const expect: _playwright_test.Expect<{
      *
      * @example expect(r3f).toHaveTotalTriangleCountLessThan(100_000);
      */
-    toHaveTotalTriangleCountLessThan(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, max: number, options?: MatcherOptions): Promise<{
-        pass: false;
+    toHaveTotalTriangleCountLessThan(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, max: number, options?: MatcherOptions): Promise<{
+        pass: boolean;
         message: () => string;
         name: string;
         expected: string;
         actual: number;
     }>;
-}>;
+    /**
+     * Assert the camera position is close to the expected [x, y, z].
+     *
+     * @example expect(r3f).toHaveCameraPosition([0, 5, 10], 0.1);
+     */
+    toHaveCameraPosition(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: [number, number, number];
+        actual: [number, number, number];
+    }>;
+    /**
+     * Assert the camera field of view (PerspectiveCamera only).
+     *
+     * @example expect(r3f).toHaveCameraFov(75);
+     */
+    toHaveCameraFov(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, expected: number, tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number | undefined;
+    }>;
+    /**
+     * Assert the camera near clipping plane.
+     *
+     * @example expect(r3f).toHaveCameraNear(0.1);
+     */
+    toHaveCameraNear(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, expected: number, tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+    /**
+     * Assert the camera far clipping plane.
+     *
+     * @example expect(r3f).toHaveCameraFar(1000);
+     */
+    toHaveCameraFar(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, expected: number, tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+    /**
+     * Assert the camera zoom level.
+     *
+     * @example expect(r3f).toHaveCameraZoom(1);
+     */
+    toHaveCameraZoom(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, expected: number, tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+    /**
+     * Assert that ALL given objects exist in the scene.
+     * Accepts an array of testIds/uuids or a glob pattern (e.g. "wall-*").
+     *
+     * @example expect(r3f).toAllExist(['wall-1', 'wall-2', 'floor']);
+     * @example expect(r3f).toAllExist('wall-*');
+     */
+    toAllExist(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, idsOrPattern: string[] | string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string | string[];
+        actual: {
+            missing: string[];
+        };
+    }>;
+    /**
+     * Assert that ALL given objects are visible.
+     *
+     * @example expect(r3f).toAllBeVisible(['wall-1', 'wall-2', 'floor']);
+     * @example expect(r3f).toAllBeVisible('wall-*');
+     */
+    toAllBeVisible(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, idsOrPattern: string[] | string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string | string[];
+        actual: {
+            hidden: string[];
+        };
+    }>;
+    /**
+     * Assert that NONE of the given objects exist in the scene.
+     *
+     * @example expect(r3f).toNoneExist(['deleted-wall', 'old-floor']);
+     * @example expect(r3f).toNoneExist('temp-*');
+     */
+    toNoneExist(this: ExpectMatcherContext, r3f: R3FMatcherReceiver, idsOrPattern: string[] | string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string | string[];
+        actual: {
+            found: string[];
+        };
+    }>;
+};
+
+/**
+ * @module interactions
+ *
+ * Playwright interaction helpers — thin wrappers around `page.evaluate` calls
+ * to the `window.__R3F_DOM__` bridge interaction methods.
+ *
+ * All object-targeted interactions auto-wait for:
+ *   1. The bridge to be ready (`_ready === true`)
+ *   2. The target object to exist (by testId or uuid)
+ *
+ * This mirrors Playwright's built-in auto-waiting on locators.
+ *
+ * Multi-canvas: pass `canvasId` to target a specific canvas instance.
+ * When undefined, uses the default `window.__R3F_DOM__`.
+ */
 
 /** Click a 3D object by its testId or uuid. Auto-waits for the object. */
-declare function click(page: Page, idOrUuid: string, timeout?: number): Promise<void>;
+declare function click(page: Page, idOrUuid: string, timeout?: number, canvasId?: string): Promise<void>;
 /** Double-click a 3D object by its testId or uuid. Auto-waits for the object. */
-declare function doubleClick(page: Page, idOrUuid: string, timeout?: number): Promise<void>;
+declare function doubleClick(page: Page, idOrUuid: string, timeout?: number, canvasId?: string): Promise<void>;
 /** Right-click / context-menu a 3D object. Auto-waits for the object. */
-declare function contextMenu(page: Page, idOrUuid: string, timeout?: number): Promise<void>;
+declare function contextMenu(page: Page, idOrUuid: string, timeout?: number, canvasId?: string): Promise<void>;
 /** Hover over a 3D object. Auto-waits for the object. */
-declare function hover(page: Page, idOrUuid: string, timeout?: number): Promise<void>;
+declare function hover(page: Page, idOrUuid: string, timeout?: number, canvasId?: string): Promise<void>;
+/** Unhover / pointer-leave — resets hover state by moving pointer off-canvas. Auto-waits for bridge. */
+declare function unhover(page: Page, timeout?: number, canvasId?: string): Promise<void>;
 /** Drag a 3D object with a world-space delta. Auto-waits for the object. */
 declare function drag(page: Page, idOrUuid: string, delta: {
     x: number;
     y: number;
     z: number;
-}, timeout?: number): Promise<void>;
+}, timeout?: number, canvasId?: string): Promise<void>;
 /** Dispatch a wheel/scroll event on a 3D object. Auto-waits for the object. */
 declare function wheel(page: Page, idOrUuid: string, options?: {
     deltaY?: number;
     deltaX?: number;
-}, timeout?: number): Promise<void>;
+}, timeout?: number, canvasId?: string): Promise<void>;
 /** Click empty space to trigger onPointerMissed handlers. Auto-waits for bridge. */
-declare function pointerMiss(page: Page, timeout?: number): Promise<void>;
+declare function pointerMiss(page: Page, timeout?: number, canvasId?: string): Promise<void>;
 /** Draw a freeform path on the canvas. Auto-waits for bridge. */
 declare function drawPathOnCanvas(page: Page, points: Array<{
     x: number;
@@ -713,11 +1151,22 @@ declare function drawPathOnCanvas(page: Page, points: Array<{
     stepDelayMs?: number;
     pointerType?: 'mouse' | 'pen' | 'touch';
     clickAtEnd?: boolean;
-}, timeout?: number): Promise<{
+}, timeout?: number, canvasId?: string): Promise<{
     eventCount: number;
     pointCount: number;
 }>;
+/** Get the current camera state (position, rotation, fov, near, far, zoom). Auto-waits for bridge. */
+declare function getCameraState(page: Page, timeout?: number, canvasId?: string): Promise<CameraState>;
 
+/**
+ * @module pathGenerators
+ *
+ * Pure geometry utilities that generate arrays of screen-space points for
+ * use with `r3f.drawPath()`. Provides line, quadratic bezier, rectangle,
+ * and circle/ellipse path generators.
+ *
+ * Duplicated from `@react-three-dom/core` to avoid a runtime dependency.
+ */
 /** A 2D screen-space point in CSS pixels, relative to the canvas top-left. */
 interface DrawPoint {
     /** X coordinate in CSS pixels from canvas left edge. */
@@ -790,4 +1239,4 @@ declare function circlePath(center: {
     y: number;
 }, radiusX: number, radiusY?: number, steps?: number, pressure?: number): DrawPoint[];
 
-export { type DrawPoint, type ObjectInspection, type ObjectMetadata, R3FFixture, type R3FFixtureOptions, type SceneSnapshot, type SnapshotNode, type WaitForIdleOptions, type WaitForNewObjectOptions, type WaitForNewObjectResult, type WaitForObjectOptions, type WaitForSceneReadyOptions, circlePath, click, contextMenu, createR3FTest, curvePath, doubleClick, drag, drawPathOnCanvas, expect, hover, linePath, pointerMiss, rectPath, test, waitForIdle, waitForNewObject, waitForObject, waitForSceneReady, wheel };
+export { type BridgeDiagnostics, type CameraState, type DrawPoint, type InspectOptions, type ObjectInspection, type ObjectMetadata, R3FFixture, type R3FFixtureOptions, R3FReporter, type SceneDiff, type SceneDiffChange, type SceneSnapshot, type SnapshotNode, type WaitForIdleOptions, type WaitForNewObjectOptions, type WaitForNewObjectResult, type WaitForObjectOptions, type WaitForObjectRemovedOptions, type WaitForSceneReadyOptions, circlePath, click, contextMenu, createR3FTest, curvePath, diffSnapshots, doubleClick, drag, drawPathOnCanvas, getCameraState, hover, linePath, pointerMiss, r3fMatchers, rectPath, test, unhover, waitForIdle, waitForNewObject, waitForObject, waitForObjectRemoved, waitForSceneReady, wheel };