mujoco-react 8.11.0 → 9.1.0

package/dist/index.js

@@ -1,4 +1,4 @@
-export { ScenarioLighting, SplatEnvironment, VisualScenarioEffects, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getScenarioBackground, getScenarioCameraPosition, useSplatEnvironment, useVisualScenarioEffects, withSplatEnvironment } from './chunk-SEWQULWO.js';
+export { ScenarioLighting, SplatEnvironment, VisualScenarioEffects, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getScenarioBackground, getScenarioCameraPosition, useSplatEnvironment, useVisualScenarioEffects, withSplatEnvironment } from './chunk-33CV6HSV.js';
 import loadMujoco from '@mujoco/mujoco';
 import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, forwardRef, useEffect, useContext, useState, useRef, useCallback, useMemo, useLayoutEffect } from 'react';
@@ -1285,7 +1285,7 @@ function SceneRenderer(props) {
           const model = mjModelRef.current;
           if (model && bodyID < model.nbody && onSelectionRef.current) {
             const name = getName(model, model.name_bodyadr[bodyID]);
-            onSelectionRef.current(bodyID, name);
+            onSelectionRef.current({ bodyId: bodyID, name });
           }
         }
       }
@@ -1294,6 +1294,114 @@ function SceneRenderer(props) {
 }
 var _previousQuat = new THREE11.Quaternion();
 var _currentQuat = new THREE11.Quaternion();
+function isTargetRef(target) {
+  return Boolean(target && typeof target === "object" && "current" in target);
+}
+function resolveCanvasTarget(target) {
+  const resolvedTarget = isTargetRef(target) ? target.current : target;
+  if (!resolvedTarget) {
+    throw new Error("No frame capture target is available.");
+  }
+  if (resolvedTarget instanceof HTMLCanvasElement) {
+    return resolvedTarget;
+  }
+  const canvas = resolvedTarget.querySelector("canvas");
+  if (!canvas) {
+    throw new Error("Frame capture target does not contain a canvas.");
+  }
+  return canvas;
+}
+function waitForNextAnimationFrame() {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
+}
+async function captureFrame(options) {
+  const type = options.type ?? "image/png";
+  const canvas = resolveCanvasTarget(options.target);
+  if (options.waitForAnimationFrame ?? true) {
+    await waitForNextAnimationFrame();
+  }
+  return {
+    canvas,
+    dataUrl: canvas.toDataURL(type, options.quality),
+    type
+  };
+}
+async function captureFrameBlob(options) {
+  const type = options.type ?? "image/png";
+  const canvas = resolveCanvasTarget(options.target);
+  if (options.waitForAnimationFrame ?? true) {
+    await waitForNextAnimationFrame();
+  }
+  const blob = await new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (nextBlob) => {
+        if (nextBlob) {
+          resolve(nextBlob);
+        } else {
+          reject(new Error("Canvas frame capture did not produce a Blob."));
+        }
+      },
+      type,
+      options.quality
+    );
+  });
+  return { canvas, blob, type };
+}
+function useFrameCapture(defaultOptions = {}) {
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+  }, []);
+  const capture = useCallback(
+    async (options = {}) => {
+      setStatus("capturing");
+      setError(null);
+      try {
+        const result = await captureFrame({ ...defaultOptions, ...options });
+        setStatus("captured");
+        return result;
+      } catch (nextError) {
+        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [defaultOptions]
+  );
+  const captureBlob = useCallback(
+    async (options = {}) => {
+      setStatus("capturing");
+      setError(null);
+      try {
+        const result = await captureFrameBlob({
+          ...defaultOptions,
+          ...options
+        });
+        setStatus("captured");
+        return result;
+      } catch (nextError) {
+        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [defaultOptions]
+  );
+  return {
+    status,
+    error,
+    isCapturing: status === "capturing",
+    capture,
+    captureBlob,
+    reset
+  };
+}
 var JOINT_TYPE_NAMES2 = ["free", "ball", "slide", "hinge"];
 var GEOM_TYPE_NAMES = ["plane", "hfield", "sphere", "capsule", "ellipsoid", "cylinder", "box", "mesh"];
 var SENSOR_TYPE_NAMES = {
@@ -1420,7 +1528,7 @@ function useBeforePhysicsStep(callback) {
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
   useEffect(() => {
-    const wrapped = (model, data) => callbackRef.current(model, data);
+    const wrapped = (input) => callbackRef.current(input);
     beforeStepCallbacks.current.add(wrapped);
     return () => {
       beforeStepCallbacks.current.delete(wrapped);
@@ -1432,7 +1540,7 @@ function useAfterPhysicsStep(callback) {
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
   useEffect(() => {
-    const wrapped = (model, data) => callbackRef.current(model, data);
+    const wrapped = (input) => callbackRef.current(input);
     afterStepCallbacks.current.add(wrapped);
     return () => {
       afterStepCallbacks.current.delete(wrapped);
@@ -1576,7 +1684,7 @@ function MujocoSimProvider({
   useEffect(() => {
     if (status === "ready") {
       const api2 = apiRef.current;
-      if (onReady) onReady(api2);
+      if (onReady) onReady({ api: api2 });
       if (externalApiRef) {
         if (typeof externalApiRef === "function") {
           externalApiRef(api2);
@@ -1596,7 +1704,7 @@ function MujocoSimProvider({
       data.qfrc_applied[i] = 0;
     }
     for (const cb of beforeStepCallbacks.current) {
-      cb(model, data);
+      cb({ model, data });
     }
     const numSubsteps = substepsRef.current;
     if (!interpolateRef.current) {
@@ -1647,14 +1755,14 @@ function MujocoSimProvider({
       interpolationStateRef.current.alpha = Math.min(Math.max(physicsAccumulatorRef.current / stepDt, 0), 1);
       interpolationStateRef.current.valid = true;
       if (!stepped) {
-        onStepRef.current?.(data.time);
+        onStepRef.current?.({ time: data.time, model, data });
         return;
       }
     }
     for (const cb of afterStepCallbacks.current) {
-      cb(model, data);
+      cb({ model, data });
     }
-    onStepRef.current?.(data.time);
+    onStepRef.current?.({ time: data.time, model, data });
   }, -1);
   function ensureInterpolationBuffers(model) {
     const state = interpolationStateRef.current;
@@ -1685,7 +1793,7 @@ function MujocoSimProvider({
         }
       }
     }
-    configRef.current.onReset?.(model, data);
+    configRef.current.onReset?.({ model, data });
     mujoco.mj_forward(model, data);
     for (const cb of resetCallbacks.current) {
       cb();
@@ -2145,6 +2253,21 @@ function MujocoSimProvider({
     },
     [gl]
   );
+  const getCanvas = useCallback(() => {
+    return gl.domElement ?? null;
+  }, [gl]);
+  const captureFrameApi = useCallback(
+    (options = {}) => {
+      return captureFrame({ ...options, target: gl.domElement });
+    },
+    [gl]
+  );
+  const captureFrameBlobApi = useCallback(
+    (options = {}) => {
+      return captureFrameBlob({ ...options, target: gl.domElement });
+    },
+    [gl]
+  );
   const project2DTo3D = useCallback(
     (x, y, cameraPos, lookAt) => {
       const virtCam = camera.clone();
@@ -2251,7 +2374,10 @@ function MujocoSimProvider({
       addBody: addBodyApi,
       removeBody: removeBodyApi,
       recompile: recompileApi,
+      getCanvas,
       getCanvasSnapshot,
+      captureFrame: captureFrameApi,
+      captureFrameBlob: captureFrameBlobApi,
       project2DTo3D,
       setBodyMass,
       setGeomFriction,
@@ -2303,7 +2429,10 @@ function MujocoSimProvider({
       addBodyApi,
       removeBodyApi,
       recompileApi,
+      getCanvas,
       getCanvasSnapshot,
+      captureFrameApi,
+      captureFrameBlobApi,
       project2DTo3D,
       setBodyMass,
       setGeomFriction,
@@ -2841,9 +2970,9 @@ var useIkController = createControllerHook(
       }
     }, [config?.siteName, config?.numJoints, config?.joints, config?.actuators, status, mjModelRef, mjDataRef, config]);
     const ikSolveFn = useCallback(
-      (pos, quat, currentQ) => {
+      ({ position, quaternion, currentQ, context }) => {
         if (!config) return null;
-        if (config.ikSolveFn) return config.ikSolveFn(pos, quat, currentQ);
+        if (config.ikSolveFn) return config.ikSolveFn({ position, quaternion, currentQ, context });
         const model = mjModelRef.current;
         const data = mjDataRef.current;
         const controlGroup = controlGroupRef.current;
@@ -2853,8 +2982,8 @@ var useIkController = createControllerHook(
           data,
           siteIdRef.current,
           controlGroup.qposAdr,
-          pos,
-          quat,
+          position,
+          quaternion,
           currentQ,
           { damping: config.damping, maxIterations: config.maxIterations }
         );
@@ -2883,7 +3012,7 @@ var useIkController = createControllerHook(
       target.quaternion.slerpQuaternions(ga.startRot, ga.endRot, ease);
       if (t >= 1) ga.active = false;
     });
-    useBeforePhysicsStep((model, data) => {
+    useBeforePhysicsStep(({ model, data }) => {
       if (!config || !ikEnabledRef.current) {
         ikCalculatingRef.current = false;
         return;
@@ -2894,12 +3023,21 @@ var useIkController = createControllerHook(
       const controlGroup = controlGroupRef.current;
       if (!controlGroup) return;
       const currentQ = Array.from(controlGroup.readQpos(data));
-      const solution = config.ikSolveFn ? config.ikSolveFn(target.position, target.quaternion, currentQ, {
-        model,
-        data,
-        siteId: siteIdRef.current,
-        controlGroup
-      }) : ikSolveFnRef.current(target.position, target.quaternion, currentQ);
+      const solution = config.ikSolveFn ? config.ikSolveFn({
+        position: target.position,
+        quaternion: target.quaternion,
+        currentQ,
+        context: {
+          model,
+          data,
+          siteId: siteIdRef.current,
+          controlGroup
+        }
+      }) : ikSolveFnRef.current({
+        position: target.position,
+        quaternion: target.quaternion,
+        currentQ
+      });
       if (solution) {
         controlGroup.writeCtrl(data, solution);
       }
@@ -2938,8 +3076,8 @@ var useIkController = createControllerHook(
       if (data && target) syncGizmoToSite(data, siteIdRef.current, target);
     }, [mjDataRef]);
     const solveIK = useCallback(
-      (pos, quat, currentQ) => {
-        return ikSolveFnRef.current(pos, quat, currentQ);
+      (input) => {
+        return ikSolveFnRef.current(input);
       },
       []
     );
@@ -3153,7 +3291,7 @@ function IkGizmo({ controller, siteName, scale = 0.18, onDrag }) {
       onDrag: (_l, _dl, world) => {
         world.decompose(_pos, _quat, _scale);
         if (onDrag) {
-          onDrag(_pos.clone(), _quat.clone());
+          onDrag({ position: _pos.clone(), quaternion: _quat.clone() });
         } else {
           const target = ikTargetRef.current;
           if (target) {
@@ -3327,7 +3465,7 @@ function DragInteraction({
       window.removeEventListener("pointercancel", onPointerUp);
     };
   }, [gl, camera, scene, controls, mjDataRef]);
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (!draggingRef.current || bodyIdRef.current <= 0) return;
     const bid = bodyIdRef.current;
     const mujoco = mujocoRef.current;
@@ -4118,7 +4256,7 @@ function useContacts(bodyName, callback) {
     bodyIdRef.current = findBodyByName(model, bodyName);
     bodyResolvedRef.current = true;
   }, [bodyName, status, mjModelRef]);
-  useAfterPhysicsStep((model, data) => {
+  useAfterPhysicsStep(({ model, data }) => {
     if (bodyName && !bodyResolvedRef.current) {
       bodyIdRef.current = findBodyByName(model, bodyName);
       bodyResolvedRef.current = true;
@@ -4224,7 +4362,7 @@ function useTrajectoryPlayer(trajectory, options = {}) {
   const setState = useCallback((next) => {
     if (stateRef.current === next) return;
     stateRef.current = next;
-    optionsRef.current.onStateChange?.(next);
+    optionsRef.current.onStateChange?.({ state: next });
   }, []);
   const play = useCallback(() => {
     const traj = trajectoryRef.current;
@@ -4306,7 +4444,7 @@ function useTrajectoryPlayer(trajectory, options = {}) {
       }
     }
   });
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (stateRef.current !== "playing") return;
     if ((optionsRef.current.mode ?? "kinematic") !== "physics") return;
     const traj = trajectoryRef.current;
@@ -4391,7 +4529,10 @@ function TrajectoryPlayer({
     const currentFrame = player.frame;
     if (currentFrame !== lastReportedFrameRef.current && player.playing) {
       lastReportedFrameRef.current = currentFrame;
-      onFrameRef.current(currentFrame);
+      onFrameRef.current({
+        frameIndex: currentFrame,
+        frame: trajectory[currentFrame]
+      });
     }
   });
   return null;
@@ -4465,7 +4606,7 @@ function useSitePosition(siteName) {
 
 // src/hooks/useGravityCompensation.ts
 function useGravityCompensation(enabled = true) {
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (!enabled) return;
     for (let i = 0; i < model.nv; i++) {
       data.qfrc_applied[i] += data.qfrc_bias[i];
@@ -4492,7 +4633,7 @@ function useSensor(name) {
     }
     sensorIdRef.current = -1;
   }, [name, status, mjModelRef]);
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     if (sensorIdRef.current < 0) return;
     const adr = sensorAdrRef.current;
     const dim = sensorDimRef.current;
@@ -4589,7 +4730,7 @@ function useJointState(name) {
     }
     jointIdRef.current = -1;
   }, [name, status, mjModelRef]);
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     if (jointIdRef.current < 0) return;
     const qa = qposAdrRef.current;
     const da = dofAdrRef.current;
@@ -4619,7 +4760,7 @@ function useBodyState(name) {
     if (!model || status !== "ready") return;
     bodyIdRef.current = findBodyByName(model, name);
   }, [name, status, mjModelRef]);
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     const bid = bodyIdRef.current;
     if (bid < 0) return;
     const i3 = bid * 3;
@@ -4715,7 +4856,7 @@ function useKeyboardTeleop(config) {
       window.removeEventListener("keyup", onKeyUp);
     };
   }, []);
-  useBeforePhysicsStep((_model, data) => {
+  useBeforePhysicsStep(({ data }) => {
     if (!enabledRef.current) return;
     const bindings = bindingsRef.current;
     const cache = actuatorCacheRef.current;
@@ -4743,7 +4884,7 @@ function usePolicy(config) {
   const configRef = useRef(config);
   configRef.current = config;
   isRunningRef.current = config.enabled ?? isRunningRef.current;
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (!isRunningRef.current) return;
     const cfg = configRef.current;
     model.opt?.timestep ?? 2e-3;
@@ -4800,7 +4941,7 @@ function useTrajectoryRecorder(options = {}) {
   const recordingRef = useRef(false);
   const framesRef = useRef([]);
   const fields = options.fields ?? ["qpos"];
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     if (!recordingRef.current) return;
     const frame = {
       time: data.time,
@@ -4889,7 +5030,7 @@ function useGamepad(config) {
       buttonCacheRef.current.set(Number(idx), findActuatorByName(model, name));
     }
   }, [config.axes, config.buttons, status, mjModelRef]);
-  useBeforePhysicsStep((_model, data) => {
+  useBeforePhysicsStep(({ data }) => {
     const cfg = configRef.current;
     if (cfg.enabled === false) return;
     const gamepads = navigator.getGamepads?.();
@@ -4967,120 +5108,12 @@ function useVideoRecorder(options = {}) {
     }
   };
 }
-function isTargetRef(target) {
-  return Boolean(target && typeof target === "object" && "current" in target);
-}
-function resolveCanvasTarget(target) {
-  const resolvedTarget = isTargetRef(target) ? target.current : target;
-  if (!resolvedTarget) {
-    throw new Error("No frame capture target is available.");
-  }
-  if (resolvedTarget instanceof HTMLCanvasElement) {
-    return resolvedTarget;
-  }
-  const canvas = resolvedTarget.querySelector("canvas");
-  if (!canvas) {
-    throw new Error("Frame capture target does not contain a canvas.");
-  }
-  return canvas;
-}
-function waitForNextAnimationFrame() {
-  return new Promise((resolve) => {
-    requestAnimationFrame(() => resolve());
-  });
-}
-async function captureFrame(options) {
-  const type = options.type ?? "image/png";
-  const canvas = resolveCanvasTarget(options.target);
-  if (options.waitForAnimationFrame ?? true) {
-    await waitForNextAnimationFrame();
-  }
-  return {
-    canvas,
-    dataUrl: canvas.toDataURL(type, options.quality),
-    type
-  };
-}
-async function captureFrameBlob(options) {
-  const type = options.type ?? "image/png";
-  const canvas = resolveCanvasTarget(options.target);
-  if (options.waitForAnimationFrame ?? true) {
-    await waitForNextAnimationFrame();
-  }
-  const blob = await new Promise((resolve, reject) => {
-    canvas.toBlob(
-      (nextBlob) => {
-        if (nextBlob) {
-          resolve(nextBlob);
-        } else {
-          reject(new Error("Canvas frame capture did not produce a Blob."));
-        }
-      },
-      type,
-      options.quality
-    );
-  });
-  return { canvas, blob, type };
-}
-function useFrameCapture(defaultOptions = {}) {
-  const [status, setStatus] = useState("idle");
-  const [error, setError] = useState(null);
-  const reset = useCallback(() => {
-    setStatus("idle");
-    setError(null);
-  }, []);
-  const capture = useCallback(
-    async (options = {}) => {
-      setStatus("capturing");
-      setError(null);
-      try {
-        const result = await captureFrame({ ...defaultOptions, ...options });
-        setStatus("captured");
-        return result;
-      } catch (nextError) {
-        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
-        setError(error2);
-        setStatus("error");
-        throw error2;
-      }
-    },
-    [defaultOptions]
-  );
-  const captureBlob = useCallback(
-    async (options = {}) => {
-      setStatus("capturing");
-      setError(null);
-      try {
-        const result = await captureFrameBlob({
-          ...defaultOptions,
-          ...options
-        });
-        setStatus("captured");
-        return result;
-      } catch (nextError) {
-        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
-        setError(error2);
-        setStatus("error");
-        throw error2;
-      }
-    },
-    [defaultOptions]
-  );
-  return {
-    status,
-    error,
-    isCapturing: status === "capturing",
-    capture,
-    captureBlob,
-    reset
-  };
-}
 function useCtrlNoise(config = {}) {
   const { mjModelRef } = useMujocoContext();
   const configRef = useRef(config);
   configRef.current = config;
   const noiseRef = useRef(null);
-  useBeforePhysicsStep((_model, data) => {
+  useBeforePhysicsStep(({ data }) => {
     const cfg = configRef.current;
     if (cfg.enabled === false) return;
     const rate = cfg.rate ?? 0.01;
@@ -5227,6 +5260,12 @@ function useCameraAnimation() {
  * @license
  * SPDX-License-Identifier: Apache-2.0
 */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useFrameCapture — still-frame capture for canvas-backed MuJoCo/R3F scenes.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -5360,12 +5399,6 @@ function useCameraAnimation() {
  *
  * useVideoRecorder — canvas video recording hook (spec 13.3)
  */
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- *
- * useFrameCapture — still-frame capture for canvas-backed MuJoCo/R3F scenes.
- */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0