@react-three-dom/playwright 0.1.2 → 0.2.0

package/dist/index.d.cts

@@ -67,6 +67,11 @@ interface SceneSnapshot {
     objectCount: number;
     tree: SnapshotNode;
 }
+declare global {
+    interface Window {
+        __R3F_DOM_DEBUG__?: boolean;
+    }
+}
 
 interface WaitForSceneReadyOptions {
     /** How many consecutive stable polls are required. Default: 3 */
@@ -77,8 +82,11 @@ interface WaitForSceneReadyOptions {
     timeout?: number;
 }
 /**
- * Wait until `window.__R3F_DOM__` is available and the scene's object count
- * has stabilised (no additions or removals) over several consecutive checks.
+ * Wait until `window.__R3F_DOM__` is available, `_ready === true`, and the
+ * scene's object count has stabilised over several consecutive checks.
+ *
+ * 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>;
 interface WaitForObjectOptions {
@@ -90,12 +98,14 @@ interface WaitForObjectOptions {
     pollIntervalMs?: number;
 }
 /**
- * Wait until `window.__R3F_DOM__` is available and an object with the given
+ * Wait until `window.__R3F_DOM__` is ready and an object with the given
  * testId or uuid exists in the scene.
  *
  * Use this instead of `waitForSceneReady` when the scene object count never
  * stabilizes (e.g. continuous loading, animations adding/removing objects,
  * or GLTF/models loading asynchronously).
+ *
+ * Fails fast if the bridge reports `_ready: false` with an `_error`.
  */
 declare function waitForObject(page: Page, idOrUuid: string, options?: WaitForObjectOptions): Promise<void>;
 interface WaitForIdleOptions {
@@ -111,14 +121,82 @@ interface WaitForIdleOptions {
  * This works by taking successive snapshots and comparing them. When the
  * JSON representation is unchanged for `idleFrames` consecutive rAF
  * callbacks, the scene is considered idle.
+ *
+ * Checks `_ready === true` before starting. Fails fast if `_error` is set.
  */
 declare function waitForIdle(page: Page, options?: WaitForIdleOptions): Promise<void>;
+interface WaitForNewObjectOptions {
+    /**
+     * Only consider new objects of this Three.js type (e.g. "Mesh", "Line").
+     * If not set, any new object type qualifies.
+     */
+    type?: string;
+    /**
+     * If provided, the new object's name must contain this substring.
+     * Useful for apps that name objects predictably (e.g. "stroke-", "wall-").
+     */
+    nameContains?: string;
+    /**
+     * Poll interval in ms. Default: 100
+     */
+    pollIntervalMs?: number;
+    /**
+     * Overall timeout in ms. Default: 10_000
+     */
+    timeout?: number;
+}
+/** Result returned when new objects are detected. */
+interface WaitForNewObjectResult {
+    /** Metadata of all newly added objects (matching the filter). */
+    newObjects: ObjectMetadata[];
+    /** UUIDs of the newly added objects. */
+    newUuids: string[];
+    /** Total number of new objects detected. */
+    count: number;
+}
+/**
+ * Wait until one or more new objects appear in the scene that were not present
+ * at the time this function was called.
+ *
+ * This is designed for drawing/annotation apps where user interactions
+ * (like `drawPath`) create new Three.js objects asynchronously.
+ *
+ * @param page      Playwright Page instance
+ * @param options   Filter and timing options
+ * @returns         Metadata of the newly added object(s)
+ * @throws          If no new objects appear within the timeout
+ *
+ * @example
+ * ```typescript
+ * // Draw a stroke, then wait for the new Line object
+ * const before = await r3f.getCount();
+ * await r3f.drawPath(points);
+ * const result = await waitForNewObject(page, { type: 'Line' });
+ * expect(result.count).toBe(1);
+ * ```
+ */
+declare function waitForNewObject(page: Page, options?: WaitForNewObjectOptions): Promise<WaitForNewObjectResult>;
 
+/** Options for R3FFixture constructor. */
+interface R3FFixtureOptions {
+    /** Auto-enable debug logging (forwards browser [r3f-dom:*] logs to test terminal). */
+    debug?: boolean;
+}
 declare class R3FFixture {
     private readonly _page;
-    constructor(_page: Page);
+    private _debugListenerAttached;
+    constructor(_page: Page, opts?: R3FFixtureOptions);
     /** The underlying Playwright Page. */
     get page(): Page;
+    /**
+     * 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.
+     *
+     * Call before `page.goto()` to capture setup logs, or after to capture
+     * interaction logs.
+     */
+    enableDebug(): Promise<void>;
+    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. */
@@ -127,27 +205,117 @@ declare class R3FFixture {
     snapshot(): Promise<SceneSnapshot | null>;
     /** Get the total number of tracked objects. */
     getCount(): Promise<number>;
-    /** Click a 3D object by testId or uuid. */
-    click(idOrUuid: string): Promise<void>;
-    /** Double-click a 3D object by testId or uuid. */
-    doubleClick(idOrUuid: string): Promise<void>;
-    /** Right-click / context-menu a 3D object by testId or uuid. */
-    contextMenu(idOrUuid: string): Promise<void>;
-    /** Hover over a 3D object by testId or uuid. */
-    hover(idOrUuid: string): Promise<void>;
-    /** Drag a 3D object with a world-space delta vector. */
+    /**
+     * 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 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');
+     * ```
+     */
+    getObjects(ids: string[]): Promise<Record<string, ObjectMetadata | null>>;
+    /**
+     * Log the scene tree to the test terminal for debugging.
+     *
+     * Prints a human-readable tree like:
+     * ```
+     * Scene "root"
+     * ├─ Mesh "chair-primary" [testId: chair-primary] visible
+     * │  └─ BoxGeometry
+     * ├─ DirectionalLight "sun-light" [testId: sun-light] visible
+     * └─ Group "furniture"
+     *    ├─ Mesh "table-top" [testId: table-top] visible
+     *    └─ Mesh "vase" [testId: vase] visible
+     * ```
+     */
+    logScene(): Promise<void>;
+    /**
+     * Click a 3D object by testId or uuid.
+     * Auto-waits for the bridge and the object to exist before clicking.
+     * @param timeout  Optional auto-wait timeout in ms. Default: 5000
+     */
+    click(idOrUuid: string, timeout?: number): Promise<void>;
+    /**
+     * Double-click a 3D object by testId or uuid.
+     * Auto-waits for the object to exist.
+     */
+    doubleClick(idOrUuid: string, timeout?: number): Promise<void>;
+    /**
+     * Right-click / context-menu a 3D object by testId or uuid.
+     * Auto-waits for the object to exist.
+     */
+    contextMenu(idOrUuid: string, timeout?: number): Promise<void>;
+    /**
+     * Hover over a 3D object by testId or uuid.
+     * Auto-waits for the object to exist.
+     */
+    hover(idOrUuid: string, timeout?: number): Promise<void>;
+    /**
+     * Drag a 3D object with a world-space delta vector.
+     * Auto-waits for the object to exist.
+     */
     drag(idOrUuid: string, delta: {
         x: number;
         y: number;
         z: number;
-    }): Promise<void>;
-    /** Dispatch a wheel/scroll event on a 3D object. */
+    }, timeout?: number): Promise<void>;
+    /**
+     * Dispatch a wheel/scroll event on a 3D object.
+     * Auto-waits for the object to exist.
+     */
     wheel(idOrUuid: string, options?: {
         deltaY?: number;
         deltaX?: number;
-    }): Promise<void>;
-    /** Click empty space to trigger onPointerMissed handlers. */
-    pointerMiss(): Promise<void>;
+    }, timeout?: number): Promise<void>;
+    /**
+     * Click empty space to trigger onPointerMissed handlers.
+     * Auto-waits for the bridge to be ready.
+     */
+    pointerMiss(timeout?: number): Promise<void>;
+    /**
+     * Draw a freeform path on the canvas. Dispatches pointerdown → N × pointermove → pointerup.
+     * Designed for canvas drawing/annotation/whiteboard apps.
+     * Auto-waits for the bridge to be ready.
+     *
+     * @param points  Array of screen-space points (min 2). { x, y } in CSS pixels relative to canvas.
+     * @param options Drawing options (stepDelayMs, pointerType, clickAtEnd)
+     * @param timeout Optional auto-wait timeout in ms. Default: 5000
+     * @returns       { eventCount, pointCount }
+     */
+    drawPath(points: Array<{
+        x: number;
+        y: number;
+        pressure?: number;
+    }>, options?: {
+        stepDelayMs?: number;
+        pointerType?: 'mouse' | 'pen' | 'touch';
+        clickAtEnd?: boolean;
+    }, timeout?: number): Promise<{
+        eventCount: number;
+        pointCount: number;
+    }>;
     /**
      * Wait until the scene is ready — `window.__R3F_DOM__` is available and
      * the object count has stabilised across several consecutive checks.
@@ -164,6 +332,15 @@ declare class R3FFixture {
      * animation frames. Useful after triggering interactions or animations.
      */
     waitForIdle(options?: WaitForIdleOptions): Promise<void>;
+    /**
+     * Wait until one or more new objects appear in the scene that were not
+     * present when this call was made. Perfect for drawing apps where
+     * `drawPath()` creates new geometry asynchronously.
+     *
+     * @param options  Filter by type, nameContains, timeout, pollInterval
+     * @returns        Metadata of the newly added object(s)
+     */
+    waitForNewObject(options?: WaitForNewObjectOptions): Promise<WaitForNewObjectResult>;
     /** Select a 3D object by testId or uuid (highlights in scene). */
     select(idOrUuid: string): Promise<void>;
     /** Clear the current selection. */
@@ -172,34 +349,42 @@ declare class R3FFixture {
 declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
     r3f: R3FFixture;
 }, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
-
 /**
- * Extend Playwright's `expect` with 3D-native matchers.
+ * Create a custom test.extend with debug enabled for all tests:
  *
- * Usage:
- * ```ts
- * import { test, expect } from '@react-three-dom/playwright';
- *
- * test('chair exists', async ({ page, r3f }) => {
- *   await r3f.waitForSceneReady();
- *   await expect(r3f).toExist('chair-primary');
- * });
+ * ```typescript
+ * import { createR3FTest } from '@react-three-dom/playwright';
+ * export const test = createR3FTest({ debug: true });
  * ```
  */
+declare function createR3FTest(options?: R3FFixtureOptions): _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
+    r3f: R3FFixture;
+}, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
+
+interface R3FMatcherReceiver {
+    page: Page;
+    getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
+    inspect(idOrUuid: string): Promise<ObjectInspection | null>;
+}
+interface MatcherOptions {
+    timeout?: number;
+    interval?: number;
+}
+type Vec3Opts = MatcherOptions & {
+    tolerance?: number;
+};
 declare const expect: _playwright_test.Expect<{
-    toExist(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+    toExist(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
         expected: string;
-        actual: ObjectMetadata | null;
+        actual: null;
     }>;
-    toBeVisible(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
-        pass: false;
+    toBeVisible(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
         message: () => string;
         name: string;
-        expected?: undefined;
-        actual?: undefined;
     } | {
         pass: boolean;
         message: () => string;
@@ -207,48 +392,141 @@ declare const expect: _playwright_test.Expect<{
         expected: boolean;
         actual: boolean;
     }>;
-    toBeInFrustum(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+    toHavePosition(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expected: [number, number, number], tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        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<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
         pass: false;
         message: () => string;
         name: string;
-        expected?: undefined;
-        actual?: undefined;
+        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<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        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<{
+        pass: boolean;
+        message: () => string;
+        name: string;
     } | {
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: string;
+    }>;
+    toHaveName(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedName: string, opts?: MatcherOptions): Promise<{
         pass: boolean;
         message: () => string;
         name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
         expected: string;
-        actual: {
-            min: [number, number, number];
-            max: [number, number, number];
-        };
+        actual: string;
+    }>;
+    toHaveGeometryType(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedGeo: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: string | undefined;
     }>;
-    toHavePosition(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expected: [number, number, number], tolerance?: any): Promise<{
+    toHaveMaterialType(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedMat: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
         pass: false;
         message: () => string;
         name: string;
-        expected?: undefined;
-        actual?: undefined;
+        expected: string;
+        actual: string | undefined;
+    }>;
+    toHaveChildCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
     } | {
         pass: boolean;
         message: () => string;
         name: string;
-        expected: [number, number, number];
-        actual: [number, number, number];
+        expected: number;
+        actual: number;
     }>;
-    toHaveBounds(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expected: {
-        min: [number, number, number];
-        max: [number, number, number];
-    }, tolerance?: any): Promise<{
+    toHaveParent(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedParent: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
         pass: false;
         message: () => string;
         name: string;
-        expected?: undefined;
-        actual?: undefined;
+        expected: string;
+        actual: string | null;
+    }>;
+    toHaveInstanceCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
     } | {
         pass: boolean;
         message: () => string;
         name: string;
+        expected: number;
+        actual: number;
+    }>;
+    toBeInFrustum(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: {
+            min: [number, number, number];
+            max: [number, number, number];
+        };
+    }>;
+    toHaveBounds(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expected: {
+        min: [number, number, number];
+        max: [number, number, number];
+    }, tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
         expected: {
             min: [number, number, number];
             max: [number, number, number];
@@ -258,12 +536,43 @@ declare const expect: _playwright_test.Expect<{
             max: [number, number, number];
         };
     }>;
-    toHaveInstanceCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expectedCount: number): Promise<{
+    toHaveColor(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedColor: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: string | undefined;
+    }>;
+    toHaveOpacity(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedOpacity: number, tolOpts?: number | Vec3Opts): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number | undefined;
+    }>;
+    toBeTransparent(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
         pass: false;
         message: () => string;
         name: string;
-        expected?: undefined;
-        actual?: undefined;
+        expected: boolean;
+        actual: boolean | undefined;
+    }>;
+    toHaveVertexCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
     } | {
         pass: boolean;
         message: () => string;
@@ -271,32 +580,214 @@ declare const expect: _playwright_test.Expect<{
         expected: number;
         actual: number;
     }>;
+    toHaveTriangleCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedCount: number, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+    toHaveUserData(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, key: string, expectedValue?: unknown, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: {};
+        actual: unknown;
+    }>;
+    toHaveMapTexture(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, id: string, expectedName?: string, opts?: MatcherOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+    } | {
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: string | undefined;
+    }>;
+    /**
+     * Assert the total number of objects in the scene.
+     * Auto-retries until the count matches or timeout.
+     *
+     * @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;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+    /**
+     * Assert the total number of objects is at least `min`.
+     * Useful for BIM scenes where the exact count may vary slightly.
+     *
+     * @example expect(r3f).toHaveObjectCountGreaterThan(10);
+     */
+    toHaveObjectCountGreaterThan(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, min: number, options?: MatcherOptions): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: number;
+    }>;
+    /**
+     * Assert the count of objects of a specific Three.js type.
+     * Auto-retries until the count matches or timeout.
+     *
+     * @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;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+    /**
+     * Assert the total triangle count across all meshes in the scene.
+     * Use as a performance budget guard — fail if the scene exceeds a threshold.
+     *
+     * @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;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+    /**
+     * Assert the total triangle count is at most `max`.
+     * Perfect as a performance budget guard to prevent scene bloat.
+     *
+     * @example expect(r3f).toHaveTotalTriangleCountLessThan(100_000);
+     */
+    toHaveTotalTriangleCountLessThan(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, max: number, options?: MatcherOptions): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: number;
+    }>;
 }>;
-interface R3FMatcherReceiver {
-    getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
-    inspect(idOrUuid: string): Promise<ObjectInspection | null>;
-}
 
-/** Click a 3D object by its testId or uuid. */
-declare function click(page: Page, idOrUuid: string): Promise<void>;
-/** Double-click a 3D object by its testId or uuid. */
-declare function doubleClick(page: Page, idOrUuid: string): Promise<void>;
-/** Right-click / context-menu a 3D object by its testId or uuid. */
-declare function contextMenu(page: Page, idOrUuid: string): Promise<void>;
-/** Hover over a 3D object by its testId or uuid. */
-declare function hover(page: Page, idOrUuid: string): Promise<void>;
-/** Drag a 3D object by its testId or uuid with a given world-space delta. */
+/** 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>;
+/** 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>;
+/** Right-click / context-menu a 3D object. Auto-waits for the object. */
+declare function contextMenu(page: Page, idOrUuid: string, timeout?: number): Promise<void>;
+/** Hover over a 3D object. Auto-waits for the object. */
+declare function hover(page: Page, idOrUuid: string, timeout?: number): 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;
-}): Promise<void>;
-/** Dispatch a wheel/scroll event on a 3D object. */
+}, timeout?: number): 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;
-}): Promise<void>;
-/** Click empty space to trigger onPointerMissed handlers. */
-declare function pointerMiss(page: Page): Promise<void>;
+}, timeout?: number): Promise<void>;
+/** Click empty space to trigger onPointerMissed handlers. Auto-waits for bridge. */
+declare function pointerMiss(page: Page, timeout?: number): Promise<void>;
+/** Draw a freeform path on the canvas. Auto-waits for bridge. */
+declare function drawPathOnCanvas(page: Page, points: Array<{
+    x: number;
+    y: number;
+    pressure?: number;
+}>, options?: {
+    stepDelayMs?: number;
+    pointerType?: 'mouse' | 'pen' | 'touch';
+    clickAtEnd?: boolean;
+}, timeout?: number): Promise<{
+    eventCount: number;
+    pointCount: number;
+}>;
+
+/** 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. */
+    x: number;
+    /** Y coordinate in CSS pixels from canvas top edge. */
+    y: number;
+    /** Optional pressure (0–1). Default: 0.5 */
+    pressure?: number;
+}
+/**
+ * Generate points along a straight line.
+ *
+ * @param start     Start point
+ * @param end       End point
+ * @param steps     Intermediate points (excluding start/end). Default: 10
+ * @param pressure  Uniform pressure. Default: 0.5
+ */
+declare function linePath(start: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, steps?: number, pressure?: number): DrawPoint[];
+/**
+ * Generate points along a quadratic bezier curve.
+ *
+ * @param start     Start point
+ * @param control   Control point
+ * @param end       End point
+ * @param steps     Number of steps. Default: 20
+ * @param pressure  Uniform pressure. Default: 0.5
+ */
+declare function curvePath(start: {
+    x: number;
+    y: number;
+}, control: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, steps?: number, pressure?: number): DrawPoint[];
+/**
+ * Generate points forming a rectangle.
+ *
+ * @param topLeft      Top-left corner
+ * @param bottomRight  Bottom-right corner
+ * @param pointsPerSide  Points per side. Default: 5
+ * @param pressure     Uniform pressure. Default: 0.5
+ */
+declare function rectPath(topLeft: {
+    x: number;
+    y: number;
+}, bottomRight: {
+    x: number;
+    y: number;
+}, pointsPerSide?: number, pressure?: number): DrawPoint[];
+/**
+ * Generate points forming a circle/ellipse.
+ *
+ * @param center   Center point
+ * @param radiusX  Horizontal radius in CSS pixels
+ * @param radiusY  Vertical radius. Default: same as radiusX
+ * @param steps    Number of points. Default: 36
+ * @param pressure Uniform pressure. Default: 0.5
+ */
+declare function circlePath(center: {
+    x: number;
+    y: number;
+}, radiusX: number, radiusY?: number, steps?: number, pressure?: number): DrawPoint[];
 
-export { type ObjectInspection, type ObjectMetadata, R3FFixture, type SceneSnapshot, type SnapshotNode, type WaitForIdleOptions, type WaitForObjectOptions, type WaitForSceneReadyOptions, click, contextMenu, doubleClick, drag, expect, hover, pointerMiss, test, waitForIdle, waitForObject, waitForSceneReady, wheel };
+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 };