mujoco-react 8.7.0 → 8.9.0

package/README.md

@@ -39,13 +39,36 @@ export default defineConfig({
 });
 ```
 
-The plugin writes `src/mujoco-register.gen.d.ts` during dev and build. Commit that generated file:
+The plugin writes `src/mujoco-register.gen.ts` during dev and build. Commit that generated file. Vite auto-loads it, so app code imports generated values from `mujoco-react`, not from the generated file:
 
 ```ts
-// src/mujoco-register.gen.d.ts
+// src/mujoco-register.gen.ts
 // Auto-generated by mujoco-react. Do not edit.
 
-import "mujoco-react";
+import { registerRobotResources } from "mujoco-react";
+
+const generatedRobotResources = {
+  franka: {
+    actuators: { joint1: "joint1", joint2: "joint2", joint3: "joint3", gripper: "gripper" },
+    sensors: { force_sensor: "force_sensor", torque_sensor: "torque_sensor" },
+    bodies: { link0: "link0", link1: "link1", hand: "hand" },
+    joints: { joint1: "joint1", joint2: "joint2", joint3: "joint3" },
+    sites: { tcp: "tcp" },
+    geoms: { floor: "floor" },
+    keyframes: { home: "home" },
+  },
+  spot: {
+    actuators: { fl_hx: "fl_hx", fl_hy: "fl_hy", fl_kn: "fl_kn" },
+    sensors: {},
+    bodies: { body: "body", fl_hip: "fl_hip", fl_uleg: "fl_uleg" },
+    joints: { fl_hx: "fl_hx", fl_hy: "fl_hy", fl_kn: "fl_kn" },
+    sites: {},
+    geoms: { floor: "floor" },
+    keyframes: { home: "home" },
+  },
+};
+
+registerRobotResources(generatedRobotResources);
 
 declare module "mujoco-react" {
   interface Register {
@@ -76,7 +99,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 reusable code, use helpers such as `RobotActuators<"franka">`, `RobotSites<"franka">`, and `RobotBodies<"franka">`. 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 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`.
 
 Non-Vite projects can generate the same file with:
 
@@ -113,10 +136,10 @@ export function App() {
 
 ```tsx
 import { OrbitControls } from "@react-three/drei";
-import { IkGizmo, useIkController } from "mujoco-react";
+import { IkGizmo, RobotSites, useIkController } from "mujoco-react";
 
 function PandaTools() {
-  const ik = useIkController({ siteName: "tcp" });
+  const ik = useIkController({ siteName: RobotSites.franka.tcp });
 
   return (
     <>
@@ -153,18 +176,34 @@ function MyController() {
 
 Controllers are just React children that read sensors, write `data.ctrl`, apply forces, or call the `MujocoSimAPI` at physics-step time.
 
-With generated resource types, reusable controllers can be scoped to one robot. Configure stable robot keys in the Vite plugin, then use those keys in helper types:
+With generated resource values, reusable controllers can be scoped to one robot without hand-typing names:
 
 ```tsx
-import { useCtrl, useIkController } from "mujoco-react";
-import type { RobotActuators, RobotSites } from "mujoco-react";
-
-const frankaGripper = "gripper" satisfies RobotActuators<"franka">;
-const frankaTcp = "tcp" satisfies RobotSites<"franka">;
+import { RobotActuators, RobotJoints, RobotSites, useCtrl, useIkController } from "mujoco-react";
 
 function FrankaTypedControls() {
-  const gripper = useCtrl(frankaGripper);
-  const ik = useIkController({ siteName: frankaTcp });
+  const gripper = useCtrl(RobotActuators.franka.gripper);
+  const ik = useIkController({
+    siteName: RobotSites.franka.tcp,
+    joints: [
+      RobotJoints.franka.joint1,
+      RobotJoints.franka.joint2,
+      RobotJoints.franka.joint3,
+      RobotJoints.franka.joint4,
+      RobotJoints.franka.joint5,
+      RobotJoints.franka.joint6,
+      RobotJoints.franka.joint7,
+    ],
+    actuators: [
+      RobotActuators.franka.actuator1,
+      RobotActuators.franka.actuator2,
+      RobotActuators.franka.actuator3,
+      RobotActuators.franka.actuator4,
+      RobotActuators.franka.actuator5,
+      RobotActuators.franka.actuator6,
+      RobotActuators.franka.actuator7,
+    ],
+  });
 
   return null;
 }
@@ -341,13 +380,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 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", ikSolveFn: myIK });
+const ik = useIkController({ siteName: RobotSites.franka.tcp, ikSolveFn: myIK });
 ```
 
 ### `useIkController(config | null)`
@@ -355,7 +395,9 @@ const ik = useIkController({ siteName: "tcp", ikSolveFn: myIK });
 Hook for interactive end-effector control. Pass `null` to disable IK (safe to call unconditionally):
 
 ```tsx
-const ik = useIkController({ siteName: "tcp" });
+import { IkGizmo, RobotSites, useIkController } from "mujoco-react";
+
+const ik = useIkController({ siteName: RobotSites.franka.tcp });
 return ik ? <IkGizmo controller={ik} /> : null;
 ```
 
@@ -376,14 +418,32 @@ 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";
+
 const leftArmIk = useIkController({
-  siteName: "left_tcp",
-  joints: ["left_shoulder", "left_elbow", "left_wrist"],
+  siteName: RobotSites.franka.tcp,
+  joints: [
+    RobotJoints.franka.joint1,
+    RobotJoints.franka.joint2,
+    RobotJoints.franka.joint3,
+    RobotJoints.franka.joint4,
+    RobotJoints.franka.joint5,
+    RobotJoints.franka.joint6,
+    RobotJoints.franka.joint7,
+  ],
 });
 
 const gripperIk = useIkController({
-  siteName: "tcp",
-  actuators: /^actuator/,
+  siteName: RobotSites.franka.tcp,
+  actuators: [
+    RobotActuators.franka.actuator1,
+    RobotActuators.franka.actuator2,
+    RobotActuators.franka.actuator3,
+    RobotActuators.franka.actuator4,
+    RobotActuators.franka.actuator5,
+    RobotActuators.franka.actuator6,
+    RobotActuators.franka.actuator7,
+  ],
 });
 ```
 
@@ -424,15 +484,22 @@ interface SceneConfig {
 Load browser-selected MJCF or URDF files directly. Folder uploads preserve `webkitRelativePath`, and flat uploads fall back to matching referenced mesh/texture assets by basename:
 
 ```tsx
+import { useEffect, useRef } from "react";
+import { useMujoco } from "mujoco-react";
+
 function ModelUpload() {
   const sim = useMujoco();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  useEffect(() => {
+    inputRef.current?.setAttribute("webkitdirectory", "");
+  }, []);
 
   return (
     <input
+      ref={inputRef}
       type="file"
       multiple
-      // @ts-expect-error Chromium/WebKit folder uploads
-      webkitdirectory=""
       onChange={(event) => {
         if (sim.isReady && event.currentTarget.files) {
           sim.api.loadFromFiles(event.currentTarget.files);

package/bin/mujoco-react.mjs

@@ -5,7 +5,7 @@ import { generateMujocoRegister } from '../dist/vite.js';
 
 const usage = `
 Usage:
-  mujoco-react codegen <scene.xml> [...more.xml] [--out src/mujoco-register.gen.d.ts] [--watch]
+  mujoco-react codegen <scene.xml> [...more.xml] [--out src/mujoco-register.gen.ts] [--watch]
   mujoco-react codegen franka=models/panda/scene.xml spot=models/spot/scene.xml
 
 Vite users usually do not need this command. Prefer:
@@ -32,7 +32,7 @@ if (command !== 'codegen') {
 }
 
 const commandArgs = args.slice(1);
-const out = valueAfter(commandArgs, '--out') ?? 'src/mujoco-register.gen.d.ts';
+const out = valueAfter(commandArgs, '--out') ?? 'src/mujoco-register.gen.ts';
 const moduleName = valueAfter(commandArgs, '--module') ?? 'mujoco-react';
 const shouldWatch = commandArgs.includes('--watch');
 const models = commandArgs.filter((arg, index) => {

package/dist/index.d.ts

@@ -41,13 +41,35 @@ type Robots = [RegisteredRobotMap] extends [never] ? string : Extract<keyof Regi
 type RobotResource<TRobot extends string, TKey extends string> = [
     RegisteredRobotMap
 ] extends [never] ? string : TRobot extends keyof RegisteredRobotMap ? TKey extends keyof RegisteredRobotMap[TRobot] ? RegisteredRobotMap[TRobot][TKey] : string : never;
+type RegisterResourceKey = 'actuators' | 'sensors' | 'bodies' | 'joints' | 'sites' | 'geoms' | 'keyframes';
+type RobotResourceObject<TRobot extends string, TKey extends RegisterResourceKey> = string extends RobotResource<TRobot, TKey> ? Record<string, string> : {
+    readonly [K in RobotResource<TRobot, TKey>]: K;
+};
+type RobotResourceCategory<TKey extends RegisterResourceKey> = string extends Robots ? Record<string, Record<string, string>> : {
+    readonly [TRobot in Robots]: RobotResourceObject<TRobot, TKey>;
+};
+type RobotResourceRegistry = string extends Robots ? Record<string, Record<RegisterResourceKey, Record<string, string>>> : {
+    readonly [TRobot in Robots]: {
+        readonly [TKey in RegisterResourceKey]: RobotResourceObject<TRobot, TKey>;
+    };
+};
+type RuntimeRobotResourceRegistration = Readonly<Record<string, Readonly<Record<RegisterResourceKey, Readonly<Record<string, string>>>>>>;
+declare function registerRobotResources(resources: RuntimeRobotResourceRegistration): void;
+declare const RobotResources: RobotResourceRegistry;
 type RobotActuators<TRobot extends string> = RobotResource<TRobot, 'actuators'>;
+declare const RobotActuators: RobotResourceCategory<'actuators'>;
 type RobotSensors<TRobot extends string> = RobotResource<TRobot, 'sensors'>;
+declare const RobotSensors: RobotResourceCategory<'sensors'>;
 type RobotBodies<TRobot extends string> = RobotResource<TRobot, 'bodies'>;
+declare const RobotBodies: RobotResourceCategory<'bodies'>;
 type RobotJoints<TRobot extends string> = RobotResource<TRobot, 'joints'>;
+declare const RobotJoints: RobotResourceCategory<'joints'>;
 type RobotSites<TRobot extends string> = RobotResource<TRobot, 'sites'>;
+declare const RobotSites: RobotResourceCategory<'sites'>;
 type RobotGeoms<TRobot extends string> = RobotResource<TRobot, 'geoms'>;
+declare const RobotGeoms: RobotResourceCategory<'geoms'>;
 type RobotKeyframes<TRobot extends string> = RobotResource<TRobot, 'keyframes'>;
+declare const RobotKeyframes: RobotResourceCategory<'keyframes'>;
 type Actuators = Register extends {
     actuators: infer T extends string;
 } ? T : string;
@@ -1504,4 +1526,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { type ActuatedJointInfo, type ActuatorInfo, type Actuators, type Bodies, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControlGroupInfo, type ControlGroupSelector, type ControlJointInfo, 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, InstancedGeomRenderer, 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 MujocoLoader, type MujocoLoaderOptions, type MujocoModel, type MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoProviderProps, type MujocoSimAPI, MujocoSimProvider, type MujocoWasmVariant, type ObservationConfig, type ObservationHandle, type ObservationLayoutItem, type ObservationOutput, type ObservationResult, type PhysicsConfig, type PhysicsStepCallback, type PlaybackState, type PolicyConfig, type RayHit, type Register, type RegisteredRobotMap, type ResourceSelector, type RobotActuators, type RobotBodies, type RobotGeoms, type RobotJoints, type RobotKeyframes, type RobotResource, type RobotSensors, type RobotSites, type Robots, 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, buildObservation, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { type ActuatedJointInfo, type ActuatorInfo, type Actuators, type Bodies, Body, type BodyInfo, type BodyProps, type BodyStateResult, type CameraAnimationAPI, type ContactInfo, ContactListener, type ContactListenerProps, ContactMarkers, type ControlGroupInfo, type ControlGroupSelector, type ControlJointInfo, 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, InstancedGeomRenderer, 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 MujocoLoader, type MujocoLoaderOptions, type MujocoModel, type MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoProviderProps, type MujocoSimAPI, MujocoSimProvider, type MujocoWasmVariant, type ObservationConfig, type ObservationHandle, type ObservationLayoutItem, type ObservationOutput, type ObservationResult, type PhysicsConfig, type PhysicsStepCallback, type PlaybackState, type PolicyConfig, type RayHit, type Register, type RegisteredRobotMap, type ResourceSelector, RobotActuators, RobotBodies, RobotGeoms, RobotJoints, RobotKeyframes, type RobotResource, RobotResources, RobotSensors, RobotSites, type Robots, 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, buildObservation, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, registerRobotResources, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };

package/dist/index.js

@@ -106,6 +106,63 @@ function MujocoProvider({
 }
 
 // src/types.ts
+var runtimeRobotResources = {};
+var REGISTER_RESOURCE_KEYS = ["actuators", "sensors", "bodies", "joints", "sites", "geoms", "keyframes"];
+function createEmptyRuntimeResources() {
+  return {
+    actuators: {},
+    sensors: {},
+    bodies: {},
+    joints: {},
+    sites: {},
+    geoms: {},
+    keyframes: {}
+  };
+}
+function registerRobotResources(resources) {
+  for (const [robot, robotResources] of Object.entries(resources)) {
+    const existing = runtimeRobotResources[robot] ?? createEmptyRuntimeResources();
+    for (const key of REGISTER_RESOURCE_KEYS) {
+      existing[key] = { ...existing[key], ...robotResources[key] ?? {} };
+    }
+    runtimeRobotResources[robot] = existing;
+  }
+}
+function createResourceCategory(key) {
+  return new Proxy({}, {
+    get(_target, robot) {
+      if (typeof robot !== "string") return void 0;
+      return runtimeRobotResources[robot]?.[key] ?? {};
+    },
+    ownKeys() {
+      return Reflect.ownKeys(runtimeRobotResources);
+    },
+    getOwnPropertyDescriptor(_target, robot) {
+      if (typeof robot !== "string" || !(robot in runtimeRobotResources)) 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();
+  },
+  ownKeys(target) {
+    return Reflect.ownKeys(target);
+  },
+  getOwnPropertyDescriptor(target, robot) {
+    if (typeof robot !== "string" || !(robot 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");
 function getContact(contacts, i) {
   try {
     return contacts.get(i);
@@ -5045,6 +5102,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, InstancedGeomRenderer, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, buildObservation, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, InstancedGeomRenderer, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, RobotActuators, RobotBodies, RobotGeoms, RobotJoints, RobotKeyframes, RobotResources, RobotSensors, RobotSites, SceneLights, TendonRenderer, TrajectoryPlayer, buildObservation, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, registerRobotResources, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map