mujoco-react 7.0.1 → 8.1.0

package/README.md

@@ -24,18 +24,18 @@ import {
   MujocoCanvas,
   useIkController,
   IkGizmo,
-} from 'mujoco-react';
-import type { SceneConfig } from 'mujoco-react';
-import { OrbitControls } from '@react-three/drei';
+} from "mujoco-react";
+import type { SceneConfig } from "mujoco-react";
+import { OrbitControls } from "@react-three/drei";
 
 const config: SceneConfig = {
-  src: 'https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/',
-  sceneFile: 'scene.xml',
+  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
+  sceneFile: "scene.xml",
   homeJoints: [1.707, -1.754, 0.003, -2.702, 0.003, 0.951, 2.490],
 };
 
 function Scene() {
-  const ik = useIkController({ siteName: 'tcp', numJoints: 7 });
+  const ik = useIkController({ siteName: "tcp", numJoints: 7 });
   return (
     <>
       <OrbitControls enableDamping makeDefault />
@@ -53,7 +53,7 @@ function App() {
         config={config}
         camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
         shadows
-        style={{ width: '100%', height: '100vh' }}
+        style={{ width: "100%", height: "100vh" }}
       >
         <Scene />
       </MujocoCanvas>
@@ -67,7 +67,7 @@ function App() {
 Inside `<MujocoCanvas>` or `<MujocoPhysics>`, `useMujoco()` gives you the simulation API, refs to the live model/data, and status:
 
 ```tsx
-import { useMujoco } from 'mujoco-react';
+import { useMujoco } from "mujoco-react";
 
 function MyComponent() {
   const { isPending, isError, error, api, mjModelRef } = useMujoco();
@@ -85,15 +85,19 @@ function MyComponent() {
 
 ## Writing a Controller
 
-A controller is a React component that calls `useBeforePhysicsStep` to write `data.ctrl` each frame:
+A controller is a React component that uses handle-based hooks for type-safe actuator and sensor access:
 
 ```tsx
-import { useBeforePhysicsStep } from 'mujoco-react';
+import { useCtrl, useSensor, useBeforePhysicsStep } from "mujoco-react";
 
 function MyController() {
-  useBeforePhysicsStep((_model, data) => {
-    data.ctrl[0] = Math.sin(data.time);        // sine wave on actuator 0
-    data.ctrl[1] = data.sensordata[0] * -0.5;  // feedback from a sensor
+  const shoulder = useCtrl("shoulder");
+  const elbow = useCtrl("elbow");
+  const force = useSensor("force_sensor");
+
+  useBeforePhysicsStep(() => {
+    shoulder.write(Math.sin(Date.now() / 1000));
+    elbow.write(force.read()[0] * -0.5);
   });
   return null;
 }
@@ -110,10 +114,10 @@ Drop it into the tree:
 The `createController<TConfig>()` factory adds typed config and default merging for reusable plugins:
 
 ```tsx
-import { createController, useBeforePhysicsStep } from 'mujoco-react';
+import { createController, useBeforePhysicsStep } from "mujoco-react";
 
 export const MyController = createController<{ gain: number }>(
-  { name: 'MyController', defaultConfig: { gain: 1.0 } },
+  { name: "MyController", defaultConfig: { gain: 1.0 } },
   ({ config }) => {
     useBeforePhysicsStep((_model, data) => {
       data.ctrl[0] = config.gain * Math.sin(data.time);
@@ -145,13 +149,13 @@ export const MyController = createController<{ gain: number }>(
 The built-in `useIkController()` uses Damped Least-Squares. Pass `ikSolveFn` to swap in your own solver (analytical, learned, etc.):
 
 ```tsx
-import type { IKSolveFn } from 'mujoco-react';
+import type { IKSolveFn } from "mujoco-react";
 
 const myIK: IKSolveFn = (pos, quat, currentQ) => {
   return myAnalyticalSolver(pos, currentQ); // return joint angles or null
 };
 
-const ik = useIkController({ siteName: 'tcp', numJoints: 7, ikSolveFn: myIK });
+const ik = useIkController({ siteName: "tcp", numJoints: 7, ikSolveFn: myIK });
 ```
 
 ### `useIkController(config | null)`
@@ -159,7 +163,7 @@ const ik = useIkController({ siteName: 'tcp', numJoints: 7, ikSolveFn: myIK });
 Hook for interactive end-effector control. Pass `null` to disable IK (safe to call unconditionally):
 
 ```tsx
-const ik = useIkController({ siteName: 'tcp', numJoints: 7 });
+const ik = useIkController({ siteName: "tcp", numJoints: 7 });
 return ik ? <IkGizmo controller={ik} /> : null;
 ```
 
@@ -175,6 +179,23 @@ Returns `IkContextValue | null` with methods like `setIkEnabled`, `moveTarget`,
 
 Pass the returned value to `<IkGizmo controller={ik} />` or to your own controller as a prop.
 
+## Type-Safe Resource Names
+
+Use TypeScript module augmentation to get autocomplete and type checking for actuator, sensor, body, joint, site, geom, and keyframe names:
+
+```ts
+// e.g. in src/mujoco-register.d.ts
+declare module "mujoco-react" {
+  interface Register {
+    actuators: "joint1" | "joint2" | "joint3" | "gripper";
+    sensors: "force_sensor" | "torque_sensor";
+    bodies: "link0" | "link1" | "hand";
+  }
+}
+```
+
+Once declared, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API methods like `setCtrl`, `applyForce`, `getSensorData` will only accept the declared names. When no `Register` augmentation is provided, all names fall back to `string`.
+
 ## Loading Models
 
 The loader fetches `src + sceneFile`, parses the XML for dependencies (meshes, textures, includes), recursively fetches those too, and writes everything to MuJoCo's in-memory WASM filesystem.
@@ -182,14 +203,14 @@ The loader fetches `src + sceneFile`, parses the XML for dependencies (meshes, t
 ```tsx
 // MuJoCo Menagerie
 const franka: SceneConfig = {
-  src: 'https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/',
-  sceneFile: 'scene.xml',
+  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
+  sceneFile: "scene.xml",
 };
 
 // Any URL
 const custom: SceneConfig = {
-  src: 'http://localhost:3000/models/my_model/',
-  sceneFile: 'model.xml',
+  src: "http://localhost:3000/models/my_model/",
+  sceneFile: "model.xml",
 };
 ```
 
@@ -198,7 +219,7 @@ const custom: SceneConfig = {
 ```ts
 interface SceneConfig {
   src: string;                      // Base URL for model files
-  sceneFile: string;                // Entry XML file, e.g. 'scene.xml'
+  sceneFile: string;                // Entry XML file, e.g. "scene.xml"
   sceneObjects?: SceneObject[];     // Objects injected into scene XML at load time
   homeJoints?: number[];            // Initial joint positions
   xmlPatches?: XmlPatch[];          // Patches applied to XML files during loading
@@ -210,12 +231,12 @@ interface SceneConfig {
 
 ```tsx
 const config: SceneConfig = {
-  src: 'https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/',
-  sceneFile: 'scene.xml',
+  src: "https://raw.githubusercontent.com/google-deepmind/mujoco_menagerie/main/franka_emika_panda/",
+  sceneFile: "scene.xml",
   sceneObjects: [
-    { name: 'ball', type: 'sphere', size: [0.03, 0.03, 0.03],
+    { name: "ball", type: "sphere", size: [0.03, 0.03, 0.03],
       position: [0.5, 0, 0.1], rgba: [1, 0, 0, 1], mass: 0.1, freejoint: true },
-    { name: 'platform', type: 'box', size: [0.2, 0.2, 0.01],
+    { name: "platform", type: "box", size: [0.2, 0.2, 0.01],
       position: [0.4, 0.3, 0], rgba: [0.5, 0.5, 0.5, 1] },
   ],
 };
@@ -225,10 +246,10 @@ const config: SceneConfig = {
 
 ```tsx
 xmlPatches: [{
-  target: 'panda.xml',
-  replace: ['name="actuator8"', 'name="gripper"'],
-  inject: '<site name="tcp" pos="0 0 0.1" size="0.01"/>',
-  injectAfter: '<body name="hand"',
+  target: "panda.xml",
+  replace: ["name=\"actuator8\"", "name=\"gripper\""],
+  inject: "<site name=\"tcp\" pos=\"0 0 0.1\" size=\"0.01\"/>",
+  injectAfter: "<body name=\"hand\"",
 }]
 ```
 
@@ -352,7 +373,7 @@ InstancedMesh showing MuJoCo contact points for debugging.
 |------|------|---------|-------------|
 | `maxContacts` | `number?` | `100` | Max contacts to display |
 | `radius` | `number?` | `0.005` | Marker sphere radius |
-| `color` | `string?` | `'#4f46e5'` | Marker color |
+| `color` | `string?` | `"#4f46e5"` | Marker color |
 | `visible` | `boolean?` | `true` | Toggle visibility |
 
 ### `<SceneLights />`
@@ -372,10 +393,10 @@ Visualization overlays:
 | `showCOM` | `boolean?` | `false` | Center of mass markers |
 | `showInertia` | `boolean?` | `false` | Inertia ellipsoids |
 | `showTendons` | `boolean?` | `false` | Tendon paths |
-| `geomColor` | `string?` | `'#00ff00'` | Color for wireframe geoms |
-| `siteColor` | `string?` | `'#ff00ff'` | Color for site markers |
-| `contactColor` | `string?` | `'#ff4444'` | Color for contact force arrows |
-| `comColor` | `string?` | `'#ff0000'` | Color for COM markers |
+| `geomColor` | `string?` | `"#00ff00"` | Color for wireframe geoms |
+| `siteColor` | `string?` | `"#ff00ff"` | Color for site markers |
+| `contactColor` | `string?` | `"#ff4444"` | Color for contact force arrows |
+| `comColor` | `string?` | `"#ff0000"` | Color for COM markers |
 
 ### `<TendonRenderer />`
 
@@ -392,8 +413,8 @@ Component wrapper for contact events:
 ```tsx
 <ContactListener
   body="block_1"
-  onContactEnter={(info) => console.log('contact!', info)}
-  onContactExit={(info) => console.log('released', info)}
+  onContactEnter={(info) => console.log("contact!", info)}
+  onContactExit={(info) => console.log("released", info)}
 />
 ```
 
@@ -419,12 +440,12 @@ if (sim.isReady) {
 Access the raw WASM module lifecycle from any child of `<MujocoProvider>`. Most users won't need this — `useMujoco()` and hooks like `useBeforePhysicsStep` handle the model/data lifecycle for you.
 
 ```tsx
-import { useMujocoWasm } from 'mujoco-react';
+import { useMujocoWasm } from "mujoco-react";
 
 const { mujoco, status } = useMujocoWasm();
 
 if (mujoco) {
-  const model = mujoco.MjModel.loadFromXML('/path/to/scene.xml');
+  const model = mujoco.MjModel.loadFromXML("/path/to/scene.xml");
   const data = new mujoco.MjData(model);
   mujoco.mj_step(model, data);
   console.log(data.qpos);  // joint positions after one step
@@ -466,10 +487,11 @@ await moveCameraTo(
 
 ### `useSensor(name)` / `useSensors()`
 
-Read sensor values by name (ref-based, no re-renders):
+Read sensor values by name. Returns a `SensorHandle` with `read()`, `dim`, and `name`:
 
 ```tsx
-const { value, size, type } = useSensor('force_sensor_1');
+const force = useSensor("force_sensor_1");
+// force.read() -> Float64Array, force.dim -> number
 ```
 
 ### `useBodyState(name)`
@@ -477,7 +499,7 @@ const { value, size, type } = useSensor('force_sensor_1');
 Position, quaternion, linear/angular velocity of a body (ref-based):
 
 ```tsx
-const { position, quaternion, linearVelocity, angularVelocity } = useBodyState('block_1');
+const { position, quaternion, linearVelocity, angularVelocity } = useBodyState("block_1");
 ```
 
 ### `useJointState(name)`
@@ -485,15 +507,16 @@ const { position, quaternion, linearVelocity, angularVelocity } = useBodyState('
 Joint position and velocity:
 
 ```tsx
-const { position, velocity } = useJointState('joint1');
+const { position, velocity } = useJointState("joint1");
 ```
 
 ### `useCtrl(name)`
 
-Read/write actuator control by name:
+Read/write actuator control by name. Returns a `CtrlHandle` with `read()`, `write()`, `name`, and `range`:
 
 ```tsx
-const [value, setValue] = useCtrl('gripper');
+const gripper = useCtrl("gripper");
+// gripper.read() -> number, gripper.write(0.04), gripper.range -> [min, max]
 ```
 
 ### `useContacts(bodyName?)` / `useContactEvents(bodyName, handlers)`
@@ -501,9 +524,9 @@ const [value, setValue] = useCtrl('gripper');
 Query contacts or subscribe to enter/exit events:
 
 ```tsx
-useContactEvents('block_1', {
-  onEnter: (info) => console.log('contact!', info),
-  onExit: (info) => console.log('released', info),
+useContactEvents("block_1", {
+  onEnter: (info) => console.log("contact!", info),
+  onExit: (info) => console.log("released", info),
 });
 ```
 
@@ -514,9 +537,9 @@ Map keyboard keys to actuators:
 ```tsx
 useKeyboardTeleop({
   bindings: {
-    'w': { actuator: 'forward', delta: 0.1 },
-    's': { actuator: 'forward', delta: -0.1 },
-    'v': { actuator: 'gripper', toggle: [0, 0.04] },
+    "w": { actuator: "forward", delta: 0.1 },
+    "s": { actuator: "forward", delta: -0.1 },
+    "v": { actuator: "gripper", toggle: [0, 0.04] },
   },
 });
 ```
@@ -527,8 +550,8 @@ Map gamepad axes/buttons to actuators:
 
 ```tsx
 useGamepad({
-  axes: { 0: 'joint1', 1: 'joint2' },
-  buttons: { 0: 'gripper' },
+  axes: { 0: "joint1", 1: "joint2" },
+  buttons: { 0: "gripper" },
   deadzone: 0.1,
 });
 ```
@@ -550,11 +573,23 @@ const { step, isRunning } = usePolicy({
 Record and play back simulation trajectories:
 
 ```tsx
-const recorder = useTrajectoryRecorder({ fields: ['qpos', 'qvel', 'ctrl'] });
-// recorder.start(), recorder.stop(), recorder.downloadJSON(), recorder.downloadCSV()
+// Record
+const recorder = useTrajectoryRecorder({ fields: ["qpos", "ctrl"] });
+recorder.start();
+// ... interact with simulation ...
+recorder.stop();
 
-const player = useTrajectoryPlayer(trajectory, { fps: 30, loop: true });
-// player.play(), player.pause(), player.seek(frameIdx)
+// Play back recorded frames directly (no conversion needed)
+const player = useTrajectoryPlayer(recorder.frames, {
+  fps: 30,
+  speed: 1.0,        // 0.5x, 1x, 2x, etc.
+  loop: true,
+  mode: "kinematic",  // or "physics" to replay ctrl through the sim
+  onComplete: () => console.log("done"),
+});
+// player.play(), player.pause(), player.seek(42), player.setSpeed(2)
+// player.state → "idle" | "playing" | "paused" | "completed"
+// player.progress → 0-1
 ```
 
 ### `useVideoRecorder(config)`
@@ -562,7 +597,7 @@ const player = useTrajectoryPlayer(trajectory, { fps: 30, loop: true });
 Record the canvas as video:
 
 ```tsx
-const video = useVideoRecorder({ fps: 30, mimeType: 'video/webm' });
+const video = useVideoRecorder({ fps: 30, mimeType: "video/webm" });
 // video.start(), video.stop() -> returns Blob
 ```
 
@@ -601,7 +636,7 @@ const meshes = useBodyMeshes(selectedBodyId);
 Convenience wrapper around `useBodyMeshes` that applies an emissive highlight:
 
 ```tsx
-useSelectionHighlight(selectedBodyId, { color: '#00ff00', emissiveIntensity: 0.5 });
+useSelectionHighlight(selectedBodyId, { color: "#00ff00", emissiveIntensity: 0.5 });
 ```
 
 ### `useSceneLights(intensity?)`
@@ -732,6 +767,7 @@ Features planned but not yet implemented:
 | **Physics interpolation** | P1 | Smooth rendering between physics ticks for very high refresh displays |
 | **Instanced geom rendering** | P2 | `<InstancedGeomRenderer />` for particle/granular sims |
 | **Web Worker physics** | P2 | Run `mj_step` off main thread via SharedArrayBuffer |
+| **Register codegen** | P2 | CLI to auto-generate `Register` type augmentation from MJCF XML |
 
 ### WASM Limitations (mujoco-js 0.0.7)
 

package/dist/index.d.ts

@@ -9,6 +9,45 @@ import * as THREE from 'three';
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * Module augmentation interface for type-safe resource names.
+ *
+ * Declare your model's resource names via module augmentation:
+ * ```ts
+ * declare module 'mujoco-react' {
+ *   interface Register {
+ *     actuators: 'joint1' | 'joint2' | 'gripper';
+ *     sensors: 'force_sensor' | 'torque_sensor';
+ *     bodies: 'link0' | 'link1' | 'hand';
+ *   }
+ * }
+ * ```
+ *
+ * When no augmentation is declared, all names fall back to `string`.
+ */
+interface Register {
+}
+type Actuators = Register extends {
+    actuators: infer T extends string;
+} ? T : string;
+type Sensors = Register extends {
+    sensors: infer T extends string;
+} ? T : string;
+type Bodies = Register extends {
+    bodies: infer T extends string;
+} ? T : string;
+type Joints = Register extends {
+    joints: infer T extends string;
+} ? T : string;
+type Sites = Register extends {
+    sites: infer T extends string;
+} ? T : string;
+type Geoms = Register extends {
+    geoms: infer T extends string;
+} ? T : string;
+type Keyframes = Register extends {
+    keyframes: infer T extends string;
+} ? T : string;
 /**
  * A single MuJoCo contact from the WASM module.
  * Accessed via `data.contact.get(i)`.
@@ -245,7 +284,7 @@ interface SceneConfig {
 }
 interface IkConfig {
     /** MuJoCo site name for IK target. */
-    siteName: string;
+    siteName: Sites;
     /** Number of joints to solve for. */
     numJoints: number;
     /** Custom IK solver. When omitted, uses built-in Damped Least-Squares solver. */
@@ -364,8 +403,9 @@ interface TrajectoryData {
     frames: TrajectoryFrame[];
     fps: number;
 }
+type PlaybackState = 'idle' | 'playing' | 'paused' | 'completed';
 interface KeyBinding {
-    actuator: string;
+    actuator: Actuators;
     delta?: number;
     toggle?: [number, number];
     set?: number;
@@ -402,20 +442,25 @@ interface SceneLightsProps {
     /** Override intensity for all MJCF lights. Default: 1.0. */
     intensity?: number;
 }
+type TrajectoryInput = TrajectoryFrame[] | number[][];
 interface TrajectoryPlayerProps {
-    trajectory: number[][];
+    trajectory: TrajectoryInput;
     fps?: number;
+    speed?: number;
     loop?: boolean;
     playing?: boolean;
+    mode?: 'kinematic' | 'physics';
     onFrame?: (frameIdx: number) => void;
+    onComplete?: () => void;
+    onStateChange?: (state: PlaybackState) => void;
 }
 interface ContactListenerProps {
-    body: string;
+    body: Bodies;
     onContactEnter?: (info: ContactInfo) => void;
     onContactExit?: (info: ContactInfo) => void;
 }
 interface BodyProps {
-    name: string;
+    name: Bodies;
     type: 'box' | 'sphere' | 'cylinder';
     size: [number, number, number];
     position?: [number, number, number];
@@ -438,20 +483,20 @@ interface MujocoSimAPI {
     step(n?: number): void;
     getTime(): number;
     getTimestep(): number;
-    applyKeyframe(nameOrIndex: string | number): void;
+    applyKeyframe(nameOrIndex: Keyframes | 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;
+    setCtrl(nameOrValues: Actuators | Record<Actuators, 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;
+    applyForce(bodyName: Bodies, force: THREE.Vector3, point?: THREE.Vector3): void;
+    applyTorque(bodyName: Bodies, torque: THREE.Vector3): void;
+    setExternalForce(bodyName: Bodies, force: THREE.Vector3, torque: THREE.Vector3): void;
     applyGeneralizedForce(values: Float64Array | number[]): void;
-    getSensorData(name: string): Float64Array | null;
+    getSensorData(name: Sensors): Float64Array | null;
     getContacts(): ContactInfo[];
     getBodies(): BodyInfo[];
     getJoints(): JointInfo[];
@@ -472,9 +517,9 @@ interface MujocoSimAPI {
         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;
+    setBodyMass(name: Bodies, mass: number): void;
+    setGeomFriction(name: Geoms, friction: [number, number, number]): void;
+    setGeomSize(name: Geoms, size: [number, number, number]): void;
     readonly mjModelRef: React__default.RefObject<MujocoModel | null>;
     readonly mjDataRef: React__default.RefObject<MujocoData | null>;
 }
@@ -499,10 +544,29 @@ interface MujocoContextValue {
     status: 'loading' | 'ready' | 'error';
     error: string | null;
 }
+/** @deprecated Use `SensorHandle` instead. */
 interface SensorResult {
     value: React__default.RefObject<Float64Array>;
     size: number;
 }
+interface CtrlHandle {
+    /** Read the current ctrl value. */
+    read(): number;
+    /** Write a ctrl value (goes directly to data.ctrl). */
+    write(value: number): void;
+    /** Actuator name. */
+    name: Actuators;
+    /** Actuator control range [min, max]. */
+    range: [number, number];
+}
+interface SensorHandle {
+    /** Read the current sensor data. */
+    read(): Float64Array;
+    /** Sensor dimensionality. */
+    dim: number;
+    /** Sensor name. */
+    name: Sensors;
+}
 interface BodyStateResult {
     position: React__default.RefObject<THREE.Vector3>;
     quaternion: React__default.RefObject<THREE.Quaternion>;
@@ -840,7 +904,7 @@ declare function ContactListener({ body, onContactEnter, onContactExit, }: Conta
  * Component wrapper for useTrajectoryPlayer.
  * Provides declarative trajectory playback controlled via props.
  */
-declare function TrajectoryPlayer({ trajectory, fps, loop, playing, onFrame, }: TrajectoryPlayerProps): null;
+declare function TrajectoryPlayer({ trajectory, fps, speed, loop, playing, mode, onFrame, onComplete, onStateChange, }: TrajectoryPlayerProps): null;
 
 /**
  * @license
@@ -862,7 +926,7 @@ declare function useActuators(): ActuatorInfo[];
  * 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;
+declare function useSitePosition(siteName: Sites): SitePositionResult;
 
 /**
  * @license
@@ -885,10 +949,11 @@ declare function useGravityCompensation(enabled?: boolean): void;
  */
 
 /**
- * Access a single MuJoCo sensor by name. Returns a ref-based value
- * updated every physics frame without causing React re-renders.
+ * Access a single MuJoCo sensor by name. Returns a `SensorHandle` with
+ * `read()`, `dim`, and `name`. The backing array is updated every physics
+ * frame without causing React re-renders.
  */
-declare function useSensor(name: string): SensorResult;
+declare function useSensor(name: Sensors): SensorHandle;
 /**
  * Enumerate all sensors in the loaded MuJoCo model.
  * Returns a stable array recomputed only when the model changes.
@@ -910,7 +975,7 @@ declare function useSensors(): SensorInfo[];
  * 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;
+declare function useJointState(name: Joints): JointStateResult;
 
 /**
  * @license
@@ -923,22 +988,22 @@ declare function useJointState(name: string): JointStateResult;
  * 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;
+declare function useBodyState(name: Bodies): BodyStateResult;
 
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
- * useCtrl — clean read/write access to a named actuator's ctrl value (spec 3.1)
+ * useCtrl — handle-based 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]`.
+ * Returns a `CtrlHandle` with `read()` and `write()` methods that
+ * operate directly on `data.ctrl` without causing React re-renders.
  */
-declare function useCtrl(name: string): [React.RefObject<number>, (value: number) => void];
+declare function useCtrl(name: Actuators): CtrlHandle;
 
 /**
  * @license
@@ -953,13 +1018,13 @@ declare function useCtrl(name: string): [React.RefObject<number>, (value: number
  * 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[]>;
+declare function useContacts(bodyName?: Bodies, 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: {
+declare function useContactEvents(bodyName: Bodies, handlers: {
     onEnter?: (info: ContactInfo) => void;
     onExit?: (info: ContactInfo) => void;
 }): void;
@@ -1011,24 +1076,38 @@ declare function usePolicy(config: PolicyConfig): {
  *
  * useTrajectoryPlayer — trajectory playback/scrubbing (spec 13.2)
  */
+
 interface TrajectoryPlayerOptions {
     fps?: number;
+    speed?: number;
     loop?: boolean;
+    mode?: 'kinematic' | 'physics';
+    onComplete?: () => void;
+    onStateChange?: (state: PlaybackState) => void;
 }
 /**
- * Play back a sequence of qpos frames, overriding simulation state.
+ * Play back a trajectory, overriding simulation state.
+ *
+ * Accepts either `TrajectoryFrame[]` (from useTrajectoryRecorder) or
+ * `number[][]` (raw qpos arrays).
+ *
+ * In `kinematic` mode (default), the simulation is paused and qpos is
+ * set directly each frame with mj_forward for rendering.
  *
- * When playing, the simulation is effectively paused and qpos is set
- * from the trajectory each render frame at the specified FPS.
+ * In `physics` mode, the simulation keeps running and ctrl values from
+ * the trajectory are applied each physics step via useBeforePhysicsStep.
  */
-declare function useTrajectoryPlayer(trajectory: number[][], options?: TrajectoryPlayerOptions): {
+declare function useTrajectoryPlayer(trajectory: TrajectoryInput, options?: TrajectoryPlayerOptions): {
     play: () => void;
     pause: () => void;
     seek: (frameIdx: number) => void;
     reset: () => void;
+    setSpeed: (s: number) => void;
+    readonly state: PlaybackState;
     readonly frame: number;
     readonly playing: boolean;
     readonly totalFrames: number;
+    readonly progress: number;
 };
 
 /**
@@ -1195,4 +1274,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { type ActuatorInfo, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type IKSolveFn, type IkConfig, type IkContextValue, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type KeyBinding, type KeyboardTeleopConfig, type ModelOptions, MujocoCanvas, type MujocoCanvasProps, type MujocoContact, type MujocoContactArray, type MujocoContextValue, type MujocoData, type MujocoModel, type MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoSimAPI, MujocoSimProvider, type PhysicsConfig, type PhysicsStepCallback, type PolicyConfig, type RayHit, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, type SensorInfo, type SensorResult, type SiteInfo, type SitePositionResult, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { type ActuatorInfo, type Actuators, type Bodies, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControllerComponent, type ControllerOptions, type CtrlHandle, Debug, type DebugProps, DragInteraction, type DragInteractionProps, FlexRenderer, type GeomInfo, type Geoms, type IKSolveFn, type IkConfig, type IkContextValue, IkGizmo, type IkGizmoProps, type JointInfo, type JointStateResult, type Joints, type KeyBinding, type KeyboardTeleopConfig, type Keyframes, type ModelOptions, MujocoCanvas, type MujocoCanvasProps, type MujocoContact, type MujocoContactArray, type MujocoContextValue, type MujocoData, type MujocoModel, type MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoSimAPI, MujocoSimProvider, type PhysicsConfig, type PhysicsStepCallback, type PlaybackState, type PolicyConfig, type RayHit, type Register, type SceneConfig, SceneLights, type SceneLightsProps, type SceneMarker, type SceneObject, type SensorHandle, type SensorInfo, type SensorResult, type Sensors, type SiteInfo, type SitePositionResult, type Sites, type StateSnapshot, TendonRenderer, type TrajectoryData, type TrajectoryFrame, type TrajectoryInput, TrajectoryPlayer, type TrajectoryPlayerProps, type XmlPatch, createController, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getContact, getName, loadScene, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };