@react-three-dom/core 0.3.0 → 0.5.0

package/dist/index.cjs

@@ -6,7 +6,7 @@ var fiber = require('@react-three/fiber');
 var threeMeshBvh = require('three-mesh-bvh');
 
 // src/version.ts
-var version = "0.3.0";
+var version = "0.5.0";
 
 // src/debug.ts
 var _enabled = false;
@@ -401,6 +401,7 @@ var ObjectStore = class {
     this._dirtyQueue.delete(obj);
     this._flatListDirty = true;
     delete obj.userData.__r3fdom_tracked;
+    delete obj.userData.__r3fdom_manual;
     if (meta.testId) {
       this._objectsByTestId.delete(meta.testId);
     }
@@ -421,6 +422,10 @@ var ObjectStore = class {
   /**
    * Unregister an entire subtree (object + all descendants).
    */
+  /** Mark a root as tracked without traversing/registering its children. */
+  addTrackedRoot(root) {
+    this._trackedRoots.add(root);
+  }
   unregisterTree(root) {
     root.traverse((obj) => {
       this.unregister(obj);
@@ -1517,16 +1522,17 @@ function findTrackingPair(obj) {
   }
   return null;
 }
-function registerSubtree(obj, store, mirror) {
+function registerSubtree(obj, store, mirror, instanceKey) {
   obj.traverse((child) => {
-    if (!store.has(child)) {
+    if (!store.has(child) && shouldRegister(instanceKey, child)) {
+      ensureAncestorChain(child, store, mirror);
       store.register(child);
       mirror.onObjectAdded(child);
     }
   });
 }
-function patchObject3D(store, mirror) {
-  _activePairs.push({ store, mirror });
+function patchObject3D(store, mirror, instanceKey = "") {
+  _activePairs.push({ store, mirror, instanceKey });
   if (!_patched) {
     r3fLog("patch", "Patching Object3D.prototype.add and .remove");
     _originalAdd = three.Object3D.prototype.add;
@@ -1539,7 +1545,7 @@ function patchObject3D(store, mirror) {
           if (obj === this) continue;
           try {
             r3fLog("patch", `patchedAdd: "${obj.name || obj.type}" added to "${this.name || this.type}"`);
-            registerSubtree(obj, pair.store, pair.mirror);
+            registerSubtree(obj, pair.store, pair.mirror, pair.instanceKey);
           } catch (err) {
             r3fLog("patch", `patchedAdd: failed to register "${obj.name || obj.type}"`, err);
           }
@@ -3098,7 +3104,7 @@ var InspectController = class {
     this._overlay = overlay;
     r3fLog("inspect", "Inspect mode enabled \u2014 hover to highlight, click to select");
   }
-  /** Deactivate inspect mode — removes overlay and clears hover state. */
+  /** Deactivate inspect mode — removes overlay and clears all inspect state. */
   disable() {
     if (!this._active) return;
     this._active = false;
@@ -3345,6 +3351,30 @@ var _mirrors = /* @__PURE__ */ new Map();
 var _selectionManagers = /* @__PURE__ */ new Map();
 var _highlighters = /* @__PURE__ */ new Map();
 var _inspectControllers = /* @__PURE__ */ new Map();
+var _filters = /* @__PURE__ */ new Map();
+var _modes = /* @__PURE__ */ new Map();
+function shouldRegister(instanceKey, obj) {
+  const mode = _modes.get(instanceKey);
+  if (mode === "manual") return false;
+  const filter = _filters.get(instanceKey);
+  if (filter) return filter(obj);
+  return true;
+}
+function ensureAncestorChain(obj, store, mirror) {
+  const chain = [];
+  let cursor = obj.parent;
+  while (cursor) {
+    if (store.has(cursor)) break;
+    chain.push(cursor);
+    cursor = cursor.parent;
+  }
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const ancestor = chain[i];
+    store.register(ancestor);
+    mirror.onObjectAdded(ancestor);
+    mirror.materialize(ancestor.uuid);
+  }
+}
 function getStore2(canvasId = "") {
   return _stores.get(canvasId) ?? null;
 }
@@ -3495,6 +3525,38 @@ function exposeGlobalAPI(store, gl, cameraRef, selMgr, inspCtrl, mirror, canvasI
       }
       return state;
     },
+    r3fRegister: (obj) => {
+      if (store.has(obj)) return;
+      if (!store.isInTrackedScene(obj)) {
+        console.warn(
+          `[react-three-dom] r3fRegister: object "${obj.userData?.testId || obj.name || obj.uuid.slice(0, 8)}" is not in a tracked scene. Add it to the scene graph first.`
+        );
+        return;
+      }
+      obj.userData.__r3fdom_manual = true;
+      ensureAncestorChain(obj, store, mirror);
+      let count = 0;
+      obj.traverse((child) => {
+        if (!store.has(child)) {
+          store.register(child);
+          mirror?.onObjectAdded(child);
+          mirror?.materialize(child.uuid);
+          count++;
+        }
+      });
+      r3fLog("bridge", `r3fRegister: "${obj.userData?.testId || obj.name || obj.uuid.slice(0, 8)}" (${obj.type}) \u2014 ${count} objects`);
+    },
+    r3fUnregister: (obj) => {
+      if (!store.has(obj)) return;
+      if (!obj.userData?.__r3fdom_manual) {
+        r3fLog("bridge", `r3fUnregister skipped \u2014 "${obj.userData?.testId || obj.name || obj.uuid.slice(0, 8)}" was auto-registered`);
+        return;
+      }
+      delete obj.userData.__r3fdom_manual;
+      mirror?.onObjectRemoved(obj);
+      obj.traverse((child) => store.unregister(child));
+      r3fLog("bridge", `r3fUnregister: "${obj.userData?.testId || obj.name || obj.uuid.slice(0, 8)}" (${obj.type})`);
+    },
     fuzzyFind: (query, limit = 5) => {
       const q = query.toLowerCase();
       const results = [];
@@ -3617,6 +3679,10 @@ function createStubBridge(error, canvasId) {
     setInspectMode: () => {
     },
     getInspectMode: () => false,
+    r3fRegister: () => {
+    },
+    r3fUnregister: () => {
+    },
     sweepOrphans: () => 0,
     getDiagnostics: () => ({
       version,
@@ -3651,6 +3717,8 @@ function ThreeDom({
   canvasId,
   primary,
   root = "#three-dom-root",
+  mode = "auto",
+  filter,
   batchSize = 500,
   syncBudgetMs = 0.5,
   maxDomNodes = 2e3,
@@ -3725,18 +3793,42 @@ function ThreeDom({
       mirror.setRoot(rootElement);
       r3fLog("setup", "Store and mirror created");
       ensureCustomElements(store);
-      unpatch = patchObject3D(store, mirror);
+      _modes.set(instanceKey, mode);
+      _filters.set(instanceKey, filter ?? null);
+      unpatch = patchObject3D(store, mirror, instanceKey);
       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);
+      r3fLog("setup", `Object3D patched (mode=${mode}), interaction state set`);
+      if (mode === "auto") {
+        if (filter) {
+          store.addTrackedRoot(scene);
+          store.register(scene);
+          mirror.onObjectAdded(scene);
+          scene.traverse((obj) => {
+            if (obj === scene) return;
+            if (filter(obj)) {
+              ensureAncestorChain(obj, store, mirror);
+              store.register(obj);
+              mirror.onObjectAdded(obj);
+            }
+          });
+        } else {
+          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);
+        if (!filter) {
+          cancelAsyncReg = store.registerTreeAsync(scene);
+        }
+      } else {
+        store.addTrackedRoot(scene);
+        store.register(scene);
+        mirror.onObjectAdded(scene);
       }
-      mirror.materializeSubtree(scene.uuid, initialDepth);
-      cancelAsyncReg = store.registerTreeAsync(scene);
-      r3fLog("setup", `Scene registered: ${store.getCount()} objects, async watcher started`);
+      r3fLog("setup", `Scene registered (mode=${mode}): ${store.getCount()} objects`);
       selectionManager = new SelectionManager();
       highlighter = new Highlighter();
       highlighter.attach(scene, selectionManager, camera, gl, store);
@@ -3808,6 +3900,8 @@ function ThreeDom({
       _selectionManagers.delete(instanceKey);
       _highlighters.delete(instanceKey);
       _inspectControllers.delete(instanceKey);
+      _modes.delete(instanceKey);
+      _filters.delete(instanceKey);
       if (debug) enableDebug(false);
       r3fLog("setup", "ThreeDom cleanup complete");
     };
@@ -3855,6 +3949,41 @@ function ThreeDom({
   });
   return null;
 }
+function getAPI(canvasId) {
+  if (canvasId) {
+    return window.__R3F_DOM_INSTANCES__?.[canvasId];
+  }
+  return window.__R3F_DOM__;
+}
+function useR3FRegister(ref, canvasId) {
+  const trackedObj = react.useRef(null);
+  const canvasIdRef = react.useRef(canvasId);
+  canvasIdRef.current = canvasId;
+  const register = react.useCallback((obj) => {
+    const api = getAPI(canvasIdRef.current);
+    if (!api) return false;
+    api.r3fRegister(obj);
+    trackedObj.current = obj;
+    return true;
+  }, []);
+  const unregister = react.useCallback(() => {
+    if (!trackedObj.current) return;
+    const api = getAPI(canvasIdRef.current);
+    api?.r3fUnregister(trackedObj.current);
+    trackedObj.current = null;
+  }, []);
+  react.useEffect(() => {
+    const obj = ref.current;
+    if (obj) register(obj);
+    return () => unregister();
+  }, [ref, register, unregister]);
+  fiber.useFrame(() => {
+    const current = ref.current;
+    if (current === trackedObj.current) return;
+    unregister();
+    if (current) register(current);
+  });
+}
 
 exports.DomMirror = DomMirror;
 exports.Highlighter = Highlighter;
@@ -3910,6 +4039,7 @@ exports.resolveObject = resolveObject;
 exports.restoreObject3D = restoreObject3D;
 exports.screenDeltaToWorld = screenDeltaToWorld;
 exports.unhover3D = unhover3D;
+exports.useR3FRegister = useR3FRegister;
 exports.verifyRaycastHit = verifyRaycastHit;
 exports.verifyRaycastHitMultiPoint = verifyRaycastHitMultiPoint;
 exports.version = version;