mujoco-react 8.11.0 → 9.1.0

package/dist/spark.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _sparkjsdev_spark from '@sparkjsdev/spark';
-import { l as SplatEnvironmentProps } from './types-BmneHLBM.js';
+import { n as SplatEnvironmentProps } from './types-C5gTvR7b.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';

package/dist/spark.js

@@ -1,4 +1,4 @@
-import { useSplatEnvironment, SplatEnvironment } from './chunk-SEWQULWO.js';
+import { useSplatEnvironment, SplatEnvironment } from './chunk-33CV6HSV.js';
 import { useThree } from '@react-three/fiber';
 import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import * as THREE from 'three';

package/dist/{types-BmneHLBM.d.ts → types-C5gTvR7b.d.ts}

@@ -327,7 +327,7 @@ interface LoadFromFilesOptions {
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
     sceneObjects?: SceneObject[];
-    onReset?: (model: MujocoModel, data: MujocoData) => void;
+    onReset?: (input: ResetCallbackInput) => void;
 }
 interface SceneConfig {
     /** Base URL for fetching model files. The loader fetches `src + sceneFile` and follows dependencies. */
@@ -347,7 +347,7 @@ interface SceneConfig {
     sceneObjects?: SceneObject[];
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
-    onReset?: (model: MujocoModel, data: MujocoData) => void;
+    onReset?: (input: ResetCallbackInput) => void;
 }
 type ResourceSelector<TInfo, TName extends string = string> = TName | readonly TName[] | RegExp | ((info: TInfo) => boolean);
 interface IkConfig {
@@ -380,7 +380,7 @@ interface IkContextValue {
     setIkEnabled: (enabled: boolean) => void;
     moveTarget: (pos: THREE.Vector3, duration?: number) => void;
     syncTargetToSite: () => void;
-    solveIK: (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]) => number[] | null;
+    solveIK: (input: IkSolveInput) => number[] | null;
     getGizmoStats: () => {
         pos: THREE.Vector3;
         rot: THREE.Euler;
@@ -398,14 +398,38 @@ interface PhysicsConfig {
     paused?: boolean;
     speed?: number;
 }
-type IKSolveFn = (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[], context?: IKSolveContext) => number[] | null;
+type IKSolveFn = (input: IkSolveInput) => number[] | null;
+interface IkSolveInput {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+    currentQ: number[];
+    context?: IKSolveContext;
+}
 interface IKSolveContext {
     model: MujocoModel;
     data: MujocoData;
     siteId: number;
     controlGroup: ControlGroupInfo;
 }
-type PhysicsStepCallback = (model: MujocoModel, data: MujocoData) => void;
+interface PhysicsStepInput {
+    model: MujocoModel;
+    data: MujocoData;
+}
+interface ResetCallbackInput extends PhysicsStepInput {
+}
+interface ReadyCallbackInput {
+    api: MujocoSimAPI;
+}
+interface StepCallbackInput {
+    time: number;
+    model: MujocoModel;
+    data: MujocoData;
+}
+interface SelectionCallbackInput {
+    bodyId: number;
+    name: string;
+}
+type PhysicsStepCallback = (input: PhysicsStepInput) => void;
 interface StateSnapshot {
     time: number;
     qpos: Float64Array;
@@ -606,7 +630,11 @@ interface IkGizmoProps {
     controller: IkContextValue;
     siteName?: string;
     scale?: number;
-    onDrag?: (position: THREE.Vector3, quaternion: THREE.Quaternion) => void;
+    onDrag?: (input: IkGizmoDragInput) => void;
+}
+interface IkGizmoDragInput {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
 }
 interface DragInteractionProps {
     stiffness?: number;
@@ -718,7 +746,11 @@ interface VisualScenarioEffectsProps {
     background?: THREE.ColorRepresentation;
     fogNear?: number;
     fogFar?: number;
-    materialFilter?: (object: THREE.Object3D, material: THREE.Material) => boolean;
+    materialFilter?: (input: VisualScenarioMaterialFilterInput) => boolean;
+}
+interface VisualScenarioMaterialFilterInput {
+    object: THREE.Object3D;
+    material: THREE.Material;
 }
 type TrajectoryInput = TrajectoryFrame[] | number[][];
 interface TrajectoryPlayerProps {
@@ -728,9 +760,16 @@ interface TrajectoryPlayerProps {
     loop?: boolean;
     playing?: boolean;
     mode?: 'kinematic' | 'physics';
-    onFrame?: (frameIdx: number) => void;
+    onFrame?: (input: TrajectoryFrameCallbackInput) => void;
     onComplete?: () => void;
-    onStateChange?: (state: PlaybackState) => void;
+    onStateChange?: (input: TrajectoryStateChangeInput) => void;
+}
+interface TrajectoryFrameCallbackInput {
+    frameIndex: number;
+    frame: TrajectoryFrame | number[] | undefined;
+}
+interface TrajectoryStateChangeInput {
+    state: PlaybackState;
 }
 interface ContactListenerProps {
     body: Bodies;
@@ -798,7 +837,10 @@ interface MujocoSimAPI {
     addBody(body: SceneObject): Promise<void>;
     removeBody(name: Bodies): Promise<void>;
     recompile(patches?: XmlPatch[]): Promise<void>;
+    getCanvas(): HTMLCanvasElement | null;
     getCanvasSnapshot(width?: number, height?: number, mimeType?: string): string;
+    captureFrame(options?: MujocoFrameCaptureOptions): Promise<FrameCaptureResult>;
+    captureFrameBlob(options?: MujocoFrameCaptureOptions): Promise<FrameCaptureBlobResult>;
     project2DTo3D(x: number, y: number, cameraPos: THREE.Vector3, lookAt: THREE.Vector3): {
         point: THREE.Vector3;
         bodyId: number;
@@ -810,14 +852,42 @@ interface MujocoSimAPI {
     readonly mjModelRef: React__default.RefObject<MujocoModel | null>;
     readonly mjDataRef: React__default.RefObject<MujocoData | null>;
 }
+type FrameCaptureStatus = 'idle' | 'capturing' | 'captured' | 'error';
+type FrameCaptureTarget = HTMLCanvasElement | HTMLElement | null | undefined;
+type FrameCaptureTargetRef = React__default.RefObject<HTMLCanvasElement | HTMLElement | null>;
+interface FrameCaptureOptions {
+    target?: FrameCaptureTarget | FrameCaptureTargetRef;
+    type?: string;
+    quality?: number;
+    waitForAnimationFrame?: boolean;
+}
+type MujocoFrameCaptureOptions = Omit<FrameCaptureOptions, 'target'>;
+interface FrameCaptureResult {
+    canvas: HTMLCanvasElement;
+    dataUrl: string;
+    type: string;
+}
+interface FrameCaptureBlobResult {
+    canvas: HTMLCanvasElement;
+    blob: Blob;
+    type: string;
+}
+interface FrameCaptureAPI {
+    status: FrameCaptureStatus;
+    error: Error | null;
+    isCapturing: boolean;
+    capture: (options?: FrameCaptureOptions) => Promise<FrameCaptureResult>;
+    captureBlob: (options?: FrameCaptureOptions) => Promise<FrameCaptureBlobResult>;
+    reset: () => void;
+}
 type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
     config: SceneConfig;
     /** R3F content rendered while the MuJoCo WASM module is still loading. */
     loadingFallback?: ReactNode;
-    onReady?: (api: MujocoSimAPI) => void;
+    onReady?: (input: ReadyCallbackInput) => void;
     onError?: (error: Error) => void;
-    onStep?: (time: number) => void;
-    onSelection?: (bodyId: number, name: string) => void;
+    onStep?: (input: StepCallbackInput) => void;
+    onSelection?: (input: SelectionCallbackInput) => void;
     gravity?: [number, number, number];
     timestep?: number;
     substeps?: number;
@@ -868,4 +938,4 @@ interface JointStateResult {
     velocity: React__default.RefObject<number | Float64Array>;
 }
 
-export { type TrajectoryInput as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type SitePositionResult as E, type Sensors as F, type GeomInfo as G, type SensorHandle as H, type IkConfig as I, type SensorInfo as J, type Joints as K, type JointStateResult as L, type MujocoContextValue as M, type Bodies as N, type ObservationConfig as O, type PhysicsStepCallback as P, type BodyStateResult as Q, type Actuators as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type CtrlHandle as U, type VisualScenarioEffectsProps as V, type ContactInfo as W, type KeyboardTeleopConfig as X, type PolicyConfig as Y, type PolicyVector as Z, type ObservationHandle as _, type MujocoCanvasProps as a, type PlaybackState as a0, type TrajectoryFrame as a1, type BodyInfo as a2, type ControlJointInfo as a3, type Geoms as a4, type IKSolveFn as a5, type JointInfo as a6, type KeyBinding as a7, type Keyframes as a8, type ModelOptions as a9, type SensorResult as aA, type SiteInfo as aB, type SplatAssetConfig as aC, type SplatScenarioConfig as aD, type StateSnapshot as aE, type TrajectoryData as aF, type XmlPatch as aG, getContact as aH, registerRobotResources as aI, type MujocoContact as aa, type MujocoContactArray as ab, type ObservationLayoutItem as ac, type ObservationOutput as ad, type PhysicsConfig as ae, type PolicyActionInput as af, type PolicyInferenceInput as ag, type PolicyObservationInput as ah, type RayHit as ai, type Register as aj, type RegisteredRobotMap as ak, type ResourceSelector as al, RobotActuators as am, RobotBodies as an, RobotGeoms as ao, RobotJoints as ap, RobotKeyframes as aq, type RobotResource as ar, RobotResources as as, RobotSensors as at, RobotSites as au, type Robots as av, type ScenarioCameraConfig as aw, type ScenarioMaterialConfig as ax, type SceneMarker as ay, type SceneObject as az, type MujocoSimAPI as b, type MujocoModule as c, type MujocoModel as d, type MujocoData as e, type ControlGroupSelector as f, type ObservationResult as g, type IkContextValue as h, type IkGizmoProps as i, type SceneLightsProps as j, type ScenarioLightingProps as k, type SplatEnvironmentProps as l, type VisualScenarioConfig as m, type SplatRendererKind as n, type PairedSplatEnvironmentConfig as o, type SplatFormat as p, type SplatCollisionProxyConfig as q, type SplatCollisionPrimitive as r, type ScenarioLightingPreset as s, type SplatEnvironmentMetadataInput as t, type SplatEnvironmentMetadata as u, type SplatSceneInput as v, type DebugProps as w, type ContactListenerProps as x, type ActuatorInfo as y, type Sites as z };
+export { type PolicyConfig as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type ActuatorInfo as E, type Sites as F, type GeomInfo as G, type SitePositionResult as H, type IkConfig as I, type Sensors as J, type SensorHandle as K, type SensorInfo as L, type MujocoContextValue as M, type Joints as N, type ObservationConfig as O, type PhysicsStepCallback as P, type JointStateResult as Q, type ReadyCallbackInput as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type Bodies as U, type VisualScenarioEffectsProps as V, type BodyStateResult as W, type Actuators as X, type CtrlHandle as Y, type ContactInfo as Z, type KeyboardTeleopConfig as _, type MujocoCanvasProps as a, type PolicyVector as a0, type ObservationHandle as a1, type TrajectoryInput as a2, type TrajectoryStateChangeInput as a3, type PlaybackState as a4, type TrajectoryFrame as a5, type FrameCaptureOptions as a6, type FrameCaptureResult as a7, type FrameCaptureBlobResult as a8, type FrameCaptureAPI as a9, type ResetCallbackInput as aA, type ResourceSelector as aB, RobotActuators as aC, RobotBodies as aD, RobotGeoms as aE, RobotJoints as aF, RobotKeyframes as aG, type RobotResource as aH, RobotResources as aI, RobotSensors as aJ, RobotSites as aK, type Robots as aL, type ScenarioCameraConfig as aM, type ScenarioMaterialConfig as aN, type SceneMarker as aO, type SceneObject as aP, type SensorResult as aQ, type SiteInfo as aR, type SplatAssetConfig as aS, type SplatScenarioConfig as aT, type StateSnapshot as aU, type TrajectoryData as aV, type TrajectoryFrameCallbackInput as aW, type VisualScenarioMaterialFilterInput as aX, type XmlPatch as aY, getContact as aZ, registerRobotResources as a_, type BodyInfo as aa, type ControlJointInfo as ab, type FrameCaptureStatus as ac, type FrameCaptureTarget as ad, type FrameCaptureTargetRef as ae, type Geoms as af, type IKSolveFn as ag, type IkGizmoDragInput as ah, type IkSolveInput as ai, type JointInfo as aj, type KeyBinding as ak, type Keyframes as al, type ModelOptions as am, type MujocoContact as an, type MujocoContactArray as ao, type MujocoFrameCaptureOptions as ap, type ObservationLayoutItem as aq, type ObservationOutput as ar, type PhysicsConfig as as, type PhysicsStepInput as at, type PolicyActionInput as au, type PolicyInferenceInput as av, type PolicyObservationInput as aw, type RayHit as ax, type Register as ay, type RegisteredRobotMap as az, type MujocoSimAPI as b, type StepCallbackInput as c, type SelectionCallbackInput as d, type MujocoModule as e, type MujocoModel as f, type MujocoData as g, type ControlGroupSelector as h, type ObservationResult as i, type IkContextValue as j, type IkGizmoProps as k, type SceneLightsProps as l, type ScenarioLightingProps as m, type SplatEnvironmentProps as n, type VisualScenarioConfig as o, type SplatRendererKind as p, type PairedSplatEnvironmentConfig as q, type SplatFormat as r, type SplatCollisionProxyConfig as s, type SplatCollisionPrimitive as t, type ScenarioLightingPreset as u, type SplatEnvironmentMetadataInput as v, type SplatEnvironmentMetadata as w, type SplatSceneInput as x, type DebugProps as y, type ContactListenerProps as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "8.11.0",
+  "version": "9.1.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/DragInteraction.tsx

@@ -168,7 +168,7 @@ export function DragInteraction({
   }, [gl, camera, scene, controls, mjDataRef]);
 
   // Apply spring force each physics frame
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (!draggingRef.current || bodyIdRef.current <= 0) return;
 
     const bid = bodyIdRef.current;

package/src/components/IkGizmo.tsx

@@ -26,7 +26,7 @@ const _scale = new THREE.Vector3(1, 1, 1);
  * - `controller` — IkContextValue from `useIkController()`.
  * - `siteName` — MuJoCo site to track. Defaults to the controller's configured site.
  * - `scale` — Gizmo handle scale. Default: 0.18.
- * - `onDrag` — Custom drag callback `(pos, quat) => void`.
+ * - `onDrag` — Custom drag callback `({ position, quaternion }) => void`.
  *   When omitted, dragging enables IK and writes to the IK target.
  *   When provided, the consumer handles what happens during drag.
  */
@@ -112,7 +112,7 @@ export function IkGizmo({ controller, siteName, scale = 0.18, onDrag }: IkGizmoP
           world.decompose(_pos, _quat, _scale);
           if (onDrag) {
             // Custom: consumer handles the drag
-            onDrag(_pos.clone(), _quat.clone());
+            onDrag({ position: _pos.clone(), quaternion: _quat.clone() });
           } else {
             // Default: write to IK target
             const target = ikTargetRef.current;

package/src/components/SceneRenderer.tsx

@@ -139,7 +139,7 @@ export function SceneRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
           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 });
           }
         }
       }}

package/src/components/TrajectoryPlayer.tsx

@@ -54,7 +54,10 @@ export 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],
+      });
     }
   });
 

package/src/components/VisualScenario.tsx

@@ -490,7 +490,7 @@ function applyScenarioMaterials(
     for (const material of normalizeMaterials(object.material)) {
       const mutable = getMutableScenarioMaterial(material);
       if (!mutable) continue;
-      if (materialFilter && !materialFilter(object, material)) continue;
+      if (materialFilter && !materialFilter({ object, material })) continue;
 
       if (!snapshots.has(material)) {
         snapshots.set(material, {

package/src/core/MujocoPhysics.tsx

@@ -6,19 +6,25 @@
 import { forwardRef, useEffect } from 'react';
 import { useMujocoWasm } from './MujocoProvider';
 import { MujocoSimProvider } from './MujocoSimProvider';
-import type { MujocoSimAPI, SceneConfig } from '../types';
+import type {
+  MujocoSimAPI,
+  ReadyCallbackInput,
+  SceneConfig,
+  SelectionCallbackInput,
+  StepCallbackInput,
+} from '../types';
 
 export interface MujocoPhysicsProps {
   /** Scene/robot configuration. */
   config: SceneConfig;
   /** Fires when model is loaded and API is ready. */
-  onReady?: (api: MujocoSimAPI) => void;
+  onReady?: (input: ReadyCallbackInput) => void;
   /** Fires on scene load failure. */
   onError?: (error: Error) => void;
   /** Called each physics step. */
-  onStep?: (time: number) => void;
+  onStep?: (input: StepCallbackInput) => void;
   /** Called on body double-click selection. */
-  onSelection?: (bodyId: number, name: string) => void;
+  onSelection?: (input: SelectionCallbackInput) => void;
   /** Override model gravity. */
   gravity?: [number, number, number];
   /** Override model.opt.timestep. */

package/src/core/MujocoSimProvider.tsx

@@ -31,13 +31,20 @@ import {
   MujocoSimAPI,
   PhysicsStepCallback,
   RayHit,
+  ReadyCallbackInput,
   SceneConfig,
   SceneObject,
+  SelectionCallbackInput,
   SensorInfo,
   SiteInfo,
   StateSnapshot,
+  StepCallbackInput,
   XmlPatch,
 } from '../types';
+import {
+  captureFrame as captureCanvasFrame,
+  captureFrameBlob as captureCanvasFrameBlob,
+} from '../hooks/useFrameCapture';
 import {
   loadScene,
   createSceneConfigFromFiles,
@@ -117,7 +124,7 @@ export interface MujocoSimContextValue {
   interpolateRef: React.RefObject<boolean>;
   interpolationStateRef: React.RefObject<BodyInterpolationState>;
   onSelectionRef: React.RefObject<
-    ((bodyId: number, name: string) => void) | undefined
+    ((input: SelectionCallbackInput) => void) | undefined
   >;
   beforeStepCallbacks: React.RefObject<Set<PhysicsStepCallback>>;
   afterStepCallbacks: React.RefObject<Set<PhysicsStepCallback>>;
@@ -197,7 +204,7 @@ export function useBeforePhysicsStep(callback: PhysicsStepCallback) {
   callbackRef.current = callback;
 
   useEffect(() => {
-    const wrapped: PhysicsStepCallback = (model, data) => callbackRef.current(model, data);
+    const wrapped: PhysicsStepCallback = (input) => callbackRef.current(input);
     beforeStepCallbacks.current.add(wrapped);
     return () => { beforeStepCallbacks.current.delete(wrapped); };
   }, [beforeStepCallbacks]);
@@ -209,7 +216,7 @@ export function useAfterPhysicsStep(callback: PhysicsStepCallback) {
   callbackRef.current = callback;
 
   useEffect(() => {
-    const wrapped: PhysicsStepCallback = (model, data) => callbackRef.current(model, data);
+    const wrapped: PhysicsStepCallback = (input) => callbackRef.current(input);
     afterStepCallbacks.current.add(wrapped);
     return () => { afterStepCallbacks.current.delete(wrapped); };
   }, [afterStepCallbacks]);
@@ -219,10 +226,10 @@ interface MujocoSimProviderProps {
   mujoco: MujocoModule;
   config: SceneConfig;
   apiRef?: React.ForwardedRef<MujocoSimAPI>;
-  onReady?: (api: MujocoSimAPI) => void;
+  onReady?: (input: ReadyCallbackInput) => void;
   onError?: (error: Error) => void;
-  onStep?: (time: number) => void;
-  onSelection?: (bodyId: number, name: string) => void;
+  onStep?: (input: StepCallbackInput) => void;
+  onSelection?: (input: SelectionCallbackInput) => void;
   // Declarative physics config props
   gravity?: [number, number, number];
   timestep?: number;
@@ -380,7 +387,7 @@ export function MujocoSimProvider({
   useEffect(() => {
     if (status === 'ready') {
       const api = apiRef.current;
-      if (onReady) onReady(api);
+      if (onReady) onReady({ api });
       // Assign the forwarded ref
       if (externalApiRef) {
         if (typeof externalApiRef === 'function') {
@@ -409,7 +416,7 @@ export function MujocoSimProvider({
 
     // Before-step callbacks
     for (const cb of beforeStepCallbacks.current) {
-      cb(model, data);
+      cb({ model, data });
     }
 
     const numSubsteps = substepsRef.current;
@@ -466,17 +473,17 @@ export function MujocoSimProvider({
       interpolationStateRef.current.valid = true;
 
       if (!stepped) {
-        onStepRef.current?.(data.time);
+        onStepRef.current?.({ time: data.time, model, data });
         return;
       }
     }
 
     // After-step callbacks
     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: MujocoModel) {
@@ -515,7 +522,7 @@ export function MujocoSimProvider({
       }
     }
 
-    configRef.current.onReset?.(model, data);
+    configRef.current.onReset?.({ model, data });
     mujoco.mj_forward(model, data);
 
     // Notify composable plugins (e.g. IkController)
@@ -1016,6 +1023,24 @@ export function MujocoSimProvider({
     [gl]
   );
 
+  const getCanvas = useCallback((): HTMLCanvasElement | null => {
+    return gl.domElement ?? null;
+  }, [gl]);
+
+  const captureFrameApi = useCallback(
+    (options = {}) => {
+      return captureCanvasFrame({ ...options, target: gl.domElement });
+    },
+    [gl]
+  );
+
+  const captureFrameBlobApi = useCallback(
+    (options = {}) => {
+      return captureCanvasFrameBlob({ ...options, target: gl.domElement });
+    },
+    [gl]
+  );
+
   const project2DTo3D = useCallback(
     (x: number, y: number, cameraPos: THREE.Vector3, lookAt: THREE.Vector3): { point: THREE.Vector3; bodyId: number; geomId: number } | null => {
       const virtCam = (camera as THREE.PerspectiveCamera).clone();
@@ -1125,7 +1150,10 @@ export function MujocoSimProvider({
       addBody: addBodyApi,
       removeBody: removeBodyApi,
       recompile: recompileApi,
+      getCanvas,
       getCanvasSnapshot,
+      captureFrame: captureFrameApi,
+      captureFrameBlob: captureFrameBlobApi,
       project2DTo3D,
       setBodyMass,
       setGeomFriction,
@@ -1143,7 +1171,8 @@ export function MujocoSimProvider({
       getActuatorsApi, getSensors, getModelOption, setGravity, setTimestepApi,
       raycast, getKeyframeNames, getKeyframeCount, loadSceneApi,
       loadFromFilesApi, addBodyApi, removeBodyApi, recompileApi,
-      getCanvasSnapshot, project2DTo3D,
+      getCanvas, getCanvasSnapshot, captureFrameApi, captureFrameBlobApi,
+      project2DTo3D,
       setBodyMass, setGeomFriction, setGeomSize,
     ]
   );

package/src/core/createController.tsx

@@ -43,7 +43,7 @@ export type ControllerComponent<TConfig> = React.FC<{
  * const MyController = createController<{ speed: number }>(
  *   { name: 'my-controller', defaultConfig: { speed: 1.0 } },
  *   function MyControllerImpl({ config }) {
- *     useBeforePhysicsStep((_model, data) => {
+ *     useBeforePhysicsStep(({ data }) => {
  *       data.ctrl[0] = config.speed;
  *     });
  *     return null;
@@ -100,7 +100,7 @@ export function createController<TConfig>(
  *   { name: 'useMyController', defaultConfig: { gain: 1.0 } },
  *   function useMyControllerImpl(config) {
  *     // config is MyConfig | null — hooks must be called unconditionally
- *     useBeforePhysicsStep((_model, data) => {
+ *     useBeforePhysicsStep(({ data }) => {
  *       if (!config) return;
  *       data.ctrl[0] = config.gain * Math.sin(data.time);
  *     });

package/src/hooks/useBodyState.ts

@@ -29,7 +29,7 @@ export function useBodyState(name: Bodies): BodyStateResult {
     bodyIdRef.current = findBodyByName(model, name);
   }, [name, status, mjModelRef]);
 
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     const bid = bodyIdRef.current;
     if (bid < 0) return;
 

package/src/hooks/useContacts.ts

@@ -60,7 +60,7 @@ export function useContacts(
     bodyResolvedRef.current = true;
   }, [bodyName, status, mjModelRef]);
 
-  useAfterPhysicsStep((model, data) => {
+  useAfterPhysicsStep(({ model, data }) => {
     // Resolve body id lazily once model exists, to avoid missing the first ready frame.
     if (bodyName && !bodyResolvedRef.current) {
       bodyIdRef.current = findBodyByName(model, bodyName);

package/src/hooks/useCtrlNoise.ts

@@ -30,7 +30,7 @@ export function useCtrlNoise(config: CtrlNoiseConfig = {}) {
   configRef.current = config;
   const noiseRef = useRef<Float64Array | null>(null);
 
-  useBeforePhysicsStep((_model, data) => {
+  useBeforePhysicsStep(({ data }) => {
     const cfg = configRef.current;
     if (cfg.enabled === false) return;
 

package/src/hooks/useFrameCapture.ts

@@ -6,48 +6,14 @@
  */
 
 import { useCallback, useState } from 'react';
-import type React from 'react';
-
-export type FrameCaptureStatus = 'idle' | 'capturing' | 'captured' | 'error';
-
-export type FrameCaptureTarget =
-  | HTMLCanvasElement
-  | HTMLElement
-  | null
-  | undefined;
-
-export type FrameCaptureTargetRef =
-  React.RefObject<HTMLCanvasElement | HTMLElement | null>;
-
-export interface FrameCaptureOptions {
-  target?: FrameCaptureTarget | FrameCaptureTargetRef;
-  type?: string;
-  quality?: number;
-  waitForAnimationFrame?: boolean;
-}
-
-export interface FrameCaptureResult {
-  canvas: HTMLCanvasElement;
-  dataUrl: string;
-  type: string;
-}
-
-export interface FrameCaptureBlobResult {
-  canvas: HTMLCanvasElement;
-  blob: Blob;
-  type: string;
-}
-
-export interface FrameCaptureAPI {
-  status: FrameCaptureStatus;
-  error: Error | null;
-  isCapturing: boolean;
-  capture: (options?: FrameCaptureOptions) => Promise<FrameCaptureResult>;
-  captureBlob: (
-    options?: FrameCaptureOptions
-  ) => Promise<FrameCaptureBlobResult>;
-  reset: () => void;
-}
+import type {
+  FrameCaptureAPI,
+  FrameCaptureBlobResult,
+  FrameCaptureOptions,
+  FrameCaptureResult,
+  FrameCaptureStatus,
+  FrameCaptureTargetRef,
+} from '../types';
 
 function isTargetRef(
   target: FrameCaptureOptions['target']

package/src/hooks/useGamepad.ts

@@ -50,7 +50,7 @@ export function useGamepad(config: GamepadConfig) {
     }
   }, [config.axes, config.buttons, status, mjModelRef]);
 
-  useBeforePhysicsStep((_model, data) => {
+  useBeforePhysicsStep(({ data }) => {
     const cfg = configRef.current;
     if (cfg.enabled === false) return;
 

package/src/hooks/useGravityCompensation.ts

@@ -13,7 +13,7 @@ import { useBeforePhysicsStep } from '../core/MujocoSimProvider';
  * hook (and DragInteraction) compose correctly — both add to a clean slate.
  */
 export function useGravityCompensation(enabled = true): void {
-  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];

package/src/hooks/useIkController.ts

@@ -10,7 +10,7 @@ import { createControllerHook } from '../core/createController';
 import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
 import { GenericIK } from '../core/GenericIK';
 import { createContiguousControlGroup, findSiteByName, resolveControlGroup } from '../core/SceneLoader';
-import type { ControlGroupInfo, IkConfig, IkContextValue, IKSolveFn, MujocoData } from '../types';
+import type { ControlGroupInfo, IkConfig, IkContextValue, IKSolveFn, IkSolveInput, MujocoData } from '../types';
 
 // Preallocated temp for syncGizmoToSite
 const _syncMat4 = new THREE.Matrix4();
@@ -84,16 +84,16 @@ export const useIkController = createControllerHook<IkConfig, IkContextValue>(
 
     // IK solve function
     const ikSolveFn = useCallback(
-      (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]): number[] | null => {
+      ({ position, quaternion, currentQ, context }: IkSolveInput): number[] | null => {
         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;
         if (!model || !data || !controlGroup || siteIdRef.current === -1) return null;
         return genericIkRef.current.solve(
           model, data, siteIdRef.current, controlGroup.qposAdr,
-          pos, quat, currentQ,
+          position, quaternion, currentQ,
           { damping: config.damping, maxIterations: config.maxIterations },
         );
       },
@@ -128,7 +128,7 @@ export const useIkController = createControllerHook<IkConfig, IkContextValue>(
     });
 
     // IK solve in physics loop
-    useBeforePhysicsStep((model, data) => {
+    useBeforePhysicsStep(({ model, data }) => {
       if (!config || !ikEnabledRef.current) {
         ikCalculatingRef.current = false;
         return;
@@ -142,13 +142,22 @@ export const useIkController = createControllerHook<IkConfig, IkContextValue>(
 
       const currentQ = Array.from(controlGroup.readQpos(data));
       const solution = config.ikSolveFn
-        ? config.ikSolveFn(target.position, target.quaternion, currentQ, {
-            model,
-            data,
-            siteId: siteIdRef.current,
-            controlGroup,
+        ? config.ikSolveFn({
+            position: target.position,
+            quaternion: target.quaternion,
+            currentQ,
+            context: {
+              model,
+              data,
+              siteId: siteIdRef.current,
+              controlGroup,
+            },
           })
-        : ikSolveFnRef.current(target.position, target.quaternion, currentQ);
+        : ikSolveFnRef.current({
+            position: target.position,
+            quaternion: target.quaternion,
+            currentQ,
+          });
       if (solution) {
         controlGroup.writeCtrl(data, solution);
       }
@@ -192,8 +201,8 @@ export const useIkController = createControllerHook<IkConfig, IkContextValue>(
     }, [mjDataRef]);
 
     const solveIK = useCallback(
-      (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]): number[] | null => {
-        return ikSolveFnRef.current(pos, quat, currentQ);
+      (input: IkSolveInput): number[] | null => {
+        return ikSolveFnRef.current(input);
       },
       [],
     );