mujoco-react 12.0.0 → 12.1.0

package/dist/index.js

@@ -1,5 +1,6 @@
-import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, createCaptureCamera, prepareCaptureCamera } from './chunk-7BCIHJMW.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-7BCIHJMW.js';
+import { displayFields } from './chunk-U2Y2BODT.js';
+import { withContacts, getContact, captureCameraFrame, captureCameraFrameBlob, createCameraFrameCaptureSession, CAMERA_FRAME_CAPTURE_PRE_RENDER_USER_DATA_KEY, CAPTURE_EXCLUDE_KEY, createCaptureCamera, prepareCaptureCamera } from './chunk-XD3AY7XZ.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-XD3AY7XZ.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';
@@ -975,939 +976,1322 @@ 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;
-var GeomBuilder = class {
-  mujoco;
-  textureCache = /* @__PURE__ */ new Map();
-  renderOptions;
-  constructor(mujoco, renderOptions) {
-    this.mujoco = mujoco;
-    this.renderOptions = renderOptions;
+// src/core/sceneIdentity.ts
+var fileIds = /* @__PURE__ */ new WeakMap();
+var nextFileId = 0;
+function sceneIdentity(config) {
+  return JSON.stringify([
+    config.src,
+    config.sceneFile,
+    config.environmentFiles ?? [],
+    config.sceneObjects ?? [],
+    config.homeJoints ?? [],
+    config.xmlPatches ?? [],
+    (config.files ?? []).map((file) => {
+      if (!fileIds.has(file)) fileIds.set(file, ++nextFileId);
+      return fileIds.get(file);
+    })
+  ], (_key, value) => value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value);
+}
+
+// src/core/stepBudget.ts
+function runStepBudget(requested, step, budgetMs = 8, now2 = () => performance.now()) {
+  if (!Number.isFinite(budgetMs) || budgetMs <= 0) throw new Error("physicsBudgetMs must be positive and finite");
+  const start = now2();
+  let steps = 0;
+  while (steps < requested && steps < 100) {
+    step();
+    steps++;
+    if (now2() - start >= budgetMs) break;
+  }
+  return { steps, physicsMs: now2() - start, budgetExceeded: steps < requested };
+}
+
+// src/rendering/cameraFrameSource.ts
+var MountedCameraFrameSourceSuggestionMatch = {
+  Direct: "direct",
+  Alias: "alias",
+  Normalized: "normalized",
+  Prefix: "prefix",
+  Suffix: "suffix",
+  Contains: "contains"
+};
+var MountedCameraFrameSequenceReadinessStatus = {
+  Ready: "ready",
+  Partial: "partial",
+  Missing: "missing"
+};
+var MountedCameraFrameSequenceManifestStatus = {
+  Complete: "complete",
+  Partial: "partial",
+  Missing: "missing"
+};
+function getResourceName(resource) {
+  if (!resource) return null;
+  return typeof resource === "string" ? resource : resource.name ?? null;
+}
+function createNameSet(resources) {
+  return new Set(
+    (resources ?? []).map((resource) => getResourceName(resource)).filter((name) => Boolean(name))
+  );
+}
+function createResourceNames(resources) {
+  return (resources ?? []).map((resource) => getResourceName(resource)).filter((name) => Boolean(name));
+}
+function normalizeAliasCandidates(value) {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+function countMountedSelectors(selector) {
+  return Number(Boolean(selector.cameraName)) + Number(Boolean(selector.siteName)) + Number(Boolean(selector.bodyName));
+}
+function normalizeCameraSourceName(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function createCameraSourceKeyVariants(key) {
+  const candidates = [
+    key,
+    key.startsWith("observation.images.") ? key.slice("observation.images.".length) : "",
+    key.includes(".") ? key.split(".").at(-1) ?? "" : "",
+    key.includes("/") ? key.split("/").at(-1) ?? "" : ""
+  ];
+  return candidates.map((candidate) => candidate.trim()).filter((candidate, index, items) => candidate && items.indexOf(candidate) === index);
+}
+function getSelectorKey(selector) {
+  if (selector.cameraName) return `camera:${selector.cameraName}`;
+  if (selector.siteName) return `site:${selector.siteName}`;
+  if (selector.bodyName) return `body:${selector.bodyName}`;
+  return null;
+}
+function getMountedCameraFrameCaptureSource(selector) {
+  if (countMountedSelectors(selector) !== 1) return null;
+  if (selector.cameraName) {
+    return { kind: "mujoco-camera", cameraName: selector.cameraName };
   }
-  getMeshNormalSmoothingTolerance() {
-    const smoothing = this.renderOptions?.meshNormalSmoothing;
-    if (!smoothing) return null;
-    if (smoothing === true) return DEFAULT_MESH_NORMAL_SMOOTHING_TOLERANCE;
-    return smoothing.tolerance ?? DEFAULT_MESH_NORMAL_SMOOTHING_TOLERANCE;
+  if (selector.siteName) {
+    return { kind: "mujoco-site", siteName: selector.siteName };
   }
-  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 (selector.bodyName) {
+    return { kind: "mujoco-body", bodyName: selector.bodyName };
+  }
+  return null;
+}
+function isMountedCameraFrameCaptureSource(source) {
+  return source.kind === "mujoco-camera" || source.kind === "mujoco-site" || source.kind === "mujoco-body";
+}
+function getCameraFrameCaptureSourceTarget(source) {
+  if (source.kind === "mujoco-camera") return source.cameraName;
+  if (source.kind === "mujoco-site") return source.siteName;
+  if (source.kind === "mujoco-body") return source.bodyName;
+  if (source.kind === "custom-camera") return "custom camera";
+  if (source.kind === "explicit-pose") return "explicit pose";
+  return "fallback camera";
+}
+function createMountedCameraFrameSourceSuggestion(key, selector, resourceName, match) {
+  const source = getMountedCameraFrameCaptureSource(selector);
+  if (!source) return null;
+  return {
+    key,
+    selector,
+    source,
+    resourceName,
+    resourceKind: source.kind,
+    match
+  };
+}
+function addMountedCameraFrameSourceSuggestion(suggestions, seen, suggestion) {
+  if (!suggestion) return;
+  const selectorKey = getSelectorKey(suggestion.selector);
+  if (!selectorKey || seen.has(selectorKey)) return;
+  seen.add(selectorKey);
+  suggestions.push(suggestion);
+}
+function getCameraFrameResourceMatch(key, resourceName) {
+  if (resourceName === key) return MountedCameraFrameSourceSuggestionMatch.Direct;
+  const normalizedResource = normalizeCameraSourceName(resourceName);
+  if (!normalizedResource) return null;
+  for (const variant of createCameraSourceKeyVariants(key)) {
+    if (resourceName === variant) return MountedCameraFrameSourceSuggestionMatch.Direct;
+    const normalizedKey = normalizeCameraSourceName(variant);
+    if (!normalizedKey) continue;
+    if (normalizedResource === normalizedKey) {
+      return MountedCameraFrameSourceSuggestionMatch.Normalized;
     }
-    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;
+    if (normalizedResource.startsWith(`${normalizedKey}_`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Prefix;
+    }
+    if (normalizedResource.endsWith(`_${normalizedKey}`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Suffix;
+    }
+    if (normalizedResource.includes(`_${normalizedKey}_`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Contains;
     }
-    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;
-    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 THREE12.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];
+  return null;
+}
+function isSelectorMounted(selector, cameraNames, siteNames, bodyNames) {
+  if (countMountedSelectors(selector) !== 1) return false;
+  return (selector.cameraName ? cameraNames.has(selector.cameraName) : false) || (selector.siteName ? siteNames.has(selector.siteName) : false) || (selector.bodyName ? bodyNames.has(selector.bodyName) : false);
+}
+function createMountedCameraFrameSourceSuggestions(key, options) {
+  const cameraNames = createNameSet(options.cameras);
+  const siteNames = createNameSet(options.sites);
+  const bodyNames = createNameSet(options.bodies);
+  const suggestions = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const selector of normalizeAliasCandidates(options.aliases?.[key])) {
+    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
+      continue;
     }
-    const MG = this.mujoco.mjtGeom;
-    let geo = null;
-    const getVal = (v) => v?.value ?? v;
-    if (type === getVal(MG.mjGEOM_PLANE)) {
-      geo = new THREE12.PlaneGeometry(size[0] * 2 || 5, size[1] * 2 || 5);
-    } else if (type === getVal(MG.mjGEOM_SPHERE)) {
-      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 THREE12.BoxGeometry(size[0] * 2, size[1] * 2, size[2] * 2);
-    } else if (type === getVal(MG.mjGEOM_CYLINDER)) {
-      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];
-      const vAdr = mjModel.mesh_vertadr[mId];
-      const vNum = mjModel.mesh_vertnum[mId];
-      const fAdr = mjModel.mesh_faceadr[mId];
-      const fNum = mjModel.mesh_facenum[mId];
-      const tAdr = mjModel.mesh_texcoordadr?.[mId] ?? -1;
-      if (map && tAdr >= 0 && mjModel.mesh_texcoord && mjModel.mesh_facetexcoord) {
-        const corners = fNum * 3;
-        const positions = new Float32Array(corners * 3);
-        const uvs = new Float32Array(corners * 2);
-        for (let c = 0; c < corners; c++) {
-          const v = vAdr + mjModel.mesh_face[fAdr * 3 + c];
-          positions[c * 3] = mjModel.mesh_vert[v * 3];
-          positions[c * 3 + 1] = mjModel.mesh_vert[v * 3 + 1];
-          positions[c * 3 + 2] = mjModel.mesh_vert[v * 3 + 2];
-          const t = tAdr + mjModel.mesh_facetexcoord[fAdr * 3 + c];
-          uvs[c * 2] = mjModel.mesh_texcoord[t * 2];
-          uvs[c * 2 + 1] = 1 - mjModel.mesh_texcoord[t * 2 + 1];
-        }
-        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 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) {
-          geo = mergeVertices(geo, smoothingTolerance);
-        }
-        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 THREE12.Mesh(geo, new THREE12.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;
+    const source = getMountedCameraFrameCaptureSource(selector);
+    if (!source) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        selector,
+        getCameraFrameCaptureSourceTarget(source),
+        MountedCameraFrameSourceSuggestionMatch.Alias
+      )
+    );
   }
-};
-function getRenderOptionsKey(renderOptions) {
-  const smoothing = renderOptions?.meshNormalSmoothing;
-  if (!smoothing) return "default";
-  if (smoothing === true) return "meshNormalSmoothing:true";
-  return `meshNormalSmoothing:${smoothing.tolerance ?? "default"}`;
+  for (const cameraName of createResourceNames(options.cameras)) {
+    const match = getCameraFrameResourceMatch(key, cameraName);
+    if (!match) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        { cameraName },
+        cameraName,
+        match
+      )
+    );
+  }
+  for (const siteName of createResourceNames(options.sites)) {
+    const match = getCameraFrameResourceMatch(key, siteName);
+    if (!match) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        { siteName },
+        siteName,
+        match
+      )
+    );
+  }
+  for (const bodyName of createResourceNames(options.bodies)) {
+    const match = getCameraFrameResourceMatch(key, bodyName);
+    if (!match) continue;
+    addMountedCameraFrameSourceSuggestion(
+      suggestions,
+      seen,
+      createMountedCameraFrameSourceSuggestion(
+        key,
+        { bodyName },
+        bodyName,
+        match
+      )
+    );
+  }
+  return suggestions;
 }
-function SceneRenderer({ renderOptions, ...props }) {
-  const {
-    mjModelRef,
-    mjDataRef,
-    mujocoRef,
-    onSelectionRef,
-    hiddenBodiesRef,
-    hiddenBodiesVersion,
-    interpolateRef,
-    interpolationStateRef,
-    status
-  } = useMujocoContext();
-  const groupRef = useRef(null);
-  const bodyRefs = useRef([]);
-  const prevModelRef = useRef(null);
-  const prevRenderOptionsKeyRef = useRef(null);
-  const prevHiddenVersionRef = useRef(null);
-  const renderOptionsKey = getRenderOptionsKey(renderOptions);
-  const geomBuilder = useMemo(() => {
-    if (status !== "ready") return null;
-    return new GeomBuilder(mujocoRef.current, renderOptions);
-  }, [status, mujocoRef, renderOptionsKey]);
-  useEffect(() => {
-    if (status !== "ready" || !geomBuilder) return;
-    const model = mjModelRef.current;
-    const group = groupRef.current;
-    if (!model || !group) return;
-    if (prevModelRef.current === model && prevRenderOptionsKeyRef.current === renderOptionsKey && prevHiddenVersionRef.current === hiddenBodiesVersion) {
-      return;
-    }
-    prevModelRef.current = model;
-    prevRenderOptionsKeyRef.current = renderOptionsKey;
-    prevHiddenVersionRef.current = hiddenBodiesVersion;
-    while (group.children.length > 0) {
-      group.remove(group.children[0]);
-    }
-    const refs = [];
-    for (let i = 0; i < model.nbody; i++) {
-      const bodyGroup = new THREE12.Group();
-      bodyGroup.userData.bodyID = i;
-      const bodyName = getName(model, model.name_bodyadr[i]);
-      if (!hiddenBodiesRef.current.has(bodyName)) {
-        for (let g = 0; g < model.ngeom; g++) {
-          if (model.geom_bodyid[g] === i) {
-            const mesh = geomBuilder.create(model, g);
-            if (mesh) bodyGroup.add(mesh);
-          }
-        }
-      }
-      group.add(bodyGroup);
-      refs.push(bodyGroup);
-    }
-    bodyRefs.current = refs;
-  }, [status, geomBuilder, mjModelRef, renderOptionsKey, hiddenBodiesRef, hiddenBodiesVersion]);
-  const syncBodiesToData = useCallback(() => {
-    const data = mjDataRef.current;
-    if (!data) return;
-    const bodies = bodyRefs.current;
-    const interpolation = interpolationStateRef.current;
-    const useInterpolation = interpolateRef.current && interpolation.valid;
-    for (let i = 0; i < bodies.length; i++) {
-      const ref = bodies[i];
-      if (!ref) continue;
-      if (useInterpolation) {
-        const alpha = interpolation.alpha;
-        const i3 = i * 3;
-        ref.position.set(
-          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(
-          interpolation.previousXquat[i4 + 1],
-          interpolation.previousXquat[i4 + 2],
-          interpolation.previousXquat[i4 + 3],
-          interpolation.previousXquat[i4]
-        );
-        _currentQuat.set(
-          interpolation.currentXquat[i4 + 1],
-          interpolation.currentXquat[i4 + 2],
-          interpolation.currentXquat[i4 + 3],
-          interpolation.currentXquat[i4]
-        );
-        ref.quaternion.copy(_previousQuat).slerp(_currentQuat, alpha);
-      } else {
-        ref.position.set(
-          data.xpos[i * 3],
-          data.xpos[i * 3 + 1],
-          data.xpos[i * 3 + 2]
-        );
-        ref.quaternion.set(
-          data.xquat[i * 4 + 1],
-          data.xquat[i * 4 + 2],
-          data.xquat[i * 4 + 3],
-          data.xquat[i * 4]
-        );
-      }
-    }
-  }, [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();
-        let obj = e.object;
-        while (obj && obj.userData.bodyID === void 0 && obj.parent) {
-          obj = obj.parent;
-        }
-        const bodyID = obj?.userData.bodyID;
-        if (typeof bodyID === "number" && bodyID > 0) {
-          const model = mjModelRef.current;
-          if (model && bodyID < model.nbody && onSelectionRef.current) {
-            const name = getName(model, model.name_bodyadr[bodyID]);
-            onSelectionRef.current({ bodyId: bodyID, name });
-          }
-        }
-      }
+function resolveMountedCameraFrameSource(key, options) {
+  const cameraNames = createNameSet(options.cameras);
+  const siteNames = createNameSet(options.sites);
+  const bodyNames = createNameSet(options.bodies);
+  const directCandidates = [
+    { cameraName: key },
+    { siteName: key },
+    { bodyName: key }
+  ];
+  const aliasCandidates = normalizeAliasCandidates(options.aliases?.[key]);
+  for (const selector of aliasCandidates) {
+    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
+      continue;
     }
-  );
-}
-var _previousQuat = new THREE12.Quaternion();
-var _currentQuat = new THREE12.Quaternion();
-var CameraViewportRegistryContext = createContext(null);
-var nextViewportId = 0;
-var VIEWPORT_RENDER_PRIORITY = 1;
-function CameraViewportRenderer({
-  viewportsRef
-}) {
-  const gl = useThree((state) => state.gl);
-  const scene = useThree((state) => state.scene);
-  const mainCamera = useThree((state) => state.camera);
-  const mujoco = useMujoco();
-  useFrame(() => {
-    const drawWidth = gl.domElement.width;
-    const drawHeight = gl.domElement.height;
-    gl.setScissorTest(false);
-    gl.setViewport(0, 0, drawWidth, drawHeight);
-    gl.render(scene, mainCamera);
-    const api = mujoco.api;
-    if (!api || viewportsRef.current.size === 0) return;
-    const dpr = gl.getPixelRatio();
-    const canvasRect = gl.domElement.getBoundingClientRect();
-    for (const descriptor of viewportsRef.current.values()) {
-      const element = descriptor.getElement();
-      if (!element) continue;
-      const rect = element.getBoundingClientRect();
-      const isOffscreen = rect.bottom < canvasRect.top || rect.top > canvasRect.bottom || rect.right < canvasRect.left || rect.left > canvasRect.right;
-      if (isOffscreen) continue;
-      const width = Math.floor(rect.width * dpr);
-      const height = Math.floor(rect.height * dpr);
-      if (width <= 0 || height <= 0) continue;
-      const left = Math.floor((rect.left - canvasRect.left) * dpr);
-      const bottom = Math.floor((canvasRect.bottom - rect.bottom) * dpr);
-      let resolved;
-      try {
-        resolved = api.resolveCameraCaptureOptions(descriptor.getOptions());
-      } catch {
-        continue;
-      }
-      if (!descriptor.camera) {
-        descriptor.camera = createCaptureCamera(resolved, mainCamera, width, height);
-      } else {
-        prepareCaptureCamera(descriptor.camera, resolved, mainCamera, width, height);
-      }
-      gl.setViewport(left, bottom, width, height);
-      gl.setScissor(left, bottom, width, height);
-      gl.setScissorTest(true);
-      gl.render(scene, descriptor.camera);
+    const source = getMountedCameraFrameCaptureSource(selector);
+    if (!source) continue;
+    return { key, selector, source };
+  }
+  const [suggestion] = createMountedCameraFrameSourceSuggestions(key, options);
+  if (suggestion) {
+    return {
+      key,
+      selector: suggestion.selector,
+      source: suggestion.source
+    };
+  }
+  if (options.allowAliasFallback) {
+    for (const selector of aliasCandidates) {
+      const source = getMountedCameraFrameCaptureSource(selector);
+      if (!source) continue;
+      return { key, selector, source };
     }
-    gl.setScissorTest(false);
-    gl.setViewport(0, 0, drawWidth, drawHeight);
-  }, VIEWPORT_RENDER_PRIORITY);
+  }
+  for (const selector of directCandidates) {
+    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
+      continue;
+    }
+    const source = getMountedCameraFrameCaptureSource(selector);
+    if (!source) continue;
+    return { key, selector, source };
+  }
   return null;
 }
-function CameraViewportProvider({ children }) {
-  const viewportsRef = useRef(/* @__PURE__ */ new Map());
-  const [count, setCount] = useState(0);
-  const register = useCallback((descriptor) => {
-    const id = nextViewportId++;
-    viewportsRef.current.set(id, descriptor);
-    setCount((value2) => value2 + 1);
-    return () => {
-      viewportsRef.current.delete(id);
-      setCount((value2) => value2 - 1);
-    };
-  }, []);
-  const value = useMemo(() => ({ register }), [register]);
-  return /* @__PURE__ */ jsxs(CameraViewportRegistryContext.Provider, { value, children: [
-    children,
-    count > 0 && /* @__PURE__ */ jsx(CameraViewportRenderer, { viewportsRef })
-  ] });
-}
-function useCameraViewport(elementRef, options) {
-  const registry = useContext(CameraViewportRegistryContext);
-  if (!registry) {
-    throw new Error("useCameraViewport must be used inside <MujocoCanvas>.");
+function createMountedCameraFrameSequencePlan(cameraKeys, options) {
+  const cameras = [];
+  const resolved = {};
+  const missingKeys = [];
+  for (const key of cameraKeys) {
+    const mountedSource = resolveMountedCameraFrameSource(key, options);
+    if (!mountedSource) {
+      missingKeys.push(key);
+      continue;
+    }
+    resolved[key] = mountedSource;
+    cameras.push({
+      key,
+      ...options.defaults,
+      ...options.cameraOptions?.[key],
+      ...mountedSource.selector,
+      source: mountedSource.source
+    });
   }
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-  useEffect(() => {
-    const descriptor = {
-      getElement: () => elementRef.current,
-      getOptions: () => optionsRef.current,
-      camera: null
-    };
-    return registry.register(descriptor);
-  }, [registry, elementRef]);
+  if (options.requireAll && missingKeys.length > 0) {
+    throw new Error(
+      `Unable to resolve mounted MuJoCo camera source${missingKeys.length === 1 ? "" : "s"} for ${missingKeys.join(", ")}.`
+    );
+  }
+  return {
+    cameraKeys: [...cameraKeys],
+    cameras,
+    resolved,
+    missingKeys
+  };
 }
-function CameraView({ className, style, ...options }) {
-  const gl = useThree((state) => state.gl);
-  const elementRef = useRef(null);
-  if (!elementRef.current && typeof document !== "undefined") {
-    elementRef.current = document.createElement("div");
+function createMountedCameraFrameSequenceReadiness(plan) {
+  const cameras = {};
+  const resolvedKeys = plan.cameraKeys.filter((key) => Boolean(plan.resolved[key]));
+  for (const key of plan.cameraKeys) {
+    const resolved = plan.resolved[key];
+    cameras[key] = resolved ? {
+      key,
+      ready: true,
+      selector: resolved.selector,
+      source: resolved.source,
+      message: `Camera stream "${key}" resolves to ${resolved.source.kind}:${getCameraFrameCaptureSourceTarget(resolved.source)}.`
+    } : {
+      key,
+      ready: false,
+      message: `Camera stream "${key}" does not resolve to a mounted MuJoCo camera, site, or body.`
+    };
   }
-  useEffect(() => {
-    const element = elementRef.current;
-    const parent = gl.domElement.parentElement;
-    if (!element || !parent) return;
-    element.style.position = "absolute";
-    element.style.overflow = "hidden";
-    parent.appendChild(element);
-    return () => {
-      parent.removeChild(element);
+  const missingKeys = [...plan.missingKeys];
+  const ready = missingKeys.length === 0;
+  const status = ready ? MountedCameraFrameSequenceReadinessStatus.Ready : resolvedKeys.length > 0 ? MountedCameraFrameSequenceReadinessStatus.Partial : MountedCameraFrameSequenceReadinessStatus.Missing;
+  return {
+    ready,
+    status,
+    cameraKeys: [...plan.cameraKeys],
+    resolvedKeys,
+    missingKeys,
+    cameras,
+    message: ready ? `All ${plan.cameraKeys.length} requested camera stream${plan.cameraKeys.length === 1 ? "" : "s"} resolve to mounted MuJoCo sources.` : `Missing mounted MuJoCo source${missingKeys.length === 1 ? "" : "s"} for ${missingKeys.join(", ")}.`
+  };
+}
+function normalizeFrameCount(frameCount) {
+  return Number.isFinite(frameCount) && frameCount !== void 0 ? Math.max(0, Math.floor(frameCount)) : 0;
+}
+function createMountedCameraFrameSequenceManifest(result, options = {}) {
+  const cameraKeys = [
+    ...options.cameraKeys ?? result.readiness.cameraKeys ?? result.plan.cameraKeys ?? result.cameraKeys
+  ];
+  const expectedFrameCount = normalizeFrameCount(
+    options.expectedFrameCount ?? result.frameCount
+  );
+  const recordedFrameCount = normalizeFrameCount(result.frameCount);
+  const streamSummaries = {};
+  const streams = [];
+  let missingFrameCount = 0;
+  let completeStreamCount = 0;
+  let resolvedOrRecordedStreamCount = 0;
+  for (const key of cameraKeys) {
+    const summary = result.cameraSummaries[key];
+    const readiness = result.readiness.cameras[key];
+    const source = summary?.source ?? readiness?.source;
+    const ready = readiness?.ready ?? Boolean(summary);
+    const recorded = normalizeFrameCount(summary?.frameCount);
+    const missing = Math.max(expectedFrameCount - recorded, 0);
+    const complete2 = ready && missing === 0;
+    const status2 = complete2 ? MountedCameraFrameSequenceManifestStatus.Complete : ready || recorded > 0 ? MountedCameraFrameSequenceManifestStatus.Partial : MountedCameraFrameSequenceManifestStatus.Missing;
+    const target = source ? getCameraFrameCaptureSourceTarget(source) : readiness?.message ? void 0 : "missing MuJoCo camera";
+    const message = complete2 ? `Camera stream "${key}" recorded ${recorded} of ${expectedFrameCount} frame${expectedFrameCount === 1 ? "" : "s"}.` : ready || recorded > 0 ? `Camera stream "${key}" recorded ${recorded} of ${expectedFrameCount} frame${expectedFrameCount === 1 ? "" : "s"}.` : readiness?.message ?? `Camera stream "${key}" did not record any frames.`;
+    const stream = {
+      key,
+      ready,
+      complete: complete2,
+      status: status2,
+      source,
+      selector: readiness?.selector,
+      target,
+      width: summary?.width,
+      height: summary?.height,
+      expectedFrameCount,
+      recordedFrameCount: recorded,
+      missingFrameCount: missing,
+      firstFrameIndex: summary?.firstFrameIndex ?? null,
+      lastFrameIndex: summary?.lastFrameIndex ?? null,
+      firstTimestamp: summary?.firstTimestamp ?? null,
+      lastTimestamp: summary?.lastTimestamp ?? null,
+      message
     };
-  }, [gl]);
-  useEffect(() => {
-    const element = elementRef.current;
-    if (!element) return;
-    element.className = className ?? "";
-    if (style) Object.assign(element.style, style);
-  }, [className, style]);
-  useCameraViewport(elementRef, options);
-  return null;
+    streamSummaries[key] = stream;
+    streams.push(stream);
+    missingFrameCount += missing;
+    if (complete2) completeStreamCount += 1;
+    if (ready || recorded > 0) resolvedOrRecordedStreamCount += 1;
+  }
+  const complete = result.readiness.ready && streams.length === completeStreamCount && missingFrameCount === 0;
+  const status = complete ? MountedCameraFrameSequenceManifestStatus.Complete : resolvedOrRecordedStreamCount > 0 ? MountedCameraFrameSequenceManifestStatus.Partial : MountedCameraFrameSequenceManifestStatus.Missing;
+  return {
+    schema: "mujoco-react/mounted-camera-frame-sequence-manifest@1",
+    ready: result.readiness.ready,
+    complete,
+    status,
+    cameraKeys,
+    resolvedKeys: [...result.readiness.resolvedKeys],
+    missingKeys: [...result.readiness.missingKeys],
+    expectedFrameCount,
+    recordedFrameCount,
+    missingFrameCount,
+    streamSummaries,
+    streams,
+    readiness: result.readiness,
+    message: complete ? `All ${cameraKeys.length} camera stream${cameraKeys.length === 1 ? "" : "s"} recorded ${expectedFrameCount} frame${expectedFrameCount === 1 ? "" : "s"}.` : `Mounted camera sequence coverage is ${status}.`
+  };
 }
-function isTargetRef(target) {
-  return Boolean(target && typeof target === "object" && "current" in target);
+function createMountedCameraFrameSequencePlanFromApi(api, cameraKeys, options = {}) {
+  return createMountedCameraFrameSequencePlan(cameraKeys, {
+    ...options,
+    cameras: api.getCameras(),
+    sites: api.getSites(),
+    bodies: api.getBodies()
+  });
 }
-function resolveCanvasTarget(target) {
-  const resolvedTarget = isTargetRef(target) ? target.current : target;
-  if (!resolvedTarget) {
-    throw new Error("No frame capture target is available.");
+async function recordMountedCameraFrameSequence(api, options) {
+  const { cameraKeys, ...restOptions } = options;
+  const requireAll = restOptions.requireAll ?? restOptions.requireMountedSources ?? true;
+  const plan = createMountedCameraFrameSequencePlanFromApi(
+    api,
+    cameraKeys,
+    { ...restOptions, requireAll }
+  );
+  const readiness = createMountedCameraFrameSequenceReadiness(plan);
+  const result = await api.recordCameraSequence({
+    ...restOptions,
+    cameras: plan.cameras,
+    requireMountedSources: restOptions.requireMountedSources ?? true
+  });
+  return {
+    ...result,
+    plan,
+    readiness
+  };
+}
+
+// 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}`);
+    }
   }
-  if (resolvedTarget instanceof HTMLCanvasElement) {
-    return resolvedTarget;
+  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 canvas = resolvedTarget.querySelector("canvas");
-  if (!canvas) {
-    throw new Error("Frame capture target does not contain a canvas.");
+  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 canvas;
+  return result;
 }
-function waitForNextAnimationFrame() {
-  return new Promise((resolve) => {
-    requestAnimationFrame(() => resolve());
+function createPolicyCameraFrameCapturePlanFromApi(api, options) {
+  return createPolicyCameraFrameCapturePlan({
+    ...options,
+    cameras: api.getCameras(),
+    sites: api.getSites(),
+    bodies: api.getBodies()
   });
 }
-async function captureFrame(options) {
-  const type = options.type ?? "image/png";
-  const canvas = resolveCanvasTarget(options.target);
-  if (options.waitForAnimationFrame ?? true) {
-    await waitForNextAnimationFrame();
+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 {
-    canvas,
-    dataUrl: canvas.toDataURL(type, options.quality),
-    type
+    frames,
+    images,
+    sourceSummary: sourceParts.length > 0 ? sourceParts.join(" + ") : "not used by policy",
+    capturedAt: Date.now()
   };
 }
-async function captureFrameBlob(options) {
-  const type = options.type ?? "image/png";
-  const canvas = resolveCanvasTarget(options.target);
-  if (options.waitForAnimationFrame ?? true) {
-    await waitForNextAnimationFrame();
-  }
-  const blob = await new Promise((resolve, reject) => {
-    canvas.toBlob(
-      (nextBlob) => {
-        if (nextBlob) {
-          resolve(nextBlob);
-        } else {
-          reject(new Error("Canvas frame capture did not produce a Blob."));
-        }
-      },
-      type,
-      options.quality
-    );
-  });
-  return { canvas, blob, type };
+async function capturePolicyCameraFramesFromMountedStreams(target, options) {
+  const plan = createPolicyCameraFrameCapturePlanFromApi(target, options);
+  const result = await capturePolicyCameraFrames(target, plan);
+  return { ...result, plan };
 }
-function useFrameCapture(defaultOptions = {}) {
-  const [status, setStatus] = useState("idle");
-  const [error, setError] = useState(null);
-  const reset = useCallback(() => {
-    setStatus("idle");
-    setError(null);
-  }, []);
-  const capture = useCallback(
-    async (options = {}) => {
-      setStatus("capturing");
-      setError(null);
+
+// src/runtime/client.ts
+var owners = /* @__PURE__ */ new WeakMap();
+var isWorkerOwned = (model) => Boolean(model && owners.has(model));
+function closeModelRuntime(model) {
+  if (model) owners.get(model)?.close();
+}
+function runtimeContacts(model) {
+  return owners.get(model)?.contacts();
+}
+function assertMainThreadOwnership(model) {
+  if (isWorkerOwned(model)) throw new Error("Worker runtime owns this simulation. Use runtime operations or dispose it before using viewer physics operations.");
+}
+var abortError = () => new DOMException("Simulation operation cancelled", "AbortError");
+var RuntimeClient = class {
+  constructor(worker, apply, release, capture) {
+    this.worker = worker;
+    this.apply = apply;
+    this.release = release;
+    this.capture = capture;
+    worker.onmessage = (event) => {
+      const response = event.data;
+      if (this.closed || response.id !== this.pending?.id) return;
+      if (response.display) {
+        try {
+          this.apply(response.display);
+          const f = response.display.fields;
+          this.latest = {
+            time: response.display.time,
+            qpos: f.qpos,
+            qvel: f.qvel,
+            ctrl: f.ctrl,
+            sensors: f.sensordata,
+            contacts: response.done ? response.display.contacts : this.latest.contacts
+          };
+        } catch (error) {
+          this.close(error instanceof Error ? error : new Error(String(error)));
+          return;
+        }
+      }
+      if (!response.done) this.worker.postMessage({ kind: "ack", id: response.id });
+      if (response.done) {
+        const pending = this.pending;
+        this.pending = null;
+        if (response.error) pending.reject(new Error(response.error));
+        else pending.resolve(response);
+      }
+    };
+    worker.onerror = (event) => this.close(new Error(event.message || "Simulation worker failed"));
+    worker.onmessageerror = () => this.close(new Error("Cannot read simulation worker response"));
+  }
+  pending = null;
+  nextId = 0;
+  closed = false;
+  busy = false;
+  flight = Promise.resolve();
+  generation = 0;
+  latest = { time: 0, qpos: new Float64Array(), qvel: new Float64Array(), ctrl: new Float64Array(), sensors: new Float64Array(), contacts: [] };
+  statistics = { steps: 0, physicsMs: 0, elapsedMs: 0, realTimeFactor: 0, captureMs: 0, busy: false };
+  modelId = crypto.randomUUID();
+  get state() {
+    return {
+      ...this.latest,
+      qpos: this.latest.qpos.slice(),
+      qvel: this.latest.qvel.slice(),
+      ctrl: this.latest.ctrl.slice(),
+      sensors: this.latest.sensors.slice(),
+      contacts: this.latest.contacts.map((c) => ({ ...c, pos: [...c.pos] }))
+    };
+  }
+  get metrics() {
+    return { ...this.statistics, busy: this.busy };
+  }
+  request(request) {
+    if (this.closed) return Promise.reject(new Error("Simulation runtime is disposed"));
+    return new Promise((resolve, reject) => {
+      const id = ++this.nextId;
+      this.pending = { id, resolve, reject };
       try {
-        const result = await captureFrame({ ...defaultOptions, ...options });
-        setStatus("captured");
-        return result;
-      } catch (nextError) {
-        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
-        setError(error2);
-        setStatus("error");
-        throw error2;
+        this.worker.postMessage({ ...request, id });
+      } catch (error) {
+        this.pending = null;
+        reject(error instanceof Error ? error : new Error(String(error)));
       }
-    },
-    [defaultOptions]
-  );
-  const captureBlob = useCallback(
-    async (options = {}) => {
-      setStatus("capturing");
-      setError(null);
+    });
+  }
+  exclusive(operation) {
+    if (this.closed) return Promise.reject(new Error("Simulation runtime is disposed"));
+    if (this.busy) return Promise.reject(new Error("Runtime is busy; await the current operation (work is not queued)"));
+    this.busy = true;
+    const result = operation().finally(() => {
+      this.busy = false;
+    });
+    this.flight = result.catch(() => {
+    });
+    return result;
+  }
+  initialize(initial) {
+    return this.exclusive(async () => {
+      await this.request({ kind: "initialize", initial });
+    });
+  }
+  advance(options) {
+    return this.exclusive(async () => {
+      if (options.signal?.aborted) throw abortError();
+      const started = performance.now(), simStart = this.latest.time;
+      const abort = () => {
+        this.worker.postMessage({ kind: "cancel", id: ++this.nextId });
+      };
+      options.signal?.addEventListener("abort", abort, { once: true });
       try {
-        const result = await captureFrameBlob({
-          ...defaultOptions,
-          ...options
+        const result = await this.request({
+          kind: "advance",
+          steps: options.steps,
+          controls: options.controls ? Float64Array.from(options.controls) : void 0
         });
-        setStatus("captured");
-        return result;
-      } catch (nextError) {
-        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
-        setError(error2);
-        setStatus("error");
-        throw error2;
+        const elapsedMs = performance.now() - started;
+        this.statistics = {
+          ...this.statistics,
+          steps: result.steps ?? 0,
+          physicsMs: result.physicsMs ?? 0,
+          elapsedMs,
+          realTimeFactor: (this.latest.time - simStart) * 1e3 / Math.max(elapsedMs, 1e-3)
+        };
+        if (result.cancelled || options.signal?.aborted) throw abortError();
+        return this.state;
+      } finally {
+        options.signal?.removeEventListener("abort", abort);
       }
-    },
-    [defaultOptions]
-  );
-  return {
-    status,
-    error,
-    isCapturing: status === "capturing",
-    capture,
-    captureBlob,
-    reset
-  };
-}
-
-// src/rendering/cameraFrameSource.ts
-var MountedCameraFrameSourceSuggestionMatch = {
-  Direct: "direct",
-  Alias: "alias",
-  Normalized: "normalized",
-  Prefix: "prefix",
-  Suffix: "suffix",
-  Contains: "contains"
-};
-var MountedCameraFrameSequenceReadinessStatus = {
-  Ready: "ready",
-  Partial: "partial",
-  Missing: "missing"
-};
-var MountedCameraFrameSequenceManifestStatus = {
-  Complete: "complete",
-  Partial: "partial",
-  Missing: "missing"
-};
-function getResourceName(resource) {
-  if (!resource) return null;
-  return typeof resource === "string" ? resource : resource.name ?? null;
-}
-function createNameSet(resources) {
-  return new Set(
-    (resources ?? []).map((resource) => getResourceName(resource)).filter((name) => Boolean(name))
-  );
-}
-function createResourceNames(resources) {
-  return (resources ?? []).map((resource) => getResourceName(resource)).filter((name) => Boolean(name));
-}
-function normalizeAliasCandidates(value) {
-  if (!value) return [];
-  return Array.isArray(value) ? value : [value];
-}
-function countMountedSelectors(selector) {
-  return Number(Boolean(selector.cameraName)) + Number(Boolean(selector.siteName)) + Number(Boolean(selector.bodyName));
-}
-function normalizeCameraSourceName(value) {
-  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
-}
-function createCameraSourceKeyVariants(key) {
-  const candidates = [
-    key,
-    key.startsWith("observation.images.") ? key.slice("observation.images.".length) : "",
-    key.includes(".") ? key.split(".").at(-1) ?? "" : "",
-    key.includes("/") ? key.split("/").at(-1) ?? "" : ""
-  ];
-  return candidates.map((candidate) => candidate.trim()).filter((candidate, index, items) => candidate && items.indexOf(candidate) === index);
-}
-function getSelectorKey(selector) {
-  if (selector.cameraName) return `camera:${selector.cameraName}`;
-  if (selector.siteName) return `site:${selector.siteName}`;
-  if (selector.bodyName) return `body:${selector.bodyName}`;
-  return null;
-}
-function getMountedCameraFrameCaptureSource(selector) {
-  if (countMountedSelectors(selector) !== 1) return null;
-  if (selector.cameraName) {
-    return { kind: "mujoco-camera", cameraName: selector.cameraName };
+    });
+  }
+  observe(cameras) {
+    return this.exclusive(async () => {
+      const generation = this.generation;
+      await this.request({ kind: "snapshot" });
+      const state = this.state, started = performance.now();
+      const frames = cameras ? await this.capture?.(cameras) : void 0;
+      if (cameras && !frames) throw new Error("Camera observations require an attached canvas");
+      this.statistics.captureMs = performance.now() - started;
+      if (generation !== this.generation || this.closed) throw abortError();
+      return { ...state, ...frames ? { cameras: frames } : {} };
+    });
+  }
+  saveState() {
+    return this.exclusive(async () => {
+      const result = await this.request({ kind: "snapshot" });
+      const state = result.display.integration;
+      return { modelId: this.modelId, signature: state.signature, values: state.values.slice() };
+    });
   }
-  if (selector.siteName) {
-    return { kind: "mujoco-site", siteName: selector.siteName };
+  restoreState(snapshot) {
+    return this.exclusive(async () => {
+      if (snapshot.modelId !== this.modelId) throw new Error("Snapshot belongs to a different runtime");
+      await this.request({ kind: "restore", state: { signature: snapshot.signature, values: snapshot.values } });
+      return this.state;
+    });
   }
-  if (selector.bodyName) {
-    return { kind: "mujoco-body", bodyName: selector.bodyName };
+  async cancel() {
+    if (this.closed) return;
+    this.generation++;
+    this.worker.postMessage({ kind: "cancel", id: ++this.nextId });
+    await this.flight;
+  }
+  async reset() {
+    await this.cancel();
+    return this.exclusive(async () => {
+      await this.request({ kind: "reset" });
+      return this.state;
+    });
   }
-  return null;
-}
-function isMountedCameraFrameCaptureSource(source) {
-  return source.kind === "mujoco-camera" || source.kind === "mujoco-site" || source.kind === "mujoco-body";
-}
-function getCameraFrameCaptureSourceTarget(source) {
-  if (source.kind === "mujoco-camera") return source.cameraName;
-  if (source.kind === "mujoco-site") return source.siteName;
-  if (source.kind === "mujoco-body") return source.bodyName;
-  if (source.kind === "custom-camera") return "custom camera";
-  if (source.kind === "explicit-pose") return "explicit pose";
-  return "fallback camera";
-}
-function createMountedCameraFrameSourceSuggestion(key, selector, resourceName, match) {
-  const source = getMountedCameraFrameCaptureSource(selector);
-  if (!source) return null;
-  return {
-    key,
-    selector,
-    source,
-    resourceName,
-    resourceKind: source.kind,
-    match
+  async dispose() {
+    await this.cancel();
+    this.close();
+  }
+  close(error = new Error("Simulation runtime disposed")) {
+    if (this.closed) return;
+    this.closed = true;
+    this.generation++;
+    this.worker.terminate();
+    this.pending?.reject(error);
+    this.pending = null;
+    this.release();
+  }
+};
+async function attachSimulationRuntime(module, api, waitForDisplay, invalidate, options = {}) {
+  const model = api.mjModelRef.current, data = api.mjDataRef.current;
+  if (!model || !data) throw new Error("Scene must be ready before creating a runtime");
+  assertMainThreadOwnership(model);
+  api.setPaused(true);
+  const state = api.saveState().integration;
+  const initialState = { signature: state.signature, values: state.values };
+  const mj = module;
+  const path = `/runtime-${crypto.randomUUID()}.mjb`;
+  let binary;
+  try {
+    mj.mj_saveModel(model, path, null);
+    binary = mj.FS.readFile(path);
+  } finally {
+    try {
+      mj.FS.unlink(path);
+    } catch {
+    }
+  }
+  const worker = options.createWorker?.() ?? new Worker(new URL("./physics.worker.js", import.meta.url), { type: "module" });
+  let complete;
+  const apply = (display) => {
+    if (api.mjModelRef.current !== model) throw new Error("Simulation model changed");
+    if (display.integration) {
+      module.mj_setState(model, data, Array.from(display.integration.values), display.integration.signature);
+      complete = display;
+    }
+    for (const field of displayFields) {
+      const target = data[field];
+      if (!(target instanceof Float64Array || target instanceof Int32Array) || target.length !== display.fields[field].length) throw new Error(`Invalid display field ${field}`);
+      target.set(display.fields[field]);
+    }
+    data.time = display.time;
+    invalidate();
   };
+  const client = new RuntimeClient(worker, apply, () => {
+    if (api.mjModelRef.current === model && complete) apply(complete);
+    owners.delete(model);
+  }, async (cameras) => {
+    await waitForDisplay();
+    return capturePolicyCameraFrames(api, cameras);
+  });
+  owners.set(model, { close: () => client.close(), contacts: () => client.state.contacts });
+  try {
+    await client.initialize({ model: binary, state: initialState });
+    return client;
+  } catch (error) {
+    client.close();
+    throw error;
+  }
 }
-function addMountedCameraFrameSourceSuggestion(suggestions, seen, suggestion) {
-  if (!suggestion) return;
-  const selectorKey = getSelectorKey(suggestion.selector);
-  if (!selectorKey || seen.has(selectorKey)) return;
-  seen.add(selectorKey);
-  suggestions.push(suggestion);
+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;
+var GeomBuilder = class {
+  mujoco;
+  textureCache = /* @__PURE__ */ new Map();
+  renderOptions;
+  constructor(mujoco, renderOptions) {
+    this.mujoco = mujoco;
+    this.renderOptions = renderOptions;
+  }
+  getMeshNormalSmoothingTolerance() {
+    const smoothing = this.renderOptions?.meshNormalSmoothing;
+    if (!smoothing) return null;
+    if (smoothing === true) return DEFAULT_MESH_NORMAL_SMOOTHING_TOLERANCE;
+    return smoothing.tolerance ?? DEFAULT_MESH_NORMAL_SMOOTHING_TOLERANCE;
+  }
+  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 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;
+    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 THREE12.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 THREE12.PlaneGeometry(size[0] * 2 || 5, size[1] * 2 || 5);
+    } else if (type === getVal(MG.mjGEOM_SPHERE)) {
+      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 THREE12.BoxGeometry(size[0] * 2, size[1] * 2, size[2] * 2);
+    } else if (type === getVal(MG.mjGEOM_CYLINDER)) {
+      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];
+      const vAdr = mjModel.mesh_vertadr[mId];
+      const vNum = mjModel.mesh_vertnum[mId];
+      const fAdr = mjModel.mesh_faceadr[mId];
+      const fNum = mjModel.mesh_facenum[mId];
+      const tAdr = mjModel.mesh_texcoordadr?.[mId] ?? -1;
+      if (map && tAdr >= 0 && mjModel.mesh_texcoord && mjModel.mesh_facetexcoord) {
+        const corners = fNum * 3;
+        const positions = new Float32Array(corners * 3);
+        const uvs = new Float32Array(corners * 2);
+        for (let c = 0; c < corners; c++) {
+          const v = vAdr + mjModel.mesh_face[fAdr * 3 + c];
+          positions[c * 3] = mjModel.mesh_vert[v * 3];
+          positions[c * 3 + 1] = mjModel.mesh_vert[v * 3 + 1];
+          positions[c * 3 + 2] = mjModel.mesh_vert[v * 3 + 2];
+          const t = tAdr + mjModel.mesh_facetexcoord[fAdr * 3 + c];
+          uvs[c * 2] = mjModel.mesh_texcoord[t * 2];
+          uvs[c * 2 + 1] = 1 - mjModel.mesh_texcoord[t * 2 + 1];
+        }
+        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 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) {
+          geo = mergeVertices(geo, smoothingTolerance);
+        }
+        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 THREE12.Mesh(geo, new THREE12.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 getRenderOptionsKey(renderOptions) {
+  const smoothing = renderOptions?.meshNormalSmoothing;
+  if (!smoothing) return "default";
+  if (smoothing === true) return "meshNormalSmoothing:true";
+  return `meshNormalSmoothing:${smoothing.tolerance ?? "default"}`;
 }
-function getCameraFrameResourceMatch(key, resourceName) {
-  if (resourceName === key) return MountedCameraFrameSourceSuggestionMatch.Direct;
-  const normalizedResource = normalizeCameraSourceName(resourceName);
-  if (!normalizedResource) return null;
-  for (const variant of createCameraSourceKeyVariants(key)) {
-    if (resourceName === variant) return MountedCameraFrameSourceSuggestionMatch.Direct;
-    const normalizedKey = normalizeCameraSourceName(variant);
-    if (!normalizedKey) continue;
-    if (normalizedResource === normalizedKey) {
-      return MountedCameraFrameSourceSuggestionMatch.Normalized;
+function SceneRenderer({ renderOptions, ...props }) {
+  const {
+    mjModelRef,
+    mjDataRef,
+    mujocoRef,
+    onSelectionRef,
+    hiddenBodiesRef,
+    hiddenBodiesVersion,
+    interpolateRef,
+    interpolationStateRef,
+    status
+  } = useMujocoContext();
+  const groupRef = useRef(null);
+  const bodyRefs = useRef([]);
+  const prevModelRef = useRef(null);
+  const prevRenderOptionsKeyRef = useRef(null);
+  const prevHiddenVersionRef = useRef(null);
+  const renderOptionsKey = getRenderOptionsKey(renderOptions);
+  const geomBuilder = useMemo(() => {
+    if (status !== "ready") return null;
+    return new GeomBuilder(mujocoRef.current, renderOptions);
+  }, [status, mujocoRef, renderOptionsKey]);
+  useEffect(() => {
+    if (status !== "ready" || !geomBuilder) return;
+    const model = mjModelRef.current;
+    const group = groupRef.current;
+    if (!model || !group) return;
+    if (prevModelRef.current === model && prevRenderOptionsKeyRef.current === renderOptionsKey && prevHiddenVersionRef.current === hiddenBodiesVersion) {
+      return;
     }
-    if (normalizedResource.startsWith(`${normalizedKey}_`)) {
-      return MountedCameraFrameSourceSuggestionMatch.Prefix;
+    prevModelRef.current = model;
+    prevRenderOptionsKeyRef.current = renderOptionsKey;
+    prevHiddenVersionRef.current = hiddenBodiesVersion;
+    while (group.children.length > 0) {
+      group.remove(group.children[0]);
     }
-    if (normalizedResource.endsWith(`_${normalizedKey}`)) {
-      return MountedCameraFrameSourceSuggestionMatch.Suffix;
+    const refs = [];
+    for (let i = 0; i < model.nbody; i++) {
+      const bodyGroup = new THREE12.Group();
+      bodyGroup.userData.bodyID = i;
+      const bodyName = getName(model, model.name_bodyadr[i]);
+      if (!hiddenBodiesRef.current.has(bodyName)) {
+        for (let g = 0; g < model.ngeom; g++) {
+          if (model.geom_bodyid[g] === i) {
+            const mesh = geomBuilder.create(model, g);
+            if (mesh) bodyGroup.add(mesh);
+          }
+        }
+      }
+      group.add(bodyGroup);
+      refs.push(bodyGroup);
     }
-    if (normalizedResource.includes(`_${normalizedKey}_`)) {
-      return MountedCameraFrameSourceSuggestionMatch.Contains;
+    bodyRefs.current = refs;
+  }, [status, geomBuilder, mjModelRef, renderOptionsKey, hiddenBodiesRef, hiddenBodiesVersion]);
+  const syncBodiesToData = useCallback(() => {
+    const data = mjDataRef.current;
+    if (!data) return;
+    const bodies = bodyRefs.current;
+    const interpolation = interpolationStateRef.current;
+    const useInterpolation = interpolateRef.current && interpolation.valid;
+    for (let i = 0; i < bodies.length; i++) {
+      const ref = bodies[i];
+      if (!ref) continue;
+      if (useInterpolation) {
+        const alpha = interpolation.alpha;
+        const i3 = i * 3;
+        ref.position.set(
+          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(
+          interpolation.previousXquat[i4 + 1],
+          interpolation.previousXquat[i4 + 2],
+          interpolation.previousXquat[i4 + 3],
+          interpolation.previousXquat[i4]
+        );
+        _currentQuat.set(
+          interpolation.currentXquat[i4 + 1],
+          interpolation.currentXquat[i4 + 2],
+          interpolation.currentXquat[i4 + 3],
+          interpolation.currentXquat[i4]
+        );
+        ref.quaternion.copy(_previousQuat).slerp(_currentQuat, alpha);
+      } else {
+        ref.position.set(
+          data.xpos[i * 3],
+          data.xpos[i * 3 + 1],
+          data.xpos[i * 3 + 2]
+        );
+        ref.quaternion.set(
+          data.xquat[i * 4 + 1],
+          data.xquat[i * 4 + 2],
+          data.xquat[i * 4 + 3],
+          data.xquat[i * 4]
+        );
+      }
     }
-  }
-  return null;
-}
-function isSelectorMounted(selector, cameraNames, siteNames, bodyNames) {
-  if (countMountedSelectors(selector) !== 1) return false;
-  return (selector.cameraName ? cameraNames.has(selector.cameraName) : false) || (selector.siteName ? siteNames.has(selector.siteName) : false) || (selector.bodyName ? bodyNames.has(selector.bodyName) : false);
+  }, [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();
+        let obj = e.object;
+        while (obj && obj.userData.bodyID === void 0 && obj.parent) {
+          obj = obj.parent;
+        }
+        const bodyID = obj?.userData.bodyID;
+        if (typeof bodyID === "number" && bodyID > 0) {
+          const model = mjModelRef.current;
+          if (model && bodyID < model.nbody && onSelectionRef.current) {
+            const name = getName(model, model.name_bodyadr[bodyID]);
+            onSelectionRef.current({ bodyId: bodyID, name });
+          }
+        }
+      }
+    }
+  );
 }
-function createMountedCameraFrameSourceSuggestions(key, options) {
-  const cameraNames = createNameSet(options.cameras);
-  const siteNames = createNameSet(options.sites);
-  const bodyNames = createNameSet(options.bodies);
-  const suggestions = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const selector of normalizeAliasCandidates(options.aliases?.[key])) {
-    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
-      continue;
+var _previousQuat = new THREE12.Quaternion();
+var _currentQuat = new THREE12.Quaternion();
+var CameraViewportRegistryContext = createContext(null);
+var nextViewportId = 0;
+var VIEWPORT_RENDER_PRIORITY = 1;
+function CameraViewportRenderer({
+  viewportsRef
+}) {
+  const gl = useThree((state) => state.gl);
+  const scene = useThree((state) => state.scene);
+  const mainCamera = useThree((state) => state.camera);
+  const mujoco = useMujoco();
+  useFrame(() => {
+    const dpr = gl.getPixelRatio();
+    const drawWidth = gl.domElement.width / dpr;
+    const drawHeight = gl.domElement.height / dpr;
+    gl.setScissorTest(false);
+    gl.setViewport(0, 0, drawWidth, drawHeight);
+    gl.render(scene, mainCamera);
+    const api = mujoco.api;
+    if (!api || viewportsRef.current.size === 0) return;
+    const canvasRect = gl.domElement.getBoundingClientRect();
+    for (const descriptor of viewportsRef.current.values()) {
+      const element = descriptor.getElement();
+      if (!element) continue;
+      const rect = element.getBoundingClientRect();
+      const isOffscreen = rect.bottom < canvasRect.top || rect.top > canvasRect.bottom || rect.right < canvasRect.left || rect.left > canvasRect.right;
+      if (isOffscreen) continue;
+      const width = rect.width;
+      const height = rect.height;
+      if (width <= 0 || height <= 0) continue;
+      const left = rect.left - canvasRect.left;
+      const bottom = canvasRect.bottom - rect.bottom;
+      let resolved;
+      try {
+        resolved = api.resolveCameraCaptureOptions(descriptor.getOptions());
+      } catch {
+        continue;
+      }
+      if (!descriptor.camera) {
+        descriptor.camera = createCaptureCamera(resolved, mainCamera, width, height);
+      } else {
+        prepareCaptureCamera(descriptor.camera, resolved, mainCamera, width, height);
+      }
+      gl.setViewport(left, bottom, width, height);
+      gl.setScissor(left, bottom, width, height);
+      gl.setScissorTest(true);
+      gl.render(scene, descriptor.camera);
     }
-    const source = getMountedCameraFrameCaptureSource(selector);
-    if (!source) continue;
-    addMountedCameraFrameSourceSuggestion(
-      suggestions,
-      seen,
-      createMountedCameraFrameSourceSuggestion(
-        key,
-        selector,
-        getCameraFrameCaptureSourceTarget(source),
-        MountedCameraFrameSourceSuggestionMatch.Alias
-      )
-    );
-  }
-  for (const cameraName of createResourceNames(options.cameras)) {
-    const match = getCameraFrameResourceMatch(key, cameraName);
-    if (!match) continue;
-    addMountedCameraFrameSourceSuggestion(
-      suggestions,
-      seen,
-      createMountedCameraFrameSourceSuggestion(
-        key,
-        { cameraName },
-        cameraName,
-        match
-      )
-    );
-  }
-  for (const siteName of createResourceNames(options.sites)) {
-    const match = getCameraFrameResourceMatch(key, siteName);
-    if (!match) continue;
-    addMountedCameraFrameSourceSuggestion(
-      suggestions,
-      seen,
-      createMountedCameraFrameSourceSuggestion(
-        key,
-        { siteName },
-        siteName,
-        match
-      )
-    );
-  }
-  for (const bodyName of createResourceNames(options.bodies)) {
-    const match = getCameraFrameResourceMatch(key, bodyName);
-    if (!match) continue;
-    addMountedCameraFrameSourceSuggestion(
-      suggestions,
-      seen,
-      createMountedCameraFrameSourceSuggestion(
-        key,
-        { bodyName },
-        bodyName,
-        match
-      )
-    );
-  }
-  return suggestions;
+    gl.setScissorTest(false);
+    gl.setViewport(0, 0, drawWidth, drawHeight);
+  }, VIEWPORT_RENDER_PRIORITY);
+  return null;
+}
+function CameraViewportProvider({ children }) {
+  const viewportsRef = useRef(/* @__PURE__ */ new Map());
+  const [count, setCount] = useState(0);
+  const register = useCallback((descriptor) => {
+    const id = nextViewportId++;
+    viewportsRef.current.set(id, descriptor);
+    setCount((value2) => value2 + 1);
+    return () => {
+      viewportsRef.current.delete(id);
+      setCount((value2) => value2 - 1);
+    };
+  }, []);
+  const value = useMemo(() => ({ register }), [register]);
+  return /* @__PURE__ */ jsxs(CameraViewportRegistryContext.Provider, { value, children: [
+    children,
+    count > 0 && /* @__PURE__ */ jsx(CameraViewportRenderer, { viewportsRef })
+  ] });
 }
-function resolveMountedCameraFrameSource(key, options) {
-  const cameraNames = createNameSet(options.cameras);
-  const siteNames = createNameSet(options.sites);
-  const bodyNames = createNameSet(options.bodies);
-  const directCandidates = [
-    { cameraName: key },
-    { siteName: key },
-    { bodyName: key }
-  ];
-  const aliasCandidates = normalizeAliasCandidates(options.aliases?.[key]);
-  for (const selector of aliasCandidates) {
-    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
-      continue;
-    }
-    const source = getMountedCameraFrameCaptureSource(selector);
-    if (!source) continue;
-    return { key, selector, source };
+function useCameraViewport(elementRef, options) {
+  const registry = useContext(CameraViewportRegistryContext);
+  if (!registry) {
+    throw new Error("useCameraViewport must be used inside <MujocoCanvas>.");
   }
-  const [suggestion] = createMountedCameraFrameSourceSuggestions(key, options);
-  if (suggestion) {
-    return {
-      key,
-      selector: suggestion.selector,
-      source: suggestion.source
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  useEffect(() => {
+    const descriptor = {
+      getElement: () => elementRef.current,
+      getOptions: () => optionsRef.current,
+      camera: null
     };
+    return registry.register(descriptor);
+  }, [registry, elementRef]);
+}
+function CameraView({ className, style, ...options }) {
+  const gl = useThree((state) => state.gl);
+  const elementRef = useRef(null);
+  if (!elementRef.current && typeof document !== "undefined") {
+    elementRef.current = document.createElement("div");
   }
-  if (options.allowAliasFallback) {
-    for (const selector of aliasCandidates) {
-      const source = getMountedCameraFrameCaptureSource(selector);
-      if (!source) continue;
-      return { key, selector, source };
-    }
-  }
-  for (const selector of directCandidates) {
-    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
-      continue;
-    }
-    const source = getMountedCameraFrameCaptureSource(selector);
-    if (!source) continue;
-    return { key, selector, source };
-  }
+  useEffect(() => {
+    const element = elementRef.current;
+    const parent = gl.domElement.parentElement;
+    if (!element || !parent) return;
+    element.style.position = "absolute";
+    element.style.overflow = "hidden";
+    parent.appendChild(element);
+    return () => {
+      parent.removeChild(element);
+    };
+  }, [gl]);
+  useEffect(() => {
+    const element = elementRef.current;
+    if (!element) return;
+    element.className = className ?? "";
+    if (style) Object.assign(element.style, style);
+  }, [className, style]);
+  useCameraViewport(elementRef, options);
   return null;
 }
-function createMountedCameraFrameSequencePlan(cameraKeys, options) {
-  const cameras = [];
-  const resolved = {};
-  const missingKeys = [];
-  for (const key of cameraKeys) {
-    const mountedSource = resolveMountedCameraFrameSource(key, options);
-    if (!mountedSource) {
-      missingKeys.push(key);
-      continue;
-    }
-    resolved[key] = mountedSource;
-    cameras.push({
-      key,
-      ...options.defaults,
-      ...options.cameraOptions?.[key],
-      ...mountedSource.selector,
-      source: mountedSource.source
-    });
+function isTargetRef(target) {
+  return Boolean(target && typeof target === "object" && "current" in target);
+}
+function resolveCanvasTarget(target) {
+  const resolvedTarget = isTargetRef(target) ? target.current : target;
+  if (!resolvedTarget) {
+    throw new Error("No frame capture target is available.");
   }
-  if (options.requireAll && missingKeys.length > 0) {
-    throw new Error(
-      `Unable to resolve mounted MuJoCo camera source${missingKeys.length === 1 ? "" : "s"} for ${missingKeys.join(", ")}.`
-    );
+  if (resolvedTarget instanceof HTMLCanvasElement) {
+    return resolvedTarget;
   }
-  return {
-    cameraKeys: [...cameraKeys],
-    cameras,
-    resolved,
-    missingKeys
-  };
-}
-function createMountedCameraFrameSequenceReadiness(plan) {
-  const cameras = {};
-  const resolvedKeys = plan.cameraKeys.filter((key) => Boolean(plan.resolved[key]));
-  for (const key of plan.cameraKeys) {
-    const resolved = plan.resolved[key];
-    cameras[key] = resolved ? {
-      key,
-      ready: true,
-      selector: resolved.selector,
-      source: resolved.source,
-      message: `Camera stream "${key}" resolves to ${resolved.source.kind}:${getCameraFrameCaptureSourceTarget(resolved.source)}.`
-    } : {
-      key,
-      ready: false,
-      message: `Camera stream "${key}" does not resolve to a mounted MuJoCo camera, site, or body.`
-    };
+  const canvas = resolvedTarget.querySelector("canvas");
+  if (!canvas) {
+    throw new Error("Frame capture target does not contain a canvas.");
   }
-  const missingKeys = [...plan.missingKeys];
-  const ready = missingKeys.length === 0;
-  const status = ready ? MountedCameraFrameSequenceReadinessStatus.Ready : resolvedKeys.length > 0 ? MountedCameraFrameSequenceReadinessStatus.Partial : MountedCameraFrameSequenceReadinessStatus.Missing;
-  return {
-    ready,
-    status,
-    cameraKeys: [...plan.cameraKeys],
-    resolvedKeys,
-    missingKeys,
-    cameras,
-    message: ready ? `All ${plan.cameraKeys.length} requested camera stream${plan.cameraKeys.length === 1 ? "" : "s"} resolve to mounted MuJoCo sources.` : `Missing mounted MuJoCo source${missingKeys.length === 1 ? "" : "s"} for ${missingKeys.join(", ")}.`
-  };
+  return canvas;
 }
-function normalizeFrameCount(frameCount) {
-  return Number.isFinite(frameCount) && frameCount !== void 0 ? Math.max(0, Math.floor(frameCount)) : 0;
+function waitForNextAnimationFrame() {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
 }
-function createMountedCameraFrameSequenceManifest(result, options = {}) {
-  const cameraKeys = [
-    ...options.cameraKeys ?? result.readiness.cameraKeys ?? result.plan.cameraKeys ?? result.cameraKeys
-  ];
-  const expectedFrameCount = normalizeFrameCount(
-    options.expectedFrameCount ?? result.frameCount
-  );
-  const recordedFrameCount = normalizeFrameCount(result.frameCount);
-  const streamSummaries = {};
-  const streams = [];
-  let missingFrameCount = 0;
-  let completeStreamCount = 0;
-  let resolvedOrRecordedStreamCount = 0;
-  for (const key of cameraKeys) {
-    const summary = result.cameraSummaries[key];
-    const readiness = result.readiness.cameras[key];
-    const source = summary?.source ?? readiness?.source;
-    const ready = readiness?.ready ?? Boolean(summary);
-    const recorded = normalizeFrameCount(summary?.frameCount);
-    const missing = Math.max(expectedFrameCount - recorded, 0);
-    const complete2 = ready && missing === 0;
-    const status2 = complete2 ? MountedCameraFrameSequenceManifestStatus.Complete : ready || recorded > 0 ? MountedCameraFrameSequenceManifestStatus.Partial : MountedCameraFrameSequenceManifestStatus.Missing;
-    const target = source ? getCameraFrameCaptureSourceTarget(source) : readiness?.message ? void 0 : "missing MuJoCo camera";
-    const message = complete2 ? `Camera stream "${key}" recorded ${recorded} of ${expectedFrameCount} frame${expectedFrameCount === 1 ? "" : "s"}.` : ready || recorded > 0 ? `Camera stream "${key}" recorded ${recorded} of ${expectedFrameCount} frame${expectedFrameCount === 1 ? "" : "s"}.` : readiness?.message ?? `Camera stream "${key}" did not record any frames.`;
-    const stream = {
-      key,
-      ready,
-      complete: complete2,
-      status: status2,
-      source,
-      selector: readiness?.selector,
-      target,
-      width: summary?.width,
-      height: summary?.height,
-      expectedFrameCount,
-      recordedFrameCount: recorded,
-      missingFrameCount: missing,
-      firstFrameIndex: summary?.firstFrameIndex ?? null,
-      lastFrameIndex: summary?.lastFrameIndex ?? null,
-      firstTimestamp: summary?.firstTimestamp ?? null,
-      lastTimestamp: summary?.lastTimestamp ?? null,
-      message
-    };
-    streamSummaries[key] = stream;
-    streams.push(stream);
-    missingFrameCount += missing;
-    if (complete2) completeStreamCount += 1;
-    if (ready || recorded > 0) resolvedOrRecordedStreamCount += 1;
+async function captureFrame(options) {
+  const type = options.type ?? "image/png";
+  const canvas = resolveCanvasTarget(options.target);
+  if (options.waitForAnimationFrame ?? true) {
+    await waitForNextAnimationFrame();
   }
-  const complete = result.readiness.ready && streams.length === completeStreamCount && missingFrameCount === 0;
-  const status = complete ? MountedCameraFrameSequenceManifestStatus.Complete : resolvedOrRecordedStreamCount > 0 ? MountedCameraFrameSequenceManifestStatus.Partial : MountedCameraFrameSequenceManifestStatus.Missing;
   return {
-    schema: "mujoco-react/mounted-camera-frame-sequence-manifest@1",
-    ready: result.readiness.ready,
-    complete,
-    status,
-    cameraKeys,
-    resolvedKeys: [...result.readiness.resolvedKeys],
-    missingKeys: [...result.readiness.missingKeys],
-    expectedFrameCount,
-    recordedFrameCount,
-    missingFrameCount,
-    streamSummaries,
-    streams,
-    readiness: result.readiness,
-    message: complete ? `All ${cameraKeys.length} camera stream${cameraKeys.length === 1 ? "" : "s"} recorded ${expectedFrameCount} frame${expectedFrameCount === 1 ? "" : "s"}.` : `Mounted camera sequence coverage is ${status}.`
+    canvas,
+    dataUrl: canvas.toDataURL(type, options.quality),
+    type
   };
 }
-function createMountedCameraFrameSequencePlanFromApi(api, cameraKeys, options = {}) {
-  return createMountedCameraFrameSequencePlan(cameraKeys, {
-    ...options,
-    cameras: api.getCameras(),
-    sites: api.getSites(),
-    bodies: api.getBodies()
-  });
-}
-async function recordMountedCameraFrameSequence(api, options) {
-  const { cameraKeys, ...restOptions } = options;
-  const requireAll = restOptions.requireAll ?? restOptions.requireMountedSources ?? true;
-  const plan = createMountedCameraFrameSequencePlanFromApi(
-    api,
-    cameraKeys,
-    { ...restOptions, requireAll }
-  );
-  const readiness = createMountedCameraFrameSequenceReadiness(plan);
-  const result = await api.recordCameraSequence({
-    ...restOptions,
-    cameras: plan.cameras,
-    requireMountedSources: restOptions.requireMountedSources ?? true
+async function captureFrameBlob(options) {
+  const type = options.type ?? "image/png";
+  const canvas = resolveCanvasTarget(options.target);
+  if (options.waitForAnimationFrame ?? true) {
+    await waitForNextAnimationFrame();
+  }
+  const blob = await new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (nextBlob) => {
+        if (nextBlob) {
+          resolve(nextBlob);
+        } else {
+          reject(new Error("Canvas frame capture did not produce a Blob."));
+        }
+      },
+      type,
+      options.quality
+    );
   });
+  return { canvas, blob, type };
+}
+function useFrameCapture(defaultOptions = {}) {
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+  }, []);
+  const capture = useCallback(
+    async (options = {}) => {
+      setStatus("capturing");
+      setError(null);
+      try {
+        const result = await captureFrame({ ...defaultOptions, ...options });
+        setStatus("captured");
+        return result;
+      } catch (nextError) {
+        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [defaultOptions]
+  );
+  const captureBlob = useCallback(
+    async (options = {}) => {
+      setStatus("capturing");
+      setError(null);
+      try {
+        const result = await captureFrameBlob({
+          ...defaultOptions,
+          ...options
+        });
+        setStatus("captured");
+        return result;
+      } catch (nextError) {
+        const error2 = nextError instanceof Error ? nextError : new Error("Unable to capture the current canvas frame.");
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [defaultOptions]
+  );
   return {
-    ...result,
-    plan,
-    readiness
+    status,
+    error,
+    isCapturing: status === "capturing",
+    capture,
+    captureBlob,
+    reset
   };
 }
 var _raycaster = new THREE12.Raycaster();
@@ -2358,10 +2742,11 @@ function useMujoco() {
   };
 }
 function useBeforePhysicsStep(callback) {
-  const { beforeStepCallbacks } = useMujocoContext();
+  const { beforeStepCallbacks, mjModelRef } = useMujocoContext();
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
   useEffect(() => {
+    assertMainThreadOwnership(mjModelRef.current);
     const wrapped = (input) => callbackRef.current(input);
     beforeStepCallbacks.current.add(wrapped);
     return () => {
@@ -2370,10 +2755,11 @@ function useBeforePhysicsStep(callback) {
   }, [beforeStepCallbacks]);
 }
 function useAfterPhysicsStep(callback) {
-  const { afterStepCallbacks } = useMujocoContext();
+  const { afterStepCallbacks, mjModelRef } = useMujocoContext();
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
   useEffect(() => {
+    assertMainThreadOwnership(mjModelRef.current);
     const wrapped = (input) => callbackRef.current(input);
     afterStepCallbacks.current.add(wrapped);
     return () => {
@@ -2393,6 +2779,7 @@ function MujocoSimProvider({
   timestep,
   integrator,
   substeps,
+  physicsBudgetMs = 8,
   paused,
   speed,
   interpolate,
@@ -2400,7 +2787,32 @@ function MujocoSimProvider({
   hiddenBodies,
   children
 }) {
-  const { gl, camera, scene } = useThree();
+  const { gl, camera, scene, invalidate } = useThree();
+  const modelIdentity = sceneIdentity(config);
+  const performanceRef = useRef({ steps: 0, physicsMs: 0, realTimeFactor: 0, backlogSteps: 0, budgetExceeded: false });
+  const displayWaiters = useRef(/* @__PURE__ */ new Set());
+  useFrame(() => {
+    if (displayWaiters.current.size) {
+      const waiters = [...displayWaiters.current];
+      displayWaiters.current.clear();
+      queueMicrotask(() => {
+        scene.updateMatrixWorld(true);
+        for (const ready of waiters) ready();
+      });
+    }
+  }, 0);
+  const waitForDisplay = () => new Promise((resolve, reject) => {
+    const ready = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      displayWaiters.current.delete(ready);
+      reject(new Error("Canvas did not produce an observation frame within 5 seconds"));
+    }, 5e3);
+    displayWaiters.current.add(ready);
+    invalidate();
+  });
   const [status, setStatus] = useState("loading");
   const mjModelRef = useRef(null);
   const mjDataRef = useRef(null);
@@ -2436,18 +2848,23 @@ function MujocoSimProvider({
   const bodyReloadTimerRef = useRef(null);
   configRef.current = config;
   mujocoRef.current = mujoco;
-  pausedRef.current = paused ?? false;
-  speedRef.current = speed ?? 1;
+  useEffect(() => {
+    pausedRef.current = paused ?? false;
+  }, [paused]);
+  useEffect(() => {
+    speedRef.current = speed ?? 1;
+  }, [speed]);
   substepsRef.current = substeps ?? 1;
   interpolateRef.current = interpolate ?? false;
   useEffect(() => {
     if (!gravity) return;
     const model = mjModelRef.current;
     if (!model?.opt?.gravity) return;
+    assertMainThreadOwnership(model);
     model.opt.gravity[0] = gravity[0];
     model.opt.gravity[1] = gravity[1];
     model.opt.gravity[2] = gravity[2];
-  }, [gravity]);
+  }, [gravity?.[0], gravity?.[1], gravity?.[2]]);
   const integratorRef = useRef(integrator);
   integratorRef.current = integrator;
   const applyIntegrator = (model) => {
@@ -2455,12 +2872,16 @@ function MujocoSimProvider({
     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);
+    if (mjModelRef.current) {
+      assertMainThreadOwnership(mjModelRef.current);
+      applyIntegrator(mjModelRef.current);
+    }
   }, [integrator]);
   useEffect(() => {
     if (timestep === void 0) return;
     const model = mjModelRef.current;
     if (!model?.opt) return;
+    assertMainThreadOwnership(model);
     model.opt.timestep = timestep;
   }, [timestep]);
   const hiddenBodiesKey = (hiddenBodies ?? []).join("\0");
@@ -2498,6 +2919,7 @@ function MujocoSimProvider({
   }
   useEffect(() => {
     let disposed = false;
+    setStatus("loading");
     (async () => {
       try {
         const result = await loadScene(mujoco, buildMergedConfig(config));
@@ -2532,6 +2954,7 @@ function MujocoSimProvider({
     })();
     return () => {
       disposed = true;
+      closeModelRuntime(mjModelRef.current);
       mjDataRef.current?.delete();
       mjModelRef.current?.delete();
       mjModelRef.current = null;
@@ -2543,7 +2966,7 @@ function MujocoSimProvider({
       } catch {
       }
     };
-  }, [mujoco, config]);
+  }, [mujoco, modelIdentity]);
   useEffect(() => {
     if (status === "ready") {
       const api2 = apiRef.current;
@@ -2561,66 +2984,43 @@ function MujocoSimProvider({
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return;
-    const shouldStep = !pausedRef.current || stepsToRunRef.current > 0;
-    if (!shouldStep) return;
-    for (let i = 0; i < model.nv; i++) {
-      data.qfrc_applied[i] = 0;
-    }
-    for (const cb of beforeStepCallbacks.current) {
-      cb({ model, data });
+    if (isWorkerOwned(model)) {
+      interpolationStateRef.current.valid = false;
+      return;
     }
-    const numSubsteps = substepsRef.current;
-    if (!interpolateRef.current) {
-      if (stepsToRunRef.current > 0) {
-        for (let s = 0; s < stepsToRunRef.current; s++) {
-          mujocoRef.current.mj_step(model, data);
-        }
-        stepsToRunRef.current = 0;
-      } else {
-        const startSimTime = data.time;
-        const clampedDelta = Math.min(delta, 1 / 15);
-        const frameTime = clampedDelta * speedRef.current;
-        while (data.time - startSimTime < frameTime) {
-          for (let s = 0; s < numSubsteps; s++) {
-            mujocoRef.current.mj_step(model, data);
-          }
-        }
-      }
-    } else if (stepsToRunRef.current > 0) {
+    const queued = stepsToRunRef.current > 0;
+    if (pausedRef.current && !queued) return;
+    const startTime = data.time;
+    const dt = model.opt.timestep;
+    if (!Number.isFinite(dt) || dt <= 0) return;
+    const substeps2 = Math.max(1, Math.floor(substepsRef.current));
+    const frameTime = Math.max(0, Math.min(delta, 1 / 15) * speedRef.current);
+    if (!queued && interpolateRef.current) physicsAccumulatorRef.current += frameTime;
+    const desired = queued ? stepsToRunRef.current : interpolateRef.current ? Math.floor(physicsAccumulatorRef.current / (dt * substeps2)) * substeps2 : Math.ceil(frameTime / (dt * substeps2)) * substeps2;
+    for (let i = 0; i < model.nv; i++) data.qfrc_applied[i] = 0;
+    for (const cb of beforeStepCallbacks.current) cb({ model, data });
+    if (interpolateRef.current) {
       ensureInterpolationBuffers(model);
-      copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
-      for (let s = 0; s < stepsToRunRef.current; s++) {
-        mujocoRef.current.mj_step(model, data);
-      }
+      if (!interpolationStateRef.current.valid) copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
+    }
+    const measured = runStepBudget(desired, () => {
+      if (interpolateRef.current) copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
+      mujocoRef.current.mj_step(model, data);
+    }, physicsBudgetMs);
+    if (queued) stepsToRunRef.current -= measured.steps;
+    performanceRef.current = {
+      ...measured,
+      backlogSteps: Math.max(0, desired - measured.steps),
+      realTimeFactor: (data.time - startTime) / Math.max(delta, 1e-6)
+    };
+    if (interpolateRef.current) {
       copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
-      interpolationStateRef.current.alpha = 1;
-      interpolationStateRef.current.valid = true;
-      stepsToRunRef.current = 0;
-    } else {
-      ensureInterpolationBuffers(model);
-      const clampedDelta = Math.min(delta, 1 / 15);
-      physicsAccumulatorRef.current += clampedDelta * speedRef.current;
-      const stepDt = Math.max((model.opt?.timestep ?? 2e-3) * Math.max(1, numSubsteps), 1e-6);
-      let stepped = false;
-      while (physicsAccumulatorRef.current >= stepDt) {
-        copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
-        for (let s = 0; s < numSubsteps; s++) {
-          mujocoRef.current.mj_step(model, data);
-        }
-        copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
-        physicsAccumulatorRef.current -= stepDt;
-        stepped = true;
-      }
-      if (!interpolationStateRef.current.valid) {
-        copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
-        copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
-      }
-      interpolationStateRef.current.alpha = Math.min(Math.max(physicsAccumulatorRef.current / stepDt, 0), 1);
+      if (!queued) {
+        physicsAccumulatorRef.current -= measured.steps * dt;
+        if (measured.budgetExceeded) physicsAccumulatorRef.current %= dt * substeps2;
+      } else physicsAccumulatorRef.current = 0;
+      interpolationStateRef.current.alpha = queued ? 1 : Math.min(1, physicsAccumulatorRef.current / dt);
       interpolationStateRef.current.valid = true;
-      if (!stepped) {
-        onStepRef.current?.({ time: data.time, model, data });
-        return;
-      }
     }
     for (const cb of afterStepCallbacks.current) {
       cb({ model, data });
@@ -2673,6 +3073,7 @@ function MujocoSimProvider({
     pausedRef.current = p;
   }, []);
   const step = useCallback((n = 1) => {
+    if (!Number.isSafeInteger(n) || n <= 0) throw new Error("Step count must be a positive safe integer");
     stepsToRunRef.current = n;
   }, []);
   useCallback((steps = 1) => {
@@ -3091,6 +3492,7 @@ function MujocoSimProvider({
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return null;
+    assertMainThreadOwnership(model);
     _rayPnt[0] = origin.x;
     _rayPnt[1] = origin.y;
     _rayPnt[2] = origin.z;
@@ -3162,6 +3564,7 @@ function MujocoSimProvider({
   const loadSceneApi = useCallback(async (newConfig) => {
     const gen = ++loadGenRef.current;
     try {
+      closeModelRuntime(mjModelRef.current);
       mjDataRef.current?.delete();
       mjModelRef.current?.delete();
       mjModelRef.current = null;
@@ -3317,6 +3720,7 @@ function MujocoSimProvider({
         if (!model || !data) {
           throw new Error("MuJoCo scene is not ready for camera sequence stepping.");
         }
+        let sliceStarted = performance.now();
         for (let stepIndex = 0; stepIndex < steps; stepIndex += 1) {
           for (let i = 0; i < model.nv; i += 1) {
             data.qfrc_applied[i] = 0;
@@ -3336,6 +3740,11 @@ function MujocoSimProvider({
             cb({ model, data });
           }
           onStepRef.current?.({ time: data.time, model, data });
+          if (performance.now() - sliceStarted >= 8) {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            throwIfCameraSequenceAborted(options.signal);
+            sliceStarted = performance.now();
+          }
           await options.onAfterStep?.({
             frameIndex,
             stepIndex,
@@ -3543,7 +3952,14 @@ function MujocoSimProvider({
     model.geom_size[id * 3 + 2] = size[2];
   }, []);
   const api = useMemo(
-    () => ({
+    () => guardRuntimeOwnership({
+      createRuntime: (options) => {
+        if (beforeStepCallbacks.current.size || afterStepCallbacks.current.size) {
+          return Promise.reject(new Error("Unmount physics callbacks/controllers before creating a worker runtime; use runtime.advance({controls}) for policy actions."));
+        }
+        return attachSimulationRuntime(mujocoRef.current, apiRef.current, waitForDisplay, invalidate, options);
+      },
+      getPerformance: () => ({ ...performanceRef.current }),
       get status() {
         return status;
       },
@@ -3574,7 +3990,10 @@ function MujocoSimProvider({
       setExternalForce,
       applyGeneralizedForce,
       getSensorData,
-      getContacts,
+      getContacts: () => {
+        const model = mjModelRef.current;
+        return model && isWorkerOwned(model) ? runtimeContacts(model) : getContacts();
+      },
       getBodies,
       getJoints,
       getGeoms,
@@ -3610,7 +4029,7 @@ function MujocoSimProvider({
       setGeomSize,
       mjModelRef,
       mjDataRef
-    }),
+    }, () => mjModelRef.current),
     [
       status,
       reset,
@@ -3705,6 +4124,45 @@ function MujocoSimProvider({
     /* @__PURE__ */ jsx(CameraViewportProvider, { children })
   ] });
 }
+var runtimeMutators = /* @__PURE__ */ new Set([
+  "reset",
+  "setSpeed",
+  "togglePause",
+  "setPaused",
+  "step",
+  "applyKeyframe",
+  "saveState",
+  "restoreState",
+  "setQpos",
+  "setQvel",
+  "setCtrl",
+  "applyForce",
+  "applyTorque",
+  "setExternalForce",
+  "applyGeneralizedForce",
+  "setGravity",
+  "setTimestep",
+  "setBodyMass",
+  "setGeomFriction",
+  "setGeomSize",
+  "loadScene",
+  "loadFromFiles",
+  "addBody",
+  "removeBody",
+  "recompile",
+  "recordCameraSequence"
+]);
+function guardRuntimeOwnership(api, model) {
+  for (const key of runtimeMutators) {
+    const record = api;
+    const method = record[key];
+    record[key] = (...args) => {
+      assertMainThreadOwnership(model());
+      return method(...args);
+    };
+  }
+  return api;
+}
 var MujocoCanvas = forwardRef(
   function MujocoCanvas2({
     config,
@@ -3717,6 +4175,7 @@ var MujocoCanvas = forwardRef(
     timestep,
     integrator,
     substeps,
+    physicsBudgetMs,
     paused,
     speed,
     interpolate,
@@ -3754,6 +4213,7 @@ var MujocoCanvas = forwardRef(
         timestep,
         integrator,
         substeps,
+        physicsBudgetMs,
         paused,
         speed,
         interpolate,
@@ -5248,10 +5708,10 @@ function useCameraStream(canvasRef, options) {
     if (!api || !canvasRef.current) return;
     const opts = optionsRef.current;
     if (opts.paused) return;
-    if (opts.fps && opts.fps > 0) {
-      elapsedRef.current += delta;
-      if (elapsedRef.current < 1 / opts.fps) return;
-    }
+    const fps = opts.fps ?? 10;
+    if (!Number.isFinite(fps) || fps <= 0) throw new Error("Camera stream fps must be positive and finite");
+    elapsedRef.current += delta;
+    if (elapsedRef.current < 1 / fps) return;
     if (inFlightRef.current) return;
     elapsedRef.current = 0;
     const signature = streamSignature(opts);
@@ -5272,7 +5732,10 @@ function useCameraStream(canvasRef, options) {
         canvas.height = frame.height;
       }
       ctx.drawImage(frame.canvas, 0, 0);
-    }).catch(() => {
+    }).catch((error) => {
+      const failure = error instanceof Error ? error : new Error(String(error));
+      if (optionsRef.current.onError) optionsRef.current.onError(failure);
+      else console.error("Camera stream capture failed", failure);
     }).finally(() => {
       inFlightRef.current = false;
     });
@@ -7407,7 +7870,9 @@ function isPolicyActionChunk(value) {
 function toPolicyActions(output) {
   return isPolicyActionChunk(output) ? [...output] : [output];
 }
-function enqueuePolicyActions(queue, actions, observation, strategy) {
+function enqueuePolicyActions(queue, actions, observation, strategy, limit = 256) {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new Error("maxQueuedActions must be a positive safe integer");
+  if ((strategy === "replace" ? 0 : queue.length) + actions.length > limit) throw new Error(`Policy action queue exceeds maxQueuedActions (${limit})`);
   if (strategy === "replace") {
     queue.splice(0, queue.length);
   }
@@ -7428,7 +7893,6 @@ function usePolicy(config) {
   const clearQueue = useCallback(() => {
     epochRef.current += 1;
     actionQueueRef.current.splice(0, actionQueueRef.current.length);
-    inFlightRef.current = false;
     lastErrorRef.current = null;
   }, []);
   const reset = useCallback(() => {
@@ -7437,6 +7901,13 @@ function usePolicy(config) {
     lastObservationRef.current = null;
     lastActionRef.current = null;
   }, [clearQueue]);
+  useEffect(() => {
+    isRunningRef.current = configRef.current.enabled ?? true;
+    return () => {
+      epochRef.current++;
+      isRunningRef.current = false;
+    };
+  }, []);
   useBeforePhysicsStep(({ model, data }) => {
     if (!isRunningRef.current) return;
     const cfg = configRef.current;
@@ -7469,7 +7940,8 @@ function usePolicy(config) {
             actionQueueRef.current,
             toPolicyActions(output),
             observation,
-            cfg.queueStrategy ?? "append"
+            cfg.queueStrategy ?? "append",
+            cfg.maxQueuedActions
           );
           lastErrorRef.current = null;
         }).catch((error) => {
@@ -7477,7 +7949,6 @@ function usePolicy(config) {
           lastErrorRef.current = error;
           cfg.onError?.(error);
         }).finally(() => {
-          if (epoch !== epochRef.current) return;
           inFlightRef.current = false;
         });
       } else {
@@ -7487,7 +7958,8 @@ function usePolicy(config) {
             actionQueueRef.current,
             actions,
             observation,
-            cfg.queueStrategy ?? "append"
+            cfg.queueStrategy ?? "append",
+            cfg.maxQueuedActions
           );
         } else {
           const [action, ...queuedActions2] = actions;
@@ -7496,7 +7968,8 @@ function usePolicy(config) {
             actionQueueRef.current,
             queuedActions2,
             observation,
-            cfg.queueStrategy ?? "append"
+            cfg.queueStrategy ?? "append",
+            cfg.maxQueuedActions
           );
           cfg.onAction({ action, observation, model, data });
           lastActionRef.current = action;
@@ -8197,125 +8670,6 @@ 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,
@@ -8838,6 +9192,18 @@ function useCameraAnimation() {
  * @license
  * SPDX-License-Identifier: Apache-2.0
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Helpers for resolving dataset camera streams to mounted MuJoCo resources.
+ */
+/**
+ * @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
@@ -8861,12 +9227,6 @@ function useCameraAnimation() {
  *
  * useFrameCapture — still-frame capture for canvas-backed MuJoCo/R3F scenes.
  */
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- *
- * Helpers for resolving dataset camera streams to mounted MuJoCo resources.
- */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -8907,16 +9267,9 @@ function useCameraAnimation() {
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
- * Stream a live MuJoCo camera into a DOM `<canvas>`. Each frame the scene is
- * rendered offscreen from the selected camera and blitted into the canvas, so
- * it composites normally in the DOM (works inside opaque panels) and does NOT
- * take over the render loop. Prefer this over `useCameraViewport` for camera
- * tiles embedded in HTML UI; use `useCameraViewport` for transparent overlays
- * on a full-bleed canvas.
- *
- * Uses the async capture path so Gaussian-splat environments render through
- * their dedicated capture renderer — streaming a splat scene at full rate does
- * not disturb the main view's splat sort.
+ * Readback stream for DOM compositing/encoding. For interactive camera previews,
+ * use CameraView/useCameraViewport: they render on the GPU with no readback.
+ * This path defaults to 10 FPS and permits only one capture in flight.
  */
 /**
  * @license
@@ -9071,12 +9424,6 @@ 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