mujoco-react 0.3.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,13 +34,12 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/noah/mujoco-react"
+    "url": "https://github.com/noah-wardlow/mujoco-react"
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
     "@react-three/drei": ">=9",
@@ -54,9 +53,12 @@
   "devDependencies": {
     "@react-three/drei": "^10.7.7",
     "@react-three/fiber": "^9.5.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
     "@types/react": "^19.0.0",
     "@types/three": "^0.181.0",
     "react": "^19.2.0",
+    "semantic-release": "^25.0.3",
     "three": "^0.181.0",
     "tsup": "^8.4.0",
     "typescript": "~5.8.2"

package/src/components/ContactMarkers.tsx

@@ -10,6 +10,7 @@
 
 import { useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
+import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoSim } from '../core/MujocoSimProvider';
 import { getContact } from '../types';
@@ -32,7 +33,8 @@ export function ContactMarkers({
   radius = 0.008,
   color = '#22d3ee',
   visible = true,
-}: ContactMarkersProps = {}) {
+  ...groupProps
+}: ContactMarkersProps & Omit<ThreeElements['group'], 'ref' | 'visible'> = {}) {
   const { mjDataRef, status } = useMujocoSim();
   const meshRef = useRef<THREE.InstancedMesh>(null);
 
@@ -66,9 +68,11 @@ export function ContactMarkers({
   if (status !== 'ready') return null;
 
   return (
-    <instancedMesh ref={meshRef} args={[undefined, undefined, maxContacts]} frustumCulled={false} renderOrder={999}>
-      <sphereGeometry args={[radius, 8, 8]} />
-      <meshBasicMaterial color={color} depthTest={false} />
-    </instancedMesh>
+    <group {...groupProps}>
+      <instancedMesh ref={meshRef} args={[undefined, undefined, maxContacts]} frustumCulled={false} renderOrder={999}>
+        <sphereGeometry args={[radius, 8, 8]} />
+        <meshBasicMaterial color={color} depthTest={false} />
+      </instancedMesh>
+    </group>
   );
 }

package/src/components/Debug.tsx

@@ -7,6 +7,7 @@
 
 import { useEffect, useMemo, useRef } from 'react';
 import { useFrame, useThree } from '@react-three/fiber';
+import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoSim } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
@@ -40,7 +41,8 @@ export function Debug({
   showCOM = false,
   showInertia = false,
   showTendons = false,
-}: DebugProps) {
+  ...groupProps
+}: DebugProps & Omit<ThreeElements['group'], 'ref'>) {
   const { mjModelRef, mjDataRef, status } = useMujocoSim();
   const { scene } = useThree();
   const groupRef = useRef<THREE.Group>(null);
@@ -354,9 +356,9 @@ export function Debug({
   if (status !== 'ready') return null;
 
   return (
-    <>
+    <group {...groupProps}>
       <group ref={groupRef} />
       {showContacts && <group ref={contactGroupRef} />}
-    </>
+    </group>
   );
 }

package/src/components/DragInteraction.tsx

@@ -4,6 +4,7 @@
  */
 
 import { useFrame, useThree } from '@react-three/fiber';
+import type { ThreeElements } from '@react-three/fiber';
 import { useEffect, useRef } from 'react';
 import * as THREE from 'three';
 import { useMujocoSim, useBeforePhysicsStep } from '../core/MujocoSimProvider';
@@ -35,7 +36,8 @@ const _mouse = new THREE.Vector2();
 export function DragInteraction({
   stiffness = 250,
   showArrow = true,
-}: DragInteractionProps) {
+  ...groupProps
+}: DragInteractionProps & Omit<ThreeElements['group'], 'ref'>) {
   const { mjDataRef, mujocoRef, mjModelRef, status } = useMujocoSim();
   const { gl, camera, scene, controls } = useThree();
 
@@ -223,5 +225,5 @@ export function DragInteraction({
 
   if (status !== 'ready') return null;
 
-  return <group ref={groupRef} />;
+  return <group {...groupProps} ref={groupRef} />;
 }

package/src/components/FlexRenderer.tsx

@@ -7,6 +7,7 @@
 
 import { useEffect, useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
+import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoSim } from '../core/MujocoSimProvider';
 
@@ -14,7 +15,7 @@ import { useMujocoSim } from '../core/MujocoSimProvider';
  * Renders MuJoCo flex (deformable) bodies as dynamic meshes.
  * Vertices are updated every frame from flexvert_xpos.
  */
-export function FlexRenderer() {
+export function FlexRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
   const { mjModelRef, mjDataRef, status } = useMujocoSim();
   const groupRef = useRef<THREE.Group>(null);
   const meshesRef = useRef<THREE.Mesh[]>([]);
@@ -98,5 +99,5 @@ export function FlexRenderer() {
   });
 
   if (status !== 'ready') return null;
-  return <group ref={groupRef} />;
+  return <group {...props} ref={groupRef} />;
 }

package/src/components/SceneRenderer.tsx

@@ -4,6 +4,7 @@
  */
 
 import { useFrame } from '@react-three/fiber';
+import type { ThreeElements } from '@react-three/fiber';
 import { useEffect, useMemo, useRef } from 'react';
 import * as THREE from 'three';
 import { GeomBuilder } from '../rendering/GeomBuilder';
@@ -13,9 +14,9 @@ import { useMujocoSim } from '../core/MujocoSimProvider';
 
 /**
  * SceneRenderer — creates and syncs MuJoCo body meshes every frame.
- * Replaces RenderSystem.initScene() + RenderSystem.update() body loop.
+ * Accepts standard R3F group props (position, rotation, scale, visible, etc.).
  */
-export function SceneRenderer() {
+export function SceneRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
   const { mjModelRef, mjDataRef, mujocoRef, onSelectionRef, status } = useMujocoSim();
   const groupRef = useRef<THREE.Group>(null);
   const bodyRefs = useRef<(THREE.Group | null)[]>([]);
@@ -85,8 +86,10 @@ export function SceneRenderer() {
 
   return (
     <group
+      {...props}
       ref={groupRef}
       onDoubleClick={(e) => {
+        if (typeof props.onDoubleClick === 'function') props.onDoubleClick(e);
         e.stopPropagation();
         let obj: THREE.Object3D | null = e.object;
         while (obj && obj.userData.bodyID === undefined && obj.parent) {

package/src/components/TendonRenderer.tsx

@@ -13,6 +13,7 @@
 
 import { useEffect, useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
+import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 import { useMujocoSim } from '../core/MujocoSimProvider';
 
@@ -22,7 +23,7 @@ const DEFAULT_TENDON_WIDTH = 0.002;
 // Preallocated temp vector to avoid per-frame allocations
 const _tmpVec = new THREE.Vector3();
 
-export function TendonRenderer() {
+export function TendonRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
   const { mjModelRef, mjDataRef, status } = useMujocoSim();
   const groupRef = useRef<THREE.Group>(null);
   const meshesRef = useRef<THREE.Mesh[]>([]);
@@ -144,5 +145,5 @@ export function TendonRenderer() {
   });
 
   if (status !== 'ready') return null;
-  return <group ref={groupRef} />;
+  return <group {...props} ref={groupRef} />;
 }

package/src/core/MujocoCanvas.tsx

@@ -24,15 +24,12 @@ export const MujocoCanvas = forwardRef<MujocoSimAPI, MujocoCanvasProps>(
       onError,
       onStep,
       onSelection,
-      // Declarative physics config (spec 1.1)
+      // Declarative physics config
       gravity,
       timestep,
       substeps,
       paused,
       speed,
-      interpolate,
-      gravityCompensation,
-      mjcfLights,
       children,
       ...canvasProps
     },
@@ -65,7 +62,6 @@ export const MujocoCanvas = forwardRef<MujocoSimAPI, MujocoCanvasProps>(
           substeps={substeps}
           paused={paused}
           speed={speed}
-          interpolate={interpolate}
         >
           {children}
         </MujocoSimProvider>

package/src/core/MujocoPhysics.tsx

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { forwardRef, useEffect } from 'react';
+import { useMujoco } from './MujocoProvider';
+import { MujocoSimProvider } from './MujocoSimProvider';
+import type { MujocoSimAPI, SceneConfig } from '../types';
+
+export interface MujocoPhysicsProps {
+  /** Scene/robot configuration. */
+  config: SceneConfig;
+  /** Fires when model is loaded and API is ready. */
+  onReady?: (api: MujocoSimAPI) => void;
+  /** Fires on scene load failure. */
+  onError?: (error: Error) => void;
+  /** Called each physics step. */
+  onStep?: (time: number) => void;
+  /** Called on body double-click selection. */
+  onSelection?: (bodyId: number, name: string) => void;
+  /** Override model gravity. */
+  gravity?: [number, number, number];
+  /** Override model.opt.timestep. */
+  timestep?: number;
+  /** mj_step calls per frame. */
+  substeps?: number;
+  /** Declarative pause. */
+  paused?: boolean;
+  /** Simulation speed multiplier. */
+  speed?: number;
+  children: React.ReactNode;
+}
+
+/**
+ * MujocoPhysics — physics provider for use inside a user-owned R3F Canvas.
+ *
+ * This is the R3F-idiomatic alternative to MujocoCanvas. Instead of wrapping
+ * the Canvas, place this inside your own <Canvas>:
+ *
+ * ```tsx
+ * <MujocoProvider>
+ *   <Canvas shadows camera={...}>
+ *     <MujocoPhysics config={config} paused={paused}>
+ *       <SceneRenderer />
+ *       <OrbitControls />
+ *     </MujocoPhysics>
+ *   </Canvas>
+ * </MujocoProvider>
+ * ```
+ *
+ * Forward ref exposes MujocoSimAPI.
+ */
+export const MujocoPhysics = forwardRef<MujocoSimAPI, MujocoPhysicsProps>(
+  function MujocoPhysics({ onError, children, ...props }, ref) {
+    const { mujoco, status: wasmStatus, error: wasmError } = useMujoco();
+
+    useEffect(() => {
+      if (wasmStatus === 'error' && onError) {
+        onError(new Error(wasmError ?? 'WASM load failed'));
+      }
+    }, [wasmStatus, wasmError, onError]);
+
+    if (wasmStatus === 'error' || wasmStatus === 'loading' || !mujoco) {
+      return null;
+    }
+
+    return (
+      <MujocoSimProvider
+        mujoco={mujoco}
+        apiRef={ref}
+        onError={onError}
+        {...props}
+      >
+        {children}
+      </MujocoSimProvider>
+    );
+  }
+);

package/src/core/MujocoSimProvider.tsx

@@ -140,7 +140,6 @@ interface MujocoSimProviderProps {
   substeps?: number;
   paused?: boolean;
   speed?: number;
-  interpolate?: boolean;
   children: React.ReactNode;
 }
 
@@ -157,7 +156,6 @@ export function MujocoSimProvider({
   substeps,
   paused,
   speed,
-  interpolate,
   children,
 }: MujocoSimProviderProps) {
   const { gl, camera } = useThree();
@@ -171,15 +169,9 @@ export function MujocoSimProvider({
   const pausedRef = useRef(paused ?? false);
   const speedRef = useRef(speed ?? 1);
   const substepsRef = useRef(substeps ?? 1);
-  const interpolateRef = useRef(interpolate ?? false);
   const stepsToRunRef = useRef(0);
   const loadGenRef = useRef(0);
 
-  // Interpolation state
-  const prevXposRef = useRef<Float64Array | null>(null);
-  const prevXquatRef = useRef<Float64Array | null>(null);
-  const interpAlphaRef = useRef(0);
-
   const onSelectionRef = useRef(onSelection);
   onSelectionRef.current = onSelection;
   const onStepRef = useRef(onStep);
@@ -195,7 +187,6 @@ export function MujocoSimProvider({
   useEffect(() => { pausedRef.current = paused ?? false; }, [paused]);
   useEffect(() => { speedRef.current = speed ?? 1; }, [speed]);
   useEffect(() => { substepsRef.current = substeps ?? 1; }, [substeps]);
-  useEffect(() => { interpolateRef.current = interpolate ?? false; }, [interpolate]);
 
   // Sync gravity prop
   useEffect(() => {
@@ -277,7 +268,7 @@ export function MujocoSimProvider({
   }, [status]);
 
   // --- Physics step (priority -1) ---
-  useFrame(() => {
+  useFrame((_state, delta) => {
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return;
@@ -305,7 +296,8 @@ export function MujocoSimProvider({
       stepsToRunRef.current = 0;
     } else {
       const startSimTime = data.time;
-      const frameTime = (1.0 / 60.0) * speedRef.current;
+      const clampedDelta = Math.min(delta, 1 / 15); // cap to avoid spiral of death
+      const frameTime = clampedDelta * speedRef.current;
       while (data.time - startSimTime < frameTime) {
         for (let s = 0; s < numSubsteps; s++) {
           mujoco.mj_step(model, data);

package/src/core/SceneLoader.ts

@@ -140,8 +140,6 @@ function sceneObjectToXml(obj: SceneObject): string {
 interface LoadResult {
   mjModel: MujocoModel;
   mjData: MujocoData;
-  siteId: number;
-  gripperId: number;
 }
 
 /**
@@ -241,11 +239,7 @@ export async function loadScene(
   const mjModel = mujoco.MjModel.loadFromXML(`/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
 
-  // 6. Find TCP site and gripper actuator
-  const siteId = findSiteByName(mjModel, config.tcpSiteName ?? 'tcp');
-  const gripperId = findActuatorByName(mjModel, config.gripperActuatorName ?? 'gripper');
-
-  // 7. Set initial pose — set both ctrl and qpos so robot starts at home.
+  // 6. Set initial pose — set both ctrl and qpos so robot starts at home.
   //    If homeJoints is not provided, keep raw MuJoCo defaults.
   if (config.homeJoints) {
     const homeCount = Math.min(config.homeJoints.length, mjModel.nu);
@@ -260,7 +254,7 @@ export async function loadScene(
 
   mujoco.mj_forward(mjModel, mjData);
 
-  return { mjModel, mjData, siteId, gripperId };
+  return { mjModel, mjData };
 }
 
 /**

package/src/index.ts

@@ -6,6 +6,8 @@
 // Core
 export { MujocoProvider, useMujoco } from './core/MujocoProvider';
 export { MujocoCanvas } from './core/MujocoCanvas';
+export { MujocoPhysics } from './core/MujocoPhysics';
+export type { MujocoPhysicsProps } from './core/MujocoPhysics';
 export { MujocoSimProvider, useMujocoSim, useBeforePhysicsStep, useAfterPhysicsStep } from './core/MujocoSimProvider';
 export {
   loadScene,

package/src/types.ts

@@ -291,12 +291,6 @@ export interface SceneConfig {
   homeJoints?: number[];
   xmlPatches?: XmlPatch[];
   onReset?: (model: MujocoModel, data: MujocoData) => void;
-  /** @deprecated Use IkController config.siteName instead. */
-  tcpSiteName?: string;
-  /** @deprecated Use your own gripper control logic instead. */
-  gripperActuatorName?: string;
-  /** @deprecated Use IkController config.numJoints instead. */
-  numArmJoints?: number;
 }
 
 // ---- IK Controller Config ----
@@ -328,7 +322,6 @@ export interface PhysicsConfig {
   substeps?: number;
   paused?: boolean;
   speed?: number;
-  interpolate?: boolean;
 }
 
 // ---- IK ----
@@ -620,9 +613,6 @@ export type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
   substeps?: number;
   paused?: boolean;
   speed?: number;
-  interpolate?: boolean;
-  gravityCompensation?: boolean;
-  mjcfLights?: boolean;
 };
 
 // ---- Hook Return Types ----