mujoco-react 8.11.0 → 9.0.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-izZlUweI.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-izZlUweI.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;
@@ -814,10 +853,10 @@ 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 +907,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 BodyInfo as a6, type ControlJointInfo as a7, type Geoms as a8, type IKSolveFn as a9, RobotResources as aA, RobotSensors as aB, RobotSites as aC, type Robots as aD, type ScenarioCameraConfig as aE, type ScenarioMaterialConfig as aF, type SceneMarker as aG, type SceneObject as aH, type SensorResult as aI, type SiteInfo as aJ, type SplatAssetConfig as aK, type SplatScenarioConfig as aL, type StateSnapshot as aM, type TrajectoryData as aN, type TrajectoryFrameCallbackInput as aO, type VisualScenarioMaterialFilterInput as aP, type XmlPatch as aQ, getContact as aR, registerRobotResources as aS, type IkGizmoDragInput as aa, type IkSolveInput as ab, type JointInfo as ac, type KeyBinding as ad, type Keyframes as ae, type ModelOptions as af, type MujocoContact as ag, type MujocoContactArray as ah, type ObservationLayoutItem as ai, type ObservationOutput as aj, type PhysicsConfig as ak, type PhysicsStepInput as al, type PolicyActionInput as am, type PolicyInferenceInput as an, type PolicyObservationInput as ao, type RayHit as ap, type Register as aq, type RegisteredRobotMap as ar, type ResetCallbackInput as as, type ResourceSelector as at, RobotActuators as au, RobotBodies as av, RobotGeoms as aw, RobotJoints as ax, RobotKeyframes as ay, type RobotResource 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.0.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,11 +31,14 @@ import {
   MujocoSimAPI,
   PhysicsStepCallback,
   RayHit,
+  ReadyCallbackInput,
   SceneConfig,
   SceneObject,
+  SelectionCallbackInput,
   SensorInfo,
   SiteInfo,
   StateSnapshot,
+  StepCallbackInput,
   XmlPatch,
 } from '../types';
 import {
@@ -117,7 +120,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 +200,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 +212,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 +222,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 +383,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 +412,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 +469,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 +518,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)

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/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);
       },
       [],
     );

package/src/hooks/useJointState.ts

@@ -59,7 +59,7 @@ export function useJointState(name: Joints): JointStateResult {
     jointIdRef.current = -1;
   }, [name, status, mjModelRef]);
 
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     if (jointIdRef.current < 0) return;
     const qa = qposAdrRef.current;
     const da = dofAdrRef.current;

package/src/hooks/useKeyboardTeleop.ts

@@ -70,7 +70,7 @@ export function useKeyboardTeleop(config: KeyboardTeleopConfig) {
   }, []);
 
   // Apply bindings each physics frame
-  useBeforePhysicsStep((_model, data) => {
+  useBeforePhysicsStep(({ data }) => {
     if (!enabledRef.current) return;
     const bindings = bindingsRef.current;
     const cache = actuatorCacheRef.current;

package/src/hooks/usePolicy.ts

@@ -28,7 +28,7 @@ export function usePolicy(config: PolicyConfig) {
   configRef.current = config;
   isRunningRef.current = config.enabled ?? isRunningRef.current;
 
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (!isRunningRef.current) return;
 
     const cfg = configRef.current;

package/src/hooks/useSensor.ts

@@ -39,7 +39,7 @@ export function useSensor(name: Sensors): SensorHandle {
   }, [name, status, mjModelRef]);
 
   // Update every frame after physics step
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     if (sensorIdRef.current < 0) return;
     const adr = sensorAdrRef.current;
     const dim = sensorDimRef.current;

package/src/hooks/useTrajectoryPlayer.ts

@@ -8,7 +8,7 @@
 import { useCallback, useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
 import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
-import type { PlaybackState, TrajectoryFrame, TrajectoryInput } from '../types';
+import type { PlaybackState, TrajectoryStateChangeInput, TrajectoryFrame, TrajectoryInput } from '../types';
 
 export interface TrajectoryPlayerOptions {
   fps?: number;
@@ -16,7 +16,7 @@ export interface TrajectoryPlayerOptions {
   loop?: boolean;
   mode?: 'kinematic' | 'physics';
   onComplete?: () => void;
-  onStateChange?: (state: PlaybackState) => void;
+  onStateChange?: (input: TrajectoryStateChangeInput) => void;
 }
 
 /** Check if input is TrajectoryFrame[] (vs number[][]) */
@@ -74,7 +74,7 @@ export function useTrajectoryPlayer(
   const setState = useCallback((next: PlaybackState) => {
     if (stateRef.current === next) return;
     stateRef.current = next;
-    optionsRef.current.onStateChange?.(next);
+    optionsRef.current.onStateChange?.({ state: next });
   }, []);
 
   const play = useCallback(() => {
@@ -181,7 +181,7 @@ export function useTrajectoryPlayer(
   });
 
   // --- Physics mode: set ctrl values each physics step ---
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (stateRef.current !== 'playing') return;
     if ((optionsRef.current.mode ?? 'kinematic') !== 'physics') return;
 

package/src/hooks/useTrajectoryRecorder.ts

@@ -22,7 +22,7 @@ export function useTrajectoryRecorder(options: RecorderOptions = {}) {
   const framesRef = useRef<TrajectoryFrame[]>([]);
   const fields = options.fields ?? ['qpos'];
 
-  useAfterPhysicsStep((_model, data) => {
+  useAfterPhysicsStep(({ data }) => {
     if (!recordingRef.current) return;
 
     const frame: TrajectoryFrame = {

package/src/index.ts

@@ -110,8 +110,14 @@ export type {
   IkConfig,
   IkContextValue,
   IKSolveFn,
+  IkSolveInput,
   // Callbacks
   PhysicsStepCallback,
+  PhysicsStepInput,
+  ResetCallbackInput,
+  ReadyCallbackInput,
+  StepCallbackInput,
+  SelectionCallbackInput,
   // State management
   StateSnapshot,
   // Model introspection
@@ -155,6 +161,7 @@ export type {
   // Component props
   BodyProps,
   IkGizmoProps,
+  IkGizmoDragInput,
   DragInteractionProps,
   DebugProps,
   SceneLightsProps,
@@ -175,7 +182,10 @@ export type {
   ScenarioMaterialConfig,
   SplatEnvironmentProps,
   VisualScenarioEffectsProps,
+  VisualScenarioMaterialFilterInput,
   TrajectoryPlayerProps,
+  TrajectoryFrameCallbackInput,
+  TrajectoryStateChangeInput,
   ContactListenerProps,
   // API
   MujocoSimAPI,