@react-three-dom/core 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -6,6 +6,25 @@ var fiber = require('@react-three/fiber');
 
 // src/version.ts
 var version = "0.1.0";
+
+// src/debug.ts
+var _enabled = false;
+function enableDebug(on = true) {
+  _enabled = on;
+}
+function isDebugEnabled() {
+  return _enabled || typeof window !== "undefined" && !!window.__R3F_DOM_DEBUG__;
+}
+function r3fLog(area, msg, data) {
+  if (!_enabled && !(typeof window !== "undefined" && window.__R3F_DOM_DEBUG__)) {
+    return;
+  }
+  if (data !== void 0) {
+    console.log(`[r3f-dom:${area}]`, msg, data);
+  } else {
+    console.log(`[r3f-dom:${area}]`, msg);
+  }
+}
 function extractMetadata(obj) {
   const meta = {
     uuid: obj.uuid,
@@ -20,31 +39,42 @@ function extractMetadata(obj) {
     childrenUuids: obj.children.map((c) => c.uuid),
     boundsDirty: true
   };
-  if ("geometry" in obj) {
-    const geom = obj.geometry;
-    if (geom instanceof three.BufferGeometry) {
-      meta.geometryType = geom.type;
-      const posAttr = geom.getAttribute("position");
-      if (posAttr) {
-        meta.vertexCount = posAttr.count;
-        if (geom.index) {
-          meta.triangleCount = Math.floor(geom.index.count / 3);
-        } else {
-          meta.triangleCount = Math.floor(posAttr.count / 3);
+  try {
+    if ("geometry" in obj) {
+      const geom = obj.geometry;
+      if (geom instanceof three.BufferGeometry) {
+        meta.geometryType = geom.type;
+        const posAttr = geom.getAttribute("position");
+        if (posAttr) {
+          meta.vertexCount = posAttr.count;
+          if (geom.index) {
+            meta.triangleCount = Math.floor(geom.index.count / 3);
+          } else {
+            meta.triangleCount = Math.floor(posAttr.count / 3);
+          }
         }
       }
     }
+  } catch {
+    r3fLog("store", `extractMetadata: geometry access failed for "${obj.name || obj.uuid}"`);
   }
-  if ("material" in obj) {
-    const mat = obj.material;
-    if (mat instanceof three.Material) {
-      meta.materialType = mat.type;
-    } else if (Array.isArray(mat) && mat.length > 0) {
-      meta.materialType = mat[0].type + (mat.length > 1 ? ` (+${mat.length - 1})` : "");
+  try {
+    if ("material" in obj) {
+      const mat = obj.material;
+      if (mat instanceof three.Material) {
+        meta.materialType = mat.type;
+      } else if (Array.isArray(mat) && mat.length > 0) {
+        meta.materialType = mat[0].type + (mat.length > 1 ? ` (+${mat.length - 1})` : "");
+      }
     }
+  } catch {
+    r3fLog("store", `extractMetadata: material access failed for "${obj.name || obj.uuid}"`);
   }
-  if (obj instanceof three.InstancedMesh) {
-    meta.instanceCount = obj.count;
+  try {
+    if (obj instanceof three.InstancedMesh) {
+      meta.instanceCount = obj.count;
+    }
+  } catch {
   }
   return meta;
 }
@@ -53,81 +83,101 @@ function hasChanged(prev, curr) {
 }
 var _box3 = new three.Box3();
 function inspectObject(obj, metadata) {
-  obj.updateWorldMatrix(true, false);
-  const worldMatrix = Array.from(obj.matrixWorld.elements);
-  _box3.setFromObject(obj);
-  const boundsMin = [_box3.min.x, _box3.min.y, _box3.min.z];
-  const boundsMax = [_box3.max.x, _box3.max.y, _box3.max.z];
+  let worldMatrix = Array(16).fill(0);
+  let boundsMin = [0, 0, 0];
+  let boundsMax = [0, 0, 0];
+  try {
+    obj.updateWorldMatrix(true, false);
+    worldMatrix = Array.from(obj.matrixWorld.elements);
+    _box3.setFromObject(obj);
+    boundsMin = [_box3.min.x, _box3.min.y, _box3.min.z];
+    boundsMax = [_box3.max.x, _box3.max.y, _box3.max.z];
+  } catch {
+    r3fLog("store", `inspectObject: world matrix / bounds failed for "${obj.name || obj.uuid}"`);
+  }
   const inspection = {
     metadata,
     worldMatrix,
     bounds: { min: boundsMin, max: boundsMax },
-    userData: { ...obj.userData }
+    userData: {}
   };
-  if ("geometry" in obj) {
-    const geom = obj.geometry;
-    if (geom instanceof three.BufferGeometry) {
-      const geoInspection = {
-        type: geom.type,
-        attributes: {}
-      };
-      for (const [name, attr] of Object.entries(geom.attributes)) {
-        geoInspection.attributes[name] = {
-          itemSize: attr.itemSize,
-          count: attr.count
+  try {
+    inspection.userData = { ...obj.userData };
+  } catch {
+    r3fLog("store", `inspectObject: userData copy failed for "${obj.name || obj.uuid}"`);
+  }
+  try {
+    if ("geometry" in obj) {
+      const geom = obj.geometry;
+      if (geom instanceof three.BufferGeometry) {
+        const geoInspection = {
+          type: geom.type,
+          attributes: {}
         };
+        for (const [name, attr] of Object.entries(geom.attributes)) {
+          geoInspection.attributes[name] = {
+            itemSize: attr.itemSize,
+            count: attr.count
+          };
+        }
+        if (geom.index) {
+          geoInspection.index = { count: geom.index.count };
+        }
+        geom.computeBoundingSphere();
+        const sphere = geom.boundingSphere;
+        if (sphere) {
+          geoInspection.boundingSphere = {
+            center: [sphere.center.x, sphere.center.y, sphere.center.z],
+            radius: sphere.radius
+          };
+        }
+        inspection.geometry = geoInspection;
       }
-      if (geom.index) {
-        geoInspection.index = { count: geom.index.count };
-      }
-      geom.computeBoundingSphere();
-      const sphere = geom.boundingSphere;
-      if (sphere) {
-        geoInspection.boundingSphere = {
-          center: [sphere.center.x, sphere.center.y, sphere.center.z],
-          radius: sphere.radius
+    }
+  } catch {
+    r3fLog("store", `inspectObject: geometry inspection failed for "${obj.name || obj.uuid}"`);
+  }
+  try {
+    if ("material" in obj) {
+      const rawMat = obj.material;
+      const mat = Array.isArray(rawMat) ? rawMat[0] : rawMat;
+      if (mat instanceof three.Material) {
+        const matInspection = {
+          type: mat.type,
+          transparent: mat.transparent,
+          opacity: mat.opacity,
+          side: mat.side
         };
-      }
-      inspection.geometry = geoInspection;
-    }
-  }
-  if ("material" in obj) {
-    const rawMat = obj.material;
-    const mat = Array.isArray(rawMat) ? rawMat[0] : rawMat;
-    if (mat instanceof three.Material) {
-      const matInspection = {
-        type: mat.type,
-        transparent: mat.transparent,
-        opacity: mat.opacity,
-        side: mat.side
-      };
-      if ("color" in mat && mat.color instanceof three.Color) {
-        matInspection.color = "#" + mat.color.getHexString();
-      }
-      if ("map" in mat) {
-        const map = mat.map;
-        if (map) {
-          matInspection.map = map.name || map.uuid || "unnamed";
+        if ("color" in mat && mat.color instanceof three.Color) {
+          matInspection.color = "#" + mat.color.getHexString();
         }
-      }
-      if ("uniforms" in mat) {
-        const uniforms = mat.uniforms;
-        matInspection.uniforms = {};
-        for (const [key, uniform] of Object.entries(uniforms)) {
-          const val = uniform.value;
-          if (val === null || val === void 0) {
-            matInspection.uniforms[key] = val;
-          } else if (typeof val === "number" || typeof val === "boolean" || typeof val === "string") {
-            matInspection.uniforms[key] = val;
-          } else if (typeof val === "object" && "toArray" in val) {
-            matInspection.uniforms[key] = val.toArray();
-          } else {
-            matInspection.uniforms[key] = `[${typeof val}]`;
+        if ("map" in mat) {
+          const map = mat.map;
+          if (map) {
+            matInspection.map = map.name || map.uuid || "unnamed";
+          }
+        }
+        if ("uniforms" in mat) {
+          const uniforms = mat.uniforms;
+          matInspection.uniforms = {};
+          for (const [key, uniform] of Object.entries(uniforms)) {
+            const val = uniform.value;
+            if (val === null || val === void 0) {
+              matInspection.uniforms[key] = val;
+            } else if (typeof val === "number" || typeof val === "boolean" || typeof val === "string") {
+              matInspection.uniforms[key] = val;
+            } else if (typeof val === "object" && "toArray" in val) {
+              matInspection.uniforms[key] = val.toArray();
+            } else {
+              matInspection.uniforms[key] = `[${typeof val}]`;
+            }
           }
         }
+        inspection.material = matInspection;
       }
-      inspection.material = matInspection;
     }
+  } catch {
+    r3fLog("store", `inspectObject: material inspection failed for "${obj.name || obj.uuid}"`);
   }
   return inspection;
 }
@@ -177,15 +227,25 @@ var ObjectStore = class {
       nameSet.add(obj);
     }
     this._emit({ type: "add", object: obj, metadata: meta });
+    if (meta.testId) {
+      r3fLog("store", `Registered "${meta.testId}" (${meta.type})`);
+    }
     return meta;
   }
   /**
    * Register an entire subtree (object + all descendants).
+   * Individual objects that fail to register are skipped (logged when debug
+   * is enabled) so that one bad object doesn't prevent the rest from being
+   * tracked.
    */
   registerTree(root) {
     this._trackedRoots.add(root);
     root.traverse((obj) => {
-      this.register(obj);
+      try {
+        this.register(obj);
+      } catch (err) {
+        r3fLog("store", `registerTree: failed to register "${obj.name || obj.uuid}"`, err);
+      }
     });
   }
   /**
@@ -210,6 +270,9 @@ var ObjectStore = class {
         }
       }
     }
+    if (meta.testId) {
+      r3fLog("store", `Unregistered "${meta.testId}" (${meta.type})`);
+    }
     this._emit({ type: "remove", object: obj, metadata: meta });
   }
   /**
@@ -227,13 +290,22 @@ var ObjectStore = class {
   /**
    * Refresh Tier 1 metadata from the live Three.js object.
    * Returns true if any values changed.
+   * Returns false (no change) if extracting metadata throws so that the
+   * previous metadata is preserved.
    */
   update(obj) {
     const prev = this._metaByObject.get(obj);
     if (!prev) return false;
-    const curr = extractMetadata(obj);
+    let curr;
+    try {
+      curr = extractMetadata(obj);
+    } catch (err) {
+      r3fLog("store", `update: extractMetadata failed for "${obj.name || obj.uuid}"`, err);
+      return false;
+    }
     if (hasChanged(prev, curr)) {
       if (prev.testId !== curr.testId) {
+        r3fLog("store", `testId changed: "${prev.testId}" \u2192 "${curr.testId}" (${curr.type})`);
         if (prev.testId) this._objectsByTestId.delete(prev.testId);
         if (curr.testId) this._objectsByTestId.set(curr.testId, obj);
       }
@@ -301,6 +373,64 @@ var ObjectStore = class {
     }
     return results;
   }
+  /**
+   * Batch lookup: get metadata for multiple objects by testId or uuid.
+   * Returns a Map from the requested id to its metadata (or null if not found).
+   * Single round-trip — much more efficient than calling getByTestId/getByUuid
+   * in a loop for BIM/CAD scenes with many objects.
+   * O(k) where k is the number of requested ids.
+   */
+  getObjects(ids) {
+    const results = /* @__PURE__ */ new Map();
+    for (const id of ids) {
+      const meta = this.getByTestId(id) ?? this.getByUuid(id);
+      results.set(id, meta);
+    }
+    return results;
+  }
+  /**
+   * Get all objects of a given Three.js type (e.g. "Mesh", "Group", "Line").
+   * Linear scan — O(n) where n is total tracked objects.
+   */
+  getByType(type) {
+    const results = [];
+    for (const obj of this.getFlatList()) {
+      const meta = this._metaByObject.get(obj);
+      if (meta && meta.type === type) results.push(meta);
+    }
+    return results;
+  }
+  /**
+   * Get all objects that have a specific userData key.
+   * If `value` is provided, only returns objects where `userData[key]` matches.
+   * Uses JSON.stringify for deep equality on complex values.
+   * Linear scan — O(n).
+   */
+  getByUserData(key, value) {
+    const results = [];
+    const checkValue = value !== void 0;
+    const valueJson = checkValue ? JSON.stringify(value) : "";
+    for (const obj of this.getFlatList()) {
+      if (!(key in obj.userData)) continue;
+      if (checkValue && JSON.stringify(obj.userData[key]) !== valueJson) continue;
+      const meta = this._metaByObject.get(obj);
+      if (meta) results.push(meta);
+    }
+    return results;
+  }
+  /**
+   * Count objects of a given Three.js type.
+   * More efficient than getByType().length — no array allocation.
+   * Linear scan — O(n).
+   */
+  getCountByType(type) {
+    let count = 0;
+    for (const obj of this.getFlatList()) {
+      const meta = this._metaByObject.get(obj);
+      if (meta && meta.type === type) count++;
+    }
+    return count;
+  }
   /** Get the raw Three.js Object3D by testId or uuid. */
   getObject3D(idOrUuid) {
     return this._objectsByTestId.get(idOrUuid) ?? this._objectByUuid.get(idOrUuid) ?? null;
@@ -1034,6 +1164,7 @@ function registerSubtree(obj, store, mirror) {
 function patchObject3D(store, mirror) {
   _activePairs.push({ store, mirror });
   if (!_patched) {
+    r3fLog("patch", "Patching Object3D.prototype.add and .remove");
     _originalAdd = three.Object3D.prototype.add;
     _originalRemove = three.Object3D.prototype.remove;
     three.Object3D.prototype.add = function patchedAdd(...objects) {
@@ -1042,8 +1173,15 @@ function patchObject3D(store, mirror) {
       if (pair) {
         for (const obj of objects) {
           if (obj === this) continue;
-          registerSubtree(obj, pair.store, pair.mirror);
+          try {
+            r3fLog("patch", `patchedAdd: "${obj.name || obj.type}" added to "${this.name || this.type}"`);
+            registerSubtree(obj, pair.store, pair.mirror);
+          } catch (err) {
+            r3fLog("patch", `patchedAdd: failed to register "${obj.name || obj.type}"`, err);
+          }
         }
+        pair.store.update(this);
+        pair.store.markDirty(this);
       }
       return this;
     };
@@ -1052,11 +1190,18 @@ function patchObject3D(store, mirror) {
       if (pair) {
         for (const obj of objects) {
           if (obj === this) continue;
-          pair.mirror.onObjectRemoved(obj);
-          obj.traverse((child) => {
-            pair.store.unregister(child);
-          });
+          try {
+            r3fLog("patch", `patchedRemove: "${obj.name || obj.type}" removed from "${this.name || this.type}"`);
+            pair.mirror.onObjectRemoved(obj);
+            obj.traverse((child) => {
+              pair.store.unregister(child);
+            });
+          } catch (err) {
+            r3fLog("patch", `patchedRemove: failed to unregister "${obj.name || obj.type}"`, err);
+          }
         }
+        pair.store.update(this);
+        pair.store.markDirty(this);
       }
       _originalRemove.call(this, ...objects);
       return this;
@@ -1077,6 +1222,7 @@ function patchObject3D(store, mirror) {
 }
 function restoreObject3D() {
   if (!_patched) return;
+  r3fLog("patch", "Restoring original Object3D.prototype.add and .remove");
   if (_originalAdd) {
     three.Object3D.prototype.add = _originalAdd;
     _originalAdd = null;
@@ -1100,7 +1246,7 @@ function buildNodeTree(store, meta) {
       children.push(buildNodeTree(store, childMeta));
     }
   }
-  return {
+  const node = {
     uuid: meta.uuid,
     name: meta.name,
     type: meta.type,
@@ -1111,6 +1257,12 @@ function buildNodeTree(store, meta) {
     scale: [...meta.scale],
     children
   };
+  if (meta.geometryType) node.geometryType = meta.geometryType;
+  if (meta.materialType) node.materialType = meta.materialType;
+  if (meta.vertexCount != null) node.vertexCount = meta.vertexCount;
+  if (meta.triangleCount != null) node.triangleCount = meta.triangleCount;
+  if (meta.instanceCount != null) node.instanceCount = meta.instanceCount;
+  return node;
 }
 function findRoot(store) {
   const allObjects = store.getFlatList();
@@ -1699,6 +1851,7 @@ function click3D(idOrUuid, options = {}) {
   const camera = getCamera();
   const gl = getRenderer();
   const size = getCanvasSize();
+  r3fLog("click", `click3D("${idOrUuid}") \u2014 resolving projection`);
   const projection = projectToScreen(obj, camera, size);
   if (!projection) {
     throw new Error(
@@ -1791,6 +1944,7 @@ function hover3D(idOrUuid, options = {}) {
   const camera = getCamera();
   const gl = getRenderer();
   const size = getCanvasSize();
+  r3fLog("hover", `hover3D("${idOrUuid}") \u2014 resolving projection`);
   const projection = projectToScreen(obj, camera, size);
   if (!projection) {
     throw new Error(
@@ -1825,6 +1979,7 @@ async function drag3D(idOrUuid, delta, options = {}) {
   const camera = getCamera();
   const gl = getRenderer();
   const size = getCanvasSize();
+  r3fLog("drag", `drag3D("${idOrUuid}") mode=${mode}`, delta);
   const projection = projectToScreen(obj, camera, size);
   if (!projection) {
     throw new Error(
@@ -1894,6 +2049,162 @@ function pointerMiss3D(options = {}) {
   dispatchPointerMiss(canvas, options.point);
 }
 
+// src/interactions/drawPath.ts
+var _nextDrawPointerId = 5e3;
+function makeDrawPointerInit(canvas, point, pointerId, pointerType, overrides) {
+  const rect = canvas.getBoundingClientRect();
+  const clientX = rect.left + point.x;
+  const clientY = rect.top + point.y;
+  return {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    clientX,
+    clientY,
+    screenX: clientX,
+    screenY: clientY,
+    pointerId,
+    pointerType,
+    isPrimary: true,
+    button: 0,
+    buttons: 1,
+    width: 1,
+    height: 1,
+    pressure: point.pressure ?? 0.5,
+    ...overrides
+  };
+}
+async function drawPath(points, options = {}) {
+  if (points.length < 2) {
+    throw new Error(
+      `[react-three-dom] drawPath requires at least 2 points, got ${points.length}.`
+    );
+  }
+  const {
+    stepDelayMs = 0,
+    pointerType = "mouse",
+    clickAtEnd = false,
+    canvas: explicitCanvas
+  } = options;
+  const canvas = explicitCanvas ?? getRenderer().domElement;
+  const pointerId = _nextDrawPointerId++;
+  let eventCount = 0;
+  r3fLog("draw", `drawPath \u2014 ${points.length} points, delay=${stepDelayMs}ms, pointerType=${pointerType}`);
+  const first = points[0];
+  canvas.dispatchEvent(
+    new PointerEvent("pointerdown", makeDrawPointerInit(canvas, first, pointerId, pointerType))
+  );
+  eventCount++;
+  for (let i = 1; i < points.length; i++) {
+    if (stepDelayMs > 0) {
+      await sleep2(stepDelayMs);
+    }
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointermove",
+        makeDrawPointerInit(canvas, points[i], pointerId, pointerType)
+      )
+    );
+    eventCount++;
+  }
+  const last = points[points.length - 1];
+  canvas.dispatchEvent(
+    new PointerEvent(
+      "pointerup",
+      makeDrawPointerInit(canvas, last, pointerId, pointerType, {
+        buttons: 0,
+        pressure: 0
+      })
+    )
+  );
+  eventCount++;
+  if (clickAtEnd) {
+    const rect = canvas.getBoundingClientRect();
+    canvas.dispatchEvent(
+      new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+        clientX: rect.left + last.x,
+        clientY: rect.top + last.y,
+        button: 0
+      })
+    );
+    eventCount++;
+  }
+  r3fLog("draw", `drawPath complete \u2014 ${eventCount} events dispatched`);
+  return {
+    eventCount,
+    pointCount: points.length,
+    startPoint: first,
+    endPoint: last
+  };
+}
+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;
+}
+function sleep2(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // src/highlight/SelectionManager.ts
 var SelectionManager = class {
   constructor() {
@@ -2048,10 +2359,22 @@ function projectToScreenRect(obj, camera, canvasRect) {
 }
 function exposeGlobalAPI(store) {
   const api = {
+    _ready: true,
     getByTestId: (id) => store.getByTestId(id),
     getByUuid: (uuid) => store.getByUuid(uuid),
     getByName: (name) => store.getByName(name),
     getCount: () => store.getCount(),
+    getByType: (type) => store.getByType(type),
+    getByUserData: (key, value) => store.getByUserData(key, value),
+    getCountByType: (type) => store.getCountByType(type),
+    getObjects: (ids) => {
+      const map = store.getObjects(ids);
+      const result = {};
+      for (const [id, meta] of map) {
+        result[id] = meta;
+      }
+      return result;
+    },
     snapshot: () => createSnapshot(store),
     inspect: (idOrUuid) => store.inspect(idOrUuid),
     click: (idOrUuid) => {
@@ -2066,8 +2389,8 @@ function exposeGlobalAPI(store) {
     hover: (idOrUuid) => {
       hover3D(idOrUuid);
     },
-    drag: (idOrUuid, delta) => {
-      void drag3D(idOrUuid, delta);
+    drag: async (idOrUuid, delta) => {
+      await drag3D(idOrUuid, delta);
     },
     wheel: (idOrUuid, options) => {
       wheel3D(idOrUuid, options);
@@ -2075,6 +2398,10 @@ function exposeGlobalAPI(store) {
     pointerMiss: () => {
       pointerMiss3D();
     },
+    drawPath: async (points, options) => {
+      const result = await drawPath(points, options);
+      return { eventCount: result.eventCount, pointCount: result.pointCount };
+    },
     select: (idOrUuid) => {
       const obj = store.getObject3D(idOrUuid);
       if (obj && _selectionManager) _selectionManager.select(obj);
@@ -2082,13 +2409,28 @@ function exposeGlobalAPI(store) {
     clearSelection: () => {
       _selectionManager?.clearSelection();
     },
+    getSelection: () => _selectionManager ? _selectionManager.getSelected().map((o) => o.uuid) : [],
     getObject3D: (idOrUuid) => store.getObject3D(idOrUuid),
     version
   };
   window.__R3F_DOM__ = api;
 }
-function removeGlobalAPI() {
-  delete window.__R3F_DOM__;
+function removeGlobalAPI(onlyIfEquals) {
+  r3fLog("bridge", "removeGlobalAPI called (deferred)");
+  if (onlyIfEquals !== void 0) {
+    const ref = onlyIfEquals;
+    queueMicrotask(() => {
+      if (window.__R3F_DOM__ === ref) {
+        delete window.__R3F_DOM__;
+        r3fLog("bridge", "Global API removed");
+      } else {
+        r3fLog("bridge", "Global API not removed \u2014 replaced by new instance (Strict Mode remount)");
+      }
+    });
+  } else {
+    delete window.__R3F_DOM__;
+    r3fLog("bridge", "Global API removed (immediate)");
+  }
 }
 function setElementRect(el, l, t, w, h) {
   const d = el.dataset;
@@ -2109,7 +2451,8 @@ function ThreeDom({
   timeBudgetMs = 0.5,
   maxDomNodes = 2e3,
   initialDepth = 3,
-  enabled = true
+  enabled = true,
+  debug = false
 } = {}) {
   const scene = fiber.useThree((s) => s.scene);
   const camera = fiber.useThree((s) => s.camera);
@@ -2119,6 +2462,8 @@ function ThreeDom({
   const positionCursorRef = react.useRef(0);
   react.useEffect(() => {
     if (!enabled) return;
+    if (debug) enableDebug(true);
+    r3fLog("setup", "ThreeDom effect started", { enabled, debug, root, maxDomNodes });
     const canvas = gl.domElement;
     const canvasParent = canvas.parentElement;
     let rootElement = null;
@@ -2145,57 +2490,115 @@ function ThreeDom({
       "overflow: hidden",
       "z-index: 10"
     ].join(";");
-    const store = new ObjectStore();
-    const mirror = new DomMirror(store, maxDomNodes);
-    mirror.setRoot(rootElement);
-    ensureCustomElements(store);
-    store.registerTree(scene);
-    mirror.materializeSubtree(scene.uuid, initialDepth);
-    const unpatch = patchObject3D(store, mirror);
-    setInteractionState(store, camera, gl, size);
-    const selectionManager = new SelectionManager();
-    _selectionManager = selectionManager;
-    _highlighter = null;
-    exposeGlobalAPI(store);
-    _store3 = store;
-    _mirror = mirror;
-    const initialCanvasRect = canvas.getBoundingClientRect();
-    const allObjects = store.getFlatList();
-    for (const obj of allObjects) {
-      if (obj.userData?.__r3fdom_internal) continue;
-      const el = mirror.getElement(obj.uuid);
-      if (!el) continue;
-      if (obj.type === "Scene") {
-        setElementRect(el, 0, 0, Math.round(initialCanvasRect.width), Math.round(initialCanvasRect.height));
-        continue;
-      }
-      const rect = projectToScreenRect(obj, camera, initialCanvasRect);
-      if (rect) {
-        let parentLeft = 0;
-        let parentTop = 0;
-        if (obj.parent && obj.parent.type !== "Scene") {
-          const parentRect = projectToScreenRect(obj.parent, camera, initialCanvasRect);
-          if (parentRect) {
-            parentLeft = Math.round(parentRect.left);
-            parentTop = Math.round(parentRect.top);
+    let store = null;
+    let mirror = null;
+    let unpatch = null;
+    let selectionManager = null;
+    let currentApi;
+    try {
+      store = new ObjectStore();
+      mirror = new DomMirror(store, maxDomNodes);
+      mirror.setRoot(rootElement);
+      r3fLog("setup", "Store and mirror created");
+      ensureCustomElements(store);
+      store.registerTree(scene);
+      r3fLog("setup", `Registered scene tree: ${store.getCount()} objects`);
+      mirror.materializeSubtree(scene.uuid, initialDepth);
+      unpatch = patchObject3D(store, mirror);
+      setInteractionState(store, camera, gl, size);
+      r3fLog("setup", "Object3D patched, interaction state set");
+      selectionManager = new SelectionManager();
+      _selectionManager = selectionManager;
+      _highlighter = null;
+      exposeGlobalAPI(store);
+      r3fLog("bridge", "exposeGlobalAPI called \u2014 bridge is live, _ready=true");
+      currentApi = window.__R3F_DOM__;
+      _store3 = store;
+      _mirror = mirror;
+      const initialCanvasRect = canvas.getBoundingClientRect();
+      const allObjects = store.getFlatList();
+      for (const obj of allObjects) {
+        if (obj.userData?.__r3fdom_internal) continue;
+        const el = mirror.getElement(obj.uuid);
+        if (!el) continue;
+        if (obj.type === "Scene") {
+          setElementRect(el, 0, 0, Math.round(initialCanvasRect.width), Math.round(initialCanvasRect.height));
+          continue;
+        }
+        const rect = projectToScreenRect(obj, camera, initialCanvasRect);
+        if (rect) {
+          let parentLeft = 0;
+          let parentTop = 0;
+          if (obj.parent && obj.parent.type !== "Scene") {
+            const parentRect = projectToScreenRect(obj.parent, camera, initialCanvasRect);
+            if (parentRect) {
+              parentLeft = Math.round(parentRect.left);
+              parentTop = Math.round(parentRect.top);
+            }
           }
+          setElementRect(
+            el,
+            Math.round(rect.left) - parentLeft,
+            Math.round(rect.top) - parentTop,
+            Math.round(rect.width),
+            Math.round(rect.height)
+          );
         }
-        setElementRect(
-          el,
-          Math.round(rect.left) - parentLeft,
-          Math.round(rect.top) - parentTop,
-          Math.round(rect.width),
-          Math.round(rect.height)
-        );
       }
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      r3fLog("setup", "ThreeDom setup failed", err);
+      console.error("[react-three-dom] Setup failed:", err);
+      window.__R3F_DOM__ = {
+        _ready: false,
+        _error: errorMsg,
+        getByTestId: () => null,
+        getByUuid: () => null,
+        getByName: () => [],
+        getCount: () => 0,
+        getByType: () => [],
+        getByUserData: () => [],
+        getCountByType: () => 0,
+        getObjects: (ids) => {
+          const result = {};
+          for (const id of ids) result[id] = null;
+          return result;
+        },
+        snapshot: () => ({ timestamp: 0, objectCount: 0, tree: { uuid: "", name: "", type: "Scene", visible: true, position: [0, 0, 0], rotation: [0, 0, 0], scale: [1, 1, 1], children: [] } }),
+        inspect: () => null,
+        click: () => {
+        },
+        doubleClick: () => {
+        },
+        contextMenu: () => {
+        },
+        hover: () => {
+        },
+        drag: async () => {
+        },
+        wheel: () => {
+        },
+        pointerMiss: () => {
+        },
+        drawPath: async () => ({ eventCount: 0, pointCount: 0 }),
+        select: () => {
+        },
+        clearSelection: () => {
+        },
+        getSelection: () => [],
+        getObject3D: () => null,
+        version
+      };
+      currentApi = window.__R3F_DOM__;
     }
     return () => {
-      unpatch();
-      removeGlobalAPI();
+      r3fLog("setup", "ThreeDom cleanup started");
+      if (unpatch) unpatch();
+      removeGlobalAPI(currentApi);
       clearInteractionState();
-      selectionManager.dispose();
-      mirror.dispose();
-      store.dispose();
+      if (selectionManager) selectionManager.dispose();
+      if (mirror) mirror.dispose();
+      if (store) store.dispose();
       if (createdRoot && rootElement?.parentNode) {
         rootElement.parentNode.removeChild(rootElement);
       }
@@ -2203,69 +2606,75 @@ function ThreeDom({
       _mirror = null;
       _selectionManager = null;
       _highlighter = null;
+      if (debug) enableDebug(false);
+      r3fLog("setup", "ThreeDom cleanup complete");
     };
-  }, [scene, camera, gl, size, enabled, root, maxDomNodes, initialDepth]);
+  }, [scene, camera, gl, size, enabled, root, maxDomNodes, initialDepth, debug]);
   fiber.useFrame(() => {
     if (!enabled || !_store3 || !_mirror) return;
-    setInteractionState(_store3, camera, gl, size);
-    const store = _store3;
-    const mirror = _mirror;
-    const canvas = gl.domElement;
-    const canvasRect = canvas.getBoundingClientRect();
-    const start = performance.now();
-    const dirtyObjects = store.drainDirtyQueue();
-    for (const obj of dirtyObjects) {
-      store.update(obj);
-      mirror.syncAttributes(obj);
-    }
-    const budgetRemaining = timeBudgetMs - (performance.now() - start);
-    if (budgetRemaining > 0.1) {
-      const objects2 = store.getFlatList();
-      if (objects2.length > 0) {
-        const end = Math.min(cursorRef.current + batchSize, objects2.length);
-        for (let i = cursorRef.current; i < end; i++) {
-          if (performance.now() - start > timeBudgetMs) break;
-          const obj = objects2[i];
-          const changed = store.update(obj);
-          if (changed) mirror.syncAttributes(obj);
-        }
-        cursorRef.current = end >= objects2.length ? 0 : end;
+    try {
+      setInteractionState(_store3, camera, gl, size);
+      const store = _store3;
+      const mirror = _mirror;
+      const canvas = gl.domElement;
+      const canvasRect = canvas.getBoundingClientRect();
+      const start = performance.now();
+      const dirtyObjects = store.drainDirtyQueue();
+      for (const obj of dirtyObjects) {
+        store.update(obj);
+        mirror.syncAttributes(obj);
       }
-    }
-    const objects = store.getFlatList();
-    if (objects.length > 0) {
-      const posEnd = Math.min(positionCursorRef.current + 50, objects.length);
-      for (let i = positionCursorRef.current; i < posEnd; i++) {
-        const obj = objects[i];
-        if (obj.userData?.__r3fdom_internal) continue;
-        const el = mirror.getElement(obj.uuid);
-        if (!el) continue;
-        if (obj.type === "Scene") {
-          setElementRect(el, 0, 0, Math.round(canvasRect.width), Math.round(canvasRect.height));
-          continue;
+      const budgetRemaining = timeBudgetMs - (performance.now() - start);
+      if (budgetRemaining > 0.1) {
+        const objects2 = store.getFlatList();
+        if (objects2.length > 0) {
+          const end = Math.min(cursorRef.current + batchSize, objects2.length);
+          for (let i = cursorRef.current; i < end; i++) {
+            if (performance.now() - start > timeBudgetMs) break;
+            const obj = objects2[i];
+            const changed = store.update(obj);
+            if (changed) mirror.syncAttributes(obj);
+          }
+          cursorRef.current = end >= objects2.length ? 0 : end;
         }
-        const rect = projectToScreenRect(obj, camera, canvasRect);
-        if (rect) {
-          let parentLeft = 0;
-          let parentTop = 0;
-          if (obj.parent && obj.parent.type !== "Scene") {
-            const parentRect = projectToScreenRect(obj.parent, camera, canvasRect);
-            if (parentRect) {
-              parentLeft = Math.round(parentRect.left);
-              parentTop = Math.round(parentRect.top);
+      }
+      const objects = store.getFlatList();
+      if (objects.length > 0) {
+        const posEnd = Math.min(positionCursorRef.current + 50, objects.length);
+        for (let i = positionCursorRef.current; i < posEnd; i++) {
+          const obj = objects[i];
+          if (obj.userData?.__r3fdom_internal) continue;
+          const el = mirror.getElement(obj.uuid);
+          if (!el) continue;
+          if (obj.type === "Scene") {
+            setElementRect(el, 0, 0, Math.round(canvasRect.width), Math.round(canvasRect.height));
+            continue;
+          }
+          const rect = projectToScreenRect(obj, camera, canvasRect);
+          if (rect) {
+            let parentLeft = 0;
+            let parentTop = 0;
+            if (obj.parent && obj.parent.type !== "Scene") {
+              const parentRect = projectToScreenRect(obj.parent, camera, canvasRect);
+              if (parentRect) {
+                parentLeft = Math.round(parentRect.left);
+                parentTop = Math.round(parentRect.top);
+              }
             }
+            const l = Math.round(rect.left) - parentLeft;
+            const t = Math.round(rect.top) - parentTop;
+            const w = Math.round(rect.width);
+            const h = Math.round(rect.height);
+            setElementRect(el, l, t, w, h);
+            if (el.style.display === "none") el.style.display = "block";
+          } else {
+            if (el.style.display !== "none") el.style.display = "none";
           }
-          const l = Math.round(rect.left) - parentLeft;
-          const t = Math.round(rect.top) - parentTop;
-          const w = Math.round(rect.width);
-          const h = Math.round(rect.height);
-          setElementRect(el, l, t, w, h);
-          if (el.style.display === "none") el.style.display = "block";
-        } else {
-          if (el.style.display !== "none") el.style.display = "none";
         }
+        positionCursorRef.current = posEnd >= objects.length ? 0 : posEnd;
       }
-      positionCursorRef.current = posEnd >= objects.length ? 0 : posEnd;
+    } catch (err) {
+      r3fLog("sync", "Per-frame sync error", err);
     }
   });
   return null;
@@ -2625,11 +3034,13 @@ exports.TAG_MAP = TAG_MAP;
 exports.ThreeDom = ThreeDom;
 exports.ThreeElement = ThreeElement;
 exports.applyAttributes = applyAttributes;
+exports.circlePath = circlePath;
 exports.click3D = click3D;
 exports.computeAttributes = computeAttributes;
 exports.contextMenu3D = contextMenu3D;
 exports.createFlatSnapshot = createFlatSnapshot;
 exports.createSnapshot = createSnapshot;
+exports.curvePath = curvePath;
 exports.dispatchClick = dispatchClick;
 exports.dispatchContextMenu = dispatchContextMenu;
 exports.dispatchDoubleClick = dispatchDoubleClick;
@@ -2640,6 +3051,8 @@ exports.dispatchUnhover = dispatchUnhover;
 exports.dispatchWheel = dispatchWheel;
 exports.doubleClick3D = doubleClick3D;
 exports.drag3D = drag3D;
+exports.drawPath = drawPath;
+exports.enableDebug = enableDebug;
 exports.ensureCustomElements = ensureCustomElements;
 exports.getHighlighter = getHighlighter;
 exports.getMirror = getMirror;
@@ -2647,13 +3060,17 @@ exports.getSelectionManager = getSelectionManager;
 exports.getStore = getStore2;
 exports.getTagForType = getTagForType;
 exports.hover3D = hover3D;
+exports.isDebugEnabled = isDebugEnabled;
 exports.isInFrustum = isInFrustum;
 exports.isPatched = isPatched;
+exports.linePath = linePath;
 exports.patchObject3D = patchObject3D;
 exports.pointerMiss3D = pointerMiss3D;
 exports.previewDragWorldDelta = previewDragWorldDelta;
 exports.projectAllSamplePoints = projectAllSamplePoints;
 exports.projectToScreen = projectToScreen;
+exports.r3fLog = r3fLog;
+exports.rectPath = rectPath;
 exports.resolveObject = resolveObject;
 exports.restoreObject3D = restoreObject3D;
 exports.screenDeltaToWorld = screenDeltaToWorld;