@react-three-dom/core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -2,6 +2,27 @@ import { Object3D, Camera, WebGLRenderer, Vector3 } from 'three';
 
 declare const version = "0.1.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 */
     uuid: string;
@@ -96,6 +117,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,6 +145,19 @@ 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 */
@@ -122,6 +166,14 @@ interface R3FDOM {
     getByName(name: string): ObjectMetadata[];
     /** 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 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) */
@@ -134,12 +186,12 @@ interface R3FDOM {
     contextMenu(idOrUuid: string): void;
     /** Deterministic hover on a 3D object */
     hover(idOrUuid: string): void;
-    /** Deterministic drag on a 3D object */
+    /** 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,10 +199,25 @@ 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;
     /** Library version */
@@ -159,6 +226,8 @@ interface R3FDOM {
 declare global {
     interface Window {
         __R3F_DOM__?: R3FDOM;
+        /** Set to true to enable debug logging from @react-three-dom/core */
+        __R3F_DOM_DEBUG__?: boolean;
     }
 }
 
@@ -179,6 +248,9 @@ declare class ObjectStore {
     register(obj: Object3D): ObjectMetadata;
     /**
      * Register an entire subtree (object + all descendants).
+     * Individual objects that fail to register are skipped (logged when debug
+     * is enabled) so that one bad object doesn't prevent the rest from being
+     * tracked.
      */
     registerTree(root: Object3D): void;
     /**
@@ -192,6 +264,8 @@ declare class ObjectStore {
     /**
      * Refresh Tier 1 metadata from the live Three.js object.
      * Returns true if any values changed.
+     * Returns false (no change) if extracting metadata throws so that the
+     * previous metadata is preserved.
      */
     update(obj: Object3D): boolean;
     /**
@@ -206,6 +280,32 @@ declare class ObjectStore {
     getByUuid(uuid: string): ObjectMetadata | null;
     /** Get metadata by name (returns array since names aren't unique). O(1). */
     getByName(name: string): ObjectMetadata[];
+    /**
+     * 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 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. */
@@ -565,12 +665,14 @@ interface ThreeDomProps {
     initialDepth?: number;
     /** Disable all sync. Default: true */
     enabled?: boolean;
+    /** Enable debug logging to browser console. Default: false */
+    debug?: 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;
+declare function ThreeDom({ root, batchSize, timeBudgetMs, maxDomNodes, initialDepth, enabled, debug, }?: ThreeDomProps): null;
 
 /**
  * Patch Object3D.prototype.add and Object3D.prototype.remove to intercept
@@ -1045,10 +1147,176 @@ 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[];
+
 /**
  * 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 CanvasSize, type Click3DOptions, type Click3DResult, DomMirror, type Drag3DOptions, type Drag3DResult, type DragOptions, type DrawPathOptions, type DrawPathResult, type DrawPoint, type GeometryInspection, Highlighter, type HighlighterOptions, type Hover3DOptions, type Hover3DResult, MANAGED_ATTRIBUTES, type MaterialInspection, type ObjectInspection, type ObjectMetadata, ObjectStore, type PointerMiss3DOptions, type ProjectionResult, type R3FDOM, type RaycastResult, type SceneSnapshot, type ScreenDelta, type ScreenPoint, type SelectionListener, SelectionManager, type SnapshotNode, type StoreEvent, type StoreEventType, type StoreListener, TAG_MAP, ThreeDom, type ThreeDomProps, ThreeElement, type ThreeTagName, type Wheel3DOptions, type Wheel3DResult, type WheelOptions, type WorldDelta, applyAttributes, circlePath, click3D, computeAttributes, contextMenu3D, createFlatSnapshot, createSnapshot, curvePath, dispatchClick, dispatchContextMenu, dispatchDoubleClick, dispatchDrag, dispatchHover, dispatchPointerMiss, dispatchUnhover, dispatchWheel, doubleClick3D, drag3D, drawPath, enableDebug, ensureCustomElements, getHighlighter, getMirror, getSelectionManager, getStore, getTagForType, hover3D, isDebugEnabled, isInFrustum, isPatched, linePath, patchObject3D, pointerMiss3D, previewDragWorldDelta, projectAllSamplePoints, projectToScreen, r3fLog, rectPath, resolveObject, restoreObject3D, screenDeltaToWorld, unhover3D, verifyRaycastHit, verifyRaycastHitMultiPoint, version, wheel3D };