mujoco-react 8.2.1 → 8.4.0

package/dist/index.js

@@ -1,4 +1,5 @@
-import loadMujoco from 'mujoco-js';
+import loadMujoco from '@mujoco/mujoco';
+import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, forwardRef, useEffect, useContext, useState, useRef, useCallback, useMemo, useLayoutEffect } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { Canvas, useThree, useFrame } from '@react-three/fiber';
@@ -14,15 +15,57 @@ var MujocoContext = createContext({
 function useMujocoWasm() {
   return useContext(MujocoContext);
 }
-function MujocoProvider({ wasmUrl, timeout = 3e4, children, onError }) {
+function canUseThreadedWasm() {
+  return typeof globalThis !== "undefined" && globalThis.crossOriginIsolated === true;
+}
+function isMujocoModule(value) {
+  return typeof value === "object" && value !== null && "FS" in value && "MjModel" in value && "MjData" in value && "mj_step" in value;
+}
+function hasWasmUrl(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function resolveWasmVariant(variant, threadedLoader, mtWasmUrl) {
+  if (variant === "threaded") return "threaded";
+  if (variant === "auto" && threadedLoader && mtWasmUrl && canUseThreadedWasm()) return "threaded";
+  return "single";
+}
+function MujocoProvider({
+  wasmUrl,
+  mtWasmUrl,
+  threadedLoader,
+  wasmVariant = "single",
+  timeout = 3e4,
+  children,
+  onError
+}) {
   const [status, setStatus] = useState("loading");
   const [error, setError] = useState(null);
   const moduleRef = useRef(null);
   const isMounted = useRef(true);
   useEffect(() => {
     isMounted.current = true;
-    const wasmPromise = loadMujoco({
-      ...wasmUrl ? { locateFile: (path) => path.endsWith(".wasm") ? wasmUrl : path } : {},
+    const variant = resolveWasmVariant(wasmVariant, threadedLoader, mtWasmUrl);
+    if (variant === "threaded" && !threadedLoader) {
+      const err = new Error('MujocoProvider wasmVariant="threaded" requires a threadedLoader from @mujoco/mujoco/mt');
+      setError(err.message);
+      setStatus("error");
+      onError?.(err);
+      return;
+    }
+    let selectedWasmUrl = wasmUrl ?? defaultMujocoWasmUrl;
+    if (variant === "threaded") {
+      if (!hasWasmUrl(mtWasmUrl)) {
+        const err = new Error('MujocoProvider wasmVariant="threaded" requires mtWasmUrl from @mujoco/mujoco/mt/mujoco.wasm?url');
+        setError(err.message);
+        setStatus("error");
+        onError?.(err);
+        return;
+      }
+      selectedWasmUrl = mtWasmUrl;
+    }
+    const load = variant === "threaded" && threadedLoader ? threadedLoader : loadMujoco;
+    const wasmPromise = load({
+      locateFile: (path) => path.endsWith(".wasm") ? selectedWasmUrl : path,
       printErr: (text) => {
         if (text.includes("Aborted") && isMounted.current) {
           setError("Simulation crashed. Reload page.");
@@ -35,6 +78,9 @@ function MujocoProvider({ wasmUrl, timeout = 3e4, children, onError }) {
     );
     Promise.race([wasmPromise, timeoutPromise]).then((inst) => {
       if (isMounted.current) {
+        if (!isMujocoModule(inst)) {
+          throw new Error("MuJoCo WASM module initialized with an unexpected shape");
+        }
         moduleRef.current = inst;
         setStatus("ready");
       }
@@ -49,7 +95,7 @@ function MujocoProvider({ wasmUrl, timeout = 3e4, children, onError }) {
     return () => {
       isMounted.current = false;
     };
-  }, [wasmUrl, timeout]);
+  }, [wasmUrl, mtWasmUrl, threadedLoader, wasmVariant, timeout, onError]);
   return /* @__PURE__ */ jsx(
     MujocoContext.Provider,
     {
@@ -60,13 +106,21 @@ function MujocoProvider({ wasmUrl, timeout = 3e4, children, onError }) {
 }
 
 // src/types.ts
-function getContact(data, i) {
+function getContact(contacts, i) {
   try {
-    return data.contact.get(i);
+    return contacts.get(i);
   } catch {
     return void 0;
   }
 }
+function withContacts(data, read) {
+  const contacts = data.contact;
+  try {
+    return read(contacts);
+  } finally {
+    contacts.delete?.();
+  }
+}
 var CapsuleGeometry = class extends THREE11.BufferGeometry {
   parameters;
   constructor(radius = 1, length = 1, capSegments = 4, radialSegments = 8) {
@@ -311,6 +365,12 @@ var GeomBuilder = class {
 };
 
 // src/core/SceneLoader.ts
+var JOINT_TYPE_NAMES = {
+  0: "free",
+  1: "ball",
+  2: "slide",
+  3: "hinge"
+};
 function getName(mjModel, address) {
   let name = "";
   let idx = address;
@@ -379,6 +439,276 @@ function getActuatedScalarQposAdr(mjModel, actuatorId) {
   if (jntType !== 2 && jntType !== 3) return -1;
   return mjModel.jnt_qposadr[jointId];
 }
+function getScalarJointDim(jointType) {
+  return jointType === 2 || jointType === 3 ? 1 : 0;
+}
+function unlimitedRange() {
+  return [-Infinity, Infinity];
+}
+function isScalarJoint(mjModel, jointId) {
+  return jointId >= 0 && jointId < mjModel.njnt && getScalarJointDim(mjModel.jnt_type[jointId]) === 1;
+}
+function getActuatorJointId(mjModel, actuatorId) {
+  if (actuatorId < 0 || actuatorId >= mjModel.nu) return -1;
+  const trnType = mjModel.actuator_trntype?.[actuatorId];
+  if (trnType !== void 0 && trnType !== 0 && trnType !== 1) return -1;
+  const jointId = mjModel.actuator_trnid[2 * actuatorId];
+  return isScalarJoint(mjModel, jointId) ? jointId : -1;
+}
+function getJointInfo(mjModel, jointId) {
+  const type = mjModel.jnt_type[jointId];
+  const range = [mjModel.jnt_range[2 * jointId], mjModel.jnt_range[2 * jointId + 1]];
+  return {
+    id: jointId,
+    name: getName(mjModel, mjModel.name_jntadr[jointId]),
+    type,
+    typeName: JOINT_TYPE_NAMES[type] ?? `unknown(${type})`,
+    range,
+    limited: range[0] < range[1],
+    bodyId: mjModel.jnt_bodyid[jointId],
+    qposAdr: mjModel.jnt_qposadr[jointId],
+    dofAdr: mjModel.jnt_dofadr[jointId]
+  };
+}
+function getActuatorInfo(mjModel, actuatorId) {
+  const hasRange = mjModel.actuator_ctrlrange[2 * actuatorId] < mjModel.actuator_ctrlrange[2 * actuatorId + 1];
+  return {
+    id: actuatorId,
+    name: getName(mjModel, mjModel.name_actuatoradr[actuatorId]),
+    range: hasRange ? [mjModel.actuator_ctrlrange[2 * actuatorId], mjModel.actuator_ctrlrange[2 * actuatorId + 1]] : unlimitedRange()
+  };
+}
+function includesResourceName(names, name) {
+  return names.includes(name);
+}
+function matchesSelector(info, selector) {
+  if (typeof selector === "string") return info.name === selector;
+  if (selector instanceof RegExp) return selector.test(info.name);
+  if (Array.isArray(selector)) return includesResourceName(selector, info.name);
+  if (typeof selector === "function") return selector(info);
+  return false;
+}
+function orderedJointIdsFromSelector(mjModel, selector) {
+  if (typeof selector === "string") {
+    const id = findJointByName(mjModel, selector);
+    return id >= 0 && isScalarJoint(mjModel, id) ? [id] : [];
+  }
+  if (Array.isArray(selector)) {
+    return selector.map((name) => findJointByName(mjModel, name)).filter((id) => id >= 0 && isScalarJoint(mjModel, id));
+  }
+  const ids = [];
+  for (let i = 0; i < mjModel.njnt; i++) {
+    if (!isScalarJoint(mjModel, i)) continue;
+    const info = getJointInfo(mjModel, i);
+    if (matchesSelector(info, selector)) ids.push(i);
+  }
+  return ids;
+}
+function orderedActuatorIdsFromSelector(mjModel, selector) {
+  if (typeof selector === "string") {
+    const id = findActuatorByName(mjModel, selector);
+    return id >= 0 && getActuatorJointId(mjModel, id) >= 0 ? [id] : [];
+  }
+  if (Array.isArray(selector)) {
+    return selector.map((name) => findActuatorByName(mjModel, name)).filter((id) => id >= 0 && getActuatorJointId(mjModel, id) >= 0);
+  }
+  const ids = [];
+  for (let i = 0; i < mjModel.nu; i++) {
+    if (getActuatorJointId(mjModel, i) < 0) continue;
+    const info = getActuatorInfo(mjModel, i);
+    if (matchesSelector(info, selector)) ids.push(i);
+  }
+  return ids;
+}
+function inferScalarJointChain(mjModel, bodyId) {
+  if (bodyId < 0 || bodyId >= mjModel.nbody) return [];
+  const chainByBody = [];
+  let current = bodyId;
+  const seen = /* @__PURE__ */ new Set();
+  while (current >= 0 && current < mjModel.nbody && !seen.has(current)) {
+    seen.add(current);
+    const joints = [];
+    const jointCount = mjModel.body_jntnum[current] ?? 0;
+    const jointStart = mjModel.body_jntadr[current] ?? -1;
+    for (let i = 0; i < jointCount; i++) {
+      const jointId = jointStart + i;
+      if (isScalarJoint(mjModel, jointId)) joints.push(jointId);
+    }
+    if (joints.length) chainByBody.push(joints);
+    const parent = mjModel.body_parentid[current];
+    if (parent === current) break;
+    current = parent;
+  }
+  return chainByBody.reverse().flat();
+}
+function unique(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const value of values) {
+    if (seen.has(value)) continue;
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+function findActuatorForJoint(mjModel, jointId, preferredActuatorIds) {
+  const search = preferredActuatorIds ?? Array.from({ length: mjModel.nu }, (_, i) => i);
+  for (const actuatorId of search) {
+    if (getActuatorJointId(mjModel, actuatorId) === jointId) return actuatorId;
+  }
+  return -1;
+}
+function buildControlGroup(mjModel, jointIds, preferredActuatorIds) {
+  const ids = unique(jointIds).filter((id) => isScalarJoint(mjModel, id));
+  if (!ids.length) return null;
+  const joints = [];
+  const actuators = [];
+  const qposAdr = [];
+  const dofAdr = [];
+  const ctrlAdr = [];
+  for (const jointId of ids) {
+    const actuatorId = findActuatorForJoint(mjModel, jointId, preferredActuatorIds);
+    const joint = getJointInfo(mjModel, jointId);
+    qposAdr.push(joint.qposAdr);
+    dofAdr.push(joint.dofAdr);
+    if (actuatorId >= 0) {
+      const actuator = getActuatorInfo(mjModel, actuatorId);
+      actuators.push(actuator);
+      ctrlAdr.push(actuatorId);
+      joints.push({
+        ...joint,
+        actuatorId,
+        actuatorName: actuator.name,
+        ctrlAdr: actuatorId,
+        ctrlRange: actuator.range
+      });
+    } else {
+      joints.push({
+        ...joint,
+        actuatorId: null,
+        actuatorName: null,
+        ctrlAdr: null,
+        ctrlRange: null
+      });
+    }
+  }
+  return {
+    joints,
+    actuators,
+    qposAdr,
+    dofAdr,
+    ctrlAdr,
+    readQpos(data) {
+      return new Float64Array(qposAdr.map((adr) => data.qpos[adr] ?? 0));
+    },
+    readCtrl(data) {
+      return new Float64Array(joints.map((joint) => joint.ctrlAdr === null ? 0 : data.ctrl[joint.ctrlAdr] ?? 0));
+    },
+    writeQpos(data, values) {
+      for (let i = 0; i < Math.min(values.length, qposAdr.length); i++) {
+        data.qpos[qposAdr[i]] = values[i];
+      }
+    },
+    writeCtrl(data, values) {
+      for (let i = 0; i < Math.min(values.length, joints.length); i++) {
+        const adr = joints[i].ctrlAdr;
+        if (adr !== null) data.ctrl[adr] = values[i];
+      }
+    }
+  };
+}
+function getActuatedJoints(mjModel) {
+  const result = [];
+  for (let actuatorId = 0; actuatorId < mjModel.nu; actuatorId++) {
+    const jointId = getActuatorJointId(mjModel, actuatorId);
+    if (jointId < 0) continue;
+    const actuator = getActuatorInfo(mjModel, actuatorId);
+    result.push({
+      ...getJointInfo(mjModel, jointId),
+      actuatorId,
+      actuatorName: actuator.name,
+      ctrlAdr: actuatorId,
+      ctrlRange: actuator.range
+    });
+  }
+  return result;
+}
+function getControlMap(mjModel) {
+  const actuatorIds = Array.from({ length: mjModel.nu }, (_, i) => i).filter((id) => getActuatorJointId(mjModel, id) >= 0);
+  const jointIds = actuatorIds.map((id) => getActuatorJointId(mjModel, id));
+  return buildControlGroup(mjModel, jointIds, actuatorIds) ?? createContiguousControlGroup(mjModel, 0);
+}
+function resolveControlGroup(mjModel, selector) {
+  if (selector.actuators) {
+    const actuatorIds = orderedActuatorIdsFromSelector(mjModel, selector.actuators);
+    const jointIds = actuatorIds.map((id) => getActuatorJointId(mjModel, id));
+    return buildControlGroup(mjModel, jointIds, actuatorIds);
+  }
+  if (selector.joints) {
+    return buildControlGroup(mjModel, orderedJointIdsFromSelector(mjModel, selector.joints));
+  }
+  if (selector.siteName) {
+    const siteId = findSiteByName(mjModel, selector.siteName);
+    const bodyId = siteId >= 0 ? mjModel.site_bodyid?.[siteId] ?? -1 : -1;
+    return buildControlGroup(mjModel, inferScalarJointChain(mjModel, bodyId));
+  }
+  if (selector.bodyName) {
+    return buildControlGroup(mjModel, inferScalarJointChain(mjModel, findBodyByName(mjModel, selector.bodyName)));
+  }
+  return getControlMap(mjModel);
+}
+function createContiguousControlGroup(mjModel, count) {
+  const n = Math.max(0, Math.min(count, mjModel.nq, mjModel.nu));
+  const joints = [];
+  const actuators = [];
+  const qposAdr = [];
+  const dofAdr = [];
+  const ctrlAdr = [];
+  for (let i = 0; i < n; i++) {
+    qposAdr.push(i);
+    dofAdr.push(i);
+    ctrlAdr.push(i);
+    const jointId = Array.from({ length: mjModel.njnt }, (_, id) => id).find((id) => mjModel.jnt_qposadr[id] === i);
+    const actuator = getActuatorInfo(mjModel, i);
+    actuators.push(actuator);
+    joints.push({
+      ...jointId !== void 0 ? getJointInfo(mjModel, jointId) : {
+        id: i,
+        name: `qpos${i}`,
+        type: 3,
+        typeName: "hinge",
+        range: unlimitedRange(),
+        limited: false,
+        bodyId: -1,
+        qposAdr: i,
+        dofAdr: i
+      },
+      actuatorId: i,
+      actuatorName: actuator.name,
+      ctrlAdr: i,
+      ctrlRange: actuator.range
+    });
+  }
+  return {
+    joints,
+    actuators,
+    qposAdr,
+    dofAdr,
+    ctrlAdr,
+    readQpos(data) {
+      return new Float64Array(qposAdr.map((adr) => data.qpos[adr] ?? 0));
+    },
+    readCtrl(data) {
+      return new Float64Array(ctrlAdr.map((adr) => data.ctrl[adr] ?? 0));
+    },
+    writeQpos(data, values) {
+      for (let i = 0; i < Math.min(values.length, qposAdr.length); i++) data.qpos[qposAdr[i]] = values[i];
+    },
+    writeCtrl(data, values) {
+      for (let i = 0; i < Math.min(values.length, ctrlAdr.length); i++) data.ctrl[ctrlAdr[i]] = values[i];
+    }
+  };
+}
 function sceneObjectToXml(obj) {
   const joint = obj.freejoint ? "<freejoint/>" : "";
   const pos = obj.position.map((v) => v.toFixed(3)).join(" ");
@@ -403,6 +733,15 @@ function ensureDir(mujoco, fname) {
     }
   }
 }
+function loadModelFromPath(mujoco, path) {
+  if (mujoco.MjModel.from_xml_path) {
+    return mujoco.MjModel.from_xml_path(path);
+  }
+  if (mujoco.MjModel.loadFromXML) {
+    return mujoco.MjModel.loadFromXML(path);
+  }
+  throw new Error("MuJoCo WASM module does not expose an XML path loader");
+}
 async function loadScene(mujoco, config, onProgress) {
   try {
     mujoco.FS.unmount("/working");
@@ -486,7 +825,7 @@ async function loadScene(mujoco, config, onProgress) {
     }
   }
   onProgress?.("Loading model...");
-  const mjModel = mujoco.MjModel.loadFromXML(`/working/${config.sceneFile}`);
+  const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
   if (config.homeJoints) {
     const homeCount = Math.min(config.homeJoints.length, mjModel.nu);
@@ -609,7 +948,7 @@ function SceneRenderer(props) {
     }
   );
 }
-var JOINT_TYPE_NAMES = ["free", "ball", "slide", "hinge"];
+var JOINT_TYPE_NAMES2 = ["free", "ball", "slide", "hinge"];
 var GEOM_TYPE_NAMES = ["plane", "hfield", "sphere", "capsule", "ellipsoid", "cylinder", "box", "mesh"];
 var SENSOR_TYPE_NAMES = {
   0: "touch",
@@ -662,6 +1001,22 @@ var SENSOR_TYPE_NAMES = {
   47: "plugin",
   48: "user"
 };
+var EMPTY_CONTROL_GROUP = {
+  joints: [],
+  actuators: [],
+  qposAdr: [],
+  dofAdr: [],
+  ctrlAdr: [],
+  readQpos: () => new Float64Array(0),
+  readCtrl: () => new Float64Array(0),
+  writeQpos: () => {
+  },
+  writeCtrl: () => {
+  }
+};
+function isMutableApiRef(ref) {
+  return typeof ref === "object" && ref !== null && "current" in ref;
+}
 var _applyForce = new Float64Array(3);
 var _applyTorque = new Float64Array(3);
 var _applyPoint = new Float64Array(3);
@@ -859,7 +1214,7 @@ function MujocoSimProvider({
       if (externalApiRef) {
         if (typeof externalApiRef === "function") {
           externalApiRef(api2);
-        } else {
+        } else if (isMutableApiRef(externalApiRef)) {
           externalApiRef.current = api2;
         }
       }
@@ -1080,18 +1435,20 @@ function MujocoSimProvider({
     if (!model || !data) return [];
     const contacts = [];
     const ncon = data.ncon;
-    for (let i = 0; i < ncon; i++) {
-      const c = getContact(data, i);
-      if (!c) break;
-      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
-      });
-    }
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < ncon; i++) {
+        const c = getContact(contactArray, i);
+        if (!c) break;
+        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
+        });
+      }
+    });
     return contacts;
   }, []);
   const getBodies = useCallback(() => {
@@ -1114,14 +1471,14 @@ function MujocoSimProvider({
     const result = [];
     for (let i = 0; i < model.njnt; i++) {
       const type = model.jnt_type[i];
-      const limited = model.jnt_limited ? model.jnt_limited[i] !== 0 : false;
+      const range = [model.jnt_range[2 * i], model.jnt_range[2 * i + 1]];
       result.push({
         id: i,
         name: getName(model, model.name_jntadr[i]),
         type,
-        typeName: JOINT_TYPE_NAMES[type] ?? `unknown(${type})`,
-        range: [model.jnt_range[2 * i], model.jnt_range[2 * i + 1]],
-        limited,
+        typeName: JOINT_TYPE_NAMES2[type] ?? `unknown(${type})`,
+        range,
+        limited: range[0] < range[1],
         bodyId: model.jnt_bodyid[i],
         qposAdr: model.jnt_qposadr[i],
         dofAdr: model.jnt_dofadr[i]
@@ -1173,6 +1530,18 @@ function MujocoSimProvider({
     }
     return result;
   }, []);
+  const getControlMapApi = useCallback(() => {
+    const model = mjModelRef.current;
+    return model ? getControlMap(model) : EMPTY_CONTROL_GROUP;
+  }, []);
+  const getActuatedJointsApi = useCallback(() => {
+    const model = mjModelRef.current;
+    return model ? getActuatedJoints(model) : [];
+  }, []);
+  const resolveControlGroupApi = useCallback((selector) => {
+    const model = mjModelRef.current;
+    return model ? resolveControlGroup(model, selector) : null;
+  }, []);
   const getSensors = useCallback(() => {
     const model = mjModelRef.current;
     if (!model) return [];
@@ -1409,6 +1778,9 @@ function MujocoSimProvider({
       getQvel,
       setCtrl,
       getCtrl: getCtrl2,
+      getControlMap: getControlMapApi,
+      getActuatedJoints: getActuatedJointsApi,
+      resolveControlGroup: resolveControlGroupApi,
       applyForce,
       applyTorque: applyTorqueApi,
       setExternalForce,
@@ -1455,6 +1827,9 @@ function MujocoSimProvider({
       getQvel,
       setCtrl,
       getCtrl2,
+      getControlMapApi,
+      getActuatedJointsApi,
+      resolveControlGroupApi,
       applyForce,
       applyTorqueApi,
       setExternalForce,
@@ -1648,16 +2023,16 @@ var GenericIK = class {
    * @param model       MuJoCo model
    * @param data        MuJoCo data (qpos will be temporarily modified, then restored)
    * @param siteId      Index of the end-effector site to control
-   * @param numJoints   Number of arm joints (assumes qpos[0..numJoints-1])
+   * @param qposAdr     qpos addresses for scalar joints in solve order
    * @param targetPos   Target position in world frame
    * @param targetQuat  Target orientation in world frame
-   * @param currentQ    Current joint angles (length = numJoints)
+   * @param currentQ    Current joint angles matching qposAdr order
    * @param opts        Optional solver parameters
    * @returns Joint angles array, or null if solver diverged
    */
-  solve(model, data, siteId, numJoints, targetPos, targetQuat, currentQ, opts) {
+  solve(model, data, siteId, qposAdr, targetPos, targetQuat, currentQ, opts) {
     const o = { ...DEFAULTS, ...opts };
-    const n = numJoints;
+    const n = qposAdr.length;
     const savedQpos = new Float64Array(data.qpos.length);
     savedQpos.set(data.qpos);
     const R_target = quatToMat3(targetQuat);
@@ -1674,8 +2049,9 @@ var GenericIK = class {
     const pertSiteMat = new Float64Array(9);
     let bestQ = null;
     let bestErr = Infinity;
+    if (n === 0) return null;
     for (let iter = 0; iter < o.maxIterations; iter++) {
-      for (let i = 0; i < n; i++) data.qpos[i] = q[i];
+      for (let i = 0; i < n; i++) data.qpos[qposAdr[i]] = q[i];
       this.mujoco.mj_forward(model, data);
       const sp = data.site_xpos;
       const sm = data.site_xmat;
@@ -1704,8 +2080,9 @@ var GenericIK = class {
       }
       if (errNorm < o.tolerance) break;
       for (let j = 0; j < n; j++) {
-        const saved = data.qpos[j];
-        data.qpos[j] = q[j] + o.epsilon;
+        const adr = qposAdr[j];
+        const saved = data.qpos[adr];
+        data.qpos[adr] = q[j] + o.epsilon;
         this.mujoco.mj_forward(model, data);
         for (let i = 0; i < 3; i++) pertSitePos[i] = sp[off3 + i];
         for (let i = 0; i < 9; i++) pertSiteMat[i] = sm[off9 + i];
@@ -1716,9 +2093,9 @@ var GenericIK = class {
         J[3 * n + j] = dRot[0] / o.epsilon * o.rotWeight;
         J[4 * n + j] = dRot[1] / o.epsilon * o.rotWeight;
         J[5 * n + j] = dRot[2] / o.epsilon * o.rotWeight;
-        data.qpos[j] = saved;
+        data.qpos[adr] = saved;
       }
-      for (let i = 0; i < n; i++) data.qpos[i] = q[i];
+      for (let i = 0; i < n; i++) data.qpos[qposAdr[i]] = q[i];
       for (let r = 0; r < 6; r++) {
         for (let c = 0; c < 6; c++) {
           let sum = 0;
@@ -1890,6 +2267,7 @@ var useIkController = createControllerHook(
     const ikCalculatingRef = useRef(false);
     const ikTargetRef = useRef(new THREE11.Group());
     const siteIdRef = useRef(-1);
+    const controlGroupRef = useRef(null);
     const genericIkRef = useRef(new GenericIK(mujocoRef.current));
     const firstIkEnableRef = useRef(true);
     const needsInitialSync = useRef(true);
@@ -1905,31 +2283,39 @@ var useIkController = createControllerHook(
     useEffect(() => {
       if (!config) {
         siteIdRef.current = -1;
+        controlGroupRef.current = null;
         return;
       }
       const model = mjModelRef.current;
       if (!model || status !== "ready") {
         siteIdRef.current = -1;
+        controlGroupRef.current = null;
         return;
       }
       siteIdRef.current = findSiteByName(model, config.siteName);
+      controlGroupRef.current = config.numJoints !== void 0 ? createContiguousControlGroup(model, config.numJoints) : resolveControlGroup(model, {
+        siteName: config.siteName,
+        joints: config.joints,
+        actuators: config.actuators
+      });
       const data = mjDataRef.current;
       if (data && ikTargetRef.current) {
         syncGizmoToSite(data, siteIdRef.current, ikTargetRef.current);
       }
-    }, [config?.siteName, status, mjModelRef, mjDataRef, config]);
+    }, [config?.siteName, config?.numJoints, config?.joints, config?.actuators, status, mjModelRef, mjDataRef, config]);
     const ikSolveFn = useCallback(
       (pos, quat, currentQ) => {
         if (!config) return null;
         if (config.ikSolveFn) return config.ikSolveFn(pos, quat, currentQ);
         const model = mjModelRef.current;
         const data = mjDataRef.current;
-        if (!model || !data || siteIdRef.current === -1) return null;
+        const controlGroup = controlGroupRef.current;
+        if (!model || !data || !controlGroup || siteIdRef.current === -1) return null;
         return genericIkRef.current.solve(
           model,
           data,
           siteIdRef.current,
-          config.numJoints,
+          controlGroup.qposAdr,
           pos,
           quat,
           currentQ,
@@ -1968,12 +2354,17 @@ var useIkController = createControllerHook(
       const target = ikTargetRef.current;
       if (!target) return;
       ikCalculatingRef.current = true;
-      const numJoints = config.numJoints;
-      const currentQ = [];
-      for (let i = 0; i < numJoints; i++) currentQ.push(data.qpos[i]);
-      const solution = ikSolveFnRef.current(target.position, target.quaternion, currentQ);
+      const controlGroup = controlGroupRef.current;
+      if (!controlGroup) return;
+      const currentQ = Array.from(controlGroup.readQpos(data));
+      const solution = config.ikSolveFn ? config.ikSolveFn(target.position, target.quaternion, currentQ, {
+        model,
+        data,
+        siteId: siteIdRef.current,
+        controlGroup
+      }) : ikSolveFnRef.current(target.position, target.quaternion, currentQ);
       if (solution) {
-        for (let i = 0; i < numJoints; i++) data.ctrl[i] = solution[i];
+        controlGroup.writeCtrl(data, solution);
       }
     });
     useEffect(() => {
@@ -2255,18 +2646,20 @@ function ContactMarkers({
     }
     const ncon = data.ncon;
     const count = Math.min(ncon, maxContacts);
-    for (let i = 0; i < count; i++) {
-      const c = getContact(data, i);
-      if (!c) {
-        mesh.count = i;
-        mesh.instanceMatrix.needsUpdate = true;
-        return;
+    let resolvedCount = count;
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < count; i++) {
+        const c = getContact(contactArray, i);
+        if (!c) {
+          resolvedCount = i;
+          return;
+        }
+        _dummy.position.set(c.pos[0], c.pos[1], c.pos[2]);
+        _dummy.updateMatrix();
+        mesh.setMatrixAt(i, _dummy.matrix);
       }
-      _dummy.position.set(c.pos[0], c.pos[1], c.pos[2]);
-      _dummy.updateMatrix();
-      mesh.setMatrixAt(i, _dummy.matrix);
-    }
-    mesh.count = count;
+    });
+    mesh.count = resolvedCount;
     mesh.instanceMatrix.needsUpdate = true;
   });
   if (status !== "ready") return null;
@@ -2807,22 +3200,24 @@ function Debug({
     if (!data || pool.length === 0) return;
     const ncon = data.ncon;
     let arrowIdx = 0;
-    for (let i = 0; i < Math.min(ncon, MAX_CONTACT_ARROWS); i++) {
-      const c = getContact(data, i);
-      if (!c) break;
-      _contactPos.set(c.pos[0], c.pos[1], c.pos[2]);
-      _contactNormal.set(c.frame[0], c.frame[1], c.frame[2]);
-      const force = Math.abs(c.dist) * 100;
-      const length = Math.min(force * 0.01, 0.1);
-      if (length > 1e-3 && arrowIdx < pool.length) {
-        const arrow = pool[arrowIdx];
-        arrow.position.copy(_contactPos);
-        arrow.setDirection(_contactNormal);
-        arrow.setLength(length, length * 0.3, length * 0.15);
-        arrow.visible = true;
-        arrowIdx++;
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < Math.min(ncon, MAX_CONTACT_ARROWS); i++) {
+        const c = getContact(contactArray, i);
+        if (!c) break;
+        _contactPos.set(c.pos[0], c.pos[1], c.pos[2]);
+        _contactNormal.set(c.frame[0], c.frame[1], c.frame[2]);
+        const force = Math.abs(c.dist) * 100;
+        const length = Math.min(force * 0.01, 0.1);
+        if (length > 1e-3 && arrowIdx < pool.length) {
+          const arrow = pool[arrowIdx];
+          arrow.position.copy(_contactPos);
+          arrow.setDirection(_contactNormal);
+          arrow.setLength(length, length * 0.3, length * 0.15);
+          arrow.visible = true;
+          arrowIdx++;
+        }
       }
-    }
+    });
     for (let i = arrowIdx; i < pool.length; i++) {
       pool[i].visible = false;
     }
@@ -3053,23 +3448,25 @@ function useContacts(bodyName, callback) {
     }
     const contacts = [];
     const filterBody = bodyIdRef.current;
-    for (let i = 0; i < ncon; i++) {
-      const c = getContact(data, i);
-      if (!c) break;
-      if (filterBody >= 0) {
-        const b1 = model.geom_bodyid[c.geom1];
-        const b2 = model.geom_bodyid[c.geom2];
-        if (b1 !== filterBody && b2 !== filterBody) continue;
+    withContacts(data, (contactArray) => {
+      for (let i = 0; i < ncon; i++) {
+        const c = getContact(contactArray, i);
+        if (!c) break;
+        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
+        });
       }
-      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);
   });
@@ -4058,7 +4455,7 @@ function useCameraAnimation() {
  * WASM fields used: model.ntendon, model.ten_wrapadr, model.ten_wrapnum
  * data.wrap_xpos, data.ten_wrapadr (runtime)
  *
- * Note: ten_rgba and ten_width are NOT available in mujoco-js 0.0.7.
+ * Note: ten_rgba and ten_width may not be available in all MuJoCo WASM builds.
  * Tendons use a default color and width.
  */
 /**
@@ -4176,6 +4573,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-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 };
+export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, TendonRenderer, TrajectoryPlayer, 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, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map