mujoco-react 9.5.0 → 10.0.0

package/README.md

@@ -4,8 +4,6 @@
 
 # mujoco-react
 
-> **Beta** — This library is under active development. The API may change between minor versions until 10.0.
-
 Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper around the official [@mujoco/mujoco](https://www.npmjs.com/package/@mujoco/mujoco) WASM bindings. Load any MuJoCo model, step physics, render bodies, and write controllers as React components.
 
 [![npm](https://img.shields.io/npm/v/mujoco-react)](https://www.npmjs.com/package/mujoco-react)
@@ -20,7 +18,7 @@ npm install mujoco-react three @react-three/fiber @react-three/drei
 
 ## Vite Plugin and Type-Safe Names
 
-Use the Vite plugin to generate TanStack-style declaration merging for actuator, sensor, body, joint, site, geom, and keyframe names:
+Use the Vite plugin to generate declaration merging for actuator, sensor, body, joint, site, geom, and keyframe names:
 
 ```ts
 // vite.config.ts
@@ -44,9 +42,9 @@ The plugin writes `src/mujoco-register.gen.ts` during dev and build. Commit that
 // src/mujoco-register.gen.ts
 // Auto-generated by mujoco-react. Do not edit.
 
-import { registerRobotResources } from "mujoco-react";
+import { registerModelResources } from "mujoco-react";
 
-const generatedRobotResources = {
+const generatedModelResources = {
   franka: {
     actuators: { joint1: "joint1", joint2: "joint2", joint3: "joint3", gripper: "gripper" },
     sensors: { force_sensor: "force_sensor", torque_sensor: "torque_sensor" },
@@ -58,11 +56,11 @@ const generatedRobotResources = {
   },
 };
 
-registerRobotResources(generatedRobotResources);
+registerModelResources(generatedModelResources);
 
 declare module "mujoco-react" {
   interface Register {
-    robots: {
+    models: {
       franka: {
         actuators: "joint1" | "joint2" | "joint3" | "gripper";
         sensors: "force_sensor" | "torque_sensor";
@@ -80,7 +78,7 @@ declare module "mujoco-react" {
 }
 ```
 
-Once generated, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API methods like `setCtrl`, `applyForce`, `getSensorData` accept the global union. For robot-scoped code, use package exports such as `RobotActuators.franka.gripper`, `RobotSites.franka.tcp`, and `RobotBodies.franka.hand`. Generic type helpers like `RobotActuators<"franka">` are still available for reusable library code. When no `Register` augmentation is present, names fall back to `string`.
+Once generated, hooks like `useCtrl`, `useSensor`, `useBodyState`, and API methods like `setCtrl`, `applyForce`, `getSensorData` accept the global union. For model-scoped code, use package exports such as `ModelActuators.franka.gripper`, `ModelSites.franka.tcp`, and `ModelBodies.franka.hand`. Generic type helpers like `ModelActuators<"franka">` are still available for reusable library code. When no `Register` augmentation is present, names fall back to `string`.
 
 Non-Vite projects can generate the same file with:
 
@@ -117,10 +115,10 @@ export function App() {
 
 ```tsx
 import { OrbitControls } from "@react-three/drei";
-import { IkGizmo, RobotSites, useIkController } from "mujoco-react";
+import { IkGizmo, ModelSites, useIkController } from "mujoco-react";
 
 function PandaTools() {
-  const ik = useIkController({ siteName: RobotSites.franka.tcp });
+  const ik = useIkController({ siteName: ModelSites.franka.tcp });
 
   return (
     <>
@@ -311,10 +309,10 @@ Tune live rendering and snapshots separately with `renderTuning` and
 ## Write Controllers
 
 ```tsx
-import { RobotActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";
+import { ModelActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";
 
 function MyController() {
-  const shoulder = useCtrl(RobotActuators.franka.actuator1);
+  const shoulder = useCtrl(ModelActuators.franka.actuator1);
 
   useBeforePhysicsStep(({ data }) => {
     shoulder.write(Math.sin(data.time));
@@ -329,29 +327,29 @@ Controllers are just React children that read sensors, write named controls, app
 With generated resource values, reusable controllers can be scoped to one robot without hand-typing names:
 
 ```tsx
-import { RobotActuators, RobotJoints, RobotSites, useCtrl, useIkController } from "mujoco-react";
+import { ModelActuators, ModelJoints, ModelSites, useCtrl, useIkController } from "mujoco-react";
 
 function FrankaTypedControls() {
-  const gripper = useCtrl(RobotActuators.franka.gripper);
+  const gripper = useCtrl(ModelActuators.franka.gripper);
   const ik = useIkController({
-    siteName: RobotSites.franka.tcp,
+    siteName: ModelSites.franka.tcp,
     joints: [
-      RobotJoints.franka.joint1,
-      RobotJoints.franka.joint2,
-      RobotJoints.franka.joint3,
-      RobotJoints.franka.joint4,
-      RobotJoints.franka.joint5,
-      RobotJoints.franka.joint6,
-      RobotJoints.franka.joint7,
+      ModelJoints.franka.joint1,
+      ModelJoints.franka.joint2,
+      ModelJoints.franka.joint3,
+      ModelJoints.franka.joint4,
+      ModelJoints.franka.joint5,
+      ModelJoints.franka.joint6,
+      ModelJoints.franka.joint7,
     ],
     actuators: [
-      RobotActuators.franka.actuator1,
-      RobotActuators.franka.actuator2,
-      RobotActuators.franka.actuator3,
-      RobotActuators.franka.actuator4,
-      RobotActuators.franka.actuator5,
-      RobotActuators.franka.actuator6,
-      RobotActuators.franka.actuator7,
+      ModelActuators.franka.actuator1,
+      ModelActuators.franka.actuator2,
+      ModelActuators.franka.actuator3,
+      ModelActuators.franka.actuator4,
+      ModelActuators.franka.actuator5,
+      ModelActuators.franka.actuator6,
+      ModelActuators.franka.actuator7,
     ],
   });
 
@@ -378,14 +376,14 @@ Use control groups when a robot's actuator order does not match a simple `qpos[0
 
 ```tsx
 import { useRef } from "react";
-import { resolveControlGroup, RobotSites, useBeforePhysicsStep } from "mujoco-react";
+import { resolveControlGroup, ModelSites, useBeforePhysicsStep } from "mujoco-react";
 import type { ControlGroupInfo } from "mujoco-react";
 
 function HoldTcpPose() {
   const armRef = useRef<ControlGroupInfo | null>(null);
 
   useBeforePhysicsStep(({ model, data }) => {
-    armRef.current ??= resolveControlGroup(model, { siteName: RobotSites.franka.tcp });
+    armRef.current ??= resolveControlGroup(model, { siteName: ModelSites.franka.tcp });
     if (!armRef.current) return;
 
     armRef.current.writeCtrl(data, armRef.current.readQpos(data));
@@ -489,7 +487,7 @@ For reusable controllers with typed config, default merging, and children, use t
 
 ```tsx
 import {
-  RobotActuators,
+  ModelActuators,
   createController,
   useBeforePhysicsStep,
   useCtrl,
@@ -498,7 +496,7 @@ import {
 export const MyController = createController<{ gain: number }>(
   { name: "MyController", defaultConfig: { gain: 1.0 } },
   ({ config, children }) => {
-    const shoulder = useCtrl(RobotActuators.franka.actuator1);
+    const shoulder = useCtrl(ModelActuators.franka.actuator1);
 
     useBeforePhysicsStep(({ data }) => {
       shoulder.write(config.gain * Math.sin(data.time));
@@ -535,14 +533,14 @@ A `createControllerHook` factory is also available for the hook equivalent — s
 The built-in `useIkController()` uses Damped Least-Squares. Pass `ikSolveFn` to swap in your own solver (analytical, learned, etc.):
 
 ```tsx
-import { RobotSites } from "mujoco-react";
+import { ModelSites } from "mujoco-react";
 import type { IKSolveFn } from "mujoco-react";
 
 const myIK: IKSolveFn = ({ position, currentQ }) => {
   return myAnalyticalSolver(position, currentQ); // return joint angles or null
 };
 
-const ik = useIkController({ siteName: RobotSites.franka.tcp, ikSolveFn: myIK });
+const ik = useIkController({ siteName: ModelSites.franka.tcp, ikSolveFn: myIK });
 ```
 
 ### `useIkController(config | null)`
@@ -550,9 +548,9 @@ const ik = useIkController({ siteName: RobotSites.franka.tcp, ikSolveFn: myIK })
 Hook for interactive end-effector control. Pass `null` to disable IK (safe to call unconditionally):
 
 ```tsx
-import { IkGizmo, RobotSites, useIkController } from "mujoco-react";
+import { IkGizmo, ModelSites, useIkController } from "mujoco-react";
 
-const ik = useIkController({ siteName: RobotSites.franka.tcp });
+const ik = useIkController({ siteName: ModelSites.franka.tcp });
 return ik ? <IkGizmo controller={ik} /> : null;
 ```
 
@@ -573,31 +571,31 @@ Pass the returned value to `<IkGizmo controller={ik} />` or to your own controll
 By default the controller infers scalar hinge/slide joints by walking from the site body toward the model root. For robots where the MJCF control layout is not a simple chain, pass explicit names:
 
 ```tsx
-import { RobotActuators, RobotJoints, RobotSites } from "mujoco-react";
+import { ModelActuators, ModelJoints, ModelSites } from "mujoco-react";
 
 const leftArmIk = useIkController({
-  siteName: RobotSites.franka.tcp,
+  siteName: ModelSites.franka.tcp,
   joints: [
-    RobotJoints.franka.joint1,
-    RobotJoints.franka.joint2,
-    RobotJoints.franka.joint3,
-    RobotJoints.franka.joint4,
-    RobotJoints.franka.joint5,
-    RobotJoints.franka.joint6,
-    RobotJoints.franka.joint7,
+    ModelJoints.franka.joint1,
+    ModelJoints.franka.joint2,
+    ModelJoints.franka.joint3,
+    ModelJoints.franka.joint4,
+    ModelJoints.franka.joint5,
+    ModelJoints.franka.joint6,
+    ModelJoints.franka.joint7,
   ],
 });
 
 const gripperIk = useIkController({
-  siteName: RobotSites.franka.tcp,
+  siteName: ModelSites.franka.tcp,
   actuators: [
-    RobotActuators.franka.actuator1,
-    RobotActuators.franka.actuator2,
-    RobotActuators.franka.actuator3,
-    RobotActuators.franka.actuator4,
-    RobotActuators.franka.actuator5,
-    RobotActuators.franka.actuator6,
-    RobotActuators.franka.actuator7,
+    ModelActuators.franka.actuator1,
+    ModelActuators.franka.actuator2,
+    ModelActuators.franka.actuator3,
+    ModelActuators.franka.actuator4,
+    ModelActuators.franka.actuator5,
+    ModelActuators.franka.actuator6,
+    ModelActuators.franka.actuator7,
   ],
 });
 ```
@@ -934,9 +932,9 @@ if (mujoco) {
 Run logic **before** `mj_step` each frame. Write to `data.ctrl`, apply forces, drive automation.
 
 ```tsx
-import { RobotActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";
+import { ModelActuators, useBeforePhysicsStep, useCtrl } from "mujoco-react";
 
-const shoulder = useCtrl(RobotActuators.franka.actuator1);
+const shoulder = useCtrl(ModelActuators.franka.actuator1);
 
 useBeforePhysicsStep(({ data }) => {
   shoulder.write(Math.sin(data.time));
@@ -971,9 +969,9 @@ await moveCameraTo(
 Read sensor values by name. Returns a `SensorHandle` with `read()`, `dim`, and `name`:
 
 ```tsx
-import { RobotSensors, useSensor } from "mujoco-react";
+import { ModelSensors, useSensor } from "mujoco-react";
 
-const imu = useSensor(RobotSensors.g1["imu-torso-angular-velocity"]);
+const imu = useSensor(ModelSensors.g1["imu-torso-angular-velocity"]);
 // imu.read() -> Float64Array, imu.dim -> number
 ```
 
@@ -998,9 +996,9 @@ const { position, velocity } = useJointState("joint1");
 Read/write actuator control by name. Returns a `CtrlHandle` with `read()`, `write()`, `name`, and `range`:
 
 ```tsx
-import { RobotActuators, useCtrl } from "mujoco-react";
+import { ModelActuators, useCtrl } from "mujoco-react";
 
-const gripper = useCtrl(RobotActuators.franka.gripper);
+const gripper = useCtrl(ModelActuators.franka.gripper);
 // gripper.read() -> number, gripper.write(0.04), gripper.range -> [min, max]
 ```
 
@@ -1020,13 +1018,13 @@ useContactEvents("block_1", {
 Map keyboard keys to actuators:
 
 ```tsx
-import { RobotActuators, useKeyboardTeleop } from "mujoco-react";
+import { ModelActuators, useKeyboardTeleop } from "mujoco-react";
 
 useKeyboardTeleop({
   bindings: {
     "w": { actuator: "forward", delta: 0.1 },
     "s": { actuator: "forward", delta: -0.1 },
-    "v": { actuator: RobotActuators.franka.gripper, toggle: [0, 0.04] },
+    "v": { actuator: ModelActuators.franka.gripper, toggle: [0, 0.04] },
   },
 });
 ```

package/dist/{chunk-6MOK6ZWB.js → chunk-QTCAVQS6.js}

@@ -4,7 +4,7 @@ import { useMemo, useEffect } from 'react';
 import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
 
 // src/types.ts
-var runtimeRobotResources = {};
+var runtimeModelResources = {};
 var REGISTER_RESOURCE_KEYS = ["actuators", "sensors", "bodies", "joints", "sites", "geoms", "keyframes", "cameras"];
 function createEmptyRuntimeResources() {
   return {
@@ -18,51 +18,51 @@ function createEmptyRuntimeResources() {
     cameras: {}
   };
 }
-function registerRobotResources(resources) {
-  for (const [robot, robotResources] of Object.entries(resources)) {
-    const existing = runtimeRobotResources[robot] ?? createEmptyRuntimeResources();
+function registerModelResources(resources) {
+  for (const [model, modelResources] of Object.entries(resources)) {
+    const existing = runtimeModelResources[model] ?? createEmptyRuntimeResources();
     for (const key of REGISTER_RESOURCE_KEYS) {
-      existing[key] = { ...existing[key], ...robotResources[key] ?? {} };
+      existing[key] = { ...existing[key], ...modelResources[key] ?? {} };
     }
-    runtimeRobotResources[robot] = existing;
+    runtimeModelResources[model] = existing;
   }
 }
 function createResourceCategory(key) {
   return new Proxy({}, {
-    get(_target, robot) {
-      if (typeof robot !== "string") return void 0;
-      return runtimeRobotResources[robot]?.[key] ?? {};
+    get(_target, model) {
+      if (typeof model !== "string") return void 0;
+      return runtimeModelResources[model]?.[key] ?? {};
     },
     ownKeys() {
-      return Reflect.ownKeys(runtimeRobotResources);
+      return Reflect.ownKeys(runtimeModelResources);
     },
-    getOwnPropertyDescriptor(_target, robot) {
-      if (typeof robot !== "string" || !(robot in runtimeRobotResources)) return void 0;
+    getOwnPropertyDescriptor(_target, model) {
+      if (typeof model !== "string" || !(model in runtimeModelResources)) return void 0;
       return { enumerable: true, configurable: true };
     }
   });
 }
-var RobotResources = new Proxy(runtimeRobotResources, {
-  get(target, robot) {
-    if (typeof robot !== "string") return void 0;
-    return target[robot] ?? createEmptyRuntimeResources();
+var ModelResources = new Proxy(runtimeModelResources, {
+  get(target, model) {
+    if (typeof model !== "string") return void 0;
+    return target[model] ?? createEmptyRuntimeResources();
   },
   ownKeys(target) {
     return Reflect.ownKeys(target);
   },
-  getOwnPropertyDescriptor(target, robot) {
-    if (typeof robot !== "string" || !(robot in target)) return void 0;
+  getOwnPropertyDescriptor(target, model) {
+    if (typeof model !== "string" || !(model in target)) return void 0;
     return { enumerable: true, configurable: true };
   }
 });
-var RobotActuators = createResourceCategory("actuators");
-var RobotSensors = createResourceCategory("sensors");
-var RobotBodies = createResourceCategory("bodies");
-var RobotJoints = createResourceCategory("joints");
-var RobotSites = createResourceCategory("sites");
-var RobotGeoms = createResourceCategory("geoms");
-var RobotKeyframes = createResourceCategory("keyframes");
-var RobotCameras = createResourceCategory("cameras");
+var ModelActuators = createResourceCategory("actuators");
+var ModelSensors = createResourceCategory("sensors");
+var ModelBodies = createResourceCategory("bodies");
+var ModelJoints = createResourceCategory("joints");
+var ModelSites = createResourceCategory("sites");
+var ModelGeoms = createResourceCategory("geoms");
+var ModelKeyframes = createResourceCategory("keyframes");
+var ModelCameras = createResourceCategory("cameras");
 function getContact(contacts, i) {
   try {
     return contacts.get(i);
@@ -1077,6 +1077,6 @@ function clamp01(value) {
  * Offscreen camera-frame capture for R3F/MuJoCo scenes.
  */
 
-export { CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, RobotActuators, RobotBodies, RobotCameras, RobotGeoms, RobotJoints, RobotKeyframes, RobotResources, RobotSensors, RobotSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, registerRobotResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withContacts, withSplatEnvironment };
-//# sourceMappingURL=chunk-6MOK6ZWB.js.map
-//# sourceMappingURL=chunk-6MOK6ZWB.js.map
+export { CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, ModelActuators, ModelBodies, ModelCameras, ModelGeoms, ModelJoints, ModelKeyframes, ModelResources, ModelSensors, ModelSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withContacts, withSplatEnvironment };
+//# sourceMappingURL=chunk-QTCAVQS6.js.map
+//# sourceMappingURL=chunk-QTCAVQS6.js.map