@react-three-dom/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,27 @@
-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.3.0";
+
+/**
+ * Enable or disable debug logging globally.
+ * When enabled, all r3fLog calls will output to console.log.
+ */
+declare function enableDebug(on?: boolean): void;
+/**
+ * Check if debug logging is currently enabled.
+ */
+declare function isDebugEnabled(): boolean;
+/**
+ * Log a debug message. Only outputs when debug is enabled via:
+ *   - enableDebug(true)
+ *   - window.__R3F_DOM_DEBUG__ = true
+ *   - <ThreeDom debug /> prop
+ *
+ * @param area - Module area (e.g. 'setup', 'store', 'patch', 'click', 'drag')
+ * @param msg  - Human-readable message
+ * @param data - Optional data payload (object, error, etc.)
+ */
+declare function r3fLog(area: string, msg: string, data?: unknown): void;
 
 interface ObjectMetadata {
     /** Three.js internal UUID */
@@ -23,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 */
@@ -36,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;
@@ -53,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 */
@@ -96,6 +134,16 @@ interface SnapshotNode {
     position: [number, number, number];
     rotation: [number, number, number];
     scale: [number, number, number];
+    /** Geometry class name (meshes only) */
+    geometryType?: string;
+    /** Material class name (meshes only) */
+    materialType?: string;
+    /** Total vertex count (meshes only) */
+    vertexCount?: number;
+    /** Triangle count (meshes only) */
+    triangleCount?: number;
+    /** Instance count (InstancedMesh only) */
+    instanceCount?: number;
     children: SnapshotNode[];
 }
 interface SceneSnapshot {
@@ -114,18 +162,47 @@ interface StoreEvent {
 }
 type StoreListener = (event: StoreEvent) => void;
 interface R3FDOM {
+    /**
+     * Whether the bridge is fully initialized and ready to use.
+     * - `true`: ThreeDom setup completed successfully, all methods are live.
+     * - `false`: Bridge exists but setup failed or is still initializing.
+     *
+     * Test waiters should check `_ready === true` instead of just `typeof !== 'undefined'`.
+     */
+    _ready: boolean;
+    /**
+     * If `_ready` is false, contains the error message from the failed setup.
+     * Undefined when `_ready` is true.
+     */
+    _error?: string;
     /** Tier 1: O(1) lookup by testId */
     getByTestId(id: string): ObjectMetadata | null;
     /** Tier 1: O(1) lookup by uuid */
     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 */
+    getCountByType(type: string): number;
+    /** Batch lookup: get metadata for multiple objects by testId or uuid in one call */
+    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 */
@@ -134,12 +211,14 @@ interface R3FDOM {
     contextMenu(idOrUuid: string): void;
     /** Deterministic hover on a 3D object */
     hover(idOrUuid: string): void;
-    /** Deterministic drag on a 3D object */
+    /** 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;
         y: number;
         z: number;
-    }): void;
+    }): Promise<void>;
     /** Dispatch a wheel/scroll event on a 3D object */
     wheel(idOrUuid: string, options?: {
         deltaY?: number;
@@ -147,21 +226,136 @@ interface R3FDOM {
     }): void;
     /** Click empty space to trigger onPointerMissed */
     pointerMiss(): void;
+    /** Draw a freeform path on the canvas (for drawing/annotation apps) */
+    drawPath(points: Array<{
+        x: number;
+        y: number;
+        pressure?: number;
+    }>, options?: {
+        stepDelayMs?: number;
+        pointerType?: 'mouse' | 'pen' | 'touch';
+        clickAtEnd?: boolean;
+    }): Promise<{
+        eventCount: number;
+        pointCount: number;
+    }>;
     /** Select an object (shows highlight wireframe in scene) */
     select(idOrUuid: string): void;
     /** Clear selection */
     clearSelection(): void;
+    /** Get uuids of currently selected objects (for DevTools panel sync) */
+    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 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;
@@ -175,14 +369,32 @@ 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).
+     * 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;
     /**
@@ -190,7 +402,10 @@ declare class ObjectStore {
      */
     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.
      */
     update(obj: Object3D): boolean;
@@ -198,14 +413,55 @@ declare class ObjectStore {
      * 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).
+     * Single round-trip — much more efficient than calling getByTestId/getByUuid
+     * in a loop for BIM/CAD scenes with many objects.
+     * O(k) where k is the number of requested ids.
+     */
+    getObjects(ids: string[]): Map<string, ObjectMetadata | null>;
+    /**
+     * Get all objects of a given Three.js type (e.g. "Mesh", "Group", "Line").
+     * 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.
+     * Uses JSON.stringify for deep equality on complex values.
+     * Linear scan — O(n).
+     */
+    getByUserData(key: string, value?: unknown): ObjectMetadata[];
+    /**
+     * Count objects of a given Three.js type.
+     * More efficient than getByType().length — no array allocation.
+     * Linear scan — O(n).
+     */
+    getCountByType(type: string): number;
     /** Get the raw Three.js Object3D by testId or uuid. */
     getObject3D(idOrUuid: string): Object3D | null;
     /** Get metadata for a known Object3D reference. */
@@ -217,9 +473,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;
     /**
@@ -239,10 +496,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.
  *
@@ -261,12 +540,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.
@@ -285,8 +582,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).
@@ -315,6 +618,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.
      */
@@ -346,6 +657,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:
@@ -369,6 +688,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.
@@ -460,6 +788,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[];
 /**
@@ -479,7 +815,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;
@@ -509,68 +858,222 @@ 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 hover 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;
     /** 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 */
     initialDepth?: number;
     /** Disable all sync. Default: true */
     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, }?: 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, batchSize, syncBudgetMs, maxDomNodes, initialDepth, enabled, debug, inspect: inspectProp, }?: ThreeDomProps): null;
 
 /**
  * Patch Object3D.prototype.add and Object3D.prototype.remove to intercept
@@ -622,6 +1125,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. */
@@ -680,6 +1193,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. */
@@ -831,6 +1353,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.
  *
@@ -914,6 +1445,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;
@@ -1045,10 +1585,185 @@ interface PointerMiss3DOptions {
  */
 declare function pointerMiss3D(options?: PointerMiss3DOptions): void;
 
+/** A 2D screen-space point in CSS pixels, relative to the canvas top-left. */
+interface DrawPoint {
+    /** X coordinate in CSS pixels from canvas left edge. */
+    x: number;
+    /** Y coordinate in CSS pixels from canvas top edge. */
+    y: number;
+    /** Optional pressure (0–1). Default: 0.5 */
+    pressure?: number;
+}
+/** Options for drawPath. */
+interface DrawPathOptions {
+    /**
+     * Delay in milliseconds between successive pointermove events.
+     * Useful for apps that sample pointer events per-frame.
+     * Default: 0 (dispatch all moves synchronously, which is fastest)
+     */
+    stepDelayMs?: number;
+    /**
+     * Pointer type. Some drawing apps differentiate between mouse and pen.
+     * Default: 'mouse'
+     */
+    pointerType?: 'mouse' | 'pen' | 'touch';
+    /**
+     * If true, also dispatches a 'click' event at the end of the path.
+     * Useful if the app interprets short strokes as clicks.
+     * Default: false
+     */
+    clickAtEnd?: boolean;
+    /**
+     * If provided, draws on a specific canvas element.
+     * Default: the R3F canvas (from the current renderer).
+     */
+    canvas?: HTMLCanvasElement;
+}
+/** Result of a drawPath operation. */
+interface DrawPathResult {
+    /** Total number of pointer events dispatched. */
+    eventCount: number;
+    /** The number of points in the path. */
+    pointCount: number;
+    /** First point of the path. */
+    startPoint: DrawPoint;
+    /** Last point of the path. */
+    endPoint: DrawPoint;
+}
+/**
+ * Simulate a freeform drawing stroke on the canvas.
+ *
+ * Dispatches a full pointer sequence through the provided path of points:
+ * `pointerdown` at the first point, `pointermove` at each subsequent point,
+ * and `pointerup` at the last point.
+ *
+ * This is designed for canvas drawing applications (e.g. whiteboard, annotation
+ * tools, CAD sketch mode) that respond to pointer events to create geometry.
+ *
+ * @param points    Array of screen-space points (min 2 required)
+ * @param options   Drawing options
+ * @returns         Result with event counts and start/end points
+ * @throws          If fewer than 2 points are provided
+ *
+ * @example
+ * ```typescript
+ * // Draw a simple line from (100, 100) to (300, 200)
+ * await drawPath([
+ *   { x: 100, y: 100 },
+ *   { x: 200, y: 150 },
+ *   { x: 300, y: 200 },
+ * ]);
+ *
+ * // Draw with pen pressure simulation
+ * await drawPath([
+ *   { x: 50, y: 50, pressure: 0.2 },
+ *   { x: 100, y: 80, pressure: 0.6 },
+ *   { x: 150, y: 70, pressure: 0.9 },
+ *   { x: 200, y: 60, pressure: 0.4 },
+ * ], { pointerType: 'pen', stepDelayMs: 16 });
+ * ```
+ */
+declare function drawPath(points: DrawPoint[], options?: DrawPathOptions): Promise<DrawPathResult>;
+/**
+ * Generate an array of DrawPoints along a straight line.
+ * Useful for creating uniform stroke paths programmatically.
+ *
+ * @param start     Start point (screen-space CSS pixels)
+ * @param end       End point (screen-space CSS pixels)
+ * @param steps     Number of intermediate points (excluding start/end). Default: 10
+ * @param pressure  Uniform pressure for all points. Default: 0.5
+ * @returns         Array of DrawPoints including start and end
+ *
+ * @example
+ * ```typescript
+ * const points = linePath({ x: 0, y: 0 }, { x: 200, y: 200 }, 20);
+ * await drawPath(points);
+ * ```
+ */
+declare function linePath(start: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, steps?: number, pressure?: number): DrawPoint[];
+/**
+ * Generate an array of DrawPoints along a quadratic bezier curve.
+ * Great for simulating smooth freehand drawing strokes.
+ *
+ * @param start     Start point
+ * @param control   Control point (determines curve shape)
+ * @param end       End point
+ * @param steps     Number of steps. Default: 20
+ * @param pressure  Uniform pressure. Default: 0.5
+ * @returns         Array of DrawPoints along the curve
+ *
+ * @example
+ * ```typescript
+ * const points = curvePath(
+ *   { x: 50, y: 200 },   // start
+ *   { x: 150, y: 50 },   // control (peak of the curve)
+ *   { x: 250, y: 200 },  // end
+ *   30,
+ * );
+ * await drawPath(points);
+ * ```
+ */
+declare function curvePath(start: {
+    x: number;
+    y: number;
+}, control: {
+    x: number;
+    y: number;
+}, end: {
+    x: number;
+    y: number;
+}, steps?: number, pressure?: number): DrawPoint[];
+/**
+ * Generate an array of DrawPoints forming a rectangle.
+ * Useful for drawing rectangular selections or bounding boxes.
+ *
+ * @param topLeft      Top-left corner
+ * @param bottomRight  Bottom-right corner
+ * @param pointsPerSide  Number of points per side. Default: 5
+ * @param pressure     Uniform pressure. Default: 0.5
+ * @returns            Array of DrawPoints tracing the rectangle
+ */
+declare function rectPath(topLeft: {
+    x: number;
+    y: number;
+}, bottomRight: {
+    x: number;
+    y: number;
+}, pointsPerSide?: number, pressure?: number): DrawPoint[];
+/**
+ * Generate an array of DrawPoints forming a circle/ellipse.
+ *
+ * @param center   Center of the circle (screen-space)
+ * @param radiusX  Horizontal radius in CSS pixels
+ * @param radiusY  Vertical radius in CSS pixels. Default: same as radiusX (circle)
+ * @param steps    Number of points. Default: 36 (10° increments)
+ * @param pressure Uniform pressure. Default: 0.5
+ * @returns        Array of DrawPoints forming the circle
+ */
+declare function circlePath(center: {
+    x: number;
+    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 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, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, ensureCustomElements, getHighlighter, getMirror, getSelectionManager, getStore, getTagForType, hover3D, isInFrustum, isPatched, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };
+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 };