mujoco-react 0.2.0 → 1.0.0

package/src/core/SceneLoader.ts

@@ -100,6 +100,26 @@ export function findTendonByName(mjModel: MujocoModel, name: string): number {
   return -1;
 }
 
+/**
+ * Return qpos address for actuators that directly target a scalar joint.
+ * Returns -1 for non-joint transmissions and multi-DOF joints.
+ */
+export function getActuatedScalarQposAdr(mjModel: MujocoModel, actuatorId: number): number {
+  if (actuatorId < 0 || actuatorId >= mjModel.nu) return -1;
+
+  // mjTRN_JOINT=0, mjTRN_JOINTINPARENT=1. Other transmission types don't map ctrl to a single qpos.
+  const trnType = mjModel.actuator_trntype?.[actuatorId];
+  if (trnType !== undefined && trnType !== 0 && trnType !== 1) return -1;
+
+  const jointId = mjModel.actuator_trnid[2 * actuatorId];
+  if (jointId < 0 || jointId >= mjModel.njnt) return -1;
+
+  const jntType = mjModel.jnt_type[jointId];
+  if (jntType !== 2 && jntType !== 3) return -1; // slide=2, hinge=3
+
+  return mjModel.jnt_qposadr[jointId];
+}
+
 /**
  * Convert a SceneObject config to MuJoCo XML.
  */
@@ -120,8 +140,6 @@ function sceneObjectToXml(obj: SceneObject): string {
 interface LoadResult {
   mjModel: MujocoModel;
   mjData: MujocoData;
-  siteId: number;
-  gripperId: number;
 }
 
 /**
@@ -174,7 +192,13 @@ export async function loadScene(
       for (const patch of config.xmlPatches ?? []) {
         if (fname.endsWith(patch.target) || fname === patch.target) {
           if (patch.replace) {
-            text = text.replace(patch.replace[0], patch.replace[1]);
+            const [from, to] = patch.replace;
+            if (text.includes(from)) {
+              text = text.replace(from, to);
+            } else {
+              const preview = from.length > 80 ? `${from.slice(0, 80)}...` : from;
+              console.warn(`XML patch replace pattern not found in ${fname}: "${preview}"`);
+            }
           }
           if (patch.inject && patch.injectAfter) {
             const idx = text.indexOf(patch.injectAfter);
@@ -183,7 +207,14 @@ export async function loadScene(
               const tagEnd = text.indexOf('>', idx + patch.injectAfter.length);
               if (tagEnd !== -1) {
                 text = text.slice(0, tagEnd + 1) + patch.inject + text.slice(tagEnd + 1);
+              } else {
+                console.warn(`XML patch inject failed in ${fname}: could not find tag end after "${patch.injectAfter}"`);
               }
+            } else {
+              const preview = patch.injectAfter.length > 80
+                ? `${patch.injectAfter.slice(0, 80)}...`
+                : patch.injectAfter;
+              console.warn(`XML patch inject anchor not found in ${fname}: "${preview}"`);
             }
           }
         }
@@ -208,27 +239,22 @@ 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
+  // 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) {
-    for (let i = 0; i < config.homeJoints.length; i++) {
+    const homeCount = Math.min(config.homeJoints.length, mjModel.nu);
+    for (let i = 0; i < homeCount; i++) {
       mjData.ctrl[i] = config.homeJoints[i];
-      if (mjModel.actuator_trnid[2 * i + 1] === 1) {
-        const jointId = mjModel.actuator_trnid[2 * i];
-        if (jointId >= 0 && jointId < mjModel.njnt) {
-          const qposAdr = mjModel.jnt_qposadr[jointId];
-          mjData.qpos[qposAdr] = config.homeJoints[i];
-        }
+      const qposAdr = getActuatedScalarQposAdr(mjModel, i);
+      if (qposAdr !== -1) {
+        mjData.qpos[qposAdr] = config.homeJoints[i];
       }
     }
   }
 
   mujoco.mj_forward(mjModel, mjData);
 
-  return { mjModel, mjData, siteId, gripperId };
+  return { mjModel, mjData };
 }
 
 /**
@@ -244,8 +270,9 @@ function scanDependencies(
   const xmlDoc = parser.parseFromString(xmlString, 'text/xml');
 
   const compiler = xmlDoc.querySelector('compiler');
-  const meshDir = compiler?.getAttribute('meshdir') || '';
-  const textureDir = compiler?.getAttribute('texturedir') || '';
+  const assetDir = compiler?.getAttribute('assetdir') || '';
+  const meshDir = compiler?.getAttribute('meshdir') || assetDir;
+  const textureDir = compiler?.getAttribute('texturedir') || assetDir;
   const currentDir = currentFile.includes('/')
     ? currentFile.substring(0, currentFile.lastIndexOf('/') + 1)
     : '';

package/src/core/createController.tsx

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * createController — typed factory for BYOC (Bring Your Own Controller) plugins.
+ */
+
+import { useMemo, useRef } from 'react';
+
+/** Shallow-compare two plain objects by own enumerable keys. */
+function shallowEqual(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
+
+export interface ControllerOptions<TConfig> {
+  /** Unique name for this controller (used as displayName). */
+  name: string;
+  /** Default values merged under user-supplied config. */
+  defaultConfig?: Partial<TConfig>;
+}
+
+export type ControllerComponent<TConfig> = React.FC<{
+  config?: Partial<TConfig>;
+  children?: React.ReactNode;
+}> & {
+  controllerName: string;
+  defaultConfig: Partial<TConfig>;
+};
+
+/**
+ * Factory that produces a typed controller component.
+ *
+ * Controllers are React components that plug into the MuJoCo simulation tree.
+ * Inside `Impl`, use any hooks (`useMujocoSim`, `useBeforePhysicsStep`, etc.)
+ * to interact with the physics engine.
+ *
+ * @example
+ * ```tsx
+ * const MyController = createController<{ speed: number }>(
+ *   { name: 'my-controller', defaultConfig: { speed: 1.0 } },
+ *   function MyControllerImpl({ config }) {
+ *     useBeforePhysicsStep((_model, data) => {
+ *       data.ctrl[0] = config.speed;
+ *     });
+ *     return null;
+ *   },
+ * );
+ *
+ * // Usage:
+ * <MyController config={{ speed: 2.0 }} />
+ * ```
+ */
+export function createController<TConfig>(
+  options: ControllerOptions<TConfig>,
+  Impl: React.FC<{ config: TConfig; children?: React.ReactNode }>,
+): ControllerComponent<TConfig> {
+  function Controller({
+    config,
+    children,
+  }: {
+    config?: Partial<TConfig>;
+    children?: React.ReactNode;
+  }) {
+    // Stabilise config reference: inline objects get a new identity each render,
+    // but the actual values rarely change.  Shallow-compare to keep the same ref.
+    const configObj = (config ?? {}) as Record<string, unknown>;
+    const stableRef = useRef(configObj);
+    if (!shallowEqual(stableRef.current, configObj)) {
+      stableRef.current = configObj;
+    }
+    const stableConfig = stableRef.current as Partial<TConfig>;
+
+    const mergedConfig = useMemo(
+      () => ({ ...options.defaultConfig, ...stableConfig }) as TConfig,
+      [stableConfig],
+    );
+    return <Impl config={mergedConfig}>{children}</Impl>;
+  }
+
+  Controller.displayName = options.name;
+  Controller.controllerName = options.name;
+  Controller.defaultConfig = options.defaultConfig ?? ({} as Partial<TConfig>);
+
+  return Controller as ControllerComponent<TConfig>;
+}

package/src/hooks/useCameraAnimation.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useCameraAnimation — composable camera animation hook.
+ */
+
+import { useCallback, useRef } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import * as THREE from 'three';
+
+export interface CameraAnimationAPI {
+  getCameraState(): { position: THREE.Vector3; target: THREE.Vector3 };
+  moveCameraTo(position: THREE.Vector3, target: THREE.Vector3, durationMs: number): Promise<void>;
+}
+
+/**
+ * Standalone hook for animated camera transitions.
+ *
+ * Manages its own `useFrame` callback — drop it into any component inside `<Canvas>`.
+ */
+export function useCameraAnimation(): CameraAnimationAPI {
+  const { camera } = useThree();
+
+  const orbitTargetRef = useRef(new THREE.Vector3(0, 0, 0));
+
+  const cameraAnimRef = useRef({
+    active: false,
+    startPos: new THREE.Vector3(),
+    endPos: new THREE.Vector3(),
+    startRot: new THREE.Quaternion(),
+    endRot: new THREE.Quaternion(),
+    startTarget: new THREE.Vector3(),
+    endTarget: new THREE.Vector3(),
+    startTime: 0,
+    duration: 0,
+    resolve: null as (() => void) | null,
+  });
+
+  useFrame((state) => {
+    const ca = cameraAnimRef.current;
+    if (!ca.active) return;
+
+    const now = performance.now();
+    const progress = Math.min((now - ca.startTime) / ca.duration, 1.0);
+    const ease =
+      progress < 0.5
+        ? 4 * progress * progress * progress
+        : 1 - Math.pow(-2 * progress + 2, 3) / 2;
+
+    camera.position.lerpVectors(ca.startPos, ca.endPos, ease);
+    camera.quaternion.slerpQuaternions(ca.startRot, ca.endRot, ease);
+    orbitTargetRef.current.lerpVectors(ca.startTarget, ca.endTarget, ease);
+
+    const orbitControls = state.controls as { target?: THREE.Vector3 };
+    if (orbitControls?.target) {
+      orbitControls.target.copy(orbitTargetRef.current);
+    }
+
+    if (progress >= 1.0) {
+      ca.active = false;
+      camera.position.copy(ca.endPos);
+      camera.quaternion.copy(ca.endRot);
+      orbitTargetRef.current.copy(ca.endTarget);
+      ca.resolve?.();
+      ca.resolve = null;
+    }
+  });
+
+  const getCameraState = useCallback(
+    (): { position: THREE.Vector3; target: THREE.Vector3 } => ({
+      position: camera.position.clone(),
+      target: orbitTargetRef.current.clone(),
+    }),
+    [camera],
+  );
+
+  const moveCameraTo = useCallback(
+    (position: THREE.Vector3, target: THREE.Vector3, durationMs: number): Promise<void> => {
+      return new Promise((resolve) => {
+        const ca = cameraAnimRef.current;
+        ca.active = true;
+        ca.startTime = performance.now();
+        ca.duration = durationMs;
+        ca.startPos.copy(camera.position);
+        ca.startRot.copy(camera.quaternion);
+        ca.startTarget.copy(orbitTargetRef.current);
+        ca.endPos.copy(position);
+        ca.endTarget.copy(target);
+        const dummyCam = (camera as THREE.PerspectiveCamera).clone();
+        dummyCam.position.copy(position);
+        dummyCam.lookAt(target);
+        ca.endRot.copy(dummyCam.quaternion);
+        ca.resolve = resolve;
+        setTimeout(resolve, durationMs + 100);
+      });
+    },
+    [camera],
+  );
+
+  return { getCameraState, moveCameraTo };
+}

package/src/hooks/useContacts.ts

@@ -9,7 +9,26 @@
 import { useCallback, useEffect, useRef } from 'react';
 import { useMujocoSim, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { findBodyByName, getName } from '../core/SceneLoader';
-import type { ContactInfo } from '../types';
+import { getContact } from '../types';
+import type { ContactInfo, MujocoModel } from '../types';
+
+// Cache geom names per model to avoid cross-model id collisions.
+const geomNameCacheByModel = new WeakMap<MujocoModel, Map<number, string>>();
+
+function getGeomNameCached(model: MujocoModel, geomId: number): string {
+  let perModel = geomNameCacheByModel.get(model);
+  if (!perModel) {
+    perModel = new Map<number, string>();
+    geomNameCacheByModel.set(model, perModel);
+  }
+
+  let name = perModel.get(geomId);
+  if (name === undefined) {
+    name = getName(model, model.name_geomadr[geomId]);
+    perModel.set(geomId, name);
+  }
+  return name;
+}
 
 /**
  * Track contacts for a specific body (or all contacts if no body specified).
@@ -20,20 +39,34 @@ export function useContacts(
   bodyName?: string,
   callback?: (contacts: ContactInfo[]) => void,
 ): React.RefObject<ContactInfo[]> {
-  const { mjModelRef } = useMujocoSim();
+  const { mjModelRef, status } = useMujocoSim();
   const contactsRef = useRef<ContactInfo[]>([]);
   const bodyIdRef = useRef(-1);
+  const bodyResolvedRef = useRef(false);
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
 
   useEffect(() => {
-    if (!bodyName) { bodyIdRef.current = -1; return; }
+    if (!bodyName) {
+      bodyIdRef.current = -1;
+      bodyResolvedRef.current = true;
+      return;
+    }
+    bodyResolvedRef.current = false;
+    if (status !== 'ready') return;
     const model = mjModelRef.current;
     if (!model) return;
     bodyIdRef.current = findBodyByName(model, bodyName);
-  }, [bodyName, mjModelRef]);
+    bodyResolvedRef.current = true;
+  }, [bodyName, status, mjModelRef]);
 
   useAfterPhysicsStep((model, data) => {
+    // Resolve body id lazily once model exists, to avoid missing the first ready frame.
+    if (bodyName && !bodyResolvedRef.current) {
+      bodyIdRef.current = findBodyByName(model, bodyName);
+      bodyResolvedRef.current = true;
+    }
+
     const ncon = data.ncon;
     if (ncon === 0) {
       if (contactsRef.current.length > 0) contactsRef.current = [];
@@ -45,25 +78,22 @@ export function useContacts(
     const filterBody = bodyIdRef.current;
 
     for (let i = 0; i < ncon; i++) {
-      try {
-        const c = (data.contact as { get(i: number): { geom1: number; geom2: number; pos: Float64Array; dist: number } }).get(i);
-        // Filter by body if specified
-        if (filterBody >= 0) {
-          const b1 = model.geom_bodyid[c.geom1];
-          const b2 = model.geom_bodyid[c.geom2];
-          if (b1 !== filterBody && b2 !== filterBody) continue;
-        }
-        contacts.push({
-          geom1: c.geom1,
-          geom1Name: getName(model, model.name_geomadr[c.geom1]),
-          geom2: c.geom2,
-          geom2Name: getName(model, model.name_geomadr[c.geom2]),
-          pos: [c.pos[0], c.pos[1], c.pos[2]],
-          depth: c.dist,
-        });
-      } catch {
-        break;
+      const c = getContact(data, i);
+      if (!c) break;
+      // Filter by body if specified
+      if (filterBody >= 0) {
+        const b1 = model.geom_bodyid[c.geom1];
+        const b2 = model.geom_bodyid[c.geom2];
+        if (b1 !== filterBody && b2 !== filterBody) continue;
       }
+      contacts.push({
+        geom1: c.geom1,
+        geom1Name: getGeomNameCached(model, c.geom1),
+        geom2: c.geom2,
+        geom2Name: getGeomNameCached(model, c.geom2),
+        pos: [c.pos[0], c.pos[1], c.pos[2]],
+        depth: c.dist,
+      });
     }
     contactsRef.current = contacts;
     callbackRef.current?.(contacts);

package/src/hooks/useJointState.ts

@@ -27,6 +27,9 @@ export function useJointState(name: string): JointStateResult {
   const dofDimRef = useRef(1);
   const positionRef = useRef<number | Float64Array>(0);
   const velocityRef = useRef<number | Float64Array>(0);
+  // Preallocated typed arrays for multi-DOF joints
+  const posBufferRef = useRef<Float64Array | null>(null);
+  const velBufferRef = useRef<Float64Array | null>(null);
 
   useEffect(() => {
     const model = mjModelRef.current;
@@ -41,6 +44,15 @@ export function useJointState(name: string): JointStateResult {
         if (type === 0) { qposDimRef.current = 7; dofDimRef.current = 6; }
         else if (type === 1) { qposDimRef.current = 4; dofDimRef.current = 3; }
         else { qposDimRef.current = 1; dofDimRef.current = 1; }
+
+        // Preallocate buffers for multi-DOF joints
+        if (qposDimRef.current > 1) {
+          posBufferRef.current = new Float64Array(qposDimRef.current);
+          velBufferRef.current = new Float64Array(dofDimRef.current);
+        } else {
+          posBufferRef.current = null;
+          velBufferRef.current = null;
+        }
         return;
       }
     }
@@ -55,8 +67,12 @@ export function useJointState(name: string): JointStateResult {
       positionRef.current = data.qpos[qa];
       velocityRef.current = data.qvel[da];
     } else {
-      positionRef.current = new Float64Array(data.qpos.subarray(qa, qa + qposDimRef.current));
-      velocityRef.current = new Float64Array(data.qvel.subarray(da, da + dofDimRef.current));
+      const posBuf = posBufferRef.current!;
+      const velBuf = velBufferRef.current!;
+      posBuf.set(data.qpos.subarray(qa, qa + qposDimRef.current));
+      velBuf.set(data.qvel.subarray(da, da + dofDimRef.current));
+      positionRef.current = posBuf;
+      velocityRef.current = velBuf;
     }
   });
 

package/src/hooks/useSceneLights.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useSceneLights — hook form of SceneLights (spec 6.3)
+ *
+ * Auto-creates Three.js lights from MJCF <light> elements.
+ */
+
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { useThree } from '@react-three/fiber';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+
+export function useSceneLights(intensity = 1.0) {
+  const { mjModelRef, status } = useMujocoSim();
+  const { scene } = useThree();
+  const lightsRef = useRef<THREE.Light[]>([]);
+  const targetsRef = useRef<THREE.Object3D[]>([]);
+
+  useEffect(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== 'ready') return;
+
+    // Clean up previous lights
+    for (const light of lightsRef.current) {
+      scene.remove(light);
+      light.dispose();
+    }
+    for (const t of targetsRef.current) scene.remove(t);
+    lightsRef.current = [];
+    targetsRef.current = [];
+
+    const nlight = model.nlight ?? 0;
+    if (nlight === 0) return;
+
+    for (let i = 0; i < nlight; i++) {
+      const active = model.light_active ? model.light_active[i] : 1;
+      if (!active) continue;
+
+      const lightType = model.light_type ? model.light_type[i] : 0;
+      const isDirectional = lightType === 0;
+      const castShadow = model.light_castshadow ? model.light_castshadow[i] !== 0 : false;
+
+      const mjIntensity = model.light_intensity ? model.light_intensity[i] : 1.0;
+      const finalIntensity = intensity * mjIntensity;
+
+      const dr = model.light_diffuse ? model.light_diffuse[3 * i] : 1;
+      const dg = model.light_diffuse ? model.light_diffuse[3 * i + 1] : 1;
+      const db = model.light_diffuse ? model.light_diffuse[3 * i + 2] : 1;
+      const color = new THREE.Color(dr, dg, db);
+
+      const px = model.light_pos[3 * i];
+      const py = model.light_pos[3 * i + 1];
+      const pz = model.light_pos[3 * i + 2];
+      const dx = model.light_dir[3 * i];
+      const dy = model.light_dir[3 * i + 1];
+      const dz = model.light_dir[3 * i + 2];
+
+      if (isDirectional) {
+        const light = new THREE.DirectionalLight(color, finalIntensity);
+        light.position.set(px, py, pz);
+        light.target.position.set(px + dx, py + dy, pz + dz);
+        light.castShadow = castShadow;
+        if (castShadow) {
+          light.shadow.mapSize.width = 1024;
+          light.shadow.mapSize.height = 1024;
+          light.shadow.camera.near = 0.1;
+          light.shadow.camera.far = 50;
+          const d = 5;
+          light.shadow.camera.left = -d;
+          light.shadow.camera.right = d;
+          light.shadow.camera.top = d;
+          light.shadow.camera.bottom = -d;
+        }
+        scene.add(light);
+        scene.add(light.target);
+        lightsRef.current.push(light);
+        targetsRef.current.push(light.target);
+      } else {
+        const cutoff = model.light_cutoff ? model.light_cutoff[i] : 45;
+        const exponent = model.light_exponent ? model.light_exponent[i] : 10;
+        const angle = (cutoff * Math.PI) / 180;
+        const light = new THREE.SpotLight(color, finalIntensity, 0, angle, exponent / 128);
+        light.position.set(px, py, pz);
+        light.target.position.set(px + dx, py + dy, pz + dz);
+        light.castShadow = castShadow;
+
+        if (model.light_attenuation) {
+          const att1 = model.light_attenuation[3 * i + 1];
+          const att2 = model.light_attenuation[3 * i + 2];
+          light.decay = att2 > 0 ? 2 : (att1 > 0 ? 1 : 0);
+          light.distance = att1 > 0 ? 1 / att1 : 0;
+        }
+
+        if (castShadow) {
+          light.shadow.mapSize.width = 512;
+          light.shadow.mapSize.height = 512;
+        }
+        scene.add(light);
+        scene.add(light.target);
+        lightsRef.current.push(light);
+        targetsRef.current.push(light.target);
+      }
+    }
+
+    return () => {
+      for (const light of lightsRef.current) {
+        scene.remove(light);
+        light.dispose();
+      }
+      for (const t of targetsRef.current) scene.remove(t);
+      lightsRef.current = [];
+      targetsRef.current = [];
+    };
+  }, [status, mjModelRef, scene, intensity]);
+}

package/src/hooks/useSelectionHighlight.ts

@@ -0,0 +1,65 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useSelectionHighlight — hook form of SelectionHighlight (spec 6.5)
+ *
+ * Applies emissive highlight to all meshes belonging to a body.
+ * Restores original emissive when bodyId changes or hook unmounts.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useThree } from '@react-three/fiber';
+import * as THREE from 'three';
+
+export function useSelectionHighlight(
+  bodyId: number | null,
+  options: { color?: string; emissiveIntensity?: number } = {},
+) {
+  const { color = '#ff4444', emissiveIntensity = 0.3 } = options;
+  const { scene } = useThree();
+  const prevMeshesRef = useRef<{ mesh: THREE.Mesh; originalEmissive: THREE.Color; originalIntensity: number }[]>([]);
+
+  useEffect(() => {
+    // Restore previous highlights
+    for (const entry of prevMeshesRef.current) {
+      const mat = entry.mesh.material as THREE.MeshStandardMaterial;
+      if (mat.emissive) {
+        mat.emissive.copy(entry.originalEmissive);
+        mat.emissiveIntensity = entry.originalIntensity;
+      }
+    }
+    prevMeshesRef.current = [];
+
+    if (bodyId === null || bodyId < 0) return;
+
+    // Find all meshes belonging to this body
+    const highlightColor = new THREE.Color(color);
+    scene.traverse((obj) => {
+      if (obj.userData.bodyID === bodyId && (obj as THREE.Mesh).isMesh) {
+        const mesh = obj as THREE.Mesh;
+        const mat = mesh.material as THREE.MeshStandardMaterial;
+        if (mat.emissive) {
+          prevMeshesRef.current.push({
+            mesh,
+            originalEmissive: mat.emissive.clone(),
+            originalIntensity: mat.emissiveIntensity ?? 0,
+          });
+          mat.emissive.copy(highlightColor);
+          mat.emissiveIntensity = emissiveIntensity;
+        }
+      }
+    });
+
+    return () => {
+      for (const entry of prevMeshesRef.current) {
+        const mat = entry.mesh.material as THREE.MeshStandardMaterial;
+        if (mat.emissive) {
+          mat.emissive.copy(entry.originalEmissive);
+          mat.emissiveIntensity = entry.originalIntensity;
+        }
+      }
+      prevMeshesRef.current = [];
+    };
+  }, [bodyId, color, emissiveIntensity, scene]);
+}

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,
@@ -20,6 +22,15 @@ export {
   findTendonByName,
 } from './core/SceneLoader';
 
+// Controller factory
+export { createController } from './core/createController';
+export type { ControllerOptions, ControllerComponent } from './core/createController';
+
+// IK controller plugin
+export { IkController } from './components/IkController';
+export { useIk } from './core/IkContext';
+export type { IkContextValue } from './core/IkContext';
+
 // Components
 export { SceneRenderer } from './components/SceneRenderer';
 export { IkGizmo } from './components/IkGizmo';
@@ -49,6 +60,10 @@ export { useTrajectoryRecorder } from './hooks/useTrajectoryRecorder';
 export { useGamepad } from './hooks/useGamepad';
 export { useVideoRecorder } from './hooks/useVideoRecorder';
 export { useCtrlNoise } from './hooks/useCtrlNoise';
+export { useSelectionHighlight } from './hooks/useSelectionHighlight';
+export { useSceneLights } from './hooks/useSceneLights';
+export { useCameraAnimation } from './hooks/useCameraAnimation';
+export type { CameraAnimationAPI } from './hooks/useCameraAnimation';
 
 // Types
 export type {
@@ -59,6 +74,7 @@ export type {
   SceneMarker,
   PhysicsConfig,
   // IK
+  IkConfig,
   IKSolveFn,
   // Callbacks
   PhysicsStepCallback,
@@ -105,4 +121,5 @@ export type {
 } from './types';
 
 // Re-export MuJoCo types for convenience
-export type { MujocoModule, MujocoModel, MujocoData } from './types';
+export type { MujocoModule, MujocoModel, MujocoData, MujocoContact, MujocoContactArray } from './types';
+export { getContact } from './types';