mujoco-react 7.0.1 → 8.0.0

package/package.json

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

package/src/hooks/useBodyState.ts

@@ -9,13 +9,13 @@ import { useEffect, useRef } from 'react';
 import * as THREE from 'three';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { findBodyByName } from '../core/SceneLoader';
-import type { BodyStateResult } from '../types';
+import type { Bodies, BodyStateResult } from '../types';
 
 /**
  * Track a MuJoCo body's world position, quaternion, and velocities.
  * All values are ref-based — updated every physics frame without re-renders.
  */
-export function useBodyState(name: string): BodyStateResult {
+export function useBodyState(name: Bodies): BodyStateResult {
   const { mjModelRef, status } = useMujocoContext();
   const bodyIdRef = useRef(-1);
   const position = useRef(new THREE.Vector3());

package/src/hooks/useContacts.ts

@@ -10,7 +10,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { findBodyByName, getName } from '../core/SceneLoader';
 import { getContact } from '../types';
-import type { ContactInfo, MujocoModel } from '../types';
+import type { Bodies, ContactInfo, MujocoModel } from '../types';
 
 // Cache geom names per model to avoid cross-model id collisions.
 const geomNameCacheByModel = new WeakMap<MujocoModel, Map<number, string>>();
@@ -36,7 +36,7 @@ function getGeomNameCached(model: MujocoModel, geomId: number): string {
  * Reads `data.ncon` first to avoid allocating for zero contacts.
  */
 export function useContacts(
-  bodyName?: string,
+  bodyName?: Bodies,
   callback?: (contacts: ContactInfo[]) => void,
 ): React.RefObject<ContactInfo[]> {
   const { mjModelRef, status } = useMujocoContext();
@@ -108,7 +108,7 @@ export function useContacts(
  * onEnter/onExit callbacks on transitions.
  */
 export function useContactEvents(
-  bodyName: string,
+  bodyName: Bodies,
   handlers: {
     onEnter?: (info: ContactInfo) => void;
     onExit?: (info: ContactInfo) => void;

package/src/hooks/useCtrl.ts

@@ -2,39 +2,52 @@
  * @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)
  */
 
-import { useCallback, useEffect, useRef } from 'react';
+import { useEffect, useRef, useMemo } from 'react';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { findActuatorByName } from '../core/SceneLoader';
+import type { Actuators, CtrlHandle } from '../types';
 
 /**
  * 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.
  */
-export function useCtrl(name: string): [React.RefObject<number>, (value: number) => void] {
+export function useCtrl(name: Actuators): CtrlHandle {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const actuatorIdRef = useRef(-1);
-  const valueRef = useRef(0);
+  const rangeRef = useRef<[number, number]>([0, 0]);
 
   useEffect(() => {
     const model = mjModelRef.current;
     if (!model || status !== 'ready') return;
-    actuatorIdRef.current = findActuatorByName(model, name);
+    const id = findActuatorByName(model, name);
+    actuatorIdRef.current = id;
+    if (id >= 0) {
+      rangeRef.current = [
+        model.actuator_ctrlrange[id * 2],
+        model.actuator_ctrlrange[id * 2 + 1],
+      ];
+    }
   }, [name, status, mjModelRef]);
 
-  // Read current value each frame (via afterStep would be ideal but
-  // useCtrl is primarily for writing; reading can use the ref)
-  const setValue = useCallback((value: number) => {
-    const data = mjDataRef.current;
-    if (!data || actuatorIdRef.current < 0) return;
-    data.ctrl[actuatorIdRef.current] = value;
-    valueRef.current = value;
-  }, [mjDataRef]);
-
-  return [valueRef, setValue];
+  return useMemo<CtrlHandle>(() => ({
+    read() {
+      const data = mjDataRef.current;
+      if (!data || actuatorIdRef.current < 0) return 0;
+      return data.ctrl[actuatorIdRef.current];
+    },
+    write(value: number) {
+      const data = mjDataRef.current;
+      if (!data || actuatorIdRef.current < 0) return;
+      data.ctrl[actuatorIdRef.current] = value;
+    },
+    name,
+    get range(): [number, number] {
+      return rangeRef.current;
+    },
+  }), [name, mjDataRef]);
 }

package/src/hooks/useJointState.ts

@@ -8,7 +8,7 @@
 import { useEffect, useRef } from 'react';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
-import type { JointStateResult } from '../types';
+import type { Joints, JointStateResult } from '../types';
 
 /**
  * Track a MuJoCo joint's position and velocity by name.
@@ -18,7 +18,7 @@ import type { JointStateResult } from '../types';
  * 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).
  */
-export function useJointState(name: string): JointStateResult {
+export function useJointState(name: Joints): JointStateResult {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const jointIdRef = useRef(-1);
   const qposAdrRef = useRef(0);

package/src/hooks/useSensor.ts

@@ -8,13 +8,14 @@
 import { useEffect, useRef, useMemo } from 'react';
 import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
-import type { SensorInfo, SensorResult } from '../types';
+import type { Sensors, SensorHandle, SensorInfo } from '../types';
 
 /**
- * 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.
  */
-export function useSensor(name: string): SensorResult {
+export function useSensor(name: Sensors): SensorHandle {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const sensorIdRef = useRef(-1);
   const sensorAdrRef = useRef(0);
@@ -47,7 +48,15 @@ export function useSensor(name: string): SensorResult {
     }
   });
 
-  return { value: valueRef, size: sensorDimRef.current };
+  return useMemo<SensorHandle>(() => ({
+    read() {
+      return valueRef.current;
+    },
+    get dim() {
+      return sensorDimRef.current;
+    },
+    name,
+  }), [name]);
 }
 
 /**

package/src/hooks/useSitePosition.ts

@@ -8,7 +8,7 @@ import { useFrame } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoContext } from '../core/MujocoSimProvider';
 import { findSiteByName } from '../core/SceneLoader';
-import type { SitePositionResult } from '../types';
+import type { Sites, SitePositionResult } from '../types';
 
 // Preallocated temp for rotation matrix extraction
 const _mat4 = new THREE.Matrix4();
@@ -17,7 +17,7 @@ const _mat4 = new THREE.Matrix4();
  * Returns reactive refs for a MuJoCo site's world position and orientation.
  * Refs are updated every frame without triggering React re-renders.
  */
-export function useSitePosition(siteName: string): SitePositionResult {
+export function useSitePosition(siteName: Sites): SitePositionResult {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const siteIdRef = useRef(-1);
   const positionRef = useRef(new THREE.Vector3());

package/src/index.ts

@@ -115,8 +115,19 @@ export type {
   // Hook return types
   SitePositionResult,
   SensorResult,
+  CtrlHandle,
+  SensorHandle,
   BodyStateResult,
   JointStateResult,
+  // Register (type-safe named resources)
+  Register,
+  Actuators,
+  Sensors,
+  Bodies,
+  Joints,
+  Sites,
+  Geoms,
+  Keyframes,
 } from './types';
 
 // Re-export MuJoCo types for convenience

package/src/types.ts

@@ -8,6 +8,34 @@ import type { ReactNode } from 'react';
 import type { CanvasProps } from '@react-three/fiber';
 import * as THREE from 'three';
 
+// ---- Register (type-safe named resources) ----
+
+/**
+ * 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`.
+ */
+export interface Register {}
+
+export type Actuators = Register extends { actuators: infer T extends string } ? T : string;
+export type Sensors = Register extends { sensors: infer T extends string } ? T : string;
+export type Bodies = Register extends { bodies: infer T extends string } ? T : string;
+export type Joints = Register extends { joints: infer T extends string } ? T : string;
+export type Sites = Register extends { sites: infer T extends string } ? T : string;
+export type Geoms = Register extends { geoms: infer T extends string } ? T : string;
+export type Keyframes = Register extends { keyframes: infer T extends string } ? T : string;
+
 // ---- MuJoCo WASM Types ----
 
 /**
@@ -300,7 +328,7 @@ export interface SceneConfig {
 
 export 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. */
@@ -462,7 +490,7 @@ export interface TrajectoryData {
 // ---- Keyboard Teleop (spec 12.1) ----
 
 export interface KeyBinding {
-  actuator: string;
+  actuator: Actuators;
   delta?: number;
   toggle?: [number, number];
   set?: number;
@@ -527,13 +555,13 @@ export interface SelectionHighlightProps {
 }
 
 export interface ContactListenerProps {
-  body: string;
+  body: Bodies;
   onContactEnter?: (info: ContactInfo) => void;
   onContactExit?: (info: ContactInfo) => void;
 }
 
 export interface BodyProps {
-  name: string;
+  name: Bodies;
   type: 'box' | 'sphere' | 'cylinder';
   size: [number, number, number];
   position?: [number, number, number];
@@ -562,7 +590,7 @@ export interface MujocoSimAPI {
   step(n?: number): void;
   getTime(): number;
   getTimestep(): number;
-  applyKeyframe(nameOrIndex: string | number): void;
+  applyKeyframe(nameOrIndex: Keyframes | number): void;
 
   // State management (spec 4.1, 4.2, 4.3)
   saveState(): StateSnapshot;
@@ -573,17 +601,17 @@ export interface MujocoSimAPI {
   getQvel(): Float64Array;
 
   // Actuator / control (spec 3.1)
-  setCtrl(nameOrValues: string | Record<string, number>, value?: number): void;
+  setCtrl(nameOrValues: Actuators | Record<Actuators, number>, value?: number): void;
   getCtrl(): Float64Array;
 
   // Force application (spec 8.1)
-  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;
 
   // Sensors (spec 2.1)
-  getSensorData(name: string): Float64Array | null;
+  getSensorData(name: Sensors): Float64Array | null;
 
   // Contacts (spec 2.4)
   getContacts(): ContactInfo[];
@@ -621,9 +649,9 @@ export interface MujocoSimAPI {
   ): { point: THREE.Vector3; bodyId: number; geomId: number } | null;
 
   // Domain randomization (spec 10.3)
-  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;
 
   // Internal refs for advanced use
   readonly mjModelRef: React.RefObject<MujocoModel | null>;
@@ -659,11 +687,32 @@ export interface MujocoContextValue {
   error: string | null;
 }
 
+/** @deprecated Use `SensorHandle` instead. */
 export interface SensorResult {
   value: React.RefObject<Float64Array>;
   size: number;
 }
 
+export 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];
+}
+
+export interface SensorHandle {
+  /** Read the current sensor data. */
+  read(): Float64Array;
+  /** Sensor dimensionality. */
+  dim: number;
+  /** Sensor name. */
+  name: Sensors;
+}
+
 export interface BodyStateResult {
   position: React.RefObject<THREE.Vector3>;
   quaternion: React.RefObject<THREE.Quaternion>;