@react-three-dom/core 0.2.0 → 0.3.0

package/dist/index.cjs

@@ -3,9 +3,10 @@
 var three = require('three');
 var react = require('react');
 var fiber = require('@react-three/fiber');
+var threeMeshBvh = require('three-mesh-bvh');
 
 // src/version.ts
-var version = "0.1.0";
+var version = "0.3.0";
 
 // src/debug.ts
 var _enabled = false;
@@ -39,6 +40,10 @@ function extractMetadata(obj) {
     childrenUuids: obj.children.map((c) => c.uuid),
     boundsDirty: true
   };
+  extractStaticFields(obj, meta);
+  return meta;
+}
+function extractStaticFields(obj, meta) {
   try {
     if ("geometry" in obj) {
       const geom = obj.geometry;
@@ -76,13 +81,79 @@ function extractMetadata(obj) {
     }
   } catch {
   }
-  return meta;
+  try {
+    if (obj instanceof three.PerspectiveCamera) {
+      meta.fov = obj.fov;
+      meta.near = obj.near;
+      meta.far = obj.far;
+      meta.zoom = obj.zoom;
+    } else if (obj instanceof three.OrthographicCamera) {
+      meta.near = obj.near;
+      meta.far = obj.far;
+      meta.zoom = obj.zoom;
+    }
+  } catch {
+  }
 }
-function hasChanged(prev, curr) {
-  return prev.visible !== curr.visible || prev.name !== curr.name || prev.testId !== curr.testId || prev.position[0] !== curr.position[0] || prev.position[1] !== curr.position[1] || prev.position[2] !== curr.position[2] || prev.rotation[0] !== curr.rotation[0] || prev.rotation[1] !== curr.rotation[1] || prev.rotation[2] !== curr.rotation[2] || prev.scale[0] !== curr.scale[0] || prev.scale[1] !== curr.scale[1] || prev.scale[2] !== curr.scale[2] || prev.parentUuid !== curr.parentUuid || prev.childrenUuids.length !== curr.childrenUuids.length || prev.instanceCount !== curr.instanceCount;
+function updateDynamicFields(obj, meta) {
+  let changed = false;
+  if (meta.visible !== obj.visible) {
+    meta.visible = obj.visible;
+    changed = true;
+  }
+  if (meta.name !== obj.name) {
+    meta.name = obj.name;
+    changed = true;
+  }
+  const testId = obj.userData?.testId;
+  if (meta.testId !== testId) {
+    meta.testId = testId;
+    changed = true;
+  }
+  const p = obj.position;
+  if (meta.position[0] !== p.x || meta.position[1] !== p.y || meta.position[2] !== p.z) {
+    meta.position[0] = p.x;
+    meta.position[1] = p.y;
+    meta.position[2] = p.z;
+    changed = true;
+  }
+  const r = obj.rotation;
+  if (meta.rotation[0] !== r.x || meta.rotation[1] !== r.y || meta.rotation[2] !== r.z) {
+    meta.rotation[0] = r.x;
+    meta.rotation[1] = r.y;
+    meta.rotation[2] = r.z;
+    changed = true;
+  }
+  const s = obj.scale;
+  if (meta.scale[0] !== s.x || meta.scale[1] !== s.y || meta.scale[2] !== s.z) {
+    meta.scale[0] = s.x;
+    meta.scale[1] = s.y;
+    meta.scale[2] = s.z;
+    changed = true;
+  }
+  const parentUuid = obj.parent?.uuid ?? null;
+  if (meta.parentUuid !== parentUuid) {
+    meta.parentUuid = parentUuid;
+    changed = true;
+  }
+  const children = obj.children;
+  const cached = meta.childrenUuids;
+  if (cached.length !== children.length) {
+    meta.childrenUuids = children.map((c) => c.uuid);
+    changed = true;
+  } else {
+    for (let i = 0; i < cached.length; i++) {
+      if (cached[i] !== children[i].uuid) {
+        meta.childrenUuids = children.map((c) => c.uuid);
+        changed = true;
+        break;
+      }
+    }
+  }
+  return changed;
 }
 var _box3 = new three.Box3();
-function inspectObject(obj, metadata) {
+function inspectObject(obj, metadata, options) {
   let worldMatrix = Array(16).fill(0);
   let boundsMin = [0, 0, 0];
   let boundsMax = [0, 0, 0];
@@ -109,12 +180,13 @@ function inspectObject(obj, metadata) {
   try {
     if ("geometry" in obj) {
       const geom = obj.geometry;
-      if (geom instanceof three.BufferGeometry) {
+      if (geom instanceof three.BufferGeometry && geom.attributes) {
         const geoInspection = {
           type: geom.type,
           attributes: {}
         };
         for (const [name, attr] of Object.entries(geom.attributes)) {
+          if (!attr) continue;
           geoInspection.attributes[name] = {
             itemSize: attr.itemSize,
             count: attr.count
@@ -123,6 +195,15 @@ function inspectObject(obj, metadata) {
         if (geom.index) {
           geoInspection.index = { count: geom.index.count };
         }
+        if (options?.includeGeometryData) {
+          const posAttr = geom.getAttribute("position");
+          if (posAttr?.array) {
+            geoInspection.positionData = Array.from(posAttr.array);
+          }
+          if (geom.index?.array) {
+            geoInspection.indexData = Array.from(geom.index.array);
+          }
+        }
         geom.computeBoundingSphere();
         const sphere = geom.boundingSphere;
         if (sphere) {
@@ -140,6 +221,7 @@ function inspectObject(obj, metadata) {
   try {
     if ("material" in obj) {
       const rawMat = obj.material;
+      if (!rawMat) throw new Error("disposed");
       const mat = Array.isArray(rawMat) ? rawMat[0] : rawMat;
       if (mat instanceof three.Material) {
         const matInspection = {
@@ -197,6 +279,10 @@ var ObjectStore = class {
     this._listeners = [];
     // Track the root scene(s) for scoping
     this._trackedRoots = /* @__PURE__ */ new WeakSet();
+    // ---- Async registration state ----
+    this._asyncRegQueue = [];
+    this._asyncRegHandle = null;
+    this._asyncRegBatchSize = 1e3;
   }
   // -------------------------------------------------------------------------
   // Registration
@@ -204,6 +290,7 @@ var ObjectStore = class {
   /**
    * Register a single object into the store.
    * Populates Tier 1 metadata and all indexes.
+   * Tags the object with `__r3fdom_tracked = true` for O(1) scene membership checks.
    */
   register(obj) {
     if (obj.userData?.__r3fdom_internal) {
@@ -215,6 +302,7 @@ var ObjectStore = class {
     this._metaByObject.set(obj, meta);
     this._objectByUuid.set(meta.uuid, obj);
     this._flatListDirty = true;
+    obj.userData.__r3fdom_tracked = true;
     if (meta.testId) {
       this._objectsByTestId.set(meta.testId, obj);
     }
@@ -233,10 +321,8 @@ var ObjectStore = class {
     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.
+   * Register an entire subtree (object + all descendants) synchronously.
+   * Prefer `registerTreeAsync` for large scenes (100k+) to avoid blocking.
    */
   registerTree(root) {
     this._trackedRoots.add(root);
@@ -248,8 +334,64 @@ var ObjectStore = class {
       }
     });
   }
+  /**
+   * Register an entire subtree asynchronously using requestIdleCallback.
+   * Processes ~1000 objects per idle slice to avoid blocking the main thread.
+   *
+   * IMPORTANT: install patchObject3D BEFORE calling this so that objects
+   * added to the scene during async registration are caught by the patch.
+   *
+   * Returns a cancel function. Also cancelled automatically by dispose().
+   */
+  registerTreeAsync(root) {
+    this._trackedRoots.add(root);
+    const queue = [];
+    root.traverse((obj) => queue.push(obj));
+    this._asyncRegQueue = queue;
+    r3fLog("store", `registerTreeAsync: ${queue.length} objects queued`);
+    this._scheduleRegChunk();
+    return () => this._cancelAsyncRegistration();
+  }
+  _scheduleRegChunk() {
+    if (this._asyncRegQueue.length === 0) {
+      this._asyncRegHandle = null;
+      r3fLog("store", `registerTreeAsync complete: ${this.getCount()} objects registered`);
+      return;
+    }
+    const callback = (deadline) => {
+      const hasTime = deadline ? () => deadline.timeRemaining() > 1 : () => true;
+      let processed = 0;
+      while (this._asyncRegQueue.length > 0 && processed < this._asyncRegBatchSize && hasTime()) {
+        const obj = this._asyncRegQueue.shift();
+        try {
+          this.register(obj);
+        } catch (err) {
+          r3fLog("store", `registerTreeAsync: failed to register "${obj.name || obj.uuid}"`, err);
+        }
+        processed++;
+      }
+      this._scheduleRegChunk();
+    };
+    if (typeof requestIdleCallback === "function") {
+      this._asyncRegHandle = requestIdleCallback(callback, { timeout: 50 });
+    } else {
+      this._asyncRegHandle = setTimeout(callback, 4);
+    }
+  }
+  _cancelAsyncRegistration() {
+    if (this._asyncRegHandle !== null) {
+      if (typeof cancelIdleCallback === "function") {
+        cancelIdleCallback(this._asyncRegHandle);
+      } else {
+        clearTimeout(this._asyncRegHandle);
+      }
+      this._asyncRegHandle = null;
+    }
+    this._asyncRegQueue = [];
+  }
   /**
    * Unregister a single object from the store.
+   * Clears the `__r3fdom_tracked` flag.
    */
   unregister(obj) {
     const meta = this._metaByObject.get(obj);
@@ -258,6 +400,7 @@ var ObjectStore = class {
     this._objectByUuid.delete(meta.uuid);
     this._dirtyQueue.delete(obj);
     this._flatListDirty = true;
+    delete obj.userData.__r3fdom_tracked;
     if (meta.testId) {
       this._objectsByTestId.delete(meta.testId);
     }
@@ -288,49 +431,50 @@ var ObjectStore = class {
   // Tier 1: Update (compare-and-set, returns true if changed)
   // -------------------------------------------------------------------------
   /**
-   * Refresh Tier 1 metadata from the live Three.js object.
+   * Refresh dynamic Tier 1 fields from the live Three.js object.
+   * Only reads transform, visibility, children count, and parent —
+   * skips static fields (geometry, material) that don't change per-frame.
+   * Mutates metadata in-place to avoid allocation.
    * 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;
-    let curr;
+    const meta = this._metaByObject.get(obj);
+    if (!meta) return false;
+    let changed;
     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);
-      }
-      if (prev.name !== curr.name) {
-        if (prev.name) {
-          const nameSet = this._objectsByName.get(prev.name);
-          if (nameSet) {
-            nameSet.delete(obj);
-            if (nameSet.size === 0) this._objectsByName.delete(prev.name);
-          }
+      const prevTestId = meta.testId;
+      const prevName = meta.name;
+      changed = updateDynamicFields(obj, meta);
+      if (changed) {
+        if (prevTestId !== meta.testId) {
+          r3fLog("store", `testId changed: "${prevTestId}" \u2192 "${meta.testId}" (${meta.type})`);
+          if (prevTestId) this._objectsByTestId.delete(prevTestId);
+          if (meta.testId) this._objectsByTestId.set(meta.testId, obj);
         }
-        if (curr.name) {
-          let nameSet = this._objectsByName.get(curr.name);
-          if (!nameSet) {
-            nameSet = /* @__PURE__ */ new Set();
-            this._objectsByName.set(curr.name, nameSet);
+        if (prevName !== meta.name) {
+          if (prevName) {
+            const nameSet = this._objectsByName.get(prevName);
+            if (nameSet) {
+              nameSet.delete(obj);
+              if (nameSet.size === 0) this._objectsByName.delete(prevName);
+            }
+          }
+          if (meta.name) {
+            let nameSet = this._objectsByName.get(meta.name);
+            if (!nameSet) {
+              nameSet = /* @__PURE__ */ new Set();
+              this._objectsByName.set(meta.name, nameSet);
+            }
+            nameSet.add(obj);
           }
-          nameSet.add(obj);
         }
+        this._emit({ type: "update", object: obj, metadata: meta });
       }
-      this._metaByObject.set(obj, curr);
-      this._emit({ type: "update", object: obj, metadata: curr });
-      return true;
+    } catch (err) {
+      r3fLog("store", `update: updateDynamicFields failed for "${obj.name || obj.uuid}"`, err);
+      return false;
     }
-    return false;
+    return changed;
   }
   // -------------------------------------------------------------------------
   // Tier 2: On-demand inspection (never cached)
@@ -339,13 +483,14 @@ var ObjectStore = class {
    * Compute full inspection data from a live Three.js object.
    * This reads geometry buffers, material properties, world bounds, etc.
    * Cost: 0.1–2ms depending on geometry complexity.
+   * Pass { includeGeometryData: true } to include vertex positions and triangle indices (higher cost for large meshes).
    */
-  inspect(idOrUuid) {
+  inspect(idOrUuid, options) {
     const obj = this.getObject3D(idOrUuid);
     if (!obj) return null;
     const meta = this._metaByObject.get(obj);
     if (!meta) return null;
-    return inspectObject(obj, meta);
+    return inspectObject(obj, meta, options);
   }
   // -------------------------------------------------------------------------
   // Lookups (O(1))
@@ -373,6 +518,23 @@ var ObjectStore = class {
     }
     return results;
   }
+  /** Get direct children of an object by testId or uuid. Returns empty array if not found. */
+  getChildren(idOrUuid) {
+    const meta = this.getByTestId(idOrUuid) ?? this.getByUuid(idOrUuid);
+    if (!meta) return [];
+    const results = [];
+    for (const childUuid of meta.childrenUuids) {
+      const childMeta = this.getByUuid(childUuid);
+      if (childMeta) results.push(childMeta);
+    }
+    return results;
+  }
+  /** Get parent of an object by testId or uuid. Returns null if not found or if root. */
+  getParent(idOrUuid) {
+    const meta = this.getByTestId(idOrUuid) ?? this.getByUuid(idOrUuid);
+    if (!meta || meta.parentUuid === null) return null;
+    return this.getByUuid(meta.parentUuid);
+  }
   /**
    * 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).
@@ -400,6 +562,30 @@ var ObjectStore = class {
     }
     return results;
   }
+  /**
+   * Get all objects with a given geometry type (e.g. "BoxGeometry", "BufferGeometry").
+   * Linear scan — O(n). Only meshes/points/lines have geometryType.
+   */
+  getByGeometryType(type) {
+    const results = [];
+    for (const obj of this.getFlatList()) {
+      const meta = this._metaByObject.get(obj);
+      if (meta && meta.geometryType === type) results.push(meta);
+    }
+    return results;
+  }
+  /**
+   * Get all objects with a given material type (e.g. "MeshStandardMaterial").
+   * Linear scan — O(n). Only meshes/points/lines have materialType.
+   */
+  getByMaterialType(type) {
+    const results = [];
+    for (const obj of this.getFlatList()) {
+      const meta = this._metaByObject.get(obj);
+      if (meta && meta.materialType === 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.
@@ -452,13 +638,16 @@ var ObjectStore = class {
     return this._trackedRoots.has(obj);
   }
   /**
-   * Walk up from `obj` to see if any ancestor is a tracked root.
-   * Used by Object3D.add/remove patch to determine if an object
-   * belongs to a monitored scene.
+   * Check if an object belongs to a tracked scene.
+   * Fast path: checks the `__r3fdom_tracked` flag set during register (O(1)).
+   * Fallback: walks up the parent chain to find a tracked root.
+   * The fallback is needed for newly added objects that aren't registered yet.
    */
   isInTrackedScene(obj) {
-    let current = obj;
+    if (obj.userData?.__r3fdom_tracked) return true;
+    let current = obj.parent;
     while (current) {
+      if (current.userData?.__r3fdom_tracked) return true;
       if (this._trackedRoots.has(current)) return true;
       current = current.parent;
     }
@@ -518,10 +707,39 @@ var ObjectStore = class {
     }
   }
   // -------------------------------------------------------------------------
+  // GC: sweep orphaned objects
+  // -------------------------------------------------------------------------
+  /**
+   * Sweep objects in `_objectByUuid` that are no longer in any tracked scene.
+   * This catches objects that were removed from the scene graph without
+   * triggering the patched Object3D.remove (e.g. direct `.children` splice,
+   * or the remove hook failing silently).
+   *
+   * At BIM scale, call this periodically (e.g. every 30s or after a floor
+   * load/unload) to prevent memory leaks from retained Object3D references.
+   *
+   * Returns the number of orphans cleaned up.
+   */
+  sweepOrphans() {
+    let swept = 0;
+    for (const [uuid, obj] of this._objectByUuid) {
+      if (!obj.parent && !this._trackedRoots.has(obj)) {
+        this.unregister(obj);
+        swept++;
+        r3fLog("store", `sweepOrphans: removed orphan "${obj.name || uuid}"`);
+      }
+    }
+    return swept;
+  }
+  // -------------------------------------------------------------------------
   // Cleanup
   // -------------------------------------------------------------------------
   /** Remove all tracked objects and reset state. */
   dispose() {
+    this._cancelAsyncRegistration();
+    for (const obj of this._objectByUuid.values()) {
+      if (obj.userData) delete obj.userData.__r3fdom_tracked;
+    }
     this._objectByUuid.clear();
     this._objectsByTestId.clear();
     this._objectsByName.clear();
@@ -738,7 +956,11 @@ var ATTRIBUTE_MAP = {
   "data-scale": (m) => serializeTuple(m.scale),
   "data-vertex-count": (m) => m.vertexCount !== void 0 ? String(m.vertexCount) : void 0,
   "data-triangle-count": (m) => m.triangleCount !== void 0 ? String(m.triangleCount) : void 0,
-  "data-instance-count": (m) => m.instanceCount !== void 0 ? String(m.instanceCount) : void 0
+  "data-instance-count": (m) => m.instanceCount !== void 0 ? String(m.instanceCount) : void 0,
+  "data-fov": (m) => m.fov !== void 0 ? String(m.fov) : void 0,
+  "data-near": (m) => m.near !== void 0 ? String(m.near) : void 0,
+  "data-far": (m) => m.far !== void 0 ? String(m.far) : void 0,
+  "data-zoom": (m) => m.zoom !== void 0 ? String(m.zoom) : void 0
 };
 var MANAGED_ATTRIBUTES = Object.keys(ATTRIBUTE_MAP);
 function serializeTuple(tuple) {
@@ -791,6 +1013,12 @@ var DomMirror = class {
     this._lruSize = 0;
     // UUID → parent UUID mapping for DOM tree structure
     this._parentMap = /* @__PURE__ */ new Map();
+    /** When true, mirror elements use pointer-events: auto so DevTools element picker can select them. */
+    this._inspectMode = false;
+    /** Async materialization state for inspect mode */
+    this._asyncQueue = [];
+    this._asyncIdleHandle = null;
+    this._asyncBatchSize = 200;
     this._store = store;
     this._maxNodes = maxNodes;
   }
@@ -804,6 +1032,29 @@ var DomMirror = class {
   setRoot(rootElement) {
     this._rootElement = rootElement;
   }
+  /**
+   * Enable or disable "inspect mode". When turning on, kicks off async
+   * chunked materialization so the full tree becomes browsable in the
+   * Elements tab without blocking the main thread.
+   *
+   * At BIM scale (100k-200k objects) the old synchronous loop would freeze
+   * the page for 2-10s. The new approach uses requestIdleCallback to
+   * spread work across idle frames (~200 nodes per idle slice, ~5ms each).
+   */
+  setInspectMode(on) {
+    if (this._inspectMode === on) return;
+    this._inspectMode = on;
+    if (on) {
+      this._startAsyncMaterialization();
+    } else {
+      this._cancelAsyncMaterialization();
+    }
+    r3fLog("inspect", "setInspectMode", { on, nodeCount: this._nodes.size });
+  }
+  /** Whether inspect mode is currently enabled. */
+  getInspectMode() {
+    return this._inspectMode;
+  }
   /**
    * Build the initial DOM tree from the scene.
    * Materializes the top 2 levels of the scene hierarchy.
@@ -832,7 +1083,7 @@ var DomMirror = class {
     }
     const tag = getTagForType(meta.type);
     const element = document.createElement(tag);
-    element.style.cssText = "display:block;position:absolute;pointer-events:none;box-sizing:border-box;";
+    element.style.cssText = "display:contents;";
     const prevAttrs = /* @__PURE__ */ new Map();
     applyAttributes(element, meta, prevAttrs);
     const lruNode = { uuid, prev: null, next: null };
@@ -859,15 +1110,39 @@ var DomMirror = class {
   /**
    * Remove a DOM node but keep JS metadata in the ObjectStore.
    * Called by LRU eviction or when an object is removed from the scene.
+   * Also dematerializes any materialized descendants so they don't become
+   * orphaned entries in the LRU / _nodes maps.
    */
   dematerialize(uuid) {
     const node = this._nodes.get(uuid);
     if (!node) return;
+    const descendants = this._collectMaterializedDescendants(uuid);
+    for (const descUuid of descendants) {
+      const descNode = this._nodes.get(descUuid);
+      if (descNode) {
+        this._lruRemove(descNode.lruNode);
+        this._nodes.delete(descUuid);
+        this._parentMap.delete(descUuid);
+      }
+    }
     node.element.remove();
     this._lruRemove(node.lruNode);
     this._nodes.delete(uuid);
     this._parentMap.delete(uuid);
   }
+  /**
+   * Collect all materialized descendants of a uuid by walking _parentMap.
+   */
+  _collectMaterializedDescendants(parentUuid) {
+    const result = [];
+    for (const [childUuid, pUuid] of this._parentMap) {
+      if (pUuid === parentUuid) {
+        result.push(childUuid);
+        result.push(...this._collectMaterializedDescendants(childUuid));
+      }
+    }
+    return result;
+  }
   // -------------------------------------------------------------------------
   // Structural updates (called by Object3D.add/remove patch)
   // -------------------------------------------------------------------------
@@ -943,6 +1218,22 @@ var DomMirror = class {
     }
     return null;
   }
+  /**
+   * Get or lazily materialize a DOM element for an object.
+   * Also materializes the ancestor chain so the element is correctly
+   * nested in the DOM tree. Used by InspectController so that
+   * hover/click always produces a valid mirror element regardless
+   * of whether async materialization has reached it yet.
+   */
+  getOrMaterialize(uuid) {
+    const existing = this._nodes.get(uuid);
+    if (existing) {
+      this._lruTouch(existing.lruNode);
+      return existing.element;
+    }
+    this._materializeAncestorChain(uuid);
+    return this.materialize(uuid);
+  }
   /**
    * Check if an object has a materialized DOM node.
    */
@@ -1005,6 +1296,7 @@ var DomMirror = class {
    * Remove all materialized DOM nodes and reset state.
    */
   dispose() {
+    this._cancelAsyncMaterialization();
     for (const [, node] of this._nodes) {
       node.element.remove();
     }
@@ -1037,6 +1329,78 @@ var DomMirror = class {
     }
   }
   // -------------------------------------------------------------------------
+  // Private: Ancestor chain materialization
+  // -------------------------------------------------------------------------
+  /**
+   * Materialize all ancestors of a uuid from root down, so the target
+   * element will be correctly nested when materialized.
+   */
+  _materializeAncestorChain(uuid) {
+    const chain = [];
+    let currentUuid = uuid;
+    while (currentUuid) {
+      if (this._nodes.has(currentUuid)) break;
+      const meta = this._store.getByUuid(currentUuid);
+      if (!meta) break;
+      chain.push(currentUuid);
+      currentUuid = meta.parentUuid;
+    }
+    for (let i = chain.length - 1; i > 0; i--) {
+      this.materialize(chain[i]);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Private: Async chunked materialization for inspect mode
+  // -------------------------------------------------------------------------
+  _startAsyncMaterialization() {
+    this._cancelAsyncMaterialization();
+    const flatList = this._store.getFlatList();
+    this._asyncQueue = [];
+    for (const obj of flatList) {
+      if (obj.userData?.__r3fdom_internal) continue;
+      if (this._nodes.has(obj.uuid)) continue;
+      this._asyncQueue.push(obj.uuid);
+    }
+    if (this._asyncQueue.length === 0) return;
+    r3fLog("inspect", `Async materialization started: ${this._asyncQueue.length} objects queued`);
+    this._scheduleAsyncChunk();
+  }
+  _cancelAsyncMaterialization() {
+    if (this._asyncIdleHandle !== null) {
+      if (typeof cancelIdleCallback === "function") {
+        cancelIdleCallback(this._asyncIdleHandle);
+      } else {
+        clearTimeout(this._asyncIdleHandle);
+      }
+      this._asyncIdleHandle = null;
+    }
+    this._asyncQueue = [];
+  }
+  _scheduleAsyncChunk() {
+    if (this._asyncQueue.length === 0) {
+      this._asyncIdleHandle = null;
+      r3fLog("inspect", `Async materialization complete: ${this._nodes.size} nodes materialized`);
+      return;
+    }
+    const callback = (deadline) => {
+      const hasTimeRemaining = deadline ? () => deadline.timeRemaining() > 2 : () => true;
+      let processed = 0;
+      while (this._asyncQueue.length > 0 && processed < this._asyncBatchSize && hasTimeRemaining()) {
+        const uuid = this._asyncQueue.shift();
+        if (!this._nodes.has(uuid)) {
+          this.materialize(uuid);
+        }
+        processed++;
+      }
+      this._scheduleAsyncChunk();
+    };
+    if (typeof requestIdleCallback === "function") {
+      this._asyncIdleHandle = requestIdleCallback(callback, { timeout: 100 });
+    } else {
+      this._asyncIdleHandle = setTimeout(callback, 16);
+    }
+  }
+  // -------------------------------------------------------------------------
   // Private: Selector → UUID resolution
   // -------------------------------------------------------------------------
   /**
@@ -2290,677 +2654,324 @@ var SelectionManager = class {
     this._listeners = [];
   }
 };
-
-// src/bridge/ThreeDom.tsx
-var _store3 = null;
-var _mirror = null;
-var _selectionManager = null;
-var _highlighter = null;
-function getStore2() {
-  return _store3;
-}
-function getMirror() {
-  return _mirror;
-}
-function getSelectionManager() {
-  return _selectionManager;
-}
-function getHighlighter() {
-  return _highlighter;
-}
-var _box = /* @__PURE__ */ new three.Box3();
-var _v = /* @__PURE__ */ new three.Vector3();
-var _corners = Array.from({ length: 8 }, () => new three.Vector3());
-function projectToScreenRect(obj, camera, canvasRect) {
-  _box.setFromObject(obj);
-  if (_box.isEmpty()) return null;
-  const { min, max } = _box;
-  _corners[0].set(min.x, min.y, min.z);
-  _corners[1].set(min.x, min.y, max.z);
-  _corners[2].set(min.x, max.y, min.z);
-  _corners[3].set(min.x, max.y, max.z);
-  _corners[4].set(max.x, min.y, min.z);
-  _corners[5].set(max.x, min.y, max.z);
-  _corners[6].set(max.x, max.y, min.z);
-  _corners[7].set(max.x, max.y, max.z);
-  let sxMin = Infinity, syMin = Infinity;
-  let sxMax = -Infinity, syMax = -Infinity;
-  let anyInFront = false;
-  let anyBehind = false;
-  for (const corner of _corners) {
-    _v.copy(corner).project(camera);
-    if (_v.z >= 1) {
-      anyBehind = true;
-      continue;
-    }
-    anyInFront = true;
-    const sx = (_v.x + 1) / 2 * canvasRect.width;
-    const sy = (1 - _v.y) / 2 * canvasRect.height;
-    sxMin = Math.min(sxMin, sx);
-    syMin = Math.min(syMin, sy);
-    sxMax = Math.max(sxMax, sx);
-    syMax = Math.max(syMax, sy);
-  }
-  if (!anyInFront) return null;
-  if (anyBehind) {
-    sxMin = Math.min(sxMin, 0);
-    syMin = Math.min(syMin, 0);
-    sxMax = Math.max(sxMax, canvasRect.width);
-    syMax = Math.max(syMax, canvasRect.height);
-  }
-  sxMin = Math.max(0, sxMin);
-  syMin = Math.max(0, syMin);
-  sxMax = Math.min(canvasRect.width, sxMax);
-  syMax = Math.min(canvasRect.height, syMax);
-  const w = sxMax - sxMin;
-  const h = syMax - syMin;
-  if (w < 1 || h < 1) return null;
-  return { left: sxMin, top: syMin, width: w, height: h };
-}
-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) => {
-      click3D(idOrUuid);
-    },
-    doubleClick: (idOrUuid) => {
-      doubleClick3D(idOrUuid);
-    },
-    contextMenu: (idOrUuid) => {
-      contextMenu3D(idOrUuid);
-    },
-    hover: (idOrUuid) => {
-      hover3D(idOrUuid);
-    },
-    drag: async (idOrUuid, delta) => {
-      await drag3D(idOrUuid, delta);
-    },
-    wheel: (idOrUuid, options) => {
-      wheel3D(idOrUuid, options);
-    },
-    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);
-    },
-    clearSelection: () => {
-      _selectionManager?.clearSelection();
-    },
-    getSelection: () => _selectionManager ? _selectionManager.getSelected().map((o) => o.uuid) : [],
-    getObject3D: (idOrUuid) => store.getObject3D(idOrUuid),
-    version
+var HOVER_FILL_COLOR = 7317724;
+var HOVER_FILL_OPACITY = 0.66;
+var SELECTION_FILL_COLOR = 7317724;
+var SELECTION_FILL_OPACITY = 0.75;
+var SELECTION_BBOX_COLOR = 7317724;
+var SELECTION_BBOX_OPACITY = 0.3;
+var _box33 = /* @__PURE__ */ new three.Box3();
+function hasRenderableGeometry(obj) {
+  return obj.isMesh === true || obj.isLine === true || obj.isPoints === true;
+}
+function collectHighlightTargets(obj) {
+  if (hasRenderableGeometry(obj)) return [obj];
+  const targets = [];
+  obj.traverse((child) => {
+    if (child === obj) return;
+    if (child.userData?.__r3fdom_internal) return;
+    if (hasRenderableGeometry(child)) targets.push(child);
+  });
+  return targets;
+}
+function markInternal(obj) {
+  obj.userData.__r3fdom_internal = true;
+  obj.raycast = () => {
+  };
+  obj.traverse((child) => {
+    child.userData.__r3fdom_internal = true;
+    child.raycast = () => {
+    };
+  });
+}
+function _syncGroupTransform(source, highlightRoot) {
+  source.updateWorldMatrix(true, false);
+  source.matrixWorld.decompose(
+    highlightRoot.position,
+    highlightRoot.quaternion,
+    highlightRoot.scale
+  );
+}
+function _attachRenderSync(source, highlightRoot) {
+  highlightRoot.matrixAutoUpdate = false;
+  highlightRoot.updateMatrixWorld = (force) => {
+    source.updateWorldMatrix(true, false);
+    highlightRoot.matrixWorld.copy(source.matrixWorld);
+    for (const child of highlightRoot.children) {
+      child.updateMatrixWorld(force);
+    }
   };
-  window.__R3F_DOM__ = api;
 }
-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)");
+function createHighlightMesh(source, fillColor, fillOpacity) {
+  const geom = source.geometry;
+  if (!geom) return null;
+  const group = new three.Object3D();
+  const disposables = [];
+  const fillMat = new three.MeshBasicMaterial({
+    color: fillColor,
+    transparent: true,
+    opacity: fillOpacity,
+    depthTest: false,
+    depthWrite: false,
+    side: three.DoubleSide
+  });
+  disposables.push(fillMat);
+  const fillMesh = new three.Mesh(geom, fillMat);
+  fillMesh.scale.setScalar(1.005);
+  fillMesh.raycast = () => {
+  };
+  group.add(fillMesh);
+  source.updateWorldMatrix(true, false);
+  source.matrixWorld.decompose(group.position, group.quaternion, group.scale);
+  markInternal(group);
+  _attachRenderSync(source, group);
+  return { root: group, disposables };
+}
+function createBoundingBoxHighlight(obj) {
+  _box33.makeEmpty();
+  const targets = collectHighlightTargets(obj);
+  if (targets.length === 0) return null;
+  for (const target of targets) {
+    target.updateWorldMatrix(true, false);
+    const geom = target.geometry;
+    if (geom) {
+      if (!geom.boundingBox) geom.computeBoundingBox();
+      if (geom.boundingBox) {
+        const childBox = geom.boundingBox.clone();
+        childBox.applyMatrix4(target.matrixWorld);
+        _box33.union(childBox);
       }
-    });
-  } else {
-    delete window.__R3F_DOM__;
-    r3fLog("bridge", "Global API removed (immediate)");
+    }
   }
+  if (_box33.isEmpty()) return null;
+  const size = _box33.getSize(new three.Vector3());
+  const center = _box33.getCenter(new three.Vector3());
+  const disposables = [];
+  const boxGeom = new three.BoxGeometry(size.x, size.y, size.z);
+  disposables.push(boxGeom);
+  const fillMat = new three.MeshBasicMaterial({
+    color: SELECTION_BBOX_COLOR,
+    transparent: true,
+    opacity: SELECTION_BBOX_OPACITY,
+    depthTest: false,
+    depthWrite: false,
+    side: three.DoubleSide
+  });
+  disposables.push(fillMat);
+  const fillMesh = new three.Mesh(boxGeom, fillMat);
+  fillMesh.raycast = () => {
+  };
+  const edgesGeom = new three.EdgesGeometry(boxGeom);
+  disposables.push(edgesGeom);
+  const edgeMat = new three.LineBasicMaterial({
+    color: SELECTION_BBOX_COLOR,
+    transparent: true,
+    opacity: 0.5,
+    depthTest: false,
+    depthWrite: false
+  });
+  disposables.push(edgeMat);
+  const edgeMesh = new three.LineSegments(edgesGeom, edgeMat);
+  edgeMesh.raycast = () => {
+  };
+  const group = new three.Object3D();
+  group.add(fillMesh);
+  group.add(edgeMesh);
+  group.position.copy(center);
+  group.renderOrder = 998;
+  markInternal(group);
+  group.matrixAutoUpdate = false;
+  group.updateMatrixWorld = (force) => {
+    _box33.makeEmpty();
+    for (const target of targets) {
+      target.updateWorldMatrix(true, false);
+      const g = target.geometry;
+      if (g) {
+        if (!g.boundingBox) g.computeBoundingBox();
+        if (g.boundingBox) {
+          const childBox = g.boundingBox.clone();
+          childBox.applyMatrix4(target.matrixWorld);
+          _box33.union(childBox);
+        }
+      }
+    }
+    if (!_box33.isEmpty()) {
+      const s = _box33.getSize(new three.Vector3());
+      const c = _box33.getCenter(new three.Vector3());
+      group.position.copy(c);
+      group.scale.set(
+        s.x / size.x || 1,
+        s.y / size.y || 1,
+        s.z / size.z || 1
+      );
+    }
+    group.updateMatrix();
+    group.matrixWorld.copy(group.matrix);
+    for (const child of group.children) {
+      child.updateMatrixWorld(force);
+    }
+  };
+  return { root: group, disposables };
 }
-function setElementRect(el, l, t, w, h) {
-  const d = el.dataset;
-  if (d._l !== String(l) || d._t !== String(t) || d._w !== String(w) || d._h !== String(h)) {
-    el.style.left = `${l}px`;
-    el.style.top = `${t}px`;
-    el.style.width = `${w}px`;
-    el.style.height = `${h}px`;
-    d._l = String(l);
-    d._t = String(t);
-    d._w = String(w);
-    d._h = String(h);
+var Highlighter = class {
+  constructor(_options = {}) {
+    this._scene = null;
+    this._unsubscribe = null;
+    this._hoverEntries = [];
+    this._hoverTarget = null;
+    this._selectedEntries = /* @__PURE__ */ new Map();
+    this._hoverPollId = null;
+    this._lastHoveredUuid = null;
+    this._store = null;
   }
-}
-function ThreeDom({
-  root = "#three-dom-root",
-  batchSize = 500,
-  timeBudgetMs = 0.5,
-  maxDomNodes = 2e3,
-  initialDepth = 3,
-  enabled = true,
-  debug = false
-} = {}) {
-  const scene = fiber.useThree((s) => s.scene);
-  const camera = fiber.useThree((s) => s.camera);
-  const gl = fiber.useThree((s) => s.gl);
-  const size = fiber.useThree((s) => s.size);
-  const cursorRef = react.useRef(0);
-  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;
-    let createdRoot = false;
-    if (typeof root === "string") {
-      rootElement = document.querySelector(root);
-    } else {
-      rootElement = root;
-    }
-    if (!rootElement) {
-      rootElement = document.createElement("div");
-      rootElement.id = typeof root === "string" ? root.replace(/^#/, "") : "three-dom-root";
-      createdRoot = true;
-    }
-    canvasParent.style.position = canvasParent.style.position || "relative";
-    canvasParent.appendChild(rootElement);
-    rootElement.style.cssText = [
-      "position: absolute",
-      "top: 0",
-      "left: 0",
-      "width: 100%",
-      "height: 100%",
-      "pointer-events: none",
-      "overflow: hidden",
-      "z-index: 10"
-    ].join(";");
-    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)
-          );
-        }
-      }
-    } 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 () => {
-      r3fLog("setup", "ThreeDom cleanup started");
-      if (unpatch) unpatch();
-      removeGlobalAPI(currentApi);
-      clearInteractionState();
-      if (selectionManager) selectionManager.dispose();
-      if (mirror) mirror.dispose();
-      if (store) store.dispose();
-      if (createdRoot && rootElement?.parentNode) {
-        rootElement.parentNode.removeChild(rootElement);
-      }
-      _store3 = null;
-      _mirror = null;
-      _selectionManager = null;
-      _highlighter = null;
-      if (debug) enableDebug(false);
-      r3fLog("setup", "ThreeDom cleanup complete");
-    };
-  }, [scene, camera, gl, size, enabled, root, maxDomNodes, initialDepth, debug]);
-  fiber.useFrame(() => {
-    if (!enabled || !_store3 || !_mirror) return;
-    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 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 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";
-          }
-        }
-        positionCursorRef.current = posEnd >= objects.length ? 0 : posEnd;
-      }
-    } catch (err) {
-      r3fLog("sync", "Per-frame sync error", err);
-    }
-  });
-  return null;
-}
-var COLORS = {
-  /** Content area — same blue as Chrome DevTools element highlight */
-  content: "rgba(111, 168, 220, 0.66)",
-  /** Slightly dimmer for children of a selected parent */
-  contentChild: "rgba(111, 168, 220, 0.33)",
-  /** Hover highlight — lighter blue */
-  hover: "rgba(111, 168, 220, 0.4)",
-  /** Tooltip background */
-  tooltipBg: "rgba(36, 36, 36, 0.9)",
-  /** Tooltip text */
-  tooltipText: "#fff",
-  /** Tooltip tag color */
-  tooltipTag: "#e776e0",
-  /** Tooltip dimensions color */
-  tooltipDim: "#c5c5c5",
-  /** Border for selected elements */
-  border: "rgba(111, 168, 220, 0.9)"
-};
-var _box2 = /* @__PURE__ */ new three.Box3();
-var _v2 = /* @__PURE__ */ new three.Vector3();
-var _corners2 = Array.from({ length: 8 }, () => new three.Vector3());
-function projectBoundsToScreen(obj, camera, canvas) {
-  _box2.setFromObject(obj);
-  if (_box2.isEmpty()) return null;
-  const { min, max } = _box2;
-  _corners2[0].set(min.x, min.y, min.z);
-  _corners2[1].set(min.x, min.y, max.z);
-  _corners2[2].set(min.x, max.y, min.z);
-  _corners2[3].set(min.x, max.y, max.z);
-  _corners2[4].set(max.x, min.y, min.z);
-  _corners2[5].set(max.x, min.y, max.z);
-  _corners2[6].set(max.x, max.y, min.z);
-  _corners2[7].set(max.x, max.y, max.z);
-  const rect = canvas.getBoundingClientRect();
-  let screenMinX = Infinity;
-  let screenMinY = Infinity;
-  let screenMaxX = -Infinity;
-  let screenMaxY = -Infinity;
-  let allBehind = true;
-  for (const corner of _corners2) {
-    _v2.copy(corner).project(camera);
-    if (_v2.z < 1) allBehind = false;
-    const sx = (_v2.x + 1) / 2 * rect.width;
-    const sy = (1 - _v2.y) / 2 * rect.height;
-    screenMinX = Math.min(screenMinX, sx);
-    screenMinY = Math.min(screenMinY, sy);
-    screenMaxX = Math.max(screenMaxX, sx);
-    screenMaxY = Math.max(screenMaxY, sy);
-  }
-  if (allBehind) return null;
-  screenMinX = Math.max(0, screenMinX);
-  screenMinY = Math.max(0, screenMinY);
-  screenMaxX = Math.min(rect.width, screenMaxX);
-  screenMaxY = Math.min(rect.height, screenMaxY);
-  const width = screenMaxX - screenMinX;
-  const height = screenMaxY - screenMinY;
-  if (width < 1 || height < 1) return null;
-  return {
-    left: rect.left + screenMinX,
-    top: rect.top + screenMinY,
-    width,
-    height
-  };
-}
-function getObjectLabel2(obj) {
-  const tag = `three-${obj.type.toLowerCase()}`;
-  const parts = [tag];
-  if (obj.name) {
-    parts.push(`.${obj.name}`);
-  }
-  const testId = obj.userData?.testId;
-  if (testId) {
-    parts.push(`[testId="${testId}"]`);
-  }
-  return parts.join("");
-}
-function getObjectDimensions(obj) {
-  _box2.setFromObject(obj);
-  if (_box2.isEmpty()) return "";
-  const size = _box2.getSize(new three.Vector3());
-  return `${size.x.toFixed(1)} \xD7 ${size.y.toFixed(1)} \xD7 ${size.z.toFixed(1)}`;
-}
-function createOverlayElement(color, showBorder) {
-  const el = document.createElement("div");
-  el.style.cssText = `
-    position: fixed;
-    pointer-events: none;
-    z-index: 99998;
-    background: ${color};
-    ${showBorder ? `border: 1px solid ${COLORS.border};` : ""}
-    transition: all 0.05s ease-out;
-    box-sizing: border-box;
-  `;
-  return el;
-}
-function createTooltipElement() {
-  const el = document.createElement("div");
-  el.style.cssText = `
-    position: fixed;
-    pointer-events: none;
-    z-index: 99999;
-    background: ${COLORS.tooltipBg};
-    color: ${COLORS.tooltipText};
-    font-family: 'SF Mono', Monaco, monospace;
-    font-size: 11px;
-    padding: 4px 8px;
-    border-radius: 3px;
-    white-space: nowrap;
-    line-height: 1.4;
-    box-shadow: 0 2px 8px rgba(0,0,0,0.3);
-  `;
-  return el;
-}
-function positionOverlay(entry, rect) {
-  const { overlayEl, tooltipEl } = entry;
-  overlayEl.style.left = `${rect.left}px`;
-  overlayEl.style.top = `${rect.top}px`;
-  overlayEl.style.width = `${rect.width}px`;
-  overlayEl.style.height = `${rect.height}px`;
-  overlayEl.style.display = "block";
-  tooltipEl.style.left = `${rect.left}px`;
-  tooltipEl.style.top = `${Math.max(0, rect.top - 28)}px`;
-  tooltipEl.style.display = "block";
-}
-function hideOverlay(entry) {
-  entry.overlayEl.style.display = "none";
-  entry.tooltipEl.style.display = "none";
-}
-var Highlighter = class {
-  constructor(options = {}) {
-    /** Selected object overlays (persistent until deselected) */
-    this._selectedEntries = /* @__PURE__ */ new Map();
-    /** Hover overlay (temporary, single object at a time) */
-    this._hoverEntries = /* @__PURE__ */ new Map();
-    this._camera = null;
-    this._renderer = null;
-    this._unsubscribe = null;
-    /** DevTools hover polling interval */
-    this._hoverPollId = null;
-    this._lastHoveredElement = null;
-    /** Store reference for resolving objects */
-    this._store = null;
-    this._showTooltip = options.showTooltip ?? true;
-  }
-  // -----------------------------------------------------------------------
-  // Lifecycle
-  // -----------------------------------------------------------------------
-  attach(_scene, selectionManager, camera, renderer, store) {
-    this.detach();
-    this._camera = camera;
-    this._renderer = renderer;
-    this._store = store;
-    this._unsubscribe = selectionManager.subscribe((selected) => {
-      this._syncSelectedHighlights(selected);
-    });
-    this._syncSelectedHighlights([...selectionManager.getSelected()]);
-    this._startHoverPolling();
-  }
-  detach() {
-    if (this._unsubscribe) {
-      this._unsubscribe();
-      this._unsubscribe = null;
+  // -----------------------------------------------------------------------
+  // Lifecycle
+  // -----------------------------------------------------------------------
+  /** Bind to a scene and selection manager, start hover polling. */
+  attach(scene, selectionManager, _camera2, _renderer, store) {
+    this.detach();
+    this._scene = scene;
+    this._store = store;
+    this._unsubscribe = selectionManager.subscribe((selected) => {
+      this._syncSelectionHighlights(selected);
+    });
+    this._syncSelectionHighlights([...selectionManager.getSelected()]);
+    this._startHoverPolling();
+  }
+  /** Unbind from the scene, stop polling, and remove all highlights. */
+  detach() {
+    if (this._unsubscribe) {
+      this._unsubscribe();
+      this._unsubscribe = null;
     }
     this._stopHoverPolling();
-    this._clearAllOverlays(this._selectedEntries);
-    this._clearAllOverlays(this._hoverEntries);
-    this._camera = null;
-    this._renderer = null;
+    this.clearHoverHighlight();
+    this._clearAllSelectionHighlights();
+    this._scene = null;
     this._store = null;
   }
   // -----------------------------------------------------------------------
-  // Per-frame update — reposition all overlays to follow camera/objects
+  // Per-frame update
   // -----------------------------------------------------------------------
+  /** Sync highlight group transforms to their source objects. Call each frame. */
   update() {
-    if (!this._camera || !this._renderer) return;
-    const canvas = this._renderer.domElement;
-    for (const entry of this._selectedEntries.values()) {
-      const rect = projectBoundsToScreen(entry.target, this._camera, canvas);
-      if (rect) {
-        positionOverlay(entry, rect);
-      } else {
-        hideOverlay(entry);
-      }
-    }
-    for (const entry of this._hoverEntries.values()) {
-      const rect = projectBoundsToScreen(entry.target, this._camera, canvas);
-      if (rect) {
-        positionOverlay(entry, rect);
-      } else {
-        hideOverlay(entry);
+    for (const entry of this._hoverEntries) {
+      _syncGroupTransform(entry.source, entry.group.root);
+    }
+    for (const selEntry of this._selectedEntries.values()) {
+      for (const mg of selEntry.meshGroups) {
+        const src = mg.root.userData.__r3fdom_source;
+        if (src) {
+          _syncGroupTransform(src, mg.root);
+        }
       }
     }
   }
   // -----------------------------------------------------------------------
-  // Public API
+  // Public API: hover highlight
   // -----------------------------------------------------------------------
-  highlight(obj) {
-    this._addSelectedHighlight(obj, false);
+  /** Show a hover highlight on the given object (replaces any previous hover). */
+  showHoverHighlight(obj) {
+    if (obj === this._hoverTarget) return;
+    this._clearHoverVisuals();
+    if (!this._scene) return;
+    this._hoverTarget = obj;
+    const targets = collectHighlightTargets(obj);
+    for (const target of targets) {
+      const hg = createHighlightMesh(target, HOVER_FILL_COLOR, HOVER_FILL_OPACITY);
+      if (hg) {
+        hg.root.renderOrder = 997;
+        this._scene.add(hg.root);
+        this._hoverEntries.push({ source: target, group: hg });
+      }
+    }
   }
-  unhighlight(obj) {
-    this._removeOverlay(obj, this._selectedEntries);
+  /** Remove the current hover highlight. */
+  clearHoverHighlight() {
+    this._clearHoverVisuals();
+    this._lastHoveredUuid = null;
   }
-  clearAll() {
-    this._clearAllOverlays(this._selectedEntries);
-    this._clearAllOverlays(this._hoverEntries);
+  _clearHoverVisuals() {
+    for (const entry of this._hoverEntries) {
+      this._disposeHighlightGroup(entry.group);
+    }
+    this._hoverEntries = [];
+    this._hoverTarget = null;
   }
+  // -----------------------------------------------------------------------
+  // Public API: queries
+  // -----------------------------------------------------------------------
+  /** Check if an object currently has a selection highlight. */
   isHighlighted(obj) {
     return this._selectedEntries.has(obj);
   }
-  /** Show a temporary hover highlight for an object and its children */
-  showHoverHighlight(obj) {
-    this._clearAllOverlays(this._hoverEntries);
-    this._addHoverHighlightRecursive(obj);
-  }
-  /** Clear the hover highlight */
-  clearHoverHighlight() {
-    this._clearAllOverlays(this._hoverEntries);
-    this._lastHoveredElement = null;
+  /** Remove all hover and selection highlights. */
+  clearAll() {
+    this.clearHoverHighlight();
+    this._clearAllSelectionHighlights();
   }
   // -----------------------------------------------------------------------
   // Internal: selection highlights
   // -----------------------------------------------------------------------
-  _syncSelectedHighlights(selected) {
-    const targetSet = /* @__PURE__ */ new Set();
-    const primarySet = new Set(selected);
-    for (const obj of selected) {
-      targetSet.add(obj);
-      obj.traverse((child) => {
-        targetSet.add(child);
-      });
-    }
+  _syncSelectionHighlights(selected) {
+    if (!this._scene) return;
+    const selectedSet = new Set(selected);
     for (const [obj] of this._selectedEntries) {
-      if (!targetSet.has(obj)) {
-        this._removeOverlay(obj, this._selectedEntries);
+      if (!selectedSet.has(obj)) {
+        this._removeSelectionHighlight(obj);
       }
     }
-    for (const obj of targetSet) {
-      if (obj.userData?.__r3fdom_internal) continue;
+    for (const obj of selected) {
       if (!this._selectedEntries.has(obj)) {
-        const isChild = !primarySet.has(obj);
-        this._addSelectedHighlight(obj, isChild);
+        this._addSelectionHighlight(obj);
       }
     }
   }
-  _addSelectedHighlight(obj, isChild) {
-    if (this._selectedEntries.has(obj)) return;
-    const color = isChild ? COLORS.contentChild : COLORS.content;
-    const overlayEl = createOverlayElement(color, !isChild);
-    const tooltipEl = createTooltipElement();
-    if (isChild || !this._showTooltip) {
-      tooltipEl.style.display = "none";
+  _addSelectionHighlight(obj) {
+    if (!this._scene) return;
+    const targets = collectHighlightTargets(obj);
+    const meshGroups = [];
+    for (const target of targets) {
+      const hg = createHighlightMesh(target, SELECTION_FILL_COLOR, SELECTION_FILL_OPACITY);
+      if (hg) {
+        hg.root.userData.__r3fdom_source = target;
+        hg.root.renderOrder = 999;
+        this._scene.add(hg.root);
+        meshGroups.push(hg);
+      }
+    }
+    let bboxGroup = null;
+    if (targets.length > 1 && obj.type !== "Group") {
+      bboxGroup = createBoundingBoxHighlight(obj);
+      if (bboxGroup) {
+        this._scene.add(bboxGroup.root);
+      }
+    }
+    if (meshGroups.length > 0 || bboxGroup) {
+      this._selectedEntries.set(obj, { source: obj, meshGroups, bboxGroup });
     }
-    const label = getObjectLabel2(obj);
-    const dims = getObjectDimensions(obj);
-    tooltipEl.innerHTML = `<span style="color:${COLORS.tooltipTag}">${label}</span>` + (dims ? ` <span style="color:${COLORS.tooltipDim}">${dims}</span>` : "");
-    document.body.appendChild(overlayEl);
-    document.body.appendChild(tooltipEl);
-    const entry = { overlayEl, tooltipEl, target: obj, isChild };
-    this._selectedEntries.set(obj, entry);
   }
-  // -----------------------------------------------------------------------
-  // Internal: hover highlights
-  // -----------------------------------------------------------------------
-  _addHoverHighlightRecursive(obj) {
-    if (obj.userData?.__r3fdom_internal) return;
-    const overlayEl = createOverlayElement(COLORS.hover, false);
-    const tooltipEl = createTooltipElement();
-    if (this._hoverEntries.size === 0 && this._showTooltip) {
-      const label = getObjectLabel2(obj);
-      const dims = getObjectDimensions(obj);
-      tooltipEl.innerHTML = `<span style="color:${COLORS.tooltipTag}">${label}</span>` + (dims ? ` <span style="color:${COLORS.tooltipDim}">${dims}</span>` : "");
-    } else {
-      tooltipEl.style.display = "none";
-    }
-    document.body.appendChild(overlayEl);
-    document.body.appendChild(tooltipEl);
-    this._hoverEntries.set(obj, { overlayEl, tooltipEl, target: obj, isChild: false });
-    for (const child of obj.children) {
-      if (!child.userData?.__r3fdom_internal) {
-        this._addHoverHighlightRecursive(child);
+  _removeSelectionHighlight(obj) {
+    const entry = this._selectedEntries.get(obj);
+    if (!entry) return;
+    for (const mg of entry.meshGroups) {
+      this._disposeHighlightGroup(mg);
+    }
+    if (entry.bboxGroup) {
+      this._disposeHighlightGroup(entry.bboxGroup);
+    }
+    this._selectedEntries.delete(obj);
+  }
+  _clearAllSelectionHighlights() {
+    for (const entry of this._selectedEntries.values()) {
+      for (const mg of entry.meshGroups) {
+        this._disposeHighlightGroup(mg);
+      }
+      if (entry.bboxGroup) {
+        this._disposeHighlightGroup(entry.bboxGroup);
       }
     }
+    this._selectedEntries.clear();
   }
   // -----------------------------------------------------------------------
   // Internal: DevTools hover polling
@@ -2979,56 +2990,878 @@ var Highlighter = class {
   _pollDevToolsHover() {
     if (!this._store) return;
     try {
-      const hoveredEl = globalThis.__r3fdom_hovered__;
-      if (hoveredEl === this._lastHoveredElement) return;
-      this._lastHoveredElement = hoveredEl ?? null;
-      if (!hoveredEl) {
-        this._clearAllOverlays(this._hoverEntries);
-        return;
-      }
-      const uuid = hoveredEl.getAttribute?.("data-uuid");
+      const hoveredEl = window.__r3fdom_hovered__;
+      const uuid = hoveredEl?.getAttribute?.("data-uuid") ?? null;
+      if (uuid === this._lastHoveredUuid) return;
+      this._lastHoveredUuid = uuid;
       if (!uuid) {
-        this._clearAllOverlays(this._hoverEntries);
+        this._clearHoverVisuals();
         return;
       }
       const obj = this._store.getObject3D(uuid);
       if (obj) {
         this.showHoverHighlight(obj);
       } else {
-        this._clearAllOverlays(this._hoverEntries);
+        this._clearHoverVisuals();
       }
     } catch {
     }
   }
   // -----------------------------------------------------------------------
-  // Internal: overlay cleanup
+  // Internal: cleanup
   // -----------------------------------------------------------------------
-  _removeOverlay(obj, map) {
-    const entry = map.get(obj);
-    if (!entry) return;
-    entry.overlayEl.remove();
-    entry.tooltipEl.remove();
-    map.delete(obj);
-  }
-  _clearAllOverlays(map) {
-    for (const entry of map.values()) {
-      entry.overlayEl.remove();
-      entry.tooltipEl.remove();
+  _disposeHighlightGroup(hg) {
+    hg.root.removeFromParent();
+    for (const d of hg.disposables) {
+      d.dispose();
     }
-    map.clear();
+  }
+  /** Detach and release all resources. */
+  dispose() {
+    this.detach();
+  }
+};
+
+// src/highlight/selectionDisplayTarget.ts
+function isFirstMeshInGroup(obj) {
+  const parent = obj.parent;
+  if (!parent || parent.type !== "Group") return false;
+  const firstMesh = parent.children.find((c) => getTagForType(c.type) === "three-mesh");
+  return firstMesh === obj;
+}
+function resolveSelectionDisplayTarget(getObject3D, uuid) {
+  const obj = getObject3D(uuid);
+  if (!obj) return null;
+  if (getTagForType(obj.type) !== "three-mesh") return uuid;
+  if (isFirstMeshInGroup(obj) && obj.parent) return obj.parent.uuid;
+  return uuid;
+}
+
+// src/highlight/InspectController.ts
+var RAYCAST_THROTTLE_MS = 50;
+var HOVER_REVEAL_DEBOUNCE_MS = 300;
+var InspectController = class {
+  constructor(opts) {
+    this._active = false;
+    this._lastRaycastTime = 0;
+    this._hoveredObject = null;
+    this._hoverRevealTimer = null;
+    this._overlay = null;
+    this._boundPointerMove = null;
+    this._boundPointerDown = null;
+    this._boundContextMenu = null;
+    this._camera = opts.camera;
+    this._renderer = opts.renderer;
+    this._selectionManager = opts.selectionManager;
+    this._highlighter = opts.highlighter;
+    this._raycastAccelerator = opts.raycastAccelerator;
+    this._mirror = opts.mirror;
+    this._store = opts.store;
+  }
+  get active() {
+    return this._active;
+  }
+  /** Update the camera reference (e.g. after a camera switch). */
+  updateCamera(camera) {
+    this._camera = camera;
   }
   // -----------------------------------------------------------------------
-  // Cleanup
+  // Enable / disable
   // -----------------------------------------------------------------------
+  /** Activate inspect mode — creates overlay on top of canvas. */
+  enable() {
+    if (this._active) return;
+    this._active = true;
+    const canvas = this._renderer.domElement;
+    const parent = canvas.parentElement;
+    if (!parent) return;
+    const overlay = document.createElement("div");
+    overlay.dataset.r3fdomInspect = "true";
+    overlay.style.cssText = [
+      "position:absolute",
+      "inset:0",
+      "z-index:999999",
+      "cursor:crosshair",
+      "background:transparent"
+    ].join(";");
+    const parentPos = getComputedStyle(parent).position;
+    if (parentPos === "static") {
+      parent.style.position = "relative";
+    }
+    this._boundPointerMove = this._onPointerMove.bind(this);
+    this._boundPointerDown = this._onPointerDown.bind(this);
+    this._boundContextMenu = (e) => e.preventDefault();
+    overlay.addEventListener("pointermove", this._boundPointerMove);
+    overlay.addEventListener("pointerdown", this._boundPointerDown);
+    overlay.addEventListener("contextmenu", this._boundContextMenu);
+    parent.appendChild(overlay);
+    this._overlay = overlay;
+    r3fLog("inspect", "Inspect mode enabled \u2014 hover to highlight, click to select");
+  }
+  /** Deactivate inspect mode — removes overlay and clears hover state. */
+  disable() {
+    if (!this._active) return;
+    this._active = false;
+    if (this._overlay) {
+      if (this._boundPointerMove) this._overlay.removeEventListener("pointermove", this._boundPointerMove);
+      if (this._boundPointerDown) this._overlay.removeEventListener("pointerdown", this._boundPointerDown);
+      if (this._boundContextMenu) this._overlay.removeEventListener("contextmenu", this._boundContextMenu);
+      this._overlay.remove();
+      this._overlay = null;
+    }
+    this._boundPointerMove = null;
+    this._boundPointerDown = null;
+    this._boundContextMenu = null;
+    this._hoveredObject = null;
+    this._cancelHoverReveal();
+    this._highlighter.clearHoverHighlight();
+    window.__r3fdom_selected_element__ = null;
+    r3fLog("inspect", "InspectController disabled");
+  }
+  /** Disable and release all resources. */
   dispose() {
-    this.detach();
+    this.disable();
+  }
+  // -----------------------------------------------------------------------
+  // Raycasting (delegated to RaycastAccelerator)
+  // -----------------------------------------------------------------------
+  _raycastFromEvent(e) {
+    return this._raycastAccelerator.raycastAtMouse(
+      e,
+      this._camera,
+      this._renderer.domElement
+    );
+  }
+  /**
+   * Resolve a raw raycast hit to the logical selection target.
+   * Walks up to find the best Group parent if applicable.
+   */
+  _resolveTarget(hit) {
+    const displayUuid = resolveSelectionDisplayTarget(
+      (id) => this._store.getObject3D(id),
+      hit.uuid
+    );
+    if (!displayUuid) return hit;
+    return this._store.getObject3D(displayUuid) ?? hit;
+  }
+  // -----------------------------------------------------------------------
+  // Event handlers
+  // -----------------------------------------------------------------------
+  _onPointerMove(e) {
+    e.stopPropagation();
+    e.preventDefault();
+    const now = performance.now();
+    if (now - this._lastRaycastTime < RAYCAST_THROTTLE_MS) return;
+    this._lastRaycastTime = now;
+    const hit = this._raycastFromEvent(e);
+    if (!hit) {
+      if (this._hoveredObject) {
+        this._hoveredObject = null;
+        this._highlighter.clearHoverHighlight();
+        this._cancelHoverReveal();
+      }
+      return;
+    }
+    if (hit === this._hoveredObject) return;
+    this._hoveredObject = hit;
+    this._highlighter.showHoverHighlight(hit);
+    this._scheduleHoverReveal(hit);
+  }
+  /**
+   * After hovering an object for HOVER_REVEAL_DEBOUNCE_MS, auto-reveal its
+   * mirror element in the Elements tab.
+   */
+  _scheduleHoverReveal(target) {
+    this._cancelHoverReveal();
+    this._hoverRevealTimer = setTimeout(() => {
+      const mirrorEl = this._mirror.getOrMaterialize(target.uuid);
+      if (mirrorEl) {
+        window.__r3fdom_selected_element__ = mirrorEl;
+      }
+    }, HOVER_REVEAL_DEBOUNCE_MS);
+  }
+  _cancelHoverReveal() {
+    if (this._hoverRevealTimer) {
+      clearTimeout(this._hoverRevealTimer);
+      this._hoverRevealTimer = null;
+    }
+  }
+  _onPointerDown(e) {
+    e.stopPropagation();
+    e.preventDefault();
+    const hit = this._raycastFromEvent(e);
+    if (!hit) {
+      this._selectionManager.clearSelection();
+      return;
+    }
+    const target = this._resolveTarget(hit);
+    if (!target) return;
+    this._selectionManager.select(target);
+    const mirrorEl = this._mirror.getOrMaterialize(target.uuid);
+    if (mirrorEl) {
+      window.__r3fdom_selected_element__ = mirrorEl;
+    }
+    r3fLog("inspect", "Object selected via canvas click", {
+      uuid: target.uuid.slice(0, 8),
+      name: target.name || "(unnamed)",
+      type: target.type
+    });
   }
 };
+var _bvhPatched = false;
+function ensureBVHPatched() {
+  if (_bvhPatched) return;
+  _bvhPatched = true;
+  three.BufferGeometry.prototype.computeBoundsTree = threeMeshBvh.computeBoundsTree;
+  three.BufferGeometry.prototype.disposeBoundsTree = threeMeshBvh.disposeBoundsTree;
+  three.Mesh.prototype.raycast = threeMeshBvh.acceleratedRaycast;
+  r3fLog("raycast", "three-mesh-bvh patched into Three.js");
+}
+var _raycaster2 = /* @__PURE__ */ new three.Raycaster();
+var _mouse = /* @__PURE__ */ new three.Vector2();
+function isRaycastable(obj) {
+  if (obj.userData?.__r3fdom_internal) return false;
+  if (!obj.visible) return false;
+  const isMeshLike = obj.isMesh === true || obj.isLine === true || obj.isPoints === true;
+  if (!isMeshLike) return false;
+  const geom = obj.geometry;
+  if (geom) {
+    const posAttr = geom.getAttribute("position");
+    if (posAttr && !posAttr.array) return false;
+  }
+  return true;
+}
+var RaycastAccelerator = class {
+  constructor(store) {
+    this._targets = [];
+    this._dirty = true;
+    this._unsubscribe = null;
+    this._bvhBuiltFor = /* @__PURE__ */ new WeakSet();
+    this._store = store;
+    ensureBVHPatched();
+    this._unsubscribe = store.subscribe(() => {
+      this._dirty = true;
+    });
+  }
+  /** Force a target list rebuild on the next raycast. */
+  markDirty() {
+    this._dirty = true;
+  }
+  _rebuild() {
+    this._dirty = false;
+    const flatList = this._store.getFlatList();
+    const targets = [];
+    for (let i = 0; i < flatList.length; i++) {
+      const obj = flatList[i];
+      if (isRaycastable(obj)) {
+        targets.push(obj);
+      }
+    }
+    this._targets = targets;
+    let bvhBudget = 50;
+    for (let i = 0; i < targets.length && bvhBudget > 0; i++) {
+      const obj = targets[i];
+      if (obj.isMesh) {
+        const geom = obj.geometry;
+        if (geom && !this._bvhBuiltFor.has(geom) && !geom.boundsTree) {
+          this._ensureBVH(obj);
+          bvhBudget--;
+        }
+      }
+    }
+    if (bvhBudget === 0) {
+      this._dirty = true;
+    }
+  }
+  /**
+   * Build a BVH for a mesh's geometry if it doesn't have one yet.
+   * Uses indirect mode to avoid modifying the index buffer.
+   * Skips disposed geometries and does NOT mark failed builds so they
+   * can be retried (e.g. after geometry is re-uploaded).
+   */
+  _ensureBVH(obj) {
+    if (!obj.isMesh) return;
+    const geom = obj.geometry;
+    if (!geom || this._bvhBuiltFor.has(geom)) return;
+    const posAttr = geom.getAttribute("position");
+    if (!posAttr || !posAttr.array) return;
+    if (geom.boundsTree) {
+      this._bvhBuiltFor.add(geom);
+      return;
+    }
+    try {
+      geom.computeBoundsTree({ indirect: true });
+      this._bvhBuiltFor.add(geom);
+    } catch {
+      r3fLog("raycast", `BVH build failed for geometry, will retry next rebuild`);
+    }
+  }
+  /**
+   * Raycast from mouse position against only raycastable meshes.
+   * Returns the closest non-internal hit, or null.
+   */
+  raycastAtMouse(e, camera, canvas) {
+    if (this._dirty) this._rebuild();
+    const rect = canvas.getBoundingClientRect();
+    _mouse.x = (e.clientX - rect.left) / rect.width * 2 - 1;
+    _mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1;
+    _raycaster2.setFromCamera(_mouse, camera);
+    _raycaster2.firstHitOnly = true;
+    const intersections = _raycaster2.intersectObjects(this._targets, false);
+    _raycaster2.firstHitOnly = false;
+    for (const intersection of intersections) {
+      if (intersection.object.userData?.__r3fdom_internal) continue;
+      return intersection.object;
+    }
+    return null;
+  }
+  /**
+   * Raycast from NDC coordinates. Used by raycastVerify.
+   */
+  raycastAtNdc(ndcX, ndcY, camera) {
+    if (this._dirty) this._rebuild();
+    _mouse.set(ndcX, ndcY);
+    _raycaster2.setFromCamera(_mouse, camera);
+    return _raycaster2.intersectObjects(this._targets, false);
+  }
+  /** Current number of raycastable targets. */
+  get targetCount() {
+    if (this._dirty) this._rebuild();
+    return this._targets.length;
+  }
+  /** Unsubscribe from the store and release the target list. */
+  dispose() {
+    if (this._unsubscribe) {
+      this._unsubscribe();
+      this._unsubscribe = null;
+    }
+    this._targets = [];
+  }
+};
+
+// src/bridge/ThreeDom.tsx
+var _stores = /* @__PURE__ */ new Map();
+var _mirrors = /* @__PURE__ */ new Map();
+var _selectionManagers = /* @__PURE__ */ new Map();
+var _highlighters = /* @__PURE__ */ new Map();
+var _inspectControllers = /* @__PURE__ */ new Map();
+function getStore2(canvasId = "") {
+  return _stores.get(canvasId) ?? null;
+}
+function getMirror(canvasId = "") {
+  return _mirrors.get(canvasId) ?? null;
+}
+function getSelectionManager(canvasId = "") {
+  return _selectionManagers.get(canvasId) ?? null;
+}
+function getHighlighter(canvasId = "") {
+  return _highlighters.get(canvasId) ?? null;
+}
+function getInspectController(canvasId = "") {
+  return _inspectControllers.get(canvasId) ?? null;
+}
+function getCanvasIds() {
+  return Array.from(_stores.keys());
+}
+function exposeGlobalAPI(store, gl, cameraRef, selMgr, inspCtrl, mirror, canvasId, isPrimary = true) {
+  const api = {
+    _ready: true,
+    canvasId,
+    getByTestId: (id) => store.getByTestId(id),
+    getByUuid: (uuid) => store.getByUuid(uuid),
+    getByName: (name) => store.getByName(name),
+    getChildren: (idOrUuid) => store.getChildren(idOrUuid),
+    getParent: (idOrUuid) => store.getParent(idOrUuid),
+    getCount: () => store.getCount(),
+    getByType: (type) => store.getByType(type),
+    getByGeometryType: (type) => store.getByGeometryType(type),
+    getByMaterialType: (type) => store.getByMaterialType(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, options) => store.inspect(idOrUuid, options),
+    click: (idOrUuid) => {
+      click3D(idOrUuid);
+    },
+    doubleClick: (idOrUuid) => {
+      doubleClick3D(idOrUuid);
+    },
+    contextMenu: (idOrUuid) => {
+      contextMenu3D(idOrUuid);
+    },
+    hover: (idOrUuid) => {
+      hover3D(idOrUuid);
+    },
+    unhover: () => {
+      unhover3D();
+    },
+    drag: async (idOrUuid, delta) => {
+      await drag3D(idOrUuid, delta);
+    },
+    wheel: (idOrUuid, options) => {
+      wheel3D(idOrUuid, options);
+    },
+    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 && selMgr) selMgr.select(obj);
+    },
+    clearSelection: () => {
+      selMgr?.clearSelection();
+    },
+    getSelection: () => selMgr ? selMgr.getSelected().map((o) => o.uuid) : [],
+    getObject3D: (idOrUuid) => store.getObject3D(idOrUuid),
+    getSelectionDisplayTarget: (uuid) => resolveSelectionDisplayTarget((id) => store.getObject3D(id), uuid) ?? uuid,
+    setInspectMode: (on) => {
+      r3fLog("inspect", "Global API setInspectMode called", { on });
+      const ctrl = inspCtrl ?? _inspectControllers.get(canvasId ?? "");
+      if (on) {
+        ctrl?.enable();
+        mirror?.setInspectMode(true);
+      } else {
+        ctrl?.disable();
+        mirror?.setInspectMode(false);
+      }
+    },
+    getInspectMode: () => {
+      const ctrl = inspCtrl ?? _inspectControllers.get(canvasId ?? "");
+      return ctrl?.active ?? false;
+    },
+    sweepOrphans: () => store.sweepOrphans(),
+    getDiagnostics: () => ({
+      version,
+      ready: true,
+      objectCount: store.getCount(),
+      meshCount: store.getCountByType("Mesh"),
+      groupCount: store.getCountByType("Group"),
+      lightCount: store.getCountByType("DirectionalLight") + store.getCountByType("PointLight") + store.getCountByType("SpotLight") + store.getCountByType("AmbientLight") + store.getCountByType("HemisphereLight"),
+      cameraCount: store.getCountByType("PerspectiveCamera") + store.getCountByType("OrthographicCamera"),
+      materializedDomNodes: mirror?.getMaterializedCount() ?? 0,
+      maxDomNodes: mirror?.getMaxNodes() ?? 0,
+      canvasWidth: gl.domElement.width,
+      canvasHeight: gl.domElement.height,
+      webglRenderer: (() => {
+        try {
+          const ctx = gl.getContext();
+          const dbg = ctx.getExtension("WEBGL_debug_renderer_info");
+          return dbg ? ctx.getParameter(dbg.UNMASKED_RENDERER_WEBGL) : "unknown";
+        } catch {
+          return "unknown";
+        }
+      })(),
+      dirtyQueueSize: store.getDirtyCount()
+    }),
+    getCameraState: () => {
+      const cam = cameraRef.current;
+      const dir = new three.Vector3(0, 0, -1).applyQuaternion(cam.quaternion);
+      const target = [
+        cam.position.x + dir.x * 100,
+        cam.position.y + dir.y * 100,
+        cam.position.z + dir.z * 100
+      ];
+      const state = {
+        type: cam.type,
+        position: [cam.position.x, cam.position.y, cam.position.z],
+        rotation: [cam.rotation.x, cam.rotation.y, cam.rotation.z],
+        target,
+        near: cam.near,
+        far: cam.far,
+        zoom: cam.zoom
+      };
+      if (cam.type === "PerspectiveCamera") {
+        const pc = cam;
+        state.fov = pc.fov;
+        state.aspect = pc.aspect;
+      } else if (cam.type === "OrthographicCamera") {
+        const oc = cam;
+        state.left = oc.left;
+        state.right = oc.right;
+        state.top = oc.top;
+        state.bottom = oc.bottom;
+      }
+      return state;
+    },
+    fuzzyFind: (query, limit = 5) => {
+      const q = query.toLowerCase();
+      const results = [];
+      for (const obj of store.getFlatList()) {
+        if (results.length >= limit) break;
+        const meta = store.getMetadata(obj);
+        if (!meta) continue;
+        const testId = meta.testId?.toLowerCase() ?? "";
+        const name = meta.name?.toLowerCase() ?? "";
+        if (testId.includes(q) || name.includes(q) || meta.uuid.startsWith(q)) {
+          results.push(meta);
+        }
+      }
+      return results;
+    },
+    version
+  };
+  if (isPrimary) {
+    window.__R3F_DOM__ = api;
+  }
+  if (canvasId) {
+    if (!window.__R3F_DOM_INSTANCES__) window.__R3F_DOM_INSTANCES__ = {};
+    if (window.__R3F_DOM_INSTANCES__[canvasId]) {
+      console.warn(
+        `[react-three-dom] Duplicate canvasId "${canvasId}" \u2014 the previous bridge instance will be overwritten. Each <ThreeDom> must have a unique canvasId.`
+      );
+    }
+    window.__R3F_DOM_INSTANCES__[canvasId] = api;
+  }
+}
+function removeGlobalAPI(onlyIfEquals, canvasId) {
+  r3fLog("bridge", "removeGlobalAPI called (deferred)");
+  const removeFromRegistry = (ref) => {
+    if (canvasId && window.__R3F_DOM_INSTANCES__) {
+      if (!ref || window.__R3F_DOM_INSTANCES__[canvasId] === ref) {
+        delete window.__R3F_DOM_INSTANCES__[canvasId];
+        if (Object.keys(window.__R3F_DOM_INSTANCES__).length === 0) {
+          delete window.__R3F_DOM_INSTANCES__;
+        }
+      }
+    }
+  };
+  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)");
+      }
+      removeFromRegistry(ref);
+    });
+  } else {
+    delete window.__R3F_DOM__;
+    removeFromRegistry();
+    r3fLog("bridge", "Global API removed (immediate)");
+  }
+}
+function createStubBridge(error, canvasId) {
+  return {
+    _ready: false,
+    _error: error,
+    canvasId,
+    getByTestId: () => null,
+    getByUuid: () => null,
+    getByName: () => [],
+    getChildren: () => [],
+    getParent: () => null,
+    getCount: () => 0,
+    getByType: () => [],
+    getByGeometryType: () => [],
+    getByMaterialType: () => [],
+    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: () => {
+    },
+    unhover: () => {
+    },
+    drag: async () => {
+    },
+    wheel: () => {
+    },
+    pointerMiss: () => {
+    },
+    drawPath: async () => ({ eventCount: 0, pointCount: 0 }),
+    select: () => {
+    },
+    clearSelection: () => {
+    },
+    getSelection: () => [],
+    getObject3D: () => null,
+    getSelectionDisplayTarget: (uuid) => uuid,
+    setInspectMode: () => {
+    },
+    getInspectMode: () => false,
+    sweepOrphans: () => 0,
+    getDiagnostics: () => ({
+      version,
+      ready: false,
+      error: error ?? void 0,
+      objectCount: 0,
+      meshCount: 0,
+      groupCount: 0,
+      lightCount: 0,
+      cameraCount: 0,
+      materializedDomNodes: 0,
+      maxDomNodes: 0,
+      canvasWidth: 0,
+      canvasHeight: 0,
+      webglRenderer: "unavailable",
+      dirtyQueueSize: 0
+    }),
+    getCameraState: () => ({
+      type: "unknown",
+      position: [0, 0, 0],
+      rotation: [0, 0, 0],
+      target: [0, 0, -100],
+      near: 0.1,
+      far: 1e3,
+      zoom: 1
+    }),
+    fuzzyFind: () => [],
+    version
+  };
+}
+function ThreeDom({
+  canvasId,
+  primary,
+  root = "#three-dom-root",
+  batchSize = 500,
+  syncBudgetMs = 0.5,
+  maxDomNodes = 2e3,
+  initialDepth = 3,
+  enabled = true,
+  debug = false,
+  inspect: inspectProp = false
+} = {}) {
+  const isPrimary = primary ?? canvasId === void 0;
+  const instanceKey = canvasId ?? "";
+  const scene = fiber.useThree((s) => s.scene);
+  const camera = fiber.useThree((s) => s.camera);
+  const gl = fiber.useThree((s) => s.gl);
+  const size = fiber.useThree((s) => s.size);
+  const cursorRef = react.useRef(0);
+  const lastSweepRef = react.useRef(0);
+  const cameraRef = react.useRef(camera);
+  cameraRef.current = camera;
+  react.useEffect(() => {
+    if (!enabled) return;
+    if (debug) enableDebug(true);
+    r3fLog("setup", "ThreeDom effect started", { enabled, debug, root, maxDomNodes });
+    const canvas = gl.domElement;
+    canvas.setAttribute("data-r3f-canvas", canvasId ?? "true");
+    const canvasParent = canvas.parentElement;
+    let rootElement = null;
+    let createdRoot = false;
+    if (typeof root === "string") {
+      rootElement = document.querySelector(root);
+    } else {
+      rootElement = root;
+    }
+    if (!rootElement) {
+      rootElement = document.createElement("div");
+      rootElement.id = typeof root === "string" ? root.replace(/^#/, "") : "three-dom-root";
+      createdRoot = true;
+    }
+    canvasParent.style.position = canvasParent.style.position || "relative";
+    canvasParent.appendChild(rootElement);
+    rootElement.style.cssText = "width:0;height:0;overflow:hidden;pointer-events:none;opacity:0;";
+    let store = null;
+    let mirror = null;
+    let unpatch = null;
+    let cancelAsyncReg = null;
+    let selectionManager = null;
+    let highlighter = null;
+    let raycastAccelerator = null;
+    let inspectController = null;
+    let currentApi;
+    try {
+      const webglContext = gl.getContext();
+      if (!webglContext || webglContext.isContextLost?.()) {
+        const msg = "WebGL context not available. For headless Chromium, add --enable-webgl and optionally --use-gl=angle --use-angle=swiftshader-webgl to launch args.";
+        const stubApi = createStubBridge(msg, canvasId);
+        if (isPrimary) window.__R3F_DOM__ = stubApi;
+        if (canvasId) {
+          if (!window.__R3F_DOM_INSTANCES__) window.__R3F_DOM_INSTANCES__ = {};
+          window.__R3F_DOM_INSTANCES__[canvasId] = stubApi;
+        }
+        r3fLog("setup", msg);
+        return () => {
+          removeGlobalAPI(stubApi, canvasId);
+          canvas.removeAttribute("data-r3f-canvas");
+          if (createdRoot && rootElement?.parentNode) {
+            rootElement.parentNode.removeChild(rootElement);
+          }
+          if (debug) enableDebug(false);
+        };
+      }
+      store = new ObjectStore();
+      mirror = new DomMirror(store, maxDomNodes);
+      mirror.setRoot(rootElement);
+      r3fLog("setup", "Store and mirror created");
+      ensureCustomElements(store);
+      unpatch = patchObject3D(store, mirror);
+      setInteractionState(store, camera, gl, size);
+      r3fLog("setup", "Object3D patched, interaction state set");
+      store.registerTree(scene);
+      if (!store.has(camera)) {
+        const camMeta = store.register(camera);
+        camMeta.parentUuid = scene.uuid;
+        mirror.materialize(camera.uuid);
+      }
+      mirror.materializeSubtree(scene.uuid, initialDepth);
+      cancelAsyncReg = store.registerTreeAsync(scene);
+      r3fLog("setup", `Scene registered: ${store.getCount()} objects, async watcher started`);
+      selectionManager = new SelectionManager();
+      highlighter = new Highlighter();
+      highlighter.attach(scene, selectionManager, camera, gl, store);
+      raycastAccelerator = new RaycastAccelerator(store);
+      inspectController = new InspectController({
+        camera,
+        renderer: gl,
+        selectionManager,
+        highlighter,
+        raycastAccelerator,
+        mirror,
+        store
+      });
+      _selectionManagers.set(instanceKey, selectionManager);
+      _highlighters.set(instanceKey, highlighter);
+      _inspectControllers.set(instanceKey, inspectController);
+      exposeGlobalAPI(store, gl, cameraRef, selectionManager, inspectController, mirror, canvasId, isPrimary);
+      r3fLog("bridge", `exposeGlobalAPI called \u2014 bridge is live, _ready=true${canvasId ? `, canvasId="${canvasId}"` : ""}`);
+      currentApi = canvasId ? window.__R3F_DOM_INSTANCES__?.[canvasId] : window.__R3F_DOM__;
+      _stores.set(instanceKey, store);
+      _mirrors.set(instanceKey, mirror);
+      if (inspectProp) {
+        inspectController.enable();
+      }
+      if (debug) {
+        const inspectStatus = inspectProp ? "on" : "off";
+        console.log(
+          "%c[react-three-dom]%c v" + version + " \u2014 " + store.getCount() + " objects \xB7 inspect: " + inspectStatus + "\n  %c\u2192%c Toggle inspect: %c__R3F_DOM__.setInspectMode(true|false)%c\n  %c\u2192%c Hover 3D objects to highlight + auto-reveal in Elements tab",
+          "background:#1a73e8;color:#fff;padding:2px 6px;border-radius:3px;font-weight:bold",
+          "color:inherit",
+          "color:#1a73e8",
+          "color:inherit",
+          "color:#e8a317;font-family:monospace",
+          "color:inherit",
+          "color:#1a73e8",
+          "color:inherit"
+        );
+      }
+    } 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);
+      const stubApi = createStubBridge(errorMsg, canvasId);
+      if (isPrimary) window.__R3F_DOM__ = stubApi;
+      if (canvasId) {
+        if (!window.__R3F_DOM_INSTANCES__) window.__R3F_DOM_INSTANCES__ = {};
+        window.__R3F_DOM_INSTANCES__[canvasId] = stubApi;
+      }
+      currentApi = stubApi;
+    }
+    return () => {
+      r3fLog("setup", "ThreeDom cleanup started");
+      if (cancelAsyncReg) cancelAsyncReg();
+      if (inspectController) inspectController.dispose();
+      if (raycastAccelerator) raycastAccelerator.dispose();
+      if (highlighter) highlighter.dispose();
+      if (unpatch) unpatch();
+      removeGlobalAPI(currentApi, canvasId);
+      clearInteractionState();
+      if (selectionManager) selectionManager.dispose();
+      if (mirror) mirror.dispose();
+      if (store) store.dispose();
+      canvas.removeAttribute("data-r3f-canvas");
+      if (createdRoot && rootElement?.parentNode) {
+        rootElement.parentNode.removeChild(rootElement);
+      }
+      _stores.delete(instanceKey);
+      _mirrors.delete(instanceKey);
+      _selectionManagers.delete(instanceKey);
+      _highlighters.delete(instanceKey);
+      _inspectControllers.delete(instanceKey);
+      if (debug) enableDebug(false);
+      r3fLog("setup", "ThreeDom cleanup complete");
+    };
+  }, [scene, camera, gl, enabled, root, maxDomNodes, initialDepth, debug, inspectProp, canvasId, isPrimary, instanceKey]);
+  fiber.useFrame(() => {
+    const _store3 = _stores.get(instanceKey);
+    const _mirror = _mirrors.get(instanceKey);
+    const _highlighter = _highlighters.get(instanceKey);
+    const _inspectController = _inspectControllers.get(instanceKey);
+    if (!enabled || !_store3 || !_mirror) return;
+    try {
+      setInteractionState(_store3, camera, gl, size);
+      if (_inspectController) _inspectController.updateCamera(camera);
+      const store = _store3;
+      const mirror = _mirror;
+      const start = performance.now();
+      const dirtyObjects = store.drainDirtyQueue();
+      for (const obj of dirtyObjects) {
+        store.update(obj);
+        mirror.syncAttributes(obj);
+      }
+      const budgetRemaining = syncBudgetMs - (performance.now() - start);
+      if (budgetRemaining > 0.1) {
+        const objects = store.getFlatList();
+        if (objects.length > 0) {
+          const end = Math.min(cursorRef.current + batchSize, objects.length);
+          for (let i = cursorRef.current; i < end; i++) {
+            if (performance.now() - start > syncBudgetMs) break;
+            const obj = objects[i];
+            const changed = store.update(obj);
+            if (changed) mirror.syncAttributes(obj);
+          }
+          cursorRef.current = end >= objects.length ? 0 : end;
+        }
+      }
+      if (_highlighter) _highlighter.update();
+      const now = performance.now();
+      if (now - lastSweepRef.current > 3e4) {
+        lastSweepRef.current = now;
+        store.sweepOrphans();
+      }
+    } catch (err) {
+      r3fLog("sync", "Per-frame sync error", err);
+    }
+  });
+  return null;
+}
 
 exports.DomMirror = DomMirror;
 exports.Highlighter = Highlighter;
+exports.InspectController = InspectController;
 exports.MANAGED_ATTRIBUTES = MANAGED_ATTRIBUTES;
 exports.ObjectStore = ObjectStore;
+exports.RaycastAccelerator = RaycastAccelerator;
 exports.SelectionManager = SelectionManager;
 exports.TAG_MAP = TAG_MAP;
 exports.ThreeDom = ThreeDom;
@@ -3054,7 +3887,9 @@ exports.drag3D = drag3D;
 exports.drawPath = drawPath;
 exports.enableDebug = enableDebug;
 exports.ensureCustomElements = ensureCustomElements;
+exports.getCanvasIds = getCanvasIds;
 exports.getHighlighter = getHighlighter;
+exports.getInspectController = getInspectController;
 exports.getMirror = getMirror;
 exports.getSelectionManager = getSelectionManager;
 exports.getStore = getStore2;