mujoco-react 10.8.0 → 11.0.0

package/dist/index.js

@@ -1,14 +1,55 @@
-import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, createCaptureCamera, prepareCaptureCamera } from './chunk-5WFYM73E.js';
-export { CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, ModelActuators, ModelBodies, ModelCameras, ModelGeoms, ModelJoints, ModelKeyframes, ModelResources, ModelSensors, ModelSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, captureCameraFrameTensor, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, dataUrlToPolicyImageTensor, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, imageDataToPolicyImageTensor, pixelsToPolicyImageTensor, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment } from './chunk-5WFYM73E.js';
+import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, createCaptureCamera, prepareCaptureCamera } from './chunk-UCQ5MJP4.js';
+export { CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAMERA_FRAME_CAPTURE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, ModelActuators, ModelBodies, ModelCameras, ModelGeoms, ModelJoints, ModelKeyframes, ModelResources, ModelSensors, ModelSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, captureCameraFrameTensor, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, dataUrlToPolicyImageTensor, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, imageDataToPolicyImageTensor, pixelsToPolicyImageTensor, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment } from './chunk-UCQ5MJP4.js';
 import loadMujoco from '@mujoco/mujoco';
 import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, forwardRef, useRef, useEffect, useContext, useState, useCallback, useMemo, useLayoutEffect, useId } from 'react';
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { Canvas, useThree, useFrame } from '@react-three/fiber';
-import * as THREE11 from 'three';
+import * as THREE12 from 'three';
 import { mergeVertices } from 'three/examples/jsm/utils/BufferGeometryUtils.js';
 import { PivotControls } from '@react-three/drei';
 
+// src/core/engineState.ts
+var threadCounts = /* @__PURE__ */ new WeakMap();
+function configureModuleThreads(module, count) {
+  threadCounts.set(module, count);
+}
+function initializeDataThreads(module, data) {
+  const count = threadCounts.get(module) ?? 0;
+  if (count > 0) module.mju_threadpool(data, count);
+}
+function captureSimulationState(module, model, data) {
+  const signature = module.mjtState.mjSTATE_INTEGRATION.value;
+  const buffer = new module.DoubleBuffer(module.mj_stateSize(model, signature));
+  try {
+    module.mj_getState(model, data, buffer, signature);
+    return {
+      time: data.time,
+      qpos: new Float64Array(data.qpos),
+      qvel: new Float64Array(data.qvel),
+      ctrl: new Float64Array(data.ctrl),
+      act: new Float64Array(data.act),
+      qfrc_applied: new Float64Array(data.qfrc_applied),
+      integration: { signature, values: new Float64Array(buffer.GetView()), model }
+    };
+  } finally {
+    buffer.delete();
+  }
+}
+function restoreSimulationState(module, model, data, snapshot) {
+  const integration = snapshot.integration;
+  if (integration && (integration.model !== model || integration.values.length !== module.mj_stateSize(model, integration.signature))) {
+    throw new Error("Snapshot belongs to a different model; capture a new snapshot after loading a scene");
+  }
+  for (const key of ["qpos", "qvel", "ctrl", "act", "qfrc_applied"]) {
+    if (snapshot[key].length !== data[key].length)
+      throw new Error(`Snapshot ${key} size does not match model`);
+  }
+  if (integration) module.mj_setState(model, data, Array.from(integration.values), integration.signature);
+  data.time = snapshot.time;
+  for (const key of ["qpos", "qvel", "ctrl", "act", "qfrc_applied"]) data[key].set(snapshot[key]);
+  module.mj_forward(model, data);
+}
 var MujocoContext = createContext({
   mujoco: null,
   status: "loading",
@@ -36,6 +77,7 @@ function MujocoProvider({
   mtWasmUrl,
   threadedLoader,
   wasmVariant = "single",
+  threadCount = 0,
   timeout = 3e4,
   children,
   onError
@@ -43,12 +85,21 @@ function MujocoProvider({
   const [status, setStatus] = useState("loading");
   const [error, setError] = useState(null);
   const moduleRef = useRef(null);
-  const isMounted = useRef(true);
   const onErrorRef = useRef(onError);
   onErrorRef.current = onError;
   useEffect(() => {
-    isMounted.current = true;
+    let disposed = false;
+    moduleRef.current = null;
+    setStatus("loading");
+    setError(null);
     const variant = resolveWasmVariant(wasmVariant, threadedLoader, mtWasmUrl);
+    if (!Number.isInteger(threadCount) || threadCount < 0 || threadCount > 0 && variant !== "threaded" || variant === "threaded" && !canUseThreadedWasm()) {
+      const err = new Error("threadCount must be a nonnegative integer; threaded physics requires the MT loader and cross-origin isolation");
+      setError(err.message);
+      setStatus("error");
+      onErrorRef.current?.(err);
+      return;
+    }
     if (variant === "threaded" && !threadedLoader) {
       const err = new Error('MujocoProvider wasmVariant="threaded" requires a threadedLoader from @mujoco/mujoco/mt');
       setError(err.message);
@@ -71,35 +122,38 @@ function MujocoProvider({
     const wasmPromise = load({
       locateFile: (path) => path.endsWith(".wasm") ? selectedWasmUrl : path,
       printErr: (text) => {
-        if (text.includes("Aborted") && isMounted.current) {
+        if (text.includes("Aborted") && !disposed) {
           setError("Simulation crashed. Reload page.");
           setStatus("error");
         }
       }
     });
+    let timeoutId;
     const timeoutPromise = new Promise(
-      (_, reject) => setTimeout(() => reject(new Error(`WASM module load timed out after ${timeout}ms`)), timeout)
+      (_, reject) => timeoutId = setTimeout(() => reject(new Error(`WASM module load timed out after ${timeout}ms`)), timeout)
     );
     Promise.race([wasmPromise, timeoutPromise]).then((inst) => {
-      if (isMounted.current) {
+      if (!disposed) {
         if (!isMujocoModule(inst)) {
           throw new Error("MuJoCo WASM module initialized with an unexpected shape");
         }
+        configureModuleThreads(inst, threadCount);
         moduleRef.current = inst;
         setStatus("ready");
       }
     }).catch((err) => {
-      if (isMounted.current) {
+      if (!disposed) {
         const msg = err.message || "Failed to init spatial simulation";
         setError(msg);
         setStatus("error");
         onErrorRef.current?.(new Error(msg));
       }
-    });
+    }).finally(() => clearTimeout(timeoutId));
     return () => {
-      isMounted.current = false;
+      disposed = true;
+      clearTimeout(timeoutId);
     };
-  }, [wasmUrl, mtWasmUrl, threadedLoader, wasmVariant, timeout]);
+  }, [wasmUrl, mtWasmUrl, threadedLoader, wasmVariant, threadCount, timeout]);
   return /* @__PURE__ */ jsx(
     MujocoContext.Provider,
     {
@@ -108,23 +162,6 @@ function MujocoProvider({
     }
   );
 }
-var CapsuleGeometry = class extends THREE11.BufferGeometry {
-  parameters;
-  constructor(radius = 1, length = 1, capSegments = 4, radialSegments = 8) {
-    super();
-    this.type = "CapsuleGeometry";
-    this.parameters = { radius, length, capSegments, radialSegments };
-    const path = new THREE11.Path();
-    path.absarc(0, -length / 2, radius, Math.PI * 1.5, 0, false);
-    path.absarc(0, length / 2, radius, 0, Math.PI * 0.5, false);
-    const latheGeometry = new THREE11.LatheGeometry(path.getPoints(capSegments), radialSegments);
-    const self = this;
-    self.setIndex(latheGeometry.getIndex());
-    self.setAttribute("position", latheGeometry.getAttribute("position"));
-    self.setAttribute("normal", latheGeometry.getAttribute("normal"));
-    self.setAttribute("uv", latheGeometry.getAttribute("uv"));
-  }
-};
 
 // src/core/SceneLoader.ts
 var JOINT_TYPE_NAMES = {
@@ -150,7 +187,7 @@ function findSiteByName(mjModel, name) {
   return -1;
 }
 function findActuatorByName(mjModel, name) {
-  for (let i = 0; i < mjModel.nu; i++) {
+  for (let i = 0; i < mjModel.nactuator; i++) {
     if (getName(mjModel, mjModel.name_actuatoradr[i]).includes(name)) return i;
   }
   return -1;
@@ -201,7 +238,7 @@ function findTendonByName(mjModel, name) {
   return -1;
 }
 function getActuatedScalarQposAdr(mjModel, actuatorId) {
-  if (actuatorId < 0 || actuatorId >= mjModel.nu) return -1;
+  if (actuatorId < 0 || actuatorId >= mjModel.nactuator) 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];
@@ -220,7 +257,7 @@ 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;
+  if (actuatorId < 0 || actuatorId >= mjModel.nactuator) 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];
@@ -242,13 +279,38 @@ function getJointInfo(mjModel, jointId) {
   };
 }
 function getActuatorInfo(mjModel, actuatorId) {
-  const hasRange = mjModel.actuator_ctrlrange[2 * actuatorId] < mjModel.actuator_ctrlrange[2 * actuatorId + 1];
+  const ctrlAdr = mjModel.actuator_ctrladr[actuatorId];
+  const ctrlCount = mjModel.actuator_ctrlnum[actuatorId];
+  const ranges = Array.from({ length: ctrlCount }, (_, input) => {
+    const adr = ctrlAdr + input;
+    const lo = mjModel.actuator_ctrlrange[2 * adr], hi = mjModel.actuator_ctrlrange[2 * adr + 1];
+    return lo < hi ? [lo, hi] : [-Infinity, Infinity];
+  });
   return {
     id: actuatorId,
     name: getName(mjModel, mjModel.name_actuatoradr[actuatorId]),
-    range: hasRange ? [mjModel.actuator_ctrlrange[2 * actuatorId], mjModel.actuator_ctrlrange[2 * actuatorId + 1]] : unlimitedRange()
+    ctrlAdr,
+    ctrlCount,
+    ranges,
+    range: ranges[0] ?? [-Infinity, Infinity]
   };
 }
+function getActuatorControlAddress(model, id, input) {
+  if (id < 0) return -1;
+  const count = model.actuator_ctrlnum[id];
+  if (input === void 0 && count !== 1) throw new Error("This actuator requires an explicit input index or a complete control vector");
+  const index = input ?? 0;
+  if (!Number.isInteger(index) || index < 0 || index >= count) throw new Error("Actuator input index out of range");
+  return model.actuator_ctrladr[id] + index;
+}
+function writeActuatorControl(model, data, id, value) {
+  if (id < 0) return;
+  const values = typeof value === "number" ? [value] : value;
+  if (values.length !== model.actuator_ctrlnum[id] || !values.every(Number.isFinite)) {
+    throw new Error("Actuator control must contain one finite value per input");
+  }
+  data.ctrl.set(values, model.actuator_ctrladr[id]);
+}
 function includesResourceName(names, name) {
   return names.includes(name);
 }
@@ -284,7 +346,7 @@ function orderedActuatorIdsFromSelector(mjModel, 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++) {
+  for (let i = 0; i < mjModel.nactuator; i++) {
     if (getActuatorJointId(mjModel, i) < 0) continue;
     const info = getActuatorInfo(mjModel, i);
     if (matchesSelector(info, selector)) ids.push(i);
@@ -323,9 +385,9 @@ function unique(values) {
   return result;
 }
 function findActuatorForJoint(mjModel, jointId, preferredActuatorIds) {
-  const search = preferredActuatorIds ?? Array.from({ length: mjModel.nu }, (_, i) => i);
+  const search = preferredActuatorIds ?? Array.from({ length: mjModel.nactuator }, (_, i) => i);
   for (const actuatorId of search) {
-    if (getActuatorJointId(mjModel, actuatorId) === jointId) return actuatorId;
+    if (mjModel.actuator_ctrlnum[actuatorId] === 1 && getActuatorJointId(mjModel, actuatorId) === jointId) return actuatorId;
   }
   return -1;
 }
@@ -345,12 +407,12 @@ function buildControlGroup(mjModel, jointIds, preferredActuatorIds) {
     if (actuatorId >= 0) {
       const actuator = getActuatorInfo(mjModel, actuatorId);
       actuators.push(actuator);
-      ctrlAdr.push(actuatorId);
+      ctrlAdr.push(getActuatorControlAddress(mjModel, actuatorId));
       joints.push({
         ...joint,
         actuatorId,
         actuatorName: actuator.name,
-        ctrlAdr: actuatorId,
+        ctrlAdr: getActuatorControlAddress(mjModel, actuatorId),
         ctrlRange: actuator.range
       });
     } else {
@@ -390,28 +452,29 @@ function buildControlGroup(mjModel, jointIds, preferredActuatorIds) {
 }
 function getActuatedJoints(mjModel) {
   const result = [];
-  for (let actuatorId = 0; actuatorId < mjModel.nu; actuatorId++) {
+  for (let actuatorId = 0; actuatorId < mjModel.nactuator; actuatorId++) {
     const jointId = getActuatorJointId(mjModel, actuatorId);
-    if (jointId < 0) continue;
+    if (jointId < 0 || mjModel.actuator_ctrlnum[actuatorId] !== 1) continue;
     const actuator = getActuatorInfo(mjModel, actuatorId);
     result.push({
       ...getJointInfo(mjModel, jointId),
       actuatorId,
       actuatorName: actuator.name,
-      ctrlAdr: actuatorId,
+      ctrlAdr: getActuatorControlAddress(mjModel, 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 actuatorIds = Array.from({ length: mjModel.nactuator }, (_, i) => i).filter((id) => mjModel.actuator_ctrlnum[id] === 1 && 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);
+    for (const id of actuatorIds) getActuatorControlAddress(mjModel, id);
     const jointIds = actuatorIds.map((id) => getActuatorJointId(mjModel, id));
     return buildControlGroup(mjModel, jointIds, actuatorIds);
   }
@@ -429,6 +492,9 @@ function resolveControlGroup(mjModel, selector) {
   return getControlMap(mjModel);
 }
 function createContiguousControlGroup(mjModel, count) {
+  if (count > 0 && (mjModel.nactuator !== mjModel.nu || Array.from(mjModel.actuator_ctrlnum).some((n2) => n2 !== 1))) {
+    throw new Error("Legacy numJoints control groups require scalar-input actuators; use named controls");
+  }
   const n = Math.max(0, Math.min(count, mjModel.nq, mjModel.nu));
   const joints = [];
   const actuators = [];
@@ -778,12 +844,20 @@ async function loadSceneFromFiles(mujoco, config, onProgress) {
   onProgress?.("Loading model...");
   const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
-  applyInitialPose(mjModel, mjData, config);
-  mujoco.mj_forward(mjModel, mjData);
-  return { mjModel, mjData };
+  try {
+    initializeDataThreads(mujoco, mjData);
+    applyInitialPose(mjModel, mjData, config);
+    mujoco.mj_forward(mjModel, mjData);
+    return { mjModel, mjData };
+  } catch (error) {
+    mjData.delete();
+    mjModel.delete();
+    throw error;
+  }
 }
 function applyInitialPose(mjModel, mjData, config) {
   if (!config.homeJoints) return;
+  if (config.homeJoints.length && (mjModel.nactuator !== mjModel.nu || Array.from(mjModel.actuator_ctrlnum).some((n) => n !== 1))) throw new Error("homeJoints requires scalar-input actuators; use a keyframe for multi-input models");
   const homeCount = Math.min(config.homeJoints.length, Math.max(mjModel.nu, mjModel.nq));
   for (let i = 0; i < homeCount; i++) {
     if (i < mjModel.nu) mjData.ctrl[i] = config.homeJoints[i];
@@ -862,9 +936,16 @@ async function loadScene(mujoco, config, onProgress) {
   onProgress?.("Loading model...");
   const mjModel = loadModelFromPath(mujoco, `/working/${config.sceneFile}`);
   const mjData = new mujoco.MjData(mjModel);
-  applyInitialPose(mjModel, mjData, config);
-  mujoco.mj_forward(mjModel, mjData);
-  return { mjModel, mjData };
+  try {
+    initializeDataThreads(mujoco, mjData);
+    applyInitialPose(mjModel, mjData, config);
+    mujoco.mj_forward(mjModel, mjData);
+    return { mjModel, mjData };
+  } catch (error) {
+    mjData.delete();
+    mjModel.delete();
+    throw error;
+  }
 }
 function scanDependencies(xmlString, currentFile, parser, downloaded, queue) {
   for (const fullPath of collectDependencyPaths(xmlString, currentFile, parser)) {
@@ -894,6 +975,23 @@ function collectDependencyPaths(xmlString, currentFile, parser) {
   });
   return paths;
 }
+var CapsuleGeometry = class extends THREE12.BufferGeometry {
+  parameters;
+  constructor(radius = 1, length = 1, capSegments = 4, radialSegments = 8) {
+    super();
+    this.type = "CapsuleGeometry";
+    this.parameters = { radius, length, capSegments, radialSegments };
+    const path = new THREE12.Path();
+    path.absarc(0, -length / 2, radius, Math.PI * 1.5, 0, false);
+    path.absarc(0, length / 2, radius, 0, Math.PI * 0.5, false);
+    const latheGeometry = new THREE12.LatheGeometry(path.getPoints(capSegments), radialSegments);
+    const self = this;
+    self.setIndex(latheGeometry.getIndex());
+    self.setAttribute("position", latheGeometry.getAttribute("position"));
+    self.setAttribute("normal", latheGeometry.getAttribute("normal"));
+    self.setAttribute("uv", latheGeometry.getAttribute("uv"));
+  }
+};
 
 // src/rendering/GeomBuilder.ts
 var DEFAULT_MESH_NORMAL_SMOOTHING_TOLERANCE = 1e-4;
@@ -944,10 +1042,10 @@ var GeomBuilder = class {
       rgba[out + 2] = b;
       rgba[out + 3] = a;
     }
-    const texture = new THREE11.DataTexture(rgba, width, height, THREE11.RGBAFormat);
-    texture.colorSpace = THREE11.LinearSRGBColorSpace;
-    texture.wrapS = THREE11.RepeatWrapping;
-    texture.wrapT = THREE11.RepeatWrapping;
+    const texture = new THREE12.DataTexture(rgba, width, height, THREE12.RGBAFormat);
+    texture.colorSpace = THREE12.LinearSRGBColorSpace;
+    texture.wrapS = THREE12.RepeatWrapping;
+    texture.wrapT = THREE12.RepeatWrapping;
     texture.flipY = true;
     const repeatOffset = matId * 2;
     const repeatS = mjModel.mat_texrepeat?.[repeatOffset] ?? 1;
@@ -968,7 +1066,7 @@ var GeomBuilder = class {
     const pos = mjModel.geom_pos.subarray(g * 3, g * 3 + 3);
     const quat = mjModel.geom_quat.subarray(g * 4, g * 4 + 4);
     const matId = mjModel.geom_matid[g];
-    const color = new THREE11.Color(16777215);
+    const color = new THREE12.Color(16777215);
     const map = this.getMaterialTexture(mjModel, matId);
     let opacity = 1;
     if (matId >= 0) {
@@ -984,16 +1082,16 @@ var GeomBuilder = class {
     let geo = null;
     const getVal = (v) => v?.value ?? v;
     if (type === getVal(MG.mjGEOM_PLANE)) {
-      geo = new THREE11.PlaneGeometry(size[0] * 2 || 5, size[1] * 2 || 5);
+      geo = new THREE12.PlaneGeometry(size[0] * 2 || 5, size[1] * 2 || 5);
     } else if (type === getVal(MG.mjGEOM_SPHERE)) {
-      geo = new THREE11.SphereGeometry(size[0], 24, 24);
+      geo = new THREE12.SphereGeometry(size[0], 24, 24);
     } else if (type === getVal(MG.mjGEOM_CAPSULE)) {
       geo = new CapsuleGeometry(size[0], size[1] * 2, 24, 12);
       geo.rotateX(Math.PI / 2);
     } else if (type === getVal(MG.mjGEOM_BOX)) {
-      geo = new THREE11.BoxGeometry(size[0] * 2, size[1] * 2, size[2] * 2);
+      geo = new THREE12.BoxGeometry(size[0] * 2, size[1] * 2, size[2] * 2);
     } else if (type === getVal(MG.mjGEOM_CYLINDER)) {
-      geo = new THREE11.CylinderGeometry(size[0], size[0], size[1] * 2, 24);
+      geo = new THREE12.CylinderGeometry(size[0], size[0], size[1] * 2, 24);
       geo.rotateX(Math.PI / 2);
     } else if (type === getVal(MG.mjGEOM_MESH)) {
       const mId = mjModel.geom_dataid[g];
@@ -1015,13 +1113,13 @@ var GeomBuilder = class {
           uvs[c * 2] = mjModel.mesh_texcoord[t * 2];
           uvs[c * 2 + 1] = 1 - mjModel.mesh_texcoord[t * 2 + 1];
         }
-        geo = new THREE11.BufferGeometry();
-        geo.setAttribute("position", new THREE11.Float32BufferAttribute(positions, 3));
-        geo.setAttribute("uv", new THREE11.Float32BufferAttribute(uvs, 2));
+        geo = new THREE12.BufferGeometry();
+        geo.setAttribute("position", new THREE12.Float32BufferAttribute(positions, 3));
+        geo.setAttribute("uv", new THREE12.Float32BufferAttribute(uvs, 2));
         geo.computeVertexNormals();
       } else {
-        geo = new THREE11.BufferGeometry();
-        geo.setAttribute("position", new THREE11.Float32BufferAttribute(mjModel.mesh_vert.subarray(vAdr * 3, (vAdr + vNum) * 3), 3));
+        geo = new THREE12.BufferGeometry();
+        geo.setAttribute("position", new THREE12.Float32BufferAttribute(mjModel.mesh_vert.subarray(vAdr * 3, (vAdr + vNum) * 3), 3));
         geo.setIndex(Array.from(mjModel.mesh_face.subarray(fAdr * 3, (fAdr + fNum) * 3)));
         const smoothingTolerance = this.getMeshNormalSmoothingTolerance();
         if (smoothingTolerance !== null) {
@@ -1037,7 +1135,7 @@ var GeomBuilder = class {
         materialMap.repeat.multiplyScalar(2.5);
         materialMap.needsUpdate = true;
       }
-      const mesh = new THREE11.Mesh(geo, new THREE11.MeshStandardMaterial({
+      const mesh = new THREE12.Mesh(geo, new THREE12.MeshStandardMaterial({
         color,
         map: materialMap,
         transparent: opacity < 1,
@@ -1102,7 +1200,7 @@ function SceneRenderer({ renderOptions, ...props }) {
     }
     const refs = [];
     for (let i = 0; i < model.nbody; i++) {
-      const bodyGroup = new THREE11.Group();
+      const bodyGroup = new THREE12.Group();
       bodyGroup.userData.bodyID = i;
       const bodyName = getName(model, model.name_bodyadr[i]);
       if (!hiddenBodiesRef.current.has(bodyName)) {
@@ -1131,9 +1229,9 @@ function SceneRenderer({ renderOptions, ...props }) {
         const alpha = interpolation.alpha;
         const i3 = i * 3;
         ref.position.set(
-          THREE11.MathUtils.lerp(interpolation.previousXpos[i3], interpolation.currentXpos[i3], alpha),
-          THREE11.MathUtils.lerp(interpolation.previousXpos[i3 + 1], interpolation.currentXpos[i3 + 1], alpha),
-          THREE11.MathUtils.lerp(interpolation.previousXpos[i3 + 2], interpolation.currentXpos[i3 + 2], alpha)
+          THREE12.MathUtils.lerp(interpolation.previousXpos[i3], interpolation.currentXpos[i3], alpha),
+          THREE12.MathUtils.lerp(interpolation.previousXpos[i3 + 1], interpolation.currentXpos[i3 + 1], alpha),
+          THREE12.MathUtils.lerp(interpolation.previousXpos[i3 + 2], interpolation.currentXpos[i3 + 2], alpha)
         );
         const i4 = i * 4;
         _previousQuat.set(
@@ -1193,8 +1291,8 @@ function SceneRenderer({ renderOptions, ...props }) {
     }
   );
 }
-var _previousQuat = new THREE11.Quaternion();
-var _currentQuat = new THREE11.Quaternion();
+var _previousQuat = new THREE12.Quaternion();
+var _currentQuat = new THREE12.Quaternion();
 var CameraViewportRegistryContext = createContext(null);
 var nextViewportId = 0;
 var VIEWPORT_RENDER_PRIORITY = 1;
@@ -1812,17 +1910,17 @@ async function recordMountedCameraFrameSequence(api, options) {
     readiness
   };
 }
-var _raycaster = new THREE11.Raycaster();
-var _ndc = new THREE11.Vector2();
+var _raycaster = new THREE12.Raycaster();
+var _ndc = new THREE12.Vector2();
 function toVector3(value, fallback) {
   if (!value) return fallback.clone();
-  return value instanceof THREE11.Vector3 ? value.clone() : new THREE11.Vector3(value[0], value[1], value[2]);
+  return value instanceof THREE12.Vector3 ? value.clone() : new THREE12.Vector3(value[0], value[1], value[2]);
 }
 function applyCameraPose(camera, options, fallbackCamera) {
   camera.position.copy(toVector3(options.position, fallbackCamera.position));
   camera.up.copy(toVector3(options.up, fallbackCamera.up));
   if (options.quaternion) {
-    if (options.quaternion instanceof THREE11.Quaternion) {
+    if (options.quaternion instanceof THREE12.Quaternion) {
       camera.quaternion.copy(options.quaternion);
     } else {
       camera.quaternion.set(
@@ -1833,15 +1931,15 @@ function applyCameraPose(camera, options, fallbackCamera) {
       );
     }
   } else if (options.lookAt) {
-    camera.lookAt(toVector3(options.lookAt, new THREE11.Vector3()));
+    camera.lookAt(toVector3(options.lookAt, new THREE12.Vector3()));
   } else {
     camera.quaternion.copy(fallbackCamera.quaternion);
   }
   camera.updateMatrixWorld();
 }
 function createProjectionCamera(fallbackCamera, options, width, height) {
-  const camera = options.camera ? options.camera.clone() : fallbackCamera instanceof THREE11.PerspectiveCamera ? fallbackCamera.clone() : new THREE11.PerspectiveCamera(45, width / height, 0.01, 100);
-  if (camera instanceof THREE11.PerspectiveCamera) {
+  const camera = options.camera ? options.camera.clone() : fallbackCamera instanceof THREE12.PerspectiveCamera ? fallbackCamera.clone() : new THREE12.PerspectiveCamera(45, width / height, 0.01, 100);
+  if (camera instanceof THREE12.PerspectiveCamera) {
     camera.aspect = width / height;
     camera.fov = options.fov ?? camera.fov;
     camera.near = options.near ?? camera.near;
@@ -2006,8 +2104,8 @@ var _applyPoint = new Float64Array(3);
 var _rayPnt = new Float64Array(3);
 var _rayVec = new Float64Array(3);
 var _rayGeomId = new Int32Array(1);
-var _projRaycaster = new THREE11.Raycaster();
-var _projNdc = new THREE11.Vector2();
+var _projRaycaster = new THREE12.Raycaster();
+var _projNdc = new THREE12.Vector2();
 function waitForNextAnimationFrame2() {
   return new Promise((resolve) => {
     requestAnimationFrame(() => resolve());
@@ -2032,7 +2130,7 @@ function quaternionFromMujocoQuat(values, offset) {
   ];
 }
 function quaternionFromXmat(values, offset) {
-  const matrix = new THREE11.Matrix4();
+  const matrix = new THREE12.Matrix4();
   matrix.set(
     values[offset],
     values[offset + 1],
@@ -2051,7 +2149,7 @@ function quaternionFromXmat(values, offset) {
     0,
     1
   );
-  const quaternion = new THREE11.Quaternion().setFromRotationMatrix(matrix);
+  const quaternion = new THREE12.Quaternion().setFromRotationMatrix(matrix);
   return [quaternion.x, quaternion.y, quaternion.z, quaternion.w];
 }
 function omitResolvedCameraSelectors(options) {
@@ -2059,14 +2157,14 @@ function omitResolvedCameraSelectors(options) {
   return rest;
 }
 function vector3FromCaptureValue(value) {
-  return value instanceof THREE11.Vector3 ? value.clone() : new THREE11.Vector3(value[0], value[1], value[2]);
+  return value instanceof THREE12.Vector3 ? value.clone() : new THREE12.Vector3(value[0], value[1], value[2]);
 }
 function quaternionFromCaptureValue(value) {
-  return value instanceof THREE11.Quaternion ? value.clone() : new THREE11.Quaternion(value[0], value[1], value[2], value[3]);
+  return value instanceof THREE12.Quaternion ? value.clone() : new THREE12.Quaternion(value[0], value[1], value[2], value[3]);
 }
 function applyMountedCameraPoseOffsets(options, position, quaternion) {
-  const resolvedPosition = new THREE11.Vector3(position[0], position[1], position[2]);
-  const resolvedQuaternion = new THREE11.Quaternion(
+  const resolvedPosition = new THREE12.Vector3(position[0], position[1], position[2]);
+  const resolvedQuaternion = new THREE12.Quaternion(
     quaternion[0],
     quaternion[1],
     quaternion[2],
@@ -2151,7 +2249,7 @@ function mujocoCameraProjectionMatrix(model, cameraId, width, height, near, far)
   const cy = height * (0.5 + principalY / sensorHeight);
   const znear = near ?? 0.01;
   const zfar = far ?? 100;
-  return new THREE11.Matrix4().set(
+  return new THREE12.Matrix4().set(
     2 * fx / width,
     0,
     1 - 2 * cx / width,
@@ -2293,6 +2391,7 @@ function MujocoSimProvider({
   onSelection,
   gravity,
   timestep,
+  integrator,
   substeps,
   paused,
   speed,
@@ -2349,6 +2448,15 @@ function MujocoSimProvider({
     model.opt.gravity[1] = gravity[1];
     model.opt.gravity[2] = gravity[2];
   }, [gravity]);
+  const integratorRef = useRef(integrator);
+  integratorRef.current = integrator;
+  const applyIntegrator = (model) => {
+    const value = integratorRef.current;
+    if (value !== void 0) model.opt.integrator = { Euler: 0, RK4: 1, implicit: 2, implicitfast: 3, discrete: 4 }[value];
+  };
+  useEffect(() => {
+    if (mjModelRef.current) applyIntegrator(mjModelRef.current);
+  }, [integrator]);
   useEffect(() => {
     if (timestep === void 0) return;
     const model = mjModelRef.current;
@@ -2394,11 +2502,12 @@ function MujocoSimProvider({
       try {
         const result = await loadScene(mujoco, buildMergedConfig(config));
         if (disposed) {
-          result.mjModel.delete();
           result.mjData.delete();
+          result.mjModel.delete();
           return;
         }
         mujocoRef.current = mujoco;
+        applyIntegrator(result.mjModel);
         mjModelRef.current = result.mjModel;
         mjDataRef.current = result.mjData;
         physicsAccumulatorRef.current = 0;
@@ -2423,8 +2532,8 @@ function MujocoSimProvider({
     })();
     return () => {
       disposed = true;
-      mjModelRef.current?.delete();
       mjDataRef.current?.delete();
+      mjModelRef.current?.delete();
       mjModelRef.current = null;
       mjDataRef.current = null;
       physicsAccumulatorRef.current = 0;
@@ -2596,26 +2705,15 @@ function MujocoSimProvider({
   const saveState = useCallback(() => {
     const data = mjDataRef.current;
     if (!data) return { time: 0, qpos: new Float64Array(0), qvel: new Float64Array(0), ctrl: new Float64Array(0), act: new Float64Array(0), qfrc_applied: new Float64Array(0) };
-    return {
-      time: data.time,
-      qpos: new Float64Array(data.qpos),
-      qvel: new Float64Array(data.qvel),
-      ctrl: new Float64Array(data.ctrl),
-      act: new Float64Array(data.act),
-      qfrc_applied: new Float64Array(data.qfrc_applied)
-    };
+    return captureSimulationState(mujocoRef.current, mjModelRef.current, data);
   }, []);
   const restoreState = useCallback((snapshot) => {
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return;
-    data.time = snapshot.time;
-    data.qpos.set(snapshot.qpos);
-    data.qvel.set(snapshot.qvel);
-    data.ctrl.set(snapshot.ctrl);
-    if (snapshot.act.length > 0) data.act.set(snapshot.act);
-    data.qfrc_applied.set(snapshot.qfrc_applied);
-    mujocoRef.current.mj_forward(model, data);
+    restoreSimulationState(mujocoRef.current, model, data, snapshot);
+    physicsAccumulatorRef.current = 0;
+    interpolationStateRef.current.valid = false;
   }, [mujoco]);
   const setQpos = useCallback((values) => {
     const model = mjModelRef.current;
@@ -2643,11 +2741,11 @@ function MujocoSimProvider({
     if (!model || !data) return;
     if (typeof nameOrValues === "string") {
       const id = findActuatorByName(model, nameOrValues);
-      if (id >= 0 && value !== void 0) data.ctrl[id] = value;
+      if (value !== void 0) writeActuatorControl(model, data, id, value);
     } else {
       for (const [name, val] of Object.entries(nameOrValues)) {
         const id = findActuatorByName(model, name);
-        if (id >= 0) data.ctrl[id] = val;
+        writeActuatorControl(model, data, id, val);
       }
     }
   }, []);
@@ -2818,15 +2916,7 @@ function MujocoSimProvider({
   const getActuatorsApi = useCallback(() => {
     const model = mjModelRef.current;
     if (!model) return [];
-    const result = [];
-    for (let i = 0; i < model.nu; i++) {
-      const hasRange = model.actuator_ctrlrange[2 * i] < model.actuator_ctrlrange[2 * i + 1];
-      result.push({
-        id: i,
-        name: getName(model, model.name_actuatoradr[i]),
-        range: hasRange ? [model.actuator_ctrlrange[2 * i], model.actuator_ctrlrange[2 * i + 1]] : [-Infinity, Infinity]
-      });
-    }
+    const result = Array.from({ length: model.nactuator }, (_, id) => getActuatorInfo(model, id));
     return result;
   }, []);
   const getControlMapApi = useCallback(() => {
@@ -3015,7 +3105,7 @@ function MujocoSimProvider({
       const geomId = _rayGeomId[0];
       const bodyId = geomId >= 0 ? model.geom_bodyid[geomId] : -1;
       return {
-        point: new THREE11.Vector3(
+        point: new THREE12.Vector3(
           origin.x + dir.x * dist,
           origin.y + dir.y * dist,
           origin.z + dir.z * dist
@@ -3072,17 +3162,18 @@ function MujocoSimProvider({
   const loadSceneApi = useCallback(async (newConfig) => {
     const gen = ++loadGenRef.current;
     try {
-      mjModelRef.current?.delete();
       mjDataRef.current?.delete();
+      mjModelRef.current?.delete();
       mjModelRef.current = null;
       mjDataRef.current = null;
       setStatus("loading");
       const result = await loadScene(mujoco, buildMergedConfig(newConfig));
       if (gen !== loadGenRef.current) {
-        result.mjModel.delete();
         result.mjData.delete();
+        result.mjModel.delete();
         return;
       }
+      applyIntegrator(result.mjModel);
       mjModelRef.current = result.mjModel;
       mjDataRef.current = result.mjData;
       physicsAccumulatorRef.current = 0;
@@ -3624,6 +3715,7 @@ var MujocoCanvas = forwardRef(
     // Declarative physics config
     gravity,
     timestep,
+    integrator,
     substeps,
     paused,
     speed,
@@ -3660,6 +3752,7 @@ var MujocoCanvas = forwardRef(
         onSelection,
         gravity,
         timestep,
+        integrator,
         substeps,
         paused,
         speed,
@@ -3821,15 +3914,14 @@ function createControllerHook(options, useImpl) {
   };
   return useController;
 }
-
-// src/core/GenericIK.ts
 var DEFAULTS = {
   maxIterations: 50,
   damping: 0.01,
   tolerance: 1e-3,
   epsilon: 1e-6,
   posWeight: 1,
-  rotWeight: 0.3
+  rotWeight: 0.3,
+  maxStepRad: 0.5
 };
 function resolveOptions(opts) {
   return {
@@ -3839,121 +3931,173 @@ function resolveOptions(opts) {
     epsilon: opts?.epsilon ?? DEFAULTS.epsilon,
     posWeight: opts?.posWeight ?? DEFAULTS.posWeight,
     rotWeight: opts?.rotWeight ?? DEFAULTS.rotWeight,
+    maxStepRad: opts?.maxStepRad ?? DEFAULTS.maxStepRad,
     jointLimits: opts?.jointLimits
   };
 }
 var GenericIK = class {
-  mujoco;
   constructor(mujoco) {
     this.mujoco = mujoco;
   }
+  /** Scalar hinge/slide interface. Returns values in qposAdr order. */
+  solve(model, data, siteId, qposAdr, targetPos, targetQuat, currentQ, opts) {
+    if (currentQ.length !== qposAdr.length) throw new Error("IK currentQ must match qposAdr length");
+    const jointIds = Array.from(qposAdr, (adr) => {
+      const id = Array.from({ length: model.njnt }, (_, i) => i).find(
+        (i) => model.jnt_qposadr[i] === adr
+      );
+      if (id === void 0 || model.jnt_type[id] < 2) {
+        throw new Error(
+          "Scalar IK requires hinge/slide qpos addresses; use solveJoints for ball/free joints"
+        );
+      }
+      return id;
+    });
+    const initial = new Float64Array(data.qpos);
+    for (let i = 0; i < qposAdr.length; i++) initial[qposAdr[i]] = currentQ[i];
+    const result = this.solveJoints(model, data, siteId, jointIds, targetPos, targetQuat, initial, opts);
+    return result ? Array.from(qposAdr, (adr) => result[adr]) : null;
+  }
   /**
-   * Solve IK for a target 6-DOF pose.
-   * @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 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 matching qposAdr order
-   * @param opts        Optional solver parameters
-   * @returns Joint angles array, or null if solver diverged
+   * Solve selected joint IDs, including ball/free joints. Initial and returned
+   * configurations have model.nq entries, with MuJoCo wxyz quaternions.
+   * Jacobian columns use nv/dof addresses; mj_integratePos updates quaternions.
+   * The caller's qpos is restored even if the solve throws.
    */
-  solve(model, data, siteId, qposAdr, targetPos, targetQuat, currentQ, opts) {
+  solveJoints(model, data, siteId, jointIds, targetPos, targetQuat, currentQpos = data.qpos, opts) {
     const o = resolveOptions(opts);
-    const n = qposAdr.length;
-    const savedQpos = new Float64Array(data.qpos.length);
-    savedQpos.set(data.qpos);
-    const R_target = quatToMat3(targetQuat);
-    const q = new Float64Array(n);
-    for (let i = 0; i < n; i++) q[i] = currentQ[i];
-    const J = new Float64Array(6 * n);
-    const JJt = new Float64Array(36);
-    const rhs = new Float64Array(6);
-    const x = new Float64Array(6);
-    const dq = new Float64Array(n);
-    const baseSitePos = new Float64Array(3);
-    const baseSiteMat = new Float64Array(9);
-    const pertSitePos = new Float64Array(3);
-    const pertSiteMat = new Float64Array(9);
-    let bestQ = null;
-    let bestErr = Infinity;
-    const patience = 4;
-    let noImprove = 0;
-    if (n === 0) return null;
-    for (let iter = 0; iter < o.maxIterations; iter++) {
-      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;
-      const off3 = siteId * 3;
-      const off9 = siteId * 9;
-      for (let i = 0; i < 3; i++) baseSitePos[i] = sp[off3 + i];
-      for (let i = 0; i < 9; i++) baseSiteMat[i] = sm[off9 + i];
-      const posErr0 = targetPos.x - baseSitePos[0];
-      const posErr1 = targetPos.y - baseSitePos[1];
-      const posErr2 = targetPos.z - baseSitePos[2];
-      const rotErr = orientationError(baseSiteMat, R_target);
-      const error = [
-        posErr0 * o.posWeight,
-        posErr1 * o.posWeight,
-        posErr2 * o.posWeight,
-        rotErr[0] * o.rotWeight,
-        rotErr[1] * o.rotWeight,
-        rotErr[2] * o.rotWeight
-      ];
-      const errNorm = Math.sqrt(
-        error[0] * error[0] + error[1] * error[1] + error[2] * error[2] + error[3] * error[3] + error[4] * error[4] + error[5] * error[5]
-      );
-      if (errNorm < bestErr - 1e-9) {
-        bestErr = errNorm;
-        bestQ = Array.from(q);
-        noImprove = 0;
-      } else {
-        noImprove++;
-      }
-      if (errNorm < o.tolerance) break;
-      if (noImprove >= patience) break;
-      for (let j = 0; j < n; j++) {
-        const adr = qposAdr[j];
-        const saved = data.qpos[adr];
-        data.qpos[adr] = q[j] + o.epsilon;
+    const targetRotation = new THREE12.Quaternion(targetQuat.x, targetQuat.y, targetQuat.z, targetQuat.w);
+    if (!Number.isInteger(siteId) || siteId < 0 || siteId >= model.nsite)
+      throw new Error("Invalid IK site ID");
+    if (currentQpos.length !== model.nq || !Array.from(currentQpos).every(Number.isFinite))
+      throw new Error("IK configuration must contain nq finite values");
+    if (![
+      targetPos.x,
+      targetPos.y,
+      targetPos.z,
+      targetQuat.x,
+      targetQuat.y,
+      targetQuat.z,
+      targetQuat.w
+    ].every(Number.isFinite) || targetRotation.lengthSq() === 0)
+      throw new Error("IK target must be finite with a nonzero quaternion");
+    if (!(o.damping > 0) || !(o.maxStepRad > 0) || !Number.isFinite(o.maxStepRad) || !Number.isInteger(o.maxIterations) || o.maxIterations < 1)
+      throw new Error("Invalid IK solver options");
+    const ids = Array.from(jointIds);
+    if (new Set(ids).size !== ids.length || ids.some((id) => !Number.isInteger(id) || id < 0 || id >= model.njnt))
+      throw new Error("IK joint IDs must be unique and valid");
+    const dofs = ids.flatMap(
+      (id) => Array.from(
+        { length: model.jnt_type[id] === 0 ? 6 : model.jnt_type[id] === 1 ? 3 : 1 },
+        (_, i) => model.jnt_dofadr[id] + i
+      )
+    );
+    const n = dofs.length;
+    if (!n) return null;
+    const savedQpos = new Float64Array(data.qpos);
+    const buffers = [];
+    try {
+      const alloc = (size) => {
+        const b = new this.mujoco.DoubleBuffer(size);
+        buffers.push(b);
+        return b;
+      };
+      const jacp = alloc(3 * model.nv), jacr = alloc(3 * model.nv), qbuffer = alloc(model.nq);
+      qbuffer.GetView().set(currentQpos);
+      const target = quatToMat3(targetRotation.normalize());
+      const J = new Float64Array(6 * n), JJt = new Float64Array(36), rhs = new Float64Array(6), x = new Float64Array(6);
+      const velocity = new Array(model.nv).fill(0);
+      let best = null, bestErr = Infinity, noImprove = 0;
+      const clamp = () => {
+        const q = qbuffer.GetView();
+        ids.forEach((id, i) => {
+          const adr = model.jnt_qposadr[id], type = model.jnt_type[id];
+          if (type >= 2) {
+            const limits = o.jointLimits?.[i] ?? (model.jnt_limited[id] ? [model.jnt_range[2 * id], model.jnt_range[2 * id + 1]] : null);
+            if (limits)
+              q[adr] = Math.max(Math.min(...limits), Math.min(Math.max(...limits), q[adr]));
+          } else {
+            const offset = adr + (type === 0 ? 3 : 0);
+            const quat = new THREE12.Quaternion(
+              q[offset + 1],
+              q[offset + 2],
+              q[offset + 3],
+              q[offset]
+            ).normalize();
+            if (type === 1 && model.jnt_limited[id]) {
+              if (quat.w < 0) {
+                quat.x *= -1;
+                quat.y *= -1;
+                quat.z *= -1;
+                quat.w *= -1;
+              }
+              const angle = 2 * Math.acos(Math.min(1, Math.max(-1, quat.w)));
+              const limit = model.jnt_range[2 * id + 1];
+              if (angle > limit)
+                quat.identity().slerp(
+                  new THREE12.Quaternion(
+                    q[offset + 1],
+                    q[offset + 2],
+                    q[offset + 3],
+                    q[offset]
+                  ).normalize(),
+                  limit / angle
+                );
+            }
+            q.set([quat.w, quat.x, quat.y, quat.z], offset);
+          }
+        });
+      };
+      clamp();
+      for (let iter = 0; iter < o.maxIterations; iter++) {
+        data.qpos.set(qbuffer.GetView());
         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];
-        J[0 * n + j] = (pertSitePos[0] - baseSitePos[0]) / o.epsilon * o.posWeight;
-        J[1 * n + j] = (pertSitePos[1] - baseSitePos[1]) / o.epsilon * o.posWeight;
-        J[2 * n + j] = (pertSitePos[2] - baseSitePos[2]) / o.epsilon * o.posWeight;
-        const dRot = angularDelta(baseSiteMat, pertSiteMat);
-        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[adr] = saved;
-      }
-      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;
-          for (let k = 0; k < n; k++) {
-            sum += J[r * n + k] * J[c * n + k];
+        const pos = data.site_xpos.subarray(3 * siteId, 3 * siteId + 3);
+        const rot = orientationError(data.site_xmat.subarray(9 * siteId, 9 * siteId + 9), target);
+        const error = [
+          (targetPos.x - pos[0]) * o.posWeight,
+          (targetPos.y - pos[1]) * o.posWeight,
+          (targetPos.z - pos[2]) * o.posWeight,
+          ...rot.map((v) => v * o.rotWeight)
+        ];
+        const norm = Math.hypot(...error);
+        if (!Number.isFinite(norm)) break;
+        if (norm < bestErr - 1e-9) {
+          bestErr = norm;
+          best = Array.from(qbuffer.GetView());
+          noImprove = 0;
+        } else noImprove++;
+        if (norm < o.tolerance || noImprove >= 4) break;
+        this.mujoco.mj_jacSite(model, data, jacp, jacr, siteId);
+        const jp = jacp.GetView(), jr = jacr.GetView();
+        for (let r = 0; r < 3; r++)
+          for (let j = 0; j < n; j++) {
+            J[r * n + j] = jp[r * model.nv + dofs[j]] * o.posWeight;
+            J[(r + 3) * n + j] = jr[r * model.nv + dofs[j]] * o.rotWeight;
           }
-          JJt[r * 6 + c] = sum + (r === c ? o.damping : 0);
-        }
-      }
-      for (let i = 0; i < 6; i++) rhs[i] = error[i];
-      solve6x6(JJt, rhs, x);
-      for (let j = 0; j < n; j++) {
-        let sum = 0;
-        for (let r = 0; r < 6; r++) {
-          sum += J[r * n + j] * x[r];
+        for (let r = 0; r < 6; r++)
+          for (let c = 0; c < 6; c++) {
+            let sum = 0;
+            for (let k = 0; k < n; k++) sum += J[r * n + k] * J[c * n + k];
+            JJt[r * 6 + c] = sum + (r === c ? o.damping : 0);
+          }
+        rhs.set(error);
+        solve6x6(JJt, rhs, x);
+        velocity.fill(0);
+        for (let j = 0; j < n; j++) {
+          let step = 0;
+          for (let r = 0; r < 6; r++) step += J[r * n + j] * x[r];
+          velocity[dofs[j]] = Math.max(-o.maxStepRad, Math.min(o.maxStepRad, step));
         }
-        dq[j] = sum;
+        this.mujoco.mj_integratePos(model, qbuffer, velocity, 1);
+        clamp();
       }
-      for (let i = 0; i < n; i++) q[i] += dq[i];
+      return best;
+    } finally {
+      for (const buffer of buffers) buffer.delete();
+      data.qpos.set(savedQpos);
+      this.mujoco.mj_forward(model, data);
     }
-    data.qpos.set(savedQpos);
-    this.mujoco.mj_forward(model, data);
-    return bestQ;
   }
 };
 function quatToMat3(q) {
@@ -3990,36 +4134,31 @@ function orientationError(R_cur, R_tgt) {
   if (angle < 1e-6) {
     return [0, 0, 0];
   }
-  if (angle > Math.PI - 1e-6) {
-    return [
-      0.5 * (Re[7] - Re[5]),
-      0.5 * (Re[2] - Re[6]),
-      0.5 * (Re[3] - Re[1])
-    ];
+  if (angle > Math.PI - 1e-4) {
+    const matrix = new THREE12.Matrix4().set(
+      Re[0],
+      Re[1],
+      Re[2],
+      0,
+      Re[3],
+      Re[4],
+      Re[5],
+      0,
+      Re[6],
+      Re[7],
+      Re[8],
+      0,
+      0,
+      0,
+      0,
+      1
+    );
+    const q = new THREE12.Quaternion().setFromRotationMatrix(matrix).normalize();
+    const scale = angle / Math.hypot(q.x, q.y, q.z) * (q.w < 0 ? -1 : 1);
+    return [q.x * scale, q.y * scale, q.z * scale];
   }
   const s = angle / (2 * Math.sin(angle));
-  return [
-    s * (Re[7] - Re[5]),
-    s * (Re[2] - Re[6]),
-    s * (Re[3] - Re[1])
-  ];
-}
-function angularDelta(R_base, R_pert) {
-  const dR = new Float64Array(9);
-  for (let i = 0; i < 3; i++) {
-    for (let j = 0; j < 3; j++) {
-      let s = 0;
-      for (let k = 0; k < 3; k++) {
-        s += R_pert[i * 3 + k] * R_base[j * 3 + k];
-      }
-      dR[i * 3 + j] = s;
-    }
-  }
-  return [
-    0.5 * (dR[7] - dR[5]),
-    0.5 * (dR[2] - dR[6]),
-    0.5 * (dR[3] - dR[1])
-  ];
+  return [s * (Re[7] - Re[5]), s * (Re[2] - Re[6]), s * (Re[3] - Re[1])];
 }
 function solve6x6(A, b, x) {
   const N = 6;
@@ -4068,12 +4207,12 @@ function solve6x6(A, b, x) {
 }
 
 // src/hooks/useIkController.ts
-var _syncMat4 = new THREE11.Matrix4();
+var _syncMat4 = new THREE12.Matrix4();
 function toIkVector3(value) {
-  return "x" in value ? new THREE11.Vector3(value.x, value.y, value.z) : new THREE11.Vector3(value[0], value[1], value[2]);
+  return "x" in value ? new THREE12.Vector3(value.x, value.y, value.z) : new THREE12.Vector3(value[0], value[1], value[2]);
 }
 function toIkQuaternion(value) {
-  return "x" in value ? new THREE11.Quaternion(value.x, value.y, value.z, value.w) : new THREE11.Quaternion(value[0], value[1], value[2], value[3]);
+  return "x" in value ? new THREE12.Quaternion(value.x, value.y, value.z, value.w) : new THREE12.Quaternion(value[0], value[1], value[2], value[3]);
 }
 function syncGizmoToSite(data, siteId, target) {
   if (siteId === -1) return;
@@ -4106,7 +4245,7 @@ var useIkController = createControllerHook(
     const { mjModelRef, mjDataRef, mujocoRef, resetCallbacks, status } = useMujocoContext();
     const ikEnabledRef = useRef(false);
     const ikCalculatingRef = useRef(false);
-    const ikTargetRef = useRef(new THREE11.Group());
+    const ikTargetRef = useRef(new THREE12.Group());
     const siteIdRef = useRef(-1);
     const controlGroupRef = useRef(null);
     const genericIkRef = useRef(null);
@@ -4123,10 +4262,10 @@ var useIkController = createControllerHook(
     const needsInitialSync = useRef(true);
     const gizmoAnimRef = useRef({
       active: false,
-      startPos: new THREE11.Vector3(),
-      endPos: new THREE11.Vector3(),
-      startRot: new THREE11.Quaternion(),
-      endRot: new THREE11.Quaternion(),
+      startPos: new THREE12.Vector3(),
+      endPos: new THREE12.Vector3(),
+      startRot: new THREE12.Quaternion(),
+      endRot: new THREE12.Quaternion(),
       startTime: 0,
       duration: 1e3
     });
@@ -4287,8 +4426,8 @@ var useIkController = createControllerHook(
         const target = ikTargetRef.current;
         if (!target) return;
         const targetPos = toIkVector3(pos);
-        const targetRot = new THREE11.Quaternion().setFromEuler(
-          new THREE11.Euler(Math.PI, 0, 0)
+        const targetRot = new THREE12.Quaternion().setFromEuler(
+          new THREE12.Euler(Math.PI, 0, 0)
         );
         if (duration > 0) {
           const ga = gizmoAnimRef.current;
@@ -4313,7 +4452,7 @@ var useIkController = createControllerHook(
         if (!ikCalculatingRef.current || !target) return null;
         return {
           pos: target.position.clone(),
-          rot: new THREE11.Euler().setFromQuaternion(target.quaternion)
+          rot: new THREE12.Euler().setFromQuaternion(target.quaternion)
         };
       },
       []
@@ -4409,10 +4548,10 @@ function Body({
   if (!hasChildren) return null;
   return /* @__PURE__ */ jsx("group", { ref: groupRef, children });
 }
-var _mat4 = new THREE11.Matrix4();
-var _pos = new THREE11.Vector3();
-var _quat = new THREE11.Quaternion();
-var _scale = new THREE11.Vector3(1, 1, 1);
+var _mat4 = new THREE12.Matrix4();
+var _pos = new THREE12.Vector3();
+var _quat = new THREE12.Quaternion();
+var _scale = new THREE12.Vector3(1, 1, 1);
 function IkGizmo({ controller, siteName, scale = 0.18, onDrag }) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const { ikTargetRef, siteIdRef, ikEnabledRef, setIkEnabled } = controller;
@@ -4511,7 +4650,7 @@ function IkGizmo({ controller, siteName, scale = 0.18, onDrag }) {
     }
   );
 }
-var _dummy = new THREE11.Object3D();
+var _dummy = new THREE12.Object3D();
 function ContactMarkers({
   maxContacts = 100,
   radius = 8e-3,
@@ -4565,11 +4704,11 @@ function ContactMarkers({
 var _force = new Float64Array(3);
 var _torque = new Float64Array(3);
 var _point = new Float64Array(3);
-var _bodyPos = new THREE11.Vector3();
-var _bodyQuat = new THREE11.Quaternion();
-var _worldHit = new THREE11.Vector3();
-var _raycaster2 = new THREE11.Raycaster();
-var _mouse = new THREE11.Vector2();
+var _bodyPos = new THREE12.Vector3();
+var _bodyQuat = new THREE12.Quaternion();
+var _worldHit = new THREE12.Vector3();
+var _raycaster2 = new THREE12.Raycaster();
+var _mouse = new THREE12.Vector2();
 function DragInteraction({
   stiffness = 250,
   showArrow = true,
@@ -4580,16 +4719,16 @@ function DragInteraction({
   const draggingRef = useRef(false);
   const bodyIdRef = useRef(-1);
   const grabDistanceRef = useRef(0);
-  const localHitRef = useRef(new THREE11.Vector3());
-  const grabWorldRef = useRef(new THREE11.Vector3());
-  const mouseWorldRef = useRef(new THREE11.Vector3());
+  const localHitRef = useRef(new THREE12.Vector3());
+  const grabWorldRef = useRef(new THREE12.Vector3());
+  const mouseWorldRef = useRef(new THREE12.Vector3());
   const arrowRef = useRef(null);
   const groupRef = useRef(null);
   useEffect(() => {
     if (!showArrow || !groupRef.current) return;
-    const arrow = new THREE11.ArrowHelper(
-      new THREE11.Vector3(0, 1, 0),
-      new THREE11.Vector3(),
+    const arrow = new THREE12.ArrowHelper(
+      new THREE12.Vector3(0, 1, 0),
+      new THREE12.Vector3(),
       0.1,
       16729156
     );
@@ -4772,7 +4911,7 @@ function useSceneLights(intensity = 1) {
       const dr = lightDiffuse ? lightDiffuse[3 * i] : 1;
       const dg = lightDiffuse ? lightDiffuse[3 * i + 1] : 1;
       const db = lightDiffuse ? lightDiffuse[3 * i + 2] : 1;
-      const color = new THREE11.Color(dr, dg, db);
+      const color = new THREE12.Color(dr, dg, db);
       const px = lightPos[3 * i];
       const py = lightPos[3 * i + 1];
       const pz = lightPos[3 * i + 2];
@@ -4780,7 +4919,7 @@ function useSceneLights(intensity = 1) {
       const dy = lightDir[3 * i + 1];
       const dz = lightDir[3 * i + 2];
       if (isDirectional) {
-        const light = new THREE11.DirectionalLight(color, finalIntensity);
+        const light = new THREE12.DirectionalLight(color, finalIntensity);
         light.position.set(px, py, pz);
         light.target.position.set(px + dx, py + dy, pz + dz);
         light.castShadow = castShadow;
@@ -4803,7 +4942,7 @@ function useSceneLights(intensity = 1) {
         const cutoff = lightCutoff ? lightCutoff[i] : 45;
         const exponent = lightExponent ? lightExponent[i] : 10;
         const angle = cutoff * Math.PI / 180;
-        const light = new THREE11.SpotLight(color, finalIntensity, 0, angle, exponent / 128);
+        const light = new THREE12.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;
@@ -5149,31 +5288,31 @@ var JOINT_COLORS = {
   3: 16776960
   // hinge - yellow
 };
-var _v3a = new THREE11.Vector3();
-new THREE11.Vector3();
-var _quat2 = new THREE11.Quaternion();
-var _cameraMatrix = new THREE11.Matrix4();
-var _contactPos = new THREE11.Vector3();
-var _contactNormal = new THREE11.Vector3();
+var _v3a = new THREE12.Vector3();
+new THREE12.Vector3();
+var _quat2 = new THREE12.Quaternion();
+var _cameraMatrix = new THREE12.Matrix4();
+var _contactPos = new THREE12.Vector3();
+var _contactNormal = new THREE12.Vector3();
 var MAX_CONTACT_ARROWS = 50;
 var CAMERA_DEBUG_LENGTH = 0.12;
 var CAMERA_DEBUG_FRUSTUM_DEPTH = 0.08;
 function toVector32(value, fallback) {
   if (!value) return fallback.clone();
-  return value instanceof THREE11.Vector3 ? value.clone() : new THREE11.Vector3(value[0], value[1], value[2]);
+  return value instanceof THREE12.Vector3 ? value.clone() : new THREE12.Vector3(value[0], value[1], value[2]);
 }
 function createCameraLabel(text, color) {
   const canvas = document.createElement("canvas");
   canvas.width = 256;
   canvas.height = 64;
   const ctx = canvas.getContext("2d");
-  ctx.fillStyle = new THREE11.Color(color).getStyle();
+  ctx.fillStyle = new THREE12.Color(color).getStyle();
   ctx.font = "bold 32px monospace";
   ctx.textAlign = "center";
   ctx.fillText(text, 128, 42);
-  const texture = new THREE11.CanvasTexture(canvas);
-  const sprite = new THREE11.Sprite(
-    new THREE11.SpriteMaterial({
+  const texture = new THREE12.CanvasTexture(canvas);
+  const sprite = new THREE12.Sprite(
+    new THREE12.SpriteMaterial({
       map: texture,
       depthTest: false,
       transparent: true
@@ -5188,12 +5327,12 @@ function createVirtualCameraDebugObject(camera, index) {
   const color = camera.color ?? "#ff3d71";
   const aimColor = camera.aimColor ?? "#38bdf8";
   const markerScale = camera.markerScale ?? 1;
-  const cameraPosition = toVector32(camera.position, new THREE11.Vector3());
-  const configuredUp = toVector32(camera.up, new THREE11.Vector3(0, 0, 1)).normalize();
-  const cameraQuaternion = new THREE11.Quaternion();
-  const forward = new THREE11.Vector3();
+  const cameraPosition = toVector32(camera.position, new THREE12.Vector3());
+  const configuredUp = toVector32(camera.up, new THREE12.Vector3(0, 0, 1)).normalize();
+  const cameraQuaternion = new THREE12.Quaternion();
+  const forward = new THREE12.Vector3();
   if (camera.quaternion) {
-    if (camera.quaternion instanceof THREE11.Quaternion) {
+    if (camera.quaternion instanceof THREE12.Quaternion) {
       cameraQuaternion.copy(camera.quaternion);
     } else {
       cameraQuaternion.set(
@@ -5207,13 +5346,13 @@ function createVirtualCameraDebugObject(camera, index) {
   } else {
     const target2 = toVector32(
       camera.lookAt,
-      cameraPosition.clone().add(new THREE11.Vector3(0, 0, -1))
+      cameraPosition.clone().add(new THREE12.Vector3(0, 0, -1))
     );
     forward.copy(target2).sub(cameraPosition);
     if (forward.lengthSq() < 1e-8) forward.set(0, 0, -1);
     forward.normalize();
     cameraQuaternion.setFromRotationMatrix(
-      new THREE11.Matrix4().lookAt(cameraPosition, target2, configuredUp)
+      new THREE12.Matrix4().lookAt(cameraPosition, target2, configuredUp)
     );
   }
   const target = camera.lookAt ? toVector32(camera.lookAt, cameraPosition.clone().add(forward)) : cameraPosition.clone().addScaledVector(forward, 0.4);
@@ -5225,7 +5364,7 @@ function createVirtualCameraDebugObject(camera, index) {
   if (right.lengthSq() < 1e-8) right.set(1, 0, 0);
   right.normalize();
   const orthogonalUp = right.clone().cross(forward).normalize();
-  const frustumHeight = 2 * Math.tan(THREE11.MathUtils.degToRad(fov) / 2) * depth;
+  const frustumHeight = 2 * Math.tan(THREE12.MathUtils.degToRad(fov) / 2) * depth;
   const frustumWidth = frustumHeight * aspect;
   const center = cameraPosition.clone().addScaledVector(forward, depth);
   const halfRight = right.clone().multiplyScalar(frustumWidth / 2);
@@ -5252,13 +5391,13 @@ function createVirtualCameraDebugObject(camera, index) {
     bottomLeft,
     topLeft
   ];
-  const group = new THREE11.Group();
+  const group = new THREE12.Group();
   group.name = camera.name ?? `virtual-camera-${index}`;
   group.renderOrder = 999;
   group.frustumCulled = false;
-  const frustum = new THREE11.LineSegments(
-    new THREE11.BufferGeometry().setFromPoints(frustumPoints),
-    new THREE11.LineBasicMaterial({
+  const frustum = new THREE12.LineSegments(
+    new THREE12.BufferGeometry().setFromPoints(frustumPoints),
+    new THREE12.LineBasicMaterial({
       color,
       transparent: true,
       opacity: 0.9,
@@ -5268,9 +5407,9 @@ function createVirtualCameraDebugObject(camera, index) {
   frustum.renderOrder = 999;
   frustum.frustumCulled = false;
   group.add(frustum);
-  const aim = new THREE11.LineSegments(
-    new THREE11.BufferGeometry().setFromPoints([cameraPosition, target]),
-    new THREE11.LineBasicMaterial({
+  const aim = new THREE12.LineSegments(
+    new THREE12.BufferGeometry().setFromPoints([cameraPosition, target]),
+    new THREE12.LineBasicMaterial({
       color: aimColor,
       transparent: true,
       opacity: 0.95,
@@ -5280,26 +5419,26 @@ function createVirtualCameraDebugObject(camera, index) {
   aim.renderOrder = 999;
   aim.frustumCulled = false;
   group.add(aim);
-  const markerGroup = new THREE11.Group();
+  const markerGroup = new THREE12.Group();
   markerGroup.position.copy(cameraPosition);
   markerGroup.quaternion.copy(cameraQuaternion);
   markerGroup.renderOrder = 999;
   markerGroup.frustumCulled = false;
-  markerGroup.add(new THREE11.Mesh(
-    new THREE11.BoxGeometry(0.045 * markerScale, 0.028 * markerScale, 0.022 * markerScale),
-    new THREE11.MeshBasicMaterial({ color, depthTest: false })
+  markerGroup.add(new THREE12.Mesh(
+    new THREE12.BoxGeometry(0.045 * markerScale, 0.028 * markerScale, 0.022 * markerScale),
+    new THREE12.MeshBasicMaterial({ color, depthTest: false })
   ));
-  const lens = new THREE11.Mesh(
-    new THREE11.BoxGeometry(0.025 * markerScale, 0.018 * markerScale, 0.014 * markerScale),
-    new THREE11.MeshBasicMaterial({ color: aimColor, depthTest: false })
+  const lens = new THREE12.Mesh(
+    new THREE12.BoxGeometry(0.025 * markerScale, 0.018 * markerScale, 0.014 * markerScale),
+    new THREE12.MeshBasicMaterial({ color: aimColor, depthTest: false })
   );
   lens.position.set(0, 0, -0.021 * markerScale);
   markerGroup.add(lens);
   if (camera.name) markerGroup.add(createCameraLabel(camera.name, color));
   group.add(markerGroup);
-  const targetMarker = new THREE11.Mesh(
-    new THREE11.SphereGeometry(0.018 * markerScale, 16, 10),
-    new THREE11.MeshBasicMaterial({ color: aimColor, depthTest: false })
+  const targetMarker = new THREE12.Mesh(
+    new THREE12.SphereGeometry(0.018 * markerScale, 16, 10),
+    new THREE12.MeshBasicMaterial({ color: aimColor, depthTest: false })
   );
   targetMarker.position.copy(target);
   targetMarker.renderOrder = 999;
@@ -5338,21 +5477,21 @@ function Debug({
         let geometry = null;
         switch (type) {
           case 2:
-            geometry = new THREE11.SphereGeometry(s[3 * i], 12, 8);
+            geometry = new THREE12.SphereGeometry(s[3 * i], 12, 8);
             break;
           case 3:
-            geometry = new THREE11.CapsuleGeometry(s[3 * i], s[3 * i + 1] * 2, 6, 8);
+            geometry = new THREE12.CapsuleGeometry(s[3 * i], s[3 * i + 1] * 2, 6, 8);
             break;
           case 5:
-            geometry = new THREE11.CylinderGeometry(s[3 * i], s[3 * i], s[3 * i + 1] * 2, 12);
+            geometry = new THREE12.CylinderGeometry(s[3 * i], s[3 * i], s[3 * i + 1] * 2, 12);
             break;
           case 6:
-            geometry = new THREE11.BoxGeometry(s[3 * i] * 2, s[3 * i + 1] * 2, s[3 * i + 2] * 2);
+            geometry = new THREE12.BoxGeometry(s[3 * i] * 2, s[3 * i + 1] * 2, s[3 * i + 2] * 2);
             break;
         }
         if (geometry) {
-          const mat = new THREE11.MeshBasicMaterial({ color: 65280, wireframe: true, transparent: true, opacity: 0.3 });
-          const mesh = new THREE11.Mesh(geometry, mat);
+          const mat = new THREE12.MeshBasicMaterial({ color: 65280, wireframe: true, transparent: true, opacity: 0.3 });
+          const mesh = new THREE12.Mesh(geometry, mat);
           mesh.userData.geomId = i;
           mesh.userData.bodyId = model.geom_bodyid[i];
           geoms.push(mesh);
@@ -5375,9 +5514,9 @@ function Debug({
           }
           if (maxGeomSize > 0) radius = maxGeomSize * 0.15;
         }
-        const geometry = new THREE11.OctahedronGeometry(radius);
-        const mat = new THREE11.MeshBasicMaterial({ color: 16711935, depthTest: false });
-        const mesh = new THREE11.Mesh(geometry, mat);
+        const geometry = new THREE12.OctahedronGeometry(radius);
+        const mat = new THREE12.MeshBasicMaterial({ color: 16711935, depthTest: false });
+        const mesh = new THREE12.Mesh(geometry, mat);
         mesh.renderOrder = 999;
         mesh.frustumCulled = false;
         mesh.userData.siteId = i;
@@ -5389,9 +5528,9 @@ function Debug({
         ctx.font = "bold 36px monospace";
         ctx.textAlign = "center";
         ctx.fillText(getName(model, model.name_siteadr[i]), 128, 42);
-        const tex = new THREE11.CanvasTexture(canvas);
-        const spriteMat = new THREE11.SpriteMaterial({ map: tex, depthTest: false, transparent: true });
-        const sprite = new THREE11.Sprite(spriteMat);
+        const tex = new THREE12.CanvasTexture(canvas);
+        const spriteMat = new THREE12.SpriteMaterial({ map: tex, depthTest: false, transparent: true });
+        const sprite = new THREE12.Sprite(spriteMat);
         const labelScale = radius * 15;
         sprite.scale.set(labelScale, labelScale * 0.25, 1);
         sprite.position.y = radius * 2;
@@ -5414,9 +5553,9 @@ function Debug({
           }
         }
         const arrowLen = Math.max(maxGeomSize * 0.8, 0.05);
-        const arrow = new THREE11.ArrowHelper(
-          new THREE11.Vector3(0, 0, 1),
-          new THREE11.Vector3(),
+        const arrow = new THREE12.ArrowHelper(
+          new THREE12.Vector3(0, 0, 1),
+          new THREE12.Vector3(),
           arrowLen,
           color,
           arrowLen * 0.25,
@@ -5424,7 +5563,7 @@ function Debug({
         );
         arrow.renderOrder = 999;
         arrow.frustumCulled = false;
-        arrow.line.material = new THREE11.LineBasicMaterial({ color, depthTest: false });
+        arrow.line.material = new THREE12.LineBasicMaterial({ color, depthTest: false });
         arrow.cone.material.depthTest = false;
         arrow.line.renderOrder = 999;
         arrow.line.frustumCulled = false;
@@ -5439,20 +5578,20 @@ function Debug({
     }
     if (showCameras && model.ncam && model.name_camadr) {
       for (let i = 0; i < model.ncam; i++) {
-        const group = new THREE11.Group();
+        const group = new THREE12.Group();
         group.userData.cameraId = i;
         group.renderOrder = 999;
         group.frustumCulled = false;
-        const marker = new THREE11.Mesh(
-          new THREE11.BoxGeometry(0.014, 9e-3, 6e-3),
-          new THREE11.MeshBasicMaterial({ color: 3718648, depthTest: false })
+        const marker = new THREE12.Mesh(
+          new THREE12.BoxGeometry(0.014, 9e-3, 6e-3),
+          new THREE12.MeshBasicMaterial({ color: 3718648, depthTest: false })
         );
         marker.renderOrder = 999;
         marker.frustumCulled = false;
         group.add(marker);
-        const forward = new THREE11.ArrowHelper(
-          new THREE11.Vector3(0, 0, -1),
-          new THREE11.Vector3(),
+        const forward = new THREE12.ArrowHelper(
+          new THREE12.Vector3(0, 0, -1),
+          new THREE12.Vector3(),
           CAMERA_DEBUG_LENGTH,
           3718648,
           CAMERA_DEBUG_LENGTH * 0.24,
@@ -5460,20 +5599,20 @@ function Debug({
         );
         forward.renderOrder = 999;
         forward.frustumCulled = false;
-        forward.line.material = new THREE11.LineBasicMaterial({
+        forward.line.material = new THREE12.LineBasicMaterial({
           color: 3718648,
           depthTest: false
         });
         forward.cone.material.depthTest = false;
         group.add(forward);
-        const frustumGeometry = new THREE11.BufferGeometry();
+        const frustumGeometry = new THREE12.BufferGeometry();
         frustumGeometry.setAttribute(
           "position",
-          new THREE11.Float32BufferAttribute(new Float32Array(8 * 2 * 3), 3)
+          new THREE12.Float32BufferAttribute(new Float32Array(8 * 2 * 3), 3)
         );
-        const frustum = new THREE11.LineSegments(
+        const frustum = new THREE12.LineSegments(
           frustumGeometry,
-          new THREE11.LineBasicMaterial({
+          new THREE12.LineBasicMaterial({
             color: 3718648,
             transparent: true,
             opacity: 0.8,
@@ -5492,9 +5631,9 @@ function Debug({
         ctx.font = "bold 32px monospace";
         ctx.textAlign = "center";
         ctx.fillText(getName(model, model.name_camadr[i]), 128, 42);
-        const texture = new THREE11.CanvasTexture(canvas);
-        const sprite = new THREE11.Sprite(
-          new THREE11.SpriteMaterial({
+        const texture = new THREE12.CanvasTexture(canvas);
+        const sprite = new THREE12.Sprite(
+          new THREE12.SpriteMaterial({
             map: texture,
             depthTest: false,
             transparent: true
@@ -5513,9 +5652,9 @@ function Debug({
     }
     if (showCOM) {
       for (let i = 1; i < model.nbody; i++) {
-        const geometry = new THREE11.SphereGeometry(5e-3, 6, 6);
-        const mat = new THREE11.MeshBasicMaterial({ color: 16711680 });
-        const mesh = new THREE11.Mesh(geometry, mat);
+        const geometry = new THREE12.SphereGeometry(5e-3, 6, 6);
+        const mat = new THREE12.MeshBasicMaterial({ color: 16711680 });
+        const mesh = new THREE12.Mesh(geometry, mat);
         mesh.userData.bodyId = i;
         comMarkers.push(mesh);
       }
@@ -5625,7 +5764,7 @@ function Debug({
         );
         group.quaternion.setFromRotationMatrix(_cameraMatrix);
         const fovy = model.cam_fovy?.[cameraId] ?? 45;
-        const halfHeight = Math.tan(THREE11.MathUtils.degToRad(fovy) / 2) * CAMERA_DEBUG_FRUSTUM_DEPTH;
+        const halfHeight = Math.tan(THREE12.MathUtils.degToRad(fovy) / 2) * CAMERA_DEBUG_FRUSTUM_DEPTH;
         const halfWidth = halfHeight * 4 / 3;
         const positions = group.userData.frustum.geometry.attributes.position;
         const array = positions.array;
@@ -5670,9 +5809,9 @@ function Debug({
     contactPoolInitRef.current = true;
     const pool = [];
     for (let i = 0; i < MAX_CONTACT_ARROWS; i++) {
-      const arrow = new THREE11.ArrowHelper(
-        new THREE11.Vector3(0, 1, 0),
-        new THREE11.Vector3(),
+      const arrow = new THREE12.ArrowHelper(
+        new THREE12.Vector3(0, 1, 0),
+        new THREE12.Vector3(),
         0.1,
         16729156,
         0.03,
@@ -5737,9 +5876,9 @@ function Debug({
     }
   );
 }
-var DEFAULT_TENDON_COLOR = new THREE11.Color(0.3, 0.3, 0.8);
+var DEFAULT_TENDON_COLOR = new THREE12.Color(0.3, 0.3, 0.8);
 var DEFAULT_TENDON_WIDTH = 2e-3;
-new THREE11.Vector3();
+new THREE12.Vector3();
 function TendonRenderer(props) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const groupRef = useRef(null);
@@ -5753,7 +5892,7 @@ function TendonRenderer(props) {
     if (!model || !data || !group) return;
     const ntendon = model.ntendon ?? 0;
     if (ntendon === 0) return;
-    const material = new THREE11.MeshStandardMaterial({
+    const material = new THREE12.MeshStandardMaterial({
       color: DEFAULT_TENDON_COLOR,
       roughness: 0.6,
       metalness: 0.1
@@ -5768,11 +5907,11 @@ function TendonRenderer(props) {
         curves.push(null);
         continue;
       }
-      const points = Array.from({ length: wrapNum }, () => new THREE11.Vector3());
-      const curve = new THREE11.CatmullRomCurve3(points, false);
+      const points = Array.from({ length: wrapNum }, () => new THREE12.Vector3());
+      const curve = new THREE12.CatmullRomCurve3(points, false);
       const segments = Math.max(wrapNum * 2, 4);
-      const geometry = new THREE11.TubeGeometry(curve, segments, DEFAULT_TENDON_WIDTH, 6, false);
-      const mesh = new THREE11.Mesh(geometry, material);
+      const geometry = new THREE12.TubeGeometry(curve, segments, DEFAULT_TENDON_WIDTH, 6, false);
+      const mesh = new THREE12.Mesh(geometry, material);
       mesh.frustumCulled = false;
       group.add(mesh);
       meshes.push(mesh);
@@ -5827,11 +5966,11 @@ function TendonRenderer(props) {
       if (curve.points.length !== validCount) {
         curve.points.length = validCount;
         while (curve.points.length < validCount) {
-          curve.points.push(new THREE11.Vector3());
+          curve.points.push(new THREE12.Vector3());
         }
       }
       mesh.geometry.dispose();
-      mesh.geometry = new THREE11.TubeGeometry(
+      mesh.geometry = new THREE12.TubeGeometry(
         curve,
         Math.max(validCount * 2, 4),
         DEFAULT_TENDON_WIDTH,
@@ -5844,6 +5983,26 @@ function TendonRenderer(props) {
   if (status !== "ready") return null;
   return /* @__PURE__ */ jsx("group", { ...props, ref: groupRef });
 }
+
+// src/rendering/flexTopology.ts
+function getFlexTopology(model, id) {
+  const dim = model.flex_dim[id];
+  if (dim === 3) {
+    const start = model.flex_shelldataadr[id];
+    return {
+      kind: "mesh",
+      indices: Array.from(model.flex_shell.subarray(start, start + 3 * model.flex_shellnum[id]))
+    };
+  }
+  if (dim === 1 || dim === 2) {
+    const start = model.flex_elemdataadr[id];
+    return {
+      kind: dim === 2 ? "mesh" : "lines",
+      indices: Array.from(model.flex_elem.subarray(start, start + (dim + 1) * model.flex_elemnum[id]))
+    };
+  }
+  return { kind: "points", indices: [] };
+}
 function FlexRenderer(props) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const groupRef = useRef(null);
@@ -5858,24 +6017,23 @@ function FlexRenderer(props) {
       const vertAdr = model.flex_vertadr[f];
       const vertNum = model.flex_vertnum[f];
       if (vertNum === 0) continue;
-      const geometry = new THREE11.BufferGeometry();
+      const geometry = new THREE12.BufferGeometry();
       const positions = new Float32Array(vertNum * 3);
-      geometry.setAttribute("position", new THREE11.BufferAttribute(positions, 3));
-      geometry.computeVertexNormals();
-      let color = new THREE11.Color(0.5, 0.5, 0.5);
+      geometry.setAttribute("position", new THREE12.BufferAttribute(positions, 3));
+      const topology = getFlexTopology(model, f);
+      if (topology.indices.length) geometry.setIndex(topology.indices);
+      let color = new THREE12.Color(0.5, 0.5, 0.5);
       if (model.flex_rgba) {
-        color = new THREE11.Color(
+        color = new THREE12.Color(
           model.flex_rgba[4 * f],
           model.flex_rgba[4 * f + 1],
           model.flex_rgba[4 * f + 2]
         );
       }
-      const material = new THREE11.MeshStandardMaterial({
-        color,
-        roughness: 0.7,
-        side: THREE11.DoubleSide
-      });
-      const mesh = new THREE11.Mesh(geometry, material);
+      const opacity = model.flex_rgba[4 * f + 3];
+      const materialOptions = { color, opacity, transparent: opacity < 1 };
+      const mesh = topology.kind === "mesh" ? new THREE12.Mesh(geometry, new THREE12.MeshStandardMaterial({ ...materialOptions, roughness: 0.7, side: THREE12.DoubleSide })) : topology.kind === "lines" ? new THREE12.LineSegments(geometry, new THREE12.LineBasicMaterial(materialOptions)) : new THREE12.Points(geometry, new THREE12.PointsMaterial({ ...materialOptions, size: 0.01 }));
+      mesh.frustumCulled = false;
       mesh.userData.flexId = f;
       mesh.userData.vertAdr = vertAdr;
       mesh.userData.vertNum = vertNum;
@@ -5904,14 +6062,14 @@ function FlexRenderer(props) {
         posAttr.setXYZ(v, data.flexvert_xpos[srcIdx], data.flexvert_xpos[srcIdx + 1], data.flexvert_xpos[srcIdx + 2]);
       }
       posAttr.needsUpdate = true;
-      mesh.geometry.computeVertexNormals();
+      if (mesh instanceof THREE12.Mesh) mesh.geometry.computeVertexNormals();
     }
   });
   if (status !== "ready") return null;
   return /* @__PURE__ */ jsx("group", { ...props, ref: groupRef });
 }
 var GEOM_TYPE_NAMES2 = ["plane", "hfield", "sphere", "capsule", "ellipsoid", "cylinder", "box", "mesh"];
-var _matrix = new THREE11.Matrix4();
+var _matrix = new THREE12.Matrix4();
 function getGeomInfo(model, geomId) {
   const size = model.geom_size.subarray(geomId * 3, geomId * 3 + 3);
   const type = model.geom_type[geomId];
@@ -5933,10 +6091,10 @@ function geomSignature(model, geomId) {
   return [type, size, mat, data, rgba].join("|");
 }
 function firstMesh(object) {
-  if (object instanceof THREE11.Mesh) return object;
+  if (object instanceof THREE12.Mesh) return object;
   let mesh = null;
   object.traverse((child) => {
-    if (!mesh && child instanceof THREE11.Mesh) mesh = child;
+    if (!mesh && child instanceof THREE12.Mesh) mesh = child;
   });
   return mesh;
 }
@@ -6353,24 +6511,16 @@ function useActuators() {
     if (status !== "ready") return [];
     const model = mjModelRef.current;
     if (!model) return [];
-    const actuators = [];
-    for (let i = 0; i < model.nu; i++) {
-      const name = getName(model, model.name_actuatoradr[i]);
-      const lo = model.actuator_ctrlrange[i * 2];
-      const hi = model.actuator_ctrlrange[i * 2 + 1];
-      const hasRange = lo < hi;
-      const range = hasRange ? [lo, hi] : [-Infinity, Infinity];
-      actuators.push({ id: i, name, range });
-    }
+    const actuators = Array.from({ length: model.nactuator }, (_, id) => getActuatorInfo(model, id));
     return actuators;
   }, [status, mjModelRef]);
 }
-var _mat42 = new THREE11.Matrix4();
+var _mat42 = new THREE12.Matrix4();
 function useSitePosition(siteName) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const siteIdRef = useRef(-1);
-  const positionRef = useRef(new THREE11.Vector3());
-  const quaternionRef = useRef(new THREE11.Quaternion());
+  const positionRef = useRef(new THREE12.Vector3());
+  const quaternionRef = useRef(new THREE12.Quaternion());
   useEffect(() => {
     const model = mjModelRef.current;
     if (!model || status !== "ready") {
@@ -6563,10 +6713,10 @@ function useJointState(name, options = {}) {
 function useBodyState(name) {
   const { mjModelRef, status } = useMujocoContext();
   const bodyIdRef = useRef(-1);
-  const position = useRef(new THREE11.Vector3());
-  const quaternion = useRef(new THREE11.Quaternion());
-  const linearVelocity = useRef(new THREE11.Vector3());
-  const angularVelocity = useRef(new THREE11.Vector3());
+  const position = useRef(new THREE12.Vector3());
+  const quaternion = useRef(new THREE12.Quaternion());
+  const linearVelocity = useRef(new THREE12.Vector3());
+  const angularVelocity = useRef(new THREE12.Vector3());
   useEffect(() => {
     const model = mjModelRef.current;
     if (!model || status !== "ready") return;
@@ -6592,7 +6742,7 @@ function useBodyState(name) {
   });
   return { position, quaternion, linearVelocity, angularVelocity };
 }
-var _matrix2 = new THREE11.Matrix4();
+var _matrix2 = new THREE12.Matrix4();
 function quaternionFromMatrixArray(target, values, offset) {
   _matrix2.set(
     values[offset],
@@ -6626,8 +6776,8 @@ function useNamedPose(kind, name) {
   const { mjModelRef, status } = useMujocoContext();
   const idRef = useRef(-1);
   const foundRef = useRef(false);
-  const positionRef = useRef(new THREE11.Vector3());
-  const quaternionRef = useRef(new THREE11.Quaternion());
+  const positionRef = useRef(new THREE12.Vector3());
+  const quaternionRef = useRef(new THREE12.Quaternion());
   useEffect(() => {
     const model = mjModelRef.current;
     if (!model || status !== "ready") {
@@ -6679,7 +6829,7 @@ function useGeomPose(name) {
 function useSitePose(name) {
   return useNamedPose("site", name);
 }
-function useCtrl(name) {
+function useCtrl(name, input) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const actuatorIdRef = useRef(-1);
   const rangeRef = useRef([0, 0]);
@@ -6687,14 +6837,15 @@ function useCtrl(name) {
     const model = mjModelRef.current;
     if (!model || status !== "ready") return;
     const id = findActuatorByName(model, name);
-    actuatorIdRef.current = id;
+    const adr = getActuatorControlAddress(model, id, input);
+    actuatorIdRef.current = adr;
     if (id >= 0) {
       rangeRef.current = [
-        model.actuator_ctrlrange[id * 2],
-        model.actuator_ctrlrange[id * 2 + 1]
+        model.actuator_ctrlrange[adr * 2],
+        model.actuator_ctrlrange[adr * 2 + 1]
       ];
     }
-  }, [name, status, mjModelRef]);
+  }, [name, input, status, mjModelRef]);
   return useMemo(() => ({
     read() {
       const data = mjDataRef.current;
@@ -6864,7 +7015,7 @@ function useControlGroup(group, options = {}) {
       if (id < 0) {
         console.warn(`[mujoco-react] useControlGroup: actuator "${name}" was not found.`);
       }
-      return id;
+      return getActuatorControlAddress(model, id);
     });
   }, [mjModelRef, status, namesKey]);
   const patch = useCallback(
@@ -7070,7 +7221,7 @@ function useKeyboardTeleop(config) {
     const cache = /* @__PURE__ */ new Map();
     for (const binding of Object.values(config.bindings)) {
       if (!cache.has(binding.actuator)) {
-        cache.set(binding.actuator, findActuatorByName(model, binding.actuator));
+        cache.set(binding.actuator, getActuatorControlAddress(model, findActuatorByName(model, binding.actuator)));
       }
     }
     actuatorCacheRef.current = cache;
@@ -7120,9 +7271,9 @@ function useKeyboardTeleop(config) {
 }
 var DEFAULT_TRANSLATE_SPEED = 0.25;
 var DEFAULT_ROTATE_SPEED = 1;
-var _translation = new THREE11.Vector3();
-var _axis = new THREE11.Vector3();
-var _quat3 = new THREE11.Quaternion();
+var _translation = new THREE12.Vector3();
+var _axis = new THREE12.Vector3();
+var _quat3 = new THREE12.Quaternion();
 function actionSign(action) {
   return action.endsWith("+") ? 1 : -1;
 }
@@ -7899,10 +8050,10 @@ function useGamepad(config) {
     axisCacheRef.current.clear();
     buttonCacheRef.current.clear();
     for (const [idx, name] of Object.entries(config.axes ?? {})) {
-      axisCacheRef.current.set(Number(idx), findActuatorByName(model, name));
+      axisCacheRef.current.set(Number(idx), getActuatorControlAddress(model, findActuatorByName(model, name)));
     }
     for (const [idx, name] of Object.entries(config.buttons ?? {})) {
-      buttonCacheRef.current.set(Number(idx), findActuatorByName(model, name));
+      buttonCacheRef.current.set(Number(idx), getActuatorControlAddress(model, findActuatorByName(model, name)));
     }
   }, [config.axes, config.buttons, status, mjModelRef]);
   useBeforePhysicsStep(({ data }) => {
@@ -8590,7 +8741,7 @@ function useSelectionHighlight(bodyId, options = {}) {
       }
     }
     prevRef.current = [];
-    const highlightColor = new THREE11.Color(color);
+    const highlightColor = new THREE12.Color(color);
     for (const mesh of meshes) {
       const mat = mesh.material;
       if (mat.emissive) {
@@ -8617,15 +8768,15 @@ function useSelectionHighlight(bodyId, options = {}) {
 }
 function useCameraAnimation() {
   const { camera } = useThree();
-  const orbitTargetRef = useRef(new THREE11.Vector3(0, 0, 0));
+  const orbitTargetRef = useRef(new THREE12.Vector3(0, 0, 0));
   const cameraAnimRef = useRef({
     active: false,
-    startPos: new THREE11.Vector3(),
-    endPos: new THREE11.Vector3(),
-    startRot: new THREE11.Quaternion(),
-    endRot: new THREE11.Quaternion(),
-    startTarget: new THREE11.Vector3(),
-    endTarget: new THREE11.Vector3(),
+    startPos: new THREE12.Vector3(),
+    endPos: new THREE12.Vector3(),
+    startRot: new THREE12.Quaternion(),
+    endRot: new THREE12.Quaternion(),
+    startTarget: new THREE12.Vector3(),
+    endTarget: new THREE12.Vector3(),
     startTime: 0,
     duration: 0,
     resolve: null