@react-three-dom/cypress 0.1.1 → 0.3.0

package/dist/index.cjs

@@ -1,65 +1,504 @@
 'use strict';
 
+// 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 [, node] of afterMap) {
+    if (!beforeMap.has(node.uuid)) added.push(node);
+  }
+  for (const [, node] of beforeMap) {
+    if (!afterMap.has(node.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/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}`;
+}
+function registerR3FTasks(on) {
+  on("task", {
+    r3fLog(message) {
+      process.stdout.write(message + "\n");
+      return null;
+    }
+  });
+}
+var _enabled = true;
+function termLog(message) {
+  if (!_enabled) return;
+  cy.task("r3fLog", message, { log: false });
+}
+function cmdLog(name, message, props) {
+  Cypress.log({
+    name,
+    message,
+    consoleProps: () => props ?? {}
+  });
+}
+function getAPI(win) {
+  return win.__R3F_DOM__ ?? null;
+}
+var R3FReporter = class {
+  constructor(enabled = true) {
+    _enabled = enabled;
+  }
+  enable() {
+    _enabled = true;
+  }
+  disable() {
+    _enabled = false;
+  }
+  // ---- Lifecycle ----
+  logBridgeWaiting() {
+    termLog(info("Waiting for bridge (window.__R3F_DOM__)..."));
+    cmdLog("r3f", "Waiting for bridge...");
+  }
+  logBridgeConnected(diag) {
+    if (diag) {
+      termLog(ok(`Bridge connected \u2014 v${diag.version}, ${diag.objectCount} objects, ${diag.meshCount} meshes`));
+      termLog(info(`  Canvas: ${diag.canvasWidth}\xD7${diag.canvasHeight}  GPU: ${diag.webglRenderer}`));
+      termLog(info(`  DOM nodes: ${diag.materializedDomNodes}/${diag.maxDomNodes}  Dirty queue: ${diag.dirtyQueueSize}`));
+      cmdLog("r3f", `Bridge connected v${diag.version} \u2014 ${diag.objectCount} objects`, { diagnostics: diag });
+    } else {
+      termLog(ok("Bridge connected"));
+      cmdLog("r3f", "Bridge connected");
+    }
+  }
+  logBridgeError(error) {
+    termLog(fail(`Bridge error: ${error}`));
+    cmdLog("r3f", `Bridge error: ${error}`);
+  }
+  logSceneReady(objectCount) {
+    termLog(ok(`Scene ready \u2014 ${objectCount} objects stabilized`));
+    cmdLog("r3f", `Scene ready \u2014 ${objectCount} objects`);
+  }
+  logObjectFound(idOrUuid, type, name) {
+    const label = name ? `"${name}" (${type})` : type;
+    termLog(ok(`Object found: "${idOrUuid}" \u2192 ${label}`));
+    cmdLog("r3f", `Object found: "${idOrUuid}" \u2192 ${label}`);
+  }
+  logObjectNotFound(idOrUuid, suggestions) {
+    termLog(fail(`Object not found: "${idOrUuid}"`));
+    if (suggestions && suggestions.length > 0) {
+      termLog(warn("Did you mean:"));
+      for (const s of suggestions.slice(0, 5)) {
+        const id = s.testId ? `testId="${s.testId}"` : `uuid="${s.uuid}"`;
+        termLog(info(`  \u2192 ${s.name || "(unnamed)"} [${id}]`));
+      }
+    }
+    cmdLog("r3f", `Object not found: "${idOrUuid}"`, { suggestions });
+  }
+  // ---- Interactions ----
+  logInteraction(action, idOrUuid, extra) {
+    const suffix = extra ? ` ${extra}` : "";
+    termLog(info(`${action}("${idOrUuid}")${suffix}`));
+  }
+  logInteractionDone(action, idOrUuid, durationMs) {
+    termLog(ok(`${action}("${idOrUuid}") \u2014 ${durationMs}ms`));
+  }
+  // ---- Assertions ----
+  logAssertionFailure(matcherName, id, detail, diag) {
+    termLog(heading(`Assertion failed: ${matcherName}("${id}")`));
+    termLog(fail(detail));
+    if (diag) {
+      this._printDiagnosticsSummary(diag);
+    }
+  }
+  // ---- Diagnostics ----
+  logDiagnostics() {
+    return cy.window({ log: false }).then((win) => {
+      const api = getAPI(win);
+      if (!api || typeof api.getDiagnostics !== "function") {
+        termLog(fail("Cannot fetch diagnostics \u2014 bridge not available"));
+        return;
+      }
+      const d = api.getDiagnostics();
+      termLog(heading("Bridge Diagnostics"));
+      this._printDiagnosticsFull(d);
+      cmdLog("r3fDiagnostics", `v${d.version} ${d.objectCount} objects`, { diagnostics: d });
+    });
+  }
+  fetchDiagnostics() {
+    return cy.window({ log: false }).then((win) => {
+      const api = getAPI(win);
+      if (!api || typeof api.getDiagnostics !== "function") return null;
+      return api.getDiagnostics();
+    });
+  }
+  fetchFuzzyMatches(query, limit = 5) {
+    return cy.window({ log: false }).then((win) => {
+      const api = getAPI(win);
+      if (!api || typeof api.fuzzyFind !== "function") return [];
+      return api.fuzzyFind(query, limit).map((m) => ({
+        testId: m.testId,
+        name: m.name,
+        uuid: m.uuid
+      }));
+    });
+  }
+  // ---- Private formatting ----
+  _printDiagnosticsSummary(d) {
+    termLog(info(`  Bridge: v${d.version} ready=${d.ready}${d.error ? ` error="${d.error}"` : ""}`));
+    termLog(info(`  Scene: ${d.objectCount} objects (${d.meshCount} meshes, ${d.groupCount} groups, ${d.lightCount} lights)`));
+    termLog(info(`  Canvas: ${d.canvasWidth}\xD7${d.canvasHeight}  GPU: ${d.webglRenderer}`));
+  }
+  _printDiagnosticsFull(d) {
+    const status = d.ready ? `${GREEN}READY${RESET}` : `${RED}NOT READY${RESET}`;
+    termLog(`  ${BOLD}Status:${RESET}    ${status}  v${d.version}`);
+    if (d.error) termLog(`  ${BOLD}Error:${RESET}     ${RED}${d.error}${RESET}`);
+    termLog(`  ${BOLD}Objects:${RESET}   ${d.objectCount} total`);
+    termLog(`             ${d.meshCount} meshes, ${d.groupCount} groups, ${d.lightCount} lights, ${d.cameraCount} cameras`);
+    termLog(`  ${BOLD}DOM:${RESET}       ${d.materializedDomNodes}/${d.maxDomNodes} materialized`);
+    termLog(`  ${BOLD}Canvas:${RESET}    ${d.canvasWidth}\xD7${d.canvasHeight}`);
+    termLog(`  ${BOLD}GPU:${RESET}       ${d.webglRenderer}`);
+    termLog(`  ${BOLD}Dirty:${RESET}     ${d.dirtyQueueSize} queued updates`);
+  }
+};
+
+// src/reporterState.ts
+var _reporter = null;
+function _setReporter(r) {
+  _reporter = r;
+}
+function _getReporter() {
+  return _reporter;
+}
+
 // src/commands.ts
+var _activeCanvasId = null;
+function _getActiveCanvasId() {
+  return _activeCanvasId;
+}
 function getR3F(win) {
-  const api = win.__R3F_DOM__;
+  const w = win;
+  const api = _activeCanvasId ? w.__R3F_DOM_INSTANCES__?.[_activeCanvasId] : w.__R3F_DOM__;
   if (!api) {
     throw new Error(
-      "react-three-dom bridge not found. Is <ThreeDom> mounted in your app?"
+      `react-three-dom bridge not found${_activeCanvasId ? ` (canvas: "${_activeCanvasId}")` : ""}. Is <ThreeDom${_activeCanvasId ? ` canvasId="${_activeCanvasId}"` : ""}> mounted in your app?`
     );
   }
   return api;
 }
+var AUTO_WAIT_TIMEOUT = 5e3;
+var AUTO_WAIT_POLL_MS = 100;
+function resolveApi(win) {
+  const w = win;
+  return _activeCanvasId ? w.__R3F_DOM_INSTANCES__?.[_activeCanvasId] : w.__R3F_DOM__;
+}
+function autoWaitForBridge(timeout = AUTO_WAIT_TIMEOUT) {
+  const deadline = Date.now() + timeout;
+  function poll() {
+    return cy.window({ log: false }).then((win) => {
+      const api = resolveApi(win);
+      if (api && api._ready) return api;
+      if (api && !api._ready && api._error) {
+        throw new Error(
+          `[react-three-dom] Bridge initialization failed: ${api._error}`
+        );
+      }
+      if (Date.now() > deadline) {
+        throw new Error(
+          `[react-three-dom] Auto-wait timed out after ${timeout}ms: bridge not ready${_activeCanvasId ? ` (canvas: "${_activeCanvasId}")` : ""}.
+Ensure <ThreeDom${_activeCanvasId ? ` canvasId="${_activeCanvasId}"` : ""}> is mounted inside your <Canvas> component.`
+        );
+      }
+      return cy.wait(AUTO_WAIT_POLL_MS, { log: false }).then(() => poll());
+    });
+  }
+  return poll();
+}
+function autoWaitForObject(idOrUuid, timeout = AUTO_WAIT_TIMEOUT) {
+  const deadline = Date.now() + timeout;
+  function poll() {
+    return cy.window({ log: false }).then((win) => {
+      const api = resolveApi(win);
+      if (!api) {
+        if (Date.now() > deadline) {
+          throw new Error(
+            `[react-three-dom] Auto-wait timed out after ${timeout}ms: bridge not found${_activeCanvasId ? ` (canvas: "${_activeCanvasId}")` : ""}.`
+          );
+        }
+        return cy.wait(AUTO_WAIT_POLL_MS, { log: false }).then(() => poll());
+      }
+      if (!api._ready && api._error) {
+        throw new Error(
+          `[react-three-dom] Bridge initialization failed: ${api._error}`
+        );
+      }
+      if (api._ready) {
+        const found = (api.getByTestId(idOrUuid) ?? api.getByUuid(idOrUuid)) !== null;
+        if (found) return api;
+      }
+      if (Date.now() > deadline) {
+        let msg = `[react-three-dom] Auto-wait timed out after ${timeout}ms: object "${idOrUuid}" not found${_activeCanvasId ? ` (canvas: "${_activeCanvasId}")` : ""}.
+Bridge: ready=${api._ready}, objectCount=${api.getCount()}.
+Ensure the object has userData.testId="${idOrUuid}" or uuid="${idOrUuid}".`;
+        if (typeof api.fuzzyFind === "function") {
+          const suggestions = api.fuzzyFind(idOrUuid, 5);
+          if (suggestions.length > 0) {
+            msg += "\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");
+          }
+        }
+        throw new Error(msg);
+      }
+      return cy.wait(AUTO_WAIT_POLL_MS, { log: false }).then(() => poll());
+    });
+  }
+  return poll();
+}
+function formatCypressSceneTree(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 += formatCypressSceneTree(child, childPrefix, last);
+  }
+  return result;
+}
 function registerCommands() {
-  Cypress.Commands.add("r3fClick", (idOrUuid) => {
+  Cypress.Commands.add("r3fUseCanvas", (canvasId) => {
+    _activeCanvasId = canvasId;
+    Cypress.log({
+      name: "r3fUseCanvas",
+      message: canvasId ? `Switched to canvas "${canvasId}"` : "Switched to default canvas"
+    });
+  });
+  Cypress.Commands.add("r3fGetCanvasIds", () => {
+    return cy.window({ log: false }).then((win) => {
+      const instances = win.__R3F_DOM_INSTANCES__;
+      return instances ? Object.keys(instances) : [];
+    });
+  });
+  Cypress.Commands.add("r3fEnableReporter", (enabled = true) => {
+    if (enabled) {
+      _setReporter(new R3FReporter(true));
+    } else {
+      _setReporter(null);
+    }
+  });
+  Cypress.Commands.add("r3fEnableDebug", () => {
     cy.window({ log: false }).then((win) => {
-      getR3F(win).click(idOrUuid);
+      win.__R3F_DOM_DEBUG__ = true;
+    });
+    Cypress.on("window:before:load", (win) => {
+      const origLog = win.console.log;
+      win.console.log = (...args) => {
+        origLog.apply(win.console, args);
+        const text = String(args[0]);
+        if (text.startsWith("[r3f-dom:")) {
+          Cypress.log({
+            name: "r3f-dom",
+            message: args.slice(1).map(String).join(" "),
+            consoleProps: () => ({ raw: args })
+          });
+        }
+      };
+    });
+  });
+  Cypress.Commands.add("r3fClick", (idOrUuid) => {
+    const reporter = _getReporter();
+    const t0 = Date.now();
+    reporter?.logInteraction("click", idOrUuid);
+    return autoWaitForObject(idOrUuid).then((api) => {
+      api.click(idOrUuid);
+      reporter?.logInteractionDone("click", idOrUuid, Date.now() - t0);
     });
   });
   Cypress.Commands.add("r3fDoubleClick", (idOrUuid) => {
-    cy.window({ log: false }).then((win) => {
-      getR3F(win).doubleClick(idOrUuid);
+    const reporter = _getReporter();
+    const t0 = Date.now();
+    reporter?.logInteraction("doubleClick", idOrUuid);
+    return autoWaitForObject(idOrUuid).then((api) => {
+      api.doubleClick(idOrUuid);
+      reporter?.logInteractionDone("doubleClick", idOrUuid, Date.now() - t0);
     });
   });
   Cypress.Commands.add("r3fContextMenu", (idOrUuid) => {
-    cy.window({ log: false }).then((win) => {
-      getR3F(win).contextMenu(idOrUuid);
+    const reporter = _getReporter();
+    const t0 = Date.now();
+    reporter?.logInteraction("contextMenu", idOrUuid);
+    return autoWaitForObject(idOrUuid).then((api) => {
+      api.contextMenu(idOrUuid);
+      reporter?.logInteractionDone("contextMenu", idOrUuid, Date.now() - t0);
     });
   });
   Cypress.Commands.add("r3fHover", (idOrUuid) => {
-    cy.window({ log: false }).then((win) => {
-      getR3F(win).hover(idOrUuid);
+    const reporter = _getReporter();
+    const t0 = Date.now();
+    reporter?.logInteraction("hover", idOrUuid);
+    return autoWaitForObject(idOrUuid).then((api) => {
+      api.hover(idOrUuid);
+      reporter?.logInteractionDone("hover", idOrUuid, Date.now() - t0);
+    });
+  });
+  Cypress.Commands.add("r3fUnhover", () => {
+    const reporter = _getReporter();
+    const t0 = Date.now();
+    reporter?.logInteraction("unhover", "(canvas)");
+    return autoWaitForBridge().then((api) => {
+      api.unhover();
+      reporter?.logInteractionDone("unhover", "(canvas)", Date.now() - t0);
     });
   });
   Cypress.Commands.add(
     "r3fDrag",
     (idOrUuid, delta) => {
-      cy.window({ log: false }).then((win) => {
-        getR3F(win).drag(idOrUuid, delta);
+      return autoWaitForObject(idOrUuid).then((api) => {
+        return Cypress.Promise.resolve(api.drag(idOrUuid, delta));
       });
     }
   );
   Cypress.Commands.add(
     "r3fWheel",
     (idOrUuid, options) => {
-      cy.window({ log: false }).then((win) => {
-        getR3F(win).wheel(idOrUuid, options);
+      return autoWaitForObject(idOrUuid).then((api) => {
+        api.wheel(idOrUuid, options);
       });
     }
   );
   Cypress.Commands.add("r3fPointerMiss", () => {
-    cy.window({ log: false }).then((win) => {
-      getR3F(win).pointerMiss();
+    return autoWaitForBridge().then((api) => {
+      api.pointerMiss();
     });
   });
   Cypress.Commands.add("r3fSelect", (idOrUuid) => {
-    cy.window({ log: false }).then((win) => {
-      getR3F(win).select(idOrUuid);
+    return autoWaitForObject(idOrUuid).then((api) => {
+      api.select(idOrUuid);
     });
   });
   Cypress.Commands.add("r3fClearSelection", () => {
-    cy.window({ log: false }).then((win) => {
-      getR3F(win).clearSelection();
+    return autoWaitForBridge().then((api) => {
+      api.clearSelection();
+    });
+  });
+  Cypress.Commands.add(
+    "r3fDrawPath",
+    (points, options) => {
+      return autoWaitForBridge().then((api) => {
+        return Cypress.Promise.resolve(api.drawPath(points, options));
+      });
+    }
+  );
+  Cypress.Commands.add("r3fLogScene", () => {
+    return cy.window({ log: false }).then((win) => {
+      const api = getR3F(win);
+      const snap = api.snapshot();
+      const lines = formatCypressSceneTree(snap.tree);
+      const output = `Scene tree (${snap.objectCount} objects):
+${lines}`;
+      Cypress.log({
+        name: "r3fLogScene",
+        message: `${snap.objectCount} objects`,
+        consoleProps: () => ({ snapshot: snap, tree: output })
+      });
+      console.log(`[r3f-dom] ${output}`);
+    });
+  });
+  Cypress.Commands.add("r3fGetDiagnostics", () => {
+    return cy.window({ log: false }).then((win) => {
+      const api = getR3F(win);
+      if (typeof api.getDiagnostics !== "function") return null;
+      return api.getDiagnostics();
+    });
+  });
+  Cypress.Commands.add("r3fLogDiagnostics", () => {
+    return cy.window({ log: false }).then((win) => {
+      const api = getR3F(win);
+      if (typeof api.getDiagnostics !== "function") {
+        Cypress.log({ name: "r3fLogDiagnostics", message: "getDiagnostics not available" });
+        return;
+      }
+      const d = api.getDiagnostics();
+      const lines = [
+        `Bridge Diagnostics`,
+        `  Status:    ${d.ready ? "READY" : "NOT READY"}  v${d.version}`,
+        d.error ? `  Error:     ${d.error}` : null,
+        `  Objects:   ${d.objectCount} total`,
+        `             ${d.meshCount} meshes, ${d.groupCount} groups, ${d.lightCount} lights, ${d.cameraCount} cameras`,
+        `  DOM:       ${d.materializedDomNodes}/${d.maxDomNodes} materialized`,
+        `  Canvas:    ${d.canvasWidth}\xD7${d.canvasHeight}`,
+        `  GPU:       ${d.webglRenderer}`,
+        `  Dirty:     ${d.dirtyQueueSize} queued updates`
+      ].filter(Boolean).join("\n");
+      Cypress.log({
+        name: "r3fLogDiagnostics",
+        message: `v${d.version} ${d.objectCount} objects`,
+        consoleProps: () => ({ diagnostics: d, formatted: lines })
+      });
+      console.log(`[r3f-dom] ${lines}`);
     });
   });
   Cypress.Commands.add("r3fGetObject", (idOrUuid) => {
@@ -68,6 +507,58 @@ function registerCommands() {
       return api.getByTestId(idOrUuid) ?? api.getByUuid(idOrUuid) ?? null;
     });
   });
+  Cypress.Commands.add("r3fGetByTestId", (testId) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getByTestId(testId);
+    });
+  });
+  Cypress.Commands.add("r3fGetByName", (name) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getByName(name);
+    });
+  });
+  Cypress.Commands.add("r3fGetByUuid", (uuid) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getByUuid(uuid);
+    });
+  });
+  Cypress.Commands.add("r3fGetChildren", (idOrUuid) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getChildren(idOrUuid);
+    });
+  });
+  Cypress.Commands.add("r3fGetParent", (idOrUuid) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getParent(idOrUuid);
+    });
+  });
+  Cypress.Commands.add("r3fGetCanvas", () => {
+    return cy.get("[data-r3f-canvas]");
+  });
+  Cypress.Commands.add("r3fGetWorldPosition", (idOrUuid) => {
+    return cy.window({ log: false }).then((win) => {
+      const api = getR3F(win);
+      const insp = api.inspect(idOrUuid);
+      if (!insp?.worldMatrix || insp.worldMatrix.length < 15) return null;
+      const m = insp.worldMatrix;
+      return [m[12], m[13], m[14]];
+    });
+  });
+  Cypress.Commands.add("r3fDiffSnapshots", (before, after) => {
+    return cy.wrap(diffSnapshots(before, after), { log: false });
+  });
+  Cypress.Commands.add("r3fTrackObjectCount", (action) => {
+    return cy.window({ log: false }).then((win) => {
+      const before = getR3F(win).snapshot();
+      return action().then(
+        () => cy.window({ log: false }).then((w) => {
+          const after = getR3F(w).snapshot();
+          const d = diffSnapshots(before, after);
+          return { added: d.added.length, removed: d.removed.length };
+        })
+      );
+    });
+  });
   Cypress.Commands.add("r3fInspect", (idOrUuid) => {
     return cy.window({ log: false }).then((win) => {
       return getR3F(win).inspect(idOrUuid);
@@ -83,20 +574,101 @@ function registerCommands() {
       return getR3F(win).getCount();
     });
   });
+  Cypress.Commands.add("r3fGetByType", (type) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getByType(type);
+    });
+  });
+  Cypress.Commands.add("r3fGetByUserData", (key, value) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getByUserData(key, value);
+    });
+  });
+  Cypress.Commands.add("r3fGetCountByType", (type) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getCountByType(type);
+    });
+  });
+  Cypress.Commands.add("r3fGetObjects", (ids) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getObjects(ids);
+    });
+  });
+  Cypress.Commands.add("r3fGetByGeometryType", (type) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getByGeometryType(type);
+    });
+  });
+  Cypress.Commands.add("r3fGetByMaterialType", (type) => {
+    return cy.window({ log: false }).then((win) => {
+      return getR3F(win).getByMaterialType(type);
+    });
+  });
+  Cypress.Commands.add("r3fFuzzyFind", (query, limit) => {
+    return cy.window({ log: false }).then((win) => {
+      const api = getR3F(win);
+      if (typeof api.fuzzyFind !== "function") return [];
+      return api.fuzzyFind(query, limit);
+    });
+  });
+  Cypress.Commands.add("r3fGetCameraState", () => {
+    return cy.window({ log: false }).then((win) => {
+      const api = getR3F(win);
+      return api.getCameraState();
+    });
+  });
 }
 
 // src/assertions.ts
 function getR3FFromWindow() {
   const win = cy.state("window");
-  const api = win?.__R3F_DOM__;
+  const cid = _getActiveCanvasId();
+  const api = cid ? win?.__R3F_DOM_INSTANCES__?.[cid] : win?.__R3F_DOM__;
   if (!api) {
-    throw new Error("react-three-dom bridge not found. Is <ThreeDom> mounted?");
+    throw new Error(
+      `react-three-dom bridge not found${cid ? ` (canvas: "${cid}")` : ""}. Is <ThreeDom${cid ? ` canvasId="${cid}"` : ""}> mounted?`
+    );
   }
   return api;
 }
 function resolveObject(api, idOrUuid) {
   return api.getByTestId(idOrUuid) ?? api.getByUuid(idOrUuid) ?? null;
 }
+function requireObject(api, idOrUuid, matcherName) {
+  const meta = resolveObject(api, idOrUuid);
+  if (!meta) {
+    let msg = `[${matcherName}] 3D object "${idOrUuid}" not found in the scene`;
+    if (typeof api.fuzzyFind === "function") {
+      const suggestions = api.fuzzyFind(idOrUuid, 5);
+      if (suggestions.length > 0) {
+        msg += "\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");
+      }
+    }
+    throw new Error(msg);
+  }
+  return meta;
+}
+function requireInspection(api, idOrUuid, matcherName) {
+  const insp = api.inspect(idOrUuid);
+  if (!insp) {
+    throw new Error(`[${matcherName}] 3D object "${idOrUuid}" not found for inspection`);
+  }
+  return insp;
+}
+function collectTriangles(api) {
+  const snap = api.snapshot();
+  let total = 0;
+  function walk(node) {
+    const meta = api.getByUuid(node.uuid);
+    if (meta?.triangleCount) total += meta.triangleCount;
+    for (const child of node.children) walk(child);
+  }
+  walk(snap.tree);
+  return total;
+}
 function registerAssertions() {
   chai.use((_chai) => {
     const { Assertion } = _chai;
@@ -113,97 +685,480 @@ function registerAssertions() {
     });
     Assertion.addMethod("r3fVisible", function(idOrUuid) {
       const api = getR3FFromWindow();
-      const meta = resolveObject(api, idOrUuid);
-      if (!meta) {
-        throw new Error(`3D object "${idOrUuid}" not found in the scene`);
-      }
+      const meta = requireObject(api, idOrUuid, "r3fVisible");
       this.assert(
         meta.visible,
-        `expected 3D object "${idOrUuid}" to be visible`,
-        `expected 3D object "${idOrUuid}" to NOT be visible`,
+        `expected "${idOrUuid}" to be visible`,
+        `expected "${idOrUuid}" to NOT be visible`,
         true,
         meta.visible
       );
     });
-    Assertion.addMethod("r3fInFrustum", function(idOrUuid) {
+    Assertion.addMethod("r3fPosition", function(idOrUuid, expected, tolerance = 0.01) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fPosition");
+      const pass = expected.every((v, i) => Math.abs(meta.position[i] - v) <= tolerance);
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" at [${expected}] (\xB1${tolerance}), got [${meta.position}]`,
+        `expected "${idOrUuid}" to NOT be at [${expected}] (\xB1${tolerance})`,
+        expected,
+        meta.position
+      );
+    });
+    Assertion.addMethod("r3fWorldPosition", function(idOrUuid, expected, tolerance = 0.01) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fWorldPosition");
+      const m = insp.worldMatrix;
+      const wp = [m[12], m[13], m[14]];
+      const pass = expected.every((v, i) => Math.abs(wp[i] - v) <= tolerance);
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" world position [${expected}] (\xB1${tolerance}), got [${wp.map((v) => v.toFixed(4))}]`,
+        `expected "${idOrUuid}" to NOT have world position [${expected}] (\xB1${tolerance})`,
+        expected,
+        wp
+      );
+    });
+    Assertion.addMethod("r3fRotation", function(idOrUuid, expected, tolerance = 0.01) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fRotation");
+      const pass = expected.every((v, i) => Math.abs(meta.rotation[i] - v) <= tolerance);
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" rotation [${expected}] (\xB1${tolerance}), got [${meta.rotation}]`,
+        `expected "${idOrUuid}" to NOT have rotation [${expected}] (\xB1${tolerance})`,
+        expected,
+        meta.rotation
+      );
+    });
+    Assertion.addMethod("r3fScale", function(idOrUuid, expected, tolerance = 0.01) {
       const api = getR3FFromWindow();
-      const inspection = api.inspect(idOrUuid);
-      if (!inspection) {
-        throw new Error(`3D object "${idOrUuid}" not found in the scene`);
+      const meta = requireObject(api, idOrUuid, "r3fScale");
+      const pass = expected.every((v, i) => Math.abs(meta.scale[i] - v) <= tolerance);
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" scale [${expected}] (\xB1${tolerance}), got [${meta.scale}]`,
+        `expected "${idOrUuid}" to NOT have scale [${expected}] (\xB1${tolerance})`,
+        expected,
+        meta.scale
+      );
+    });
+    Assertion.addMethod("r3fType", function(idOrUuid, expectedType) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fType");
+      this.assert(
+        meta.type === expectedType,
+        `expected "${idOrUuid}" type "${expectedType}", got "${meta.type}"`,
+        `expected "${idOrUuid}" to NOT have type "${expectedType}"`,
+        expectedType,
+        meta.type
+      );
+    });
+    Assertion.addMethod("r3fName", function(idOrUuid, expectedName) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fName");
+      this.assert(
+        meta.name === expectedName,
+        `expected "${idOrUuid}" name "${expectedName}", got "${meta.name}"`,
+        `expected "${idOrUuid}" to NOT have name "${expectedName}"`,
+        expectedName,
+        meta.name
+      );
+    });
+    Assertion.addMethod("r3fGeometryType", function(idOrUuid, expectedGeo) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fGeometryType");
+      this.assert(
+        meta.geometryType === expectedGeo,
+        `expected "${idOrUuid}" geometry "${expectedGeo}", got "${meta.geometryType ?? "none"}"`,
+        `expected "${idOrUuid}" to NOT have geometry "${expectedGeo}"`,
+        expectedGeo,
+        meta.geometryType
+      );
+    });
+    Assertion.addMethod("r3fMaterialType", function(idOrUuid, expectedMat) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fMaterialType");
+      this.assert(
+        meta.materialType === expectedMat,
+        `expected "${idOrUuid}" material "${expectedMat}", got "${meta.materialType ?? "none"}"`,
+        `expected "${idOrUuid}" to NOT have material "${expectedMat}"`,
+        expectedMat,
+        meta.materialType
+      );
+    });
+    Assertion.addMethod("r3fChildCount", function(idOrUuid, expectedCount) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fChildCount");
+      const actual = meta.childrenUuids.length;
+      this.assert(
+        actual === expectedCount,
+        `expected "${idOrUuid}" ${expectedCount} children, got ${actual}`,
+        `expected "${idOrUuid}" to NOT have ${expectedCount} children`,
+        expectedCount,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fParent", function(idOrUuid, expectedParent) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fParent");
+      if (!meta.parentUuid) {
+        throw new Error(`[r3fParent] "${idOrUuid}" has no parent (is scene root)`);
       }
-      const { bounds } = inspection;
-      const isFinite = (v) => v.every(Number.isFinite);
-      const inFrustum = isFinite(bounds.min) && isFinite(bounds.max);
+      const parentMeta = api.getByUuid(meta.parentUuid);
+      const pass = parentMeta !== null && (parentMeta.uuid === expectedParent || parentMeta.testId === expectedParent || parentMeta.name === expectedParent);
+      const parentLabel = parentMeta?.testId ?? parentMeta?.name ?? meta.parentUuid;
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" parent "${expectedParent}", got "${parentLabel}"`,
+        `expected "${idOrUuid}" to NOT have parent "${expectedParent}"`,
+        expectedParent,
+        parentLabel
+      );
+    });
+    Assertion.addMethod("r3fInstanceCount", function(idOrUuid, expectedCount) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fInstanceCount");
+      const actual = meta.instanceCount ?? 0;
       this.assert(
-        inFrustum,
-        `expected 3D object "${idOrUuid}" to be in the camera frustum`,
-        `expected 3D object "${idOrUuid}" to NOT be in the camera frustum`,
+        actual === expectedCount,
+        `expected "${idOrUuid}" instance count ${expectedCount}, got ${actual}`,
+        `expected "${idOrUuid}" to NOT have instance count ${expectedCount}`,
+        expectedCount,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fInFrustum", function(idOrUuid) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fInFrustum");
+      const fin = (v) => v.every(Number.isFinite);
+      const pass = fin(insp.bounds.min) && fin(insp.bounds.max);
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" to be in the camera frustum`,
+        `expected "${idOrUuid}" to NOT be in the camera frustum`,
         "in frustum",
-        inFrustum ? "in frustum" : "out of frustum / invalid bounds"
+        pass ? "in frustum" : "invalid bounds"
       );
     });
-    Assertion.addMethod(
-      "r3fPosition",
-      function(idOrUuid, expected, tolerance = 0.01) {
-        const api = getR3FFromWindow();
-        const meta = resolveObject(api, idOrUuid);
-        if (!meta) {
-          throw new Error(`3D object "${idOrUuid}" not found in the scene`);
-        }
-        const [ex, ey, ez] = expected;
-        const [ax, ay, az] = meta.position;
-        const pass = Math.abs(ax - ex) <= tolerance && Math.abs(ay - ey) <= tolerance && Math.abs(az - ez) <= tolerance;
+    Assertion.addMethod("r3fBounds", function(idOrUuid, expected, tolerance = 0.1) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fBounds");
+      const w = (a, b) => a.every((v, i) => Math.abs(v - b[i]) <= tolerance);
+      const pass = w(insp.bounds.min, expected.min) && w(insp.bounds.max, expected.max);
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" bounds min:${JSON.stringify(expected.min)} max:${JSON.stringify(expected.max)} (\xB1${tolerance}), got min:${JSON.stringify(insp.bounds.min)} max:${JSON.stringify(insp.bounds.max)}`,
+        `expected "${idOrUuid}" bounds to NOT match`,
+        expected,
+        insp.bounds
+      );
+    });
+    Assertion.addMethod("r3fColor", function(idOrUuid, expectedColor) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fColor");
+      const norm = expectedColor.startsWith("#") ? expectedColor.toLowerCase() : `#${expectedColor.toLowerCase()}`;
+      const actual = insp.material?.color?.toLowerCase();
+      this.assert(
+        actual === norm,
+        `expected "${idOrUuid}" color "${norm}", got "${actual ?? "no color"}"`,
+        `expected "${idOrUuid}" to NOT have color "${norm}"`,
+        norm,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fOpacity", function(idOrUuid, expectedOpacity, tolerance = 0.01) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fOpacity");
+      const actual = insp.material?.opacity;
+      const pass = actual !== void 0 && Math.abs(actual - expectedOpacity) <= tolerance;
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" opacity ${expectedOpacity} (\xB1${tolerance}), got ${actual ?? "no material"}`,
+        `expected "${idOrUuid}" to NOT have opacity ${expectedOpacity} (\xB1${tolerance})`,
+        expectedOpacity,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fTransparent", function(idOrUuid) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fTransparent");
+      const pass = insp.material?.transparent === true;
+      this.assert(
+        pass,
+        `expected "${idOrUuid}" transparent=true, got ${insp.material?.transparent ?? "no material"}`,
+        `expected "${idOrUuid}" to NOT be transparent`,
+        true,
+        insp.material?.transparent
+      );
+    });
+    Assertion.addMethod("r3fVertexCount", function(idOrUuid, expectedCount) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fVertexCount");
+      const actual = meta.vertexCount ?? 0;
+      this.assert(
+        actual === expectedCount,
+        `expected "${idOrUuid}" ${expectedCount} vertices, got ${actual}`,
+        `expected "${idOrUuid}" to NOT have ${expectedCount} vertices`,
+        expectedCount,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fTriangleCount", function(idOrUuid, expectedCount) {
+      const api = getR3FFromWindow();
+      const meta = requireObject(api, idOrUuid, "r3fTriangleCount");
+      const actual = meta.triangleCount ?? 0;
+      this.assert(
+        actual === expectedCount,
+        `expected "${idOrUuid}" ${expectedCount} triangles, got ${actual}`,
+        `expected "${idOrUuid}" to NOT have ${expectedCount} triangles`,
+        expectedCount,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fUserData", function(idOrUuid, key, expectedValue) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fUserData");
+      const hasKey = key in insp.userData;
+      if (expectedValue === void 0) {
+        this.assert(
+          hasKey,
+          `expected "${idOrUuid}" to have userData key "${key}"`,
+          `expected "${idOrUuid}" to NOT have userData key "${key}"`,
+          `key "${key}"`,
+          hasKey ? "present" : "missing"
+        );
+      } else {
+        const actual = insp.userData[key];
+        const pass = hasKey && JSON.stringify(actual) === JSON.stringify(expectedValue);
         this.assert(
           pass,
-          `expected 3D object "${idOrUuid}" to be at [${expected}] (\xB1${tolerance}), but was at [${meta.position}]`,
-          `expected 3D object "${idOrUuid}" to NOT be at [${expected}] (\xB1${tolerance})`,
-          expected,
-          meta.position
+          `expected "${idOrUuid}" userData.${key} = ${JSON.stringify(expectedValue)}, got ${JSON.stringify(actual)}`,
+          `expected "${idOrUuid}" to NOT have userData.${key} = ${JSON.stringify(expectedValue)}`,
+          expectedValue,
+          actual
         );
       }
-    );
-    Assertion.addMethod(
-      "r3fInstanceCount",
-      function(idOrUuid, expectedCount) {
-        const api = getR3FFromWindow();
-        const meta = resolveObject(api, idOrUuid);
-        if (!meta) {
-          throw new Error(`3D object "${idOrUuid}" not found in the scene`);
-        }
-        const actual = meta.instanceCount ?? 0;
+    });
+    Assertion.addMethod("r3fMapTexture", function(idOrUuid, expectedName) {
+      const api = getR3FFromWindow();
+      const insp = requireInspection(api, idOrUuid, "r3fMapTexture");
+      const actual = insp.material?.map;
+      if (!expectedName) {
         this.assert(
-          actual === expectedCount,
-          `expected 3D object "${idOrUuid}" to have instance count ${expectedCount}, but had ${actual}`,
-          `expected 3D object "${idOrUuid}" to NOT have instance count ${expectedCount}`,
-          expectedCount,
+          actual !== void 0 && actual !== null,
+          `expected "${idOrUuid}" to have a map texture`,
+          `expected "${idOrUuid}" to NOT have a map texture`,
+          "any map",
           actual
         );
-      }
-    );
-    Assertion.addMethod(
-      "r3fBounds",
-      function(idOrUuid, expected, tolerance = 0.1) {
-        const api = getR3FFromWindow();
-        const inspection = api.inspect(idOrUuid);
-        if (!inspection) {
-          throw new Error(`3D object "${idOrUuid}" not found in the scene`);
-        }
-        const { bounds } = inspection;
-        const withinTol = (a, b) => a.every((v, i) => Math.abs(v - b[i]) <= tolerance);
-        const pass = withinTol(bounds.min, expected.min) && withinTol(bounds.max, expected.max);
+      } else {
         this.assert(
-          pass,
-          `expected 3D object "${idOrUuid}" bounds to be min:${JSON.stringify(expected.min)} max:${JSON.stringify(expected.max)} (\xB1${tolerance}), but got min:${JSON.stringify(bounds.min)} max:${JSON.stringify(bounds.max)}`,
-          `expected 3D object "${idOrUuid}" bounds to NOT match`,
-          expected,
-          bounds
+          actual === expectedName,
+          `expected "${idOrUuid}" map "${expectedName}", got "${actual ?? "none"}"`,
+          `expected "${idOrUuid}" to NOT have map "${expectedName}"`,
+          expectedName,
+          actual
         );
       }
-    );
+    });
+    Assertion.addMethod("r3fObjectCount", function(expected) {
+      const api = getR3FFromWindow();
+      const actual = api.getCount();
+      this.assert(
+        actual === expected,
+        `expected scene to have ${expected} objects, got ${actual}`,
+        `expected scene to NOT have ${expected} objects`,
+        expected,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fObjectCountGreaterThan", function(min) {
+      const api = getR3FFromWindow();
+      const actual = api.getCount();
+      this.assert(
+        actual > min,
+        `expected scene to have more than ${min} objects, got ${actual}`,
+        `expected scene to have at most ${min} objects, but has ${actual}`,
+        `> ${min}`,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fCountByType", function(type, expected) {
+      const api = getR3FFromWindow();
+      const actual = api.getCountByType(type);
+      this.assert(
+        actual === expected,
+        `expected ${expected} "${type}" objects, got ${actual}`,
+        `expected scene to NOT have ${expected} "${type}" objects`,
+        expected,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fTotalTriangleCount", function(expected) {
+      const api = getR3FFromWindow();
+      const actual = collectTriangles(api);
+      this.assert(
+        actual === expected,
+        `expected ${expected} total triangles, got ${actual}`,
+        `expected scene to NOT have ${expected} total triangles`,
+        expected,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fTotalTriangleCountLessThan", function(max) {
+      const api = getR3FFromWindow();
+      const actual = collectTriangles(api);
+      this.assert(
+        actual < max,
+        `expected fewer than ${max} total triangles, got ${actual}`,
+        `expected at least ${max} total triangles, but has ${actual}`,
+        `< ${max}`,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fCameraPosition", function(expected, tolerance = 0.1) {
+      const api = getR3FFromWindow();
+      const cam = api.getCameraState();
+      const pass = expected.every((v, i) => Math.abs(cam.position[i] - v) <= tolerance);
+      this.assert(
+        pass,
+        `expected camera at [${expected}], got [${cam.position}] (tol=${tolerance})`,
+        `expected camera NOT at [${expected}]`,
+        expected,
+        cam.position
+      );
+    });
+    Assertion.addMethod("r3fCameraFov", function(expected, tolerance = 0.1) {
+      const api = getR3FFromWindow();
+      const cam = api.getCameraState();
+      const actual = cam.fov;
+      const pass = actual !== void 0 && Math.abs(actual - expected) <= tolerance;
+      this.assert(
+        pass,
+        `expected camera fov ${expected}, got ${actual ?? "N/A"} (tol=${tolerance})`,
+        `expected camera fov NOT ${expected}`,
+        expected,
+        actual
+      );
+    });
+    Assertion.addMethod("r3fCameraNear", function(expected, tolerance = 0.01) {
+      const api = getR3FFromWindow();
+      const cam = api.getCameraState();
+      const pass = Math.abs(cam.near - expected) <= tolerance;
+      this.assert(
+        pass,
+        `expected camera near ${expected}, got ${cam.near} (tol=${tolerance})`,
+        `expected camera near NOT ${expected}`,
+        expected,
+        cam.near
+      );
+    });
+    Assertion.addMethod("r3fCameraFar", function(expected, tolerance = 1) {
+      const api = getR3FFromWindow();
+      const cam = api.getCameraState();
+      const pass = Math.abs(cam.far - expected) <= tolerance;
+      this.assert(
+        pass,
+        `expected camera far ${expected}, got ${cam.far} (tol=${tolerance})`,
+        `expected camera far NOT ${expected}`,
+        expected,
+        cam.far
+      );
+    });
+    Assertion.addMethod("r3fCameraZoom", function(expected, tolerance = 0.01) {
+      const api = getR3FFromWindow();
+      const cam = api.getCameraState();
+      const pass = Math.abs(cam.zoom - expected) <= tolerance;
+      this.assert(
+        pass,
+        `expected camera zoom ${expected}, got ${cam.zoom} (tol=${tolerance})`,
+        `expected camera zoom NOT ${expected}`,
+        expected,
+        cam.zoom
+      );
+    });
+    Assertion.addMethod("r3fAllExist", function(idsOrPattern) {
+      const api = getR3FFromWindow();
+      const ids = typeof idsOrPattern === "string" ? resolvePatternSync(api, idsOrPattern) : idsOrPattern;
+      const missing = ids.filter((id) => resolveObject(api, id) === null);
+      this.assert(
+        missing.length === 0 && ids.length > 0,
+        `expected all objects to exist, missing: [${missing.join(", ")}]`,
+        `expected some objects to NOT exist, but all do`,
+        ids,
+        { missing }
+      );
+    });
+    Assertion.addMethod("r3fAllVisible", function(idsOrPattern) {
+      const api = getR3FFromWindow();
+      const ids = typeof idsOrPattern === "string" ? resolvePatternSync(api, idsOrPattern) : idsOrPattern;
+      const hidden = ids.filter((id) => {
+        const m = resolveObject(api, id);
+        return !m || !m.visible;
+      });
+      this.assert(
+        hidden.length === 0 && ids.length > 0,
+        `expected all objects to be visible, hidden/missing: [${hidden.join(", ")}]`,
+        `expected some objects to NOT be visible, but all are`,
+        ids,
+        { hidden }
+      );
+    });
+    Assertion.addMethod("r3fNoneExist", function(idsOrPattern) {
+      const api = getR3FFromWindow();
+      const ids = typeof idsOrPattern === "string" ? resolvePatternSync(api, idsOrPattern) : idsOrPattern;
+      const found = ids.filter((id) => resolveObject(api, id) !== null);
+      this.assert(
+        found.length === 0,
+        `expected no objects to exist, but found: [${found.join(", ")}]`,
+        `expected some objects to exist, but none do`,
+        ids,
+        { found }
+      );
+    });
   });
 }
+function resolvePatternSync(api, pattern) {
+  const snap = api.snapshot();
+  const ids = [];
+  const regex = new RegExp("^" + pattern.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;
+}
 
 // src/waiters.ts
+function resolveApiFromWindow(win) {
+  const w = win;
+  const cid = _getActiveCanvasId();
+  return cid ? w.__R3F_DOM_INSTANCES__?.[cid] : w.__R3F_DOM__;
+}
+function getBridgeState(win) {
+  const api = resolveApiFromWindow(win);
+  if (!api) return { exists: false, ready: false, error: null, count: 0 };
+  return {
+    exists: true,
+    ready: api._ready,
+    error: api._error ?? null,
+    count: api.getCount()
+  };
+}
+function assertBridgeNotErrored(state) {
+  if (state.exists && !state.ready && state.error) {
+    const reporter = _getReporter();
+    reporter?.logBridgeError(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.`
+    );
+  }
+}
 function registerWaiters() {
   Cypress.Commands.add(
     "r3fWaitForSceneReady",
@@ -213,24 +1168,41 @@ function registerWaiters() {
         pollIntervalMs = 100,
         timeout = 1e4
       } = options;
+      const reporter = _getReporter();
+      reporter?.logBridgeWaiting();
       const startTime = Date.now();
       let lastCount = -1;
       let stableRuns = 0;
+      let bridgeLogged = false;
       function poll() {
         if (Date.now() - startTime > timeout) {
+          reporter?.logBridgeError(
+            `Timed out after ${timeout}ms. Last count: ${lastCount}, stable: ${stableRuns}/${stableChecks}`
+          );
           throw new Error(
             `r3fWaitForSceneReady timed out after ${timeout}ms. Last count: ${lastCount}, stable runs: ${stableRuns}/${stableChecks}`
           );
         }
         return cy.window({ log: false }).then((win) => {
-          const api = win.__R3F_DOM__;
-          if (!api) {
+          const state = getBridgeState(win);
+          assertBridgeNotErrored(state);
+          if (!state.exists || !state.ready) {
             return cy.wait(pollIntervalMs, { log: false }).then(() => poll());
           }
-          const count = api.getCount();
+          if (!bridgeLogged) {
+            bridgeLogged = true;
+            const api = resolveApiFromWindow(win);
+            let diag;
+            if (typeof api.getDiagnostics === "function") {
+              diag = api.getDiagnostics();
+            }
+            reporter?.logBridgeConnected(diag);
+          }
+          const count = state.count;
           if (count === lastCount && count > 0) {
             stableRuns++;
             if (stableRuns >= stableChecks) {
+              reporter?.logSceneReady(count);
               return;
             }
           } else {
@@ -252,20 +1224,27 @@ function registerWaiters() {
         timeout = 1e4
       } = options;
       const startTime = Date.now();
-      let lastJson = "";
+      let lastHash = "";
       let stableCount = 0;
+      function hashTree(node) {
+        let h = `${node.uuid}:${node.visible ? 1 : 0}:${node.position[0].toFixed(3)},${node.position[1].toFixed(3)},${node.position[2].toFixed(3)}:${node.children.length}`;
+        for (const c of node.children) h += "|" + hashTree(c);
+        return h;
+      }
       function poll() {
         if (Date.now() - startTime > timeout) {
           throw new Error(`r3fWaitForIdle timed out after ${timeout}ms`);
         }
         return cy.window({ log: false }).then((win) => {
-          const api = win.__R3F_DOM__;
-          if (!api) {
+          const state = getBridgeState(win);
+          assertBridgeNotErrored(state);
+          if (!state.exists || !state.ready) {
             return cy.wait(pollIntervalMs, { log: false }).then(() => poll());
           }
+          const api = resolveApiFromWindow(win);
           const snap = api.snapshot();
-          const json = JSON.stringify(snap.tree);
-          if (json === lastJson && json !== "") {
+          const hash = hashTree(snap.tree);
+          if (hash === lastHash && hash !== "") {
             stableCount++;
             if (stableCount >= idleChecks) {
               return;
@@ -273,18 +1252,221 @@ function registerWaiters() {
           } else {
             stableCount = 0;
           }
-          lastJson = json;
+          lastHash = hash;
           return cy.wait(pollIntervalMs, { log: false }).then(() => poll());
         });
       }
       return poll();
     }
   );
+  Cypress.Commands.add(
+    "r3fWaitForObject",
+    (idOrUuid, options = {}) => {
+      const {
+        bridgeTimeout = 3e4,
+        objectTimeout = 4e4,
+        pollIntervalMs = 200
+      } = options;
+      const reporter = _getReporter();
+      const bridgeStart = Date.now();
+      function waitForBridge() {
+        if (Date.now() - bridgeStart > bridgeTimeout) {
+          reporter?.logBridgeError(
+            `Timed out after ${bridgeTimeout}ms waiting for bridge`
+          );
+          throw new Error(
+            `r3fWaitForObject("${idOrUuid}") timed out after ${bridgeTimeout}ms waiting for the bridge. Ensure <ThreeDom> is mounted inside your <Canvas>.`
+          );
+        }
+        return cy.window({ log: false }).then((win) => {
+          const state = getBridgeState(win);
+          assertBridgeNotErrored(state);
+          if (state.exists && state.ready) {
+            return pollForObject();
+          }
+          return cy.wait(pollIntervalMs, { log: false }).then(() => waitForBridge());
+        });
+      }
+      const objectStart = Date.now();
+      function pollForObject() {
+        if (Date.now() - objectStart > objectTimeout) {
+          return cy.window({ log: false }).then((win) => {
+            const api = resolveApiFromWindow(win);
+            const state = getBridgeState(win);
+            let msg = `r3fWaitForObject("${idOrUuid}") timed out after ${objectTimeout}ms.
+Bridge: ${state.exists ? "exists" : "missing"}, ready: ${state.ready}, objectCount: ${state.count}.
+Ensure the object has userData.testId="${idOrUuid}" or uuid="${idOrUuid}".`;
+            let suggestions = [];
+            if (api && typeof api.fuzzyFind === "function") {
+              suggestions = api.fuzzyFind(idOrUuid, 5);
+              if (suggestions.length > 0) {
+                msg += "\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");
+              }
+            }
+            reporter?.logObjectNotFound(idOrUuid, suggestions);
+            throw new Error(msg);
+          });
+        }
+        return cy.window({ log: false }).then((win) => {
+          const api = resolveApiFromWindow(win);
+          if (!api || !api._ready) {
+            return cy.wait(pollIntervalMs, { log: false }).then(() => pollForObject());
+          }
+          const meta = api.getByTestId(idOrUuid) ?? api.getByUuid(idOrUuid);
+          if (meta) {
+            reporter?.logObjectFound(idOrUuid, meta.type, meta.name || void 0);
+            Cypress.log({
+              name: "r3fWaitForObject",
+              message: `"${idOrUuid}" found`
+            });
+            return;
+          }
+          return cy.wait(pollIntervalMs, { log: false }).then(() => pollForObject());
+        });
+      }
+      return waitForBridge();
+    }
+  );
+  Cypress.Commands.add(
+    "r3fWaitForNewObject",
+    (options = {}) => {
+      const {
+        type: filterType,
+        nameContains,
+        pollIntervalMs = 100,
+        timeout = 1e4
+      } = options;
+      const baselineUuids = [];
+      function collectUuids(node) {
+        baselineUuids.push(node.uuid);
+        for (const child of node.children) {
+          collectUuids(child);
+        }
+      }
+      return cy.window({ log: false }).then((win) => {
+        const state = getBridgeState(win);
+        assertBridgeNotErrored(state);
+        if (state.exists && state.ready) {
+          const api = resolveApiFromWindow(win);
+          const snap = api.snapshot();
+          collectUuids(snap.tree);
+        }
+        const baselineSet = new Set(baselineUuids);
+        const startTime = Date.now();
+        function poll() {
+          if (Date.now() - startTime > timeout) {
+            const filterDesc = [
+              filterType ? `type="${filterType}"` : null,
+              nameContains ? `nameContains="${nameContains}"` : null
+            ].filter(Boolean).join(", ");
+            throw new Error(
+              `r3fWaitForNewObject timed out after ${timeout}ms. No new objects appeared${filterDesc ? ` matching ${filterDesc}` : ""}. Baseline had ${baselineUuids.length} objects.`
+            );
+          }
+          return cy.wait(pollIntervalMs, { log: false }).then(() => {
+            return cy.window({ log: false }).then((w) => {
+              const bridgeState = getBridgeState(w);
+              assertBridgeNotErrored(bridgeState);
+              if (!bridgeState.exists || !bridgeState.ready) return poll();
+              const bridge = resolveApiFromWindow(w);
+              const snap = bridge.snapshot();
+              const newObjects = [];
+              const newUuids = [];
+              function scanForNew(node) {
+                if (!baselineSet.has(node.uuid)) {
+                  const typeMatch = !filterType || node.type === filterType;
+                  const nameMatch = !nameContains || node.name.includes(nameContains);
+                  if (typeMatch && nameMatch) {
+                    const meta = bridge.getByUuid(node.uuid);
+                    if (meta) {
+                      newObjects.push(meta);
+                      newUuids.push(node.uuid);
+                    }
+                  }
+                }
+                for (const child of node.children) {
+                  scanForNew(child);
+                }
+              }
+              scanForNew(snap.tree);
+              if (newObjects.length > 0) {
+                Cypress.log({
+                  name: "r3fWaitForNewObject",
+                  message: `${newObjects.length} new object(s) found`,
+                  consoleProps: () => ({ newObjects, newUuids })
+                });
+                return { newObjects, newUuids, count: newObjects.length };
+              }
+              return poll();
+            });
+          });
+        }
+        return poll();
+      });
+    }
+  );
+  Cypress.Commands.add(
+    "r3fWaitForObjectRemoved",
+    (idOrUuid, options = {}) => {
+      const {
+        bridgeTimeout = 3e4,
+        pollIntervalMs = 100,
+        timeout = 1e4
+      } = options;
+      const bridgeStart = Date.now();
+      function waitForBridge() {
+        if (Date.now() - bridgeStart > bridgeTimeout) {
+          throw new Error(
+            `r3fWaitForObjectRemoved("${idOrUuid}") timed out after ${bridgeTimeout}ms waiting for the bridge.`
+          );
+        }
+        return cy.window({ log: false }).then((win) => {
+          const state = getBridgeState(win);
+          assertBridgeNotErrored(state);
+          if (state.exists && state.ready) {
+            return pollForRemoved();
+          }
+          return cy.wait(pollIntervalMs, { log: false }).then(() => waitForBridge());
+        });
+      }
+      const removeDeadline = Date.now() + timeout;
+      function pollForRemoved() {
+        if (Date.now() > removeDeadline) {
+          throw new Error(
+            `r3fWaitForObjectRemoved("${idOrUuid}") timed out after ${timeout}ms. Object is still in the scene.`
+          );
+        }
+        return cy.window({ log: false }).then((win) => {
+          const api = resolveApiFromWindow(win);
+          if (!api || !api._ready) {
+            return cy.wait(pollIntervalMs, { log: false }).then(() => pollForRemoved());
+          }
+          const stillPresent = (api.getByTestId(idOrUuid) ?? api.getByUuid(idOrUuid)) !== null;
+          if (!stillPresent) {
+            Cypress.log({
+              name: "r3fWaitForObjectRemoved",
+              message: `"${idOrUuid}" removed`
+            });
+            return;
+          }
+          return cy.wait(pollIntervalMs, { log: false }).then(() => pollForRemoved());
+        });
+      }
+      return waitForBridge();
+    }
+  );
 }
 
 // src/index.ts
 registerCommands();
 registerAssertions();
 registerWaiters();
+
+exports.R3FReporter = R3FReporter;
+exports.diffSnapshots = diffSnapshots;
+exports.registerR3FTasks = registerR3FTasks;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map