mujoco-react 8.1.1 → 8.2.0

package/README.md

@@ -8,7 +8,9 @@
 
 Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) wrapper around [mujoco-js](https://www.npmjs.com/package/mujoco-js). Load any MuJoCo model, step physics, render bodies, and write controllers as React components.
 
-**[Demo](https://mujoco-react-example.pages.dev)** | **[Docs](https://dadd.mintlify.app)** | **[Example Source](https://github.com/noah-wardlow/mujoco-react-example)** | **[llms.txt](https://dadd.mintlify.app/llms.txt)**
+[![npm](https://img.shields.io/npm/v/mujoco-react)](https://www.npmjs.com/package/mujoco-react)
+
+**[Demo](https://mujoco-react-example.pages.dev)** | **[Docs](https://dadd.mintlify.app)** | **[npm](https://www.npmjs.com/package/mujoco-react)** | **[Example Source](https://github.com/noah-wardlow/mujoco-react-example)** | **[llms.txt](https://dadd.mintlify.app/llms.txt)**
 
 ## Install
 
@@ -111,22 +113,45 @@ Drop it into the tree:
 </MujocoCanvas>
 ```
 
-The `createController<TConfig>()` factory adds typed config and default merging for reusable plugins:
+The `createControllerHook` factory produces a typed hook with config stabilization and default merging. Pass `null` to disable:
+
+```tsx
+import { createControllerHook, useBeforePhysicsStep } from "mujoco-react";
+
+export const useMyController = createControllerHook<{ gain: number }, { value: number }>(
+  { name: "useMyController", defaultConfig: { gain: 1.0 } },
+  (config) => {
+    useBeforePhysicsStep((_model, data) => {
+      if (!config) return;
+      data.ctrl[0] = config.gain * Math.sin(data.time);
+    });
+    if (!config) return null;
+    return { value: config.gain };
+  },
+);
+
+// const result = useMyController({ gain: 2.0 });
+// const disabled = useMyController(null); // returns null
+```
+
+The `createController` factory is the component equivalent — same config stabilization, but returns a component that can render children:
 
 ```tsx
-import { createController, useBeforePhysicsStep } from "mujoco-react";
+import { createController, useBeforePhysicsStep, Debug } from "mujoco-react";
 
 export const MyController = createController<{ gain: number }>(
   { name: "MyController", defaultConfig: { gain: 1.0 } },
-  ({ config }) => {
+  ({ config, children }) => {
     useBeforePhysicsStep((_model, data) => {
       data.ctrl[0] = config.gain * Math.sin(data.time);
     });
-    return null;
+    return <>{children}</>;
   },
 );
 
-// <MyController config={{ gain: 2.0 }} />
+// <MyController config={{ gain: 2.0 }}>
+//   <Debug showJoints />
+// </MyController>
 ```
 
 ## Architecture
@@ -727,7 +752,7 @@ The full API object available via `ref` or `useMujoco()` (when `isReady`):
 
 ### Building Controllers
 
-See [Building Controllers](https://dadd.mintlify.app/guides/building-controllers) for full patterns including config-driven controllers, IK gizmo coexistence, multi-arm support, and the `createController` factory.
+See [Building Controllers](https://dadd.mintlify.app/guides/building-controllers) for full patterns including config-driven controllers, IK gizmo coexistence, multi-arm support, and the `createControllerHook`/`createController` factories.
 
 ### Contact Parameters
 

package/dist/index.d.ts

@@ -790,6 +790,33 @@ declare function createController<TConfig>(options: ControllerOptions<TConfig>,
     config: TConfig;
     children?: React.ReactNode;
 }>): ControllerComponent<TConfig>;
+/**
+ * Factory that produces a typed controller hook.
+ *
+ * Same config stabilization and default merging as `createController`,
+ * but returns a hook instead of a component. Pass `null` to disable.
+ *
+ * @example
+ * ```tsx
+ * const useMyController = createControllerHook<MyConfig, MyValue>(
+ *   { name: 'useMyController', defaultConfig: { gain: 1.0 } },
+ *   function useMyControllerImpl(config) {
+ *     // config is MyConfig | null — hooks must be called unconditionally
+ *     useBeforePhysicsStep((_model, data) => {
+ *       if (!config) return;
+ *       data.ctrl[0] = config.gain * Math.sin(data.time);
+ *     });
+ *     if (!config) return null;
+ *     return { /* value *\/ };
+ *   },
+ * );
+ *
+ * // Usage:
+ * const value = useMyController({ gain: 2.0 });
+ * const disabled = useMyController(null); // returns null
+ * ```
+ */
+declare function createControllerHook<TConfig, TValue>(options: ControllerOptions<TConfig>, useImpl: (config: TConfig | null) => TValue | null): (config: TConfig | null) => TValue | null;
 
 /**
  * @license
@@ -1274,4 +1301,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-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 };
+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, createControllerHook, 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 };

package/dist/index.js

@@ -4176,6 +4176,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, 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 { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, createController, createControllerHook, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

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

package/src/index.ts

@@ -23,7 +23,7 @@ export {
 } from './core/SceneLoader';
 
 // Controller factory
-export { createController } from './core/createController';
+export { createController, createControllerHook } from './core/createController';
 export type { ControllerOptions, ControllerComponent } from './core/createController';
 
 // IK controller hook