@react-three-dom/core 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Object3D, Scene, Camera, WebGLRenderer, Intersection, Vector3 } from 'three';
 
-declare const version = "0.4.0";
+declare const version = "0.5.0";
 
 /**
  * Enable or disable debug logging globally.
@@ -239,6 +239,97 @@ interface R3FDOM {
         eventCount: number;
         pointCount: number;
     }>;
+    /** Click at an arbitrary world coordinate (projects to screen, dispatches click) */
+    clickAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Double-click at an arbitrary world coordinate */
+    doubleClickAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Right-click (context menu) at an arbitrary world coordinate */
+    contextMenuAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Hover at an arbitrary world coordinate */
+    hoverAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Click a sequence of world coordinates with delay between each (for drawing tools) */
+    clickAtWorldSequence(points: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>, options?: {
+        delayMs?: number;
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): Promise<Array<{
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    }>>;
     /** Select an object (shows highlight wireframe in scene) */
     select(idOrUuid: string): void;
     /** Clear selection */
@@ -916,6 +1007,16 @@ declare class Highlighter {
     isHighlighted(obj: Object3D): boolean;
     /** Remove all hover and selection highlights. */
     clearAll(): void;
+    /** When true, the hover poll is paused and showHoverHighlight is blocked. */
+    private _hoverPollSuppressed;
+    private _suppressTimer;
+    /**
+     * Stop the hover poll, clear all hover state, and restart after a delay.
+     * This prevents the DevTools extension from re-applying highlights after
+     * inspect mode is disabled (the extension polls `$0` every 200ms and
+     * keeps writing `__r3fdom_hovered__`).
+     */
+    suppressHoverPoll(durationMs?: number): void;
     private _syncSelectionHighlights;
     private _addSelectionHighlight;
     private _removeSelectionHighlight;
@@ -1777,6 +1878,62 @@ declare function circlePath(center: {
     y: number;
 }, radiusX: number, radiusY?: number, steps?: number, pressure?: number): DrawPoint[];
 
+/** A 3D world-space coordinate. */
+interface WorldPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Options shared by all world-coordinate interactions. */
+interface WorldInteractionOptions {
+    /** Modifier keys to include on the synthetic events. */
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+}
+/** Result returned by world-coordinate interactions. */
+interface WorldInteractionResult {
+    dispatched: boolean;
+    screenPoint: ScreenPoint;
+    behindCamera: boolean;
+}
+/**
+ * Click at an arbitrary world coordinate.
+ *
+ * Projects the point to screen space and dispatches a full click sequence
+ * (pointerdown → pointerup → click) on the canvas. R3F's event system will
+ * raycast from that screen position and fire onClick on whatever mesh is hit.
+ *
+ * @returns Result with the screen point used and whether the point was behind the camera.
+ */
+declare function clickAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Double-click at an arbitrary world coordinate.
+ */
+declare function doubleClickAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Right-click (context menu) at an arbitrary world coordinate.
+ */
+declare function contextMenuAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Hover at an arbitrary world coordinate.
+ *
+ * Dispatches pointermove → pointerover → pointerenter at the projected
+ * screen position. R3F will raycast and fire onPointerEnter/onPointerOver
+ * on whatever mesh is at that position.
+ */
+declare function hoverAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Click a sequence of world coordinates with optional delay between each.
+ * Useful for BIM drawing tools (polyline, measurement, etc.).
+ *
+ * @returns Array of results, one per point.
+ */
+declare function clickAtWorldSequence(points: WorldPoint[], options?: {
+    delayMs?: number;
+} & WorldInteractionOptions): Promise<WorldInteractionResult[]>;
+
 /**
  * @module resolve
  *
@@ -1824,4 +1981,4 @@ declare function resolveObject(idOrUuid: string): Object3D;
  */
 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 };
+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, type WorldInteractionOptions, type WorldInteractionResult, type WorldPoint, applyAttributes, circlePath, click3D, clickAtWorld, clickAtWorldSequence, computeAttributes, contextMenu3D, contextMenuAtWorld, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, doubleClickAtWorld, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore, getTagForType, hover3D, hoverAtWorld, 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.4.0";
+declare const version = "0.5.0";
 
 /**
  * Enable or disable debug logging globally.
@@ -239,6 +239,97 @@ interface R3FDOM {
         eventCount: number;
         pointCount: number;
     }>;
+    /** Click at an arbitrary world coordinate (projects to screen, dispatches click) */
+    clickAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Double-click at an arbitrary world coordinate */
+    doubleClickAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Right-click (context menu) at an arbitrary world coordinate */
+    contextMenuAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Hover at an arbitrary world coordinate */
+    hoverAtWorld(point: {
+        x: number;
+        y: number;
+        z: number;
+    }, options?: {
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): {
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    };
+    /** Click a sequence of world coordinates with delay between each (for drawing tools) */
+    clickAtWorldSequence(points: Array<{
+        x: number;
+        y: number;
+        z: number;
+    }>, options?: {
+        delayMs?: number;
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        altKey?: boolean;
+        metaKey?: boolean;
+    }): Promise<Array<{
+        dispatched: boolean;
+        screenPoint: {
+            x: number;
+            y: number;
+        };
+        behindCamera: boolean;
+    }>>;
     /** Select an object (shows highlight wireframe in scene) */
     select(idOrUuid: string): void;
     /** Clear selection */
@@ -916,6 +1007,16 @@ declare class Highlighter {
     isHighlighted(obj: Object3D): boolean;
     /** Remove all hover and selection highlights. */
     clearAll(): void;
+    /** When true, the hover poll is paused and showHoverHighlight is blocked. */
+    private _hoverPollSuppressed;
+    private _suppressTimer;
+    /**
+     * Stop the hover poll, clear all hover state, and restart after a delay.
+     * This prevents the DevTools extension from re-applying highlights after
+     * inspect mode is disabled (the extension polls `$0` every 200ms and
+     * keeps writing `__r3fdom_hovered__`).
+     */
+    suppressHoverPoll(durationMs?: number): void;
     private _syncSelectionHighlights;
     private _addSelectionHighlight;
     private _removeSelectionHighlight;
@@ -1777,6 +1878,62 @@ declare function circlePath(center: {
     y: number;
 }, radiusX: number, radiusY?: number, steps?: number, pressure?: number): DrawPoint[];
 
+/** A 3D world-space coordinate. */
+interface WorldPoint {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Options shared by all world-coordinate interactions. */
+interface WorldInteractionOptions {
+    /** Modifier keys to include on the synthetic events. */
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+}
+/** Result returned by world-coordinate interactions. */
+interface WorldInteractionResult {
+    dispatched: boolean;
+    screenPoint: ScreenPoint;
+    behindCamera: boolean;
+}
+/**
+ * Click at an arbitrary world coordinate.
+ *
+ * Projects the point to screen space and dispatches a full click sequence
+ * (pointerdown → pointerup → click) on the canvas. R3F's event system will
+ * raycast from that screen position and fire onClick on whatever mesh is hit.
+ *
+ * @returns Result with the screen point used and whether the point was behind the camera.
+ */
+declare function clickAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Double-click at an arbitrary world coordinate.
+ */
+declare function doubleClickAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Right-click (context menu) at an arbitrary world coordinate.
+ */
+declare function contextMenuAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Hover at an arbitrary world coordinate.
+ *
+ * Dispatches pointermove → pointerover → pointerenter at the projected
+ * screen position. R3F will raycast and fire onPointerEnter/onPointerOver
+ * on whatever mesh is at that position.
+ */
+declare function hoverAtWorld(point: WorldPoint, _options?: WorldInteractionOptions): WorldInteractionResult;
+/**
+ * Click a sequence of world coordinates with optional delay between each.
+ * Useful for BIM drawing tools (polyline, measurement, etc.).
+ *
+ * @returns Array of results, one per point.
+ */
+declare function clickAtWorldSequence(points: WorldPoint[], options?: {
+    delayMs?: number;
+} & WorldInteractionOptions): Promise<WorldInteractionResult[]>;
+
 /**
  * @module resolve
  *
@@ -1824,4 +1981,4 @@ declare function resolveObject(idOrUuid: string): Object3D;
  */
 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 };
+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, type WorldInteractionOptions, type WorldInteractionResult, type WorldPoint, applyAttributes, circlePath, click3D, clickAtWorld, clickAtWorldSequence, computeAttributes, contextMenu3D, contextMenuAtWorld, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, doubleClickAtWorld, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore, getTagForType, hover3D, hoverAtWorld, 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 { Box3, Vector3, Object3D, Matrix4, Frustum, Raycaster, Vector2, BufferGeometry, Material, Color, MeshBasicMaterial, DoubleSide, Mesh, BoxGeometry, EdgesGeometry, LineBasicMaterial, LineSegments, InstancedMesh, PerspectiveCamera, OrthographicCamera } from 'three';
 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.4.0";
+var version = "0.5.0";
 
 // src/debug.ts
 var _enabled = false;
@@ -1523,6 +1523,7 @@ function findTrackingPair(obj) {
 function registerSubtree(obj, store, mirror, instanceKey) {
   obj.traverse((child) => {
     if (!store.has(child) && shouldRegister(instanceKey, child)) {
+      ensureAncestorChain(child, store, mirror);
       store.register(child);
       mirror.onObjectAdded(child);
     }
@@ -2571,6 +2572,82 @@ function circlePath(center, radiusX, radiusY, steps = 36, pressure = 0.5) {
 function sleep2(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+var _v = new Vector3();
+function projectWorld(point, camera, size) {
+  _v.set(point.x, point.y, point.z).project(camera);
+  if (_v.z > 1) return null;
+  return {
+    x: (_v.x + 1) / 2 * size.width,
+    y: (-_v.y + 1) / 2 * size.height
+  };
+}
+function clickAtWorld(point, _options = {}) {
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const canvas = gl.domElement;
+  const screen = projectWorld(point, camera, size);
+  if (!screen) {
+    r3fLog("interaction", `clickAtWorld(${point.x}, ${point.y}, ${point.z}) \u2014 behind camera, skipped`);
+    return { dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: true };
+  }
+  r3fLog("interaction", `clickAtWorld(${point.x}, ${point.y}, ${point.z}) \u2192 screen(${Math.round(screen.x)}, ${Math.round(screen.y)})`);
+  dispatchClick(canvas, screen);
+  return { dispatched: true, screenPoint: screen, behindCamera: false };
+}
+function doubleClickAtWorld(point, _options = {}) {
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const canvas = gl.domElement;
+  const screen = projectWorld(point, camera, size);
+  if (!screen) {
+    r3fLog("interaction", `doubleClickAtWorld(${point.x}, ${point.y}, ${point.z}) \u2014 behind camera, skipped`);
+    return { dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: true };
+  }
+  r3fLog("interaction", `doubleClickAtWorld(${point.x}, ${point.y}, ${point.z}) \u2192 screen(${Math.round(screen.x)}, ${Math.round(screen.y)})`);
+  dispatchDoubleClick(canvas, screen);
+  return { dispatched: true, screenPoint: screen, behindCamera: false };
+}
+function contextMenuAtWorld(point, _options = {}) {
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const canvas = gl.domElement;
+  const screen = projectWorld(point, camera, size);
+  if (!screen) {
+    r3fLog("interaction", `contextMenuAtWorld(${point.x}, ${point.y}, ${point.z}) \u2014 behind camera, skipped`);
+    return { dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: true };
+  }
+  r3fLog("interaction", `contextMenuAtWorld(${point.x}, ${point.y}, ${point.z}) \u2192 screen(${Math.round(screen.x)}, ${Math.round(screen.y)})`);
+  dispatchContextMenu(canvas, screen);
+  return { dispatched: true, screenPoint: screen, behindCamera: false };
+}
+function hoverAtWorld(point, _options = {}) {
+  const camera = getCamera();
+  const gl = getRenderer();
+  const size = getCanvasSize();
+  const canvas = gl.domElement;
+  const screen = projectWorld(point, camera, size);
+  if (!screen) {
+    r3fLog("interaction", `hoverAtWorld(${point.x}, ${point.y}, ${point.z}) \u2014 behind camera, skipped`);
+    return { dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: true };
+  }
+  r3fLog("interaction", `hoverAtWorld(${point.x}, ${point.y}, ${point.z}) \u2192 screen(${Math.round(screen.x)}, ${Math.round(screen.y)})`);
+  dispatchHover(canvas, screen);
+  return { dispatched: true, screenPoint: screen, behindCamera: false };
+}
+async function clickAtWorldSequence(points, options = {}) {
+  const { delayMs = 50, ...interactionOpts } = options;
+  const results = [];
+  for (let i = 0; i < points.length; i++) {
+    results.push(clickAtWorld(points[i], interactionOpts));
+    if (delayMs > 0 && i < points.length - 1) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+  return results;
+}
 
 // src/highlight/SelectionManager.ts
 var SelectionManager = class {
@@ -2826,6 +2903,9 @@ var Highlighter = class {
     this._hoverPollId = null;
     this._lastHoveredUuid = null;
     this._store = null;
+    /** When true, the hover poll is paused and showHoverHighlight is blocked. */
+    this._hoverPollSuppressed = false;
+    this._suppressTimer = null;
   }
   // -----------------------------------------------------------------------
   // Lifecycle
@@ -2848,6 +2928,11 @@ var Highlighter = class {
       this._unsubscribe = null;
     }
     this._stopHoverPolling();
+    if (this._suppressTimer) {
+      clearTimeout(this._suppressTimer);
+      this._suppressTimer = null;
+    }
+    this._hoverPollSuppressed = false;
     this.clearHoverHighlight();
     this._clearAllSelectionHighlights();
     this._scene = null;
@@ -2875,6 +2960,7 @@ var Highlighter = class {
   // -----------------------------------------------------------------------
   /** Show a hover highlight on the given object (replaces any previous hover). */
   showHoverHighlight(obj) {
+    if (this._hoverPollSuppressed) return;
     if (obj === this._hoverTarget) return;
     this._clearHoverVisuals();
     if (!this._scene) return;
@@ -2913,6 +2999,26 @@ var Highlighter = class {
     this.clearHoverHighlight();
     this._clearAllSelectionHighlights();
   }
+  /**
+   * Stop the hover poll, clear all hover state, and restart after a delay.
+   * This prevents the DevTools extension from re-applying highlights after
+   * inspect mode is disabled (the extension polls `$0` every 200ms and
+   * keeps writing `__r3fdom_hovered__`).
+   */
+  suppressHoverPoll(durationMs = 1500) {
+    this._hoverPollSuppressed = true;
+    this._stopHoverPolling();
+    this._clearHoverVisuals();
+    this._lastHoveredUuid = null;
+    window.__r3fdom_hovered__ = null;
+    if (this._suppressTimer) clearTimeout(this._suppressTimer);
+    this._suppressTimer = setTimeout(() => {
+      this._hoverPollSuppressed = false;
+      this._suppressTimer = null;
+      window.__r3fdom_hovered__ = null;
+      this._startHoverPolling();
+    }, durationMs);
+  }
   // -----------------------------------------------------------------------
   // Internal: selection highlights
   // -----------------------------------------------------------------------
@@ -2995,6 +3101,16 @@ var Highlighter = class {
     try {
       const hoveredEl = window.__r3fdom_hovered__;
       const uuid = hoveredEl?.getAttribute?.("data-uuid") ?? null;
+      if (this._hoverPollSuppressed) {
+        if (uuid) {
+          window.__r3fdom_hovered__ = null;
+        }
+        if (this._hoverTarget) {
+          this._clearHoverVisuals();
+        }
+        this._lastHoveredUuid = null;
+        return;
+      }
       if (uuid === this._lastHoveredUuid) return;
       this._lastHoveredUuid = uuid;
       if (!uuid) {
@@ -3117,9 +3233,12 @@ var InspectController = class {
     this._boundContextMenu = null;
     this._hoveredObject = null;
     this._cancelHoverReveal();
-    this._highlighter.clearHoverHighlight();
+    this._highlighter.clearAll();
+    this._highlighter.suppressHoverPoll();
+    this._selectionManager.clearSelection();
+    window.__r3fdom_hovered__ = null;
     window.__r3fdom_selected_element__ = null;
-    r3fLog("inspect", "InspectController disabled");
+    r3fLog("inspect", "InspectController disabled \u2014 highlights and selection cleared");
   }
   /** Disable and release all resources. */
   dispose() {
@@ -3357,6 +3476,21 @@ function shouldRegister(instanceKey, obj) {
   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;
 }
@@ -3428,6 +3562,11 @@ function exposeGlobalAPI(store, gl, cameraRef, selMgr, inspCtrl, mirror, canvasI
       const result = await drawPath(points, options);
       return { eventCount: result.eventCount, pointCount: result.pointCount };
     },
+    clickAtWorld: (point, options) => clickAtWorld(point, options),
+    doubleClickAtWorld: (point, options) => doubleClickAtWorld(point, options),
+    contextMenuAtWorld: (point, options) => contextMenuAtWorld(point, options),
+    hoverAtWorld: (point, options) => hoverAtWorld(point, options),
+    clickAtWorldSequence: (points, options) => clickAtWorldSequence(points, options),
     select: (idOrUuid) => {
       const obj = store.getObject3D(idOrUuid);
       if (obj && selMgr) selMgr.select(obj);
@@ -3516,10 +3655,17 @@ function exposeGlobalAPI(store, gl, cameraRef, selMgr, inspCtrl, mirror, canvasI
         return;
       }
       obj.userData.__r3fdom_manual = true;
-      store.register(obj);
-      mirror?.onObjectAdded(obj);
-      mirror?.materialize(obj.uuid);
-      r3fLog("bridge", `r3fRegister: "${obj.userData?.testId || obj.name || obj.uuid.slice(0, 8)}" (${obj.type})`);
+      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;
@@ -3644,6 +3790,11 @@ function createStubBridge(error, canvasId) {
     pointerMiss: () => {
     },
     drawPath: async () => ({ eventCount: 0, pointCount: 0 }),
+    clickAtWorld: () => ({ dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: false }),
+    doubleClickAtWorld: () => ({ dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: false }),
+    contextMenuAtWorld: () => ({ dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: false }),
+    hoverAtWorld: () => ({ dispatched: false, screenPoint: { x: 0, y: 0 }, behindCamera: false }),
+    clickAtWorldSequence: async () => [],
     select: () => {
     },
     clearSelection: () => {
@@ -3776,8 +3927,12 @@ function ThreeDom({
       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);
             }
@@ -3956,6 +4111,6 @@ function useR3FRegister(ref, canvasId) {
   });
 }
 
-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 };
+export { DomMirror, Highlighter, InspectController, MANAGED_ATTRIBUTES, ObjectStore, RaycastAccelerator, SelectionManager, TAG_MAP, ThreeDom, ThreeElement, applyAttributes, circlePath, click3D, clickAtWorld, clickAtWorldSequence, computeAttributes, contextMenu3D, contextMenuAtWorld, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, doubleClickAtWorld, drag3D, drawPath, enableDebug, ensureCustomElements, getCanvasIds, getHighlighter, getInspectController, getMirror, getSelectionManager, getStore2 as getStore, getTagForType, hover3D, hoverAtWorld, 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