mujoco-react 10.0.1 → 10.2.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAPTURE_EXCLUDE_KEY } from './chunk-QTCAVQS6.js';
-export { CAPTURE_EXCLUDE_KEY, ModelActuators, ModelBodies, ModelCameras, ModelGeoms, ModelJoints, ModelKeyframes, ModelResources, ModelSensors, ModelSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment } from './chunk-QTCAVQS6.js';
+import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY } from './chunk-3BMNRSS2.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, createCameraFrameCaptureSession, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, registerModelResources, renderCameraFrameToCanvas, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment } from './chunk-3BMNRSS2.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';
@@ -122,231 +122,6 @@ var CapsuleGeometry = class extends THREE11.BufferGeometry {
     self.setAttribute("uv", latheGeometry.getAttribute("uv"));
   }
 };
-var Reflector = class extends THREE11.Mesh {
-  isReflector = true;
-  camera;
-  reflectorPlane = new THREE11.Plane();
-  normal = new THREE11.Vector3();
-  reflectorWorldPosition = new THREE11.Vector3();
-  cameraWorldPosition = new THREE11.Vector3();
-  rotationMatrix = new THREE11.Matrix4();
-  lookAtPosition = new THREE11.Vector3(0, 0, -1);
-  clipPlane = new THREE11.Vector4();
-  view = new THREE11.Vector3();
-  target = new THREE11.Vector3();
-  q = new THREE11.Vector4();
-  textureMatrix = new THREE11.Matrix4();
-  virtualCamera;
-  renderTarget;
-  constructor(geometry, options = {}) {
-    super(geometry);
-    this.type = "Reflector";
-    this.camera = new THREE11.PerspectiveCamera();
-    const color = options.color !== void 0 ? new THREE11.Color(options.color) : new THREE11.Color(8355711);
-    const textureWidth = options.textureWidth || 512;
-    const textureHeight = options.textureHeight || 512;
-    const clipBias = options.clipBias || 0;
-    const multisample = options.multisample !== void 0 ? options.multisample : 4;
-    const blendTexture = options.texture || void 0;
-    const mixStrength = options.mixStrength !== void 0 ? options.mixStrength : 0.25;
-    this.virtualCamera = this.camera;
-    this.renderTarget = new THREE11.WebGLRenderTarget(textureWidth, textureHeight, {
-      samples: multisample,
-      type: THREE11.HalfFloatType
-    });
-    this.material = new THREE11.MeshPhysicalMaterial({
-      map: blendTexture,
-      color,
-      roughness: 0.5,
-      metalness: 0.1
-    });
-    this.material.onBeforeCompile = (shader) => {
-      shader.uniforms.tDiffuse = { value: this.renderTarget.texture };
-      shader.uniforms.textureMatrix = { value: this.textureMatrix };
-      shader.uniforms.mixStrength = { value: mixStrength };
-      const bodyStart = shader.vertexShader.indexOf("void main() {");
-      shader.vertexShader = "uniform mat4 textureMatrix;\nvarying vec4 vUvReflection;\n" + shader.vertexShader.slice(0, bodyStart) + shader.vertexShader.slice(bodyStart, -1) + "   vUvReflection = textureMatrix * vec4( position, 1.0 );\n}";
-      const fragmentBodyStart = shader.fragmentShader.indexOf("void main() {");
-      shader.fragmentShader = "uniform sampler2D tDiffuse;\nuniform float mixStrength;\nvarying vec4 vUvReflection;\n" + shader.fragmentShader.slice(0, fragmentBodyStart) + shader.fragmentShader.slice(fragmentBodyStart, -1) + "   vec4 reflectionColor = texture2DProj( tDiffuse, vUvReflection );\n   gl_FragColor = vec4( mix( gl_FragColor.rgb, reflectionColor.rgb, mixStrength ), gl_FragColor.a );\n}";
-    };
-    this.receiveShadow = true;
-    this.onBeforeRender = (renderer, scene, camera) => {
-      this.reflectorWorldPosition.setFromMatrixPosition(this.matrixWorld);
-      this.cameraWorldPosition.setFromMatrixPosition(camera.matrixWorld);
-      this.rotationMatrix.extractRotation(this.matrixWorld);
-      this.normal.set(0, 0, 1);
-      this.normal.applyMatrix4(this.rotationMatrix);
-      this.view.subVectors(this.reflectorWorldPosition, this.cameraWorldPosition);
-      if (this.view.dot(this.normal) > 0) return;
-      this.view.reflect(this.normal).negate();
-      this.view.add(this.reflectorWorldPosition);
-      this.rotationMatrix.extractRotation(camera.matrixWorld);
-      this.lookAtPosition.set(0, 0, -1);
-      this.lookAtPosition.applyMatrix4(this.rotationMatrix);
-      this.lookAtPosition.add(this.cameraWorldPosition);
-      this.target.subVectors(this.reflectorWorldPosition, this.lookAtPosition);
-      this.target.reflect(this.normal).negate();
-      this.target.add(this.reflectorWorldPosition);
-      this.virtualCamera.position.copy(this.view);
-      this.virtualCamera.up.set(0, 1, 0);
-      this.virtualCamera.up.applyMatrix4(this.rotationMatrix);
-      this.virtualCamera.up.reflect(this.normal);
-      this.virtualCamera.lookAt(this.target);
-      this.virtualCamera.far = camera.far;
-      this.virtualCamera.updateMatrixWorld();
-      this.virtualCamera.projectionMatrix.copy(camera.projectionMatrix);
-      this.textureMatrix.set(
-        0.5,
-        0,
-        0,
-        0.5,
-        0,
-        0.5,
-        0,
-        0.5,
-        0,
-        0,
-        0.5,
-        0.5,
-        0,
-        0,
-        0,
-        1
-      );
-      this.textureMatrix.multiply(this.virtualCamera.projectionMatrix);
-      this.textureMatrix.multiply(this.virtualCamera.matrixWorldInverse);
-      this.textureMatrix.multiply(this.matrixWorld);
-      this.reflectorPlane.setFromNormalAndCoplanarPoint(this.normal, this.reflectorWorldPosition);
-      this.reflectorPlane.applyMatrix4(this.virtualCamera.matrixWorldInverse);
-      this.clipPlane.set(this.reflectorPlane.normal.x, this.reflectorPlane.normal.y, this.reflectorPlane.normal.z, this.reflectorPlane.constant);
-      const projectionMatrix = this.virtualCamera.projectionMatrix;
-      this.q.x = (Math.sign(this.clipPlane.x) + projectionMatrix.elements[8]) / projectionMatrix.elements[0];
-      this.q.y = (Math.sign(this.clipPlane.y) + projectionMatrix.elements[9]) / projectionMatrix.elements[5];
-      this.q.z = -1;
-      this.q.w = (1 + projectionMatrix.elements[10]) / projectionMatrix.elements[14];
-      this.clipPlane.multiplyScalar(2 / this.clipPlane.dot(this.q));
-      projectionMatrix.elements[2] = this.clipPlane.x;
-      projectionMatrix.elements[6] = this.clipPlane.y;
-      projectionMatrix.elements[10] = this.clipPlane.z + 1 - clipBias;
-      projectionMatrix.elements[14] = this.clipPlane.w;
-      this.visible = false;
-      const currentRenderTarget = renderer.getRenderTarget();
-      const currentXrEnabled = renderer.xr.enabled;
-      const currentShadowAutoUpdate = renderer.shadowMap.autoUpdate;
-      renderer.xr.enabled = false;
-      renderer.shadowMap.autoUpdate = false;
-      renderer.setRenderTarget(this.renderTarget);
-      renderer.state.buffers.depth.setMask(true);
-      if (renderer.autoClear === false) renderer.clear();
-      renderer.render(scene, this.virtualCamera);
-      renderer.xr.enabled = currentXrEnabled;
-      renderer.shadowMap.autoUpdate = currentShadowAutoUpdate;
-      renderer.setRenderTarget(currentRenderTarget);
-      const viewport = camera.viewport;
-      if (viewport !== void 0) {
-        renderer.state.viewport(viewport);
-      }
-      this.visible = true;
-    };
-  }
-  getRenderTarget() {
-    return this.renderTarget;
-  }
-  dispose() {
-    this.renderTarget.dispose();
-    const mesh = this;
-    if (Array.isArray(mesh.material)) {
-      mesh.material.forEach((m) => m.dispose());
-    } else {
-      mesh.material.dispose();
-    }
-  }
-};
-
-// src/rendering/GeomBuilder.ts
-var GeomBuilder = class {
-  mujoco;
-  constructor(mujoco) {
-    this.mujoco = mujoco;
-  }
-  /**
-   * Creates a Three.js Object3D (usually a Mesh) for a specific geometry in the MuJoCo model.
-   * Returns null if the geometry shouldn't be rendered (e.g., invisible collision triggers).
-   */
-  create(mjModel, g) {
-    if (mjModel.geom_group[g] === 3) return null;
-    const type = mjModel.geom_type[g];
-    const size = mjModel.geom_size.subarray(g * 3, g * 3 + 3);
-    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);
-    let opacity = 1;
-    if (matId >= 0) {
-      const rgba = mjModel.mat_rgba.subarray(matId * 4, matId * 4 + 4);
-      color.setRGB(rgba[0], rgba[1], rgba[2]);
-      opacity = rgba[3];
-    } else {
-      const rgba = mjModel.geom_rgba.subarray(g * 4, g * 4 + 4);
-      color.setRGB(rgba[0], rgba[1], rgba[2]);
-      opacity = rgba[3];
-    }
-    const MG = this.mujoco.mjtGeom;
-    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);
-    } else if (type === getVal(MG.mjGEOM_SPHERE)) {
-      geo = new THREE11.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);
-    } else if (type === getVal(MG.mjGEOM_CYLINDER)) {
-      geo = new THREE11.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];
-      const vAdr = mjModel.mesh_vertadr[mId];
-      const vNum = mjModel.mesh_vertnum[mId];
-      const fAdr = mjModel.mesh_faceadr[mId];
-      const fNum = mjModel.mesh_facenum[mId];
-      geo = new THREE11.BufferGeometry();
-      geo.setAttribute("position", new THREE11.Float32BufferAttribute(mjModel.mesh_vert.subarray(vAdr * 3, (vAdr + vNum) * 3), 3));
-      geo.setIndex(Array.from(mjModel.mesh_face.subarray(fAdr * 3, (fAdr + fNum) * 3)));
-      geo.computeVertexNormals();
-    }
-    if (geo) {
-      let mesh;
-      if (type === getVal(MG.mjGEOM_PLANE)) {
-        mesh = new Reflector(geo, {
-          clipBias: 3e-3,
-          textureWidth: 1024,
-          textureHeight: 1024,
-          color,
-          mixStrength: 0.25
-        });
-      } else {
-        mesh = new THREE11.Mesh(geo, new THREE11.MeshStandardMaterial({
-          color,
-          transparent: opacity < 1,
-          opacity,
-          roughness: 0.6,
-          metalness: 0.2
-        }));
-        mesh.castShadow = true;
-        mesh.receiveShadow = true;
-      }
-      mesh.position.set(pos[0], pos[1], pos[2]);
-      mesh.quaternion.set(quat[1], quat[2], quat[3], quat[0]);
-      mesh.userData.bodyID = mjModel.geom_bodyid[g];
-      mesh.userData.geomID = g;
-      return mesh;
-    }
-    return null;
-  }
-};
 
 // src/core/SceneLoader.ts
 var JOINT_TYPE_NAMES = {
@@ -704,8 +479,10 @@ function createContiguousControlGroup(mjModel, count) {
 }
 function sceneObjectToXml(obj) {
   const joint = obj.freejoint ? "<freejoint/>" : "";
+  const geomName = obj.geomName ?? `${obj.name}_geom`;
   const pos = obj.position.map((v) => v.toFixed(3)).join(" ");
-  const size = obj.size.map((v) => v.toFixed(3)).join(" ");
+  const sizeValues = obj.type === "sphere" ? obj.size.slice(0, 1) : obj.type === "cylinder" ? obj.size.slice(0, 2) : obj.size;
+  const size = sizeValues.map((v) => v.toFixed(3)).join(" ");
   const rgba = obj.rgba.join(" ");
   const mass = obj.mass ? ` mass="${obj.mass}"` : "";
   const friction = obj.friction ? ` friction="${obj.friction}"` : "";
@@ -713,7 +490,7 @@ function sceneObjectToXml(obj) {
   const solimp = obj.solimp ? ` solimp="${obj.solimp}"` : "";
   const condim = obj.condim ? ` condim="${obj.condim}"` : "";
   const group = obj.group !== void 0 ? ` group="${obj.group}"` : "";
-  return `<body name="${obj.name}" pos="${pos}">${joint}<geom type="${obj.type}" size="${size}" rgba="${rgba}" contype="1" conaffinity="1"${mass}${friction}${solref}${solimp}${condim}${group}/></body>`;
+  return `<body name="${obj.name}" pos="${pos}">${joint}<geom name="${geomName}" type="${obj.type}" size="${size}" rgba="${rgba}" contype="1" conaffinity="1"${mass}${friction}${solref}${solimp}${condim}${group}/></body>`;
 }
 function ensureDir(mujoco, fname) {
   const dirParts = fname.split("/");
@@ -1112,6 +889,137 @@ function collectDependencyPaths(xmlString, currentFile, parser) {
   });
   return paths;
 }
+
+// src/rendering/GeomBuilder.ts
+var GeomBuilder = class {
+  mujoco;
+  textureCache = /* @__PURE__ */ new Map();
+  constructor(mujoco) {
+    this.mujoco = mujoco;
+  }
+  getMaterialTexture(mjModel, matId) {
+    if (matId < 0 || !mjModel.mat_texid || !mjModel.tex_data) return null;
+    const materialCount = Math.max(1, Math.floor(mjModel.mat_rgba.length / 4));
+    const textureRoles = Math.max(1, Math.floor(mjModel.mat_texid.length / materialCount));
+    let texId = -1;
+    for (let role = 0; role < textureRoles; role += 1) {
+      const candidate = mjModel.mat_texid[matId * textureRoles + role];
+      if (candidate >= 0) {
+        texId = candidate;
+        break;
+      }
+    }
+    if (texId < 0) return null;
+    const cached = this.textureCache.get(texId);
+    if (cached) return cached;
+    const width = Number(mjModel.tex_width[texId]);
+    const height = Number(mjModel.tex_height[texId]);
+    const channels = Number(mjModel.tex_nchannel[texId]);
+    const offset = Number(mjModel.tex_adr[texId]);
+    if (width <= 0 || height <= 0 || channels <= 0 || offset < 0) return null;
+    const source = mjModel.tex_data.subarray(offset, offset + width * height * channels);
+    const rgba = new Uint8Array(width * height * 4);
+    for (let i = 0, j = 0; i < width * height; i += 1, j += channels) {
+      const r = source[j] ?? 255;
+      const g = channels > 1 ? source[j + 1] : r;
+      const b = channels > 2 ? source[j + 2] : r;
+      const a = channels > 3 ? source[j + 3] : 255;
+      const out = i * 4;
+      rgba[out] = r;
+      rgba[out + 1] = g;
+      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;
+    texture.flipY = true;
+    const repeatOffset = matId * 2;
+    const repeatS = mjModel.mat_texrepeat?.[repeatOffset] ?? 1;
+    const repeatT = mjModel.mat_texrepeat?.[repeatOffset + 1] ?? 1;
+    texture.repeat.set(repeatS || 1, repeatT || 1);
+    texture.needsUpdate = true;
+    this.textureCache.set(texId, texture);
+    return texture;
+  }
+  /**
+   * Creates a Three.js Object3D (usually a Mesh) for a specific geometry in the MuJoCo model.
+   * Returns null if the geometry shouldn't be rendered (e.g., invisible collision triggers).
+   */
+  create(mjModel, g) {
+    if (mjModel.geom_group[g] === 3) return null;
+    const type = mjModel.geom_type[g];
+    const size = mjModel.geom_size.subarray(g * 3, g * 3 + 3);
+    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 map = this.getMaterialTexture(mjModel, matId);
+    let opacity = 1;
+    if (matId >= 0) {
+      const rgba = mjModel.mat_rgba.subarray(matId * 4, matId * 4 + 4);
+      color.setRGB(rgba[0], rgba[1], rgba[2]);
+      opacity = rgba[3];
+    } else {
+      const rgba = mjModel.geom_rgba.subarray(g * 4, g * 4 + 4);
+      color.setRGB(rgba[0], rgba[1], rgba[2]);
+      opacity = rgba[3];
+    }
+    const MG = this.mujoco.mjtGeom;
+    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);
+    } else if (type === getVal(MG.mjGEOM_SPHERE)) {
+      geo = new THREE11.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);
+    } else if (type === getVal(MG.mjGEOM_CYLINDER)) {
+      geo = new THREE11.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];
+      const vAdr = mjModel.mesh_vertadr[mId];
+      const vNum = mjModel.mesh_vertnum[mId];
+      const fAdr = mjModel.mesh_faceadr[mId];
+      const fNum = mjModel.mesh_facenum[mId];
+      geo = new THREE11.BufferGeometry();
+      geo.setAttribute("position", new THREE11.Float32BufferAttribute(mjModel.mesh_vert.subarray(vAdr * 3, (vAdr + vNum) * 3), 3));
+      geo.setIndex(Array.from(mjModel.mesh_face.subarray(fAdr * 3, (fAdr + fNum) * 3)));
+      geo.computeVertexNormals();
+    }
+    if (geo) {
+      const isPlane = type === getVal(MG.mjGEOM_PLANE);
+      const materialMap = isPlane && map ? map.clone() : map;
+      if (isPlane && materialMap) {
+        materialMap.repeat.multiplyScalar(2.5);
+        materialMap.needsUpdate = true;
+      }
+      const mesh = new THREE11.Mesh(geo, new THREE11.MeshStandardMaterial({
+        color,
+        map: materialMap,
+        transparent: opacity < 1,
+        opacity,
+        roughness: 0.6,
+        metalness: 0
+      }));
+      mesh.castShadow = type !== getVal(MG.mjGEOM_PLANE);
+      mesh.receiveShadow = true;
+      mesh.position.set(pos[0], pos[1], pos[2]);
+      mesh.quaternion.set(quat[1], quat[2], quat[3], quat[0]);
+      mesh.userData.bodyID = mjModel.geom_bodyid[g];
+      mesh.userData.geomID = g;
+      mesh.userData.geomGroup = mjModel.geom_group[g];
+      mesh.userData.geomName = getName(mjModel, mjModel.name_geomadr[g]);
+      return mesh;
+    }
+    return null;
+  }
+};
 function SceneRenderer(props) {
   const {
     mjModelRef,
@@ -1158,7 +1066,7 @@ function SceneRenderer(props) {
     }
     bodyRefs.current = refs;
   }, [status, geomBuilder, mjModelRef]);
-  useFrame(() => {
+  const syncBodiesToData = useCallback(() => {
     const data = mjDataRef.current;
     if (!data) return;
     const bodies = bodyRefs.current;
@@ -1203,12 +1111,17 @@ function SceneRenderer(props) {
         );
       }
     }
-  });
+  }, [interpolateRef, interpolationStateRef, mjDataRef]);
+  useFrame(syncBodiesToData);
   return /* @__PURE__ */ jsx(
     "group",
     {
       ...props,
       ref: groupRef,
+      userData: {
+        ...props.userData,
+        [CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY]: syncBodiesToData
+      },
       onDoubleClick: (e) => {
         if (typeof props.onDoubleClick === "function") props.onDoubleClick(e);
         e.stopPropagation();
@@ -1735,6 +1648,125 @@ async function recordMountedCameraFrameSequence(api, options) {
     readiness
   };
 }
+var _raycaster = new THREE11.Raycaster();
+var _ndc = new THREE11.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]);
+}
+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) {
+      camera.quaternion.copy(options.quaternion);
+    } else {
+      camera.quaternion.set(
+        options.quaternion[0],
+        options.quaternion[1],
+        options.quaternion[2],
+        options.quaternion[3]
+      );
+    }
+  } else if (options.lookAt) {
+    camera.lookAt(toVector3(options.lookAt, new THREE11.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) {
+    camera.aspect = width / height;
+    camera.fov = options.fov ?? camera.fov;
+    camera.near = options.near ?? camera.near;
+    camera.far = options.far ?? camera.far;
+    camera.updateProjectionMatrix();
+  }
+  applyCameraPose(camera, options, fallbackCamera);
+  return camera;
+}
+function getProjectionSource(options) {
+  if (options.source) return options.source;
+  if (options.cameraName) return { kind: "mujoco-camera", cameraName: options.cameraName };
+  if (options.siteName) return { kind: "mujoco-site", siteName: options.siteName };
+  if (options.bodyName) return { kind: "mujoco-body", bodyName: options.bodyName };
+  if (options.camera) return { kind: "custom-camera" };
+  if (options.position || options.lookAt || options.quaternion) return { kind: "explicit-pose" };
+  return { kind: "fallback-camera" };
+}
+function imageSize(renderer, options) {
+  return [
+    Math.max(1, Math.floor(options.imageWidth ?? options.width ?? renderer.domElement.width)),
+    Math.max(1, Math.floor(options.imageHeight ?? options.height ?? renderer.domElement.height))
+  ];
+}
+function imagePointToNdc(x, y, coordinateSpace = "normalized", width = 1, height = 1) {
+  if (coordinateSpace === "ndc") return [x, y];
+  if (coordinateSpace === "normalized-1000") {
+    return [x / 1e3 * 2 - 1, 1 - y / 1e3 * 2];
+  }
+  if (coordinateSpace === "pixel") {
+    return [x / width * 2 - 1, 1 - y / height * 2];
+  }
+  return [x * 2 - 1, 1 - y * 2];
+}
+function isProjectionCandidate(object, options) {
+  if (!object.visible) return false;
+  if (object.userData[CAPTURE_EXCLUDE_KEY]) return false;
+  const geomGroup = object.userData.geomGroup;
+  const geomName = object.userData.geomName;
+  if (options.hiddenGeomNames && typeof geomName === "string" && options.hiddenGeomNames.includes(geomName)) {
+    return false;
+  }
+  if (options.hiddenGeomGroups && typeof geomGroup === "number" && options.hiddenGeomGroups.includes(geomGroup)) {
+    return false;
+  }
+  if (options.visibleGeomGroups && typeof geomGroup === "number" && !options.visibleGeomGroups.includes(geomGroup)) {
+    return false;
+  }
+  return true;
+}
+function findBodyId(object) {
+  let current = object;
+  while (current && current.userData.bodyID === void 0 && current.parent) {
+    current = current.parent;
+  }
+  return typeof current?.userData.bodyID === "number" ? current.userData.bodyID : -1;
+}
+function projectImagePointTo3D(renderer, scene, fallbackCamera, options) {
+  const [width, height] = imageSize(renderer, options);
+  const [ndcX, ndcY] = imagePointToNdc(
+    options.x,
+    options.y,
+    options.coordinateSpace,
+    width,
+    height
+  );
+  const projectionCamera = createProjectionCamera(fallbackCamera, options, width, height);
+  scene.updateMatrixWorld(true);
+  _ndc.set(ndcX, ndcY);
+  _raycaster.setFromCamera(_ndc, projectionCamera);
+  _raycaster.far = options.maxDistance ?? Infinity;
+  const objects = [];
+  scene.traverse((object) => {
+    if (object.isMesh && isProjectionCandidate(object, options)) {
+      objects.push(object);
+    }
+  });
+  const [hit] = _raycaster.intersectObjects(objects, true);
+  if (!hit) return null;
+  return {
+    point: hit.point.clone(),
+    bodyId: findBodyId(hit.object),
+    geomId: typeof hit.object.userData.geomID === "number" ? hit.object.userData.geomID : -1,
+    distance: hit.distance,
+    ndc: [ndcX, ndcY],
+    imageSize: [width, height],
+    source: getProjectionSource(options)
+  };
+}
 var JOINT_TYPE_NAMES2 = ["free", "ball", "slide", "hinge"];
 var GEOM_TYPE_NAMES = ["plane", "hfield", "sphere", "capsule", "ellipsoid", "cylinder", "box", "mesh"];
 var SENSOR_TYPE_NAMES = {
@@ -1862,6 +1894,42 @@ function omitResolvedCameraSelectors(options) {
   const { cameraName, siteName, bodyName, ...rest } = options;
   return rest;
 }
+function vector3FromCaptureValue(value) {
+  return value instanceof THREE11.Vector3 ? value.clone() : new THREE11.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]);
+}
+function applyMountedCameraPoseOffsets(options, position, quaternion) {
+  const resolvedPosition = new THREE11.Vector3(position[0], position[1], position[2]);
+  const resolvedQuaternion = new THREE11.Quaternion(
+    quaternion[0],
+    quaternion[1],
+    quaternion[2],
+    quaternion[3]
+  );
+  if (options.positionOffset) {
+    resolvedPosition.add(
+      vector3FromCaptureValue(options.positionOffset).applyQuaternion(resolvedQuaternion)
+    );
+  }
+  if (options.quaternionOffset) {
+    resolvedQuaternion.multiply(quaternionFromCaptureValue(options.quaternionOffset)).normalize();
+  }
+  return {
+    position: [
+      resolvedPosition.x,
+      resolvedPosition.y,
+      resolvedPosition.z
+    ],
+    quaternion: [
+      resolvedQuaternion.x,
+      resolvedQuaternion.y,
+      resolvedQuaternion.z,
+      resolvedQuaternion.w
+    ]
+  };
+}
 function countMountedCameraSelectors(options) {
   return Number(Boolean(options.cameraName)) + Number(Boolean(options.siteName)) + Number(Boolean(options.bodyName));
 }
@@ -2553,10 +2621,10 @@ function MujocoSimProvider({
             `MuJoCo camera "${options.cameraName}" does not expose a capture pose.`
           );
         }
+        const pose = applyMountedCameraPoseOffsets(options, position, quaternion);
         return {
           ...baseOptions,
-          position,
-          quaternion,
+          ...pose,
           fov: options.fov ?? model.cam_fovy?.[cameraId],
           source: { kind: "mujoco-camera", cameraName: options.cameraName }
         };
@@ -2566,10 +2634,14 @@ function MujocoSimProvider({
         if (siteId < 0) {
           throw new Error(`MuJoCo site "${options.siteName}" was not found.`);
         }
+        const pose = applyMountedCameraPoseOffsets(
+          options,
+          vector3FromArray(data.site_xpos, siteId * 3),
+          quaternionFromXmat(data.site_xmat, siteId * 9)
+        );
         return {
           ...baseOptions,
-          position: vector3FromArray(data.site_xpos, siteId * 3),
-          quaternion: quaternionFromXmat(data.site_xmat, siteId * 9),
+          ...pose,
           source: { kind: "mujoco-site", siteName: options.siteName }
         };
       }
@@ -2583,10 +2655,14 @@ function MujocoSimProvider({
             `MuJoCo body "${options.bodyName}" does not expose world orientation data.`
           );
         }
+        const pose = applyMountedCameraPoseOffsets(
+          options,
+          vector3FromArray(data.xpos, bodyId * 3),
+          quaternionFromXmat(data.xmat, bodyId * 9)
+        );
         return {
           ...baseOptions,
-          position: vector3FromArray(data.xpos, bodyId * 3),
-          quaternion: quaternionFromXmat(data.xmat, bodyId * 9),
+          ...pose,
           source: { kind: "mujoco-body", bodyName: options.bodyName }
         };
       }
@@ -2994,6 +3070,30 @@ function MujocoSimProvider({
     },
     [camera, gl]
   );
+  const projectImagePointTo3D2 = useCallback(
+    (options) => {
+      const {
+        x,
+        y,
+        coordinateSpace,
+        imageWidth,
+        imageHeight,
+        maxDistance,
+        ...captureOptions
+      } = options;
+      const resolvedCaptureOptions = resolveCameraCaptureOptions(captureOptions);
+      return projectImagePointTo3D(gl, scene, camera, {
+        ...resolvedCaptureOptions,
+        x,
+        y,
+        coordinateSpace,
+        imageWidth,
+        imageHeight,
+        maxDistance
+      });
+    },
+    [camera, gl, resolveCameraCaptureOptions, scene]
+  );
   const setBodyMass = useCallback((name, mass) => {
     const model = mjModelRef.current;
     if (!model) return;
@@ -3078,6 +3178,7 @@ function MujocoSimProvider({
       captureCameraFrameBlob: captureCameraFrameBlobApi,
       recordCameraSequence: recordCameraSequenceApi,
       project2DTo3D,
+      projectImagePointTo3D: projectImagePointTo3D2,
       setBodyMass,
       setGeomFriction,
       setGeomSize,
@@ -3137,6 +3238,7 @@ function MujocoSimProvider({
       captureCameraFrameBlobApi,
       recordCameraSequenceApi,
       project2DTo3D,
+      projectImagePointTo3D2,
       setBodyMass,
       setGeomFriction,
       setGeomSize
@@ -3724,8 +3826,8 @@ var useIkController = createControllerHook(
       const ga = gizmoAnimRef.current;
       const target = ikTargetRef.current;
       if (!ga.active || !target) return;
-      const now = performance.now();
-      const elapsed = now - ga.startTime;
+      const now2 = performance.now();
+      const elapsed = now2 - ga.startTime;
       const t = Math.min(elapsed / ga.duration, 1);
       const ease = 1 - Math.pow(1 - t, 3);
       target.position.lerpVectors(ga.startPos, ga.endPos, ease);
@@ -4088,7 +4190,7 @@ var _point = new Float64Array(3);
 var _bodyPos = new THREE11.Vector3();
 var _bodyQuat = new THREE11.Quaternion();
 var _worldHit = new THREE11.Vector3();
-var _raycaster = new THREE11.Raycaster();
+var _raycaster2 = new THREE11.Raycaster();
 var _mouse = new THREE11.Vector2();
 function DragInteraction({
   stiffness = 250,
@@ -4137,8 +4239,8 @@ function DragInteraction({
         (evt.clientX - rect.left) / rect.width * 2 - 1,
         -((evt.clientY - rect.top) / rect.height) * 2 + 1
       );
-      _raycaster.setFromCamera(_mouse, camera);
-      const hits = _raycaster.intersectObjects(scene.children, true);
+      _raycaster2.setFromCamera(_mouse, camera);
+      const hits = _raycaster2.intersectObjects(scene.children, true);
       for (const hit of hits) {
         let obj = hit.object;
         while (obj && obj.userData.bodyID === void 0 && obj.parent) {
@@ -4183,8 +4285,8 @@ function DragInteraction({
         (evt.clientX - rect.left) / rect.width * 2 - 1,
         -((evt.clientY - rect.top) / rect.height) * 2 + 1
       );
-      _raycaster.setFromCamera(_mouse, camera);
-      mouseWorldRef.current.copy(_raycaster.ray.origin).addScaledVector(_raycaster.ray.direction, grabDistanceRef.current);
+      _raycaster2.setFromCamera(_mouse, camera);
+      mouseWorldRef.current.copy(_raycaster2.ray.origin).addScaledVector(_raycaster2.ray.direction, grabDistanceRef.current);
     };
     const onPointerUp = () => {
       if (!draggingRef.current) return;
@@ -5532,12 +5634,12 @@ function useTrajectoryPlayer(trajectory, options = {}) {
     if ((optionsRef.current.mode ?? "kinematic") !== "kinematic") return;
     const traj = trajectoryRef.current;
     if (traj.length === 0) return;
-    const now = performance.now();
+    const now2 = performance.now();
     const fps = optionsRef.current.fps ?? 30;
     const frameInterval = 1e3 / (fps * speedRef.current);
-    const elapsed = now - lastFrameTimeRef.current;
+    const elapsed = now2 - lastFrameTimeRef.current;
     if (elapsed < frameInterval) return;
-    lastFrameTimeRef.current = now;
+    lastFrameTimeRef.current = now2;
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return;
@@ -5894,6 +5996,93 @@ function useBodyState(name) {
   });
   return { position, quaternion, linearVelocity, angularVelocity };
 }
+var _matrix2 = new THREE11.Matrix4();
+function quaternionFromMatrixArray(target, values, offset) {
+  _matrix2.set(
+    values[offset],
+    values[offset + 1],
+    values[offset + 2],
+    0,
+    values[offset + 3],
+    values[offset + 4],
+    values[offset + 5],
+    0,
+    values[offset + 6],
+    values[offset + 7],
+    values[offset + 8],
+    0,
+    0,
+    0,
+    0,
+    1
+  );
+  target.setFromRotationMatrix(_matrix2);
+}
+function quaternionFromMujocoQuat2(target, values, offset) {
+  target.set(
+    values[offset + 1] ?? 0,
+    values[offset + 2] ?? 0,
+    values[offset + 3] ?? 0,
+    values[offset] ?? 1
+  );
+}
+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());
+  useEffect(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== "ready") {
+      idRef.current = -1;
+      foundRef.current = false;
+      return;
+    }
+    if (kind === "body") idRef.current = findBodyByName(model, name);
+    else if (kind === "geom") idRef.current = findGeomByName(model, name);
+    else idRef.current = findSiteByName(model, name);
+    foundRef.current = idRef.current >= 0;
+  }, [kind, name, status, mjModelRef]);
+  useAfterPhysicsStep(({ data }) => {
+    const id = idRef.current;
+    if (id < 0) return;
+    if (kind === "body") {
+      const p2 = id * 3;
+      positionRef.current.set(data.xpos[p2], data.xpos[p2 + 1], data.xpos[p2 + 2]);
+      if (data.xmat) {
+        quaternionFromMatrixArray(quaternionRef.current, data.xmat, id * 9);
+      } else {
+        quaternionFromMujocoQuat2(quaternionRef.current, data.xquat, id * 4);
+      }
+      return;
+    }
+    if (kind === "geom") {
+      const p2 = id * 3;
+      positionRef.current.set(data.geom_xpos[p2], data.geom_xpos[p2 + 1], data.geom_xpos[p2 + 2]);
+      quaternionFromMatrixArray(quaternionRef.current, data.geom_xmat, id * 9);
+      return;
+    }
+    const p = id * 3;
+    positionRef.current.set(data.site_xpos[p], data.site_xpos[p + 1], data.site_xpos[p + 2]);
+    quaternionFromMatrixArray(quaternionRef.current, data.site_xmat, id * 9);
+  });
+  return {
+    id: idRef,
+    found: foundRef,
+    position: positionRef,
+    quaternion: quaternionRef
+  };
+}
+function useBodyPose(name) {
+  return useNamedPose("body", name);
+}
+function useGeomPose(name) {
+  return useNamedPose("geom", name);
+}
+function useSitePose(name) {
+  return useNamedPose("site", name);
+}
 function useCtrl(name) {
   const { mjModelRef, mjDataRef, status } = useMujocoContext();
   const actuatorIdRef = useRef(-1);
@@ -5927,10 +6116,203 @@ function useCtrl(name) {
     }
   }), [name, mjDataRef]);
 }
-function useKeyboardTeleop(config) {
-  const { mjModelRef, mjDataRef, status } = useMujocoContext();
-  const pressedRef = useRef(/* @__PURE__ */ new Set());
-  const toggleStateRef = useRef(/* @__PURE__ */ new Map());
+var claimsByModel = /* @__PURE__ */ new WeakMap();
+function getClaims(model) {
+  let claims = claimsByModel.get(model);
+  if (!claims) {
+    claims = /* @__PURE__ */ new Map();
+    claimsByModel.set(model, claims);
+  }
+  return claims;
+}
+function releaseClaims(model, token) {
+  if (!model) return;
+  const claims = claimsByModel.get(model);
+  if (!claims) return;
+  for (const [actuatorIndex, claim] of claims) {
+    if (claim.token === token) claims.delete(actuatorIndex);
+  }
+}
+function useControlWriter(options) {
+  const {
+    owner,
+    selector,
+    enabled = true,
+    warnOnConflict = true,
+    allowSameOwner = true,
+    onConflict
+  } = options;
+  const { api, mjModelRef, mjDataRef, status } = useMujocoContext();
+  const tokenRef = useRef(Symbol(owner));
+  const claimedModelRef = useRef(null);
+  const groupRef = useRef(null);
+  const conflictsRef = useRef([]);
+  const onConflictRef = useRef(onConflict);
+  onConflictRef.current = onConflict;
+  const release = useCallback(() => {
+    releaseClaims(claimedModelRef.current, tokenRef.current);
+    claimedModelRef.current = null;
+    conflictsRef.current = [];
+  }, []);
+  useEffect(() => {
+    release();
+    if (!enabled || status !== "ready") {
+      groupRef.current = null;
+      return;
+    }
+    const model = mjModelRef.current;
+    if (!model) {
+      groupRef.current = null;
+      return;
+    }
+    const group = selector ? api.resolveControlGroup(selector) : api.getControlMap();
+    groupRef.current = group;
+    if (!group) return;
+    const claims = getClaims(model);
+    const conflicts = [];
+    for (const actuatorIndex of group.ctrlAdr) {
+      const existing = claims.get(actuatorIndex);
+      if (existing && existing.token !== tokenRef.current && (!allowSameOwner || existing.owner !== owner)) {
+        conflicts.push({
+          actuatorIndex,
+          owner: existing.owner,
+          requestedBy: owner
+        });
+      }
+    }
+    conflictsRef.current = conflicts;
+    if (conflicts.length > 0) {
+      onConflictRef.current?.(conflicts);
+      if (warnOnConflict) {
+        console.warn(
+          `[mujoco-react] Control writer "${owner}" conflicts with existing writer(s): ${conflicts.map((conflict) => `${conflict.actuatorIndex}:${conflict.owner}`).join(", ")}`
+        );
+      }
+      return;
+    }
+    for (const actuatorIndex of group.ctrlAdr) {
+      claims.set(actuatorIndex, { owner, token: tokenRef.current });
+    }
+    claimedModelRef.current = model;
+    return release;
+  }, [allowSameOwner, api, enabled, mjModelRef, owner, release, selector, status, warnOnConflict]);
+  const canWrite = useCallback(() => enabled && groupRef.current !== null && conflictsRef.current.length === 0, [enabled]);
+  const read = useCallback(() => {
+    const data = mjDataRef.current;
+    const group = groupRef.current;
+    if (!data || !group) return new Float64Array(0);
+    return group.readCtrl(data);
+  }, [mjDataRef]);
+  const write = useCallback((values, writeOptions = {}) => {
+    const data = mjDataRef.current;
+    const group = groupRef.current;
+    if (!data || !group) return false;
+    if (!writeOptions.force && !canWrite()) return false;
+    group.writeCtrl(data, values);
+    return true;
+  }, [canWrite, mjDataRef]);
+  return useMemo(() => ({
+    owner,
+    group: groupRef,
+    conflicts: conflictsRef,
+    canWrite,
+    read,
+    write,
+    release
+  }), [canWrite, owner, read, release, write]);
+}
+var geomNameCacheByModel2 = /* @__PURE__ */ new WeakMap();
+var bodyNameCacheByModel = /* @__PURE__ */ new WeakMap();
+function getCachedName(cacheByModel, model, id, address) {
+  if (id < 0) return "";
+  let cache = cacheByModel.get(model);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    cacheByModel.set(model, cache);
+  }
+  let name = cache.get(id);
+  if (name === void 0) {
+    name = getName(model, address);
+    cache.set(id, name);
+  }
+  return name;
+}
+function matchesFilter(entry, bodyNames, geomNames, includeWorldBody) {
+  if (!includeWorldBody && (entry.body1 === 0 || entry.body2 === 0)) return false;
+  if (bodyNames && !bodyNames.includes(entry.body1Name) && !bodyNames.includes(entry.body2Name)) {
+    return false;
+  }
+  if (geomNames && !geomNames.includes(entry.geom1Name) && !geomNames.includes(entry.geom2Name)) {
+    return false;
+  }
+  return true;
+}
+function useContactHistory(options = {}) {
+  const entriesRef = useRef([]);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const clear = useCallback(() => {
+    entriesRef.current = [];
+  }, []);
+  const countPair = useCallback((nameA, nameB) => {
+    let count = 0;
+    for (const entry of entriesRef.current) {
+      const matchesBodies = entry.body1Name === nameA && entry.body2Name === nameB || entry.body1Name === nameB && entry.body2Name === nameA;
+      const matchesGeoms = entry.geom1Name === nameA && entry.geom2Name === nameB || entry.geom1Name === nameB && entry.geom2Name === nameA;
+      if (matchesBodies || matchesGeoms) count += 1;
+    }
+    return count;
+  }, []);
+  useAfterPhysicsStep(({ model, data }) => {
+    if ((data.ncon ?? 0) <= 0) return;
+    const {
+      maxLength = 2e3,
+      bodyNames,
+      geomNames,
+      includeWorldBody = false
+    } = optionsRef.current;
+    if (maxLength <= 0) return;
+    const nextEntries = [];
+    withContacts(data, (contacts) => {
+      for (let index = 0; index < data.ncon; index += 1) {
+        const contact = getContact(contacts, index);
+        if (!contact) break;
+        const body1 = model.geom_bodyid[contact.geom1] ?? -1;
+        const body2 = model.geom_bodyid[contact.geom2] ?? -1;
+        const entry = {
+          geom1: contact.geom1,
+          geom2: contact.geom2,
+          geom1Name: getCachedName(geomNameCacheByModel2, model, contact.geom1, model.name_geomadr[contact.geom1]),
+          geom2Name: getCachedName(geomNameCacheByModel2, model, contact.geom2, model.name_geomadr[contact.geom2]),
+          body1,
+          body2,
+          body1Name: body1 >= 0 ? getCachedName(bodyNameCacheByModel, model, body1, model.name_bodyadr[body1]) : "",
+          body2Name: body2 >= 0 ? getCachedName(bodyNameCacheByModel, model, body2, model.name_bodyadr[body2]) : "",
+          pos: [contact.pos[0], contact.pos[1], contact.pos[2]],
+          depth: contact.dist,
+          time: data.time
+        };
+        if (matchesFilter(entry, bodyNames, geomNames, includeWorldBody)) {
+          nextEntries.push(entry);
+        }
+      }
+    });
+    if (nextEntries.length === 0) return;
+    entriesRef.current.push(...nextEntries);
+    if (entriesRef.current.length > maxLength) {
+      entriesRef.current.splice(0, entriesRef.current.length - maxLength);
+    }
+  });
+  return {
+    entries: entriesRef,
+    clear,
+    countPair
+  };
+}
+function useKeyboardTeleop(config) {
+  const { mjModelRef, mjDataRef, status } = useMujocoContext();
+  const pressedRef = useRef(/* @__PURE__ */ new Set());
+  const toggleStateRef = useRef(/* @__PURE__ */ new Map());
   const enabledRef = useRef(config.enabled ?? true);
   enabledRef.current = config.enabled ?? true;
   const bindingsRef = useRef(config.bindings);
@@ -6119,29 +6501,114 @@ function useKeyboardIkTarget(config) {
     }
   });
 }
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function isPolicyActionChunk(value) {
+  return Array.isArray(value) && value.length > 0 && (Array.isArray(value[0]) || ArrayBuffer.isView(value[0]));
+}
+function toPolicyActions(output) {
+  return isPolicyActionChunk(output) ? [...output] : [output];
+}
+function enqueuePolicyActions(queue, actions, observation, strategy) {
+  if (strategy === "replace") {
+    queue.splice(0, queue.length);
+  }
+  queue.push(...actions.map((action) => ({ action, observation })));
+}
 function usePolicy(config) {
   const lastActionTimeRef = useRef(0);
   const lastObservationRef = useRef(null);
   const lastActionRef = useRef(null);
+  const actionQueueRef = useRef([]);
+  const inFlightRef = useRef(false);
+  const lastErrorRef = useRef(null);
+  const epochRef = useRef(0);
   const isRunningRef = useRef(config.enabled ?? true);
   const configRef = useRef(config);
   configRef.current = config;
   isRunningRef.current = config.enabled ?? isRunningRef.current;
+  const clearQueue = useCallback(() => {
+    epochRef.current += 1;
+    actionQueueRef.current.splice(0, actionQueueRef.current.length);
+    inFlightRef.current = false;
+    lastErrorRef.current = null;
+  }, []);
+  const reset = useCallback(() => {
+    clearQueue();
+    lastActionTimeRef.current = 0;
+    lastObservationRef.current = null;
+    lastActionRef.current = null;
+  }, [clearQueue]);
   useBeforePhysicsStep(({ model, data }) => {
     if (!isRunningRef.current) return;
     const cfg = configRef.current;
     model.opt?.timestep ?? 2e-3;
     const interval = 1 / cfg.frequency;
     if (data.time - lastActionTimeRef.current >= interval) {
+      const queuedAction = actionQueueRef.current.shift();
+      if (queuedAction) {
+        cfg.onAction({
+          action: queuedAction.action,
+          observation: queuedAction.observation,
+          model,
+          data
+        });
+        lastActionTimeRef.current = data.time;
+        lastActionRef.current = queuedAction.action;
+      }
+      const prefetchThreshold = cfg.prefetchThreshold ?? 0;
+      const shouldInfer = !inFlightRef.current && (!queuedAction || actionQueueRef.current.length <= prefetchThreshold);
+      if (!shouldInfer) return;
       const observation = cfg.onObservation({ model, data });
-      const action = cfg.infer ? cfg.infer({ observation, model, data }) : observation;
-      cfg.onAction({ action, observation, model, data });
+      const result = cfg.infer ? cfg.infer({ observation, model, data }) : observation;
+      if (isPromiseLike(result)) {
+        const epoch = epochRef.current;
+        inFlightRef.current = true;
+        result.then((output) => {
+          if (epoch !== epochRef.current) return;
+          enqueuePolicyActions(
+            actionQueueRef.current,
+            toPolicyActions(output),
+            observation,
+            cfg.queueStrategy ?? "append"
+          );
+          lastErrorRef.current = null;
+        }).catch((error) => {
+          if (epoch !== epochRef.current) return;
+          lastErrorRef.current = error;
+          cfg.onError?.(error);
+        }).finally(() => {
+          if (epoch !== epochRef.current) return;
+          inFlightRef.current = false;
+        });
+      } else {
+        const actions = toPolicyActions(result);
+        if (queuedAction) {
+          enqueuePolicyActions(
+            actionQueueRef.current,
+            actions,
+            observation,
+            cfg.queueStrategy ?? "append"
+          );
+        } else {
+          const [action, ...queuedActions] = actions;
+          if (!action) return;
+          enqueuePolicyActions(
+            actionQueueRef.current,
+            queuedActions,
+            observation,
+            cfg.queueStrategy ?? "append"
+          );
+          cfg.onAction({ action, observation, model, data });
+          lastActionRef.current = action;
+        }
+      }
       lastActionTimeRef.current = data.time;
       lastObservationRef.current = observation;
-      lastActionRef.current = action;
     }
   });
-  return {
+  return useMemo(() => ({
     get isRunning() {
       return isRunningRef.current;
     },
@@ -6150,15 +6617,304 @@ function usePolicy(config) {
     },
     stop: () => {
       isRunningRef.current = false;
+      if (configRef.current.clearQueueOnStop) reset();
+    },
+    clearQueue,
+    reset,
+    get inFlight() {
+      return inFlightRef.current;
+    },
+    get queuedActions() {
+      return actionQueueRef.current.length;
     },
     get lastObservation() {
       return lastObservationRef.current;
     },
     get lastAction() {
       return lastActionRef.current;
+    },
+    get lastError() {
+      return lastErrorRef.current;
     }
+  }), [clearQueue, reset]);
+}
+function now() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function isAbortError(error) {
+  return typeof DOMException !== "undefined" && error instanceof DOMException && error.name === "AbortError" || error instanceof Error && error.name === "AbortError";
+}
+function createAbortError(message) {
+  if (typeof DOMException !== "undefined") {
+    return new DOMException(message, "AbortError");
+  }
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
+}
+function abortController(controller, reason) {
+  if (!controller || controller.signal.aborted) return;
+  if (reason !== void 0) {
+    controller.abort(reason);
+  } else {
+    controller.abort();
+  }
+}
+function createMergedAbortSignal(localSignal, externalSignal) {
+  if (!externalSignal) return localSignal;
+  if (externalSignal.aborted) {
+    const controller2 = new AbortController();
+    abortController(controller2, externalSignal.reason);
+    return controller2.signal;
+  }
+  if (typeof AbortSignal !== "undefined" && typeof AbortSignal.any === "function") {
+    return AbortSignal.any([localSignal, externalSignal]);
+  }
+  const controller = new AbortController();
+  const abortFromLocal = () => abortController(controller, localSignal.reason);
+  const abortFromExternal = () => abortController(controller, externalSignal.reason);
+  localSignal.addEventListener("abort", abortFromLocal, { once: true });
+  externalSignal.addEventListener("abort", abortFromExternal, { once: true });
+  return controller.signal;
+}
+function vectorToArray(vector) {
+  return Array.from(vector, (value) => Number(value));
+}
+function isPolicyVectorArray(value) {
+  return Array.isArray(value) && value.every((entry) => Array.isArray(entry) || ArrayBuffer.isView(entry));
+}
+function isPolicyVector(value) {
+  return Array.isArray(value) || ArrayBuffer.isView(value);
+}
+function defaultBuildRemotePolicyRequest(input) {
+  const observation = vectorToArray(input.observation);
+  return {
+    observation,
+    state: observation,
+    time: input.data.time,
+    reset: input.reset
   };
 }
+async function defaultReadRemotePolicyResponse(response) {
+  const text = await response.text();
+  if (text.length === 0) return null;
+  return JSON.parse(text);
+}
+function defaultParseRemotePolicyResponse(responseBody) {
+  if (responseBody && typeof responseBody === "object") {
+    const body = responseBody;
+    if (typeof body.error === "string" && body.error.length > 0) {
+      throw new Error(body.error);
+    }
+    if (isPolicyVectorArray(body.actions) && body.actions.length > 0) {
+      return body.actions;
+    }
+    if (isPolicyVector(body.action)) {
+      return body.action;
+    }
+  }
+  if (isPolicyVectorArray(responseBody) && responseBody.length > 0) {
+    return responseBody;
+  }
+  if (isPolicyVector(responseBody)) {
+    return responseBody;
+  }
+  throw new Error("Remote policy response must include `action` or `actions`.");
+}
+function createHttpError(response, responseBody) {
+  const suffix = responseBody && typeof responseBody === "object" && "error" in responseBody ? `: ${String(responseBody.error)}` : "";
+  return new Error(`Remote policy request failed with HTTP ${response.status}${suffix}`);
+}
+function useRemotePolicy(config) {
+  const configRef = useRef(config);
+  configRef.current = config;
+  const requestCountRef = useRef(0);
+  const responseCountRef = useRef(0);
+  const remoteStatusRef = useRef("idle");
+  const lastRequestBodyRef = useRef(null);
+  const lastResponseBodyRef = useRef(null);
+  const lastHttpStatusRef = useRef(null);
+  const lastRequestMsRef = useRef(null);
+  const abortControllerRef = useRef(null);
+  const remoteEpochRef = useRef(0);
+  const policy = usePolicy({
+    ...config,
+    infer: async ({ observation, model, data }) => {
+      const cfg = configRef.current;
+      abortController(abortControllerRef.current, createAbortError("Remote policy request was superseded."));
+      const controller = new AbortController();
+      abortControllerRef.current = controller;
+      const signal = createMergedAbortSignal(controller.signal, cfg.signal);
+      const remoteEpoch = remoteEpochRef.current;
+      const requestIndex = requestCountRef.current;
+      const requestInput = {
+        observation,
+        model,
+        data,
+        reset: requestIndex === 0,
+        requestIndex,
+        signal
+      };
+      requestCountRef.current += 1;
+      const requestStartedAt = now();
+      const body = await (cfg.buildRequest?.(requestInput) ?? defaultBuildRemotePolicyRequest(requestInput));
+      signal.throwIfAborted();
+      if (remoteEpoch !== remoteEpochRef.current) {
+        throw createAbortError("Remote policy request was reset.");
+      }
+      lastRequestBodyRef.current = body;
+      remoteStatusRef.current = "requesting";
+      cfg.onRequest?.({
+        ...requestInput,
+        body,
+        requestStartedAt
+      });
+      let response = null;
+      let responseBody = null;
+      try {
+        const headers = new Headers(cfg.headers);
+        if (!headers.has("content-type")) {
+          headers.set("content-type", "application/json");
+        }
+        const fetcher = cfg.fetcher ?? fetch;
+        response = await fetcher(String(cfg.endpoint), {
+          ...cfg.requestInit,
+          method: cfg.method ?? "POST",
+          credentials: cfg.credentials,
+          headers,
+          signal,
+          body: typeof body === "string" ? body : JSON.stringify(body)
+        });
+        if (remoteEpoch === remoteEpochRef.current) {
+          lastHttpStatusRef.current = response.status;
+        }
+        responseBody = await (cfg.readResponse?.(response) ?? defaultReadRemotePolicyResponse(response));
+        signal.throwIfAborted();
+        if (remoteEpoch !== remoteEpochRef.current) {
+          throw createAbortError("Remote policy request was reset.");
+        }
+        lastResponseBodyRef.current = responseBody;
+        if (!response.ok) {
+          throw createHttpError(response, responseBody);
+        }
+        const responseFinishedAt = now();
+        const info = {
+          ...requestInput,
+          body,
+          requestStartedAt,
+          response,
+          responseBody,
+          responseFinishedAt,
+          requestMs: responseFinishedAt - requestStartedAt
+        };
+        if (remoteEpoch === remoteEpochRef.current) {
+          lastRequestMsRef.current = info.requestMs;
+          responseCountRef.current += 1;
+        }
+        cfg.onResponse?.(info);
+        const output = await (cfg.parseResponse?.(responseBody, info) ?? defaultParseRemotePolicyResponse(responseBody));
+        if (remoteEpoch === remoteEpochRef.current) {
+          remoteStatusRef.current = "ready";
+        }
+        return output;
+      } catch (error) {
+        if (response && remoteEpoch === remoteEpochRef.current) {
+          lastHttpStatusRef.current = response.status;
+        }
+        if (isAbortError(error) || signal.aborted) {
+          if (remoteEpoch === remoteEpochRef.current) {
+            remoteStatusRef.current = "aborted";
+          }
+          throw error;
+        }
+        if (remoteEpoch === remoteEpochRef.current) {
+          remoteStatusRef.current = "error";
+        }
+        throw error;
+      } finally {
+        if (abortControllerRef.current === controller) {
+          abortControllerRef.current = null;
+        }
+      }
+    }
+  });
+  return useMemo(() => {
+    const abort = (reason) => {
+      abortController(abortControllerRef.current, reason);
+      if (abortControllerRef.current) {
+        remoteStatusRef.current = "aborted";
+      }
+    };
+    const resetRemoteState = () => {
+      remoteEpochRef.current += 1;
+      abort(createAbortError("Remote policy request was reset."));
+      requestCountRef.current = 0;
+      responseCountRef.current = 0;
+      remoteStatusRef.current = "idle";
+      lastRequestBodyRef.current = null;
+      lastResponseBodyRef.current = null;
+      lastHttpStatusRef.current = null;
+      lastRequestMsRef.current = null;
+    };
+    return {
+      get isRunning() {
+        return policy.isRunning;
+      },
+      start: policy.start,
+      stop: () => {
+        if (configRef.current.abortOnStop ?? true) {
+          abort(createAbortError("Remote policy request was stopped."));
+        }
+        policy.stop();
+        if (configRef.current.clearQueueOnStop) {
+          resetRemoteState();
+        }
+      },
+      clearQueue: policy.clearQueue,
+      abort,
+      reset: () => {
+        resetRemoteState();
+        policy.reset();
+      },
+      get inFlight() {
+        return policy.inFlight;
+      },
+      get queuedActions() {
+        return policy.queuedActions;
+      },
+      get lastObservation() {
+        return policy.lastObservation;
+      },
+      get lastAction() {
+        return policy.lastAction;
+      },
+      get lastError() {
+        return policy.lastError;
+      },
+      get remoteStatus() {
+        return remoteStatusRef.current;
+      },
+      get requestCount() {
+        return requestCountRef.current;
+      },
+      get responseCount() {
+        return responseCountRef.current;
+      },
+      get lastRequestBody() {
+        return lastRequestBodyRef.current;
+      },
+      get lastResponseBody() {
+        return lastResponseBodyRef.current;
+      },
+      get lastHttpStatus() {
+        return lastHttpStatusRef.current;
+      },
+      get lastRequestMs() {
+        return lastRequestMsRef.current;
+      }
+    };
+  }, [policy]);
+}
 var EMPTY_OBSERVATION = {
   values: new Float32Array(0),
   layout: []
@@ -6179,6 +6935,134 @@ function useObservation(config) {
     }
   }), [mjDataRef, mjModelRef]);
 }
+
+// src/policyObservation.ts
+function pushValues(target, value, size) {
+  if (typeof value === "number") {
+    target.push(value);
+    for (let index = 1; index < size; index += 1) target.push(0);
+    return;
+  }
+  for (let index = 0; index < size; index += 1) {
+    target.push(Number(value[index] ?? 0));
+  }
+}
+function readNamedObservation(model, data, options) {
+  const values = [];
+  const layout = [];
+  const missing = options.missing ?? "skip";
+  for (const field of options.fields) {
+    const start = values.length;
+    const value = field.read({ model, data });
+    if (value === null || value === void 0) {
+      if (missing === "skip") continue;
+      if (missing === "throw") {
+        throw new Error(`Unable to read named observation field "${field.name}".`);
+      }
+      for (let index = 0; index < field.size; index += 1) values.push(0);
+    } else {
+      pushValues(values, value, field.size);
+    }
+    layout.push({
+      name: field.name,
+      start,
+      size: field.size,
+      units: field.units
+    });
+  }
+  return {
+    values: options.output === "float64" ? new Float64Array(values) : new Float32Array(values),
+    layout
+  };
+}
+function createNamedObservationBuilder(options) {
+  return (model, data) => readNamedObservation(model, data, options);
+}
+function qposField(name, index, units = "qpos") {
+  return {
+    name,
+    size: 1,
+    units,
+    read: ({ data }) => data.qpos[index]
+  };
+}
+function qvelField(name, index, units = "qvel") {
+  return {
+    name,
+    size: 1,
+    units,
+    read: ({ data }) => data.qvel[index]
+  };
+}
+function ctrlField(name, index, units = "ctrl") {
+  return {
+    name,
+    size: 1,
+    units,
+    read: ({ data }) => data.ctrl[index]
+  };
+}
+function bodyPositionField(name, units = "world_position") {
+  return {
+    name: `body:${name}:xpos`,
+    size: 3,
+    units,
+    read: ({ model, data }) => {
+      const bodyId = findBodyByName(model, name);
+      if (bodyId < 0) return null;
+      const offset = bodyId * 3;
+      return data.xpos.subarray(offset, offset + 3);
+    }
+  };
+}
+function geomPositionField(name, units = "world_position") {
+  return {
+    name: `geom:${name}:xpos`,
+    size: 3,
+    units,
+    read: ({ model, data }) => {
+      const geomId = findGeomByName(model, name);
+      if (geomId < 0) return null;
+      const offset = geomId * 3;
+      return data.geom_xpos.subarray(offset, offset + 3);
+    }
+  };
+}
+function sitePositionField(name, units = "world_position") {
+  return {
+    name: `site:${name}:xpos`,
+    size: 3,
+    units,
+    read: ({ model, data }) => {
+      const siteId = findSiteByName(model, name);
+      if (siteId < 0) return null;
+      const offset = siteId * 3;
+      return data.site_xpos.subarray(offset, offset + 3);
+    }
+  };
+}
+
+// src/hooks/useNamedObservation.ts
+var EMPTY_NAMED_OBSERVATION = {
+  values: new Float32Array(0),
+  layout: []
+};
+function useNamedObservation(options) {
+  const { mjModelRef, mjDataRef } = useMujocoContext();
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  return useMemo(() => ({
+    read() {
+      const model = mjModelRef.current;
+      const data = mjDataRef.current;
+      if (!model || !data) return EMPTY_NAMED_OBSERVATION;
+      return readNamedObservation(model, data, optionsRef.current);
+    },
+    readValues() {
+      return this.read().values;
+    }
+  }), [mjDataRef, mjModelRef]);
+}
 function useTrajectoryRecorder(options = {}) {
   const { mjModelRef } = useMujocoContext();
   const recordingRef = useRef(false);
@@ -6414,6 +7298,223 @@ function useCameraFrameCapture(defaultOptions = {}) {
     reset
   };
 }
+
+// src/policyCameraFrames.ts
+function addPolicyImageAliases(images, stream, frame, includeObservationImageAliases) {
+  const keys = /* @__PURE__ */ new Set();
+  keys.add(stream.key);
+  for (const alias of stream.aliases ?? []) keys.add(alias);
+  if (includeObservationImageAliases) {
+    keys.add(`observation.images.${stream.key}`);
+    for (const alias of stream.aliases ?? []) {
+      keys.add(`observation.images.${alias}`);
+    }
+  }
+  for (const key of keys) {
+    images[key] = frame.dataUrl;
+  }
+}
+function describeFrameSource(key, frame) {
+  return `${key}:${frame.source.kind}`;
+}
+function hasExplicitPolicyCameraSource(options) {
+  return Boolean(
+    options?.camera || options?.position || options?.quaternion || options?.source
+  );
+}
+function createPolicyCameraFrameCapturePlan(options) {
+  const {
+    cameraKeys,
+    defaults,
+    streamOptions,
+    includeObservationImageAliases,
+    requireAll,
+    ...sourceOptions
+  } = options;
+  const mountedPlan = createMountedCameraFrameSequencePlan(cameraKeys, {
+    ...sourceOptions,
+    defaults,
+    cameraOptions: streamOptions
+  });
+  const streams = [];
+  const missingKeys = new Set(mountedPlan.missingKeys);
+  for (const key of cameraKeys) {
+    const perStreamOptions = streamOptions?.[key];
+    if (hasExplicitPolicyCameraSource(perStreamOptions)) {
+      missingKeys.delete(key);
+      streams.push({
+        ...defaults,
+        ...perStreamOptions,
+        key,
+        aliases: perStreamOptions?.aliases
+      });
+      continue;
+    }
+    const mountedCamera = mountedPlan.cameras.find((camera) => camera.key === key);
+    if (!mountedCamera) continue;
+    const { key: _mountedKey, ...captureOptions } = mountedCamera;
+    streams.push({
+      ...captureOptions,
+      key,
+      aliases: perStreamOptions?.aliases
+    });
+  }
+  const result = {
+    cameraKeys: [...cameraKeys],
+    streams,
+    includeObservationImageAliases,
+    mountedPlan,
+    missingKeys: [...missingKeys]
+  };
+  if (requireAll && result.missingKeys.length > 0) {
+    throw new Error(
+      `Unable to resolve policy camera stream${result.missingKeys.length === 1 ? "" : "s"} for ${result.missingKeys.join(", ")}.`
+    );
+  }
+  return result;
+}
+function createPolicyCameraFrameCapturePlanFromApi(api, options) {
+  return createPolicyCameraFrameCapturePlan({
+    ...options,
+    cameras: api.getCameras(),
+    sites: api.getSites(),
+    bodies: api.getBodies()
+  });
+}
+async function capturePolicyCameraFrames(target, options) {
+  const includeObservationImageAliases = options.includeObservationImageAliases ?? true;
+  const entries = await Promise.all(
+    options.streams.map(async ({ key, aliases, ...captureOptions }) => {
+      const frame = await target.captureCameraFrame(captureOptions);
+      return [key, { frame, aliases }];
+    })
+  );
+  const frames = {};
+  const images = {};
+  const sourceParts = [];
+  for (const [key, { frame, aliases }] of entries) {
+    const stream = { key, aliases };
+    frames[key] = frame;
+    addPolicyImageAliases(
+      images,
+      stream,
+      frame,
+      includeObservationImageAliases
+    );
+    sourceParts.push(describeFrameSource(key, frame));
+  }
+  return {
+    frames,
+    images,
+    sourceSummary: sourceParts.length > 0 ? sourceParts.join(" + ") : "not used by policy",
+    capturedAt: Date.now()
+  };
+}
+async function capturePolicyCameraFramesFromMountedStreams(target, options) {
+  const plan = createPolicyCameraFrameCapturePlanFromApi(target, options);
+  const result = await capturePolicyCameraFrames(target, plan);
+  return { ...result, plan };
+}
+
+// src/hooks/usePolicyCameraFrames.ts
+function mergePolicyCameraFrameCaptureOptions(defaultOptions, options) {
+  return {
+    ...defaultOptions,
+    ...options,
+    cameraKeys: options.cameraKeys ?? defaultOptions.cameraKeys,
+    aliases: {
+      ...defaultOptions.aliases,
+      ...options.aliases
+    },
+    defaults: {
+      ...defaultOptions.defaults,
+      ...options.defaults
+    },
+    streamOptions: {
+      ...defaultOptions.streamOptions,
+      ...options.streamOptions
+    }
+  };
+}
+function usePolicyCameraFrames(defaultOptions) {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+  }, []);
+  const capture = useCallback(
+    async (options = {}) => {
+      if (!mujoco.api) {
+        throw new Error("MuJoCo scene is not ready for policy camera capture.");
+      }
+      setStatus("capturing");
+      setError(null);
+      try {
+        const result = await capturePolicyCameraFrames(mujoco.api, {
+          ...defaultOptions,
+          ...options,
+          streams: options.streams ?? defaultOptions.streams
+        });
+        setStatus("captured");
+        return result;
+      } catch (nextError) {
+        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture policy camera frames.");
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+  return {
+    status,
+    error,
+    isCapturing: status === "capturing",
+    capture,
+    reset
+  };
+}
+function usePolicyCameraFramesFromMountedStreams(defaultOptions) {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+  }, []);
+  const capture = useCallback(
+    async (options = {}) => {
+      if (!mujoco.api) {
+        throw new Error("MuJoCo scene is not ready for mounted policy camera capture.");
+      }
+      setStatus("capturing");
+      setError(null);
+      try {
+        const result = await capturePolicyCameraFramesFromMountedStreams(
+          mujoco.api,
+          mergePolicyCameraFrameCaptureOptions(defaultOptions, options)
+        );
+        setStatus("captured");
+        return result;
+      } catch (nextError) {
+        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture mounted policy camera frames.");
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+  return {
+    status,
+    error,
+    isCapturing: status === "capturing",
+    capture,
+    reset
+  };
+}
 function useCameraSequenceRecorder() {
   const mujoco = useMujoco();
   const [status, setStatus] = useState("idle");
@@ -6534,6 +7635,38 @@ function useMountedCameraSequenceRecorder(defaultOptions = {}) {
     reset
   };
 }
+
+// src/policyControls.ts
+function clampPolicyActionValue(model, actuatorIndex, value) {
+  const ranges = model.actuator_ctrlrange;
+  const min = ranges?.[actuatorIndex * 2] ?? -Infinity;
+  const max = ranges?.[actuatorIndex * 2 + 1] ?? Infinity;
+  return Math.max(min, Math.min(max, value));
+}
+function applyPolicyActionToControls(model, data, action, options = {}) {
+  const actuatorOffset = options.actuatorOffset ?? 0;
+  const actionSize = options.actionSize ?? action.length;
+  const shouldClamp = options.clamp ?? true;
+  const shouldSkipInvalid = options.skipInvalid ?? true;
+  const count = Math.max(
+    0,
+    Math.min(actionSize, action.length, data.ctrl.length - actuatorOffset, model.nu - actuatorOffset)
+  );
+  const applied = [];
+  const skipped = [];
+  for (let index = 0; index < count; index += 1) {
+    const actuatorIndex = actuatorOffset + index;
+    const value = Number(action[index]);
+    if (shouldSkipInvalid && !Number.isFinite(value)) {
+      skipped.push(actuatorIndex);
+      continue;
+    }
+    const nextValue = shouldClamp ? clampPolicyActionValue(model, actuatorIndex, value) : value;
+    data.ctrl[actuatorIndex] = nextValue;
+    applied.push(nextValue);
+  }
+  return { applied, skipped, actuatorOffset };
+}
 function useCtrlNoise(config = {}) {
   const { mjModelRef } = useMujocoContext();
   const configRef = useRef(config);
@@ -6628,8 +7761,8 @@ function useCameraAnimation() {
   useFrame((state) => {
     const ca = cameraAnimRef.current;
     if (!ca.active) return;
-    const now = performance.now();
-    const progress = Math.min((now - ca.startTime) / ca.duration, 1);
+    const now2 = performance.now();
+    const progress = Math.min((now2 - ca.startTime) / ca.duration, 1);
     const ease = progress < 0.5 ? 4 * progress * progress * progress : 1 - Math.pow(-2 * progress + 2, 3) / 2;
     camera.position.lerpVectors(ca.startPos, ca.endPos, ease);
     camera.quaternion.slerpQuaternions(ca.startRot, ca.endRot, ease);
@@ -6698,6 +7831,12 @@ function useCameraAnimation() {
  *
  * Helpers for resolving dataset camera streams to mounted MuJoCo resources.
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Project detector/image coordinates from a camera view into the rendered MuJoCo scene.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -6795,12 +7934,30 @@ function useCameraAnimation() {
  *
  * useBodyState — per-body position/velocity tracking (spec 2.2)
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Ref-based world pose hooks for named MuJoCo bodies, geoms, and sites.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
  * useCtrl — handle-based read/write access to a named actuator's ctrl value (spec 3.1)
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Cooperative actuator/control ownership for policies, IK, teleop, and replay.
+ */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Bounded contact history for rollout verification and debugging.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -6813,6 +7970,24 @@ function useCameraAnimation() {
  *
  * usePolicy — policy decimation loop hook (spec 10.1)
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useRemotePolicy — HTTP JSON inference wrapper around usePolicy.
+ */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Named policy observation builders with layout and units metadata.
+ */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Stable React handle for named policy observations.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -6837,6 +8012,18 @@ function useCameraAnimation() {
  *
  * React state wrapper around MuJoCo/R3F offscreen camera-frame capture.
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Helpers for turning Three/MuJoCo camera captures into policy image payloads.
+ */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * React wrapper for capturing policy image payloads from Three/MuJoCo cameras.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -6849,6 +8036,12 @@ function useCameraAnimation() {
  *
  * React state wrapper for named MuJoCo camera/site/body sequence recording.
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Helpers for applying policy action vectors to MuJoCo controls.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -6879,6 +8072,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, InstancedGeomRenderer, MountedCameraFrameSequenceManifestStatus, MountedCameraFrameSequenceReadinessStatus, MountedCameraFrameSourceSuggestionMatch, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, SplatCollisionProxyPreview, TendonRenderer, TrajectoryPlayer, buildObservation, canFetchSplatCollisionProxyXml, captureFrame, captureFrameBlob, createContiguousControlGroup, createController, createControllerHook, createMountedCameraFrameSequenceManifest, createMountedCameraFrameSequencePlan, createMountedCameraFrameSequencePlanFromApi, createMountedCameraFrameSequenceReadiness, createMountedCameraFrameSourceSuggestions, fetchSplatCollisionProxyXml, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getCameraFrameCaptureSourceTarget, getControlMap, getMountedCameraFrameCaptureSource, getName, isMountedCameraFrameCaptureSource, loadScene, parseSplatCollisionProxyGeoms, recordMountedCameraFrameSequence, resolveControlGroup, resolveMountedCameraFrameSource, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useContactEvents, useContacts, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardIkTarget, useKeyboardTeleop, useMountedCameraSequenceRecorder, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useSplatCollisionProxyGeoms, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, InstancedGeomRenderer, MountedCameraFrameSequenceManifestStatus, MountedCameraFrameSequenceReadinessStatus, MountedCameraFrameSourceSuggestionMatch, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, SplatCollisionProxyPreview, TendonRenderer, TrajectoryPlayer, applyPolicyActionToControls, bodyPositionField, buildObservation, canFetchSplatCollisionProxyXml, captureFrame, captureFrameBlob, capturePolicyCameraFrames, capturePolicyCameraFramesFromMountedStreams, clampPolicyActionValue, createContiguousControlGroup, createController, createControllerHook, createMountedCameraFrameSequenceManifest, createMountedCameraFrameSequencePlan, createMountedCameraFrameSequencePlanFromApi, createMountedCameraFrameSequenceReadiness, createMountedCameraFrameSourceSuggestions, createNamedObservationBuilder, createPolicyCameraFrameCapturePlan, createPolicyCameraFrameCapturePlanFromApi, ctrlField, fetchSplatCollisionProxyXml, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, geomPositionField, getActuatedJoints, getCameraFrameCaptureSourceTarget, getControlMap, getMountedCameraFrameCaptureSource, getName, imagePointToNdc, isMountedCameraFrameCaptureSource, loadScene, parseSplatCollisionProxyGeoms, projectImagePointTo3D, qposField, qvelField, readNamedObservation, recordMountedCameraFrameSequence, resolveControlGroup, resolveMountedCameraFrameSource, sitePositionField, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyPose, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useContactEvents, useContactHistory, useContacts, useControlWriter, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGeomPose, useGravityCompensation, useIkController, useJointState, useKeyboardIkTarget, useKeyboardTeleop, useMountedCameraSequenceRecorder, useMujoco, useMujocoWasm, useNamedObservation, useObservation, usePolicy, usePolicyCameraFrames, usePolicyCameraFramesFromMountedStreams, useRemotePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePose, useSitePosition, useSplatCollisionProxyGeoms, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map