@react-three-dom/core 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Object3D, Scene, Camera, WebGLRenderer, Intersection, Vector3 } from 'three';
 
-declare const version = "0.3.0";
+declare const version = "0.5.0";
 
 /**
  * Enable or disable debug logging globally.
@@ -261,6 +261,17 @@ interface R3FDOM {
     setInspectMode(on: boolean): void;
     /** Returns true if inspect mode is currently active. */
     getInspectMode(): boolean;
+    /**
+     * Manually register a Three.js object (and materialize its mirror DOM node).
+     * Useful in `manual` mode or to add specific objects in `auto` mode that
+     * were excluded by a filter.
+     */
+    r3fRegister(obj: Object3D): void;
+    /**
+     * Unregister a previously registered object and its descendants.
+     * Removes the mirror DOM node and store entry.
+     */
+    r3fUnregister(obj: Object3D): void;
     /**
      * Manually sweep orphaned objects from the store.
      * Removes objects that are no longer in any tracked scene graph.
@@ -400,6 +411,8 @@ declare class ObjectStore {
     /**
      * Unregister an entire subtree (object + all descendants).
      */
+    /** Mark a root as tracked without traversing/registering its children. */
+    addTrackedRoot(root: Object3D): void;
     unregisterTree(root: Object3D): void;
     /**
      * Refresh dynamic Tier 1 fields from the live Three.js object.
@@ -1010,7 +1023,7 @@ declare class InspectController {
     updateCamera(camera: Camera): void;
     /** Activate inspect mode — creates overlay on top of canvas. */
     enable(): void;
-    /** Deactivate inspect mode — removes overlay and clears hover state. */
+    /** Deactivate inspect mode — removes overlay and clears all inspect state. */
     disable(): void;
     /** Disable and release all resources. */
     dispose(): void;
@@ -1044,6 +1057,19 @@ interface ThreeDomProps {
      * Default: true when canvasId is omitted, false otherwise.
      */
     primary?: boolean;
+    /**
+     * Registration mode:
+     * - "auto" (default): traverses and registers all objects in the scene.
+     * - "manual": nothing is auto-registered. Use `useR3FRegister` hook or
+     *   `__R3F_DOM__.r3fRegister()` to add objects explicitly.
+     */
+    mode?: 'auto' | 'manual';
+    /**
+     * Filter function for auto mode. Only objects that pass the filter are
+     * registered. Ignored in manual mode.
+     * Example: `filter={(obj) => !!obj.userData.testId}`
+     */
+    filter?: (obj: Object3D) => boolean;
     /** CSS selector or HTMLElement for the mirror DOM root. Default: "#three-dom-root" */
     root?: string | HTMLElement;
     /** Objects to process per amortized batch per frame. Default: 500 */
@@ -1073,7 +1099,7 @@ declare function getHighlighter(canvasId?: string): Highlighter | null;
 declare function getInspectController(canvasId?: string): InspectController | null;
 /** List all active canvas IDs. */
 declare function getCanvasIds(): string[];
-declare function ThreeDom({ canvasId, primary, root, batchSize, syncBudgetMs, maxDomNodes, initialDepth, enabled, debug, inspect: inspectProp, }?: ThreeDomProps): null;
+declare function ThreeDom({ canvasId, primary, root, mode, filter, batchSize, syncBudgetMs, maxDomNodes, initialDepth, enabled, debug, inspect: inspectProp, }?: ThreeDomProps): null;
 
 /**
  * Patch Object3D.prototype.add and Object3D.prototype.remove to intercept
@@ -1083,7 +1109,7 @@ declare function ThreeDom({ canvasId, primary, root, batchSize, syncBudgetMs, ma
  * @param mirror - The DomMirror managing the parallel DOM tree
  * @returns A cleanup function that unregisters this store/mirror pair
  */
-declare function patchObject3D(store: ObjectStore, mirror: DomMirror): () => void;
+declare function patchObject3D(store: ObjectStore, mirror: DomMirror, instanceKey?: string): () => void;
 /**
  * Restore the original Object3D.prototype.add and remove methods.
  * Called automatically when the last store/mirror pair is removed.
@@ -1766,4 +1792,36 @@ declare function circlePath(center: {
  */
 declare function resolveObject(idOrUuid: string): Object3D;
 
-export { type CameraState, type CanvasSize, type Click3DOptions, type Click3DResult, DomMirror, type Drag3DOptions, type Drag3DResult, type DragOptions, type DrawPathOptions, type DrawPathResult, type DrawPoint, type GeometryInspection, Highlighter, type HighlighterOptions, type Hover3DOptions, type Hover3DResult, InspectController, type InspectOptions, MANAGED_ATTRIBUTES, type MaterialInspection, type ObjectInspection, type ObjectMetadata, ObjectStore, type PointerMiss3DOptions, type ProjectionResult, type R3FDOM, RaycastAccelerator, type RaycastResult, type SceneSnapshot, type ScreenDelta, type ScreenPoint, type SelectionListener, SelectionManager, type SnapshotNode, type StoreEvent, type StoreEventType, type StoreListener, TAG_MAP, ThreeDom, type ThreeDomProps, ThreeElement, type ThreeTagName, type Wheel3DOptions, type Wheel3DResult, type WheelOptions, type WorldDelta, applyAttributes, circlePath, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore, getTagForType, hover3D, isDebugEnabled, isInFrustum, isPatched, linePath, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, r3fLog, rectPath, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };
+/**
+ * Registers a Three.js object with the react-three-dom bridge on mount and
+ * unregisters it on unmount. Works in both `auto` and `manual` mode.
+ *
+ * - In `manual` mode this is the primary way to opt objects into the mirror DOM.
+ * - In `auto` mode it can force-register objects excluded by a `filter`.
+ * - Handles `ref.current` identity changes automatically.
+ * - If the bridge isn't ready on mount, retries each frame until available.
+ * - Supports multi-canvas via the optional `canvasId` parameter.
+ *
+ * @param ref - Ref to the Three.js object to register
+ * @param canvasId - Optional canvas ID for multi-canvas setups. When omitted,
+ *   uses the primary bridge (`window.__R3F_DOM__`).
+ *
+ * @example
+ * ```tsx
+ * function Wall({ geometry }) {
+ *   const ref = useRef<Mesh>(null!);
+ *   useR3FRegister(ref);
+ *   return <mesh ref={ref} geometry={geometry} userData={{ testId: 'wall' }} />;
+ * }
+ *
+ * // Multi-canvas
+ * function Overlay() {
+ *   const ref = useRef<Mesh>(null!);
+ *   useR3FRegister(ref, 'overlay');
+ *   return <mesh ref={ref} />;
+ * }
+ * ```
+ */
+declare function useR3FRegister(ref: React.RefObject<Object3D | null>, canvasId?: string): void;
+
+export { type CameraState, type CanvasSize, type Click3DOptions, type Click3DResult, DomMirror, type Drag3DOptions, type Drag3DResult, type DragOptions, type DrawPathOptions, type DrawPathResult, type DrawPoint, type GeometryInspection, Highlighter, type HighlighterOptions, type Hover3DOptions, type Hover3DResult, InspectController, type InspectOptions, MANAGED_ATTRIBUTES, type MaterialInspection, type ObjectInspection, type ObjectMetadata, ObjectStore, type PointerMiss3DOptions, type ProjectionResult, type R3FDOM, RaycastAccelerator, type RaycastResult, type SceneSnapshot, type ScreenDelta, type ScreenPoint, type SelectionListener, SelectionManager, type SnapshotNode, type StoreEvent, type StoreEventType, type StoreListener, TAG_MAP, ThreeDom, type ThreeDomProps, ThreeElement, type ThreeTagName, type Wheel3DOptions, type Wheel3DResult, type WheelOptions, type WorldDelta, applyAttributes, circlePath, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore, getTagForType, hover3D, isDebugEnabled, isInFrustum, isPatched, linePath, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, r3fLog, rectPath, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, useR3FRegister, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Object3D, Scene, Camera, WebGLRenderer, Intersection, Vector3 } from 'three';
 
-declare const version = "0.3.0";
+declare const version = "0.5.0";
 
 /**
  * Enable or disable debug logging globally.
@@ -261,6 +261,17 @@ interface R3FDOM {
     setInspectMode(on: boolean): void;
     /** Returns true if inspect mode is currently active. */
     getInspectMode(): boolean;
+    /**
+     * Manually register a Three.js object (and materialize its mirror DOM node).
+     * Useful in `manual` mode or to add specific objects in `auto` mode that
+     * were excluded by a filter.
+     */
+    r3fRegister(obj: Object3D): void;
+    /**
+     * Unregister a previously registered object and its descendants.
+     * Removes the mirror DOM node and store entry.
+     */
+    r3fUnregister(obj: Object3D): void;
     /**
      * Manually sweep orphaned objects from the store.
      * Removes objects that are no longer in any tracked scene graph.
@@ -400,6 +411,8 @@ declare class ObjectStore {
     /**
      * Unregister an entire subtree (object + all descendants).
      */
+    /** Mark a root as tracked without traversing/registering its children. */
+    addTrackedRoot(root: Object3D): void;
     unregisterTree(root: Object3D): void;
     /**
      * Refresh dynamic Tier 1 fields from the live Three.js object.
@@ -1010,7 +1023,7 @@ declare class InspectController {
     updateCamera(camera: Camera): void;
     /** Activate inspect mode — creates overlay on top of canvas. */
     enable(): void;
-    /** Deactivate inspect mode — removes overlay and clears hover state. */
+    /** Deactivate inspect mode — removes overlay and clears all inspect state. */
     disable(): void;
     /** Disable and release all resources. */
     dispose(): void;
@@ -1044,6 +1057,19 @@ interface ThreeDomProps {
      * Default: true when canvasId is omitted, false otherwise.
      */
     primary?: boolean;
+    /**
+     * Registration mode:
+     * - "auto" (default): traverses and registers all objects in the scene.
+     * - "manual": nothing is auto-registered. Use `useR3FRegister` hook or
+     *   `__R3F_DOM__.r3fRegister()` to add objects explicitly.
+     */
+    mode?: 'auto' | 'manual';
+    /**
+     * Filter function for auto mode. Only objects that pass the filter are
+     * registered. Ignored in manual mode.
+     * Example: `filter={(obj) => !!obj.userData.testId}`
+     */
+    filter?: (obj: Object3D) => boolean;
     /** CSS selector or HTMLElement for the mirror DOM root. Default: "#three-dom-root" */
     root?: string | HTMLElement;
     /** Objects to process per amortized batch per frame. Default: 500 */
@@ -1073,7 +1099,7 @@ declare function getHighlighter(canvasId?: string): Highlighter | null;
 declare function getInspectController(canvasId?: string): InspectController | null;
 /** List all active canvas IDs. */
 declare function getCanvasIds(): string[];
-declare function ThreeDom({ canvasId, primary, root, batchSize, syncBudgetMs, maxDomNodes, initialDepth, enabled, debug, inspect: inspectProp, }?: ThreeDomProps): null;
+declare function ThreeDom({ canvasId, primary, root, mode, filter, batchSize, syncBudgetMs, maxDomNodes, initialDepth, enabled, debug, inspect: inspectProp, }?: ThreeDomProps): null;
 
 /**
  * Patch Object3D.prototype.add and Object3D.prototype.remove to intercept
@@ -1083,7 +1109,7 @@ declare function ThreeDom({ canvasId, primary, root, batchSize, syncBudgetMs, ma
  * @param mirror - The DomMirror managing the parallel DOM tree
  * @returns A cleanup function that unregisters this store/mirror pair
  */
-declare function patchObject3D(store: ObjectStore, mirror: DomMirror): () => void;
+declare function patchObject3D(store: ObjectStore, mirror: DomMirror, instanceKey?: string): () => void;
 /**
  * Restore the original Object3D.prototype.add and remove methods.
  * Called automatically when the last store/mirror pair is removed.
@@ -1766,4 +1792,36 @@ declare function circlePath(center: {
  */
 declare function resolveObject(idOrUuid: string): Object3D;
 
-export { type CameraState, type CanvasSize, type Click3DOptions, type Click3DResult, DomMirror, type Drag3DOptions, type Drag3DResult, type DragOptions, type DrawPathOptions, type DrawPathResult, type DrawPoint, type GeometryInspection, Highlighter, type HighlighterOptions, type Hover3DOptions, type Hover3DResult, InspectController, type InspectOptions, MANAGED_ATTRIBUTES, type MaterialInspection, type ObjectInspection, type ObjectMetadata, ObjectStore, type PointerMiss3DOptions, type ProjectionResult, type R3FDOM, RaycastAccelerator, type RaycastResult, type SceneSnapshot, type ScreenDelta, type ScreenPoint, type SelectionListener, SelectionManager, type SnapshotNode, type StoreEvent, type StoreEventType, type StoreListener, TAG_MAP, ThreeDom, type ThreeDomProps, ThreeElement, type ThreeTagName, type Wheel3DOptions, type Wheel3DResult, type WheelOptions, type WorldDelta, applyAttributes, circlePath, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore, getTagForType, hover3D, isDebugEnabled, isInFrustum, isPatched, linePath, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, r3fLog, rectPath, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };
+/**
+ * Registers a Three.js object with the react-three-dom bridge on mount and
+ * unregisters it on unmount. Works in both `auto` and `manual` mode.
+ *
+ * - In `manual` mode this is the primary way to opt objects into the mirror DOM.
+ * - In `auto` mode it can force-register objects excluded by a `filter`.
+ * - Handles `ref.current` identity changes automatically.
+ * - If the bridge isn't ready on mount, retries each frame until available.
+ * - Supports multi-canvas via the optional `canvasId` parameter.
+ *
+ * @param ref - Ref to the Three.js object to register
+ * @param canvasId - Optional canvas ID for multi-canvas setups. When omitted,
+ *   uses the primary bridge (`window.__R3F_DOM__`).
+ *
+ * @example
+ * ```tsx
+ * function Wall({ geometry }) {
+ *   const ref = useRef<Mesh>(null!);
+ *   useR3FRegister(ref);
+ *   return <mesh ref={ref} geometry={geometry} userData={{ testId: 'wall' }} />;
+ * }
+ *
+ * // Multi-canvas
+ * function Overlay() {
+ *   const ref = useRef<Mesh>(null!);
+ *   useR3FRegister(ref, 'overlay');
+ *   return <mesh ref={ref} />;
+ * }
+ * ```
+ */
+declare function useR3FRegister(ref: React.RefObject<Object3D | null>, canvasId?: string): void;
+
+export { type CameraState, type CanvasSize, type Click3DOptions, type Click3DResult, DomMirror, type Drag3DOptions, type Drag3DResult, type DragOptions, type DrawPathOptions, type DrawPathResult, type DrawPoint, type GeometryInspection, Highlighter, type HighlighterOptions, type Hover3DOptions, type Hover3DResult, InspectController, type InspectOptions, MANAGED_ATTRIBUTES, type MaterialInspection, type ObjectInspection, type ObjectMetadata, ObjectStore, type PointerMiss3DOptions, type ProjectionResult, type R3FDOM, RaycastAccelerator, type RaycastResult, type SceneSnapshot, type ScreenDelta, type ScreenPoint, type SelectionListener, SelectionManager, type SnapshotNode, type StoreEvent, type StoreEventType, type StoreListener, TAG_MAP, ThreeDom, type ThreeDomProps, ThreeElement, type ThreeTagName, type Wheel3DOptions, type Wheel3DResult, type WheelOptions, type WorldDelta, applyAttributes, circlePath, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore, getTagForType, hover3D, isDebugEnabled, isInFrustum, isPatched, linePath, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, r3fLog, rectPath, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, useR3FRegister, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };

package/dist/index.js

@@ -1,10 +1,10 @@
 import { Box3, Object3D, Vector3, Matrix4, Frustum, Raycaster, Vector2, BufferGeometry, Material, Color, MeshBasicMaterial, DoubleSide, Mesh, BoxGeometry, EdgesGeometry, LineBasicMaterial, LineSegments, InstancedMesh, PerspectiveCamera, OrthographicCamera } from 'three';
-import { useRef, useEffect } from 'react';
+import { useRef, useEffect, useCallback } from 'react';
 import { useThree, useFrame } from '@react-three/fiber';
 import { computeBoundsTree, disposeBoundsTree, acceleratedRaycast } from 'three-mesh-bvh';
 
 // src/version.ts
-var version = "0.3.0";
+var version = "0.5.0";
 
 // src/debug.ts
 var _enabled = false;
@@ -399,6 +399,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);
     }
@@ -419,6 +420,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);
@@ -1515,16 +1520,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 = Object3D.prototype.add;
@@ -1537,7 +1543,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);
           }
@@ -3096,7 +3102,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;
@@ -3343,6 +3349,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;
 }
@@ -3493,6 +3523,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 = [];
@@ -3615,6 +3677,10 @@ function createStubBridge(error, canvasId) {
     setInspectMode: () => {
     },
     getInspectMode: () => false,
+    r3fRegister: () => {
+    },
+    r3fUnregister: () => {
+    },
     sweepOrphans: () => 0,
     getDiagnostics: () => ({
       version,
@@ -3649,6 +3715,8 @@ function ThreeDom({
   canvasId,
   primary,
   root = "#three-dom-root",
+  mode = "auto",
+  filter,
   batchSize = 500,
   syncBudgetMs = 0.5,
   maxDomNodes = 2e3,
@@ -3723,18 +3791,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);
@@ -3806,6 +3898,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");
     };
@@ -3853,7 +3947,42 @@ 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 = useRef(null);
+  const canvasIdRef = useRef(canvasId);
+  canvasIdRef.current = canvasId;
+  const register = useCallback((obj) => {
+    const api = getAPI(canvasIdRef.current);
+    if (!api) return false;
+    api.r3fRegister(obj);
+    trackedObj.current = obj;
+    return true;
+  }, []);
+  const unregister = useCallback(() => {
+    if (!trackedObj.current) return;
+    const api = getAPI(canvasIdRef.current);
+    api?.r3fUnregister(trackedObj.current);
+    trackedObj.current = null;
+  }, []);
+  useEffect(() => {
+    const obj = ref.current;
+    if (obj) register(obj);
+    return () => unregister();
+  }, [ref, register, unregister]);
+  useFrame(() => {
+    const current = ref.current;
+    if (current === trackedObj.current) return;
+    unregister();
+    if (current) register(current);
+  });
+}
 
-export { DomMirror, Highlighter, InspectController, MANAGED_ATTRIBUTES, ObjectStore, RaycastAccelerator, SelectionManager, TAG_MAP, ThreeDom, ThreeElement, applyAttributes, circlePath, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore2 as getStore, getTagForType, hover3D, isDebugEnabled, isInFrustum, isPatched, linePath, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, r3fLog, rectPath, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };
+export { DomMirror, Highlighter, InspectController, MANAGED_ATTRIBUTES, ObjectStore, RaycastAccelerator, SelectionManager, TAG_MAP, ThreeDom, ThreeElement, applyAttributes, circlePath, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore2 as getStore, getTagForType, hover3D, isDebugEnabled, isInFrustum, isPatched, linePath, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, r3fLog, rectPath, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, useR3FRegister, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map