mujoco-react 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1080 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CanvasProps } from '@react-three/fiber';
+import * as THREE from 'three';
+import * as react from 'react';
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Minimal interface for MuJoCo Model to avoid 'any'.
+ */
+interface MujocoModel {
+    nbody: number;
+    ngeom: number;
+    nsite: number;
+    nu: number;
+    njnt: number;
+    nq: number;
+    nv: number;
+    nkey: number;
+    nsensor: number;
+    nsensordata: number;
+    nlight: number;
+    ntendon: number;
+    nflex: number;
+    nmesh: number;
+    nmat: number;
+    names: Int8Array;
+    name_bodyadr: Int32Array;
+    name_jntadr: Int32Array;
+    name_geomadr: Int32Array;
+    name_siteadr: Int32Array;
+    name_actuatoradr: Int32Array;
+    name_keyadr: Int32Array;
+    name_sensoradr: Int32Array;
+    name_tendonadr: Int32Array;
+    body_mass: Float64Array;
+    body_parentid: Int32Array;
+    body_jntnum: Int32Array;
+    body_jntadr: Int32Array;
+    body_pos: Float64Array;
+    body_quat: Float64Array;
+    body_geomnum: Int32Array;
+    body_geomadr: Int32Array;
+    body_inertia: Float64Array;
+    jnt_qposadr: Int32Array;
+    jnt_dofadr: Int32Array;
+    jnt_type: Int32Array;
+    jnt_range: Float64Array;
+    jnt_bodyid: Int32Array;
+    jnt_limited: Uint8Array;
+    geom_group: Int32Array;
+    geom_type: Int32Array;
+    geom_size: Float64Array;
+    geom_pos: Float64Array;
+    geom_quat: Float64Array;
+    geom_matid: Int32Array;
+    geom_rgba: Float32Array;
+    geom_dataid: Int32Array;
+    geom_bodyid: Int32Array;
+    geom_contype: Int32Array;
+    geom_conaffinity: Int32Array;
+    geom_friction: Float64Array;
+    mat_rgba: Float32Array;
+    mesh_vertadr: Int32Array;
+    mesh_vertnum: Int32Array;
+    mesh_faceadr: Int32Array;
+    mesh_facenum: Int32Array;
+    mesh_vert: Float32Array;
+    mesh_face: Int32Array;
+    mesh_normal: Float32Array;
+    site_bodyid: Int32Array;
+    actuator_trnid: Int32Array;
+    actuator_ctrlrange: Float64Array;
+    actuator_trntype: Int32Array;
+    actuator_gainprm: Float64Array;
+    actuator_biasprm: Float64Array;
+    sensor_type: Int32Array;
+    sensor_dim: Int32Array;
+    sensor_adr: Int32Array;
+    sensor_objtype: Int32Array;
+    sensor_objid: Int32Array;
+    key_qpos: Float64Array;
+    key_ctrl: Float64Array;
+    key_time: Float64Array;
+    key_qvel: Float64Array;
+    light_pos: Float64Array;
+    light_dir: Float64Array;
+    light_diffuse: Float32Array;
+    light_specular: Float32Array;
+    light_type: Int32Array;
+    light_active: Uint8Array;
+    light_castshadow: Uint8Array;
+    light_attenuation: Float32Array;
+    light_cutoff: Float32Array;
+    light_exponent: Float32Array;
+    light_intensity: Float32Array;
+    ten_wrapadr: Int32Array;
+    ten_wrapnum: Int32Array;
+    ten_range: Float64Array;
+    ten_rgba: Float32Array;
+    ten_width: Float64Array;
+    flex_vertadr: Int32Array;
+    flex_vertnum: Int32Array;
+    flex_faceadr: Int32Array;
+    flex_facenum: Int32Array;
+    flex_face: Int32Array;
+    flex_rgba: Float32Array;
+    opt: {
+        timestep: number;
+        gravity: Float64Array;
+        integrator: number;
+        [key: string]: unknown;
+    };
+    delete: () => void;
+    [key: string]: unknown;
+}
+/**
+ * Minimal interface for MuJoCo Data to avoid 'any'.
+ */
+interface MujocoData {
+    time: number;
+    qpos: Float64Array;
+    qvel: Float64Array;
+    ctrl: Float64Array;
+    act: Float64Array;
+    xpos: Float64Array;
+    xquat: Float64Array;
+    xfrc_applied: Float64Array;
+    qfrc_applied: Float64Array;
+    qfrc_bias: Float64Array;
+    site_xpos: Float64Array;
+    site_xmat: Float64Array;
+    sensordata: Float64Array;
+    ncon: number;
+    contact: unknown;
+    cvel: Float64Array;
+    cfrc_ext: Float64Array;
+    ten_length: Float64Array;
+    wrap_xpos: Float64Array;
+    ten_wrapadr: Int32Array;
+    flexvert_xpos: Float64Array;
+    geom_xpos: Float64Array;
+    geom_xmat: Float64Array;
+    delete: () => void;
+    [key: string]: unknown;
+}
+/**
+ * Minimal interface for the MuJoCo WASM Module.
+ */
+interface MujocoModule {
+    MjModel: {
+        loadFromXML: (path: string) => MujocoModel;
+        [key: string]: unknown;
+    };
+    MjData: new (model: MujocoModel) => MujocoData;
+    MjvOption: new () => {
+        delete: () => void;
+        [key: string]: unknown;
+    };
+    mj_forward: (m: MujocoModel, d: MujocoData) => void;
+    mj_step: (m: MujocoModel, d: MujocoData) => void;
+    mj_resetData: (m: MujocoModel, d: MujocoData) => void;
+    mj_step1: (m: MujocoModel, d: MujocoData) => void;
+    mj_step2: (m: MujocoModel, d: MujocoData) => void;
+    mj_applyFT: (model: MujocoModel, data: MujocoData, force: Float64Array, torque: Float64Array, point: Float64Array, bodyId: number, qfrc_target: Float64Array) => void;
+    mj_ray: (model: MujocoModel, data: MujocoData, pnt: Float64Array, vec: Float64Array, geomgroup: Uint8Array | null, flg_static: number, bodyexclude: number, geomid: Int32Array) => number;
+    mj_name2id: (model: MujocoModel, type: number, name: string) => number;
+    mjtObj: Record<string, number>;
+    mjtGeom: Record<string, number | {
+        value: number;
+    }>;
+    mjtJoint: Record<string, number | {
+        value: number;
+    }>;
+    mjtSensor: Record<string, number | {
+        value: number;
+    }>;
+    FS: {
+        writeFile: (path: string, content: string | Uint8Array) => void;
+        readFile: (path: string, opts?: {
+            encoding: string;
+        }) => string | Uint8Array;
+        mkdir: (path: string) => void;
+        unmount: (path: string) => void;
+    };
+    [key: string]: unknown;
+}
+interface SceneObject {
+    name: string;
+    type: 'box' | 'sphere' | 'cylinder';
+    size: [number, number, number];
+    position: [number, number, number];
+    rgba: [number, number, number, number];
+    mass?: number;
+    freejoint?: boolean;
+    friction?: string;
+    solref?: string;
+    solimp?: string;
+    condim?: number;
+}
+interface XmlPatch {
+    target: string;
+    inject?: string;
+    injectAfter?: string;
+    replace?: [string, string];
+}
+interface SceneConfig {
+    robotId: string;
+    sceneFile: string;
+    baseUrl?: string;
+    sceneObjects?: SceneObject[];
+    tcpSiteName?: string;
+    gripperActuatorName?: string;
+    numArmJoints?: number;
+    homeJoints?: number[];
+    xmlPatches?: XmlPatch[];
+    onReset?: (model: MujocoModel, data: MujocoData) => void;
+}
+interface SceneMarker {
+    id: number;
+    position: THREE.Vector3;
+    label: string;
+}
+interface PhysicsConfig {
+    gravity?: [number, number, number];
+    timestep?: number;
+    substeps?: number;
+    paused?: boolean;
+    speed?: number;
+    interpolate?: boolean;
+}
+type IKSolveFn = (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]) => number[] | null;
+type PhysicsStepCallback = (model: MujocoModel, data: MujocoData) => void;
+interface StateSnapshot {
+    time: number;
+    qpos: Float64Array;
+    qvel: Float64Array;
+    ctrl: Float64Array;
+    act: Float64Array;
+    qfrc_applied: Float64Array;
+}
+interface BodyInfo {
+    id: number;
+    name: string;
+    mass: number;
+    parentId: number;
+}
+interface JointInfo {
+    id: number;
+    name: string;
+    type: number;
+    typeName: string;
+    range: [number, number];
+    limited: boolean;
+    bodyId: number;
+    qposAdr: number;
+    dofAdr: number;
+}
+interface GeomInfo {
+    id: number;
+    name: string;
+    type: number;
+    typeName: string;
+    size: [number, number, number];
+    bodyId: number;
+}
+interface SiteInfo {
+    id: number;
+    name: string;
+    bodyId: number;
+}
+interface ActuatorInfo {
+    id: number;
+    name: string;
+    range: [number, number];
+}
+interface SensorInfo {
+    id: number;
+    name: string;
+    type: number;
+    typeName: string;
+    dim: number;
+    adr: number;
+}
+interface ContactInfo {
+    geom1: number;
+    geom1Name: string;
+    geom2: number;
+    geom2Name: string;
+    pos: [number, number, number];
+    depth: number;
+}
+interface RayHit {
+    point: THREE.Vector3;
+    bodyId: number;
+    geomId: number;
+    distance: number;
+}
+interface ModelOptions {
+    timestep: number;
+    gravity: [number, number, number];
+    integrator: number;
+}
+interface TrajectoryFrame {
+    time: number;
+    qpos: Float64Array;
+    qvel?: Float64Array;
+    ctrl?: Float64Array;
+    sensordata?: Float64Array;
+}
+interface TrajectoryData {
+    frames: TrajectoryFrame[];
+    fps: number;
+}
+interface KeyBinding {
+    actuator: string;
+    delta?: number;
+    toggle?: [number, number];
+    set?: number;
+}
+interface KeyboardTeleopConfig {
+    bindings: Record<string, KeyBinding>;
+    enabled?: boolean;
+}
+interface PolicyConfig {
+    frequency: number;
+    onObservation: (model: MujocoModel, data: MujocoData) => Float32Array | Float64Array | number[];
+    onAction: (action: Float32Array | Float64Array | number[], model: MujocoModel, data: MujocoData) => void;
+}
+interface DebugProps {
+    showGeoms?: boolean;
+    showSites?: boolean;
+    showJoints?: boolean;
+    showContacts?: boolean;
+    showCOM?: boolean;
+    showInertia?: boolean;
+    showTendons?: boolean;
+}
+interface IkGizmoProps {
+    siteName?: string;
+    scale?: number;
+    onDrag?: (position: THREE.Vector3, quaternion: THREE.Quaternion) => void;
+}
+interface DragInteractionProps {
+    stiffness?: number;
+    showArrow?: boolean;
+}
+interface SceneLightsProps {
+    /** Override intensity for all MJCF lights. Default: 1.0. */
+    intensity?: number;
+}
+interface TrajectoryPlayerProps {
+    trajectory: number[][];
+    fps?: number;
+    loop?: boolean;
+    playing?: boolean;
+    onFrame?: (frameIdx: number) => void;
+}
+interface SelectionHighlightProps {
+    bodyId: number | null;
+    color?: string;
+    emissiveIntensity?: number;
+}
+interface ContactListenerProps {
+    body: string;
+    onContactEnter?: (info: ContactInfo) => void;
+    onContactExit?: (info: ContactInfo) => void;
+}
+interface MujocoSimAPI {
+    readonly status: 'loading' | 'ready' | 'error';
+    readonly config: SceneConfig;
+    reset(): void;
+    setSpeed(multiplier: number): void;
+    togglePause(): boolean;
+    setPaused(paused: boolean): void;
+    step(n?: number): void;
+    getTime(): number;
+    getTimestep(): number;
+    applyKeyframe(nameOrIndex: string | number): void;
+    saveState(): StateSnapshot;
+    restoreState(snapshot: StateSnapshot): void;
+    setQpos(values: Float64Array | number[]): void;
+    setQvel(values: Float64Array | number[]): void;
+    getQpos(): Float64Array;
+    getQvel(): Float64Array;
+    setCtrl(nameOrValues: string | Record<string, number>, value?: number): void;
+    getCtrl(): Float64Array;
+    applyForce(bodyName: string, force: THREE.Vector3, point?: THREE.Vector3): void;
+    applyTorque(bodyName: string, torque: THREE.Vector3): void;
+    setExternalForce(bodyName: string, force: THREE.Vector3, torque: THREE.Vector3): void;
+    applyGeneralizedForce(values: Float64Array | number[]): void;
+    getSensorData(name: string): Float64Array | null;
+    getContacts(): ContactInfo[];
+    getBodies(): BodyInfo[];
+    getJoints(): JointInfo[];
+    getGeoms(): GeomInfo[];
+    getSites(): SiteInfo[];
+    getActuators(): ActuatorInfo[];
+    getSensors(): SensorInfo[];
+    getModelOption(): ModelOptions;
+    setGravity(g: [number, number, number]): void;
+    setTimestep(dt: number): void;
+    raycast(origin: THREE.Vector3, direction: THREE.Vector3, maxDist?: number): RayHit | null;
+    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;
+        bodyId: number;
+        geomId: number;
+    } | null;
+    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>;
+}
+type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
+    config: SceneConfig;
+    onReady?: (api: MujocoSimAPI) => void;
+    onError?: (error: Error) => void;
+    onStep?: (time: number) => void;
+    onSelection?: (bodyId: number, name: string) => void;
+    gravity?: [number, number, number];
+    timestep?: number;
+    substeps?: number;
+    paused?: boolean;
+    speed?: number;
+    interpolate?: boolean;
+    gravityCompensation?: boolean;
+    mjcfLights?: boolean;
+};
+interface SitePositionResult {
+    position: React.RefObject<THREE.Vector3>;
+    quaternion: React.RefObject<THREE.Quaternion>;
+}
+interface MujocoContextValue {
+    mujoco: MujocoModule | null;
+    status: 'loading' | 'ready' | 'error';
+    error: string | null;
+}
+interface SensorResult {
+    value: React.RefObject<Float64Array>;
+    size: number;
+}
+interface BodyStateResult {
+    position: React.RefObject<THREE.Vector3>;
+    quaternion: React.RefObject<THREE.Quaternion>;
+    linearVelocity: React.RefObject<THREE.Vector3>;
+    angularVelocity: React.RefObject<THREE.Vector3>;
+}
+interface JointStateResult {
+    position: React.RefObject<number | Float64Array>;
+    velocity: React.RefObject<number | Float64Array>;
+}
+
+/**
+ * Hook to access the MuJoCo WASM module.
+ */
+declare function useMujoco(): MujocoContextValue;
+interface MujocoProviderProps {
+    wasmUrl?: string;
+    children: React.ReactNode;
+    onError?: (error: Error) => void;
+}
+/**
+ * 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;
+
+/**
+ * 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).
+ */
+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;
+}
+
+interface MujocoSimContextValue {
+    api: MujocoSimAPI;
+    mjModelRef: React.RefObject<MujocoModel | null>;
+    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>>;
+    status: 'loading' | 'ready' | 'error';
+}
+declare function useMujocoSim(): MujocoSimContextValue;
+declare function useBeforePhysicsStep(callback: PhysicsStepCallback): void;
+declare function useAfterPhysicsStep(callback: PhysicsStepCallback): void;
+interface MujocoSimProviderProps {
+    mujoco: MujocoModule;
+    config: SceneConfig;
+    onReady?: (api: MujocoSimAPI) => void;
+    onError?: (error: Error) => void;
+    onStep?: (time: number) => void;
+    onSelection?: (bodyId: number, name: string) => void;
+    gravity?: [number, number, number];
+    timestep?: number;
+    substeps?: number;
+    paused?: boolean;
+    speed?: number;
+    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;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Reads a null-terminated C string from MuJoCo's WASM memory.
+ */
+declare function getName(mjModel: MujocoModel, address: number): string;
+/**
+ * Find a site by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findSiteByName(mjModel: MujocoModel, name: string): number;
+/**
+ * Find an actuator by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findActuatorByName(mjModel: MujocoModel, name: string): number;
+/**
+ * Find a keyframe by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findKeyframeByName(mjModel: MujocoModel, name: string): number;
+/**
+ * Find a body by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findBodyByName(mjModel: MujocoModel, name: string): number;
+/**
+ * Find a joint by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findJointByName(mjModel: MujocoModel, name: string): number;
+/**
+ * Find a geom by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findGeomByName(mjModel: MujocoModel, name: string): number;
+/**
+ * Find a sensor by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findSensorByName(mjModel: MujocoModel, name: string): number;
+/**
+ * Find a tendon by name in the MuJoCo model. Returns -1 if not found.
+ */
+declare function findTendonByName(mjModel: MujocoModel, name: string): number;
+interface LoadResult {
+    mjModel: MujocoModel;
+    mjData: MujocoData;
+    siteId: number;
+    gripperId: number;
+}
+/**
+ * Config-driven scene loader — replaces the old RobotLoader + patchSingleRobot approach.
+ */
+declare function loadScene(mujoco: MujocoModule, config: SceneConfig, onProgress?: (msg: string) => void): Promise<LoadResult>;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * SceneRenderer — creates and syncs MuJoCo body meshes every frame.
+ * Replaces RenderSystem.initScene() + RenderSystem.update() body loop.
+ */
+declare function SceneRenderer(): react_jsx_runtime.JSX.Element;
+
+/**
+ * IkGizmo — drei PivotControls that tracks a MuJoCo site.
+ *
+ * Props:
+ * - `siteName` — MuJoCo site to track. Defaults to `SceneConfig.tcpSiteName`.
+ * - `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 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;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * ContactMarkers — instanced sphere visualization of MuJoCo contacts (spec 6.2)
+ *
+ * Fixed from original: reads data.ncon first, accesses contact via .get(i),
+ * limits to maxContacts to avoid WASM heap OOM.
+ */
+interface ContactMarkersProps {
+    /** Maximum contacts to render. Default: 100. */
+    maxContacts?: number;
+    /** Sphere radius. Default: 0.005. */
+    radius?: number;
+    /** Color. Default: '#4f46e5'. */
+    color?: string;
+    /** Show markers. Default: true. */
+    visible?: boolean;
+}
+declare function ContactMarkers({ maxContacts, radius, color, visible, }?: ContactMarkersProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * DragInteraction — Ctrl/Cmd+click-drag to apply spring forces to MuJoCo bodies.
+ *
+ * Raycasts against scene meshes to identify bodies, then applies a spring
+ * force pulling the grabbed point toward the cursor each physics frame.
+ * Requires Ctrl (or Cmd on macOS) to avoid conflicting with OrbitControls.
+ *
+ * - `stiffness` — Spring constant * body mass. Default: 250.
+ * - `showArrow` — Show arrow from grab point toward cursor. Default: true.
+ *
+ * Forces compose with useGravityCompensation — the provider zeros
+ * qfrc_applied each frame, then all consumers add to it.
+ */
+declare function DragInteraction({ stiffness, showArrow, }: DragInteractionProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * SceneLights — auto-create Three.js lights from MJCF <light> elements (spec 6.3)
+ *
+ * WASM fields used: model.nlight, light_pos, light_dir, light_diffuse,
+ * light_specular, light_active, light_type, light_castshadow,
+ * light_attenuation, light_cutoff, light_exponent, light_intensity
+ *
+ * light_type: 0 = directional, 1 = spot (maps to mjLIGHT_DIRECTIONAL/mjLIGHT_SPOT)
+ * Note: light_directional does NOT exist in WASM — use light_type instead.
+ */
+
+declare function SceneLights({ intensity }: SceneLightsProps): null;
+
+/**
+ * Declarative debug visualization component.
+ * Renders wireframe geoms, site markers, joint axes, contact forces, COM markers, etc.
+ */
+declare function Debug({ showGeoms, showSites, showJoints, showContacts, showCOM, showInertia, showTendons, }: DebugProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * TendonRenderer — render tendons as tube geometries (spec 6.4)
+ *
+ * WASM fields used: model.ntendon, model.ten_wrapadr, model.ten_wrapnum
+ * data.wrap_xpos, data.ten_wrapadr (runtime)
+ *
+ * Note: ten_rgba and ten_width are NOT available in mujoco-js 0.0.7.
+ * Tendons use a default color and width.
+ */
+declare function TendonRenderer(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * FlexRenderer — render deformable flex bodies (spec 6.4)
+ */
+/**
+ * Renders MuJoCo flex (deformable) bodies as dynamic meshes.
+ * Vertices are updated every frame from flexvert_xpos.
+ */
+declare function FlexRenderer(): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * ContactListener — component form of contact events (spec 2.5)
+ */
+
+/**
+ * Component form of useContactEvents.
+ * Fires onContactEnter/onContactExit callbacks when contacts change.
+ */
+declare function ContactListener({ body, onContactEnter, onContactExit, }: ContactListenerProps): null;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * TrajectoryPlayer — component form of trajectory playback (spec 13.2)
+ */
+
+/**
+ * Component wrapper for useTrajectoryPlayer.
+ * Provides declarative trajectory playback controlled via props.
+ */
+declare function TrajectoryPlayer({ trajectory, fps, loop, playing, onFrame, }: TrajectoryPlayerProps): null;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * SelectionHighlight — highlight a selected body with emissive color (spec 6.5)
+ */
+
+/**
+ * Applies emissive highlight to all meshes belonging to a body.
+ * Restores original emissive when bodyId changes or component unmounts.
+ */
+declare function SelectionHighlight({ bodyId, color, emissiveIntensity, }: SelectionHighlightProps): null;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Returns a stable array of actuator metadata for building control UIs.
+ * Computed once when the model loads. Consumer reads/writes data.ctrl[id] directly.
+ */
+declare function useActuators(): ActuatorInfo[];
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Returns reactive refs for a MuJoCo site's world position and orientation.
+ * Refs are updated every frame without triggering React re-renders.
+ */
+declare function useSitePosition(siteName: string): SitePositionResult;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Applies gravity compensation each physics frame by adding qfrc_bias
+ * (gravity + Coriolis forces) to qfrc_applied for each DOF.
+ *
+ * The provider zeros qfrc_applied at the start of each frame, so this
+ * hook (and DragInteraction) compose correctly — both add to a clean slate.
+ */
+declare function useGravityCompensation(enabled?: boolean): void;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useSensor / useSensors — MuJoCo sensor access hooks (spec 2.1)
+ */
+
+/**
+ * Access a single MuJoCo sensor by name. Returns a ref-based value
+ * updated every physics frame without causing React re-renders.
+ */
+declare function useSensor(name: string): SensorResult;
+/**
+ * Enumerate all sensors in the loaded MuJoCo model.
+ * Returns a stable array recomputed only when the model changes.
+ */
+declare function useSensors(): SensorInfo[];
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useJointState — per-joint position/velocity access (spec 2.3)
+ */
+
+/**
+ * Track a MuJoCo joint's position and velocity by name.
+ * Values are updated every physics frame via refs (no re-renders).
+ *
+ * For hinge/slide joints, position/velocity are scalar (stored as Float64Array of length 1).
+ * For ball joints, position is quat (4), velocity is angular vel (3).
+ * For free joints, position is pos+quat (7), velocity is lin+ang vel (6).
+ */
+declare function useJointState(name: string): JointStateResult;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useBodyState — per-body position/velocity tracking (spec 2.2)
+ */
+
+/**
+ * Track a MuJoCo body's world position, quaternion, and velocities.
+ * All values are ref-based — updated every physics frame without re-renders.
+ */
+declare function useBodyState(name: string): BodyStateResult;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useCtrl — clean read/write access to a named actuator's ctrl value (spec 3.1)
+ */
+/**
+ * Access a single actuator's control value by name.
+ *
+ * Returns [currentValue, setValue]:
+ * - `currentValue` is a ref updated every frame (no re-renders).
+ * - `setValue` writes directly to `data.ctrl[actuatorId]`.
+ */
+declare function useCtrl(name: string): [React.RefObject<number>, (value: number) => void];
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useContacts — structured contact query hook (spec 2.4)
+ * useContactEvents — contact enter/exit events (spec 2.5)
+ */
+
+/**
+ * Track contacts for a specific body (or all contacts if no body specified).
+ * Calls the callback every physics frame with current contact list.
+ * Reads `data.ncon` first to avoid allocating for zero contacts.
+ */
+declare function useContacts(bodyName?: string, callback?: (contacts: ContactInfo[]) => void): React.RefObject<ContactInfo[]>;
+/**
+ * Contact enter/exit events for a specific body (spec 2.5).
+ * Tracks which geom pairs are in contact frame-to-frame and fires
+ * onEnter/onExit callbacks on transitions.
+ */
+declare function useContactEvents(bodyName: string, handlers: {
+    onEnter?: (info: ContactInfo) => void;
+    onExit?: (info: ContactInfo) => void;
+}): void;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useKeyboardTeleop — keyboard teleoperation hook (spec 12.1)
+ */
+
+/**
+ * Map keyboard keys to actuator commands.
+ *
+ * Supports three binding modes:
+ * - `delta`: Add delta to actuator value while key is held
+ * - `toggle`: Toggle between two values on key press
+ * - `set`: Set actuator to a fixed value while key is held
+ */
+declare function useKeyboardTeleop(config: KeyboardTeleopConfig): void;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * usePolicy — policy decimation loop hook (spec 10.1)
+ */
+
+/**
+ * Framework-agnostic policy execution hook.
+ *
+ * Manages a decimation loop: calls `onObservation` to build observations
+ * at the specified frequency, then calls `onAction` to apply the policy output.
+ * The actual inference (ONNX, TF.js, custom) is the consumer's responsibility.
+ *
+ * @param config Policy configuration
+ * @returns { step, isRunning } control handles
+ */
+declare function usePolicy(config: PolicyConfig): {
+    readonly isRunning: boolean;
+    start: () => void;
+    stop: () => void;
+    readonly lastObservation: Float64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | number[] | null;
+};
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useTrajectoryPlayer — trajectory playback/scrubbing (spec 13.2)
+ */
+interface TrajectoryPlayerOptions {
+    fps?: number;
+    loop?: boolean;
+}
+/**
+ * Play back a sequence of qpos frames, overriding simulation state.
+ *
+ * When playing, the simulation is effectively paused and qpos is set
+ * from the trajectory each render frame at the specified FPS.
+ */
+declare function useTrajectoryPlayer(trajectory: number[][], options?: TrajectoryPlayerOptions): {
+    play: () => void;
+    pause: () => void;
+    seek: (frameIdx: number) => void;
+    reset: () => void;
+    readonly frame: number;
+    readonly playing: boolean;
+    readonly totalFrames: number;
+};
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useTrajectoryRecorder — trajectory recording hook (spec 13.1)
+ */
+
+interface RecorderOptions {
+    fields?: ('qpos' | 'qvel' | 'ctrl' | 'sensordata')[];
+}
+/**
+ * Record simulation trajectories for analysis, replay, or training data.
+ */
+declare function useTrajectoryRecorder(options?: RecorderOptions): {
+    start: () => void;
+    stop: () => TrajectoryFrame[];
+    downloadJSON: () => void;
+    downloadCSV: () => void;
+    readonly recording: boolean;
+    readonly frameCount: number;
+    readonly frames: TrajectoryFrame[];
+};
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useGamepad — gamepad teleoperation hook (spec 12.2)
+ */
+interface GamepadConfig {
+    /** Map gamepad axis index to actuator name. */
+    axes?: Record<number, string>;
+    /** Map gamepad button index to actuator name. */
+    buttons?: Record<number, string>;
+    /** Axis deadzone. Default: 0.1. */
+    deadzone?: number;
+    /** Scale factor for axis values. Default: 1.0. */
+    scale?: number;
+    /** Gamepad index. Default: 0 (first connected). */
+    gamepadIndex?: number;
+    enabled?: boolean;
+}
+/**
+ * Map gamepad axes and buttons to actuator controls.
+ * Axes map their -1..1 value (scaled) to the actuator.
+ * Buttons map their 0..1 pressed value to the actuator.
+ */
+declare function useGamepad(config: GamepadConfig): void;
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useVideoRecorder — canvas video recording hook (spec 13.3)
+ */
+interface VideoRecorderOptions {
+    fps?: number;
+    mimeType?: string;
+}
+/**
+ * Record the R3F canvas to a video file using MediaRecorder.
+ */
+declare function useVideoRecorder(options?: VideoRecorderOptions): {
+    start: () => void;
+    stop: () => Promise<Blob>;
+    download: (filename?: string) => Promise<void>;
+    readonly recording: boolean;
+};
+
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useCtrlNoise — control noise / perturbation hook (spec 3.2)
+ */
+interface CtrlNoiseConfig {
+    /** Exponential filter rate (0-1). Higher = faster noise changes. Default: 0.01. */
+    rate?: number;
+    /** Standard deviation of Gaussian noise. Default: 0.05. */
+    std?: number;
+    /** Enable/disable. Default: true. */
+    enabled?: boolean;
+}
+/**
+ * Apply Gaussian noise with exponential filtering to all ctrl values.
+ * Useful for robustness testing and domain randomization.
+ *
+ * noise[i] = (1 - rate) * noise[i] + rate * N(0, std)
+ * data.ctrl[i] += noise[i]
+ */
+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 };