mujoco-react 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -8,6 +8,28 @@ import * as react from 'react';
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * A single MuJoCo contact from the WASM module.
+ * Accessed via `data.contact.get(i)`.
+ */
+interface MujocoContact {
+    geom1: number;
+    geom2: number;
+    pos: Float64Array;
+    frame: Float64Array;
+    dist: number;
+}
+/**
+ * WASM contact array — supports indexed access via `.get(i)`.
+ */
+interface MujocoContactArray {
+    get(i: number): MujocoContact | undefined;
+}
+/**
+ * Read a single contact from the WASM contact array.
+ * Returns undefined if the access fails (WASM heap issue, bad index, etc.).
+ */
+declare function getContact(data: MujocoData, i: number): MujocoContact | undefined;
 /**
  * Minimal interface for MuJoCo Model to avoid 'any'.
  */
@@ -45,11 +67,14 @@ interface MujocoModel {
     body_geomnum: Int32Array;
     body_geomadr: Int32Array;
     body_inertia: Float64Array;
+    qpos0: Float64Array;
     jnt_qposadr: Int32Array;
     jnt_dofadr: Int32Array;
     jnt_type: Int32Array;
     jnt_range: Float64Array;
     jnt_bodyid: Int32Array;
+    jnt_pos: Float64Array;
+    jnt_axis: Float64Array;
     jnt_limited: Uint8Array;
     geom_group: Int32Array;
     geom_type: Int32Array;
@@ -135,7 +160,7 @@ interface MujocoData {
     site_xmat: Float64Array;
     sensordata: Float64Array;
     ncon: number;
-    contact: unknown;
+    contact: MujocoContactArray;
     cvel: Float64Array;
     cfrc_ext: Float64Array;
     ten_length: Float64Array;
@@ -212,12 +237,27 @@ interface SceneConfig {
     sceneFile: string;
     baseUrl?: string;
     sceneObjects?: SceneObject[];
-    tcpSiteName?: string;
-    gripperActuatorName?: string;
-    numArmJoints?: number;
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
     onReset?: (model: MujocoModel, data: MujocoData) => void;
+    /** @deprecated Use IkController config.siteName instead. */
+    tcpSiteName?: string;
+    /** @deprecated Use your own gripper control logic instead. */
+    gripperActuatorName?: string;
+    /** @deprecated Use IkController config.numJoints instead. */
+    numArmJoints?: number;
+}
+interface IkConfig {
+    /** MuJoCo site name for IK target. */
+    siteName: string;
+    /** Number of joints to solve for. */
+    numJoints: number;
+    /** Custom IK solver. When omitted, uses built-in Damped Least-Squares solver. */
+    ikSolveFn?: IKSolveFn;
+    /** DLS damping. Default: 0.01. */
+    damping?: number;
+    /** Max solver iterations. Default: 50. */
+    maxIterations?: number;
 }
 interface SceneMarker {
     id: number;
@@ -407,14 +447,6 @@ interface MujocoSimAPI {
     getKeyframeNames(): string[];
     getKeyframeCount(): number;
     loadScene(newConfig: SceneConfig): Promise<void>;
-    setIkEnabled(enabled: boolean): void;
-    moveTarget(pos: THREE.Vector3, duration?: number): void;
-    syncTargetToSite(): void;
-    solveIK(pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]): number[] | null;
-    getGizmoStats(): {
-        pos: THREE.Vector3;
-        rot: THREE.Euler;
-    } | null;
     getCanvasSnapshot(width?: number, height?: number, mimeType?: string): string;
     project2DTo3D(x: number, y: number, cameraPos: THREE.Vector3, lookAt: THREE.Vector3): {
         point: THREE.Vector3;
@@ -424,11 +456,6 @@ interface MujocoSimAPI {
     setBodyMass(name: string, mass: number): void;
     setGeomFriction(name: string, friction: [number, number, number]): void;
     setGeomSize(name: string, size: [number, number, number]): void;
-    getCameraState(): {
-        position: THREE.Vector3;
-        target: THREE.Vector3;
-    };
-    moveCameraTo(position: THREE.Vector3, target: THREE.Vector3, durationMs: number): Promise<void>;
     readonly mjModelRef: React.RefObject<MujocoModel | null>;
     readonly mjDataRef: React.RefObject<MujocoData | null>;
 }
@@ -477,6 +504,8 @@ interface JointStateResult {
 declare function useMujoco(): MujocoContextValue;
 interface MujocoProviderProps {
     wasmUrl?: string;
+    /** Timeout in ms for WASM module load. Default: 30000. */
+    timeout?: number;
     children: React.ReactNode;
     onError?: (error: Error) => void;
 }
@@ -484,50 +513,16 @@ interface MujocoProviderProps {
  * MujocoProvider — WASM / module lifecycle.
  * Loads the MuJoCo WASM module on mount and provides it to children via context.
  */
-declare function MujocoProvider({ wasmUrl, children, onError }: MujocoProviderProps): react_jsx_runtime.JSX.Element;
+declare function MujocoProvider({ wasmUrl, timeout, children, onError }: MujocoProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * MujocoCanvas — thin R3F Canvas wrapper for MuJoCo scenes.
  * Accepts all R3F Canvas props and forwards them through.
  * Supports declarative physics config props (spec 1.1).
+ *
+ * Forward ref exposes MujocoSimAPI (not the canvas element).
  */
-declare const MujocoCanvas: react.ForwardRefExoticComponent<Omit<MujocoCanvasProps, "ref"> & react.RefAttributes<HTMLCanvasElement>>;
-
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- */
-
-interface GenericIKOptions {
-    maxIterations: number;
-    damping: number;
-    tolerance: number;
-    epsilon: number;
-    posWeight: number;
-    rotWeight: number;
-}
-/**
- * Generic Damped Least-Squares IK solver.
- * Uses finite-difference Jacobian via MuJoCo's mj_forward.
- * Works for any MuJoCo model — no robot-specific parameters.
- */
-declare class GenericIK {
-    private mujoco;
-    constructor(mujoco: MujocoModule);
-    /**
-     * Solve IK for a target 6-DOF pose.
-     * @param model       MuJoCo model
-     * @param data        MuJoCo data (qpos will be temporarily modified, then restored)
-     * @param siteId      Index of the end-effector site to control
-     * @param numJoints   Number of arm joints (assumes qpos[0..numJoints-1])
-     * @param targetPos   Target position in world frame
-     * @param targetQuat  Target orientation in world frame
-     * @param currentQ    Current joint angles (length = numJoints)
-     * @param opts        Optional solver parameters
-     * @returns Joint angles array, or null if solver diverged
-     */
-    solve(model: MujocoModel, data: MujocoData, siteId: number, numJoints: number, targetPos: THREE.Vector3, targetQuat: THREE.Quaternion, currentQ: number[], opts?: Partial<GenericIKOptions>): number[] | null;
-}
+declare const MujocoCanvas: react.ForwardRefExoticComponent<Omit<MujocoCanvasProps, "ref"> & react.RefAttributes<MujocoSimAPI>>;
 
 interface MujocoSimContextValue {
     api: MujocoSimAPI;
@@ -535,41 +530,13 @@ interface MujocoSimContextValue {
     mjDataRef: React.RefObject<MujocoData | null>;
     mujocoRef: React.RefObject<MujocoModule>;
     configRef: React.RefObject<SceneConfig>;
-    siteIdRef: React.RefObject<number>;
-    gripperIdRef: React.RefObject<number>;
-    ikEnabledRef: React.RefObject<boolean>;
-    ikCalculatingRef: React.RefObject<boolean>;
     pausedRef: React.RefObject<boolean>;
     speedRef: React.RefObject<number>;
     substepsRef: React.RefObject<number>;
-    ikTargetRef: React.RefObject<THREE.Group>;
-    genericIkRef: React.RefObject<GenericIK>;
-    ikSolveFnRef: React.RefObject<IKSolveFn>;
-    firstIkEnableRef: React.RefObject<boolean>;
-    gizmoAnimRef: React.RefObject<{
-        active: boolean;
-        startPos: THREE.Vector3;
-        endPos: THREE.Vector3;
-        startRot: THREE.Quaternion;
-        endRot: THREE.Quaternion;
-        startTime: number;
-        duration: number;
-    }>;
-    cameraAnimRef: React.RefObject<{
-        active: boolean;
-        startPos: THREE.Vector3;
-        endPos: THREE.Vector3;
-        startRot: THREE.Quaternion;
-        endRot: THREE.Quaternion;
-        startTarget: THREE.Vector3;
-        endTarget: THREE.Vector3;
-        startTime: number;
-        duration: number;
-        resolve: (() => void) | null;
-    }>;
     onSelectionRef: React.RefObject<((bodyId: number, name: string) => void) | undefined>;
     beforeStepCallbacks: React.RefObject<Set<PhysicsStepCallback>>;
     afterStepCallbacks: React.RefObject<Set<PhysicsStepCallback>>;
+    resetCallbacks: React.RefObject<Set<() => void>>;
     status: 'loading' | 'ready' | 'error';
 }
 declare function useMujocoSim(): MujocoSimContextValue;
@@ -578,6 +545,7 @@ declare function useAfterPhysicsStep(callback: PhysicsStepCallback): void;
 interface MujocoSimProviderProps {
     mujoco: MujocoModule;
     config: SceneConfig;
+    apiRef?: React.ForwardedRef<MujocoSimAPI>;
     onReady?: (api: MujocoSimAPI) => void;
     onError?: (error: Error) => void;
     onStep?: (time: number) => void;
@@ -590,7 +558,7 @@ interface MujocoSimProviderProps {
     interpolate?: boolean;
     children: React.ReactNode;
 }
-declare function MujocoSimProvider({ mujoco, config, onReady, onError, onStep, onSelection, gravity, timestep, substeps, paused, speed, interpolate, children, }: MujocoSimProviderProps): react_jsx_runtime.JSX.Element;
+declare function MujocoSimProvider({ mujoco, config, apiRef: externalApiRef, onReady, onError, onStep, onSelection, gravity, timestep, substeps, paused, speed, interpolate, children, }: MujocoSimProviderProps): react_jsx_runtime.JSX.Element;
 
 /**
  * @license
@@ -644,6 +612,81 @@ interface LoadResult {
  */
 declare function loadScene(mujoco: MujocoModule, config: SceneConfig, onProgress?: (msg: string) => void): Promise<LoadResult>;
 
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * createController — typed factory for BYOC (Bring Your Own Controller) plugins.
+ */
+interface ControllerOptions<TConfig> {
+    /** Unique name for this controller (used as displayName). */
+    name: string;
+    /** Default values merged under user-supplied config. */
+    defaultConfig?: Partial<TConfig>;
+}
+type ControllerComponent<TConfig> = React.FC<{
+    config?: Partial<TConfig>;
+    children?: React.ReactNode;
+}> & {
+    controllerName: string;
+    defaultConfig: Partial<TConfig>;
+};
+/**
+ * Factory that produces a typed controller component.
+ *
+ * Controllers are React components that plug into the MuJoCo simulation tree.
+ * Inside `Impl`, use any hooks (`useMujocoSim`, `useBeforePhysicsStep`, etc.)
+ * to interact with the physics engine.
+ *
+ * @example
+ * ```tsx
+ * const MyController = createController<{ speed: number }>(
+ *   { name: 'my-controller', defaultConfig: { speed: 1.0 } },
+ *   function MyControllerImpl({ config }) {
+ *     useBeforePhysicsStep((_model, data) => {
+ *       data.ctrl[0] = config.speed;
+ *     });
+ *     return null;
+ *   },
+ * );
+ *
+ * // Usage:
+ * <MyController config={{ speed: 2.0 }} />
+ * ```
+ */
+declare function createController<TConfig>(options: ControllerOptions<TConfig>, Impl: React.FC<{
+    config: TConfig;
+    children?: React.ReactNode;
+}>): ControllerComponent<TConfig>;
+
+declare const IkController: ControllerComponent<IkConfig>;
+
+interface IkContextValue {
+    ikEnabledRef: React.RefObject<boolean>;
+    ikCalculatingRef: React.RefObject<boolean>;
+    ikTargetRef: React.RefObject<THREE.Group>;
+    siteIdRef: React.RefObject<number>;
+    setIkEnabled(enabled: boolean): void;
+    moveTarget(pos: THREE.Vector3, duration?: number): void;
+    syncTargetToSite(): void;
+    solveIK(pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]): number[] | null;
+    getGizmoStats(): {
+        pos: THREE.Vector3;
+        rot: THREE.Euler;
+    } | null;
+}
+/**
+ * Access the IK controller context.
+ *
+ * - `useIk()` — throws if no `<IkController>` ancestor (use inside `<IkController>`)
+ * - `useIk({ optional: true })` — returns `null` if no ancestor (use in components
+ *   that optionally interact with IK, e.g. keyboard controllers that disable IK)
+ */
+declare function useIk(): IkContextValue;
+declare function useIk(options: {
+    optional: true;
+}): IkContextValue | null;
+
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -657,19 +700,14 @@ declare function SceneRenderer(): react_jsx_runtime.JSX.Element;
 /**
  * IkGizmo — drei PivotControls that tracks a MuJoCo site.
  *
+ * Must be rendered inside an `<IkController>`.
+ *
  * Props:
- * - `siteName` — MuJoCo site to track. Defaults to `SceneConfig.tcpSiteName`.
+ * - `siteName` — MuJoCo site to track. Defaults to the IkController's configured site.
  * - `scale` — Gizmo handle scale. Default: 0.18.
  * - `onDrag` — Custom drag callback `(pos, quat) => void`.
- *   When omitted, dragging enables IK and writes to the provider's IK target.
+ *   When omitted, dragging enables IK and writes to the IK target.
  *   When provided, the consumer handles what happens during drag.
- *
- * Multiple gizmos can be rendered — each tracks its own site.
- * Zero gizmos is fine — programmatic IK control works via the provider API.
- *
- * Uses a tiny invisible mesh as child instead of axesHelper — PivotControls
- * computes an anchor offset from children's bounding box, and axesHelper's
- * (0→0.15) bounds would shift the handles away from the TCP origin.
  */
 declare function IkGizmo({ siteName, scale, onDrag }: IkGizmoProps): react_jsx_runtime.JSX.Element | null;
 
@@ -685,9 +723,9 @@ declare function IkGizmo({ siteName, scale, onDrag }: IkGizmoProps): react_jsx_r
 interface ContactMarkersProps {
     /** Maximum contacts to render. Default: 100. */
     maxContacts?: number;
-    /** Sphere radius. Default: 0.005. */
+    /** Sphere radius. Default: 0.008. */
     radius?: number;
-    /** Color. Default: '#4f46e5'. */
+    /** Color. Default: '#22d3ee'. */
     color?: string;
     /** Show markers. Default: true. */
     visible?: boolean;
@@ -1077,4 +1115,49 @@ interface CtrlNoiseConfig {
  */
 declare function useCtrlNoise(config?: CtrlNoiseConfig): void;
 
-export { type ActuatorInfo, type BodyInfo, type BodyStateResult, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type IKSolveFn, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type KeyBinding, type KeyboardTeleopConfig, type ModelOptions, MujocoCanvas, type MujocoCanvasProps, type MujocoContextValue, type MujocoData, type MujocoModel, type MujocoModule, MujocoProvider, type MujocoSimAPI, MujocoSimProvider, type PhysicsConfig, type PhysicsStepCallback, type PolicyConfig, type RayHit, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, SceneRenderer, SelectionHighlight, type SelectionHighlightProps, type SensorInfo, type SensorResult, type SiteInfo, type SitePositionResult, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyState, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useJointState, useKeyboardTeleop, useMujoco, useMujocoSim, usePolicy, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useSelectionHighlight — hook form of SelectionHighlight (spec 6.5)
+ *
+ * Applies emissive highlight to all meshes belonging to a body.
+ * Restores original emissive when bodyId changes or hook unmounts.
+ */
+declare function useSelectionHighlight(bodyId: number | null, options?: {
+    color?: string;
+    emissiveIntensity?: number;
+}): void;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useSceneLights — hook form of SceneLights (spec 6.3)
+ *
+ * Auto-creates Three.js lights from MJCF <light> elements.
+ */
+declare function useSceneLights(intensity?: number): void;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useCameraAnimation — composable camera animation hook.
+ */
+
+interface CameraAnimationAPI {
+    getCameraState(): {
+        position: THREE.Vector3;
+        target: THREE.Vector3;
+    };
+    moveCameraTo(position: THREE.Vector3, target: THREE.Vector3, durationMs: number): Promise<void>;
+}
+/**
+ * Standalone hook for animated camera transitions.
+ *
+ * Manages its own `useFrame` callback — drop it into any component inside `<Canvas>`.
+ */
+declare function useCameraAnimation(): CameraAnimationAPI;
+
+export { type ActuatorInfo, type BodyInfo, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type IKSolveFn, type IkConfig, type IkContextValue, IkController, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type KeyBinding, type KeyboardTeleopConfig, type ModelOptions, MujocoCanvas, type MujocoCanvasProps, type MujocoContact, type MujocoContactArray, type MujocoContextValue, type MujocoData, type MujocoModel, type MujocoModule, MujocoProvider, type MujocoSimAPI, MujocoSimProvider, type PhysicsConfig, type PhysicsStepCallback, type PolicyConfig, type RayHit, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, SceneRenderer, SelectionHighlight, type SelectionHighlightProps, type SensorInfo, type SensorResult, type SiteInfo, type SitePositionResult, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIk, useJointState, useKeyboardTeleop, useMujoco, useMujocoSim, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };