@react-three-dom/core 0.1.0

package/dist/index.cjs

@@ -0,0 +1,2666 @@
+'use strict';
+
+var three = require('three');
+var react = require('react');
+var fiber = require('@react-three/fiber');
+
+// src/version.ts
+var version = "0.1.0";
+function extractMetadata(obj) {
+  const meta = {
+    uuid: obj.uuid,
+    name: obj.name,
+    type: obj.type,
+    visible: obj.visible,
+    testId: obj.userData?.testId,
+    position: [obj.position.x, obj.position.y, obj.position.z],
+    rotation: [obj.rotation.x, obj.rotation.y, obj.rotation.z],
+    scale: [obj.scale.x, obj.scale.y, obj.scale.z],
+    parentUuid: obj.parent?.uuid ?? null,
+    childrenUuids: obj.children.map((c) => c.uuid),
+    boundsDirty: true
+  };
+  if ("geometry" in obj) {
+    const geom = obj.geometry;
+    if (geom instanceof three.BufferGeometry) {
+      meta.geometryType = geom.type;
+      const posAttr = geom.getAttribute("position");
+      if (posAttr) {
+        meta.vertexCount = posAttr.count;
+        if (geom.index) {
+          meta.triangleCount = Math.floor(geom.index.count / 3);
+        } else {
+          meta.triangleCount = Math.floor(posAttr.count / 3);
+        }
+      }
+    }
+  }
+  if ("material" in obj) {
+    const mat = obj.material;
+    if (mat instanceof three.Material) {
+      meta.materialType = mat.type;
+    } else if (Array.isArray(mat) && mat.length > 0) {
+      meta.materialType = mat[0].type + (mat.length > 1 ? ` (+${mat.length - 1})` : "");
+    }
+  }
+  if (obj instanceof three.InstancedMesh) {
+    meta.instanceCount = obj.count;
+  }
+  return meta;
+}
+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;
+}
+var _box3 = new three.Box3();
+function inspectObject(obj, metadata) {
+  obj.updateWorldMatrix(true, false);
+  const worldMatrix = Array.from(obj.matrixWorld.elements);
+  _box3.setFromObject(obj);
+  const boundsMin = [_box3.min.x, _box3.min.y, _box3.min.z];
+  const boundsMax = [_box3.max.x, _box3.max.y, _box3.max.z];
+  const inspection = {
+    metadata,
+    worldMatrix,
+    bounds: { min: boundsMin, max: boundsMax },
+    userData: { ...obj.userData }
+  };
+  if ("geometry" in obj) {
+    const geom = obj.geometry;
+    if (geom instanceof three.BufferGeometry) {
+      const geoInspection = {
+        type: geom.type,
+        attributes: {}
+      };
+      for (const [name, attr] of Object.entries(geom.attributes)) {
+        geoInspection.attributes[name] = {
+          itemSize: attr.itemSize,
+          count: attr.count
+        };
+      }
+      if (geom.index) {
+        geoInspection.index = { count: geom.index.count };
+      }
+      geom.computeBoundingSphere();
+      const sphere = geom.boundingSphere;
+      if (sphere) {
+        geoInspection.boundingSphere = {
+          center: [sphere.center.x, sphere.center.y, sphere.center.z],
+          radius: sphere.radius
+        };
+      }
+      inspection.geometry = geoInspection;
+    }
+  }
+  if ("material" in obj) {
+    const rawMat = obj.material;
+    const mat = Array.isArray(rawMat) ? rawMat[0] : rawMat;
+    if (mat instanceof three.Material) {
+      const matInspection = {
+        type: mat.type,
+        transparent: mat.transparent,
+        opacity: mat.opacity,
+        side: mat.side
+      };
+      if ("color" in mat && mat.color instanceof three.Color) {
+        matInspection.color = "#" + mat.color.getHexString();
+      }
+      if ("map" in mat) {
+        const map = mat.map;
+        if (map) {
+          matInspection.map = map.name || map.uuid || "unnamed";
+        }
+      }
+      if ("uniforms" in mat) {
+        const uniforms = mat.uniforms;
+        matInspection.uniforms = {};
+        for (const [key, uniform] of Object.entries(uniforms)) {
+          const val = uniform.value;
+          if (val === null || val === void 0) {
+            matInspection.uniforms[key] = val;
+          } else if (typeof val === "number" || typeof val === "boolean" || typeof val === "string") {
+            matInspection.uniforms[key] = val;
+          } else if (typeof val === "object" && "toArray" in val) {
+            matInspection.uniforms[key] = val.toArray();
+          } else {
+            matInspection.uniforms[key] = `[${typeof val}]`;
+          }
+        }
+      }
+      inspection.material = matInspection;
+    }
+  }
+  return inspection;
+}
+var ObjectStore = class {
+  constructor() {
+    // Tier 1: metadata for every tracked object
+    this._metaByObject = /* @__PURE__ */ new WeakMap();
+    this._objectByUuid = /* @__PURE__ */ new Map();
+    this._objectsByTestId = /* @__PURE__ */ new Map();
+    this._objectsByName = /* @__PURE__ */ new Map();
+    // Flat list for amortized iteration
+    this._flatList = [];
+    this._flatListDirty = true;
+    // Priority dirty queue: objects that changed and need immediate sync
+    this._dirtyQueue = /* @__PURE__ */ new Set();
+    // Event listeners
+    this._listeners = [];
+    // Track the root scene(s) for scoping
+    this._trackedRoots = /* @__PURE__ */ new WeakSet();
+  }
+  // -------------------------------------------------------------------------
+  // Registration
+  // -------------------------------------------------------------------------
+  /**
+   * Register a single object into the store.
+   * Populates Tier 1 metadata and all indexes.
+   */
+  register(obj) {
+    if (obj.userData?.__r3fdom_internal) {
+      return extractMetadata(obj);
+    }
+    const existing = this._metaByObject.get(obj);
+    if (existing) return existing;
+    const meta = extractMetadata(obj);
+    this._metaByObject.set(obj, meta);
+    this._objectByUuid.set(meta.uuid, obj);
+    this._flatListDirty = true;
+    if (meta.testId) {
+      this._objectsByTestId.set(meta.testId, obj);
+    }
+    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);
+    }
+    this._emit({ type: "add", object: obj, metadata: meta });
+    return meta;
+  }
+  /**
+   * Register an entire subtree (object + all descendants).
+   */
+  registerTree(root) {
+    this._trackedRoots.add(root);
+    root.traverse((obj) => {
+      this.register(obj);
+    });
+  }
+  /**
+   * Unregister a single object from the store.
+   */
+  unregister(obj) {
+    const meta = this._metaByObject.get(obj);
+    if (!meta) return;
+    this._metaByObject.delete(obj);
+    this._objectByUuid.delete(meta.uuid);
+    this._dirtyQueue.delete(obj);
+    this._flatListDirty = true;
+    if (meta.testId) {
+      this._objectsByTestId.delete(meta.testId);
+    }
+    if (meta.name) {
+      const nameSet = this._objectsByName.get(meta.name);
+      if (nameSet) {
+        nameSet.delete(obj);
+        if (nameSet.size === 0) {
+          this._objectsByName.delete(meta.name);
+        }
+      }
+    }
+    this._emit({ type: "remove", object: obj, metadata: meta });
+  }
+  /**
+   * Unregister an entire subtree (object + all descendants).
+   */
+  unregisterTree(root) {
+    root.traverse((obj) => {
+      this.unregister(obj);
+    });
+    this._trackedRoots.delete(root);
+  }
+  // -------------------------------------------------------------------------
+  // Tier 1: Update (compare-and-set, returns true if changed)
+  // -------------------------------------------------------------------------
+  /**
+   * Refresh Tier 1 metadata from the live Three.js object.
+   * Returns true if any values changed.
+   */
+  update(obj) {
+    const prev = this._metaByObject.get(obj);
+    if (!prev) return false;
+    const curr = extractMetadata(obj);
+    if (hasChanged(prev, curr)) {
+      if (prev.testId !== curr.testId) {
+        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);
+          }
+        }
+        if (curr.name) {
+          let nameSet = this._objectsByName.get(curr.name);
+          if (!nameSet) {
+            nameSet = /* @__PURE__ */ new Set();
+            this._objectsByName.set(curr.name, nameSet);
+          }
+          nameSet.add(obj);
+        }
+      }
+      this._metaByObject.set(obj, curr);
+      this._emit({ type: "update", object: obj, metadata: curr });
+      return true;
+    }
+    return false;
+  }
+  // -------------------------------------------------------------------------
+  // Tier 2: On-demand inspection (never cached)
+  // -------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  inspect(idOrUuid) {
+    const obj = this.getObject3D(idOrUuid);
+    if (!obj) return null;
+    const meta = this._metaByObject.get(obj);
+    if (!meta) return null;
+    return inspectObject(obj, meta);
+  }
+  // -------------------------------------------------------------------------
+  // Lookups (O(1))
+  // -------------------------------------------------------------------------
+  /** Get metadata by testId. O(1). */
+  getByTestId(testId) {
+    const obj = this._objectsByTestId.get(testId);
+    if (!obj) return null;
+    return this._metaByObject.get(obj) ?? null;
+  }
+  /** Get metadata by uuid. O(1). */
+  getByUuid(uuid) {
+    const obj = this._objectByUuid.get(uuid);
+    if (!obj) return null;
+    return this._metaByObject.get(obj) ?? null;
+  }
+  /** Get metadata by name (returns array since names aren't unique). O(1). */
+  getByName(name) {
+    const objs = this._objectsByName.get(name);
+    if (!objs) return [];
+    const results = [];
+    for (const obj of objs) {
+      const meta = this._metaByObject.get(obj);
+      if (meta) results.push(meta);
+    }
+    return results;
+  }
+  /** Get the raw Three.js Object3D by testId or uuid. */
+  getObject3D(idOrUuid) {
+    return this._objectsByTestId.get(idOrUuid) ?? this._objectByUuid.get(idOrUuid) ?? null;
+  }
+  /** Get metadata for a known Object3D reference. */
+  getMetadata(obj) {
+    return this._metaByObject.get(obj) ?? null;
+  }
+  /** Check if an object is registered. */
+  has(obj) {
+    return this._metaByObject.has(obj);
+  }
+  /** Total number of tracked objects. */
+  getCount() {
+    return this._objectByUuid.size;
+  }
+  /** Check if a root scene is tracked. */
+  isTrackedRoot(obj) {
+    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.
+   */
+  isInTrackedScene(obj) {
+    let current = obj;
+    while (current) {
+      if (this._trackedRoots.has(current)) return true;
+      current = current.parent;
+    }
+    return false;
+  }
+  // -------------------------------------------------------------------------
+  // Flat list for amortized iteration
+  // -------------------------------------------------------------------------
+  /**
+   * Get a flat array of all tracked objects for amortized batch processing.
+   * Rebuilds lazily when the list is dirty (objects added/removed).
+   */
+  getFlatList() {
+    if (this._flatListDirty) {
+      this._flatList = Array.from(this._objectByUuid.values());
+      this._flatListDirty = false;
+    }
+    return this._flatList;
+  }
+  // -------------------------------------------------------------------------
+  // Priority dirty queue
+  // -------------------------------------------------------------------------
+  /** Mark an object as dirty (needs priority sync next frame). */
+  markDirty(obj) {
+    if (this._metaByObject.has(obj)) {
+      this._dirtyQueue.add(obj);
+    }
+  }
+  /**
+   * Drain the dirty queue, returning all objects that need priority sync.
+   * Clears the queue after draining.
+   */
+  drainDirtyQueue() {
+    if (this._dirtyQueue.size === 0) return [];
+    const objects = Array.from(this._dirtyQueue);
+    this._dirtyQueue.clear();
+    return objects;
+  }
+  /** Number of objects currently in the dirty queue. */
+  getDirtyCount() {
+    return this._dirtyQueue.size;
+  }
+  // -------------------------------------------------------------------------
+  // Event system
+  // -------------------------------------------------------------------------
+  /** Subscribe to store events (add, remove, update). */
+  subscribe(listener) {
+    this._listeners.push(listener);
+    return () => {
+      const idx = this._listeners.indexOf(listener);
+      if (idx !== -1) this._listeners.splice(idx, 1);
+    };
+  }
+  _emit(event) {
+    for (const listener of this._listeners) {
+      listener(event);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Cleanup
+  // -------------------------------------------------------------------------
+  /** Remove all tracked objects and reset state. */
+  dispose() {
+    this._objectByUuid.clear();
+    this._objectsByTestId.clear();
+    this._objectsByName.clear();
+    this._flatList = [];
+    this._flatListDirty = true;
+    this._dirtyQueue.clear();
+    this._listeners = [];
+  }
+};
+
+// src/mirror/CustomElements.ts
+var TAG_MAP = {
+  // Scenes
+  Scene: "three-scene",
+  // Groups / containers
+  Group: "three-group",
+  LOD: "three-group",
+  Bone: "three-group",
+  // Meshes
+  Mesh: "three-mesh",
+  SkinnedMesh: "three-mesh",
+  InstancedMesh: "three-mesh",
+  LineSegments: "three-mesh",
+  Line: "three-mesh",
+  LineLoop: "three-mesh",
+  Points: "three-mesh",
+  Sprite: "three-mesh",
+  // Lights
+  AmbientLight: "three-light",
+  DirectionalLight: "three-light",
+  HemisphereLight: "three-light",
+  PointLight: "three-light",
+  RectAreaLight: "three-light",
+  SpotLight: "three-light",
+  LightProbe: "three-light",
+  // Cameras
+  PerspectiveCamera: "three-camera",
+  OrthographicCamera: "three-camera",
+  ArrayCamera: "three-camera",
+  CubeCamera: "three-camera",
+  // Helpers (map to object as fallback)
+  BoxHelper: "three-object",
+  ArrowHelper: "three-object",
+  AxesHelper: "three-object",
+  GridHelper: "three-object",
+  SkeletonHelper: "three-object"
+};
+var ALL_TAGS = [
+  "three-scene",
+  "three-group",
+  "three-mesh",
+  "three-light",
+  "three-camera",
+  "three-object"
+];
+var DEFAULT_TAG = "three-object";
+function getTagForType(type) {
+  return TAG_MAP[type] ?? DEFAULT_TAG;
+}
+var _store = null;
+var ThreeElement = class extends HTMLElement {
+  // -------------------------------------------------------------------------
+  // Tier 1: Lightweight cached metadata (always available)
+  // -------------------------------------------------------------------------
+  /**
+   * Returns the Tier 1 cached metadata for this object.
+   * Instant, no computation. Returns null if the element is not linked.
+   */
+  get metadata() {
+    const uuid = this.dataset.uuid;
+    if (!uuid || !_store) return null;
+    return _store.getByUuid(uuid);
+  }
+  // -------------------------------------------------------------------------
+  // Tier 2: On-demand heavy inspection (reads live Three.js object)
+  // -------------------------------------------------------------------------
+  /**
+   * Performs a full inspection of the linked Three.js object.
+   * Reads geometry buffers, material properties, world bounds, etc.
+   * Cost: 0.1–2ms depending on geometry complexity.
+   */
+  inspect() {
+    const uuid = this.dataset.uuid;
+    if (!uuid || !_store) return null;
+    return _store.inspect(uuid);
+  }
+  // -------------------------------------------------------------------------
+  // Raw Three.js object reference
+  // -------------------------------------------------------------------------
+  /**
+   * Returns the raw Three.js Object3D linked to this DOM element.
+   * Allows direct access to any Three.js property or method.
+   */
+  get object3D() {
+    const uuid = this.dataset.uuid;
+    if (!uuid || !_store) return null;
+    return _store.getObject3D(uuid);
+  }
+  // -------------------------------------------------------------------------
+  // Convenience shortcuts (read from Tier 1 metadata)
+  // -------------------------------------------------------------------------
+  /**
+   * Local position as [x, y, z].
+   */
+  get position() {
+    return this.metadata?.position ?? null;
+  }
+  /**
+   * Local euler rotation as [x, y, z] in radians.
+   */
+  get rotation() {
+    return this.metadata?.rotation ?? null;
+  }
+  /**
+   * Local scale as [x, y, z].
+   */
+  get scale() {
+    return this.metadata?.scale ?? null;
+  }
+  /**
+   * Whether the object is visible (does not check parent chain).
+   */
+  get visible() {
+    return this.metadata?.visible ?? false;
+  }
+  /**
+   * The testId from userData.testId, if set.
+   */
+  get testId() {
+    return this.metadata?.testId;
+  }
+  /**
+   * World-space bounding box. Computed on-demand (Tier 2).
+   */
+  get bounds() {
+    const inspection = this.inspect();
+    return inspection?.bounds ?? null;
+  }
+  // -------------------------------------------------------------------------
+  // Interaction methods
+  // -------------------------------------------------------------------------
+  /**
+   * Trigger a deterministic click on the linked 3D object.
+   * Projects the object center to screen coordinates and dispatches pointer events.
+   */
+  click() {
+    const uuid = this.dataset.uuid;
+    if (!uuid) {
+      console.warn("[react-three-dom] Cannot click: element has no data-uuid");
+      return;
+    }
+    if (typeof window.__R3F_DOM__?.click === "function") {
+      window.__R3F_DOM__.click(uuid);
+    } else {
+      console.warn("[react-three-dom] Cannot click: bridge API not initialized");
+    }
+  }
+  /**
+   * Trigger a deterministic hover on the linked 3D object.
+   */
+  hover() {
+    const uuid = this.dataset.uuid;
+    if (!uuid) {
+      console.warn("[react-three-dom] Cannot hover: element has no data-uuid");
+      return;
+    }
+    if (typeof window.__R3F_DOM__?.hover === "function") {
+      window.__R3F_DOM__.hover(uuid);
+    } else {
+      console.warn("[react-three-dom] Cannot hover: bridge API not initialized");
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Console-friendly output
+  // -------------------------------------------------------------------------
+  /**
+   * Returns a readable string representation for console output.
+   */
+  toString() {
+    const tag = this.tagName.toLowerCase();
+    const name = this.dataset.name ? ` name="${this.dataset.name}"` : "";
+    const testId = this.dataset.testId ? ` testId="${this.dataset.testId}"` : "";
+    const type = this.dataset.type ? ` type="${this.dataset.type}"` : "";
+    return `<${tag}${name}${testId}${type}>`;
+  }
+};
+var _registered = false;
+function ensureCustomElements(store) {
+  if (_registered) return;
+  if (typeof customElements === "undefined") return;
+  _store = store;
+  for (const tag of ALL_TAGS) {
+    if (!customElements.get(tag)) {
+      const elementClass = class extends ThreeElement {
+      };
+      Object.defineProperty(elementClass, "name", { value: `ThreeElement_${tag}` });
+      customElements.define(tag, elementClass);
+    }
+  }
+  _registered = true;
+}
+
+// src/mirror/attributes.ts
+var ATTRIBUTE_MAP = {
+  "data-uuid": (m) => m.uuid,
+  "data-name": (m) => m.name || void 0,
+  "data-type": (m) => m.type,
+  "data-visible": (m) => String(m.visible),
+  "data-test-id": (m) => m.testId,
+  "data-geometry": (m) => m.geometryType,
+  "data-material": (m) => m.materialType,
+  "data-position": (m) => serializeTuple(m.position),
+  "data-rotation": (m) => serializeTuple(m.rotation),
+  "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
+};
+var MANAGED_ATTRIBUTES = Object.keys(ATTRIBUTE_MAP);
+function serializeTuple(tuple) {
+  return `${round(tuple[0])},${round(tuple[1])},${round(tuple[2])}`;
+}
+function round(n) {
+  const rounded = Math.round(n * 1e4) / 1e4;
+  return String(rounded === 0 ? 0 : rounded);
+}
+function computeAttributes(meta) {
+  const attrs = /* @__PURE__ */ new Map();
+  for (const [key, extractor] of Object.entries(ATTRIBUTE_MAP)) {
+    const value = extractor(meta);
+    if (value !== void 0) {
+      attrs.set(key, value);
+    }
+  }
+  return attrs;
+}
+function applyAttributes(element, meta, prevAttrs) {
+  let writeCount = 0;
+  const newAttrs = computeAttributes(meta);
+  for (const [key, value] of newAttrs) {
+    const prev = prevAttrs.get(key);
+    if (prev !== value) {
+      element.setAttribute(key, value);
+      prevAttrs.set(key, value);
+      writeCount++;
+    }
+  }
+  for (const key of prevAttrs.keys()) {
+    if (!newAttrs.has(key)) {
+      element.removeAttribute(key);
+      prevAttrs.delete(key);
+      writeCount++;
+    }
+  }
+  return writeCount;
+}
+
+// src/mirror/DomMirror.ts
+var DomMirror = class {
+  constructor(store, maxNodes = 2e3) {
+    this._rootElement = null;
+    // Materialized nodes indexed by uuid
+    this._nodes = /* @__PURE__ */ new Map();
+    // LRU doubly-linked list for eviction (head = most recently used, tail = least)
+    this._lruHead = null;
+    this._lruTail = null;
+    this._lruSize = 0;
+    // UUID → parent UUID mapping for DOM tree structure
+    this._parentMap = /* @__PURE__ */ new Map();
+    this._store = store;
+    this._maxNodes = maxNodes;
+  }
+  // -------------------------------------------------------------------------
+  // Initialization
+  // -------------------------------------------------------------------------
+  /**
+   * Set the root DOM element where the mirror tree will be appended.
+   * Typically a hidden div: <div id="three-dom-root" style="display:none">
+   */
+  setRoot(rootElement) {
+    this._rootElement = rootElement;
+  }
+  /**
+   * Build the initial DOM tree from the scene.
+   * Materializes the top 2 levels of the scene hierarchy.
+   */
+  buildInitialTree(scene) {
+    if (!this._rootElement) return;
+    this.materializeSubtree(scene.uuid, 2);
+  }
+  // -------------------------------------------------------------------------
+  // Materialization
+  // -------------------------------------------------------------------------
+  /**
+   * Create a DOM node for a single object.
+   * If already materialized, touches the LRU and returns the existing element.
+   */
+  materialize(uuid) {
+    const existing = this._nodes.get(uuid);
+    if (existing) {
+      this._lruTouch(existing.lruNode);
+      return existing.element;
+    }
+    const meta = this._store.getByUuid(uuid);
+    if (!meta) return null;
+    if (this._lruSize >= this._maxNodes) {
+      this._evictLRU();
+    }
+    const tag = getTagForType(meta.type);
+    const element = document.createElement(tag);
+    element.style.cssText = "display:block;position:absolute;pointer-events:none;box-sizing:border-box;";
+    const prevAttrs = /* @__PURE__ */ new Map();
+    applyAttributes(element, meta, prevAttrs);
+    const lruNode = { uuid, prev: null, next: null };
+    this._lruPush(lruNode);
+    const node = { element, prevAttrs, lruNode };
+    this._nodes.set(uuid, node);
+    this._parentMap.set(uuid, meta.parentUuid);
+    this._insertIntoDom(uuid, meta.parentUuid, element);
+    return element;
+  }
+  /**
+   * Materialize a subtree starting from the given uuid, up to the specified depth.
+   * depth=0 materializes just the node, depth=1 includes direct children, etc.
+   */
+  materializeSubtree(uuid, depth) {
+    this.materialize(uuid);
+    if (depth <= 0) return;
+    const meta = this._store.getByUuid(uuid);
+    if (!meta) return;
+    for (const childUuid of meta.childrenUuids) {
+      this.materializeSubtree(childUuid, depth - 1);
+    }
+  }
+  /**
+   * Remove a DOM node but keep JS metadata in the ObjectStore.
+   * Called by LRU eviction or when an object is removed from the scene.
+   */
+  dematerialize(uuid) {
+    const node = this._nodes.get(uuid);
+    if (!node) return;
+    node.element.remove();
+    this._lruRemove(node.lruNode);
+    this._nodes.delete(uuid);
+    this._parentMap.delete(uuid);
+  }
+  // -------------------------------------------------------------------------
+  // Structural updates (called by Object3D.add/remove patch)
+  // -------------------------------------------------------------------------
+  /**
+   * Called when a new object is added to the tracked scene.
+   * Only materializes if the parent is already materialized (lazy expansion).
+   */
+  onObjectAdded(obj) {
+    const parentUuid = obj.parent?.uuid;
+    if (!parentUuid) return;
+    const parentNode = this._nodes.get(parentUuid);
+    if (parentNode) {
+      this.materialize(obj.uuid);
+    }
+    if (parentNode) {
+      const parentMeta = this._store.getByUuid(parentUuid);
+      if (parentMeta) {
+        applyAttributes(parentNode.element, parentMeta, parentNode.prevAttrs);
+      }
+    }
+  }
+  /**
+   * Called when an object is removed from the tracked scene.
+   * Dematerializes the object and all its descendants.
+   */
+  onObjectRemoved(obj) {
+    obj.traverse((child) => {
+      this.dematerialize(child.uuid);
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Attribute sync (called per-frame by ThreeDom)
+  // -------------------------------------------------------------------------
+  /**
+   * Sync Tier 1 attributes for an object if it's materialized.
+   * No-op if the object has no materialized DOM node.
+   * Returns the number of DOM writes performed.
+   */
+  syncAttributes(obj) {
+    const node = this._nodes.get(obj.uuid);
+    if (!node) return 0;
+    const meta = this._store.getMetadata(obj);
+    if (!meta) return 0;
+    return applyAttributes(node.element, meta, node.prevAttrs);
+  }
+  /**
+   * Sync attributes by uuid (when you don't have the Object3D ref).
+   */
+  syncAttributesByUuid(uuid) {
+    const node = this._nodes.get(uuid);
+    if (!node) return 0;
+    const meta = this._store.getByUuid(uuid);
+    if (!meta) return 0;
+    return applyAttributes(node.element, meta, node.prevAttrs);
+  }
+  // -------------------------------------------------------------------------
+  // Querying
+  // -------------------------------------------------------------------------
+  /**
+   * Get the root DOM element.
+   */
+  getRootElement() {
+    return this._rootElement;
+  }
+  /**
+   * Get the materialized DOM element for an object, if it exists.
+   */
+  getElement(uuid) {
+    const node = this._nodes.get(uuid);
+    if (node) {
+      this._lruTouch(node.lruNode);
+      return node.element;
+    }
+    return null;
+  }
+  /**
+   * Check if an object has a materialized DOM node.
+   */
+  isMaterialized(uuid) {
+    return this._nodes.has(uuid);
+  }
+  /**
+   * Query the mirror DOM using a CSS selector.
+   * Falls back to searching the ObjectStore if no materialized nodes match,
+   * then materializes the matching objects.
+   */
+  querySelector(selector) {
+    if (!this._rootElement) return null;
+    const existing = this._rootElement.querySelector(selector);
+    if (existing) return existing;
+    const uuid = this._findUuidBySelector(selector);
+    if (uuid) {
+      return this.materialize(uuid);
+    }
+    return null;
+  }
+  /**
+   * Query all matching elements in the mirror DOM.
+   */
+  querySelectorAll(selector) {
+    if (!this._rootElement) return [];
+    const uuids = this._findAllUuidsBySelector(selector);
+    const elements = [];
+    for (const uuid of uuids) {
+      const el = this.materialize(uuid);
+      if (el) elements.push(el);
+    }
+    return elements;
+  }
+  // -------------------------------------------------------------------------
+  // Configuration
+  // -------------------------------------------------------------------------
+  /**
+   * Set the maximum number of materialized DOM nodes.
+   * If current count exceeds the new max, excess nodes are evicted immediately.
+   */
+  setMaxNodes(max) {
+    this._maxNodes = max;
+    while (this._lruSize > this._maxNodes) {
+      this._evictLRU();
+    }
+  }
+  /** Current number of materialized DOM nodes. */
+  getMaterializedCount() {
+    return this._nodes.size;
+  }
+  /** Maximum allowed materialized DOM nodes. */
+  getMaxNodes() {
+    return this._maxNodes;
+  }
+  // -------------------------------------------------------------------------
+  // Cleanup
+  // -------------------------------------------------------------------------
+  /**
+   * Remove all materialized DOM nodes and reset state.
+   */
+  dispose() {
+    for (const [, node] of this._nodes) {
+      node.element.remove();
+    }
+    this._nodes.clear();
+    this._parentMap.clear();
+    this._lruHead = null;
+    this._lruTail = null;
+    this._lruSize = 0;
+    if (this._rootElement) {
+      this._rootElement.innerHTML = "";
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Private: DOM insertion
+  // -------------------------------------------------------------------------
+  /**
+   * Insert a newly created element into the correct position in the DOM tree.
+   */
+  _insertIntoDom(_uuid, parentUuid, element) {
+    if (!this._rootElement) return;
+    if (!parentUuid) {
+      this._rootElement.appendChild(element);
+      return;
+    }
+    const parentNode = this._nodes.get(parentUuid);
+    if (parentNode) {
+      parentNode.element.appendChild(element);
+    } else {
+      this._rootElement.appendChild(element);
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Private: Selector → UUID resolution
+  // -------------------------------------------------------------------------
+  /**
+   * Parse common CSS selector patterns and resolve to a uuid from the store.
+   * Supports:
+   *   [data-test-id="value"]
+   *   [data-name="value"]
+   *   [data-uuid="value"]
+   *   three-mesh, three-light, etc. (by tag/type)
+   */
+  _findUuidBySelector(selector) {
+    const testIdMatch = selector.match(/\[data-test-id=["']([^"']+)["']\]/);
+    if (testIdMatch) {
+      const meta = this._store.getByTestId(testIdMatch[1]);
+      return meta?.uuid ?? null;
+    }
+    const uuidMatch = selector.match(/\[data-uuid=["']([^"']+)["']\]/);
+    if (uuidMatch) {
+      const meta = this._store.getByUuid(uuidMatch[1]);
+      return meta?.uuid ?? null;
+    }
+    const nameMatch = selector.match(/\[data-name=["']([^"']+)["']\]/);
+    if (nameMatch) {
+      const metas = this._store.getByName(nameMatch[1]);
+      return metas.length > 0 ? metas[0].uuid : null;
+    }
+    return null;
+  }
+  /**
+   * Find all UUIDs matching a selector pattern.
+   */
+  _findAllUuidsBySelector(selector) {
+    const uuids = [];
+    const testIdMatch = selector.match(/\[data-test-id=["']([^"']+)["']\]/);
+    if (testIdMatch) {
+      const meta = this._store.getByTestId(testIdMatch[1]);
+      if (meta) uuids.push(meta.uuid);
+      return uuids;
+    }
+    const nameMatch = selector.match(/\[data-name=["']([^"']+)["']\]/);
+    if (nameMatch) {
+      const metas = this._store.getByName(nameMatch[1]);
+      for (const m of metas) uuids.push(m.uuid);
+      return uuids;
+    }
+    const tagMatch = selector.match(/^(three-(?:scene|group|mesh|light|camera|object))$/);
+    if (tagMatch) {
+      const targetTag = tagMatch[1];
+      const allObjects = this._store.getFlatList();
+      for (const obj of allObjects) {
+        const meta = this._store.getMetadata(obj);
+        if (meta && getTagForType(meta.type) === targetTag) {
+          uuids.push(meta.uuid);
+        }
+      }
+      return uuids;
+    }
+    return uuids;
+  }
+  // -------------------------------------------------------------------------
+  // Private: LRU doubly-linked list operations
+  // -------------------------------------------------------------------------
+  /** Add a node to the front (most recently used). */
+  _lruPush(node) {
+    node.prev = null;
+    node.next = this._lruHead;
+    if (this._lruHead) {
+      this._lruHead.prev = node;
+    }
+    this._lruHead = node;
+    if (!this._lruTail) {
+      this._lruTail = node;
+    }
+    this._lruSize++;
+  }
+  /** Remove a node from the list. */
+  _lruRemove(node) {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this._lruHead = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this._lruTail = node.prev;
+    }
+    node.prev = null;
+    node.next = null;
+    this._lruSize--;
+  }
+  /** Move a node to the front (most recently used). */
+  _lruTouch(node) {
+    if (this._lruHead === node) return;
+    this._lruRemove(node);
+    this._lruPush(node);
+  }
+  /** Evict the least recently used node. */
+  _evictLRU() {
+    if (!this._lruTail) return;
+    const uuid = this._lruTail.uuid;
+    this.dematerialize(uuid);
+  }
+};
+var _patched = false;
+var _originalAdd = null;
+var _originalRemove = null;
+var _activePairs = [];
+function findTrackingPair(obj) {
+  for (const pair of _activePairs) {
+    if (pair.store.isInTrackedScene(obj)) {
+      return pair;
+    }
+  }
+  return null;
+}
+function registerSubtree(obj, store, mirror) {
+  obj.traverse((child) => {
+    if (!store.has(child)) {
+      store.register(child);
+      mirror.onObjectAdded(child);
+    }
+  });
+}
+function patchObject3D(store, mirror) {
+  _activePairs.push({ store, mirror });
+  if (!_patched) {
+    _originalAdd = three.Object3D.prototype.add;
+    _originalRemove = three.Object3D.prototype.remove;
+    three.Object3D.prototype.add = function patchedAdd(...objects) {
+      _originalAdd.call(this, ...objects);
+      const pair = findTrackingPair(this);
+      if (pair) {
+        for (const obj of objects) {
+          if (obj === this) continue;
+          registerSubtree(obj, pair.store, pair.mirror);
+        }
+      }
+      return this;
+    };
+    three.Object3D.prototype.remove = function patchedRemove(...objects) {
+      const pair = findTrackingPair(this);
+      if (pair) {
+        for (const obj of objects) {
+          if (obj === this) continue;
+          pair.mirror.onObjectRemoved(obj);
+          obj.traverse((child) => {
+            pair.store.unregister(child);
+          });
+        }
+      }
+      _originalRemove.call(this, ...objects);
+      return this;
+    };
+    _patched = true;
+  }
+  return () => {
+    const idx = _activePairs.findIndex(
+      (p) => p.store === store && p.mirror === mirror
+    );
+    if (idx !== -1) {
+      _activePairs.splice(idx, 1);
+    }
+    if (_activePairs.length === 0 && _patched) {
+      restoreObject3D();
+    }
+  };
+}
+function restoreObject3D() {
+  if (!_patched) return;
+  if (_originalAdd) {
+    three.Object3D.prototype.add = _originalAdd;
+    _originalAdd = null;
+  }
+  if (_originalRemove) {
+    three.Object3D.prototype.remove = _originalRemove;
+    _originalRemove = null;
+  }
+  _patched = false;
+}
+function isPatched() {
+  return _patched;
+}
+
+// src/snapshot/snapshot.ts
+function buildNodeTree(store, meta) {
+  const children = [];
+  for (const childUuid of meta.childrenUuids) {
+    const childMeta = store.getByUuid(childUuid);
+    if (childMeta) {
+      children.push(buildNodeTree(store, childMeta));
+    }
+  }
+  return {
+    uuid: meta.uuid,
+    name: meta.name,
+    type: meta.type,
+    testId: meta.testId,
+    visible: meta.visible,
+    position: [...meta.position],
+    rotation: [...meta.rotation],
+    scale: [...meta.scale],
+    children
+  };
+}
+function findRoot(store) {
+  const allObjects = store.getFlatList();
+  for (const obj of allObjects) {
+    const meta = store.getMetadata(obj);
+    if (meta && meta.parentUuid === null) {
+      return meta;
+    }
+  }
+  return null;
+}
+function createSnapshot(store) {
+  const rootMeta = findRoot(store);
+  const tree = rootMeta ? buildNodeTree(store, rootMeta) : {
+    uuid: "",
+    name: "empty",
+    type: "Scene",
+    visible: true,
+    position: [0, 0, 0],
+    rotation: [0, 0, 0],
+    scale: [1, 1, 1],
+    children: []
+  };
+  return {
+    timestamp: Date.now(),
+    objectCount: store.getCount(),
+    tree
+  };
+}
+function createFlatSnapshot(store) {
+  const objects = [];
+  const allObjects = store.getFlatList();
+  for (const obj of allObjects) {
+    const meta = store.getMetadata(obj);
+    if (meta) {
+      objects.push({ ...meta });
+    }
+  }
+  return {
+    timestamp: Date.now(),
+    objectCount: objects.length,
+    objects
+  };
+}
+var _vec3 = /* @__PURE__ */ new three.Vector3();
+var _vec3B = /* @__PURE__ */ new three.Vector3();
+var _box32 = /* @__PURE__ */ new three.Box3();
+var _frustum = /* @__PURE__ */ new three.Frustum();
+var _projMatrix = /* @__PURE__ */ new three.Matrix4();
+function ndcToScreen(ndc, size) {
+  return {
+    x: (ndc.x + 1) / 2 * size.width,
+    y: (-ndc.y + 1) / 2 * size.height
+  };
+}
+function isNdcOnScreen(ndc) {
+  return ndc.x >= -1 && ndc.x <= 1 && ndc.y >= -1 && ndc.y <= 1 && ndc.z >= -1 && ndc.z <= 1;
+}
+function isInFrontOfCamera(ndc) {
+  return ndc.z >= -1 && ndc.z <= 1;
+}
+function getWorldCenter(obj) {
+  _box32.setFromObject(obj);
+  if (_box32.isEmpty()) {
+    obj.getWorldPosition(_vec3);
+    return _vec3;
+  }
+  _box32.getCenter(_vec3);
+  return _vec3;
+}
+function getBboxCorners(obj) {
+  _box32.setFromObject(obj);
+  if (_box32.isEmpty()) return [];
+  const { min, max } = _box32;
+  return [
+    new three.Vector3(min.x, min.y, min.z),
+    new three.Vector3(min.x, min.y, max.z),
+    new three.Vector3(min.x, max.y, min.z),
+    new three.Vector3(min.x, max.y, max.z),
+    new three.Vector3(max.x, min.y, min.z),
+    new three.Vector3(max.x, min.y, max.z),
+    new three.Vector3(max.x, max.y, min.z),
+    new three.Vector3(max.x, max.y, max.z)
+  ];
+}
+function getBboxFaceCenters(obj) {
+  _box32.setFromObject(obj);
+  if (_box32.isEmpty()) return [];
+  const center = _box32.getCenter(new three.Vector3());
+  const { min, max } = _box32;
+  return [
+    new three.Vector3(min.x, center.y, center.z),
+    // -X face
+    new three.Vector3(max.x, center.y, center.z),
+    // +X face
+    new three.Vector3(center.x, min.y, center.z),
+    // -Y face
+    new three.Vector3(center.x, max.y, center.z),
+    // +Y face
+    new three.Vector3(center.x, center.y, min.z),
+    // -Z face
+    new three.Vector3(center.x, center.y, max.z)
+    // +Z face
+  ];
+}
+function tryProjectPoint(worldPoint, camera, size) {
+  _vec3B.copy(worldPoint).project(camera);
+  if (!isInFrontOfCamera(_vec3B)) return null;
+  const screen = ndcToScreen(_vec3B, size);
+  return {
+    screen,
+    ndc: { x: _vec3B.x, y: _vec3B.y },
+    ndcZ: _vec3B.z,
+    onScreen: isNdcOnScreen(_vec3B)
+  };
+}
+function projectToScreen(obj, camera, size) {
+  obj.updateWorldMatrix(true, false);
+  camera.updateWorldMatrix(true, false);
+  const center = getWorldCenter(obj);
+  const centerResult = tryProjectPoint(center, camera, size);
+  if (centerResult && centerResult.onScreen) {
+    return {
+      point: centerResult.screen,
+      strategy: "center",
+      ndc: centerResult.ndc
+    };
+  }
+  const faceCenters = getBboxFaceCenters(obj);
+  const faceResult = findBestOnScreenPoint(faceCenters, camera, size);
+  if (faceResult) {
+    return {
+      point: faceResult.screen,
+      strategy: "face-center",
+      ndc: faceResult.ndc
+    };
+  }
+  const corners = getBboxCorners(obj);
+  const cornerResult = findBestOnScreenPoint(corners, camera, size);
+  if (cornerResult) {
+    return {
+      point: cornerResult.screen,
+      strategy: "corner",
+      ndc: cornerResult.ndc
+    };
+  }
+  obj.getWorldPosition(_vec3);
+  const originResult = tryProjectPoint(_vec3.clone(), camera, size);
+  if (originResult && originResult.onScreen) {
+    return {
+      point: originResult.screen,
+      strategy: "fallback-origin",
+      ndc: originResult.ndc
+    };
+  }
+  if (centerResult) {
+    return {
+      point: centerResult.screen,
+      strategy: "center",
+      ndc: centerResult.ndc
+    };
+  }
+  return null;
+}
+function findBestOnScreenPoint(candidates, camera, size) {
+  let bestResult = null;
+  let bestDistSq = Infinity;
+  const halfW = size.width / 2;
+  const halfH = size.height / 2;
+  for (const point of candidates) {
+    const result = tryProjectPoint(point, camera, size);
+    if (!result || !result.onScreen) continue;
+    const dx = result.screen.x - halfW;
+    const dy = result.screen.y - halfH;
+    const distSq = dx * dx + dy * dy;
+    if (distSq < bestDistSq) {
+      bestDistSq = distSq;
+      bestResult = { screen: result.screen, ndc: result.ndc };
+    }
+  }
+  return bestResult;
+}
+function isInFrustum(obj, camera) {
+  camera.updateWorldMatrix(true, false);
+  obj.updateWorldMatrix(true, false);
+  _projMatrix.multiplyMatrices(
+    camera.projectionMatrix,
+    camera.matrixWorldInverse
+  );
+  _frustum.setFromProjectionMatrix(_projMatrix);
+  _box32.setFromObject(obj);
+  if (_box32.isEmpty()) {
+    obj.getWorldPosition(_vec3);
+    return _frustum.containsPoint(_vec3);
+  }
+  return _frustum.intersectsBox(_box32);
+}
+function screenDeltaToWorld(dx, dy, obj, camera, size) {
+  obj.getWorldPosition(_vec3);
+  _vec3.project(camera);
+  const depth = _vec3.z;
+  const start = new three.Vector3(0, 0, depth).unproject(camera);
+  const right = new three.Vector3(2 / size.width, 0, depth).unproject(camera);
+  const up = new three.Vector3(0, -2 / size.height, depth).unproject(camera);
+  const rightDir = right.sub(start);
+  const upDir = up.sub(start);
+  return new three.Vector3().addScaledVector(rightDir, dx).addScaledVector(upDir, dy);
+}
+function projectAllSamplePoints(obj, camera, size) {
+  obj.updateWorldMatrix(true, false);
+  camera.updateWorldMatrix(true, false);
+  const points = [];
+  const candidates = [];
+  candidates.push(getWorldCenter(obj).clone());
+  candidates.push(...getBboxFaceCenters(obj));
+  candidates.push(...getBboxCorners(obj));
+  for (const wsPt of candidates) {
+    const result = tryProjectPoint(wsPt, camera, size);
+    if (result && result.onScreen) {
+      points.push(result.screen);
+    }
+  }
+  return points;
+}
+
+// src/interactions/dispatch.ts
+var _nextPointerId = 1e3;
+function allocPointerId() {
+  return _nextPointerId++;
+}
+function toClientCoords(canvas, point) {
+  const rect = canvas.getBoundingClientRect();
+  return {
+    clientX: rect.left + point.x,
+    clientY: rect.top + point.y
+  };
+}
+function makePointerInit(canvas, point, pointerId, overrides) {
+  const { clientX, clientY } = toClientCoords(canvas, point);
+  return {
+    bubbles: true,
+    cancelable: true,
+    composed: true,
+    clientX,
+    clientY,
+    screenX: clientX,
+    screenY: clientY,
+    pointerId,
+    pointerType: "mouse",
+    isPrimary: true,
+    button: 0,
+    buttons: 1,
+    width: 1,
+    height: 1,
+    pressure: 0.5,
+    ...overrides
+  };
+}
+function dispatchClick(canvas, point) {
+  withSafePointerCapture(() => {
+    const pointerId = allocPointerId();
+    canvas.dispatchEvent(
+      new PointerEvent("pointerdown", makePointerInit(canvas, point, pointerId))
+    );
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointerup",
+        makePointerInit(canvas, point, pointerId, { buttons: 0, pressure: 0 })
+      )
+    );
+    canvas.dispatchEvent(
+      new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+        ...toClientCoords(canvas, point),
+        button: 0
+      })
+    );
+  });
+}
+function dispatchHover(canvas, point) {
+  const pointerId = allocPointerId();
+  const init = makePointerInit(canvas, point, pointerId, {
+    buttons: 0,
+    pressure: 0
+  });
+  canvas.dispatchEvent(new PointerEvent("pointermove", init));
+  canvas.dispatchEvent(new PointerEvent("pointerover", init));
+  canvas.dispatchEvent(new PointerEvent("pointerenter", { ...init, bubbles: false }));
+}
+async function dispatchDrag(canvas, start, end, options = {}) {
+  const { steps = 10, stepDelayMs = 0 } = options;
+  const pointerId = allocPointerId();
+  withSafePointerCapture(() => {
+    canvas.dispatchEvent(
+      new PointerEvent("pointerdown", makePointerInit(canvas, start, pointerId))
+    );
+  });
+  for (let i = 1; i <= steps; i++) {
+    const t = i / steps;
+    const intermediate = {
+      x: start.x + (end.x - start.x) * t,
+      y: start.y + (end.y - start.y) * t
+    };
+    if (stepDelayMs > 0) {
+      await sleep(stepDelayMs);
+    }
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointermove",
+        makePointerInit(canvas, intermediate, pointerId)
+      )
+    );
+  }
+  withSafePointerCapture(() => {
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointerup",
+        makePointerInit(canvas, end, pointerId, { buttons: 0, pressure: 0 })
+      )
+    );
+  });
+}
+function dispatchDoubleClick(canvas, point) {
+  withSafePointerCapture(() => {
+    const pointerId = allocPointerId();
+    const coords = toClientCoords(canvas, point);
+    canvas.dispatchEvent(
+      new PointerEvent("pointerdown", makePointerInit(canvas, point, pointerId))
+    );
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointerup",
+        makePointerInit(canvas, point, pointerId, { buttons: 0, pressure: 0 })
+      )
+    );
+    canvas.dispatchEvent(
+      new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+        ...coords,
+        button: 0,
+        detail: 1
+      })
+    );
+    canvas.dispatchEvent(
+      new PointerEvent("pointerdown", makePointerInit(canvas, point, pointerId))
+    );
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointerup",
+        makePointerInit(canvas, point, pointerId, { buttons: 0, pressure: 0 })
+      )
+    );
+    canvas.dispatchEvent(
+      new MouseEvent("click", {
+        bubbles: true,
+        cancelable: true,
+        ...coords,
+        button: 0,
+        detail: 2
+      })
+    );
+    canvas.dispatchEvent(
+      new MouseEvent("dblclick", {
+        bubbles: true,
+        cancelable: true,
+        ...coords,
+        button: 0,
+        detail: 2
+      })
+    );
+  });
+}
+function dispatchContextMenu(canvas, point) {
+  withSafePointerCapture(() => {
+    const pointerId = allocPointerId();
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointerdown",
+        makePointerInit(canvas, point, pointerId, { button: 2, buttons: 2 })
+      )
+    );
+    canvas.dispatchEvent(
+      new PointerEvent(
+        "pointerup",
+        makePointerInit(canvas, point, pointerId, {
+          button: 2,
+          buttons: 0,
+          pressure: 0
+        })
+      )
+    );
+    canvas.dispatchEvent(
+      new MouseEvent("contextmenu", {
+        bubbles: true,
+        cancelable: true,
+        ...toClientCoords(canvas, point),
+        button: 2
+      })
+    );
+  });
+}
+function dispatchWheel(canvas, point, options = {}) {
+  const { deltaY = 100, deltaX = 0, deltaMode = 0 } = options;
+  const coords = toClientCoords(canvas, point);
+  canvas.dispatchEvent(
+    new WheelEvent("wheel", {
+      bubbles: true,
+      cancelable: true,
+      ...coords,
+      deltaX,
+      deltaY,
+      deltaZ: 0,
+      deltaMode
+    })
+  );
+}
+function dispatchPointerMiss(canvas, point = { x: 1, y: 1 }) {
+  dispatchClick(canvas, point);
+}
+function dispatchUnhover(canvas) {
+  const pointerId = allocPointerId();
+  const offScreen = { x: -9999, y: -9999 };
+  const init = makePointerInit(canvas, offScreen, pointerId, {
+    buttons: 0,
+    pressure: 0
+  });
+  canvas.dispatchEvent(new PointerEvent("pointermove", init));
+  canvas.dispatchEvent(new PointerEvent("pointerout", init));
+  canvas.dispatchEvent(new PointerEvent("pointerleave", { ...init, bubbles: false }));
+}
+function withSafePointerCapture(fn) {
+  const original = Element.prototype.releasePointerCapture;
+  Element.prototype.releasePointerCapture = function safeRelease(pointerId) {
+    try {
+      original.call(this, pointerId);
+    } catch {
+    }
+  };
+  try {
+    return fn();
+  } finally {
+    Element.prototype.releasePointerCapture = original;
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var _raycaster = /* @__PURE__ */ new three.Raycaster();
+var _ndc = /* @__PURE__ */ new three.Vector2();
+function screenToNdc(point, size) {
+  _ndc.set(
+    point.x / size.width * 2 - 1,
+    -(point.y / size.height) * 2 + 1
+  );
+  return _ndc;
+}
+function getObjectLabel(obj) {
+  const testId = obj.userData?.testId;
+  if (testId) return `testId="${testId}"`;
+  if (obj.name) return `name="${obj.name}"`;
+  return `uuid="${obj.uuid.slice(0, 8)}\u2026"`;
+}
+function isTargetOrDescendant(candidate, target) {
+  let current = candidate;
+  while (current) {
+    if (current === target) return true;
+    current = current.parent;
+  }
+  return false;
+}
+function findScene(obj) {
+  let current = obj;
+  while (current) {
+    if (current.isScene) return current;
+    current = current.parent;
+  }
+  return null;
+}
+function verifyRaycastHit(point, target, camera, size) {
+  const scene = findScene(target);
+  if (!scene) {
+    return { hit: false, occluderLabel: "object not in scene" };
+  }
+  const ndc = screenToNdc(point, size);
+  _raycaster.setFromCamera(ndc, camera);
+  const intersections = _raycaster.intersectObjects(scene.children, true);
+  if (intersections.length === 0) {
+    return { hit: true };
+  }
+  const firstHit = intersections[0].object;
+  if (isTargetOrDescendant(firstHit, target)) {
+    return { hit: true };
+  }
+  const targetHit = intersections.find(
+    (i) => isTargetOrDescendant(i.object, target)
+  );
+  if (targetHit) {
+    return {
+      hit: false,
+      occluder: firstHit,
+      occluderLabel: getObjectLabel(firstHit)
+    };
+  }
+  return {
+    hit: false,
+    occluder: firstHit,
+    occluderLabel: getObjectLabel(firstHit)
+  };
+}
+function verifyRaycastHitMultiPoint(points, target, camera, size) {
+  let lastResult = { hit: false };
+  for (const point of points) {
+    const result = verifyRaycastHit(point, target, camera, size);
+    if (result.hit) return result;
+    lastResult = result;
+  }
+  return lastResult;
+}
+
+// src/interactions/resolve.ts
+var _store2 = null;
+var _camera = null;
+var _gl = null;
+var _size = null;
+function setInteractionState(store, camera, gl, size) {
+  _store2 = store;
+  _camera = camera;
+  _gl = gl;
+  _size = size;
+}
+function clearInteractionState() {
+  _store2 = null;
+  _camera = null;
+  _gl = null;
+  _size = null;
+}
+function getStore() {
+  if (!_store2) {
+    throw new Error(
+      "[react-three-dom] Interaction state not initialized. Is <ThreeDom> mounted?"
+    );
+  }
+  return _store2;
+}
+function getCamera() {
+  if (!_camera) {
+    throw new Error(
+      "[react-three-dom] Camera not available. Is <ThreeDom> mounted?"
+    );
+  }
+  return _camera;
+}
+function getRenderer() {
+  if (!_gl) {
+    throw new Error(
+      "[react-three-dom] Renderer not available. Is <ThreeDom> mounted?"
+    );
+  }
+  return _gl;
+}
+function getCanvasSize() {
+  if (!_size) {
+    throw new Error(
+      "[react-three-dom] Canvas size not available. Is <ThreeDom> mounted?"
+    );
+  }
+  return _size;
+}
+function resolveObject(idOrUuid) {
+  const store = getStore();
+  const obj = store.getObject3D(idOrUuid);
+  if (!obj) {
+    throw new Error(
+      `[react-three-dom] Object "${idOrUuid}" not found. Check that the object has userData.testId="${idOrUuid}" or uuid="${idOrUuid}".`
+    );
+  }
+  return obj;
+}
+
+// src/interactions/click.ts
+function click3D(idOrUuid, options = {}) {
+  const { verify = true } = options;
+  const obj = resolveObject(idOrUuid);
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const projection = projectToScreen(obj, camera, size);
+  if (!projection) {
+    throw new Error(
+      `[react-three-dom] click3D("${idOrUuid}") failed: object is not visible on screen. It may be behind the camera or outside the viewport.`
+    );
+  }
+  const canvas = gl.domElement;
+  dispatchClick(canvas, projection.point);
+  let raycast;
+  if (verify) {
+    raycast = verifyRaycastHit(projection.point, obj, camera, size);
+    if (!raycast.hit && raycast.occluderLabel) {
+      console.warn(
+        `[react-three-dom] click3D("${idOrUuid}") dispatched at (${Math.round(projection.point.x)}, ${Math.round(projection.point.y)}) but raycast hit ${raycast.occluderLabel} instead. The object may be occluded.`
+      );
+    }
+  }
+  return {
+    dispatched: true,
+    raycast,
+    screenPoint: projection.point,
+    strategy: projection.strategy
+  };
+}
+function doubleClick3D(idOrUuid, options = {}) {
+  const { verify = true } = options;
+  const obj = resolveObject(idOrUuid);
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const projection = projectToScreen(obj, camera, size);
+  if (!projection) {
+    throw new Error(
+      `[react-three-dom] doubleClick3D("${idOrUuid}") failed: object is not visible on screen.`
+    );
+  }
+  const canvas = gl.domElement;
+  dispatchDoubleClick(canvas, projection.point);
+  let raycast;
+  if (verify) {
+    raycast = verifyRaycastHit(projection.point, obj, camera, size);
+    if (!raycast.hit && raycast.occluderLabel) {
+      console.warn(
+        `[react-three-dom] doubleClick3D("${idOrUuid}") dispatched at (${Math.round(projection.point.x)}, ${Math.round(projection.point.y)}) but raycast hit ${raycast.occluderLabel} instead.`
+      );
+    }
+  }
+  return {
+    dispatched: true,
+    raycast,
+    screenPoint: projection.point,
+    strategy: projection.strategy
+  };
+}
+function contextMenu3D(idOrUuid, options = {}) {
+  const { verify = true } = options;
+  const obj = resolveObject(idOrUuid);
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const projection = projectToScreen(obj, camera, size);
+  if (!projection) {
+    throw new Error(
+      `[react-three-dom] contextMenu3D("${idOrUuid}") failed: object is not visible on screen.`
+    );
+  }
+  const canvas = gl.domElement;
+  dispatchContextMenu(canvas, projection.point);
+  let raycast;
+  if (verify) {
+    raycast = verifyRaycastHit(projection.point, obj, camera, size);
+    if (!raycast.hit && raycast.occluderLabel) {
+      console.warn(
+        `[react-three-dom] contextMenu3D("${idOrUuid}") dispatched at (${Math.round(projection.point.x)}, ${Math.round(projection.point.y)}) but raycast hit ${raycast.occluderLabel} instead.`
+      );
+    }
+  }
+  return {
+    dispatched: true,
+    raycast,
+    screenPoint: projection.point,
+    strategy: projection.strategy
+  };
+}
+
+// src/interactions/hover.ts
+function hover3D(idOrUuid, options = {}) {
+  const { verify = true } = options;
+  const obj = resolveObject(idOrUuid);
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const projection = projectToScreen(obj, camera, size);
+  if (!projection) {
+    throw new Error(
+      `[react-three-dom] hover3D("${idOrUuid}") failed: object is not visible on screen. It may be behind the camera or outside the viewport.`
+    );
+  }
+  const canvas = gl.domElement;
+  dispatchHover(canvas, projection.point);
+  let raycast;
+  if (verify) {
+    raycast = verifyRaycastHit(projection.point, obj, camera, size);
+    if (!raycast.hit && raycast.occluderLabel) {
+      console.warn(
+        `[react-three-dom] hover3D("${idOrUuid}") dispatched at (${Math.round(projection.point.x)}, ${Math.round(projection.point.y)}) but raycast hit ${raycast.occluderLabel} instead.`
+      );
+    }
+  }
+  return {
+    dispatched: true,
+    raycast,
+    screenPoint: projection.point,
+    strategy: projection.strategy
+  };
+}
+function unhover3D() {
+  const gl = getRenderer();
+  dispatchUnhover(gl.domElement);
+}
+async function drag3D(idOrUuid, delta, options = {}) {
+  const { mode = "world", ...dragOptions } = options;
+  const obj = resolveObject(idOrUuid);
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const projection = projectToScreen(obj, camera, size);
+  if (!projection) {
+    throw new Error(
+      `[react-three-dom] drag3D("${idOrUuid}") failed: object is not visible on screen. It may be behind the camera or outside the viewport.`
+    );
+  }
+  const startPoint = projection.point;
+  let endPoint;
+  if (mode === "screen" && "dx" in delta) {
+    const screenDelta = delta;
+    endPoint = {
+      x: startPoint.x + screenDelta.dx,
+      y: startPoint.y + screenDelta.dy
+    };
+  } else {
+    const worldDelta = delta;
+    const worldPos = new three.Vector3();
+    obj.getWorldPosition(worldPos);
+    const targetPos = worldPos.clone().add(new three.Vector3(worldDelta.x, worldDelta.y, worldDelta.z));
+    targetPos.project(camera);
+    endPoint = {
+      x: (targetPos.x + 1) / 2 * size.width,
+      y: (-targetPos.y + 1) / 2 * size.height
+    };
+  }
+  const canvas = gl.domElement;
+  await dispatchDrag(canvas, startPoint, endPoint, dragOptions);
+  return {
+    dispatched: true,
+    startPoint,
+    endPoint,
+    strategy: projection.strategy
+  };
+}
+function previewDragWorldDelta(idOrUuid, screenDx, screenDy) {
+  const obj = resolveObject(idOrUuid);
+  const camera = getCamera();
+  const size = getCanvasSize();
+  return screenDeltaToWorld(screenDx, screenDy, obj, camera, size);
+}
+
+// src/interactions/wheel.ts
+function wheel3D(idOrUuid, options = {}) {
+  const obj = resolveObject(idOrUuid);
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const projection = projectToScreen(obj, camera, size);
+  if (!projection) {
+    throw new Error(
+      `[react-three-dom] wheel3D("${idOrUuid}") failed: object is not visible on screen.`
+    );
+  }
+  const canvas = gl.domElement;
+  dispatchWheel(canvas, projection.point, options);
+  return {
+    dispatched: true,
+    screenPoint: projection.point,
+    strategy: projection.strategy
+  };
+}
+
+// src/interactions/pointerMiss.ts
+function pointerMiss3D(options = {}) {
+  const gl = getRenderer();
+  const canvas = gl.domElement;
+  dispatchPointerMiss(canvas, options.point);
+}
+
+// src/highlight/SelectionManager.ts
+var SelectionManager = class {
+  constructor() {
+    /** Currently selected objects (ordered by selection time). */
+    this._selected = [];
+    /** Listeners notified on selection change. */
+    this._listeners = [];
+  }
+  // -----------------------------------------------------------------------
+  // Selection API
+  // -----------------------------------------------------------------------
+  /** Select a single object (clears previous selection). */
+  select(obj) {
+    if (this._selected.length === 1 && this._selected[0] === obj) return;
+    this._selected = [obj];
+    this._notify();
+  }
+  /** Add an object to the current selection (multi-select). */
+  addToSelection(obj) {
+    if (this._selected.includes(obj)) return;
+    this._selected.push(obj);
+    this._notify();
+  }
+  /** Remove an object from the selection. */
+  removeFromSelection(obj) {
+    const idx = this._selected.indexOf(obj);
+    if (idx === -1) return;
+    this._selected.splice(idx, 1);
+    this._notify();
+  }
+  /** Toggle an object in/out of the selection. */
+  toggleSelection(obj) {
+    if (this._selected.includes(obj)) {
+      this.removeFromSelection(obj);
+    } else {
+      this.addToSelection(obj);
+    }
+  }
+  /** Clear all selections. */
+  clearSelection() {
+    if (this._selected.length === 0) return;
+    this._selected = [];
+    this._notify();
+  }
+  /** Get the currently selected objects. */
+  getSelected() {
+    return this._selected;
+  }
+  /** Get the primary (first) selected object, or null. */
+  getPrimary() {
+    return this._selected[0] ?? null;
+  }
+  /** Check if an object is selected. */
+  isSelected(obj) {
+    return this._selected.includes(obj);
+  }
+  /** Number of selected objects. */
+  get count() {
+    return this._selected.length;
+  }
+  // -----------------------------------------------------------------------
+  // Event system
+  // -----------------------------------------------------------------------
+  /** Subscribe to selection changes. Returns unsubscribe function. */
+  subscribe(listener) {
+    this._listeners.push(listener);
+    return () => {
+      const idx = this._listeners.indexOf(listener);
+      if (idx !== -1) this._listeners.splice(idx, 1);
+    };
+  }
+  _notify() {
+    const snapshot = [...this._selected];
+    for (const listener of this._listeners) {
+      listener(snapshot);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+  dispose() {
+    this._selected = [];
+    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 = {
+    getByTestId: (id) => store.getByTestId(id),
+    getByUuid: (uuid) => store.getByUuid(uuid),
+    getByName: (name) => store.getByName(name),
+    getCount: () => store.getCount(),
+    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: (idOrUuid, delta) => {
+      void drag3D(idOrUuid, delta);
+    },
+    wheel: (idOrUuid, options) => {
+      wheel3D(idOrUuid, options);
+    },
+    pointerMiss: () => {
+      pointerMiss3D();
+    },
+    select: (idOrUuid) => {
+      const obj = store.getObject3D(idOrUuid);
+      if (obj && _selectionManager) _selectionManager.select(obj);
+    },
+    clearSelection: () => {
+      _selectionManager?.clearSelection();
+    },
+    getObject3D: (idOrUuid) => store.getObject3D(idOrUuid),
+    version
+  };
+  window.__R3F_DOM__ = api;
+}
+function removeGlobalAPI() {
+  delete window.__R3F_DOM__;
+}
+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);
+  }
+}
+function ThreeDom({
+  root = "#three-dom-root",
+  batchSize = 500,
+  timeBudgetMs = 0.5,
+  maxDomNodes = 2e3,
+  initialDepth = 3,
+  enabled = true
+} = {}) {
+  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;
+    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(";");
+    const store = new ObjectStore();
+    const mirror = new DomMirror(store, maxDomNodes);
+    mirror.setRoot(rootElement);
+    ensureCustomElements(store);
+    store.registerTree(scene);
+    mirror.materializeSubtree(scene.uuid, initialDepth);
+    const unpatch = patchObject3D(store, mirror);
+    setInteractionState(store, camera, gl, size);
+    const selectionManager = new SelectionManager();
+    _selectionManager = selectionManager;
+    _highlighter = null;
+    exposeGlobalAPI(store);
+    _store3 = store;
+    _mirror = mirror;
+    const initialCanvasRect = canvas.getBoundingClientRect();
+    const allObjects = store.getFlatList();
+    for (const obj of allObjects) {
+      if (obj.userData?.__r3fdom_internal) continue;
+      const el = mirror.getElement(obj.uuid);
+      if (!el) continue;
+      if (obj.type === "Scene") {
+        setElementRect(el, 0, 0, Math.round(initialCanvasRect.width), Math.round(initialCanvasRect.height));
+        continue;
+      }
+      const rect = projectToScreenRect(obj, camera, initialCanvasRect);
+      if (rect) {
+        let parentLeft = 0;
+        let parentTop = 0;
+        if (obj.parent && obj.parent.type !== "Scene") {
+          const parentRect = projectToScreenRect(obj.parent, camera, initialCanvasRect);
+          if (parentRect) {
+            parentLeft = Math.round(parentRect.left);
+            parentTop = Math.round(parentRect.top);
+          }
+        }
+        setElementRect(
+          el,
+          Math.round(rect.left) - parentLeft,
+          Math.round(rect.top) - parentTop,
+          Math.round(rect.width),
+          Math.round(rect.height)
+        );
+      }
+    }
+    return () => {
+      unpatch();
+      removeGlobalAPI();
+      clearInteractionState();
+      selectionManager.dispose();
+      mirror.dispose();
+      store.dispose();
+      if (createdRoot && rootElement?.parentNode) {
+        rootElement.parentNode.removeChild(rootElement);
+      }
+      _store3 = null;
+      _mirror = null;
+      _selectionManager = null;
+      _highlighter = null;
+    };
+  }, [scene, camera, gl, size, enabled, root, maxDomNodes, initialDepth]);
+  fiber.useFrame(() => {
+    if (!enabled || !_store3 || !_mirror) return;
+    setInteractionState(_store3, camera, gl, size);
+    const store = _store3;
+    const mirror = _mirror;
+    const canvas = gl.domElement;
+    const canvasRect = canvas.getBoundingClientRect();
+    const start = performance.now();
+    const dirtyObjects = store.drainDirtyQueue();
+    for (const obj of dirtyObjects) {
+      store.update(obj);
+      mirror.syncAttributes(obj);
+    }
+    const budgetRemaining = timeBudgetMs - (performance.now() - start);
+    if (budgetRemaining > 0.1) {
+      const objects2 = store.getFlatList();
+      if (objects2.length > 0) {
+        const end = Math.min(cursorRef.current + batchSize, objects2.length);
+        for (let i = cursorRef.current; i < end; i++) {
+          if (performance.now() - start > timeBudgetMs) break;
+          const obj = objects2[i];
+          const changed = store.update(obj);
+          if (changed) mirror.syncAttributes(obj);
+        }
+        cursorRef.current = end >= objects2.length ? 0 : end;
+      }
+    }
+    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;
+    }
+  });
+  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;
+    }
+    this._stopHoverPolling();
+    this._clearAllOverlays(this._selectedEntries);
+    this._clearAllOverlays(this._hoverEntries);
+    this._camera = null;
+    this._renderer = null;
+    this._store = null;
+  }
+  // -----------------------------------------------------------------------
+  // Per-frame update — reposition all overlays to follow camera/objects
+  // -----------------------------------------------------------------------
+  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);
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  highlight(obj) {
+    this._addSelectedHighlight(obj, false);
+  }
+  unhighlight(obj) {
+    this._removeOverlay(obj, this._selectedEntries);
+  }
+  clearAll() {
+    this._clearAllOverlays(this._selectedEntries);
+    this._clearAllOverlays(this._hoverEntries);
+  }
+  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;
+  }
+  // -----------------------------------------------------------------------
+  // 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);
+      });
+    }
+    for (const [obj] of this._selectedEntries) {
+      if (!targetSet.has(obj)) {
+        this._removeOverlay(obj, this._selectedEntries);
+      }
+    }
+    for (const obj of targetSet) {
+      if (obj.userData?.__r3fdom_internal) continue;
+      if (!this._selectedEntries.has(obj)) {
+        const isChild = !primarySet.has(obj);
+        this._addSelectedHighlight(obj, isChild);
+      }
+    }
+  }
+  _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";
+    }
+    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);
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal: DevTools hover polling
+  // -----------------------------------------------------------------------
+  _startHoverPolling() {
+    this._hoverPollId = setInterval(() => {
+      this._pollDevToolsHover();
+    }, 100);
+  }
+  _stopHoverPolling() {
+    if (this._hoverPollId) {
+      clearInterval(this._hoverPollId);
+      this._hoverPollId = null;
+    }
+  }
+  _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");
+      if (!uuid) {
+        this._clearAllOverlays(this._hoverEntries);
+        return;
+      }
+      const obj = this._store.getObject3D(uuid);
+      if (obj) {
+        this.showHoverHighlight(obj);
+      } else {
+        this._clearAllOverlays(this._hoverEntries);
+      }
+    } catch {
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Internal: overlay 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();
+    }
+    map.clear();
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+  dispose() {
+    this.detach();
+  }
+};
+
+exports.DomMirror = DomMirror;
+exports.Highlighter = Highlighter;
+exports.MANAGED_ATTRIBUTES = MANAGED_ATTRIBUTES;
+exports.ObjectStore = ObjectStore;
+exports.SelectionManager = SelectionManager;
+exports.TAG_MAP = TAG_MAP;
+exports.ThreeDom = ThreeDom;
+exports.ThreeElement = ThreeElement;
+exports.applyAttributes = applyAttributes;
+exports.click3D = click3D;
+exports.computeAttributes = computeAttributes;
+exports.contextMenu3D = contextMenu3D;
+exports.createFlatSnapshot = createFlatSnapshot;
+exports.createSnapshot = createSnapshot;
+exports.dispatchClick = dispatchClick;
+exports.dispatchContextMenu = dispatchContextMenu;
+exports.dispatchDoubleClick = dispatchDoubleClick;
+exports.dispatchDrag = dispatchDrag;
+exports.dispatchHover = dispatchHover;
+exports.dispatchPointerMiss = dispatchPointerMiss;
+exports.dispatchUnhover = dispatchUnhover;
+exports.dispatchWheel = dispatchWheel;
+exports.doubleClick3D = doubleClick3D;
+exports.drag3D = drag3D;
+exports.ensureCustomElements = ensureCustomElements;
+exports.getHighlighter = getHighlighter;
+exports.getMirror = getMirror;
+exports.getSelectionManager = getSelectionManager;
+exports.getStore = getStore2;
+exports.getTagForType = getTagForType;
+exports.hover3D = hover3D;
+exports.isInFrustum = isInFrustum;
+exports.isPatched = isPatched;
+exports.patchObject3D = patchObject3D;
+exports.pointerMiss3D = pointerMiss3D;
+exports.previewDragWorldDelta = previewDragWorldDelta;
+exports.projectAllSamplePoints = projectAllSamplePoints;
+exports.projectToScreen = projectToScreen;
+exports.resolveObject = resolveObject;
+exports.restoreObject3D = restoreObject3D;
+exports.screenDeltaToWorld = screenDeltaToWorld;
+exports.unhover3D = unhover3D;
+exports.verifyRaycastHit = verifyRaycastHit;
+exports.verifyRaycastHitMultiPoint = verifyRaycastHitMultiPoint;
+exports.version = version;
+exports.wheel3D = wheel3D;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map