@react-three-dom/core 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { Object3D, Camera, WebGLRenderer, Vector3 } from 'three';
+import { Object3D, Scene, Camera, WebGLRenderer, Intersection, Vector3 } from 'three';
 
-declare const version = "0.1.0";
+declare const version = "0.4.0";
 
 /**
  * Enable or disable debug logging globally.
@@ -44,6 +44,14 @@ interface ObjectMetadata {
     triangleCount?: number;
     /** Instance count for InstancedMesh */
     instanceCount?: number;
+    /** Field of view in degrees (PerspectiveCamera only) */
+    fov?: number;
+    /** Near clipping plane (cameras only) */
+    near?: number;
+    /** Far clipping plane (cameras only) */
+    far?: number;
+    /** Zoom level (cameras only) */
+    zoom?: number;
     /** Local position as [x, y, z] */
     position: [number, number, number];
     /** Local euler rotation as [x, y, z] in radians */
@@ -57,6 +65,11 @@ interface ObjectMetadata {
     /** Flag indicating bounds need recomputation */
     boundsDirty: boolean;
 }
+/** Options for inspect(). Include geometry buffers only when needed to avoid perf impact. */
+interface InspectOptions {
+    /** If true, include vertex positions and triangle indices in geometry. Default: false. */
+    includeGeometryData?: boolean;
+}
 interface GeometryInspection {
     /** Geometry class type */
     type: string;
@@ -74,6 +87,10 @@ interface GeometryInspection {
         center: [number, number, number];
         radius: number;
     };
+    /** Position attribute data (x,y,z per vertex). Only set when inspect(..., { includeGeometryData: true }). */
+    positionData?: number[];
+    /** Index buffer (triangle indices). Only set when inspect(..., { includeGeometryData: true }) and geometry is indexed. */
+    indexData?: number[];
 }
 interface MaterialInspection {
     /** Material class type */
@@ -164,10 +181,18 @@ interface R3FDOM {
     getByUuid(uuid: string): ObjectMetadata | null;
     /** Tier 1: O(1) lookup by name (returns array, names aren't unique) */
     getByName(name: string): ObjectMetadata[];
+    /** Get direct children of an object by testId or uuid */
+    getChildren(idOrUuid: string): ObjectMetadata[];
+    /** Get parent of an object by testId or uuid (null if root or not found) */
+    getParent(idOrUuid: string): ObjectMetadata | null;
     /** Total number of tracked objects */
     getCount(): number;
     /** Get all objects of a given Three.js type (Mesh, Group, Line, Points, etc.) */
     getByType(type: string): ObjectMetadata[];
+    /** Get all objects with a given geometry type (e.g. "BoxGeometry", "BufferGeometry") */
+    getByGeometryType(type: string): ObjectMetadata[];
+    /** Get all objects with a given material type (e.g. "MeshStandardMaterial") */
+    getByMaterialType(type: string): ObjectMetadata[];
     /** Get objects that have a specific userData key (and optionally matching value) */
     getByUserData(key: string, value?: unknown): ObjectMetadata[];
     /** Count objects of a given Three.js type */
@@ -176,8 +201,8 @@ interface R3FDOM {
     getObjects(ids: string[]): Record<string, ObjectMetadata | null>;
     /** Full structured JSON snapshot from Tier 1 store */
     snapshot(): SceneSnapshot;
-    /** Tier 2: on-demand heavy inspection (reads live Three.js object) */
-    inspect(idOrUuid: string): ObjectInspection | null;
+    /** Tier 2: on-demand heavy inspection (reads live Three.js object). Use includeGeometryData: true to get vertex/index buffers. */
+    inspect(idOrUuid: string, options?: InspectOptions): ObjectInspection | null;
     /** Deterministic click on a 3D object */
     click(idOrUuid: string): void;
     /** Deterministic double-click on a 3D object */
@@ -186,6 +211,8 @@ interface R3FDOM {
     contextMenu(idOrUuid: string): void;
     /** Deterministic hover on a 3D object */
     hover(idOrUuid: string): void;
+    /** Unhover / pointer-leave — resets hover state by moving pointer off-canvas */
+    unhover(): void;
     /** Deterministic drag on a 3D object (async — dispatches multi-step pointer sequence) */
     drag(idOrUuid: string, delta: {
         x: number;
@@ -220,17 +247,126 @@ interface R3FDOM {
     getSelection(): string[];
     /** Raw Three.js object access (for advanced debugging) */
     getObject3D(idOrUuid: string): Object3D | null;
+    /**
+     * Resolve uuid for display: if the object is the first mesh of a Group (e.g. table top),
+     * returns the parent group uuid so the whole group is highlighted; otherwise returns the given uuid.
+     */
+    getSelectionDisplayTarget(uuid: string): string;
+    /**
+     * Enable or disable "inspect mode" for the mirror DOM.
+     * When true, mirror elements use pointer-events: auto so the DevTools element picker
+     * can select 3D objects by clicking on the canvas (e.g. hold Alt while using the picker).
+     * When false, pointer-events: none so normal 3D interaction works.
+     */
+    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.
+     * Runs automatically every ~30s, but can be called after large
+     * scene changes (e.g. floor unload) for immediate cleanup.
+     * Returns the number of orphans removed.
+     */
+    sweepOrphans(): number;
+    /**
+     * Rich diagnostics for test runners and debugging.
+     * Returns bridge health, scene stats, and WebGL context info.
+     */
+    getDiagnostics(): BridgeDiagnostics;
+    /**
+     * Fuzzy search: find objects whose testId or name contains the query string.
+     * Returns up to `limit` matches. Used by test runners to suggest corrections
+     * when an object is not found.
+     */
+    fuzzyFind(query: string, limit?: number): ObjectMetadata[];
+    /** Get current camera state (position, rotation, fov, near, far, zoom, type) */
+    getCameraState(): CameraState;
+    /** Canvas identifier for multi-canvas apps. Undefined for the default/primary canvas. */
+    canvasId?: string;
     /** Library version */
     version: string;
 }
+interface CameraState {
+    type: 'PerspectiveCamera' | 'OrthographicCamera' | string;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    /** World-space target the camera is looking at (derived from camera direction) */
+    target: [number, number, number];
+    /** Field of view in degrees (PerspectiveCamera only) */
+    fov?: number;
+    /** Near clipping plane */
+    near: number;
+    /** Far clipping plane */
+    far: number;
+    /** Zoom level */
+    zoom: number;
+    /** Aspect ratio (PerspectiveCamera only) */
+    aspect?: number;
+    /** Left/right/top/bottom (OrthographicCamera only) */
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+interface BridgeDiagnostics {
+    version: string;
+    ready: boolean;
+    error?: string;
+    objectCount: number;
+    meshCount: number;
+    groupCount: number;
+    lightCount: number;
+    cameraCount: number;
+    materializedDomNodes: number;
+    maxDomNodes: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    webglRenderer: string;
+    dirtyQueueSize: number;
+}
 declare global {
     interface Window {
+        /** Default / primary bridge instance (last mounted, or explicitly marked primary). */
         __R3F_DOM__?: R3FDOM;
+        /** Registry of all active bridge instances keyed by canvasId. */
+        __R3F_DOM_INSTANCES__?: Record<string, R3FDOM>;
         /** Set to true to enable debug logging from @react-three-dom/core */
         __R3F_DOM_DEBUG__?: boolean;
+        /** @internal Mirror element currently hovered by DevTools inspector. */
+        __r3fdom_hovered__?: HTMLElement | null;
+        /** @internal Mirror element currently selected via DevTools / inspect mode. */
+        __r3fdom_selected_element__?: HTMLElement | null;
     }
 }
 
+/**
+ * @module ObjectStore
+ *
+ * Central registry for all tracked Three.js objects in a react-three-dom session.
+ * Provides two-tier data access: Tier 1 (lightweight metadata cached per-frame)
+ * and Tier 2 (on-demand deep inspection of geometry, materials, and bounds).
+ * Designed for BIM-scale scenes (100k+ objects) with O(1) lookups by uuid,
+ * testId, and name, plus amortized flat-list iteration and async registration.
+ */
+
+/**
+ * Source of truth for all tracked Three.js objects.
+ * Maintains O(1) indexes by uuid, testId, and name, a dirty queue for
+ * priority per-frame sync, and an event system for add/remove/update
+ * notifications consumed by DomMirror and the devtools panel.
+ */
 declare class ObjectStore {
     private _metaByObject;
     private _objectByUuid;
@@ -244,42 +380,65 @@ declare class ObjectStore {
     /**
      * Register a single object into the store.
      * Populates Tier 1 metadata and all indexes.
+     * Tags the object with `__r3fdom_tracked = true` for O(1) scene membership checks.
      */
     register(obj: Object3D): ObjectMetadata;
     /**
-     * Register an entire subtree (object + all descendants).
-     * Individual objects that fail to register are skipped (logged when debug
-     * is enabled) so that one bad object doesn't prevent the rest from being
-     * tracked.
+     * Register an entire subtree (object + all descendants) synchronously.
+     * Prefer `registerTreeAsync` for large scenes (100k+) to avoid blocking.
      */
     registerTree(root: Object3D): void;
+    private _asyncRegQueue;
+    private _asyncRegHandle;
+    private _asyncRegBatchSize;
+    /**
+     * Register an entire subtree asynchronously using requestIdleCallback.
+     * Processes ~1000 objects per idle slice to avoid blocking the main thread.
+     *
+     * IMPORTANT: install patchObject3D BEFORE calling this so that objects
+     * added to the scene during async registration are caught by the patch.
+     *
+     * Returns a cancel function. Also cancelled automatically by dispose().
+     */
+    registerTreeAsync(root: Object3D): () => void;
+    private _scheduleRegChunk;
+    private _cancelAsyncRegistration;
     /**
      * Unregister a single object from the store.
+     * Clears the `__r3fdom_tracked` flag.
      */
     unregister(obj: Object3D): void;
     /**
      * 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 Tier 1 metadata from the live Three.js object.
+     * Refresh dynamic Tier 1 fields from the live Three.js object.
+     * Only reads transform, visibility, children count, and parent —
+     * skips static fields (geometry, material) that don't change per-frame.
+     * Mutates metadata in-place to avoid allocation.
      * Returns true if any values changed.
-     * Returns false (no change) if extracting metadata throws so that the
-     * previous metadata is preserved.
      */
     update(obj: Object3D): boolean;
     /**
      * Compute full inspection data from a live Three.js object.
      * This reads geometry buffers, material properties, world bounds, etc.
      * Cost: 0.1–2ms depending on geometry complexity.
+     * Pass { includeGeometryData: true } to include vertex positions and triangle indices (higher cost for large meshes).
      */
-    inspect(idOrUuid: string): ObjectInspection | null;
+    inspect(idOrUuid: string, options?: InspectOptions): ObjectInspection | null;
     /** Get metadata by testId. O(1). */
     getByTestId(testId: string): ObjectMetadata | null;
     /** Get metadata by uuid. O(1). */
     getByUuid(uuid: string): ObjectMetadata | null;
     /** Get metadata by name (returns array since names aren't unique). O(1). */
     getByName(name: string): ObjectMetadata[];
+    /** Get direct children of an object by testId or uuid. Returns empty array if not found. */
+    getChildren(idOrUuid: string): ObjectMetadata[];
+    /** Get parent of an object by testId or uuid. Returns null if not found or if root. */
+    getParent(idOrUuid: string): ObjectMetadata | null;
     /**
      * Batch lookup: get metadata for multiple objects by testId or uuid.
      * Returns a Map from the requested id to its metadata (or null if not found).
@@ -293,6 +452,16 @@ declare class ObjectStore {
      * Linear scan — O(n) where n is total tracked objects.
      */
     getByType(type: string): ObjectMetadata[];
+    /**
+     * Get all objects with a given geometry type (e.g. "BoxGeometry", "BufferGeometry").
+     * Linear scan — O(n). Only meshes/points/lines have geometryType.
+     */
+    getByGeometryType(type: string): ObjectMetadata[];
+    /**
+     * Get all objects with a given material type (e.g. "MeshStandardMaterial").
+     * Linear scan — O(n). Only meshes/points/lines have materialType.
+     */
+    getByMaterialType(type: string): ObjectMetadata[];
     /**
      * Get all objects that have a specific userData key.
      * If `value` is provided, only returns objects where `userData[key]` matches.
@@ -317,9 +486,10 @@ declare class ObjectStore {
     /** Check if a root scene is tracked. */
     isTrackedRoot(obj: Object3D): boolean;
     /**
-     * Walk up from `obj` to see if any ancestor is a tracked root.
-     * Used by Object3D.add/remove patch to determine if an object
-     * belongs to a monitored scene.
+     * Check if an object belongs to a tracked scene.
+     * Fast path: checks the `__r3fdom_tracked` flag set during register (O(1)).
+     * Fallback: walks up the parent chain to find a tracked root.
+     * The fallback is needed for newly added objects that aren't registered yet.
      */
     isInTrackedScene(obj: Object3D): boolean;
     /**
@@ -339,10 +509,32 @@ declare class ObjectStore {
     /** Subscribe to store events (add, remove, update). */
     subscribe(listener: StoreListener): () => void;
     private _emit;
+    /**
+     * Sweep objects in `_objectByUuid` that are no longer in any tracked scene.
+     * This catches objects that were removed from the scene graph without
+     * triggering the patched Object3D.remove (e.g. direct `.children` splice,
+     * or the remove hook failing silently).
+     *
+     * At BIM scale, call this periodically (e.g. every 30s or after a floor
+     * load/unload) to prevent memory leaks from retained Object3D references.
+     *
+     * Returns the number of orphans cleaned up.
+     */
+    sweepOrphans(): number;
     /** Remove all tracked objects and reset state. */
     dispose(): void;
 }
 
+/**
+ * @module DomMirror
+ *
+ * Maintains a parallel DOM tree that mirrors the Three.js scene graph using
+ * custom elements (<three-mesh>, <three-group>, etc.). This enables standard
+ * DOM tooling — CSS selectors, DevTools Elements panel, Accessibility tree —
+ * to work with 3D objects. Only a subset of objects are materialized as DOM
+ * nodes at any time (capped via LRU eviction) to stay performant at BIM scale.
+ */
+
 /**
  * Manages the parallel DOM tree that mirrors the Three.js scene graph.
  *
@@ -361,12 +553,30 @@ declare class DomMirror {
     private _lruSize;
     private _maxNodes;
     private _parentMap;
+    /** When true, mirror elements use pointer-events: auto so DevTools element picker can select them. */
+    private _inspectMode;
+    /** Async materialization state for inspect mode */
+    private _asyncQueue;
+    private _asyncIdleHandle;
+    private _asyncBatchSize;
     constructor(store: ObjectStore, maxNodes?: number);
     /**
      * 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: HTMLElement): void;
+    /**
+     * Enable or disable "inspect mode". When turning on, kicks off async
+     * chunked materialization so the full tree becomes browsable in the
+     * Elements tab without blocking the main thread.
+     *
+     * At BIM scale (100k-200k objects) the old synchronous loop would freeze
+     * the page for 2-10s. The new approach uses requestIdleCallback to
+     * spread work across idle frames (~200 nodes per idle slice, ~5ms each).
+     */
+    setInspectMode(on: boolean): void;
+    /** Whether inspect mode is currently enabled. */
+    getInspectMode(): boolean;
     /**
      * Build the initial DOM tree from the scene.
      * Materializes the top 2 levels of the scene hierarchy.
@@ -385,8 +595,14 @@ declare class DomMirror {
     /**
      * Remove a DOM node but keep JS metadata in the ObjectStore.
      * Called by LRU eviction or when an object is removed from the scene.
+     * Also dematerializes any materialized descendants so they don't become
+     * orphaned entries in the LRU / _nodes maps.
      */
     dematerialize(uuid: string): void;
+    /**
+     * Collect all materialized descendants of a uuid by walking _parentMap.
+     */
+    private _collectMaterializedDescendants;
     /**
      * Called when a new object is added to the tracked scene.
      * Only materializes if the parent is already materialized (lazy expansion).
@@ -415,6 +631,14 @@ declare class DomMirror {
      * Get the materialized DOM element for an object, if it exists.
      */
     getElement(uuid: string): HTMLElement | null;
+    /**
+     * Get or lazily materialize a DOM element for an object.
+     * Also materializes the ancestor chain so the element is correctly
+     * nested in the DOM tree. Used by InspectController so that
+     * hover/click always produces a valid mirror element regardless
+     * of whether async materialization has reached it yet.
+     */
+    getOrMaterialize(uuid: string): HTMLElement | null;
     /**
      * Check if an object has a materialized DOM node.
      */
@@ -446,6 +670,14 @@ declare class DomMirror {
      * Insert a newly created element into the correct position in the DOM tree.
      */
     private _insertIntoDom;
+    /**
+     * Materialize all ancestors of a uuid from root down, so the target
+     * element will be correctly nested when materialized.
+     */
+    private _materializeAncestorChain;
+    private _startAsyncMaterialization;
+    private _cancelAsyncMaterialization;
+    private _scheduleAsyncChunk;
     /**
      * Parse common CSS selector patterns and resolve to a uuid from the store.
      * Supports:
@@ -469,6 +701,15 @@ declare class DomMirror {
     private _evictLRU;
 }
 
+/**
+ * @module CustomElements
+ *
+ * Defines and registers the custom HTML elements (<three-scene>, <three-mesh>,
+ * <three-light>, etc.) used by DomMirror to represent Three.js objects in the
+ * DOM. The ThreeElement base class exposes interactive properties (metadata,
+ * inspect, object3D) accessible from the DevTools console via `$0.metadata`.
+ */
+
 /**
  * Maps Three.js object types to custom element tag names.
  * Multiple Three.js types can map to the same tag.
@@ -560,6 +801,14 @@ declare class ThreeElement extends HTMLElement {
  */
 declare function ensureCustomElements(store: ObjectStore): void;
 
+/**
+ * @module attributes
+ *
+ * Serializes ObjectStore Tier 1 metadata into DOM data-attributes and applies
+ * them to mirror elements with minimal DOM writes. Only attributes whose values
+ * actually changed are written, keeping per-frame cost near zero for static objects.
+ */
+
 /** All attribute names we manage (for diffing). */
 declare const MANAGED_ATTRIBUTES: string[];
 /**
@@ -579,7 +828,20 @@ declare function computeAttributes(meta: ObjectMetadata): Map<string, string>;
  */
 declare function applyAttributes(element: HTMLElement, meta: ObjectMetadata, prevAttrs: Map<string, string>): number;
 
+/**
+ * @module SelectionManager
+ *
+ * Lightweight selection state manager for 3D objects. Supports single and
+ * multi-selection, notifies listeners on change so Highlighter and the
+ * devtools inspector panel can react. Decoupled from rendering — purely
+ * manages which Object3D references are "selected".
+ */
+
 type SelectionListener = (selected: Object3D[]) => void;
+/**
+ * Tracks the set of currently selected Object3D instances and notifies
+ * subscribers when the selection changes.
+ */
 declare class SelectionManager {
     /** Currently selected objects (ordered by selection time). */
     private _selected;
@@ -609,56 +871,211 @@ declare class SelectionManager {
     dispose(): void;
 }
 
+/**
+ * @module Highlighter
+ *
+ * Renders Chrome DevTools-style translucent fill overlays on hovered and
+ * selected Three.js objects. Subscribes to SelectionManager for selection
+ * state and polls `window.__r3fdom_hovered__` for DevTools element-picker
+ * hover. Highlight meshes are marked `__r3fdom_internal` so they're excluded
+ * from raycasting and the ObjectStore.
+ */
+
 interface HighlighterOptions {
-    /** Whether to show a tooltip above highlighted objects. Default: true */
     showTooltip?: boolean;
 }
+/**
+ * Manages hover and selection highlight overlays in the 3D scene.
+ * Attaches to a Scene + SelectionManager and creates/disposes translucent
+ * mesh clones that track the source object's world transform each frame.
+ */
 declare class Highlighter {
-    /** Selected object overlays (persistent until deselected) */
-    private _selectedEntries;
-    /** Hover overlay (temporary, single object at a time) */
-    private _hoverEntries;
-    private _camera;
-    private _renderer;
+    private _scene;
     private _unsubscribe;
-    private _showTooltip;
-    /** DevTools hover polling interval */
+    private _hoverEntries;
+    private _hoverTarget;
+    private _selectedEntries;
     private _hoverPollId;
-    private _lastHoveredElement;
-    /** Store reference for resolving objects */
+    private _lastHoveredUuid;
     private _store;
-    constructor(options?: HighlighterOptions);
-    attach(_scene: Object3D, selectionManager: SelectionManager, camera: Camera, renderer: WebGLRenderer, store: {
+    constructor(_options?: HighlighterOptions);
+    /** Bind to a scene and selection manager, start hover polling. */
+    attach(scene: Scene, selectionManager: SelectionManager, _camera: Camera, _renderer: WebGLRenderer, store: {
         getObject3D(uuid: string): Object3D | null;
     }): void;
+    /** Unbind from the scene, stop polling, and remove all highlights. */
     detach(): void;
+    /** Sync highlight group transforms to their source objects. Call each frame. */
     update(): void;
-    highlight(obj: Object3D): void;
-    unhighlight(obj: Object3D): void;
-    clearAll(): void;
-    isHighlighted(obj: Object3D): boolean;
-    /** Show a temporary hover highlight for an object and its children */
+    /** Show a hover highlight on the given object (replaces any previous hover). */
     showHoverHighlight(obj: Object3D): void;
-    /** Clear the hover highlight */
+    /** Remove the current hover highlight. */
     clearHoverHighlight(): void;
-    private _syncSelectedHighlights;
-    private _addSelectedHighlight;
-    private _addHoverHighlightRecursive;
+    private _clearHoverVisuals;
+    /** Check if an object currently has a selection highlight. */
+    isHighlighted(obj: Object3D): boolean;
+    /** Remove all hover and selection highlights. */
+    clearAll(): void;
+    private _syncSelectionHighlights;
+    private _addSelectionHighlight;
+    private _removeSelectionHighlight;
+    private _clearAllSelectionHighlights;
     private _startHoverPolling;
     private _stopHoverPolling;
     private _pollDevToolsHover;
-    private _removeOverlay;
-    private _clearAllOverlays;
+    private _disposeHighlightGroup;
+    /** Detach and release all resources. */
+    dispose(): void;
+}
+
+/**
+ * @module RaycastAccelerator
+ *
+ * Two-layer acceleration structure for BIM-scale raycasting (100k+ objects).
+ * Layer 1 maintains a pre-filtered flat list of raycastable meshes from the
+ * ObjectStore (avoids recursive scene traversal). Layer 2 uses three-mesh-bvh
+ * to build per-geometry BVH trees, turning per-mesh triangle intersection
+ * from O(t) brute-force into O(log t). Combined: ~0.01–0.1ms at 200k objects.
+ */
+
+/**
+ * Maintains an accelerated raycast target list and per-geometry BVH trees.
+ * Rebuilds lazily when the ObjectStore emits changes, with a per-rebuild
+ * BVH budget to avoid blocking the main thread on large model loads.
+ */
+declare class RaycastAccelerator {
+    private _store;
+    private _targets;
+    private _dirty;
+    private _unsubscribe;
+    private _bvhBuiltFor;
+    constructor(store: ObjectStore);
+    /** Force a target list rebuild on the next raycast. */
+    markDirty(): void;
+    private _rebuild;
+    /**
+     * Build a BVH for a mesh's geometry if it doesn't have one yet.
+     * Uses indirect mode to avoid modifying the index buffer.
+     * Skips disposed geometries and does NOT mark failed builds so they
+     * can be retried (e.g. after geometry is re-uploaded).
+     */
+    private _ensureBVH;
+    /**
+     * Raycast from mouse position against only raycastable meshes.
+     * Returns the closest non-internal hit, or null.
+     */
+    raycastAtMouse(e: MouseEvent, camera: Camera, canvas: HTMLCanvasElement): Object3D | null;
+    /**
+     * Raycast from NDC coordinates. Used by raycastVerify.
+     */
+    raycastAtNdc(ndcX: number, ndcY: number, camera: Camera): Intersection[];
+    /** Current number of raycastable targets. */
+    get targetCount(): number;
+    /** Unsubscribe from the store and release the target list. */
     dispose(): void;
 }
 
+/**
+ * @module InspectController
+ *
+ * Chrome DevTools-style inspect mode for 3D scenes. When enabled, places a
+ * transparent overlay on top of the WebGL canvas that intercepts all pointer
+ * events (preventing R3F's event system and camera controls from consuming
+ * them), raycasts to identify the object under the cursor, drives
+ * hover/selection highlights, and sets a global reference so the DevTools
+ * extension can reveal the corresponding mirror DOM node.
+ * Zero overhead when disabled — no overlay, no listeners.
+ */
+
+/**
+ * Manages the inspect-mode lifecycle: creates/removes an overlay div,
+ * throttles raycasts, and coordinates Highlighter + SelectionManager + DomMirror.
+ */
+declare class InspectController {
+    private _active;
+    private _camera;
+    private _renderer;
+    private _selectionManager;
+    private _highlighter;
+    private _raycastAccelerator;
+    private _mirror;
+    private _store;
+    private _lastRaycastTime;
+    private _hoveredObject;
+    private _hoverRevealTimer;
+    private _overlay;
+    private _boundPointerMove;
+    private _boundPointerDown;
+    private _boundContextMenu;
+    constructor(opts: {
+        camera: Camera;
+        renderer: WebGLRenderer;
+        selectionManager: SelectionManager;
+        highlighter: Highlighter;
+        raycastAccelerator: RaycastAccelerator;
+        mirror: DomMirror;
+        store: {
+            getObject3D(uuid: string): Object3D | null;
+        };
+    });
+    get active(): boolean;
+    /** Update the camera reference (e.g. after a camera switch). */
+    updateCamera(camera: Camera): void;
+    /** Activate inspect mode — creates overlay on top of canvas. */
+    enable(): void;
+    /** Deactivate inspect mode — removes overlay and clears all inspect state. */
+    disable(): void;
+    /** Disable and release all resources. */
+    dispose(): void;
+    private _raycastFromEvent;
+    /**
+     * Resolve a raw raycast hit to the logical selection target.
+     * Walks up to find the best Group parent if applicable.
+     */
+    private _resolveTarget;
+    private _onPointerMove;
+    /**
+     * After hovering an object for HOVER_REVEAL_DEBOUNCE_MS, auto-reveal its
+     * mirror element in the Elements tab.
+     */
+    private _scheduleHoverReveal;
+    private _cancelHoverReveal;
+    private _onPointerDown;
+}
+
 interface ThreeDomProps {
+    /**
+     * Unique identifier for this canvas instance. Required when using multiple
+     * canvases. The bridge is registered in `window.__R3F_DOM_INSTANCES__[canvasId]`.
+     * When omitted the bridge is only set on `window.__R3F_DOM__`.
+     */
+    canvasId?: string;
+    /**
+     * Mark this canvas as the primary / default instance.
+     * `window.__R3F_DOM__` always points to the primary bridge.
+     * When only one canvas is used (no canvasId), it is implicitly primary.
+     * 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 */
     batchSize?: number;
     /** Max time budget (ms) for sync work per frame. Default: 0.5 */
-    timeBudgetMs?: number;
+    syncBudgetMs?: number;
     /** Max materialized DOM nodes (LRU eviction). Default: 2000 */
     maxDomNodes?: number;
     /** Initial DOM tree materialization depth. Default: 3 */
@@ -667,12 +1084,22 @@ interface ThreeDomProps {
     enabled?: boolean;
     /** Enable debug logging to browser console. Default: false */
     debug?: boolean;
+    /** Enable inspect mode on mount. Default: false */
+    inspect?: boolean;
 }
-declare function getStore(): ObjectStore | null;
-declare function getMirror(): DomMirror | null;
-declare function getSelectionManager(): SelectionManager | null;
-declare function getHighlighter(): Highlighter | null;
-declare function ThreeDom({ root, batchSize, timeBudgetMs, maxDomNodes, initialDepth, enabled, debug, }?: ThreeDomProps): null;
+/** Get the store for a canvas instance. Default: primary ('') instance. */
+declare function getStore(canvasId?: string): ObjectStore | null;
+/** Get the mirror for a canvas instance. Default: primary ('') instance. */
+declare function getMirror(canvasId?: string): DomMirror | null;
+/** Get the selection manager for a canvas instance. */
+declare function getSelectionManager(canvasId?: string): SelectionManager | null;
+/** Get the highlighter for a canvas instance. */
+declare function getHighlighter(canvasId?: string): Highlighter | null;
+/** Get the inspect controller for a canvas instance. */
+declare function getInspectController(canvasId?: string): InspectController | null;
+/** List all active canvas IDs. */
+declare function getCanvasIds(): string[];
+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
@@ -682,7 +1109,7 @@ declare function ThreeDom({ root, batchSize, timeBudgetMs, maxDomNodes, initialD
  * @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.
@@ -724,6 +1151,16 @@ declare function createFlatSnapshot(store: ObjectStore): {
     objects: ObjectMetadata[];
 };
 
+/**
+ * @module projection
+ *
+ * Projects Three.js objects from world space to screen-space CSS pixel
+ * coordinates using a multi-strategy approach (bbox center → face centers →
+ * corners → origin fallback). Also provides frustum visibility checks and
+ * screen-to-world conversion for drag deltas. Core utility used by all
+ * interaction modules to determine where to dispatch synthetic events.
+ */
+
 /** Screen-space coordinates in CSS pixels relative to the canvas. */
 interface ScreenPoint {
     /** X coordinate in CSS pixels, left = 0. */
@@ -782,6 +1219,15 @@ declare function screenDeltaToWorld(dx: number, dy: number, obj: Object3D, camer
  */
 declare function projectAllSamplePoints(obj: Object3D, camera: Camera, size: CanvasSize): ScreenPoint[];
 
+/**
+ * @module raycastVerify
+ *
+ * Post-dispatch raycast verification for interaction modules. After a synthetic
+ * event is dispatched at projected screen coordinates, casts a ray to confirm
+ * the intended object is actually the frontmost hit. Reports occlusion with
+ * the identity of the occluding object for clear error messages.
+ */
+
 /** Result of a raycast verification. */
 interface RaycastResult {
     /** Whether the intended object was hit. */
@@ -933,6 +1379,15 @@ declare function hover3D(idOrUuid: string, options?: Hover3DOptions): Hover3DRes
  */
 declare function unhover3D(): void;
 
+/**
+ * @module dispatch
+ *
+ * Low-level synthetic PointerEvent/MouseEvent/WheelEvent dispatch on the
+ * canvas element. Produces the exact DOM event sequences that R3F's internal
+ * event system expects (e.g. pointerdown → pointerup → click). All higher-level
+ * interaction modules (click3D, hover3D, drag3D, etc.) delegate here.
+ */
+
 /**
  * Dispatch a full click sequence on the canvas at the given screen point.
  *
@@ -1016,6 +1471,15 @@ declare function dispatchPointerMiss(canvas: HTMLCanvasElement, point?: ScreenPo
  */
 declare function dispatchUnhover(canvas: HTMLCanvasElement): void;
 
+/**
+ * @module drag
+ *
+ * Deterministic drag interactions on 3D objects. Supports world-space deltas
+ * (move N units along an axis) and screen-space deltas (move N pixels).
+ * Projects start/end points and dispatches a full pointerdown → pointermove × N
+ * → pointerup sequence on the canvas.
+ */
+
 /** World-space drag delta. */
 interface WorldDelta {
     x: number;
@@ -1313,10 +1777,51 @@ declare function circlePath(center: {
     y: number;
 }, radiusX: number, radiusY?: number, steps?: number, pressure?: number): DrawPoint[];
 
+/**
+ * @module resolve
+ *
+ * Shared resolution helpers for all interaction modules. Caches references
+ * to the current ObjectStore, Camera, WebGLRenderer, and canvas size (set
+ * by ThreeDom each frame) so interaction functions can resolve objects and
+ * access rendering state without prop-drilling.
+ */
+
 /**
  * Resolve a testId or uuid to a live Object3D reference.
  * Throws a descriptive error if the object is not found.
  */
 declare function resolveObject(idOrUuid: string): Object3D;
 
-export { 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, MANAGED_ATTRIBUTES, type MaterialInspection, type ObjectInspection, type ObjectMetadata, ObjectStore, type PointerMiss3DOptions, type ProjectionResult, type R3FDOM, 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, getHighlighter, 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 };