@react-three-dom/playwright 0.1.2 → 0.2.0

package/dist/index.cjs

@@ -5,6 +5,48 @@ var test$1 = require('@playwright/test');
 // src/fixtures.ts
 
 // src/waiters.ts
+async function waitForReadyBridge(page, timeout) {
+  const deadline = Date.now() + timeout;
+  const pollMs = 100;
+  while (Date.now() < deadline) {
+    const state = await page.evaluate(() => {
+      const api = window.__R3F_DOM__;
+      if (!api) return { exists: false };
+      return {
+        exists: true,
+        ready: api._ready,
+        error: api._error ?? null,
+        count: api.getCount()
+      };
+    });
+    if (state.exists && state.ready) {
+      return;
+    }
+    if (state.exists && !state.ready && state.error) {
+      throw new Error(
+        `[react-three-dom] Bridge initialization failed: ${state.error}
+The <ThreeDom> component mounted but threw during setup. Check the browser console for the full stack trace.`
+      );
+    }
+    await page.waitForTimeout(pollMs);
+  }
+  const finalState = await page.evaluate(() => {
+    const api = window.__R3F_DOM__;
+    if (!api) return { exists: false, ready: false, error: null };
+    return { exists: true, ready: api._ready, error: api._error ?? null };
+  });
+  if (finalState.exists && finalState.error) {
+    throw new Error(
+      `[react-three-dom] Bridge initialization failed: ${finalState.error}
+The <ThreeDom> component mounted but threw during setup.`
+    );
+  }
+  throw new Error(
+    `[react-three-dom] Timed out after ${timeout}ms waiting for the bridge to be ready.
+Bridge exists: ${finalState.exists}, ready: ${finalState.ready}.
+Ensure <ThreeDom> is mounted inside your <Canvas> component.`
+  );
+}
 async function waitForSceneReady(page, options = {}) {
   const {
     stableChecks = 3,
@@ -12,9 +54,7 @@ async function waitForSceneReady(page, options = {}) {
     timeout = 1e4
   } = options;
   const deadline = Date.now() + timeout;
-  await page.waitForFunction(() => typeof window.__R3F_DOM__ !== "undefined", void 0, {
-    timeout
-  });
+  await waitForReadyBridge(page, timeout);
   let lastCount = -1;
   let stableRuns = 0;
   while (Date.now() < deadline) {
@@ -38,15 +78,13 @@ async function waitForObject(page, idOrUuid, options = {}) {
     objectTimeout = 4e4,
     pollIntervalMs = 200
   } = options;
-  await page.waitForFunction(() => typeof window.__R3F_DOM__ !== "undefined", void 0, {
-    timeout: bridgeTimeout
-  });
+  await waitForReadyBridge(page, bridgeTimeout);
   const deadline = Date.now() + objectTimeout;
   while (Date.now() < deadline) {
     const found = await page.evaluate(
       (id) => {
         const api = window.__R3F_DOM__;
-        if (!api) return false;
+        if (!api || !api._ready) return false;
         return (api.getByTestId(id) ?? api.getByUuid(id)) !== null;
       },
       idOrUuid
@@ -54,8 +92,18 @@ async function waitForObject(page, idOrUuid, options = {}) {
     if (found) return;
     await page.waitForTimeout(pollIntervalMs);
   }
+  const diagnostics = await page.evaluate(() => {
+    const api = window.__R3F_DOM__;
+    if (!api) return { bridgeExists: false, ready: false, count: 0, error: null };
+    return {
+      bridgeExists: true,
+      ready: api._ready,
+      count: api.getCount(),
+      error: api._error ?? null
+    };
+  });
   throw new Error(
-    `waitForObject("${idOrUuid}") timed out after ${objectTimeout}ms. Is the object rendered with userData.testId or this uuid?`
+    `waitForObject("${idOrUuid}") timed out after ${objectTimeout}ms. Bridge: ${diagnostics.bridgeExists ? "exists" : "missing"}, ready: ${diagnostics.ready}, objectCount: ${diagnostics.count}` + (diagnostics.error ? `, error: ${diagnostics.error}` : "") + `. Is the object rendered with userData.testId="${idOrUuid}" or uuid="${idOrUuid}"?`
   );
 }
 async function waitForIdle(page, options = {}) {
@@ -63,6 +111,7 @@ async function waitForIdle(page, options = {}) {
     idleFrames = 10,
     timeout = 1e4
   } = options;
+  await waitForReadyBridge(page, timeout);
   const settled = await page.evaluate(
     ([frames, timeoutMs]) => {
       return new Promise((resolve) => {
@@ -74,8 +123,17 @@ async function waitForIdle(page, options = {}) {
             resolve(false);
             return;
           }
-          const snap = window.__R3F_DOM__?.snapshot();
-          const json = snap ? JSON.stringify(snap.tree) : "";
+          const api = window.__R3F_DOM__;
+          if (!api || !api._ready) {
+            if (api && api._error) {
+              resolve(`Bridge error: ${api._error}`);
+              return;
+            }
+            requestAnimationFrame(check);
+            return;
+          }
+          const snap = api.snapshot();
+          const json = JSON.stringify(snap.tree);
           if (json === lastJson && json !== "") {
             stableCount++;
             if (stableCount >= frames) {
@@ -93,76 +151,269 @@ async function waitForIdle(page, options = {}) {
     },
     [idleFrames, timeout]
   );
+  if (typeof settled === "string") {
+    throw new Error(`waitForIdle failed: ${settled}`);
+  }
   if (!settled) {
     throw new Error(`waitForIdle timed out after ${timeout}ms`);
   }
 }
-async function click(page, idOrUuid) {
-  await page.evaluate((id) => {
+async function waitForNewObject(page, options = {}) {
+  const {
+    type,
+    nameContains,
+    pollIntervalMs = 100,
+    timeout = 1e4
+  } = options;
+  const baselineUuids = await page.evaluate(() => {
     const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
-    api.click(id);
+    if (!api) return [];
+    const snap = api.snapshot();
+    const uuids = [];
+    function collect(node) {
+      uuids.push(node.uuid);
+      for (const child of node.children) {
+        collect(child);
+      }
+    }
+    collect(snap.tree);
+    return uuids;
+  });
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    await page.waitForTimeout(pollIntervalMs);
+    const result = await page.evaluate(
+      ([filterType, filterName, knownUuids]) => {
+        const api = window.__R3F_DOM__;
+        if (!api) return null;
+        const snap = api.snapshot();
+        const known = new Set(knownUuids);
+        const newObjects = [];
+        function scan(node) {
+          if (!known.has(node.uuid)) {
+            const typeMatch = !filterType || node.type === filterType;
+            const nameMatch = !filterName || node.name.includes(filterName);
+            if (typeMatch && nameMatch) {
+              newObjects.push({
+                uuid: node.uuid,
+                name: node.name,
+                type: node.type,
+                visible: node.visible,
+                testId: node.testId,
+                position: node.position,
+                rotation: node.rotation,
+                scale: node.scale
+              });
+            }
+          }
+          for (const child of node.children) {
+            scan(child);
+          }
+        }
+        scan(snap.tree);
+        if (newObjects.length === 0) return null;
+        return {
+          newObjects,
+          newUuids: newObjects.map((o) => o.uuid),
+          count: newObjects.length
+        };
+      },
+      [type ?? null, nameContains ?? null, baselineUuids]
+    );
+    if (result) {
+      return result;
+    }
+  }
+  const filterDesc = [
+    type ? `type="${type}"` : null,
+    nameContains ? `nameContains="${nameContains}"` : null
+  ].filter(Boolean).join(", ");
+  throw new Error(
+    `waitForNewObject timed out after ${timeout}ms. No new objects appeared${filterDesc ? ` matching ${filterDesc}` : ""}. Baseline had ${baselineUuids.length} objects.`
+  );
+}
+
+// src/interactions.ts
+var DEFAULT_AUTO_WAIT_TIMEOUT = 5e3;
+var AUTO_WAIT_POLL_MS = 100;
+async function autoWaitForObject(page, idOrUuid, timeout = DEFAULT_AUTO_WAIT_TIMEOUT) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const state = await page.evaluate(
+      (id) => {
+        const api = window.__R3F_DOM__;
+        if (!api) return { bridge: "missing" };
+        if (!api._ready) {
+          return {
+            bridge: "not-ready",
+            error: api._error ?? null
+          };
+        }
+        const found = (api.getByTestId(id) ?? api.getByUuid(id)) !== null;
+        return { bridge: "ready", found };
+      },
+      idOrUuid
+    );
+    if (state.bridge === "ready" && state.found) {
+      return;
+    }
+    if (state.bridge === "not-ready" && state.error) {
+      throw new Error(
+        `[react-three-dom] Bridge initialization failed: ${state.error}
+Cannot perform interaction on "${idOrUuid}".`
+      );
+    }
+    await page.waitForTimeout(AUTO_WAIT_POLL_MS);
+  }
+  const finalState = await page.evaluate(
+    (id) => {
+      const api = window.__R3F_DOM__;
+      if (!api) return { bridge: false, ready: false, count: 0, error: null, found: false };
+      return {
+        bridge: true,
+        ready: api._ready,
+        count: api.getCount(),
+        error: api._error ?? null,
+        found: (api.getByTestId(id) ?? api.getByUuid(id)) !== null
+      };
+    },
+    idOrUuid
+  );
+  if (!finalState.bridge) {
+    throw new Error(
+      `[react-three-dom] Auto-wait timed out after ${timeout}ms: bridge not found.
+Ensure <ThreeDom> is mounted inside your <Canvas> component.`
+    );
+  }
+  throw new Error(
+    `[react-three-dom] Auto-wait timed out after ${timeout}ms: object "${idOrUuid}" not found.
+Bridge: ready=${finalState.ready}, objectCount=${finalState.count}` + (finalState.error ? `, error=${finalState.error}` : "") + `.
+Ensure the object has userData.testId="${idOrUuid}" or uuid="${idOrUuid}".`
+  );
+}
+async function autoWaitForBridge(page, timeout = DEFAULT_AUTO_WAIT_TIMEOUT) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const state = await page.evaluate(() => {
+      const api = window.__R3F_DOM__;
+      if (!api) return { exists: false };
+      return {
+        exists: true,
+        ready: api._ready,
+        error: api._error ?? null
+      };
+    });
+    if (state.exists && state.ready) return;
+    if (state.exists && !state.ready && state.error) {
+      throw new Error(
+        `[react-three-dom] Bridge initialization failed: ${state.error}`
+      );
+    }
+    await page.waitForTimeout(AUTO_WAIT_POLL_MS);
+  }
+  throw new Error(
+    `[react-three-dom] Auto-wait timed out after ${timeout}ms: bridge not ready.
+Ensure <ThreeDom> is mounted inside your <Canvas> component.`
+  );
+}
+async function click(page, idOrUuid, timeout) {
+  await autoWaitForObject(page, idOrUuid, timeout);
+  await page.evaluate((id) => {
+    window.__R3F_DOM__.click(id);
   }, idOrUuid);
 }
-async function doubleClick(page, idOrUuid) {
+async function doubleClick(page, idOrUuid, timeout) {
+  await autoWaitForObject(page, idOrUuid, timeout);
   await page.evaluate((id) => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
-    api.doubleClick(id);
+    window.__R3F_DOM__.doubleClick(id);
   }, idOrUuid);
 }
-async function contextMenu(page, idOrUuid) {
+async function contextMenu(page, idOrUuid, timeout) {
+  await autoWaitForObject(page, idOrUuid, timeout);
   await page.evaluate((id) => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
-    api.contextMenu(id);
+    window.__R3F_DOM__.contextMenu(id);
   }, idOrUuid);
 }
-async function hover(page, idOrUuid) {
+async function hover(page, idOrUuid, timeout) {
+  await autoWaitForObject(page, idOrUuid, timeout);
   await page.evaluate((id) => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
-    api.hover(id);
+    window.__R3F_DOM__.hover(id);
   }, idOrUuid);
 }
-async function drag(page, idOrUuid, delta) {
+async function drag(page, idOrUuid, delta, timeout) {
+  await autoWaitForObject(page, idOrUuid, timeout);
   await page.evaluate(
-    ([id, d]) => {
-      const api = window.__R3F_DOM__;
-      if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
-      api.drag(id, d);
+    async ([id, d]) => {
+      await window.__R3F_DOM__.drag(id, d);
     },
     [idOrUuid, delta]
   );
 }
-async function wheel(page, idOrUuid, options) {
+async function wheel(page, idOrUuid, options, timeout) {
+  await autoWaitForObject(page, idOrUuid, timeout);
   await page.evaluate(
     ([id, opts]) => {
-      const api = window.__R3F_DOM__;
-      if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
-      api.wheel(id, opts);
+      window.__R3F_DOM__.wheel(id, opts);
     },
     [idOrUuid, options]
   );
 }
-async function pointerMiss(page) {
+async function pointerMiss(page, timeout) {
+  await autoWaitForBridge(page, timeout);
   await page.evaluate(() => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
-    api.pointerMiss();
+    window.__R3F_DOM__.pointerMiss();
   });
 }
+async function drawPathOnCanvas(page, points, options, timeout) {
+  await autoWaitForBridge(page, timeout);
+  return page.evaluate(
+    async ([pts, opts]) => {
+      return window.__R3F_DOM__.drawPath(pts, opts ?? void 0);
+    },
+    [points, options ?? null]
+  );
+}
 
 // src/fixtures.ts
 var R3FFixture = class {
-  constructor(_page) {
+  constructor(_page, opts) {
     this._page = _page;
+    this._debugListenerAttached = false;
+    if (opts?.debug) {
+      this._attachDebugListener();
+    }
   }
   /** The underlying Playwright Page. */
   get page() {
     return this._page;
   }
   // -----------------------------------------------------------------------
+  // Debug logging
+  // -----------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async enableDebug() {
+    this._attachDebugListener();
+    await this._page.evaluate(() => {
+      window.__R3F_DOM_DEBUG__ = true;
+    });
+  }
+  _attachDebugListener() {
+    if (this._debugListenerAttached) return;
+    this._debugListenerAttached = true;
+    this._page.on("console", (msg) => {
+      const text = msg.text();
+      if (text.startsWith("[r3f-dom:")) {
+        console.log(text);
+      }
+    });
+  }
+  // -----------------------------------------------------------------------
   // Queries
   // -----------------------------------------------------------------------
   /** Get object metadata by testId or uuid. Returns null if not found. */
@@ -195,36 +446,153 @@ var R3FFixture = class {
       return api ? api.getCount() : 0;
     });
   }
+  /**
+   * 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.
+   */
+  async getByType(type) {
+    return this._page.evaluate((t) => {
+      const api = window.__R3F_DOM__;
+      return api ? api.getByType(t) : [];
+    }, type);
+  }
+  /**
+   * 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`.
+   */
+  async getByUserData(key, value) {
+    return this._page.evaluate(({ k, v }) => {
+      const api = window.__R3F_DOM__;
+      return api ? api.getByUserData(k, v) : [];
+    }, { k: key, v: value });
+  }
+  /**
+   * Count objects of a given Three.js type.
+   * More efficient than `getByType(type).then(arr => arr.length)`.
+   */
+  async getCountByType(type) {
+    return this._page.evaluate((t) => {
+      const api = window.__R3F_DOM__;
+      return api ? api.getCountByType(t) : 0;
+    }, type);
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async getObjects(ids) {
+    return this._page.evaluate((idList) => {
+      const api = window.__R3F_DOM__;
+      if (!api) {
+        const result = {};
+        for (const id of idList) result[id] = null;
+        return result;
+      }
+      return api.getObjects(idList);
+    }, ids);
+  }
+  /**
+   * 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
+   * ```
+   */
+  async logScene() {
+    const snap = await this.snapshot();
+    if (!snap) {
+      console.log("[r3f-dom] logScene: no scene snapshot available (bridge not ready?)");
+      return;
+    }
+    const lines = formatSceneTree(snap.tree);
+    console.log(`
+[r3f-dom] Scene tree (${snap.objectCount} objects):
+${lines}
+`);
+  }
   // -----------------------------------------------------------------------
   // Interactions
   // -----------------------------------------------------------------------
-  /** Click a 3D object by testId or uuid. */
-  async click(idOrUuid) {
-    return click(this._page, idOrUuid);
+  /**
+   * 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
+   */
+  async click(idOrUuid, timeout) {
+    return click(this._page, idOrUuid, timeout);
   }
-  /** Double-click a 3D object by testId or uuid. */
-  async doubleClick(idOrUuid) {
-    return doubleClick(this._page, idOrUuid);
+  /**
+   * Double-click a 3D object by testId or uuid.
+   * Auto-waits for the object to exist.
+   */
+  async doubleClick(idOrUuid, timeout) {
+    return doubleClick(this._page, idOrUuid, timeout);
   }
-  /** Right-click / context-menu a 3D object by testId or uuid. */
-  async contextMenu(idOrUuid) {
-    return contextMenu(this._page, idOrUuid);
+  /**
+   * Right-click / context-menu a 3D object by testId or uuid.
+   * Auto-waits for the object to exist.
+   */
+  async contextMenu(idOrUuid, timeout) {
+    return contextMenu(this._page, idOrUuid, timeout);
   }
-  /** Hover over a 3D object by testId or uuid. */
-  async hover(idOrUuid) {
-    return hover(this._page, idOrUuid);
+  /**
+   * Hover over a 3D object by testId or uuid.
+   * Auto-waits for the object to exist.
+   */
+  async hover(idOrUuid, timeout) {
+    return hover(this._page, idOrUuid, timeout);
   }
-  /** Drag a 3D object with a world-space delta vector. */
-  async drag(idOrUuid, delta) {
-    return drag(this._page, idOrUuid, delta);
+  /**
+   * Drag a 3D object with a world-space delta vector.
+   * Auto-waits for the object to exist.
+   */
+  async drag(idOrUuid, delta, timeout) {
+    return drag(this._page, idOrUuid, delta, timeout);
   }
-  /** Dispatch a wheel/scroll event on a 3D object. */
-  async wheel(idOrUuid, options) {
-    return wheel(this._page, idOrUuid, options);
+  /**
+   * Dispatch a wheel/scroll event on a 3D object.
+   * Auto-waits for the object to exist.
+   */
+  async wheel(idOrUuid, options, timeout) {
+    return wheel(this._page, idOrUuid, options, timeout);
   }
-  /** Click empty space to trigger onPointerMissed handlers. */
-  async pointerMiss() {
-    return pointerMiss(this._page);
+  /**
+   * Click empty space to trigger onPointerMissed handlers.
+   * Auto-waits for the bridge to be ready.
+   */
+  async pointerMiss(timeout) {
+    return pointerMiss(this._page, timeout);
+  }
+  /**
+   * 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 }
+   */
+  async drawPath(points, options, timeout) {
+    return drawPathOnCanvas(this._page, points, options, timeout);
   }
   // -----------------------------------------------------------------------
   // Waiters
@@ -251,6 +619,17 @@ var R3FFixture = class {
   async waitForIdle(options) {
     return waitForIdle(this._page, options);
   }
+  /**
+   * 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)
+   */
+  async waitForNewObject(options) {
+    return waitForNewObject(this._page, options);
+  }
   // -----------------------------------------------------------------------
   // Selection (for inspector integration)
   // -----------------------------------------------------------------------
@@ -270,155 +649,896 @@ var R3FFixture = class {
     });
   }
 };
+function formatSceneTree(node, prefix = "", isLast = true) {
+  const connector = prefix === "" ? "" : isLast ? "\u2514\u2500 " : "\u251C\u2500 ";
+  const childPrefix = prefix === "" ? "" : prefix + (isLast ? "   " : "\u2502  ");
+  let label = node.type;
+  if (node.name) label += ` "${node.name}"`;
+  if (node.testId) label += ` [testId: ${node.testId}]`;
+  label += node.visible ? " visible" : " HIDDEN";
+  let result = prefix + connector + label + "\n";
+  for (let i = 0; i < node.children.length; i++) {
+    const child = node.children[i];
+    const last = i === node.children.length - 1;
+    result += formatSceneTree(child, childPrefix, last);
+  }
+  return result;
+}
 var test = test$1.test.extend({
   r3f: async ({ page }, use) => {
     const fixture = new R3FFixture(page);
     await use(fixture);
   }
 });
+function createR3FTest(options) {
+  return test$1.test.extend({
+    r3f: async ({ page }, use) => {
+      const fixture = new R3FFixture(page, options);
+      await use(fixture);
+    }
+  });
+}
+var DEFAULT_TIMEOUT = 5e3;
+var DEFAULT_INTERVAL = 100;
+async function fetchSceneCount(page) {
+  return page.evaluate(() => {
+    const api = window.__R3F_DOM__;
+    return api ? api.getCount() : 0;
+  });
+}
+async function fetchCountByType(page, type) {
+  return page.evaluate((t) => {
+    const api = window.__R3F_DOM__;
+    return api ? api.getCountByType(t) : 0;
+  }, type);
+}
+async function fetchTotalTriangles(page) {
+  return page.evaluate(() => {
+    const api = window.__R3F_DOM__;
+    if (!api) return 0;
+    const bridge = api;
+    const snap = bridge.snapshot();
+    let total = 0;
+    function walk(node) {
+      const meta = bridge.getByUuid(node.uuid);
+      if (meta && meta.triangleCount) total += meta.triangleCount;
+      for (const child of node.children) {
+        walk(child);
+      }
+    }
+    walk(snap.tree);
+    return total;
+  });
+}
+async function fetchMeta(page, id) {
+  return page.evaluate((i) => {
+    const api = window.__R3F_DOM__;
+    if (!api) return null;
+    return api.getByTestId(i) ?? api.getByUuid(i) ?? null;
+  }, id);
+}
+async function fetchInsp(page, id) {
+  return page.evaluate((i) => {
+    const api = window.__R3F_DOM__;
+    if (!api) return null;
+    return api.inspect(i);
+  }, id);
+}
+function parseTol(v, def) {
+  const o = typeof v === "number" ? { tolerance: v } : v ?? {};
+  return {
+    timeout: o.timeout ?? DEFAULT_TIMEOUT,
+    interval: o.interval ?? DEFAULT_INTERVAL,
+    tolerance: o.tolerance ?? def
+  };
+}
+function notFound(name, id, detail, timeout) {
+  return {
+    pass: false,
+    message: () => `Expected object "${id}" ${detail}, but it was not found (waited ${timeout}ms)`,
+    name
+  };
+}
 var expect = test$1.expect.extend({
-  // -----------------------------------------------------------------------
-  // toExist — verify an object with the given testId/uuid exists in the scene
-  // -----------------------------------------------------------------------
-  async toExist(r3f, idOrUuid) {
-    const meta = await r3f.getObject(idOrUuid);
+  // ========================= TIER 1 — Metadata ============================
+  // --- toExist ---
+  async toExist(r3f, id, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        return meta !== null;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
     const pass = meta !== null;
     return {
       pass,
-      message: () => pass ? `Expected object "${idOrUuid}" to NOT exist in the scene, but it does` : `Expected object "${idOrUuid}" to exist in the scene, but it was not found`,
+      message: () => pass ? `Expected object "${id}" to NOT exist, but it does` : `Expected object "${id}" to exist, but it was not found (waited ${timeout}ms)`,
       name: "toExist",
-      expected: idOrUuid,
+      expected: id,
       actual: meta
     };
   },
-  // -----------------------------------------------------------------------
-  // toBeVisible — verify an object is visible (object.visible === true)
-  // -----------------------------------------------------------------------
-  async toBeVisible(r3f, idOrUuid) {
-    const meta = await r3f.getObject(idOrUuid);
-    if (!meta) {
-      return {
-        pass: false,
-        message: () => `Expected object "${idOrUuid}" to be visible, but it was not found in the scene`,
-        name: "toBeVisible"
-      };
+  // --- toBeVisible ---
+  async toBeVisible(r3f, id, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        return meta?.visible ?? false;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
     }
-    const pass = meta.visible;
+    if (!meta) return notFound("toBeVisible", id, "to be visible", timeout);
+    const m = meta;
     return {
-      pass,
-      message: () => pass ? `Expected object "${idOrUuid}" to NOT be visible, but it is` : `Expected object "${idOrUuid}" to be visible, but visible=${meta.visible}`,
+      pass: m.visible,
+      message: () => m.visible ? `Expected "${id}" to NOT be visible, but it is` : `Expected "${id}" to be visible, but visible=${m.visible} (waited ${timeout}ms)`,
       name: "toBeVisible",
       expected: true,
-      actual: meta.visible
+      actual: m.visible
     };
   },
-  // -----------------------------------------------------------------------
-  // toBeInFrustum — verify an object's bounding box intersects the camera
-  // frustum (i.e. it is potentially on-screen). Uses inspect() for bounds.
-  // -----------------------------------------------------------------------
-  async toBeInFrustum(r3f, idOrUuid) {
-    const inspection = await r3f.inspect(idOrUuid);
-    if (!inspection) {
-      return {
-        pass: false,
-        message: () => `Expected object "${idOrUuid}" to be in frustum, but it was not found in the scene`,
-        name: "toBeInFrustum"
-      };
+  // --- toHavePosition ---
+  async toHavePosition(r3f, id, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.01);
+    const isNot = this.isNot;
+    let meta = null;
+    let pass = false;
+    let delta = [0, 0, 0];
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        delta = [Math.abs(meta.position[0] - expected[0]), Math.abs(meta.position[1] - expected[1]), Math.abs(meta.position[2] - expected[2])];
+        pass = delta.every((d) => d <= tolerance);
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
     }
-    const { bounds } = inspection;
-    const isFinite = (v) => v.every(Number.isFinite);
-    const pass = isFinite(bounds.min) && isFinite(bounds.max);
+    if (!meta) return notFound("toHavePosition", id, `to have position [${expected}]`, timeout);
+    const m = meta;
     return {
       pass,
-      message: () => pass ? `Expected object "${idOrUuid}" to NOT be in the camera frustum` : `Expected object "${idOrUuid}" to be in the camera frustum, but its bounds are invalid`,
-      name: "toBeInFrustum",
-      expected: "finite bounds",
-      actual: bounds
+      message: () => pass ? `Expected "${id}" to NOT be at [${expected}] (\xB1${tolerance})` : `Expected "${id}" at [${expected}] (\xB1${tolerance}), got [${m.position}] (\u0394 [${delta.map((d) => d.toFixed(4))}]) (waited ${timeout}ms)`,
+      name: "toHavePosition",
+      expected,
+      actual: m.position
     };
   },
-  // -----------------------------------------------------------------------
-  // toHavePosition — verify object position within tolerance
-  // -----------------------------------------------------------------------
-  async toHavePosition(r3f, idOrUuid, expected, tolerance = 0.01) {
-    const meta = await r3f.getObject(idOrUuid);
-    if (!meta) {
-      return {
-        pass: false,
-        message: () => `Expected object "${idOrUuid}" to have position [${expected}], but it was not found`,
-        name: "toHavePosition"
-      };
+  // --- toHaveRotation ---
+  async toHaveRotation(r3f, id, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.01);
+    const isNot = this.isNot;
+    let meta = null;
+    let pass = false;
+    let delta = [0, 0, 0];
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        delta = [Math.abs(meta.rotation[0] - expected[0]), Math.abs(meta.rotation[1] - expected[1]), Math.abs(meta.rotation[2] - expected[2])];
+        pass = delta.every((d) => d <= tolerance);
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
     }
-    const [ex, ey, ez] = expected;
-    const [ax, ay, az] = meta.position;
-    const dx = Math.abs(ax - ex);
-    const dy = Math.abs(ay - ey);
-    const dz = Math.abs(az - ez);
-    const pass = dx <= tolerance && dy <= tolerance && dz <= tolerance;
+    if (!meta) return notFound("toHaveRotation", id, `to have rotation [${expected}]`, timeout);
+    const m = meta;
     return {
       pass,
-      message: () => pass ? `Expected object "${idOrUuid}" to NOT be at position [${expected}] (\xB1${tolerance})` : `Expected object "${idOrUuid}" to be at position [${expected}] (\xB1${tolerance}), but it is at [${meta.position}] (delta: [${dx.toFixed(4)}, ${dy.toFixed(4)}, ${dz.toFixed(4)}])`,
-      name: "toHavePosition",
+      message: () => pass ? `Expected "${id}" to NOT have rotation [${expected}] (\xB1${tolerance})` : `Expected "${id}" rotation [${expected}] (\xB1${tolerance}), got [${m.rotation}] (\u0394 [${delta.map((d) => d.toFixed(4))}]) (waited ${timeout}ms)`,
+      name: "toHaveRotation",
       expected,
-      actual: meta.position
+      actual: m.rotation
     };
   },
-  // -----------------------------------------------------------------------
-  // toHaveBounds — verify object bounding box (world-space)
-  // -----------------------------------------------------------------------
-  async toHaveBounds(r3f, idOrUuid, expected, tolerance = 0.1) {
-    const inspection = await r3f.inspect(idOrUuid);
-    if (!inspection) {
-      return {
-        pass: false,
-        message: () => `Expected object "${idOrUuid}" to have specific bounds, but it was not found`,
-        name: "toHaveBounds"
-      };
+  // --- toHaveScale ---
+  async toHaveScale(r3f, id, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.01);
+    const isNot = this.isNot;
+    let meta = null;
+    let pass = false;
+    let delta = [0, 0, 0];
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        delta = [Math.abs(meta.scale[0] - expected[0]), Math.abs(meta.scale[1] - expected[1]), Math.abs(meta.scale[2] - expected[2])];
+        pass = delta.every((d) => d <= tolerance);
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
     }
-    const { bounds } = inspection;
-    const withinTolerance = (a, b) => a.every((v, i) => Math.abs(v - b[i]) <= tolerance);
-    const pass = withinTolerance(bounds.min, expected.min) && withinTolerance(bounds.max, expected.max);
+    if (!meta) return notFound("toHaveScale", id, `to have scale [${expected}]`, timeout);
+    const m = meta;
     return {
       pass,
-      message: () => pass ? `Expected object "${idOrUuid}" to NOT have bounds min:${JSON.stringify(expected.min)} max:${JSON.stringify(expected.max)}` : `Expected object "${idOrUuid}" to have bounds min:${JSON.stringify(expected.min)} max:${JSON.stringify(expected.max)}, but got min:${JSON.stringify(bounds.min)} max:${JSON.stringify(bounds.max)}`,
-      name: "toHaveBounds",
+      message: () => pass ? `Expected "${id}" to NOT have scale [${expected}] (\xB1${tolerance})` : `Expected "${id}" scale [${expected}] (\xB1${tolerance}), got [${m.scale}] (\u0394 [${delta.map((d) => d.toFixed(4))}]) (waited ${timeout}ms)`,
+      name: "toHaveScale",
       expected,
-      actual: bounds
+      actual: m.scale
     };
   },
-  // -----------------------------------------------------------------------
-  // toHaveInstanceCount — verify InstancedMesh instance count
-  // -----------------------------------------------------------------------
-  async toHaveInstanceCount(r3f, idOrUuid, expectedCount) {
-    const meta = await r3f.getObject(idOrUuid);
-    if (!meta) {
-      return {
-        pass: false,
-        message: () => `Expected object "${idOrUuid}" to have instance count ${expectedCount}, but it was not found`,
-        name: "toHaveInstanceCount"
-      };
+  // --- toHaveType ---
+  async toHaveType(r3f, id, expectedType, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        pass = meta.type === expectedType;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveType", id, `to have type "${expectedType}"`, timeout);
+    const m = meta;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have type "${expectedType}"` : `Expected "${id}" type "${expectedType}", got "${m.type}" (waited ${timeout}ms)`,
+      name: "toHaveType",
+      expected: expectedType,
+      actual: m.type
+    };
+  },
+  // --- toHaveName ---
+  async toHaveName(r3f, id, expectedName, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        pass = meta.name === expectedName;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveName", id, `to have name "${expectedName}"`, timeout);
+    const m = meta;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have name "${expectedName}"` : `Expected "${id}" name "${expectedName}", got "${m.name}" (waited ${timeout}ms)`,
+      name: "toHaveName",
+      expected: expectedName,
+      actual: m.name
+    };
+  },
+  // --- toHaveGeometryType ---
+  async toHaveGeometryType(r3f, id, expectedGeo, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        pass = meta.geometryType === expectedGeo;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveGeometryType", id, `to have geometry "${expectedGeo}"`, timeout);
+    const m = meta;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have geometry "${expectedGeo}"` : `Expected "${id}" geometry "${expectedGeo}", got "${m.geometryType ?? "none"}" (waited ${timeout}ms)`,
+      name: "toHaveGeometryType",
+      expected: expectedGeo,
+      actual: m.geometryType
+    };
+  },
+  // --- toHaveMaterialType ---
+  async toHaveMaterialType(r3f, id, expectedMat, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        pass = meta.materialType === expectedMat;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
     }
-    const actual = meta.instanceCount ?? 0;
+    if (!meta) return notFound("toHaveMaterialType", id, `to have material "${expectedMat}"`, timeout);
+    const m = meta;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have material "${expectedMat}"` : `Expected "${id}" material "${expectedMat}", got "${m.materialType ?? "none"}" (waited ${timeout}ms)`,
+      name: "toHaveMaterialType",
+      expected: expectedMat,
+      actual: m.materialType
+    };
+  },
+  // --- toHaveChildCount ---
+  async toHaveChildCount(r3f, id, expectedCount, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let actual = 0;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta) return false;
+        actual = meta.childrenUuids.length;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveChildCount", id, `to have ${expectedCount} children`, timeout);
     const pass = actual === expectedCount;
     return {
       pass,
-      message: () => pass ? `Expected object "${idOrUuid}" to NOT have instance count ${expectedCount}` : `Expected object "${idOrUuid}" to have instance count ${expectedCount}, but it has ${actual}`,
+      message: () => pass ? `Expected "${id}" to NOT have ${expectedCount} children` : `Expected "${id}" ${expectedCount} children, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveChildCount",
+      expected: expectedCount,
+      actual
+    };
+  },
+  // --- toHaveParent ---
+  async toHaveParent(r3f, id, expectedParent, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let parentMeta = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        if (!meta?.parentUuid) return false;
+        parentMeta = await fetchMeta(r3f.page, meta.parentUuid);
+        if (!parentMeta) return false;
+        pass = parentMeta.uuid === expectedParent || parentMeta.testId === expectedParent || parentMeta.name === expectedParent;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveParent", id, `to have parent "${expectedParent}"`, timeout);
+    const m = meta;
+    const pm = parentMeta;
+    const parentLabel = pm?.testId ?? pm?.name ?? m.parentUuid;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have parent "${expectedParent}"` : `Expected "${id}" parent "${expectedParent}", got "${parentLabel}" (waited ${timeout}ms)`,
+      name: "toHaveParent",
+      expected: expectedParent,
+      actual: parentLabel
+    };
+  },
+  // --- toHaveInstanceCount ---
+  async toHaveInstanceCount(r3f, id, expectedCount, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let actual = 0;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        actual = meta?.instanceCount ?? 0;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveInstanceCount", id, `to have instance count ${expectedCount}`, timeout);
+    const pass = actual === expectedCount;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have instance count ${expectedCount}` : `Expected "${id}" instance count ${expectedCount}, got ${actual} (waited ${timeout}ms)`,
       name: "toHaveInstanceCount",
       expected: expectedCount,
       actual
     };
+  },
+  // ========================= TIER 2 — Inspection ==========================
+  // --- toBeInFrustum ---
+  async toBeInFrustum(r3f, id, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let insp = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id);
+        if (!insp) return false;
+        const fin = (v) => v.every(Number.isFinite);
+        pass = fin(insp.bounds.min) && fin(insp.bounds.max);
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFound("toBeInFrustum", id, "to be in frustum", timeout);
+    const i = insp;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT be in the camera frustum` : `Expected "${id}" in frustum, but bounds are invalid (waited ${timeout}ms)`,
+      name: "toBeInFrustum",
+      expected: "finite bounds",
+      actual: i.bounds
+    };
+  },
+  // --- toHaveBounds ---
+  async toHaveBounds(r3f, id, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.1);
+    const isNot = this.isNot;
+    let insp = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id);
+        if (!insp) return false;
+        const w = (a, b) => a.every((v, j) => Math.abs(v - b[j]) <= tolerance);
+        pass = w(insp.bounds.min, expected.min) && w(insp.bounds.max, expected.max);
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFound("toHaveBounds", id, "to have specific bounds", timeout);
+    const i = insp;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have bounds min:${JSON.stringify(expected.min)} max:${JSON.stringify(expected.max)}` : `Expected "${id}" bounds min:${JSON.stringify(expected.min)} max:${JSON.stringify(expected.max)}, got min:${JSON.stringify(i.bounds.min)} max:${JSON.stringify(i.bounds.max)} (waited ${timeout}ms)`,
+      name: "toHaveBounds",
+      expected,
+      actual: i.bounds
+    };
+  },
+  // --- toHaveColor ---
+  async toHaveColor(r3f, id, expectedColor, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    const norm = expectedColor.startsWith("#") ? expectedColor.toLowerCase() : `#${expectedColor.toLowerCase()}`;
+    let insp = null;
+    let actual;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id);
+        if (!insp?.material?.color) return false;
+        actual = insp.material.color.toLowerCase();
+        pass = actual === norm;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFound("toHaveColor", id, `to have color "${norm}"`, timeout);
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have color "${norm}"` : `Expected "${id}" color "${norm}", got "${actual ?? "no color"}" (waited ${timeout}ms)`,
+      name: "toHaveColor",
+      expected: norm,
+      actual
+    };
+  },
+  // --- toHaveOpacity ---
+  async toHaveOpacity(r3f, id, expectedOpacity, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.01);
+    const isNot = this.isNot;
+    let insp = null;
+    let actual;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id);
+        if (!insp?.material) return false;
+        actual = insp.material.opacity;
+        pass = actual !== void 0 && Math.abs(actual - expectedOpacity) <= tolerance;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFound("toHaveOpacity", id, `to have opacity ${expectedOpacity}`, timeout);
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have opacity ${expectedOpacity} (\xB1${tolerance})` : `Expected "${id}" opacity ${expectedOpacity} (\xB1${tolerance}), got ${actual ?? "no material"} (waited ${timeout}ms)`,
+      name: "toHaveOpacity",
+      expected: expectedOpacity,
+      actual
+    };
+  },
+  // --- toBeTransparent ---
+  async toBeTransparent(r3f, id, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let insp = null;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id);
+        if (!insp?.material) return false;
+        pass = insp.material.transparent === true;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFound("toBeTransparent", id, "to be transparent", timeout);
+    const i = insp;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT be transparent` : `Expected "${id}" transparent=true, got ${i.material?.transparent ?? "no material"} (waited ${timeout}ms)`,
+      name: "toBeTransparent",
+      expected: true,
+      actual: i.material?.transparent
+    };
+  },
+  // --- toHaveVertexCount ---
+  async toHaveVertexCount(r3f, id, expectedCount, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let actual = 0;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        actual = meta?.vertexCount ?? 0;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveVertexCount", id, `to have ${expectedCount} vertices`, timeout);
+    const pass = actual === expectedCount;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have ${expectedCount} vertices` : `Expected "${id}" ${expectedCount} vertices, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveVertexCount",
+      expected: expectedCount,
+      actual
+    };
+  },
+  // --- toHaveTriangleCount ---
+  async toHaveTriangleCount(r3f, id, expectedCount, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let meta = null;
+    let actual = 0;
+    try {
+      await test$1.expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id);
+        actual = meta?.triangleCount ?? 0;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFound("toHaveTriangleCount", id, `to have ${expectedCount} triangles`, timeout);
+    const pass = actual === expectedCount;
+    return {
+      pass,
+      message: () => pass ? `Expected "${id}" to NOT have ${expectedCount} triangles` : `Expected "${id}" ${expectedCount} triangles, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveTriangleCount",
+      expected: expectedCount,
+      actual
+    };
+  },
+  // --- toHaveUserData ---
+  async toHaveUserData(r3f, id, key, expectedValue, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let insp = null;
+    let actual;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id);
+        if (!insp) return false;
+        if (!(key in insp.userData)) return false;
+        if (expectedValue === void 0) {
+          pass = true;
+          return true;
+        }
+        actual = insp.userData[key];
+        pass = JSON.stringify(actual) === JSON.stringify(expectedValue);
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFound("toHaveUserData", id, `to have userData.${key}`, timeout);
+    return {
+      pass,
+      message: () => {
+        if (expectedValue === void 0) {
+          return pass ? `Expected "${id}" to NOT have userData key "${key}"` : `Expected "${id}" to have userData key "${key}", but missing (waited ${timeout}ms)`;
+        }
+        return pass ? `Expected "${id}" to NOT have userData.${key} = ${JSON.stringify(expectedValue)}` : `Expected "${id}" userData.${key} = ${JSON.stringify(expectedValue)}, got ${JSON.stringify(actual)} (waited ${timeout}ms)`;
+      },
+      name: "toHaveUserData",
+      expected: expectedValue ?? `key "${key}"`,
+      actual
+    };
+  },
+  // --- toHaveMapTexture ---
+  async toHaveMapTexture(r3f, id, expectedName, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let insp = null;
+    let actual;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id);
+        if (!insp?.material?.map) return false;
+        actual = insp.material.map;
+        if (!expectedName) {
+          pass = true;
+          return true;
+        }
+        pass = actual === expectedName;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFound("toHaveMapTexture", id, "to have a map texture", timeout);
+    return {
+      pass,
+      message: () => {
+        if (!expectedName) {
+          return pass ? `Expected "${id}" to NOT have a map texture` : `Expected "${id}" to have a map texture, but none found (waited ${timeout}ms)`;
+        }
+        return pass ? `Expected "${id}" to NOT have map "${expectedName}"` : `Expected "${id}" map "${expectedName}", got "${actual ?? "none"}" (waited ${timeout}ms)`;
+      },
+      name: "toHaveMapTexture",
+      expected: expectedName ?? "any map",
+      actual
+    };
+  },
+  // =========================================================================
+  // Scene-level matchers (no object ID — operate on the whole scene)
+  // =========================================================================
+  /**
+   * 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 });
+   */
+  async toHaveObjectCount(r3f, expected, options) {
+    const isNot = this.isNot;
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = options?.interval ?? DEFAULT_INTERVAL;
+    let actual = -1;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        actual = await fetchSceneCount(r3f.page);
+        pass = actual === expected;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected scene to NOT have ${expected} objects, but it does` : `Expected scene to have ${expected} objects, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveObjectCount",
+      expected,
+      actual
+    };
+  },
+  /**
+   * 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);
+   */
+  async toHaveObjectCountGreaterThan(r3f, min, options) {
+    const isNot = this.isNot;
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = options?.interval ?? DEFAULT_INTERVAL;
+    let actual = -1;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        actual = await fetchSceneCount(r3f.page);
+        pass = actual > min;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected scene to have at most ${min} objects, but has ${actual}` : `Expected scene to have more than ${min} objects, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveObjectCountGreaterThan",
+      expected: `> ${min}`,
+      actual
+    };
+  },
+  /**
+   * 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 });
+   */
+  async toHaveCountByType(r3f, type, expected, options) {
+    const isNot = this.isNot;
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = options?.interval ?? DEFAULT_INTERVAL;
+    let actual = -1;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        actual = await fetchCountByType(r3f.page, type);
+        pass = actual === expected;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected scene to NOT have ${expected} "${type}" objects, but it does` : `Expected ${expected} "${type}" objects, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveCountByType",
+      expected,
+      actual
+    };
+  },
+  /**
+   * 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
+   */
+  async toHaveTotalTriangleCount(r3f, expected, options) {
+    const isNot = this.isNot;
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = options?.interval ?? DEFAULT_INTERVAL;
+    let actual = -1;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        actual = await fetchTotalTriangles(r3f.page);
+        pass = actual === expected;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected scene to NOT have ${expected} total triangles, but it does` : `Expected ${expected} total triangles, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveTotalTriangleCount",
+      expected,
+      actual
+    };
+  },
+  /**
+   * 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);
+   */
+  async toHaveTotalTriangleCountLessThan(r3f, max, options) {
+    const isNot = this.isNot;
+    const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = options?.interval ?? DEFAULT_INTERVAL;
+    let actual = -1;
+    let pass = false;
+    try {
+      await test$1.expect.poll(async () => {
+        actual = await fetchTotalTriangles(r3f.page);
+        pass = actual < max;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected scene to have at least ${max} triangles, but has ${actual}` : `Expected scene to have fewer than ${max} triangles, got ${actual} (waited ${timeout}ms)`,
+      name: "toHaveTotalTriangleCountLessThan",
+      expected: `< ${max}`,
+      actual
+    };
   }
 });
 
+// src/pathGenerators.ts
+function linePath(start, end, steps = 10, pressure = 0.5) {
+  const points = [];
+  const totalSteps = steps + 1;
+  for (let i = 0; i <= totalSteps; i++) {
+    const t = i / totalSteps;
+    points.push({
+      x: start.x + (end.x - start.x) * t,
+      y: start.y + (end.y - start.y) * t,
+      pressure
+    });
+  }
+  return points;
+}
+function curvePath(start, control, end, steps = 20, pressure = 0.5) {
+  const points = [];
+  for (let i = 0; i <= steps; i++) {
+    const t = i / steps;
+    const invT = 1 - t;
+    points.push({
+      x: invT * invT * start.x + 2 * invT * t * control.x + t * t * end.x,
+      y: invT * invT * start.y + 2 * invT * t * control.y + t * t * end.y,
+      pressure
+    });
+  }
+  return points;
+}
+function rectPath(topLeft, bottomRight, pointsPerSide = 5, pressure = 0.5) {
+  const topRight = { x: bottomRight.x, y: topLeft.y };
+  const bottomLeft = { x: topLeft.x, y: bottomRight.y };
+  const sides = [
+    [topLeft, topRight],
+    [topRight, bottomRight],
+    [bottomRight, bottomLeft],
+    [bottomLeft, topLeft]
+  ];
+  const points = [];
+  for (const [from, to] of sides) {
+    for (let i = 0; i < pointsPerSide; i++) {
+      const t = i / pointsPerSide;
+      points.push({
+        x: from.x + (to.x - from.x) * t,
+        y: from.y + (to.y - from.y) * t,
+        pressure
+      });
+    }
+  }
+  points.push({ x: topLeft.x, y: topLeft.y, pressure });
+  return points;
+}
+function circlePath(center, radiusX, radiusY, steps = 36, pressure = 0.5) {
+  const ry = radiusY ?? radiusX;
+  const points = [];
+  for (let i = 0; i <= steps; i++) {
+    const angle = i / steps * Math.PI * 2;
+    points.push({
+      x: center.x + Math.cos(angle) * radiusX,
+      y: center.y + Math.sin(angle) * ry,
+      pressure
+    });
+  }
+  return points;
+}
+
 exports.R3FFixture = R3FFixture;
+exports.circlePath = circlePath;
 exports.click = click;
 exports.contextMenu = contextMenu;
+exports.createR3FTest = createR3FTest;
+exports.curvePath = curvePath;
 exports.doubleClick = doubleClick;
 exports.drag = drag;
+exports.drawPathOnCanvas = drawPathOnCanvas;
 exports.expect = expect;
 exports.hover = hover;
+exports.linePath = linePath;
 exports.pointerMiss = pointerMiss;
+exports.rectPath = rectPath;
 exports.test = test;
 exports.waitForIdle = waitForIdle;
+exports.waitForNewObject = waitForNewObject;
 exports.waitForObject = waitForObject;
 exports.waitForSceneReady = waitForSceneReady;
 exports.wheel = wheel;