mujoco-react 6.0.1 → 7.0.0

package/package.json

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

package/src/components/Body.tsx

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useFrame } from '@react-three/fiber';
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { useMujocoContext } from '../core/MujocoSimProvider';
+import { findBodyByName } from '../core/SceneLoader';
+import type { BodyProps, SceneObject } from '../types';
+
+/**
+ * Declarative physics body component. Registers a body definition in the
+ * provider-level registry so it gets injected into the MJCF XML at load time.
+ *
+ * Bodies present at initial mount cause zero extra reloads (useLayoutEffect
+ * runs before the provider's loadScene useEffect). Bodies added/removed after
+ * the initial load trigger a debounced scene reload.
+ */
+export function Body({
+  name,
+  type,
+  size,
+  position = [0, 0, 0],
+  rgba = [0.5, 0.5, 0.5, 1],
+  mass,
+  freejoint,
+  friction,
+  solref,
+  solimp,
+  condim,
+  children,
+}: BodyProps) {
+  const { bodyRegistryRef, hiddenBodiesRef, requestBodyReload, mjDataRef, mjModelRef, status } =
+    useMujocoContext();
+  const bodyIdRef = useRef(-1);
+  const groupRef = useRef<THREE.Group>(null);
+  const initialLoadRef = useRef(true);
+  const hasChildren = children != null;
+
+  // Register in body registry BEFORE the provider's loadScene useEffect fires.
+  useLayoutEffect(() => {
+    const definition: SceneObject = {
+      name,
+      type,
+      size,
+      position,
+      rgba,
+      mass,
+      freejoint,
+      friction,
+      solref,
+      solimp,
+      condim,
+    };
+    bodyRegistryRef.current.set(name, { definition, hasCustomChildren: hasChildren });
+    if (hasChildren) {
+      hiddenBodiesRef.current.add(name);
+    }
+
+    return () => {
+      bodyRegistryRef.current.delete(name);
+      hiddenBodiesRef.current.delete(name);
+      if (!initialLoadRef.current) {
+        requestBodyReload();
+      }
+    };
+  }, [name, type, size, position, rgba, mass, freejoint, friction, solref, solimp, condim, hasChildren, bodyRegistryRef, hiddenBodiesRef, requestBodyReload]);
+
+  // Resolve body ID once the scene is ready
+  useEffect(() => {
+    if (status !== 'ready') return;
+    const model = mjModelRef.current;
+    if (!model) return;
+    bodyIdRef.current = findBodyByName(model, name);
+    initialLoadRef.current = false;
+  }, [status, name, mjModelRef]);
+
+  // Sync group transform to body pose each frame (only when children are provided)
+  useFrame(() => {
+    if (!hasChildren) return;
+    const data = mjDataRef.current;
+    const id = bodyIdRef.current;
+    const group = groupRef.current;
+    if (!data || id < 0 || !group) return;
+
+    const i3 = id * 3;
+    const i4 = id * 4;
+    group.position.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
+    group.quaternion.set(
+      data.xquat[i4 + 1],
+      data.xquat[i4 + 2],
+      data.xquat[i4 + 3],
+      data.xquat[i4],
+    );
+  });
+
+  if (!hasChildren) return null;
+
+  return <group ref={groupRef}>{children}</group>;
+}

package/src/components/ContactMarkers.tsx

@@ -12,7 +12,7 @@ import { useRef } from 'react';
 import { useFrame } from '@react-three/fiber';
 import type { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
-import { useMujoco } from '../core/MujocoSimProvider';
+import { useMujocoContext } from '../core/MujocoSimProvider';
 import { getContact } from '../types';
 
 const _dummy = new THREE.Object3D();
@@ -35,7 +35,7 @@ export function ContactMarkers({
   visible = true,
   ...groupProps
 }: ContactMarkersProps & Omit<ThreeElements['group'], 'ref' | 'visible'> = {}) {
-  const { mjDataRef, status } = useMujoco();
+  const { mjDataRef, status } = useMujocoContext();
   const meshRef = useRef<THREE.InstancedMesh>(null);
 
   useFrame(() => {

package/src/components/Debug.tsx

@@ -9,7 +9,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 { useMujoco } from '../core/MujocoSimProvider';
+import { useMujocoContext } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
 import { getContact } from '../types';
 import type { DebugProps } from '../types';
@@ -43,7 +43,7 @@ export function Debug({
   showTendons = false,
   ...groupProps
 }: DebugProps & Omit<ThreeElements['group'], 'ref'>) {
-  const { mjModelRef, mjDataRef, status } = useMujoco();
+  const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const { scene } = useThree();
   const groupRef = useRef<THREE.Group>(null);
 

package/src/components/DragInteraction.tsx

@@ -7,7 +7,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 { useMujoco, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
 import type { DragInteractionProps } from '../types';
 
 // Preallocated temps to avoid GC pressure
@@ -38,7 +38,7 @@ export function DragInteraction({
   showArrow = true,
   ...groupProps
 }: DragInteractionProps & Omit<ThreeElements['group'], 'ref'>) {
-  const { mjDataRef, mujocoRef, mjModelRef, status } = useMujoco();
+  const { mjDataRef, mujocoRef, mjModelRef, status } = useMujocoContext();
   const { gl, camera, scene, controls } = useThree();
 
   const draggingRef = useRef(false);

package/src/components/FlexRenderer.tsx

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

package/src/components/IkGizmo.tsx

@@ -7,8 +7,7 @@ import { PivotControls } from '@react-three/drei';
 import { useFrame, useThree } from '@react-three/fiber';
 import { useEffect, useRef } from 'react';
 import * as THREE from 'three';
-import { useMujoco } from '../core/MujocoSimProvider';
-import { useIk } from '../core/IkContext';
+import { useMujocoContext } from '../core/MujocoSimProvider';
 import { findSiteByName } from '../core/SceneLoader';
 import type { IkGizmoProps } from '../types';
 
@@ -21,18 +20,19 @@ const _scale = new THREE.Vector3(1, 1, 1);
 /**
  * IkGizmo — drei PivotControls that tracks a MuJoCo site.
  *
- * Must be rendered inside an `<IkController>`.
+ * Requires a `controller` from `useIkController()`.
  *
  * Props:
- * - `siteName` — MuJoCo site to track. Defaults to the IkController's configured site.
+ * - `controller` — IkContextValue from `useIkController()`.
+ * - `siteName` — MuJoCo site to track. Defaults to the controller's configured site.
  * - `scale` — Gizmo handle scale. Default: 0.18.
  * - `onDrag` — Custom drag callback `(pos, quat) => void`.
  *   When omitted, dragging enables IK and writes to the IK target.
  *   When provided, the consumer handles what happens during drag.
  */
-export function IkGizmo({ siteName, scale = 0.18, onDrag }: IkGizmoProps) {
-  const { mjModelRef, mjDataRef, status } = useMujoco();
-  const { ikTargetRef, siteIdRef, ikEnabledRef, setIkEnabled } = useIk();
+export function IkGizmo({ controller, siteName, scale = 0.18, onDrag }: IkGizmoProps) {
+  const { mjModelRef, mjDataRef, status } = useMujocoContext();
+  const { ikTargetRef, siteIdRef, ikEnabledRef, setIkEnabled } = controller;
 
   const wrapperRef = useRef<THREE.Group>(null);
   const pivotRef = useRef<THREE.Group>(null);
@@ -53,9 +53,6 @@ export function IkGizmo({ siteName, scale = 0.18, onDrag }: IkGizmoProps) {
   // Every frame: sync the visual wrapper to the tracked site (when not dragging)
   useFrame(() => {
     const data = mjDataRef.current;
-    // Read IkController's siteIdRef directly in useFrame — avoids useEffect timing
-    // issues (React runs child effects before parent effects, so reading siteIdRef
-    // in a useEffect would see -1 before IkController resolves it).
     const sid = siteName ? localSiteIdRef.current : siteIdRef.current;
     if (!data || sid < 0 || !wrapperRef.current) return;
 
@@ -67,7 +64,6 @@ export function IkGizmo({ siteName, scale = 0.18, onDrag }: IkGizmoProps) {
 
       // Position wrapper at the site
       wrapperRef.current.position.set(p[i3], p[i3 + 1], p[i3 + 2]);
-      // MuJoCo site_xmat is row-major 3x3; THREE.Matrix4.set() is row-major
       _mat4.set(
         m[i9],     m[i9 + 1], m[i9 + 2], 0,
         m[i9 + 3], m[i9 + 4], m[i9 + 5], 0,

package/src/components/SceneRenderer.tsx

@@ -10,14 +10,14 @@ import * as THREE from 'three';
 import { GeomBuilder } from '../rendering/GeomBuilder';
 import { MujocoModel } from '../types';
 import { getName } from '../core/SceneLoader';
-import { useMujoco } from '../core/MujocoSimProvider';
+import { useMujocoContext } from '../core/MujocoSimProvider';
 
 /**
  * SceneRenderer — creates and syncs MuJoCo body meshes every frame.
  * Accepts standard R3F group props (position, rotation, scale, visible, etc.).
  */
 export function SceneRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
-  const { mjModelRef, mjDataRef, mujocoRef, onSelectionRef, status } = useMujoco();
+  const { mjModelRef, mjDataRef, mujocoRef, onSelectionRef, hiddenBodiesRef, status } = useMujocoContext();
   const groupRef = useRef<THREE.Group>(null);
   const bodyRefs = useRef<(THREE.Group | null)[]>([]);
   const prevModelRef = useRef<MujocoModel | null>(null);
@@ -48,11 +48,14 @@ export function SceneRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
     for (let i = 0; i < model.nbody; i++) {
       const bodyGroup = new THREE.Group();
       bodyGroup.userData.bodyID = i;
+      const bodyName = getName(model, model.name_bodyadr[i]);
 
-      for (let g = 0; g < model.ngeom; g++) {
-        if (model.geom_bodyid[g] === i) {
-          const mesh = geomBuilder.create(model, g);
-          if (mesh) bodyGroup.add(mesh);
+      if (!hiddenBodiesRef.current.has(bodyName)) {
+        for (let g = 0; g < model.ngeom; g++) {
+          if (model.geom_bodyid[g] === i) {
+            const mesh = geomBuilder.create(model, g);
+            if (mesh) bodyGroup.add(mesh);
+          }
         }
       }
 

package/src/components/TendonRenderer.tsx

@@ -15,7 +15,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 { useMujoco } from '../core/MujocoSimProvider';
+import { useMujocoContext } from '../core/MujocoSimProvider';
 
 const DEFAULT_TENDON_COLOR = new THREE.Color(0.3, 0.3, 0.8);
 const DEFAULT_TENDON_WIDTH = 0.002;
@@ -24,7 +24,7 @@ const DEFAULT_TENDON_WIDTH = 0.002;
 const _tmpVec = new THREE.Vector3();
 
 export function TendonRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
-  const { mjModelRef, mjDataRef, status } = useMujoco();
+  const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const groupRef = useRef<THREE.Group>(null);
   const meshesRef = useRef<THREE.Mesh[]>([]);
   const curvesRef = useRef<THREE.CatmullRomCurve3[]>([]);

package/src/core/MujocoSimProvider.tsx

@@ -27,6 +27,7 @@ import {
   PhysicsStepCallback,
   RayHit,
   SceneConfig,
+  SceneObject,
   SensorInfo,
   SiteInfo,
   StateSnapshot,
@@ -91,20 +92,68 @@ export interface MujocoSimContextValue {
   beforeStepCallbacks: React.RefObject<Set<PhysicsStepCallback>>;
   afterStepCallbacks: React.RefObject<Set<PhysicsStepCallback>>;
   resetCallbacks: React.RefObject<Set<() => void>>;
+  errorRef: React.RefObject<string | null>;
+  bodyRegistryRef: React.RefObject<Map<string, { definition: SceneObject; hasCustomChildren: boolean }>>;
+  hiddenBodiesRef: React.RefObject<Set<string>>;
+  requestBodyReload: () => void;
   status: 'loading' | 'ready' | 'error';
 }
 
 const MujocoSimContext = createContext<MujocoSimContextValue | null>(null);
 
-export function useMujoco(): MujocoSimContextValue {
+export type UseMujocoResult =
+  | { status: 'loading'; isPending: true; isReady: false; isError: false; error: null; api: null; mjModelRef: null; mjDataRef: null }
+  | { status: 'error'; isPending: false; isReady: false; isError: true; error: string; api: null; mjModelRef: null; mjDataRef: null }
+  | { status: 'ready'; isPending: false; isReady: true; isError: false; error: null;
+      api: MujocoSimAPI; mjModelRef: React.RefObject<MujocoModel | null>; mjDataRef: React.RefObject<MujocoData | null> };
+
+export function useMujocoContext(): MujocoSimContextValue {
   const ctx = useContext(MujocoSimContext);
   if (!ctx)
     throw new Error('useMujoco must be used inside <MujocoSimProvider>');
   return ctx;
 }
 
+export function useMujoco(): UseMujocoResult {
+  const ctx = useMujocoContext();
+  if (ctx.status === 'ready') {
+    return {
+      status: 'ready',
+      isPending: false,
+      isReady: true,
+      isError: false,
+      error: null,
+      api: ctx.api,
+      mjModelRef: ctx.mjModelRef,
+      mjDataRef: ctx.mjDataRef,
+    };
+  }
+  if (ctx.status === 'error') {
+    return {
+      status: 'error',
+      isPending: false,
+      isReady: false,
+      isError: true,
+      error: ctx.errorRef.current ?? 'Unknown error',
+      api: null,
+      mjModelRef: null,
+      mjDataRef: null,
+    };
+  }
+  return {
+    status: 'loading',
+    isPending: true,
+    isReady: false,
+    isError: false,
+    error: null,
+    api: null,
+    mjModelRef: null,
+    mjDataRef: null,
+  };
+}
+
 export function useBeforePhysicsStep(callback: PhysicsStepCallback) {
-  const { beforeStepCallbacks } = useMujoco();
+  const { beforeStepCallbacks } = useMujocoContext();
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
 
@@ -116,7 +165,7 @@ export function useBeforePhysicsStep(callback: PhysicsStepCallback) {
 }
 
 export function useAfterPhysicsStep(callback: PhysicsStepCallback) {
-  const { afterStepCallbacks } = useMujoco();
+  const { afterStepCallbacks } = useMujocoContext();
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
 
@@ -181,6 +230,10 @@ export function MujocoSimProvider({
   const beforeStepCallbacks = useRef(new Set<PhysicsStepCallback>());
   const afterStepCallbacks = useRef(new Set<PhysicsStepCallback>());
   const resetCallbacks = useRef(new Set<() => void>());
+  const errorRef = useRef<string | null>(null);
+  const bodyRegistryRef = useRef(new Map<string, { definition: SceneObject; hasCustomChildren: boolean }>());
+  const hiddenBodiesRef = useRef(new Set<string>());
+  const bodyReloadTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
   configRef.current = config;
 
@@ -207,13 +260,26 @@ export function MujocoSimProvider({
     model.opt.timestep = timestep;
   }, [timestep]);
 
+  // --- Build merged config (base + body registry) ---
+  function buildMergedConfig(baseConfig: SceneConfig): SceneConfig {
+    if (bodyRegistryRef.current.size === 0) return baseConfig;
+    const registeredNames = new Set(bodyRegistryRef.current.keys());
+    const baseObjects = (baseConfig.sceneObjects ?? []).filter(o => !registeredNames.has(o.name));
+    const registeredBodies = Array.from(bodyRegistryRef.current.values()).map(e => e.definition);
+    hiddenBodiesRef.current.clear();
+    for (const [name, entry] of bodyRegistryRef.current) {
+      if (entry.hasCustomChildren) hiddenBodiesRef.current.add(name);
+    }
+    return { ...baseConfig, sceneObjects: [...baseObjects, ...registeredBodies] };
+  }
+
   // --- Load scene on mount ---
   useEffect(() => {
     let disposed = false;
 
     (async () => {
       try {
-        const result = await loadScene(mujoco, config);
+        const result = await loadScene(mujoco, buildMergedConfig(config));
         if (disposed) {
           result.mjModel.delete();
           result.mjData.delete();
@@ -236,8 +302,10 @@ export function MujocoSimProvider({
         setStatus('ready');
       } catch (e: unknown) {
         if (!disposed) {
+          const err = e instanceof Error ? e : new Error(String(e));
+          errorRef.current = err.message;
           setStatus('error');
-          onError?.(e instanceof Error ? e : new Error(String(e)));
+          onError?.(err);
         }
       }
     })();
@@ -755,11 +823,20 @@ export function MujocoSimProvider({
       setStatus('ready');
     } catch (e) {
       if (gen !== loadGenRef.current) return;
+      errorRef.current = e instanceof Error ? e.message : String(e);
       setStatus('error');
       throw e;
     }
   }, [mujoco]);
 
+  const requestBodyReload = useCallback(() => {
+    if (bodyReloadTimerRef.current) clearTimeout(bodyReloadTimerRef.current);
+    bodyReloadTimerRef.current = setTimeout(() => {
+      bodyReloadTimerRef.current = null;
+      loadSceneApi(buildMergedConfig(configRef.current));
+    }, 0);
+  }, [loadSceneApi]);
+
   const getCanvasSnapshot = useCallback(
     (width?: number, height?: number, mimeType = 'image/jpeg'): string => {
       if (width && height) {
@@ -916,9 +993,13 @@ export function MujocoSimProvider({
       beforeStepCallbacks,
       afterStepCallbacks,
       resetCallbacks,
+      errorRef,
+      bodyRegistryRef,
+      hiddenBodiesRef,
+      requestBodyReload,
       status,
     }),
-    [api, status]
+    [api, status, requestBodyReload]
   );
 
   return (

package/src/core/createController.tsx

@@ -1,8 +1,6 @@
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
- *
- * createController — typed factory for BYOC (Bring Your Own Controller) plugins.
  */
 
 import { useMemo, useRef } from 'react';
@@ -89,3 +87,57 @@ export function createController<TConfig>(
 
   return Controller as 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
+ * ```
+ */
+export function createControllerHook<TConfig, TValue>(
+  options: ControllerOptions<TConfig>,
+  useImpl: (config: TConfig | null) => TValue | null,
+): (config: TConfig | null) => TValue | null {
+  const useController = (config: TConfig | null): TValue | null => {
+    const configObj = config as Record<string, unknown> | null;
+    const stableRef = useRef(configObj);
+    if (configObj && stableRef.current) {
+      if (!shallowEqual(stableRef.current, configObj)) {
+        stableRef.current = configObj;
+      }
+    } else {
+      stableRef.current = configObj;
+    }
+
+    const mergedConfig = useMemo(
+      () => stableRef.current
+        ? ({ ...options.defaultConfig, ...stableRef.current } as TConfig)
+        : null,
+      [stableRef.current],
+    );
+
+    return useImpl(mergedConfig);
+  };
+
+  return useController;
+}

package/src/hooks/useActuators.ts

@@ -4,7 +4,7 @@
  */
 
 import { useMemo } from 'react';
-import { useMujoco } from '../core/MujocoSimProvider';
+import { useMujocoContext } from '../core/MujocoSimProvider';
 import { getName } from '../core/SceneLoader';
 import type { ActuatorInfo } from '../types';
 
@@ -13,7 +13,7 @@ import type { ActuatorInfo } from '../types';
  * Computed once when the model loads. Consumer reads/writes data.ctrl[id] directly.
  */
 export function useActuators(): ActuatorInfo[] {
-  const { mjModelRef, status } = useMujoco();
+  const { mjModelRef, status } = useMujocoContext();
 
   return useMemo(() => {
     if (status !== 'ready') return [];

package/src/hooks/useBodyState.ts

@@ -7,7 +7,7 @@
 
 import { useEffect, useRef } from 'react';
 import * as THREE from 'three';
-import { useMujoco, useAfterPhysicsStep } from '../core/MujocoSimProvider';
+import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { findBodyByName } from '../core/SceneLoader';
 import type { BodyStateResult } from '../types';
 
@@ -16,7 +16,7 @@ import type { BodyStateResult } from '../types';
  * All values are ref-based — updated every physics frame without re-renders.
  */
 export function useBodyState(name: string): BodyStateResult {
-  const { mjModelRef, status } = useMujoco();
+  const { mjModelRef, status } = useMujocoContext();
   const bodyIdRef = useRef(-1);
   const position = useRef(new THREE.Vector3());
   const quaternion = useRef(new THREE.Quaternion());

package/src/hooks/useContacts.ts

@@ -7,7 +7,7 @@
  */
 
 import { useCallback, useEffect, useRef } from 'react';
-import { useMujoco, useAfterPhysicsStep } from '../core/MujocoSimProvider';
+import { useMujocoContext, useAfterPhysicsStep } from '../core/MujocoSimProvider';
 import { findBodyByName, getName } from '../core/SceneLoader';
 import { getContact } from '../types';
 import type { ContactInfo, MujocoModel } from '../types';
@@ -39,7 +39,7 @@ export function useContacts(
   bodyName?: string,
   callback?: (contacts: ContactInfo[]) => void,
 ): React.RefObject<ContactInfo[]> {
-  const { mjModelRef, status } = useMujoco();
+  const { mjModelRef, status } = useMujocoContext();
   const contactsRef = useRef<ContactInfo[]>([]);
   const bodyIdRef = useRef(-1);
   const bodyResolvedRef = useRef(false);

package/src/hooks/useCtrl.ts

@@ -6,7 +6,7 @@
  */
 
 import { useCallback, useEffect, useRef } from 'react';
-import { useMujoco } from '../core/MujocoSimProvider';
+import { useMujocoContext } from '../core/MujocoSimProvider';
 import { findActuatorByName } from '../core/SceneLoader';
 
 /**
@@ -17,7 +17,7 @@ import { findActuatorByName } from '../core/SceneLoader';
  * - `setValue` writes directly to `data.ctrl[actuatorId]`.
  */
 export function useCtrl(name: string): [React.RefObject<number>, (value: number) => void] {
-  const { mjModelRef, mjDataRef, status } = useMujoco();
+  const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const actuatorIdRef = useRef(-1);
   const valueRef = useRef(0);
 

package/src/hooks/useCtrlNoise.ts

@@ -6,7 +6,7 @@
  */
 
 import { useRef } from 'react';
-import { useMujoco, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
 
 interface CtrlNoiseConfig {
   /** Exponential filter rate (0-1). Higher = faster noise changes. Default: 0.01. */
@@ -25,7 +25,7 @@ interface CtrlNoiseConfig {
  * data.ctrl[i] += noise[i]
  */
 export function useCtrlNoise(config: CtrlNoiseConfig = {}) {
-  const { mjModelRef } = useMujoco();
+  const { mjModelRef } = useMujocoContext();
   const configRef = useRef(config);
   configRef.current = config;
   const noiseRef = useRef<Float64Array | null>(null);

package/src/hooks/useGamepad.ts

@@ -6,7 +6,7 @@
  */
 
 import { useEffect, useRef } from 'react';
-import { useMujoco, useBeforePhysicsStep } from '../core/MujocoSimProvider';
+import { useMujocoContext, useBeforePhysicsStep } from '../core/MujocoSimProvider';
 import { findActuatorByName } from '../core/SceneLoader';
 
 interface GamepadConfig {
@@ -29,7 +29,7 @@ interface GamepadConfig {
  * Buttons map their 0..1 pressed value to the actuator.
  */
 export function useGamepad(config: GamepadConfig) {
-  const { mjModelRef, status } = useMujoco();
+  const { mjModelRef, status } = useMujocoContext();
   const configRef = useRef(config);
   configRef.current = config;