@react-three-dom/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1054 @@
+import { Object3D, Camera, WebGLRenderer, Vector3 } from 'three';
+
+declare const version = "0.1.0";
+
+interface ObjectMetadata {
+    /** Three.js internal UUID */
+    uuid: string;
+    /** Object name (object.name) */
+    name: string;
+    /** Three.js class type: "Mesh", "Group", "PointLight", etc. */
+    type: string;
+    /** Whether the object itself is visible (does not check parent chain) */
+    visible: boolean;
+    /** User-defined test identifier from userData.testId */
+    testId?: string;
+    /** Geometry class name: "BoxGeometry", "BufferGeometry", etc. */
+    geometryType?: string;
+    /** Material class name: "MeshStandardMaterial", etc. */
+    materialType?: string;
+    /** Total vertex count (from geometry attributes) */
+    vertexCount?: number;
+    /** Triangle count (derived from index or vertex count) */
+    triangleCount?: number;
+    /** Instance count for InstancedMesh */
+    instanceCount?: number;
+    /** Local position as [x, y, z] */
+    position: [number, number, number];
+    /** Local euler rotation as [x, y, z] in radians */
+    rotation: [number, number, number];
+    /** Local scale as [x, y, z] */
+    scale: [number, number, number];
+    /** UUID of parent object, or null for scene root */
+    parentUuid: string | null;
+    /** UUIDs of direct children */
+    childrenUuids: string[];
+    /** Flag indicating bounds need recomputation */
+    boundsDirty: boolean;
+}
+interface GeometryInspection {
+    /** Geometry class type */
+    type: string;
+    /** Map of attribute name → { itemSize, count } */
+    attributes: Record<string, {
+        itemSize: number;
+        count: number;
+    }>;
+    /** Index buffer info, if indexed geometry */
+    index?: {
+        count: number;
+    };
+    /** Bounding sphere computed from geometry */
+    boundingSphere?: {
+        center: [number, number, number];
+        radius: number;
+    };
+}
+interface MaterialInspection {
+    /** Material class type */
+    type: string;
+    /** Hex color string, if applicable */
+    color?: string;
+    /** Texture name/uuid of the main map, if any */
+    map?: string;
+    /** Shader material uniforms (keys only for non-shader materials) */
+    uniforms?: Record<string, unknown>;
+    /** Whether material is transparent */
+    transparent?: boolean;
+    /** Material opacity */
+    opacity?: number;
+    /** Whether the material is double-sided */
+    side?: number;
+}
+interface ObjectInspection {
+    /** Tier 1 cached metadata */
+    metadata: ObjectMetadata;
+    /** World matrix as 16-element flat array */
+    worldMatrix: number[];
+    /** World-space axis-aligned bounding box */
+    bounds: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    /** Geometry details (meshes only) */
+    geometry?: GeometryInspection;
+    /** Material details (meshes/points/lines only) */
+    material?: MaterialInspection;
+    /** Full userData object from the Three.js object */
+    userData: Record<string, unknown>;
+}
+interface SnapshotNode {
+    uuid: string;
+    name: string;
+    type: string;
+    testId?: string;
+    visible: boolean;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    children: SnapshotNode[];
+}
+interface SceneSnapshot {
+    /** Timestamp when snapshot was taken (Date.now()) */
+    timestamp: number;
+    /** Total number of objects in the scene */
+    objectCount: number;
+    /** Recursive tree of snapshot nodes */
+    tree: SnapshotNode;
+}
+type StoreEventType = 'add' | 'remove' | 'update';
+interface StoreEvent {
+    type: StoreEventType;
+    object: Object3D;
+    metadata: ObjectMetadata;
+}
+type StoreListener = (event: StoreEvent) => void;
+interface R3FDOM {
+    /** 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[];
+    /** Total number of tracked objects */
+    getCount(): number;
+    /** 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;
+    /** Deterministic click on a 3D object */
+    click(idOrUuid: string): void;
+    /** Deterministic double-click on a 3D object */
+    doubleClick(idOrUuid: string): void;
+    /** Deterministic right-click / context menu on a 3D object */
+    contextMenu(idOrUuid: string): void;
+    /** Deterministic hover on a 3D object */
+    hover(idOrUuid: string): void;
+    /** Deterministic drag on a 3D object */
+    drag(idOrUuid: string, delta: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    /** Dispatch a wheel/scroll event on a 3D object */
+    wheel(idOrUuid: string, options?: {
+        deltaY?: number;
+        deltaX?: number;
+    }): void;
+    /** Click empty space to trigger onPointerMissed */
+    pointerMiss(): void;
+    /** Select an object (shows highlight wireframe in scene) */
+    select(idOrUuid: string): void;
+    /** Clear selection */
+    clearSelection(): void;
+    /** Raw Three.js object access (for advanced debugging) */
+    getObject3D(idOrUuid: string): Object3D | null;
+    /** Library version */
+    version: string;
+}
+declare global {
+    interface Window {
+        __R3F_DOM__?: R3FDOM;
+    }
+}
+
+declare class ObjectStore {
+    private _metaByObject;
+    private _objectByUuid;
+    private _objectsByTestId;
+    private _objectsByName;
+    private _flatList;
+    private _flatListDirty;
+    private _dirtyQueue;
+    private _listeners;
+    private _trackedRoots;
+    /**
+     * Register a single object into the store.
+     * Populates Tier 1 metadata and all indexes.
+     */
+    register(obj: Object3D): ObjectMetadata;
+    /**
+     * Register an entire subtree (object + all descendants).
+     */
+    registerTree(root: Object3D): void;
+    /**
+     * Unregister a single object from the store.
+     */
+    unregister(obj: Object3D): void;
+    /**
+     * Unregister an entire subtree (object + all descendants).
+     */
+    unregisterTree(root: Object3D): void;
+    /**
+     * Refresh Tier 1 metadata from the live Three.js object.
+     * Returns true if any values changed.
+     */
+    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.
+     */
+    inspect(idOrUuid: string): 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 the raw Three.js Object3D by testId or uuid. */
+    getObject3D(idOrUuid: string): Object3D | null;
+    /** Get metadata for a known Object3D reference. */
+    getMetadata(obj: Object3D): ObjectMetadata | null;
+    /** Check if an object is registered. */
+    has(obj: Object3D): boolean;
+    /** Total number of tracked objects. */
+    getCount(): number;
+    /** 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.
+     */
+    isInTrackedScene(obj: Object3D): boolean;
+    /**
+     * Get a flat array of all tracked objects for amortized batch processing.
+     * Rebuilds lazily when the list is dirty (objects added/removed).
+     */
+    getFlatList(): Object3D[];
+    /** Mark an object as dirty (needs priority sync next frame). */
+    markDirty(obj: Object3D): void;
+    /**
+     * Drain the dirty queue, returning all objects that need priority sync.
+     * Clears the queue after draining.
+     */
+    drainDirtyQueue(): Object3D[];
+    /** Number of objects currently in the dirty queue. */
+    getDirtyCount(): number;
+    /** Subscribe to store events (add, remove, update). */
+    subscribe(listener: StoreListener): () => void;
+    private _emit;
+    /** Remove all tracked objects and reset state. */
+    dispose(): void;
+}
+
+/**
+ * Manages the parallel DOM tree that mirrors the Three.js scene graph.
+ *
+ * Key design for 100k-scale:
+ * - ObjectStore holds Tier 1 metadata for ALL objects (cheap, ~120 bytes each)
+ * - DomMirror only materializes DOM nodes for actively viewed/queried objects
+ * - Max materialized DOM nodes capped (default 2,000) with LRU eviction
+ * - DOM writes only happen for materialized nodes where values actually differ
+ */
+declare class DomMirror {
+    private _store;
+    private _rootElement;
+    private _nodes;
+    private _lruHead;
+    private _lruTail;
+    private _lruSize;
+    private _maxNodes;
+    private _parentMap;
+    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;
+    /**
+     * Build the initial DOM tree from the scene.
+     * Materializes the top 2 levels of the scene hierarchy.
+     */
+    buildInitialTree(scene: Object3D): void;
+    /**
+     * Create a DOM node for a single object.
+     * If already materialized, touches the LRU and returns the existing element.
+     */
+    materialize(uuid: string): HTMLElement | null;
+    /**
+     * Materialize a subtree starting from the given uuid, up to the specified depth.
+     * depth=0 materializes just the node, depth=1 includes direct children, etc.
+     */
+    materializeSubtree(uuid: string, depth: number): void;
+    /**
+     * Remove a DOM node but keep JS metadata in the ObjectStore.
+     * Called by LRU eviction or when an object is removed from the scene.
+     */
+    dematerialize(uuid: string): void;
+    /**
+     * Called when a new object is added to the tracked scene.
+     * Only materializes if the parent is already materialized (lazy expansion).
+     */
+    onObjectAdded(obj: Object3D): void;
+    /**
+     * Called when an object is removed from the tracked scene.
+     * Dematerializes the object and all its descendants.
+     */
+    onObjectRemoved(obj: Object3D): void;
+    /**
+     * Sync Tier 1 attributes for an object if it's materialized.
+     * No-op if the object has no materialized DOM node.
+     * Returns the number of DOM writes performed.
+     */
+    syncAttributes(obj: Object3D): number;
+    /**
+     * Sync attributes by uuid (when you don't have the Object3D ref).
+     */
+    syncAttributesByUuid(uuid: string): number;
+    /**
+     * Get the root DOM element.
+     */
+    getRootElement(): HTMLElement | null;
+    /**
+     * Get the materialized DOM element for an object, if it exists.
+     */
+    getElement(uuid: string): HTMLElement | null;
+    /**
+     * Check if an object has a materialized DOM node.
+     */
+    isMaterialized(uuid: string): boolean;
+    /**
+     * Query the mirror DOM using a CSS selector.
+     * Falls back to searching the ObjectStore if no materialized nodes match,
+     * then materializes the matching objects.
+     */
+    querySelector(selector: string): HTMLElement | null;
+    /**
+     * Query all matching elements in the mirror DOM.
+     */
+    querySelectorAll(selector: string): HTMLElement[];
+    /**
+     * Set the maximum number of materialized DOM nodes.
+     * If current count exceeds the new max, excess nodes are evicted immediately.
+     */
+    setMaxNodes(max: number): void;
+    /** Current number of materialized DOM nodes. */
+    getMaterializedCount(): number;
+    /** Maximum allowed materialized DOM nodes. */
+    getMaxNodes(): number;
+    /**
+     * Remove all materialized DOM nodes and reset state.
+     */
+    dispose(): void;
+    /**
+     * Insert a newly created element into the correct position in the DOM tree.
+     */
+    private _insertIntoDom;
+    /**
+     * Parse common CSS selector patterns and resolve to a uuid from the store.
+     * Supports:
+     *   [data-test-id="value"]
+     *   [data-name="value"]
+     *   [data-uuid="value"]
+     *   three-mesh, three-light, etc. (by tag/type)
+     */
+    private _findUuidBySelector;
+    /**
+     * Find all UUIDs matching a selector pattern.
+     */
+    private _findAllUuidsBySelector;
+    /** Add a node to the front (most recently used). */
+    private _lruPush;
+    /** Remove a node from the list. */
+    private _lruRemove;
+    /** Move a node to the front (most recently used). */
+    private _lruTouch;
+    /** Evict the least recently used node. */
+    private _evictLRU;
+}
+
+/**
+ * Maps Three.js object types to custom element tag names.
+ * Multiple Three.js types can map to the same tag.
+ */
+declare const TAG_MAP: Record<string, string>;
+/** All unique tag names that need to be registered. */
+declare const ALL_TAGS: readonly ["three-scene", "three-group", "three-mesh", "three-light", "three-camera", "three-object"];
+type ThreeTagName = (typeof ALL_TAGS)[number];
+/**
+ * Get the custom element tag name for a Three.js object type.
+ */
+declare function getTagForType(type: string): ThreeTagName;
+/**
+ * Base custom element class for the DOM mirror.
+ * Provides interactive properties and methods accessible via DevTools console.
+ *
+ * Usage in DevTools after selecting a <three-mesh> in the Elements panel:
+ *   $0.metadata     → Tier 1 cached metadata (instant)
+ *   $0.inspect()    → Tier 2 heavy inspection (reads live Three.js object)
+ *   $0.object3D     → raw THREE.Object3D reference
+ *   $0.position     → [x, y, z] shortcut
+ *   $0.bounds       → { min, max } shortcut
+ *   $0.click()      → trigger deterministic click
+ *   $0.hover()      → trigger deterministic hover
+ */
+declare class ThreeElement extends HTMLElement {
+    /**
+     * Returns the Tier 1 cached metadata for this object.
+     * Instant, no computation. Returns null if the element is not linked.
+     */
+    get metadata(): ObjectMetadata | null;
+    /**
+     * Performs a full inspection of the linked Three.js object.
+     * Reads geometry buffers, material properties, world bounds, etc.
+     * Cost: 0.1–2ms depending on geometry complexity.
+     */
+    inspect(): ObjectInspection | null;
+    /**
+     * Returns the raw Three.js Object3D linked to this DOM element.
+     * Allows direct access to any Three.js property or method.
+     */
+    get object3D(): Object3D | null;
+    /**
+     * Local position as [x, y, z].
+     */
+    get position(): [number, number, number] | null;
+    /**
+     * Local euler rotation as [x, y, z] in radians.
+     */
+    get rotation(): [number, number, number] | null;
+    /**
+     * Local scale as [x, y, z].
+     */
+    get scale(): [number, number, number] | null;
+    /**
+     * Whether the object is visible (does not check parent chain).
+     */
+    get visible(): boolean;
+    /**
+     * The testId from userData.testId, if set.
+     */
+    get testId(): string | undefined;
+    /**
+     * World-space bounding box. Computed on-demand (Tier 2).
+     */
+    get bounds(): {
+        min: [number, number, number];
+        max: [number, number, number];
+    } | null;
+    /**
+     * Trigger a deterministic click on the linked 3D object.
+     * Projects the object center to screen coordinates and dispatches pointer events.
+     */
+    click(): void;
+    /**
+     * Trigger a deterministic hover on the linked 3D object.
+     */
+    hover(): void;
+    /**
+     * Returns a readable string representation for console output.
+     */
+    toString(): string;
+}
+/**
+ * Register all custom elements (<three-scene>, <three-mesh>, etc.).
+ * Safe to call multiple times — only registers once.
+ *
+ * @param store - The ObjectStore instance for element property lookups
+ */
+declare function ensureCustomElements(store: ObjectStore): void;
+
+/** All attribute names we manage (for diffing). */
+declare const MANAGED_ATTRIBUTES: string[];
+/**
+ * Compute all attribute key-value pairs for a metadata object.
+ * Returns a map of attribute name → value.
+ * Attributes with undefined values are excluded.
+ */
+declare function computeAttributes(meta: ObjectMetadata): Map<string, string>;
+/**
+ * Apply attributes to a DOM element, only writing those that changed.
+ * Returns the number of attributes that were actually written (for perf tracking).
+ *
+ * @param element - The custom element to update
+ * @param meta - Current Tier 1 metadata
+ * @param prevAttrs - Previous attribute values (mutated in-place to reflect new state)
+ * @returns Number of DOM setAttribute calls made
+ */
+declare function applyAttributes(element: HTMLElement, meta: ObjectMetadata, prevAttrs: Map<string, string>): number;
+
+type SelectionListener = (selected: Object3D[]) => void;
+declare class SelectionManager {
+    /** Currently selected objects (ordered by selection time). */
+    private _selected;
+    /** Listeners notified on selection change. */
+    private _listeners;
+    /** Select a single object (clears previous selection). */
+    select(obj: Object3D): void;
+    /** Add an object to the current selection (multi-select). */
+    addToSelection(obj: Object3D): void;
+    /** Remove an object from the selection. */
+    removeFromSelection(obj: Object3D): void;
+    /** Toggle an object in/out of the selection. */
+    toggleSelection(obj: Object3D): void;
+    /** Clear all selections. */
+    clearSelection(): void;
+    /** Get the currently selected objects. */
+    getSelected(): readonly Object3D[];
+    /** Get the primary (first) selected object, or null. */
+    getPrimary(): Object3D | null;
+    /** Check if an object is selected. */
+    isSelected(obj: Object3D): boolean;
+    /** Number of selected objects. */
+    get count(): number;
+    /** Subscribe to selection changes. Returns unsubscribe function. */
+    subscribe(listener: SelectionListener): () => void;
+    private _notify;
+    dispose(): void;
+}
+
+interface HighlighterOptions {
+    /** Whether to show a tooltip above highlighted objects. Default: true */
+    showTooltip?: boolean;
+}
+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 _unsubscribe;
+    private _showTooltip;
+    /** DevTools hover polling interval */
+    private _hoverPollId;
+    private _lastHoveredElement;
+    /** Store reference for resolving objects */
+    private _store;
+    constructor(options?: HighlighterOptions);
+    attach(_scene: Object3D, selectionManager: SelectionManager, camera: Camera, renderer: WebGLRenderer, store: {
+        getObject3D(uuid: string): Object3D | null;
+    }): void;
+    detach(): void;
+    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 */
+    showHoverHighlight(obj: Object3D): void;
+    /** Clear the hover highlight */
+    clearHoverHighlight(): void;
+    private _syncSelectedHighlights;
+    private _addSelectedHighlight;
+    private _addHoverHighlightRecursive;
+    private _startHoverPolling;
+    private _stopHoverPolling;
+    private _pollDevToolsHover;
+    private _removeOverlay;
+    private _clearAllOverlays;
+    dispose(): void;
+}
+
+interface ThreeDomProps {
+    /** 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;
+    /** 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;
+}
+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;
+
+/**
+ * Patch Object3D.prototype.add and Object3D.prototype.remove to intercept
+ * structural changes for tracked scenes.
+ *
+ * @param store - The ObjectStore managing scene metadata
+ * @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;
+/**
+ * Restore the original Object3D.prototype.add and remove methods.
+ * Called automatically when the last store/mirror pair is removed.
+ * Can also be called manually for testing.
+ */
+declare function restoreObject3D(): void;
+/**
+ * Check if Object3D prototype is currently patched.
+ */
+declare function isPatched(): boolean;
+
+/**
+ * Create a full scene snapshot from the ObjectStore.
+ *
+ * Returns a structured JSON tree built entirely from Tier 1 cached metadata.
+ * No Three.js objects or DOM nodes are accessed.
+ *
+ * @example
+ * ```ts
+ * const snap = createSnapshot(store);
+ * console.log(snap.objectCount); // 1234
+ * console.log(snap.tree.children[0].name); // "Furniture"
+ * ```
+ */
+declare function createSnapshot(store: ObjectStore): SceneSnapshot;
+/**
+ * Create a flat snapshot — an array of all object metadata without tree structure.
+ * Useful for searching/filtering without recursion.
+ *
+ * @example
+ * ```ts
+ * const flat = createFlatSnapshot(store);
+ * const meshes = flat.objects.filter(m => m.type === 'Mesh');
+ * ```
+ */
+declare function createFlatSnapshot(store: ObjectStore): {
+    timestamp: number;
+    objectCount: number;
+    objects: ObjectMetadata[];
+};
+
+/** Screen-space coordinates in CSS pixels relative to the canvas. */
+interface ScreenPoint {
+    /** X coordinate in CSS pixels, left = 0. */
+    x: number;
+    /** Y coordinate in CSS pixels, top = 0. */
+    y: number;
+}
+/** Canvas dimensions in CSS pixels. */
+interface CanvasSize {
+    width: number;
+    height: number;
+}
+/** Result of a projection attempt. */
+interface ProjectionResult {
+    /** The screen-space point (CSS pixels relative to the canvas element). */
+    point: ScreenPoint;
+    /** Which strategy produced the result. */
+    strategy: 'center' | 'corner' | 'face-center' | 'fallback-origin';
+    /** NDC coordinates (-1..+1 range) for the projected point. */
+    ndc: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Project a 3D object to screen coordinates using a multi-strategy approach:
+ *
+ * 1. **Center**: Try the bounding box center (most natural click target).
+ * 2. **Face centers**: Try the 6 face centers (better for large/flat objects).
+ * 3. **Corners**: Try the 8 bbox corners (catches partially visible objects).
+ * 4. **Fallback origin**: Try the object's world position (lights, empty groups).
+ *
+ * For each strategy, we prefer points that are both on-screen AND closest to
+ * the viewport center (most reliable for event dispatch).
+ *
+ * Returns `null` if no part of the object is visible on screen.
+ */
+declare function projectToScreen(obj: Object3D, camera: Camera, size: CanvasSize): ProjectionResult | null;
+/**
+ * Check whether any part of an Object3D is within the camera frustum.
+ * Uses the bounding box intersection test (fast, conservative).
+ */
+declare function isInFrustum(obj: Object3D, camera: Camera): boolean;
+/**
+ * Convert a screen-space delta (CSS pixels) to a world-space displacement
+ * vector on the plane perpendicular to the camera at the given depth.
+ *
+ * Used by drag3D to convert pixel movements to 3D movements that feel
+ * natural regardless of camera position/zoom.
+ */
+declare function screenDeltaToWorld(dx: number, dy: number, obj: Object3D, camera: Camera, size: CanvasSize): Vector3;
+/**
+ * Project multiple sample points of an object to screen space.
+ * Returns all on-screen points, useful for assertions like
+ * "object covers at least 50px² of screen area".
+ */
+declare function projectAllSamplePoints(obj: Object3D, camera: Camera, size: CanvasSize): ScreenPoint[];
+
+/** Result of a raycast verification. */
+interface RaycastResult {
+    /** Whether the intended object was hit. */
+    hit: boolean;
+    /** If not hit, the object that was hit instead (occluder). */
+    occluder?: Object3D;
+    /** Name or testId of the occluder, for error messages. */
+    occluderLabel?: string;
+}
+/**
+ * Verify that a raycast from the given screen point hits the intended object.
+ *
+ * Returns a RaycastResult indicating success or failure with details about
+ * what was hit instead (for useful error messages).
+ *
+ * @param point   Screen-space coordinates (CSS pixels relative to canvas)
+ * @param target  The intended Object3D to hit
+ * @param camera  The active camera
+ * @param size    Canvas size in CSS pixels
+ */
+declare function verifyRaycastHit(point: ScreenPoint, target: Object3D, camera: Camera, size: CanvasSize): RaycastResult;
+/**
+ * Verify a hit, trying multiple sample points if the first fails.
+ * This is more robust than single-point verification for objects
+ * that are partially occluded.
+ *
+ * @param points  Array of screen-space points to try
+ * @param target  The intended Object3D to hit
+ * @param camera  The active camera
+ * @param size    Canvas size in CSS pixels
+ */
+declare function verifyRaycastHitMultiPoint(points: ScreenPoint[], target: Object3D, camera: Camera, size: CanvasSize): RaycastResult;
+
+/** Options for click3D. */
+interface Click3DOptions {
+    /**
+     * Whether to verify the click hit via raycast.
+     * Set to false for non-mesh objects (lights, cameras, groups).
+     * Default: true
+     */
+    verify?: boolean;
+}
+/** Result of a click3D operation. */
+interface Click3DResult {
+    /** Whether the click was dispatched. Always true if no error thrown. */
+    dispatched: true;
+    /** Raycast verification result (only if verify: true). */
+    raycast?: RaycastResult;
+    /** The screen point where the click was dispatched. */
+    screenPoint: {
+        x: number;
+        y: number;
+    };
+    /** Which projection strategy was used. */
+    strategy: string;
+}
+/**
+ * Programmatically click a 3D object by its testId or uuid.
+ *
+ * Projects the object to screen space, dispatches a synthetic click event
+ * on the canvas at the projected coordinates, and optionally verifies
+ * the click hit the intended object via raycasting.
+ *
+ * @param idOrUuid  The object's testId or uuid
+ * @param options   Click options
+ * @returns         Click result with dispatch and verification info
+ * @throws          If the object is not found or not visible on screen
+ *
+ * @example
+ * ```typescript
+ * // From the global API
+ * window.__R3F_DOM__.click('chair-primary');
+ *
+ * // With verification disabled (for lights, cameras)
+ * click3D('sun-light', { verify: false });
+ * ```
+ */
+declare function click3D(idOrUuid: string, options?: Click3DOptions): Click3DResult;
+/**
+ * Programmatically double-click a 3D object by its testId or uuid.
+ *
+ * Dispatches the full double-click sequence:
+ * pointerdown → pointerup → click → pointerdown → pointerup → click → dblclick
+ *
+ * Triggers R3F's `onDoubleClick` handler on the hit object.
+ *
+ * @param idOrUuid  The object's testId or uuid
+ * @param options   Same options as click3D
+ * @returns         Click result with dispatch and verification info
+ * @throws          If the object is not found or not visible on screen
+ */
+declare function doubleClick3D(idOrUuid: string, options?: Click3DOptions): Click3DResult;
+/**
+ * Programmatically right-click a 3D object by its testId or uuid.
+ *
+ * Dispatches: pointerdown (button=2) → pointerup (button=2) → contextmenu
+ *
+ * Triggers R3F's `onContextMenu` handler on the hit object.
+ *
+ * @param idOrUuid  The object's testId or uuid
+ * @param options   Same options as click3D
+ * @returns         Click result with dispatch and verification info
+ * @throws          If the object is not found or not visible on screen
+ */
+declare function contextMenu3D(idOrUuid: string, options?: Click3DOptions): Click3DResult;
+
+/** Options for hover3D. */
+interface Hover3DOptions {
+    /**
+     * Whether to verify the hover hit via raycast.
+     * Default: true
+     */
+    verify?: boolean;
+}
+/** Result of a hover3D operation. */
+interface Hover3DResult {
+    /** Whether the hover was dispatched. Always true if no error thrown. */
+    dispatched: true;
+    /** Raycast verification result (only if verify: true). */
+    raycast?: RaycastResult;
+    /** The screen point where the hover was dispatched. */
+    screenPoint: {
+        x: number;
+        y: number;
+    };
+    /** Which projection strategy was used. */
+    strategy: string;
+}
+/**
+ * Programmatically hover over a 3D object by its testId or uuid.
+ *
+ * Projects the object to screen space, dispatches a synthetic hover event
+ * sequence on the canvas, and optionally verifies the hit.
+ *
+ * @param idOrUuid  The object's testId or uuid
+ * @param options   Hover options
+ * @returns         Hover result with dispatch and verification info
+ * @throws          If the object is not found or not visible on screen
+ *
+ * @example
+ * ```typescript
+ * window.__R3F_DOM__.hover('chair-primary');
+ * ```
+ */
+declare function hover3D(idOrUuid: string, options?: Hover3DOptions): Hover3DResult;
+/**
+ * Clear hover state by moving the pointer off-canvas.
+ * Call between hover/click interactions to reset R3F's internal pointer state.
+ */
+declare function unhover3D(): void;
+
+/**
+ * Dispatch a full click sequence on the canvas at the given screen point.
+ *
+ * Sequence: pointerdown → pointerup → click
+ *
+ * This matches what R3F's event system expects. The canvas is the event
+ * target because R3F attaches its listeners to the canvas element.
+ */
+declare function dispatchClick(canvas: HTMLCanvasElement, point: ScreenPoint): void;
+/**
+ * Dispatch a hover sequence on the canvas at the given screen point.
+ *
+ * Sequence: pointermove → pointerover → pointerenter
+ *
+ * R3F translates pointermove into onPointerMove/onPointerOver/onPointerEnter
+ * via its internal raycaster. We dispatch the raw DOM events and let R3F
+ * do the rest.
+ */
+declare function dispatchHover(canvas: HTMLCanvasElement, point: ScreenPoint): void;
+/** Options for a drag interaction. */
+interface DragOptions {
+    /** Number of intermediate pointermove steps. Default: 10 */
+    steps?: number;
+    /** Delay between steps in ms (for requestAnimationFrame pacing). Default: 0 */
+    stepDelayMs?: number;
+}
+/**
+ * Dispatch a full drag sequence from `start` to `end` on the canvas.
+ *
+ * Sequence: pointerdown → N × pointermove (interpolated) → pointerup
+ *
+ * Returns a Promise that resolves when the drag is complete.
+ * The async nature allows optional frame-pacing via stepDelayMs.
+ */
+declare function dispatchDrag(canvas: HTMLCanvasElement, start: ScreenPoint, end: ScreenPoint, options?: DragOptions): Promise<void>;
+/**
+ * Dispatch a full double-click sequence on the canvas at the given screen point.
+ *
+ * Sequence: pointerdown → pointerup → click → pointerdown → pointerup → click → dblclick
+ *
+ * R3F translates the `dblclick` DOM event into `onDoubleClick` on the hit object.
+ */
+declare function dispatchDoubleClick(canvas: HTMLCanvasElement, point: ScreenPoint): void;
+/**
+ * Dispatch a right-click / context menu sequence on the canvas.
+ *
+ * Sequence: pointerdown (button=2) → pointerup (button=2) → contextmenu
+ *
+ * R3F translates the `contextmenu` DOM event into `onContextMenu`.
+ */
+declare function dispatchContextMenu(canvas: HTMLCanvasElement, point: ScreenPoint): void;
+/** Options for a wheel dispatch. */
+interface WheelOptions {
+    /** Vertical scroll delta (positive = scroll down). Default: 100 */
+    deltaY?: number;
+    /** Horizontal scroll delta. Default: 0 */
+    deltaX?: number;
+    /** DOM_DELTA_PIXEL (0), DOM_DELTA_LINE (1), or DOM_DELTA_PAGE (2). Default: 0 */
+    deltaMode?: number;
+}
+/**
+ * Dispatch a wheel event on the canvas at the given screen point.
+ *
+ * R3F translates the `wheel` DOM event into `onWheel` on the hit object.
+ */
+declare function dispatchWheel(canvas: HTMLCanvasElement, point: ScreenPoint, options?: WheelOptions): void;
+/**
+ * Dispatch a click on the canvas at a point where no meshes are present.
+ *
+ * R3F fires `onPointerMissed` on all objects that have that handler when
+ * a click lands on empty space. This dispatches a click at a configurable
+ * point (default: top-left corner, which is very unlikely to hit a mesh).
+ *
+ * @param canvas  The canvas element
+ * @param point   Optional specific screen point. Default: { x: 1, y: 1 }
+ */
+declare function dispatchPointerMiss(canvas: HTMLCanvasElement, point?: ScreenPoint): void;
+/**
+ * Dispatch an unhover sequence — moves the pointer off-canvas.
+ * Useful for cleaning up hover state between interactions.
+ */
+declare function dispatchUnhover(canvas: HTMLCanvasElement): void;
+
+/** World-space drag delta. */
+interface WorldDelta {
+    x: number;
+    y: number;
+    z: number;
+}
+/** Screen-space drag delta (CSS pixels). */
+interface ScreenDelta {
+    dx: number;
+    dy: number;
+}
+/** Options for drag3D. */
+interface Drag3DOptions extends DragOptions {
+    /**
+     * If 'world', the delta is interpreted as world units.
+     * If 'screen', the delta is interpreted as CSS pixels.
+     * Default: 'world'
+     */
+    mode?: 'world' | 'screen';
+}
+/** Result of a drag3D operation. */
+interface Drag3DResult {
+    /** Whether the drag was dispatched. */
+    dispatched: true;
+    /** Start screen point. */
+    startPoint: {
+        x: number;
+        y: number;
+    };
+    /** End screen point. */
+    endPoint: {
+        x: number;
+        y: number;
+    };
+    /** Which projection strategy was used for the start point. */
+    strategy: string;
+}
+/**
+ * Programmatically drag a 3D object by its testId or uuid.
+ *
+ * Projects the object to screen space for the start point, then computes
+ * the end point based on the delta (world-space or screen-space), and
+ * dispatches a full drag sequence on the canvas.
+ *
+ * @param idOrUuid  The object's testId or uuid
+ * @param delta     Drag delta (world-space { x, y, z } or screen-space { dx, dy })
+ * @param options   Drag options (steps, delay, mode)
+ * @returns         Drag result with start/end points
+ * @throws          If the object is not found or not visible on screen
+ *
+ * @example
+ * ```typescript
+ * // World-space drag: move 2 units on X axis
+ * window.__R3F_DOM__.drag('chair-primary', { x: 2, y: 0, z: 0 });
+ *
+ * // Screen-space drag: move 100px right, 50px down
+ * drag3D('chair-primary', { dx: 100, dy: 50 }, { mode: 'screen' });
+ * ```
+ */
+declare function drag3D(idOrUuid: string, delta: WorldDelta | ScreenDelta, options?: Drag3DOptions): Promise<Drag3DResult>;
+/**
+ * Compute what world-space displacement a screen-space drag would produce.
+ * Useful for previewing drag effects before committing.
+ */
+declare function previewDragWorldDelta(idOrUuid: string, screenDx: number, screenDy: number): Vector3;
+
+/** Options for wheel3D. */
+interface Wheel3DOptions extends WheelOptions {
+}
+/** Result of a wheel3D operation. */
+interface Wheel3DResult {
+    /** Whether the wheel event was dispatched. */
+    dispatched: true;
+    /** The screen point where the wheel was dispatched. */
+    screenPoint: {
+        x: number;
+        y: number;
+    };
+    /** Which projection strategy was used. */
+    strategy: string;
+}
+/**
+ * Programmatically scroll the wheel over a 3D object by its testId or uuid.
+ *
+ * Projects the object to screen space and dispatches a synthetic WheelEvent
+ * on the canvas. Triggers R3F's `onWheel` handler on the hit object.
+ *
+ * @param idOrUuid  The object's testId or uuid
+ * @param options   Wheel options (deltaY, deltaX, deltaMode)
+ * @returns         Wheel result with screen point info
+ * @throws          If the object is not found or not visible on screen
+ *
+ * @example
+ * ```typescript
+ * // Scroll down 200 units over the chair
+ * wheel3D('chair-primary', { deltaY: 200 });
+ *
+ * // Scroll up
+ * wheel3D('chair-primary', { deltaY: -100 });
+ * ```
+ */
+declare function wheel3D(idOrUuid: string, options?: Wheel3DOptions): Wheel3DResult;
+
+/** Options for pointerMiss3D. */
+interface PointerMiss3DOptions {
+    /**
+     * Specific screen point to click. If not provided, clicks at (1, 1)
+     * which is the top-left corner — very unlikely to hit any mesh.
+     */
+    point?: ScreenPoint;
+}
+/**
+ * Dispatch a click on empty canvas space, triggering `onPointerMissed`.
+ *
+ * R3F fires `onPointerMissed` on all objects that have that handler
+ * when a click doesn't hit any mesh. This is commonly used for
+ * deselection workflows.
+ *
+ * @param options  Optional point to click at
+ *
+ * @example
+ * ```typescript
+ * // Click empty space to deselect
+ * pointerMiss3D();
+ *
+ * // Click at a specific empty spot
+ * pointerMiss3D({ point: { x: 10, y: 10 } });
+ * ```
+ */
+declare function pointerMiss3D(options?: PointerMiss3DOptions): void;
+
+/**
+ * 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 };