@react-three-dom/playwright 0.1.2 → 0.3.0

package/dist/index.js

@@ -1,22 +1,119 @@
-import { test as test$1, expect as expect$1 } from '@playwright/test';
+import { test as test$1, expect } from '@playwright/test';
 
 // src/fixtures.ts
 
+// src/diffSnapshots.ts
+var FIELDS_TO_COMPARE = [
+  "name",
+  "type",
+  "testId",
+  "visible",
+  "position",
+  "rotation",
+  "scale"
+];
+function flattenTree(node) {
+  const map = /* @__PURE__ */ new Map();
+  function walk(n) {
+    map.set(n.uuid, n);
+    n.children.forEach(walk);
+  }
+  walk(node);
+  return map;
+}
+function valueEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => valueEqual(v, b[i]));
+  }
+  return false;
+}
+function diffSnapshots(before, after) {
+  const beforeMap = flattenTree(before.tree);
+  const afterMap = flattenTree(after.tree);
+  const added = [];
+  const removed = [];
+  const changed = [];
+  for (const [uuid, node] of afterMap) {
+    if (!beforeMap.has(uuid)) added.push(node);
+  }
+  for (const [uuid, node] of beforeMap) {
+    if (!afterMap.has(uuid)) removed.push(node);
+  }
+  for (const [uuid, afterNode] of afterMap) {
+    const beforeNode = beforeMap.get(uuid);
+    if (!beforeNode) continue;
+    for (const field of FIELDS_TO_COMPARE) {
+      const from = beforeNode[field];
+      const to = afterNode[field];
+      if (!valueEqual(from, to)) {
+        changed.push({ uuid, field, from, to });
+      }
+    }
+  }
+  return { added, removed, changed };
+}
+
 // src/waiters.ts
+async function waitForReadyBridge(page, timeout, canvasId) {
+  const deadline = Date.now() + timeout;
+  const pollMs = 100;
+  while (Date.now() < deadline) {
+    const state = await page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api) return { exists: false };
+      return {
+        exists: true,
+        ready: api._ready,
+        error: api._error ?? null,
+        count: api.getCount()
+      };
+    }, canvasId ?? 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}
+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((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    if (!api) return { exists: false, ready: false, error: null };
+    return { exists: true, ready: api._ready, error: api._error ?? null };
+  }, canvasId ?? 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,
     pollIntervalMs = 100,
-    timeout = 1e4
+    timeout = 1e4,
+    canvasId
   } = options;
   const deadline = Date.now() + timeout;
-  await page.waitForFunction(() => typeof window.__R3F_DOM__ !== "undefined", void 0, {
-    timeout
-  });
+  await waitForReadyBridge(page, timeout, canvasId);
   let lastCount = -1;
   let stableRuns = 0;
   while (Date.now() < deadline) {
-    const count = await page.evaluate(() => window.__R3F_DOM__.getCount());
+    const count = await page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api.getCount();
+    }, canvasId ?? null);
     if (count === lastCount && count > 0) {
       stableRuns++;
       if (stableRuns >= stableChecks) return;
@@ -26,43 +123,76 @@ async function waitForSceneReady(page, options = {}) {
     lastCount = count;
     await page.waitForTimeout(pollIntervalMs);
   }
+  const state = await page.evaluate((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    if (!api)
+      return { bridgeFound: false, ready: false, error: null, objectCount: 0 };
+    return {
+      bridgeFound: true,
+      ready: api._ready,
+      error: api._error ?? null,
+      objectCount: api.getCount()
+    };
+  }, canvasId ?? null);
+  const stateLine = state.bridgeFound ? `Bridge found: yes, _ready: ${state.ready}, _error: ${state.error ?? "none"}, objectCount: ${state.objectCount}` : "Bridge found: no (ensure <ThreeDom /> is mounted inside <Canvas> and refresh)";
   throw new Error(
-    `waitForSceneReady timed out after ${timeout}ms. Last count: ${lastCount}, stable runs: ${stableRuns}/${stableChecks}`
+    `waitForSceneReady timed out after ${timeout}ms. ${stateLine}. Last count: ${lastCount}, stable runs: ${stableRuns}/${stableChecks}.`
   );
 }
 async function waitForObject(page, idOrUuid, options = {}) {
   const {
     bridgeTimeout = 3e4,
     objectTimeout = 4e4,
-    pollIntervalMs = 200
+    pollIntervalMs = 200,
+    canvasId
   } = options;
-  await page.waitForFunction(() => typeof window.__R3F_DOM__ !== "undefined", void 0, {
-    timeout: bridgeTimeout
-  });
+  await waitForReadyBridge(page, bridgeTimeout, canvasId);
   const deadline = Date.now() + objectTimeout;
   while (Date.now() < deadline) {
     const found = await page.evaluate(
-      (id) => {
-        const api = window.__R3F_DOM__;
-        if (!api) return false;
+      ([id, cid]) => {
+        const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+        if (!api || !api._ready) return false;
         return (api.getByTestId(id) ?? api.getByUuid(id)) !== null;
       },
-      idOrUuid
+      [idOrUuid, canvasId ?? null]
     );
     if (found) return;
     await page.waitForTimeout(pollIntervalMs);
   }
-  throw new Error(
-    `waitForObject("${idOrUuid}") timed out after ${objectTimeout}ms. Is the object rendered with userData.testId or this uuid?`
+  const diagnostics = await page.evaluate(
+    ([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api) return { bridgeExists: false, ready: false, count: 0, error: null, suggestions: [] };
+      const suggestions = typeof api.fuzzyFind === "function" ? api.fuzzyFind(id, 5).map((m) => ({ testId: m.testId, name: m.name, uuid: m.uuid })) : [];
+      return {
+        bridgeExists: true,
+        ready: api._ready,
+        count: api.getCount(),
+        error: api._error ?? null,
+        suggestions
+      };
+    },
+    [idOrUuid, canvasId ?? null]
   );
+  let msg = `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}"?`;
+  if (diagnostics.suggestions.length > 0) {
+    msg += "\nDid you mean:\n" + diagnostics.suggestions.map((s) => {
+      const id = s.testId ? `testId="${s.testId}"` : `uuid="${s.uuid}"`;
+      return `  \u2192 ${s.name || "(unnamed)"} [${id}]`;
+    }).join("\n");
+  }
+  throw new Error(msg);
 }
 async function waitForIdle(page, options = {}) {
   const {
     idleFrames = 10,
-    timeout = 1e4
+    timeout = 1e4,
+    canvasId
   } = options;
+  await waitForReadyBridge(page, timeout, canvasId);
   const settled = await page.evaluate(
-    ([frames, timeoutMs]) => {
+    ([frames, timeoutMs, cid]) => {
       return new Promise((resolve) => {
         const deadline = Date.now() + timeoutMs;
         let lastJson = "";
@@ -72,8 +202,17 @@ async function waitForIdle(page, options = {}) {
             resolve(false);
             return;
           }
-          const snap = window.__R3F_DOM__?.snapshot();
-          const json = snap ? JSON.stringify(snap.tree) : "";
+          const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : 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) {
@@ -89,140 +228,792 @@ async function waitForIdle(page, options = {}) {
         requestAnimationFrame(check);
       });
     },
-    [idleFrames, timeout]
+    [idleFrames, timeout, canvasId ?? null]
   );
+  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) => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
+async function waitForNewObject(page, options = {}) {
+  const {
+    type,
+    nameContains,
+    pollIntervalMs = 100,
+    timeout = 1e4,
+    canvasId
+  } = options;
+  const baselineUuids = await page.evaluate((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    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;
+  }, canvasId ?? null);
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    await page.waitForTimeout(pollIntervalMs);
+    const result = await page.evaluate(
+      ([filterType, filterName, knownUuids, cid]) => {
+        const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : 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, canvasId ?? null]
+    );
+    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.`
+  );
+}
+async function waitForObjectRemoved(page, idOrUuid, options = {}) {
+  const {
+    bridgeTimeout = 3e4,
+    pollIntervalMs = 100,
+    timeout = 1e4,
+    canvasId
+  } = options;
+  await waitForReadyBridge(page, bridgeTimeout, canvasId);
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const stillPresent = await page.evaluate(([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api) return true;
+      const meta = api.getByTestId(id) ?? api.getByUuid(id);
+      return meta !== null;
+    }, [idOrUuid, canvasId ?? null]);
+    if (!stillPresent) return;
+    await page.waitForTimeout(pollIntervalMs);
+  }
+  throw new Error(
+    `waitForObjectRemoved timed out after ${timeout}ms. Object "${idOrUuid}" is still in the scene.`
+  );
+}
+
+// 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, canvasId) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const state = await page.evaluate(
+      ([id, cid]) => {
+        const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : 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, canvasId ?? null]
+    );
+    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}"${canvasId ? ` (canvas: "${canvasId}")` : ""}.`
+      );
+    }
+    await page.waitForTimeout(AUTO_WAIT_POLL_MS);
+  }
+  const finalState = await page.evaluate(
+    ([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api) return { bridge: false, ready: false, count: 0, error: null, found: false, suggestions: [] };
+      const suggestions = typeof api.fuzzyFind === "function" ? api.fuzzyFind(id, 5).map((m) => ({ testId: m.testId, name: m.name, uuid: m.uuid })) : [];
+      return {
+        bridge: true,
+        ready: api._ready,
+        count: api.getCount(),
+        error: api._error ?? null,
+        found: (api.getByTestId(id) ?? api.getByUuid(id)) !== null,
+        suggestions
+      };
+    },
+    [idOrUuid, canvasId ?? null]
+  );
+  if (!finalState.bridge) {
+    throw new Error(
+      `[react-three-dom] Auto-wait timed out after ${timeout}ms: bridge not found${canvasId ? ` (canvas: "${canvasId}")` : ""}.
+Ensure <ThreeDom${canvasId ? ` canvasId="${canvasId}"` : ""}> is mounted inside your <Canvas> component.`
+    );
+  }
+  let msg = `[react-three-dom] Auto-wait timed out after ${timeout}ms: object "${idOrUuid}" not found${canvasId ? ` (canvas: "${canvasId}")` : ""}.
+Bridge: ready=${finalState.ready}, objectCount=${finalState.count}` + (finalState.error ? `, error=${finalState.error}` : "") + `.
+Ensure the object has userData.testId="${idOrUuid}" or uuid="${idOrUuid}".`;
+  if (finalState.suggestions.length > 0) {
+    msg += "\nDid you mean:\n" + finalState.suggestions.map((s) => {
+      const id = s.testId ? `testId="${s.testId}"` : `uuid="${s.uuid}"`;
+      return `  \u2192 ${s.name || "(unnamed)"} [${id}]`;
+    }).join("\n");
+  }
+  throw new Error(msg);
+}
+async function autoWaitForBridge(page, timeout = DEFAULT_AUTO_WAIT_TIMEOUT, canvasId) {
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const state = await page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api) return { exists: false };
+      return {
+        exists: true,
+        ready: api._ready,
+        error: api._error ?? null
+      };
+    }, canvasId ?? 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${canvasId ? ` (canvas: "${canvasId}")` : ""}.
+Ensure <ThreeDom${canvasId ? ` canvasId="${canvasId}"` : ""}> is mounted inside your <Canvas> component.`
+  );
+}
+async function click(page, idOrUuid, timeout, canvasId) {
+  await autoWaitForObject(page, idOrUuid, timeout, canvasId);
+  await page.evaluate(([id, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
     api.click(id);
-  }, idOrUuid);
+  }, [idOrUuid, canvasId ?? null]);
 }
-async function doubleClick(page, idOrUuid) {
-  await page.evaluate((id) => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
+async function doubleClick(page, idOrUuid, timeout, canvasId) {
+  await autoWaitForObject(page, idOrUuid, timeout, canvasId);
+  await page.evaluate(([id, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
     api.doubleClick(id);
-  }, idOrUuid);
+  }, [idOrUuid, canvasId ?? null]);
 }
-async function contextMenu(page, idOrUuid) {
-  await page.evaluate((id) => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
+async function contextMenu(page, idOrUuid, timeout, canvasId) {
+  await autoWaitForObject(page, idOrUuid, timeout, canvasId);
+  await page.evaluate(([id, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
     api.contextMenu(id);
-  }, idOrUuid);
+  }, [idOrUuid, canvasId ?? null]);
 }
-async function hover(page, idOrUuid) {
-  await page.evaluate((id) => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
+async function hover(page, idOrUuid, timeout, canvasId) {
+  await autoWaitForObject(page, idOrUuid, timeout, canvasId);
+  await page.evaluate(([id, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
     api.hover(id);
-  }, idOrUuid);
+  }, [idOrUuid, canvasId ?? null]);
+}
+async function unhover(page, timeout, canvasId) {
+  await autoWaitForBridge(page, timeout, canvasId);
+  await page.evaluate((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
+    api.unhover();
+  }, canvasId ?? null);
 }
-async function drag(page, idOrUuid, delta) {
+async function drag(page, idOrUuid, delta, timeout, canvasId) {
+  await autoWaitForObject(page, idOrUuid, timeout, canvasId);
   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, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
+      await api.drag(id, d);
     },
-    [idOrUuid, delta]
+    [idOrUuid, delta, canvasId ?? null]
   );
 }
-async function wheel(page, idOrUuid, options) {
+async function wheel(page, idOrUuid, options, timeout, canvasId) {
+  await autoWaitForObject(page, idOrUuid, timeout, canvasId);
   await page.evaluate(
-    ([id, opts]) => {
-      const api = window.__R3F_DOM__;
-      if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
+    ([id, opts, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
       api.wheel(id, opts);
     },
-    [idOrUuid, options]
+    [idOrUuid, options, canvasId ?? null]
   );
 }
-async function pointerMiss(page) {
-  await page.evaluate(() => {
-    const api = window.__R3F_DOM__;
-    if (!api) throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
+async function pointerMiss(page, timeout, canvasId) {
+  await autoWaitForBridge(page, timeout, canvasId);
+  await page.evaluate((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
     api.pointerMiss();
-  });
+  }, canvasId ?? null);
+}
+async function drawPathOnCanvas(page, points, options, timeout, canvasId) {
+  await autoWaitForBridge(page, timeout, canvasId);
+  return page.evaluate(
+    async ([pts, opts, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
+      return api.drawPath(pts, opts ?? void 0);
+    },
+    [points, options ?? null, canvasId ?? null]
+  );
 }
+async function getCameraState(page, timeout, canvasId) {
+  await autoWaitForBridge(page, timeout, canvasId);
+  return page.evaluate((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__[cid] : window.__R3F_DOM__;
+    return api.getCameraState();
+  }, canvasId ?? null);
+}
+
+// src/reporter.ts
+var RESET = "\x1B[0m";
+var BOLD = "\x1B[1m";
+var DIM = "\x1B[2m";
+var GREEN = "\x1B[32m";
+var RED = "\x1B[31m";
+var YELLOW = "\x1B[33m";
+var CYAN = "\x1B[36m";
+var MAGENTA = "\x1B[35m";
+var TAG = `${CYAN}[r3f-dom]${RESET}`;
+function ok(msg) {
+  return `${TAG} ${GREEN}\u2713${RESET} ${msg}`;
+}
+function fail(msg) {
+  return `${TAG} ${RED}\u2717${RESET} ${msg}`;
+}
+function warn(msg) {
+  return `${TAG} ${YELLOW}\u26A0${RESET} ${msg}`;
+}
+function info(msg) {
+  return `${TAG} ${DIM}${msg}${RESET}`;
+}
+function heading(msg) {
+  return `
+${TAG} ${BOLD}${MAGENTA}${msg}${RESET}`;
+}
+var R3FReporter = class {
+  constructor(_page, enabled = true, canvasId) {
+    this._page = _page;
+    this._enabled = true;
+    this._enabled = enabled;
+    this._canvasId = canvasId;
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle events
+  // -----------------------------------------------------------------------
+  logBridgeWaiting() {
+    if (!this._enabled) return;
+    console.log(info("Waiting for bridge (window.__R3F_DOM__)..."));
+  }
+  logBridgeConnected(diag) {
+    if (!this._enabled) return;
+    if (diag) {
+      console.log(ok(`Bridge connected \u2014 v${diag.version}, ${diag.objectCount} objects, ${diag.meshCount} meshes`));
+      console.log(info(`  Canvas: ${diag.canvasWidth}\xD7${diag.canvasHeight}  GPU: ${diag.webglRenderer}`));
+      console.log(info(`  DOM nodes: ${diag.materializedDomNodes}/${diag.maxDomNodes}  Dirty queue: ${diag.dirtyQueueSize}`));
+    } else {
+      console.log(ok("Bridge connected"));
+    }
+  }
+  logBridgeError(error) {
+    if (!this._enabled) return;
+    console.log(fail(`Bridge error: ${error}`));
+  }
+  logSceneReady(objectCount) {
+    if (!this._enabled) return;
+    console.log(ok(`Scene ready \u2014 ${objectCount} objects stabilized`));
+  }
+  logObjectFound(idOrUuid, type, name) {
+    if (!this._enabled) return;
+    const label = name ? `"${name}" (${type})` : type;
+    console.log(ok(`Object found: "${idOrUuid}" \u2192 ${label}`));
+  }
+  logObjectNotFound(idOrUuid, suggestions) {
+    if (!this._enabled) return;
+    console.log(fail(`Object not found: "${idOrUuid}"`));
+    if (suggestions && suggestions.length > 0) {
+      console.log(warn("Did you mean:"));
+      for (const s of suggestions.slice(0, 5)) {
+        const id = s.testId ? `testId="${s.testId}"` : `uuid="${s.uuid}"`;
+        console.log(info(`  \u2192 ${s.name || "(unnamed)"} [${id}]`));
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Interaction events
+  // -----------------------------------------------------------------------
+  logInteraction(action, idOrUuid, extra) {
+    if (!this._enabled) return;
+    const suffix = extra ? ` ${DIM}${extra}${RESET}` : "";
+    console.log(info(`${action}("${idOrUuid}")${suffix}`));
+  }
+  logInteractionDone(action, idOrUuid, durationMs) {
+    if (!this._enabled) return;
+    console.log(ok(`${action}("${idOrUuid}") \u2014 ${durationMs}ms`));
+  }
+  // -----------------------------------------------------------------------
+  // Assertion context
+  // -----------------------------------------------------------------------
+  logAssertionFailure(matcherName, id, detail, diag) {
+    if (!this._enabled) return;
+    console.log(heading(`Assertion failed: ${matcherName}("${id}")`));
+    console.log(fail(detail));
+    if (diag) {
+      this._printDiagnosticsSummary(diag);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Full diagnostics dump
+  // -----------------------------------------------------------------------
+  async logDiagnostics() {
+    if (!this._enabled) return;
+    const diag = await this.fetchDiagnostics();
+    if (!diag) {
+      console.log(fail("Cannot fetch diagnostics \u2014 bridge not available"));
+      return;
+    }
+    console.log(heading("Bridge Diagnostics"));
+    this._printDiagnosticsFull(diag);
+  }
+  async fetchDiagnostics() {
+    return this._page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api || typeof api.getDiagnostics !== "function") return null;
+      return api.getDiagnostics();
+    }, this._canvasId ?? null);
+  }
+  async fetchFuzzyMatches(query, limit = 5) {
+    return this._page.evaluate(
+      ({ q, lim, cid }) => {
+        const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+        if (!api || typeof api.fuzzyFind !== "function") return [];
+        return api.fuzzyFind(q, lim);
+      },
+      { q: query, lim: limit, cid: this._canvasId ?? null }
+    );
+  }
+  // -----------------------------------------------------------------------
+  // Private formatting
+  // -----------------------------------------------------------------------
+  _printDiagnosticsSummary(d) {
+    console.log(info(`  Bridge: v${d.version} ready=${d.ready}${d.error ? ` error="${d.error}"` : ""}`));
+    console.log(info(`  Scene: ${d.objectCount} objects (${d.meshCount} meshes, ${d.groupCount} groups, ${d.lightCount} lights)`));
+    console.log(info(`  Canvas: ${d.canvasWidth}\xD7${d.canvasHeight}  GPU: ${d.webglRenderer}`));
+  }
+  _printDiagnosticsFull(d) {
+    const status = d.ready ? `${GREEN}READY${RESET}` : `${RED}NOT READY${RESET}`;
+    console.log(`  ${BOLD}Status:${RESET}    ${status}  v${d.version}`);
+    if (d.error) console.log(`  ${BOLD}Error:${RESET}     ${RED}${d.error}${RESET}`);
+    console.log(`  ${BOLD}Objects:${RESET}   ${d.objectCount} total`);
+    console.log(`             ${d.meshCount} meshes, ${d.groupCount} groups, ${d.lightCount} lights, ${d.cameraCount} cameras`);
+    console.log(`  ${BOLD}DOM:${RESET}       ${d.materializedDomNodes}/${d.maxDomNodes} materialized`);
+    console.log(`  ${BOLD}Canvas:${RESET}    ${d.canvasWidth}\xD7${d.canvasHeight}`);
+    console.log(`  ${BOLD}GPU:${RESET}       ${d.webglRenderer}`);
+    console.log(`  ${BOLD}Dirty:${RESET}     ${d.dirtyQueueSize} queued updates`);
+  }
+};
 
 // src/fixtures.ts
-var R3FFixture = class {
-  constructor(_page) {
+var R3FFixture = class _R3FFixture {
+  constructor(_page, opts) {
     this._page = _page;
+    this._debugListenerAttached = false;
+    this.canvasId = opts?.canvasId;
+    this._reporter = new R3FReporter(_page, opts?.report !== false, this.canvasId);
+    if (opts?.debug) {
+      this._attachDebugListener();
+    }
   }
   /** The underlying Playwright Page. */
   get page() {
     return this._page;
   }
+  /** Access the reporter for custom diagnostic logging. */
+  get reporter() {
+    return this._reporter;
+  }
+  /**
+   * Create a scoped fixture targeting a specific canvas instance.
+   * All queries, interactions, and assertions on the returned fixture
+   * will use `window.__R3F_DOM_INSTANCES__[canvasId]` instead of
+   * `window.__R3F_DOM__`.
+   *
+   * @example
+   * ```typescript
+   * const mainR3f = r3f.forCanvas('main-viewport');
+   * const minimapR3f = r3f.forCanvas('minimap');
+   * await mainR3f.click('building-42');
+   * await expect(minimapR3f).toExist('building-42-marker');
+   * ```
+   */
+  forCanvas(canvasId) {
+    return new _R3FFixture(this._page, {
+      canvasId,
+      report: this._reporter !== null
+    });
+  }
+  /**
+   * List all active canvas IDs registered on the page.
+   * Returns an empty array if only the default (unnamed) bridge is active.
+   */
+  async getCanvasIds() {
+    return this._page.evaluate(() => {
+      const instances = window.__R3F_DOM_INSTANCES__;
+      return instances ? Object.keys(instances) : [];
+    });
+  }
+  // -----------------------------------------------------------------------
+  // 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. */
   async getObject(idOrUuid) {
-    return this._page.evaluate((id) => {
-      const api = window.__R3F_DOM__;
+    return this._page.evaluate(([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
       if (!api) return null;
       return api.getByTestId(id) ?? api.getByUuid(id) ?? null;
-    }, idOrUuid);
+    }, [idOrUuid, this.canvasId ?? null]);
+  }
+  /** Get object metadata by testId (userData.testId). Returns null if not found. */
+  async getByTestId(testId) {
+    return this._page.evaluate(([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getByTestId(id) : null;
+    }, [testId, this.canvasId ?? null]);
+  }
+  /** Get object metadata by UUID. Returns null if not found. */
+  async getByUuid(uuid) {
+    return this._page.evaluate(([u, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getByUuid(u) : null;
+    }, [uuid, this.canvasId ?? null]);
+  }
+  /** Get all objects with the given name (names are not unique in Three.js). */
+  async getByName(name) {
+    return this._page.evaluate(([n, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getByName(n) : [];
+    }, [name, this.canvasId ?? null]);
   }
-  /** Get heavy inspection data (Tier 2) by testId or uuid. */
-  async inspect(idOrUuid) {
-    return this._page.evaluate((id) => {
-      const api = window.__R3F_DOM__;
+  /** Get direct children of an object by testId or uuid. */
+  async getChildren(idOrUuid) {
+    return this._page.evaluate(([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getChildren(id) : [];
+    }, [idOrUuid, this.canvasId ?? null]);
+  }
+  /** Get parent of an object by testId or uuid. Returns null if root or not found. */
+  async getParent(idOrUuid) {
+    return this._page.evaluate(([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getParent(id) : null;
+    }, [idOrUuid, this.canvasId ?? null]);
+  }
+  /** Get heavy inspection data (Tier 2) by testId or uuid. Pass { includeGeometryData: true } to include vertex positions and triangle indices. */
+  async inspect(idOrUuid, options) {
+    return this._page.evaluate(
+      ({ id, opts, cid }) => {
+        const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+        if (!api) return null;
+        return api.inspect(id, opts);
+      },
+      { id: idOrUuid, opts: options, cid: this.canvasId ?? null }
+    );
+  }
+  /**
+   * Get world-space position [x, y, z] of an object (from its world matrix).
+   * Use for nested objects where local position differs from world position.
+   */
+  async getWorldPosition(idOrUuid) {
+    return this._page.evaluate(([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
       if (!api) return null;
-      return api.inspect(id);
-    }, idOrUuid);
+      const insp = api.inspect(id);
+      if (!insp?.worldMatrix || insp.worldMatrix.length < 15) return null;
+      const m = insp.worldMatrix;
+      return [m[12], m[13], m[14]];
+    }, [idOrUuid, this.canvasId ?? null]);
   }
   /** Take a full scene snapshot. */
   async snapshot() {
-    return this._page.evaluate(() => {
-      const api = window.__R3F_DOM__;
+    return this._page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
       return api ? api.snapshot() : null;
-    });
+    }, this.canvasId ?? null);
+  }
+  /**
+   * Compare two scene snapshots: returns added nodes, removed nodes, and
+   * property changes (name, type, testId, visible, position, rotation, scale).
+   * Use after taking snapshots before/after an action to assert on scene changes.
+   */
+  diffSnapshots(before, after) {
+    return diffSnapshots(before, after);
+  }
+  /**
+   * Run an async action and return how many objects were added and removed
+   * compared to before the action. Uses snapshots before/after so add and
+   * remove are both counted correctly when both happen.
+   */
+  async trackObjectCount(action) {
+    const before = await this.snapshot();
+    if (!before) throw new Error("trackObjectCount: no snapshot before (bridge not ready?)");
+    await action();
+    const after = await this.snapshot();
+    if (!after) throw new Error("trackObjectCount: no snapshot after (bridge not ready?)");
+    const diff = diffSnapshots(before, after);
+    return { added: diff.added.length, removed: diff.removed.length };
   }
   /** Get the total number of tracked objects. */
   async getCount() {
-    return this._page.evaluate(() => {
-      const api = window.__R3F_DOM__;
+    return this._page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
       return api ? api.getCount() : 0;
-    });
+    }, this.canvasId ?? null);
+  }
+  /**
+   * Return a Playwright locator for the R3F canvas element the bridge is attached to.
+   * The canvas has `data-r3f-canvas` set by the bridge (value is the canvasId or "true").
+   */
+  getCanvasLocator() {
+    if (this.canvasId) {
+      return this._page.locator(`[data-r3f-canvas="${this.canvasId}"]`);
+    }
+    return this._page.locator("[data-r3f-canvas]");
+  }
+  /**
+   * Get all objects of a given Three.js type (e.g. "Mesh", "Group", "Line").
+   */
+  async getByType(type) {
+    return this._page.evaluate(([t, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getByType(t) : [];
+    }, [type, this.canvasId ?? null]);
+  }
+  /**
+   * Get all objects with a given geometry type (e.g. "BoxGeometry", "BufferGeometry").
+   */
+  async getByGeometryType(type) {
+    return this._page.evaluate(([t, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getByGeometryType(t) : [];
+    }, [type, this.canvasId ?? null]);
+  }
+  /**
+   * Get all objects with a given material type (e.g. "MeshStandardMaterial").
+   */
+  async getByMaterialType(type) {
+    return this._page.evaluate(([t, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getByMaterialType(t) : [];
+    }, [type, this.canvasId ?? null]);
+  }
+  /**
+   * Get objects that have a specific userData key (and optionally matching value).
+   */
+  async getByUserData(key, value) {
+    return this._page.evaluate(({ k, v, cid }) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getByUserData(k, v) : [];
+    }, { k: key, v: value, cid: this.canvasId ?? null });
+  }
+  /**
+   * Count objects of a given Three.js type.
+   */
+  async getCountByType(type) {
+    return this._page.evaluate(([t, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      return api ? api.getCountByType(t) : 0;
+    }, [type, this.canvasId ?? null]);
+  }
+  /**
+   * Batch lookup: get metadata for multiple objects by testId or uuid in a
+   * single browser round-trip.
+   */
+  async getObjects(ids) {
+    return this._page.evaluate(([idList, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api) {
+        const result = {};
+        for (const id of idList) result[id] = null;
+        return result;
+      }
+      return api.getObjects(idList);
+    }, [ids, this.canvasId ?? 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
+   * ```
+   */
+  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, this.canvasId);
+  }
+  /**
+   * 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, this.canvasId);
   }
-  /** Double-click a 3D object by testId or uuid. */
-  async doubleClick(idOrUuid) {
-    return doubleClick(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, this.canvasId);
+  }
+  /**
+   * 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, this.canvasId);
+  }
+  /**
+   * Unhover / pointer-leave — resets hover state by moving pointer off-canvas.
+   * Auto-waits for the bridge to be ready.
+   */
+  async unhover(timeout) {
+    return unhover(this._page, timeout, this.canvasId);
   }
-  /** Right-click / context-menu a 3D object by testId or uuid. */
-  async contextMenu(idOrUuid) {
-    return contextMenu(this._page, idOrUuid);
+  /**
+   * 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, this.canvasId);
   }
-  /** Hover over a 3D object by testId or uuid. */
-  async hover(idOrUuid) {
-    return hover(this._page, idOrUuid);
+  /**
+   * 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, this.canvasId);
   }
-  /** Drag a 3D object with a world-space delta vector. */
-  async drag(idOrUuid, delta) {
-    return drag(this._page, idOrUuid, delta);
+  /**
+   * Click empty space to trigger onPointerMissed handlers.
+   * Auto-waits for the bridge to be ready.
+   */
+  async pointerMiss(timeout) {
+    return pointerMiss(this._page, timeout, this.canvasId);
   }
-  /** Dispatch a wheel/scroll event on a 3D object. */
-  async wheel(idOrUuid, options) {
-    return wheel(this._page, idOrUuid, options);
+  /**
+   * 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, this.canvasId);
   }
-  /** Click empty space to trigger onPointerMissed handlers. */
-  async pointerMiss() {
-    return pointerMiss(this._page);
+  // -----------------------------------------------------------------------
+  // Camera
+  // -----------------------------------------------------------------------
+  /**
+   * Get the current camera state (position, rotation, fov, near, far, zoom, target).
+   * Auto-waits for the bridge to be ready.
+   */
+  async getCameraState(timeout) {
+    return getCameraState(this._page, timeout, this.canvasId);
   }
   // -----------------------------------------------------------------------
   // Waiters
@@ -230,9 +1021,22 @@ var R3FFixture = class {
   /**
    * Wait until the scene is ready — `window.__R3F_DOM__` is available and
    * the object count has stabilised across several consecutive checks.
+   * Logs bridge connection and scene readiness to the terminal.
    */
   async waitForSceneReady(options) {
-    return waitForSceneReady(this._page, options);
+    this._reporter.logBridgeWaiting();
+    try {
+      await waitForSceneReady(this._page, { ...options, canvasId: this.canvasId });
+      const diag = await this._reporter.fetchDiagnostics();
+      if (diag) {
+        this._reporter.logBridgeConnected(diag);
+        this._reporter.logSceneReady(diag.objectCount);
+      }
+    } catch (e) {
+      const diag = await this._reporter.fetchDiagnostics();
+      if (diag?.error) this._reporter.logBridgeError(diag.error);
+      throw e;
+    }
   }
   /**
    * Wait until the bridge is available and an object with the given testId or
@@ -240,173 +1044,1299 @@ var R3FFixture = class {
    * never stabilizes (e.g. async model loading, continuous animations).
    */
   async waitForObject(idOrUuid, options) {
-    return waitForObject(this._page, idOrUuid, options);
+    this._reporter.logBridgeWaiting();
+    try {
+      await waitForObject(this._page, idOrUuid, { ...options, canvasId: this.canvasId });
+      const meta = await this.getObject(idOrUuid);
+      if (meta) {
+        this._reporter.logObjectFound(idOrUuid, meta.type, meta.name || void 0);
+      }
+    } catch (e) {
+      const suggestions = await this._reporter.fetchFuzzyMatches(idOrUuid);
+      this._reporter.logObjectNotFound(idOrUuid, suggestions);
+      throw e;
+    }
   }
   /**
    * Wait until no object properties have changed for a number of consecutive
    * animation frames. Useful after triggering interactions or animations.
    */
   async waitForIdle(options) {
-    return waitForIdle(this._page, options);
+    return waitForIdle(this._page, { ...options, canvasId: this.canvasId });
+  }
+  /**
+   * 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, canvasId: this.canvasId });
+  }
+  /**
+   * Wait until an object (by testId or uuid) is no longer in the scene.
+   * Use for delete flows: trigger removal, then wait until the object is gone.
+   */
+  async waitForObjectRemoved(idOrUuid, options) {
+    return waitForObjectRemoved(this._page, idOrUuid, { ...options, canvasId: this.canvasId });
   }
   // -----------------------------------------------------------------------
   // Selection (for inspector integration)
   // -----------------------------------------------------------------------
   /** Select a 3D object by testId or uuid (highlights in scene). */
   async select(idOrUuid) {
-    await this._page.evaluate((id) => {
-      const api = window.__R3F_DOM__;
+    await this._page.evaluate(([id, cid]) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
       if (!api) throw new Error("react-three-dom bridge not found");
       api.select(id);
-    }, idOrUuid);
+    }, [idOrUuid, this.canvasId ?? null]);
   }
   /** Clear the current selection. */
   async clearSelection() {
-    await this._page.evaluate(() => {
-      const api = window.__R3F_DOM__;
+    await this._page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
       if (api) api.clearSelection();
-    });
+    }, this.canvasId ?? null);
+  }
+  // -----------------------------------------------------------------------
+  // Diagnostics
+  // -----------------------------------------------------------------------
+  /**
+   * Fetch full bridge diagnostics (version, object counts, GPU info, etc.).
+   * Returns null if the bridge is not available.
+   */
+  async getDiagnostics() {
+    return this._reporter.fetchDiagnostics();
+  }
+  /**
+   * Print a full diagnostics report to the terminal.
+   * Useful at the start of a test suite or when debugging failures.
+   */
+  async logDiagnostics() {
+    return this._reporter.logDiagnostics();
   }
 };
+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.extend({
   r3f: async ({ page }, use) => {
     const fixture = new R3FFixture(page);
     await use(fixture);
   }
 });
-var expect = expect$1.extend({
-  // -----------------------------------------------------------------------
-  // toExist — verify an object with the given testId/uuid exists in the scene
-  // -----------------------------------------------------------------------
-  async toExist(r3f, idOrUuid) {
-    const meta = await r3f.getObject(idOrUuid);
-    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`,
-      name: "toExist",
-      expected: idOrUuid,
-      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"
-      };
+function createR3FTest(options) {
+  return test$1.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, canvasId) {
+  return page.evaluate((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    return api ? api.getCount() : 0;
+  }, canvasId ?? null);
+}
+async function fetchCountByType(page, type, canvasId) {
+  return page.evaluate(([t, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    return api ? api.getCountByType(t) : 0;
+  }, [type, canvasId ?? null]);
+}
+async function fetchTotalTriangles(page, canvasId) {
+  return page.evaluate((cid) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : 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;
+  }, canvasId ?? null);
+}
+async function fetchMeta(page, id, canvasId) {
+  return page.evaluate(([i, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    if (!api) return null;
+    return api.getByTestId(i) ?? api.getByUuid(i) ?? null;
+  }, [id, canvasId ?? null]);
+}
+async function fetchInsp(page, id, canvasId) {
+  return page.evaluate(([i, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    if (!api) return null;
+    return api.inspect(i);
+  }, [id, canvasId ?? null]);
+}
+async function fetchWorldPosition(page, id, canvasId) {
+  return page.evaluate(([i, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    if (!api) return null;
+    const insp = api.inspect(i);
+    if (!insp || !insp.worldMatrix || insp.worldMatrix.length < 15) return null;
+    const m = insp.worldMatrix;
+    return [m[12], m[13], m[14]];
+  }, [id, canvasId ?? null]);
+}
+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
+  };
+}
+async function fetchFuzzyHints(page, query, canvasId) {
+  try {
+    const suggestions = await page.evaluate(
+      ({ q, cid }) => {
+        const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+        if (!api || typeof api.fuzzyFind !== "function") return [];
+        return api.fuzzyFind(q, 5).map((m) => ({
+          testId: m.testId,
+          name: m.name,
+          uuid: m.uuid
+        }));
+      },
+      { q: query, cid: canvasId ?? null }
+    );
+    if (suggestions.length === 0) return "";
+    return "\nDid you mean:\n" + suggestions.map((s) => {
+      const id = s.testId ? `testId="${s.testId}"` : `uuid="${s.uuid}"`;
+      return `  \u2192 ${s.name || "(unnamed)"} [${id}]`;
+    }).join("\n");
+  } catch {
+    return "";
+  }
+}
+async function fetchDiagnosticHint(page, canvasId) {
+  try {
+    const diag = await page.evaluate((cid) => {
+      const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+      if (!api || typeof api.getDiagnostics !== "function") return null;
+      return api.getDiagnostics();
+    }, canvasId ?? null);
+    if (!diag) return "";
+    return `
+Bridge: v${diag.version} ready=${diag.ready}, ${diag.objectCount} objects (${diag.meshCount} meshes)`;
+  } catch {
+    return "";
+  }
+}
+async function notFoundAsync(page, name, id, detail, timeout, canvasId) {
+  const [fuzzy, diag] = await Promise.all([
+    fetchFuzzyHints(page, id, canvasId),
+    fetchDiagnosticHint(page, canvasId)
+  ]);
+  return {
+    pass: false,
+    message: () => `Expected object "${id}" ${detail}, but it was not found (waited ${timeout}ms)${diag}${fuzzy}`,
+    name
+  };
+}
+var r3fMatchers = {
+  // ========================= 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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        return meta !== null;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
     }
-    const pass = meta.visible;
+    const pass = meta !== null;
     return {
       pass,
-      message: () => pass ? `Expected object "${idOrUuid}" to NOT be visible, but it is` : `Expected object "${idOrUuid}" to be visible, but visible=${meta.visible}`,
+      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: id,
+      actual: meta
+    };
+  },
+  // --- 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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        return meta?.visible ?? false;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toBeVisible", id, "to be visible", timeout, r3f.canvasId);
+    const m = meta;
+    return {
+      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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toHavePosition", id, `to have position [${expected}]`, timeout, r3f.canvasId);
+    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"
-      };
+  // --- toHaveWorldPosition ---
+  async toHaveWorldPosition(r3f, id, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.01);
+    const isNot = this.isNot;
+    let worldPos = null;
+    let pass = false;
+    let delta = [0, 0, 0];
+    try {
+      await expect.poll(async () => {
+        worldPos = await fetchWorldPosition(r3f.page, id, r3f.canvasId);
+        if (!worldPos) return false;
+        delta = [Math.abs(worldPos[0] - expected[0]), Math.abs(worldPos[1] - expected[1]), Math.abs(worldPos[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 (!worldPos) return notFoundAsync(r3f.page, "toHaveWorldPosition", id, `to have world position [${expected}]`, timeout, r3f.canvasId);
+    const actualWorldPos = worldPos;
     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 world position [${expected}] (\xB1${tolerance})` : `Expected "${id}" world position [${expected}] (\xB1${tolerance}), got [${actualWorldPos[0].toFixed(4)}, ${actualWorldPos[1].toFixed(4)}, ${actualWorldPos[2].toFixed(4)}] (\u0394 [${delta.map((d) => d.toFixed(4))}]) (waited ${timeout}ms)`,
+      name: "toHaveWorldPosition",
       expected,
-      actual: meta.position
+      actual: actualWorldPos
     };
   },
-  // -----------------------------------------------------------------------
-  // 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"
-      };
+  // --- 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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        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 { 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 notFoundAsync(r3f.page, "toHaveRotation", id, `to have rotation [${expected}]`, timeout, r3f.canvasId);
+    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 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: bounds
+      actual: m.rotation
     };
   },
-  // -----------------------------------------------------------------------
-  // 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"
-      };
+  // --- 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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        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 {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveScale", id, `to have scale [${expected}]`, timeout, r3f.canvasId);
+    const m = meta;
+    return {
+      pass,
+      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: m.scale
+    };
+  },
+  // --- 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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        if (!meta) return false;
+        pass = meta.type === expectedType;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveType", id, `to have type "${expectedType}"`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        if (!meta) return false;
+        pass = meta.name === expectedName;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveName", id, `to have name "${expectedName}"`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        if (!meta) return false;
+        pass = meta.geometryType === expectedGeo;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveGeometryType", id, `to have geometry "${expectedGeo}"`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        if (!meta) return false;
+        pass = meta.materialType === expectedMat;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveMaterialType", id, `to have material "${expectedMat}"`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        if (!meta) return false;
+        actual = meta.childrenUuids.length;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveChildCount", id, `to have ${expectedCount} children`, timeout, r3f.canvasId);
+    const pass = actual === expectedCount;
+    return {
+      pass,
+      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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        if (!meta?.parentUuid) return false;
+        parentMeta = await fetchMeta(r3f.page, meta.parentUuid, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toHaveParent", id, `to have parent "${expectedParent}"`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        actual = meta?.instanceCount ?? 0;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
     }
-    const actual = meta.instanceCount ?? 0;
+    if (!meta) return notFoundAsync(r3f.page, "toHaveInstanceCount", id, `to have instance count ${expectedCount}`, timeout, r3f.canvasId);
     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 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 expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toBeInFrustum", id, "to be in frustum", timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toHaveBounds", id, "to have specific bounds", timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toHaveColor", id, `to have color "${norm}"`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toHaveOpacity", id, `to have opacity ${expectedOpacity}`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id, r3f.canvasId);
+        if (!insp?.material) return false;
+        pass = insp.material.transparent === true;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!insp) return notFoundAsync(r3f.page, "toBeTransparent", id, "to be transparent", timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        actual = meta?.vertexCount ?? 0;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveVertexCount", id, `to have ${expectedCount} vertices`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        meta = await fetchMeta(r3f.page, id, r3f.canvasId);
+        actual = meta?.triangleCount ?? 0;
+        return actual === expectedCount;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    if (!meta) return notFoundAsync(r3f.page, "toHaveTriangleCount", id, `to have ${expectedCount} triangles`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toHaveUserData", id, `to have userData.${key}`, timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        insp = await fetchInsp(r3f.page, id, r3f.canvasId);
+        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 notFoundAsync(r3f.page, "toHaveMapTexture", id, "to have a map texture", timeout, r3f.canvasId);
+    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 expect.poll(async () => {
+        actual = await fetchSceneCount(r3f.page, r3f.canvasId);
+        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 expect.poll(async () => {
+        actual = await fetchSceneCount(r3f.page, r3f.canvasId);
+        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 expect.poll(async () => {
+        actual = await fetchCountByType(r3f.page, type, r3f.canvasId);
+        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 expect.poll(async () => {
+        actual = await fetchTotalTriangles(r3f.page, r3f.canvasId);
+        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 expect.poll(async () => {
+        actual = await fetchTotalTriangles(r3f.page, r3f.canvasId);
+        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
+    };
+  },
+  // ===================== CAMERA STATE ASSERTIONS ===========================
+  /**
+   * Assert the camera position is close to the expected [x, y, z].
+   *
+   * @example expect(r3f).toHaveCameraPosition([0, 5, 10], 0.1);
+   */
+  async toHaveCameraPosition(r3f, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.1);
+    const isNot = this.isNot;
+    let actual = [0, 0, 0];
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const cam = await r3f.page.evaluate((cid) => {
+          const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+          return api.getCameraState();
+        }, r3f.canvasId ?? null);
+        actual = cam.position;
+        pass = Math.abs(actual[0] - expected[0]) <= tolerance && Math.abs(actual[1] - expected[1]) <= tolerance && Math.abs(actual[2] - expected[2]) <= tolerance;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected camera NOT at [${expected}], but it is` : `Expected camera at [${expected}], got [${actual}] (tol=${tolerance}, waited ${timeout}ms)`,
+      name: "toHaveCameraPosition",
+      expected,
+      actual
+    };
+  },
+  /**
+   * Assert the camera field of view (PerspectiveCamera only).
+   *
+   * @example expect(r3f).toHaveCameraFov(75);
+   */
+  async toHaveCameraFov(r3f, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.1);
+    const isNot = this.isNot;
+    let actual;
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const cam = await r3f.page.evaluate((cid) => {
+          const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+          return api.getCameraState();
+        }, r3f.canvasId ?? null);
+        actual = cam.fov;
+        pass = actual !== void 0 && Math.abs(actual - expected) <= tolerance;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected camera NOT to have fov ${expected}, but it does` : `Expected camera fov ${expected}, got ${actual ?? "N/A"} (tol=${tolerance}, waited ${timeout}ms)`,
+      name: "toHaveCameraFov",
+      expected,
+      actual
+    };
+  },
+  /**
+   * Assert the camera near clipping plane.
+   *
+   * @example expect(r3f).toHaveCameraNear(0.1);
+   */
+  async toHaveCameraNear(r3f, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.01);
+    const isNot = this.isNot;
+    let actual = 0;
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const cam = await r3f.page.evaluate((cid) => {
+          const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+          return api.getCameraState();
+        }, r3f.canvasId ?? null);
+        actual = cam.near;
+        pass = Math.abs(actual - expected) <= tolerance;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected camera near NOT ${expected}, but it is` : `Expected camera near ${expected}, got ${actual} (tol=${tolerance}, waited ${timeout}ms)`,
+      name: "toHaveCameraNear",
+      expected,
+      actual
+    };
+  },
+  /**
+   * Assert the camera far clipping plane.
+   *
+   * @example expect(r3f).toHaveCameraFar(1000);
+   */
+  async toHaveCameraFar(r3f, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 1);
+    const isNot = this.isNot;
+    let actual = 0;
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const cam = await r3f.page.evaluate((cid) => {
+          const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+          return api.getCameraState();
+        }, r3f.canvasId ?? null);
+        actual = cam.far;
+        pass = Math.abs(actual - expected) <= tolerance;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected camera far NOT ${expected}, but it is` : `Expected camera far ${expected}, got ${actual} (tol=${tolerance}, waited ${timeout}ms)`,
+      name: "toHaveCameraFar",
+      expected,
+      actual
+    };
+  },
+  /**
+   * Assert the camera zoom level.
+   *
+   * @example expect(r3f).toHaveCameraZoom(1);
+   */
+  async toHaveCameraZoom(r3f, expected, tolOpts) {
+    const { timeout, interval, tolerance } = parseTol(tolOpts, 0.01);
+    const isNot = this.isNot;
+    let actual = 0;
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const cam = await r3f.page.evaluate((cid) => {
+          const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+          return api.getCameraState();
+        }, r3f.canvasId ?? null);
+        actual = cam.zoom;
+        pass = Math.abs(actual - expected) <= tolerance;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected camera zoom NOT ${expected}, but it is` : `Expected camera zoom ${expected}, got ${actual} (tol=${tolerance}, waited ${timeout}ms)`,
+      name: "toHaveCameraZoom",
+      expected,
+      actual
+    };
+  },
+  // ======================== BATCH ASSERTIONS ==============================
+  /**
+   * Assert that ALL given objects exist in the scene.
+   * Accepts an array of testIds/uuids or a glob pattern (e.g. "wall-*").
+   *
+   * @example expect(r3f).toAllExist(['wall-1', 'wall-2', 'floor']);
+   * @example expect(r3f).toAllExist('wall-*');
+   */
+  async toAllExist(r3f, idsOrPattern, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let missing = [];
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const ids = typeof idsOrPattern === "string" ? await resolvePattern(r3f.page, idsOrPattern, r3f.canvasId) : idsOrPattern;
+        missing = [];
+        for (const id of ids) {
+          const m = await r3f.getObject(id);
+          if (!m) missing.push(id);
+        }
+        pass = missing.length === 0 && ids.length > 0;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected some objects to NOT exist, but all do` : `Objects not found: [${missing.join(", ")}] (waited ${timeout}ms)`,
+      name: "toAllExist",
+      expected: idsOrPattern,
+      actual: { missing }
+    };
+  },
+  /**
+   * Assert that ALL given objects are visible.
+   *
+   * @example expect(r3f).toAllBeVisible(['wall-1', 'wall-2', 'floor']);
+   * @example expect(r3f).toAllBeVisible('wall-*');
+   */
+  async toAllBeVisible(r3f, idsOrPattern, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let hidden = [];
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const ids = typeof idsOrPattern === "string" ? await resolvePattern(r3f.page, idsOrPattern, r3f.canvasId) : idsOrPattern;
+        hidden = [];
+        for (const id of ids) {
+          const m = await r3f.getObject(id);
+          if (!m || !m.visible) hidden.push(id);
+        }
+        pass = hidden.length === 0 && ids.length > 0;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected some objects to NOT be visible, but all are` : `Objects not visible: [${hidden.join(", ")}] (waited ${timeout}ms)`,
+      name: "toAllBeVisible",
+      expected: idsOrPattern,
+      actual: { hidden }
+    };
+  },
+  /**
+   * Assert that NONE of the given objects exist in the scene.
+   *
+   * @example expect(r3f).toNoneExist(['deleted-wall', 'old-floor']);
+   * @example expect(r3f).toNoneExist('temp-*');
+   */
+  async toNoneExist(r3f, idsOrPattern, opts) {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const interval = opts?.interval ?? DEFAULT_INTERVAL;
+    const isNot = this.isNot;
+    let found = [];
+    let pass = false;
+    try {
+      await expect.poll(async () => {
+        const ids = typeof idsOrPattern === "string" ? await resolvePattern(r3f.page, idsOrPattern, r3f.canvasId) : idsOrPattern;
+        found = [];
+        for (const id of ids) {
+          const m = await r3f.getObject(id);
+          if (m) found.push(id);
+        }
+        pass = found.length === 0;
+        return pass;
+      }, { timeout, intervals: [interval] }).toBe(!isNot);
+    } catch {
+    }
+    return {
+      pass,
+      message: () => pass ? `Expected some objects to exist, but none do` : `Objects still exist: [${found.join(", ")}] (waited ${timeout}ms)`,
+      name: "toNoneExist",
+      expected: idsOrPattern,
+      actual: { found }
+    };
   }
-});
+};
+async function resolvePattern(page, pattern, canvasId) {
+  return page.evaluate(([p, cid]) => {
+    const api = cid ? window.__R3F_DOM_INSTANCES__?.[cid] : window.__R3F_DOM__;
+    if (!api) return [];
+    const snap = api.snapshot();
+    const ids = [];
+    const regex = new RegExp("^" + p.replace(/\*/g, ".*").replace(/\?/g, ".") + "$");
+    function walk(node) {
+      const testId = node.testId ?? node.name;
+      if (regex.test(testId) || regex.test(node.uuid)) ids.push(testId || node.uuid);
+      for (const child of node.children ?? []) walk(child);
+    }
+    walk(snap.tree);
+    return ids;
+  }, [pattern, canvasId ?? null]);
+}
+
+// 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;
+}
 
-export { R3FFixture, click, contextMenu, doubleClick, drag, expect, hover, pointerMiss, test, waitForIdle, waitForObject, waitForSceneReady, wheel };
+export { R3FFixture, R3FReporter, circlePath, click, contextMenu, createR3FTest, curvePath, diffSnapshots, doubleClick, drag, drawPathOnCanvas, getCameraState, hover, linePath, pointerMiss, r3fMatchers, rectPath, test, unhover, waitForIdle, waitForNewObject, waitForObject, waitForObjectRemoved, waitForSceneReady, wheel };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map