mujoco-react 9.2.0 → 9.4.0

package/dist/index.js

@@ -1,4 +1,5 @@
-export { ScenarioLighting, SplatEnvironment, VisualScenarioEffects, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getScenarioBackground, getScenarioCameraPosition, useSplatEnvironment, useVisualScenarioEffects, withSplatEnvironment } from './chunk-33CV6HSV.js';
+import { withContacts, getContact } from './chunk-VDSEPZYQ.js';
+export { RobotActuators, RobotBodies, RobotCameras, RobotGeoms, RobotJoints, RobotKeyframes, RobotResources, RobotSensors, RobotSites, ScenarioLighting, SplatEnvironment, SplatEnvironmentReadinessStatus, VisualScenarioEffects, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, createSplatSceneConfig, createVisualScenarioExecutionContext, getContact, getScenarioBackground, getScenarioCameraPosition, getSplatEnvironmentReadiness, registerRobotResources, useSplatEnvironment, useSplatSceneConfig, useVisualScenarioEffects, useVisualScenarioExecutionContext, withSplatEnvironment } from './chunk-VDSEPZYQ.js';
 import loadMujoco from '@mujoco/mujoco';
 import defaultMujocoWasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
 import { createContext, forwardRef, useEffect, useContext, useState, useRef, useCallback, useMemo, useLayoutEffect } from 'react';
@@ -104,80 +105,6 @@ function MujocoProvider({
     }
   );
 }
-
-// src/types.ts
-var runtimeRobotResources = {};
-var REGISTER_RESOURCE_KEYS = ["actuators", "sensors", "bodies", "joints", "sites", "geoms", "keyframes"];
-function createEmptyRuntimeResources() {
-  return {
-    actuators: {},
-    sensors: {},
-    bodies: {},
-    joints: {},
-    sites: {},
-    geoms: {},
-    keyframes: {}
-  };
-}
-function registerRobotResources(resources) {
-  for (const [robot, robotResources] of Object.entries(resources)) {
-    const existing = runtimeRobotResources[robot] ?? createEmptyRuntimeResources();
-    for (const key of REGISTER_RESOURCE_KEYS) {
-      existing[key] = { ...existing[key], ...robotResources[key] ?? {} };
-    }
-    runtimeRobotResources[robot] = existing;
-  }
-}
-function createResourceCategory(key) {
-  return new Proxy({}, {
-    get(_target, robot) {
-      if (typeof robot !== "string") return void 0;
-      return runtimeRobotResources[robot]?.[key] ?? {};
-    },
-    ownKeys() {
-      return Reflect.ownKeys(runtimeRobotResources);
-    },
-    getOwnPropertyDescriptor(_target, robot) {
-      if (typeof robot !== "string" || !(robot in runtimeRobotResources)) return void 0;
-      return { enumerable: true, configurable: true };
-    }
-  });
-}
-var RobotResources = new Proxy(runtimeRobotResources, {
-  get(target, robot) {
-    if (typeof robot !== "string") return void 0;
-    return target[robot] ?? createEmptyRuntimeResources();
-  },
-  ownKeys(target) {
-    return Reflect.ownKeys(target);
-  },
-  getOwnPropertyDescriptor(target, robot) {
-    if (typeof robot !== "string" || !(robot in target)) return void 0;
-    return { enumerable: true, configurable: true };
-  }
-});
-var RobotActuators = createResourceCategory("actuators");
-var RobotSensors = createResourceCategory("sensors");
-var RobotBodies = createResourceCategory("bodies");
-var RobotJoints = createResourceCategory("joints");
-var RobotSites = createResourceCategory("sites");
-var RobotGeoms = createResourceCategory("geoms");
-var RobotKeyframes = createResourceCategory("keyframes");
-function getContact(contacts, i) {
-  try {
-    return contacts.get(i);
-  } catch {
-    return void 0;
-  }
-}
-function withContacts(data, read) {
-  const contacts = data.contact;
-  try {
-    return read(contacts);
-  } finally {
-    contacts.delete?.();
-  }
-}
 var CapsuleGeometry = class extends THREE12.BufferGeometry {
   parameters;
   constructor(radius = 1, length = 1, capSegments = 4, radialSegments = 8) {
@@ -480,6 +407,15 @@ function findSensorByName(mjModel, name) {
   }
   return -1;
 }
+function findCameraByName(mjModel, name) {
+  const ncam = mjModel.ncam ?? 0;
+  const addresses = mjModel.name_camadr;
+  if (!addresses) return -1;
+  for (let i = 0; i < ncam; i++) {
+    if (getName(mjModel, addresses[i]) === name) return i;
+  }
+  return -1;
+}
 function findTendonByName(mjModel, name) {
   for (let i = 0; i < (mjModel.ntendon ?? 0); i++) {
     if (getName(mjModel, mjModel.name_tendonadr[i]) === name) return i;
@@ -1439,17 +1375,32 @@ function createCaptureCamera(options, fallbackCamera, width, height) {
   applyCameraPose(camera, options, fallbackCamera);
   return camera;
 }
-function readRenderTargetToCanvas(renderer, target, width, height) {
-  const pixels = new Uint8Array(width * height * 4);
-  renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
-  const canvas = document.createElement("canvas");
-  canvas.width = width;
-  canvas.height = height;
-  const context = canvas.getContext("2d");
-  if (!context) {
-    throw new Error("Unable to create a 2D canvas for camera frame capture.");
+function getCaptureDimensions(renderer, options) {
+  const width = Math.max(
+    1,
+    Math.floor(options.width ?? renderer.domElement.width)
+  );
+  const height = Math.max(
+    1,
+    Math.floor(options.height ?? renderer.domElement.height)
+  );
+  return { width, height };
+}
+function prepareCaptureCamera(camera, options, fallbackCamera, width, height) {
+  if (options.camera) {
+    camera.copy(options.camera);
+  }
+  if (camera instanceof THREE12.PerspectiveCamera) {
+    camera.aspect = width / height;
+    camera.fov = options.fov ?? camera.fov;
+    camera.near = options.near ?? camera.near;
+    camera.far = options.far ?? camera.far;
+    camera.updateProjectionMatrix();
   }
-  const imageData = context.createImageData(width, height);
+  applyCameraPose(camera, options, fallbackCamera);
+}
+function readRenderTargetToCanvas(renderer, target, canvas, context, pixels, imageData, width, height) {
+  renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
   const rowBytes = width * 4;
   for (let y = 0; y < height; y += 1) {
     const sourceStart = (height - y - 1) * rowBytes;
@@ -1462,28 +1413,133 @@ function readRenderTargetToCanvas(renderer, target, width, height) {
   context.putImageData(imageData, 0, 0);
   return canvas;
 }
-function renderCameraFrameToCanvas(renderer, scene, fallbackCamera, options = {}) {
-  const width = Math.max(1, Math.floor(options.width ?? renderer.domElement.width));
-  const height = Math.max(1, Math.floor(options.height ?? renderer.domElement.height));
+function getCameraFrameCaptureSource(options) {
+  if (options.source) return options.source;
+  if (options.cameraName) {
+    return { kind: "mujoco-camera", cameraName: options.cameraName };
+  }
+  if (options.siteName) {
+    return { kind: "mujoco-site", siteName: options.siteName };
+  }
+  if (options.bodyName) {
+    return { kind: "mujoco-body", bodyName: options.bodyName };
+  }
+  if (options.camera) return { kind: "custom-camera" };
+  if (options.position || options.lookAt || options.quaternion) {
+    return { kind: "explicit-pose" };
+  }
+  return { kind: "fallback-camera" };
+}
+function createCameraFrameCaptureSession(renderer, scene, fallbackCamera, options = {}) {
+  const { width, height } = getCaptureDimensions(renderer, options);
   const camera = createCaptureCamera(options, fallbackCamera, width, height);
   const target = new THREE12.WebGLRenderTarget(width, height, {
     format: THREE12.RGBAFormat,
     type: THREE12.UnsignedByteType
   });
-  const previousTarget = renderer.getRenderTarget();
-  const previousXrEnabled = renderer.xr.enabled;
-  scene.updateMatrixWorld(true);
+  const canvas = document.createElement("canvas");
+  canvas.width = width;
+  canvas.height = height;
+  const context = canvas.getContext("2d");
+  if (!context) {
+    target.dispose();
+    throw new Error("Unable to create a 2D canvas for camera frame capture.");
+  }
+  const drawContext = context;
+  const pixels = new Uint8Array(width * height * 4);
+  const imageData = drawContext.createImageData(width, height);
+  function capture(nextOptions = {}) {
+    const captureOptions = { ...options, ...nextOptions };
+    const nextDimensions = getCaptureDimensions(renderer, captureOptions);
+    if (nextDimensions.width !== width || nextDimensions.height !== height) {
+      throw new Error(
+        "Camera frame capture sessions require stable width and height."
+      );
+    }
+    prepareCaptureCamera(
+      camera,
+      captureOptions,
+      fallbackCamera,
+      width,
+      height
+    );
+    const previousTarget = renderer.getRenderTarget();
+    const previousXrEnabled = renderer.xr.enabled;
+    scene.updateMatrixWorld(true);
+    try {
+      renderer.xr.enabled = false;
+      renderer.setRenderTarget(target);
+      renderer.clear();
+      renderer.render(scene, camera);
+      readRenderTargetToCanvas(
+        renderer,
+        target,
+        canvas,
+        drawContext,
+        pixels,
+        imageData,
+        width,
+        height
+      );
+      return {
+        canvas,
+        camera,
+        width,
+        height,
+        source: getCameraFrameCaptureSource(captureOptions)
+      };
+    } finally {
+      renderer.setRenderTarget(previousTarget);
+      renderer.xr.enabled = previousXrEnabled;
+    }
+  }
+  return {
+    width,
+    height,
+    capture,
+    captureDataUrl(nextOptions = {}) {
+      const type = nextOptions.type ?? options.type ?? "image/png";
+      const result = capture(nextOptions);
+      return {
+        ...result,
+        dataUrl: result.canvas.toDataURL(
+          type,
+          nextOptions.quality ?? options.quality
+        ),
+        type
+      };
+    },
+    async captureBlob(nextOptions = {}) {
+      const type = nextOptions.type ?? options.type ?? "image/png";
+      const result = capture(nextOptions);
+      const blob = await new Promise((resolve, reject) => {
+        result.canvas.toBlob(
+          (nextBlob) => {
+            if (nextBlob) resolve(nextBlob);
+            else reject(new Error("Camera frame capture did not produce a Blob."));
+          },
+          type,
+          nextOptions.quality ?? options.quality
+        );
+      });
+      return { ...result, blob, type };
+    },
+    dispose() {
+      target.dispose();
+    }
+  };
+}
+function renderCameraFrameToCanvas(renderer, scene, fallbackCamera, options = {}) {
+  const session = createCameraFrameCaptureSession(
+    renderer,
+    scene,
+    fallbackCamera,
+    options
+  );
   try {
-    renderer.xr.enabled = false;
-    renderer.setRenderTarget(target);
-    renderer.clear();
-    renderer.render(scene, camera);
-    const canvas = readRenderTargetToCanvas(renderer, target, width, height);
-    return { canvas, camera, width, height };
+    return session.capture();
   } finally {
-    renderer.setRenderTarget(previousTarget);
-    renderer.xr.enabled = previousXrEnabled;
-    target.dispose();
+    session.dispose();
   }
 }
 async function captureCameraFrame(renderer, scene, fallbackCamera, options = {}) {
@@ -1520,6 +1576,396 @@ async function captureCameraFrameBlob(renderer, scene, fallbackCamera, options =
   });
   return { ...result, blob, type };
 }
+
+// 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 };
+  }
+  if (selector.siteName) {
+    return { kind: "mujoco-site", siteName: selector.siteName };
+  }
+  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 (normalizedResource.startsWith(`${normalizedKey}_`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Prefix;
+    }
+    if (normalizedResource.endsWith(`_${normalizedKey}`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Suffix;
+    }
+    if (normalizedResource.includes(`_${normalizedKey}_`)) {
+      return MountedCameraFrameSourceSuggestionMatch.Contains;
+    }
+  }
+  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 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;
+}
+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]);
+  const candidates = [...directCandidates, ...aliasCandidates];
+  for (const selector of candidates) {
+    if (!isSelectorMounted(selector, cameraNames, siteNames, bodyNames)) {
+      continue;
+    }
+    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 };
+    }
+  }
+  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
+    });
+  }
+  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 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 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
+    };
+    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 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
+  });
+  return {
+    ...result,
+    plan,
+    readiness
+  };
+}
 var JOINT_TYPE_NAMES2 = ["free", "ball", "slide", "hinge"];
 var GEOM_TYPE_NAMES = ["plane", "hfield", "sphere", "capsule", "ellipsoid", "cylinder", "box", "mesh"];
 var SENSOR_TYPE_NAMES = {
@@ -1602,6 +2048,72 @@ function waitForNextAnimationFrame2() {
     requestAnimationFrame(() => resolve());
   });
 }
+function throwIfCameraSequenceAborted(signal) {
+  if (!signal?.aborted) return;
+  if (typeof signal.reason === "object" && signal.reason instanceof Error) {
+    throw signal.reason;
+  }
+  throw new DOMException("Camera sequence recording was aborted.", "AbortError");
+}
+function vector3FromArray(values, offset) {
+  return [values[offset], values[offset + 1], values[offset + 2]];
+}
+function quaternionFromArray(values, offset) {
+  return [
+    values[offset],
+    values[offset + 1],
+    values[offset + 2],
+    values[offset + 3]
+  ];
+}
+function quaternionFromXmat(values, offset) {
+  const matrix = new THREE12.Matrix4();
+  matrix.set(
+    values[offset],
+    values[offset + 1],
+    values[offset + 2],
+    0,
+    values[offset + 3],
+    values[offset + 4],
+    values[offset + 5],
+    0,
+    values[offset + 6],
+    values[offset + 7],
+    values[offset + 8],
+    0,
+    0,
+    0,
+    0,
+    1
+  );
+  const quaternion = new THREE12.Quaternion().setFromRotationMatrix(matrix);
+  return [quaternion.x, quaternion.y, quaternion.z, quaternion.w];
+}
+function omitResolvedCameraSelectors(options) {
+  const { cameraName, siteName, bodyName, ...rest } = options;
+  return rest;
+}
+function countMountedCameraSelectors(options) {
+  return Number(Boolean(options.cameraName)) + Number(Boolean(options.siteName)) + Number(Boolean(options.bodyName));
+}
+function assertMatchingMountedCameraSource(key, requested, source) {
+  const selectorCount = countMountedCameraSelectors(requested);
+  if (selectorCount !== 1) {
+    throw new Error(
+      `Camera sequence stream "${key}" must provide exactly one mounted MuJoCo cameraName, siteName, or bodyName selector.`
+    );
+  }
+  if (!isMountedCameraFrameCaptureSource(source)) {
+    throw new Error(
+      `Camera sequence stream "${key}" resolved to ${source.kind}; use a MuJoCo-mounted camera, site, or body selector for sequence recording.`
+    );
+  }
+  if (requested.cameraName && (source.kind !== "mujoco-camera" || source.cameraName !== requested.cameraName) || requested.siteName && (source.kind !== "mujoco-site" || source.siteName !== requested.siteName) || requested.bodyName && (source.kind !== "mujoco-body" || source.bodyName !== requested.bodyName)) {
+    throw new Error(
+      `Camera sequence stream "${key}" resolved to ${source.kind}:${getCameraFrameCaptureSourceTarget(source)} instead of the requested mounted selector.`
+    );
+  }
+}
 var MujocoSimContext = createContext(null);
 function useMujocoContext() {
   const ctx = useContext(MujocoSimContext);
@@ -1721,6 +2233,9 @@ function MujocoSimProvider({
   useEffect(() => {
     configRef.current = config;
   }, [config]);
+  useEffect(() => {
+    mujocoRef.current = mujoco;
+  }, [mujoco]);
   useEffect(() => {
     pausedRef.current = paused ?? false;
   }, [paused]);
@@ -1768,6 +2283,7 @@ function MujocoSimProvider({
           result.mjData.delete();
           return;
         }
+        mujocoRef.current = mujoco;
         mjModelRef.current = result.mjModel;
         mjDataRef.current = result.mjData;
         physicsAccumulatorRef.current = 0;
@@ -1833,7 +2349,7 @@ function MujocoSimProvider({
     if (!interpolateRef.current) {
       if (stepsToRunRef.current > 0) {
         for (let s = 0; s < stepsToRunRef.current; s++) {
-          mujoco.mj_step(model, data);
+          mujocoRef.current.mj_step(model, data);
         }
         stepsToRunRef.current = 0;
       } else {
@@ -1842,7 +2358,7 @@ function MujocoSimProvider({
         const frameTime = clampedDelta * speedRef.current;
         while (data.time - startSimTime < frameTime) {
           for (let s = 0; s < numSubsteps; s++) {
-            mujoco.mj_step(model, data);
+            mujocoRef.current.mj_step(model, data);
           }
         }
       }
@@ -1850,7 +2366,7 @@ function MujocoSimProvider({
       ensureInterpolationBuffers(model);
       copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
       for (let s = 0; s < stepsToRunRef.current; s++) {
-        mujoco.mj_step(model, data);
+        mujocoRef.current.mj_step(model, data);
       }
       copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
       interpolationStateRef.current.alpha = 1;
@@ -1865,7 +2381,7 @@ function MujocoSimProvider({
       while (physicsAccumulatorRef.current >= stepDt) {
         copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
         for (let s = 0; s < numSubsteps; s++) {
-          mujoco.mj_step(model, data);
+          mujocoRef.current.mj_step(model, data);
         }
         copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
         physicsAccumulatorRef.current -= stepDt;
@@ -1904,7 +2420,7 @@ function MujocoSimProvider({
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return;
-    mujoco.mj_resetData(model, data);
+    mujocoRef.current.mj_resetData(model, data);
     const homeJoints = configRef.current.homeJoints;
     if (homeJoints) {
       const homeCount = Math.min(homeJoints.length, model.nu);
@@ -1917,7 +2433,7 @@ function MujocoSimProvider({
       }
     }
     configRef.current.onReset?.({ model, data });
-    mujoco.mj_forward(model, data);
+    mujocoRef.current.mj_forward(model, data);
     for (const cb of resetCallbacks.current) {
       cb();
     }
@@ -1935,7 +2451,7 @@ function MujocoSimProvider({
   const step = useCallback((n = 1) => {
     stepsToRunRef.current = n;
   }, []);
-  const stepImmediately = useCallback((steps = 1) => {
+  useCallback((steps = 1) => {
     const model = mjModelRef.current;
     const data = mjDataRef.current;
     if (!model || !data) return false;
@@ -1946,7 +2462,7 @@ function MujocoSimProvider({
       for (const cb of beforeStepCallbacks.current) {
         cb({ model, data });
       }
-      mujoco.mj_step(model, data);
+      mujocoRef.current.mj_step(model, data);
       for (const cb of afterStepCallbacks.current) {
         cb({ model, data });
       }
@@ -1984,7 +2500,7 @@ function MujocoSimProvider({
     data.ctrl.set(snapshot.ctrl);
     if (snapshot.act.length > 0) data.act.set(snapshot.act);
     data.qfrc_applied.set(snapshot.qfrc_applied);
-    mujoco.mj_forward(model, data);
+    mujocoRef.current.mj_forward(model, data);
   }, [mujoco]);
   const setQpos = useCallback((values) => {
     const model = mjModelRef.current;
@@ -1992,7 +2508,7 @@ function MujocoSimProvider({
     if (!model || !data) return;
     const arr = values instanceof Float64Array ? values : new Float64Array(values);
     data.qpos.set(arr.subarray(0, Math.min(arr.length, model.nq)));
-    mujoco.mj_forward(model, data);
+    mujocoRef.current.mj_forward(model, data);
   }, [mujoco]);
   const setQvel = useCallback((values) => {
     const data = mjDataRef.current;
@@ -2227,6 +2743,88 @@ function MujocoSimProvider({
     }
     return result;
   }, []);
+  const getCameras = useCallback(() => {
+    const model = mjModelRef.current;
+    if (!model) return [];
+    const ncam = model.ncam ?? 0;
+    const nameAddresses = model.name_camadr;
+    if (!ncam || !nameAddresses) return [];
+    const result = [];
+    for (let i = 0; i < ncam; i += 1) {
+      const posOffset = i * 3;
+      const quatOffset = i * 4;
+      result.push({
+        id: i,
+        name: getName(model, nameAddresses[i]),
+        bodyId: model.cam_bodyid?.[i] ?? -1,
+        fov: model.cam_fovy?.[i] ?? null,
+        position: model.cam_pos ? vector3FromArray(model.cam_pos, posOffset) : null,
+        quaternion: model.cam_quat ? quaternionFromArray(model.cam_quat, quatOffset) : null
+      });
+    }
+    return result;
+  }, []);
+  const resolveCameraCaptureOptions = useCallback(
+    (options = {}) => {
+      const model = mjModelRef.current;
+      const data = mjDataRef.current;
+      if (!model || !data) {
+        return options;
+      }
+      const baseOptions = omitResolvedCameraSelectors(options);
+      if (options.cameraName) {
+        const cameraId = findCameraByName(model, options.cameraName);
+        if (cameraId < 0) {
+          throw new Error(`MuJoCo camera "${options.cameraName}" was not found.`);
+        }
+        const position = data.cam_xpos ? vector3FromArray(data.cam_xpos, cameraId * 3) : model.cam_pos ? vector3FromArray(model.cam_pos, cameraId * 3) : void 0;
+        const quaternion = data.cam_xmat ? quaternionFromXmat(data.cam_xmat, cameraId * 9) : model.cam_quat ? quaternionFromArray(model.cam_quat, cameraId * 4) : void 0;
+        if (!position || !quaternion) {
+          throw new Error(
+            `MuJoCo camera "${options.cameraName}" does not expose a capture pose.`
+          );
+        }
+        return {
+          ...baseOptions,
+          position,
+          quaternion,
+          fov: options.fov ?? model.cam_fovy?.[cameraId],
+          source: { kind: "mujoco-camera", cameraName: options.cameraName }
+        };
+      }
+      if (options.siteName) {
+        const siteId = findSiteByName(model, options.siteName);
+        if (siteId < 0) {
+          throw new Error(`MuJoCo site "${options.siteName}" was not found.`);
+        }
+        return {
+          ...baseOptions,
+          position: vector3FromArray(data.site_xpos, siteId * 3),
+          quaternion: quaternionFromXmat(data.site_xmat, siteId * 9),
+          source: { kind: "mujoco-site", siteName: options.siteName }
+        };
+      }
+      if (options.bodyName) {
+        const bodyId = findBodyByName(model, options.bodyName);
+        if (bodyId < 0) {
+          throw new Error(`MuJoCo body "${options.bodyName}" was not found.`);
+        }
+        if (!data.xmat) {
+          throw new Error(
+            `MuJoCo body "${options.bodyName}" does not expose world orientation data.`
+          );
+        }
+        return {
+          ...baseOptions,
+          position: vector3FromArray(data.xpos, bodyId * 3),
+          quaternion: quaternionFromXmat(data.xmat, bodyId * 9),
+          source: { kind: "mujoco-body", bodyName: options.bodyName }
+        };
+      }
+      return options;
+    },
+    []
+  );
   const getModelOption = useCallback(() => {
     const model = mjModelRef.current;
     if (!model?.opt) return { timestep: 2e-3, gravity: [0, 0, -9.81], integrator: 0 };
@@ -2303,7 +2901,7 @@ function MujocoSimProvider({
       const qvelOffset = keyId * model.nv;
       for (let i = 0; i < model.nv; i++) data.qvel[i] = model.key_qvel[qvelOffset + i];
     }
-    mujoco.mj_forward(model, data);
+    mujocoRef.current.mj_forward(model, data);
     for (const cb of resetCallbacks.current) {
       cb();
     }
@@ -2414,67 +3012,187 @@ function MujocoSimProvider({
   );
   const captureCameraFrameApi = useCallback(
     (options = {}) => {
-      return captureCameraFrame(gl, scene, camera, options);
+      return captureCameraFrame(
+        gl,
+        scene,
+        camera,
+        resolveCameraCaptureOptions(options)
+      );
     },
-    [camera, gl, scene]
+    [camera, gl, resolveCameraCaptureOptions, scene]
   );
   const captureCameraFrameBlobApi = useCallback(
     (options = {}) => {
-      return captureCameraFrameBlob(gl, scene, camera, options);
+      return captureCameraFrameBlob(
+        gl,
+        scene,
+        camera,
+        resolveCameraCaptureOptions(options)
+      );
     },
-    [camera, gl, scene]
+    [camera, gl, resolveCameraCaptureOptions, scene]
   );
   const recordCameraSequenceApi = useCallback(
     async (options) => {
       const frameCount = Math.max(0, Math.floor(options.frames));
-      const stepsPerFrame = Math.max(1, Math.floor(options.stepsPerFrame ?? 1));
+      const stepsPerFrame = Math.max(0, Math.floor(options.stepsPerFrame ?? 1));
       const cameras = options.cameras;
       const frames = [];
+      const cameraSummaries = {};
       const wasPaused = pausedRef.current;
+      const retainFrames = options.retainFrames ?? true;
+      const requireMountedSources = options.requireMountedSources ?? true;
+      let recordedFrameCount = 0;
+      async function stepCameraSequence(frameIndex, steps) {
+        const model = mjModelRef.current;
+        const data = mjDataRef.current;
+        if (!model || !data) {
+          throw new Error("MuJoCo scene is not ready for camera sequence stepping.");
+        }
+        for (let stepIndex = 0; stepIndex < steps; stepIndex += 1) {
+          for (let i = 0; i < model.nv; i += 1) {
+            data.qfrc_applied[i] = 0;
+          }
+          await options.onBeforeStep?.({
+            frameIndex,
+            stepIndex,
+            time: data.time,
+            model,
+            data
+          });
+          for (const cb of beforeStepCallbacks.current) {
+            cb({ model, data });
+          }
+          mujocoRef.current.mj_step(model, data);
+          for (const cb of afterStepCallbacks.current) {
+            cb({ model, data });
+          }
+          onStepRef.current?.({ time: data.time, model, data });
+          await options.onAfterStep?.({
+            frameIndex,
+            stepIndex,
+            time: data.time,
+            model,
+            data
+          });
+        }
+        physicsAccumulatorRef.current = 0;
+        interpolationStateRef.current.valid = false;
+      }
       if (frameCount === 0 || cameras.length === 0) {
         return {
           frames,
           cameraKeys: cameras.map((sequenceCamera) => sequenceCamera.key),
+          cameraSummaries,
           frameCount: 0
         };
       }
+      throwIfCameraSequenceAborted(options.signal);
+      for (let attempt = 0; attempt < 30; attempt += 1) {
+        if (mjModelRef.current && mjDataRef.current) break;
+        await waitForNextAnimationFrame2();
+        throwIfCameraSequenceAborted(options.signal);
+      }
+      if (!mjModelRef.current || !mjDataRef.current) {
+        throw new Error("MuJoCo scene is not ready for camera sequence recording.");
+      }
+      const captureSessions = cameras.map((sequenceCamera) => {
+        const { key, ...captureOptions } = sequenceCamera;
+        const initialCaptureOptions = resolveCameraCaptureOptions(captureOptions);
+        const mountedSource = initialCaptureOptions.source;
+        if (requireMountedSources) {
+          assertMatchingMountedCameraSource(
+            key,
+            captureOptions,
+            mountedSource ?? { kind: "fallback-camera" }
+          );
+        }
+        return {
+          key,
+          captureOptions,
+          mountedSource,
+          session: createCameraFrameCaptureSession(
+            gl,
+            scene,
+            camera,
+            initialCaptureOptions
+          )
+        };
+      });
       try {
         pausedRef.current = true;
         stepsToRunRef.current = 0;
         if (options.reset) reset();
         for (let frameIndex = 0; frameIndex < frameCount; frameIndex += 1) {
-          if (frameIndex > 0 || options.captureInitialFrame === false) {
-            stepImmediately(stepsPerFrame);
+          throwIfCameraSequenceAborted(options.signal);
+          if (stepsPerFrame > 0 && (frameIndex > 0 || options.captureInitialFrame === false)) {
+            await stepCameraSequence(frameIndex, stepsPerFrame);
           }
           await waitForNextAnimationFrame2();
+          throwIfCameraSequenceAborted(options.signal);
+          const model = mjModelRef.current;
+          const data = mjDataRef.current;
+          if (!model || !data) {
+            throw new Error("MuJoCo scene is not ready for camera sequence sampling.");
+          }
+          await options.onSample?.({
+            frameIndex,
+            time: data.time,
+            model,
+            data
+          });
           const cameraFrames = {};
-          for (const sequenceCamera of cameras) {
-            const { key, ...captureOptions } = sequenceCamera;
-            cameraFrames[key] = await captureCameraFrame(
-              gl,
-              scene,
-              camera,
-              captureOptions
-            );
+          for (const { key, captureOptions, mountedSource, session } of captureSessions) {
+            const resolvedCaptureOptions = resolveCameraCaptureOptions(captureOptions);
+            const cameraFrame = session.captureDataUrl({
+              ...resolvedCaptureOptions,
+              source: mountedSource ?? resolvedCaptureOptions.source
+            });
+            if (requireMountedSources) {
+              assertMatchingMountedCameraSource(
+                key,
+                captureOptions,
+                cameraFrame.source
+              );
+            }
+            cameraSummaries[key] = {
+              key,
+              width: cameraFrame.width,
+              height: cameraFrame.height,
+              source: cameraFrame.source,
+              frameCount: (cameraSummaries[key]?.frameCount ?? 0) + 1,
+              firstFrameIndex: cameraSummaries[key]?.firstFrameIndex ?? frameIndex,
+              lastFrameIndex: frameIndex,
+              firstTimestamp: cameraSummaries[key]?.firstTimestamp ?? data.time,
+              lastTimestamp: data.time
+            };
+            cameraFrames[key] = cameraFrame;
           }
           const frame = {
             frameIndex,
-            time: getTime(),
+            time: data.time,
             cameras: cameraFrames
           };
-          frames.push(frame);
+          if (retainFrames) {
+            frames.push(frame);
+          }
+          recordedFrameCount += 1;
           await options.onFrame?.(frame);
         }
       } finally {
+        for (const { session } of captureSessions) {
+          session.dispose();
+        }
         pausedRef.current = wasPaused;
       }
       return {
         frames,
         cameraKeys: cameras.map((sequenceCamera) => sequenceCamera.key),
-        frameCount: frames.length
+        cameraSummaries,
+        frameCount: recordedFrameCount
       };
     },
-    [camera, getTime, gl, reset, scene, stepImmediately]
+    [camera, getTime, gl, mujoco, reset, resolveCameraCaptureOptions, scene]
   );
   const project2DTo3D = useCallback(
     (x, y, cameraPos, lookAt) => {
@@ -2571,6 +3289,7 @@ function MujocoSimProvider({
       getSites,
       getActuators: getActuatorsApi,
       getSensors,
+      getCameras,
       getModelOption,
       setGravity,
       setTimestep: setTimestepApi,
@@ -2629,6 +3348,7 @@ function MujocoSimProvider({
       getSites,
       getActuatorsApi,
       getSensors,
+      getCameras,
       getModelOption,
       setGravity,
       setTimestepApi,
@@ -3847,6 +4567,231 @@ function SceneLights({ intensity = 1 }) {
   useSceneLights(intensity);
   return null;
 }
+function SplatCollisionProxyPreview({
+  collisionProxy,
+  xmlText,
+  fetchXml = fetchSplatCollisionProxyXml,
+  color = "#60a5fa",
+  opacity = 0.12,
+  planeColor = "#94a3b8",
+  planeOpacity = 0.08,
+  children,
+  ...groupProps
+}) {
+  const { geoms } = useSplatCollisionProxyGeoms({
+    collisionProxy,
+    xmlText,
+    fetchXml
+  });
+  if (geoms.length === 0 && !children) return null;
+  return /* @__PURE__ */ jsxs(
+    "group",
+    {
+      ...groupProps,
+      userData: {
+        kind: "splat-collision-proxy-preview",
+        ...groupProps.userData
+      },
+      children: [
+        geoms.map((geom) => /* @__PURE__ */ jsx(
+          SplatCollisionProxyGeom,
+          {
+            geom,
+            color,
+            opacity,
+            planeColor,
+            planeOpacity
+          },
+          geom.id
+        )),
+        children
+      ]
+    }
+  );
+}
+function useSplatCollisionProxyGeoms({
+  collisionProxy,
+  xmlText,
+  fetchXml = fetchSplatCollisionProxyXml,
+  enabled = true
+}) {
+  const [loadedXmlText, setLoadedXmlText] = useState(null);
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const xmlPath = collisionProxy?.xmlPath;
+  useEffect(() => {
+    let cancelled = false;
+    if (!enabled) {
+      setLoadedXmlText(null);
+      setStatus("idle");
+      setError(null);
+      return void 0;
+    }
+    if (xmlText) {
+      setLoadedXmlText(xmlText);
+      setStatus("ready");
+      setError(null);
+      return void 0;
+    }
+    if (!xmlPath || !canFetchSplatCollisionProxyXml(xmlPath)) {
+      setLoadedXmlText(null);
+      setStatus("idle");
+      setError(null);
+      return void 0;
+    }
+    const fetchPath = xmlPath;
+    async function loadProxyXml() {
+      setStatus("loading");
+      setError(null);
+      try {
+        const nextXmlText = await fetchXml(fetchPath);
+        if (!cancelled) {
+          setLoadedXmlText(nextXmlText);
+          setStatus("ready");
+        }
+      } catch (nextError) {
+        if (!cancelled) {
+          setLoadedXmlText(null);
+          setStatus("error");
+          setError(
+            nextError instanceof Error ? nextError : new Error("Unable to load collision proxy XML.")
+          );
+        }
+      }
+    }
+    void loadProxyXml();
+    return () => {
+      cancelled = true;
+    };
+  }, [enabled, fetchXml, xmlPath, xmlText]);
+  const geoms = useMemo(
+    () => loadedXmlText ? parseSplatCollisionProxyGeoms(loadedXmlText) : [],
+    [loadedXmlText]
+  );
+  return useMemo(
+    () => ({
+      geoms,
+      status,
+      error,
+      xmlPath
+    }),
+    [error, geoms, status, xmlPath]
+  );
+}
+async function fetchSplatCollisionProxyXml(xmlPath) {
+  const response = await fetch(xmlPath);
+  if (!response.ok) {
+    throw new Error(`Unable to load collision proxy XML (${response.status}).`);
+  }
+  return response.text();
+}
+function canFetchSplatCollisionProxyXml(xmlPath) {
+  return xmlPath.startsWith("/") || xmlPath.startsWith("http://") || xmlPath.startsWith("https://");
+}
+function parseSplatCollisionProxyGeoms(xmlText) {
+  const parser = typeof DOMParser === "undefined" ? null : new DOMParser();
+  if (!parser) return [];
+  const document2 = parser.parseFromString(xmlText, "application/xml");
+  if (document2.querySelector("parsererror")) return [];
+  const bodyPositions = /* @__PURE__ */ new Map();
+  for (const body of Array.from(document2.querySelectorAll("body"))) {
+    const parentBody = body.parentElement?.closest("body");
+    const parentPosition = parentBody ? bodyPositions.get(parentBody) ?? [0, 0, 0] : [0, 0, 0];
+    bodyPositions.set(
+      body,
+      addProxyVectors(parentPosition, parseProxyVector(body.getAttribute("pos")))
+    );
+  }
+  return Array.from(document2.querySelectorAll("geom")).map((geom, index) => {
+    const type = getCollisionProxyGeomType(geom);
+    if (!type) return null;
+    const parentBody = geom.closest("body");
+    const bodyPosition = parentBody ? bodyPositions.get(parentBody) ?? [0, 0, 0] : [0, 0, 0];
+    const position = addProxyVectors(
+      bodyPosition,
+      parseProxyVector(geom.getAttribute("pos"))
+    );
+    const size = parseNumberList(geom.getAttribute("size"));
+    return {
+      id: geom.getAttribute("name") ?? `${type}-${index}`,
+      type,
+      position,
+      size
+    };
+  }).filter((geom) => Boolean(geom));
+}
+function SplatCollisionProxyGeom({
+  geom,
+  color,
+  opacity,
+  planeColor,
+  planeOpacity
+}) {
+  if (geom.type === "sphere") {
+    return /* @__PURE__ */ jsxs("mesh", { position: geom.position, children: [
+      /* @__PURE__ */ jsx("sphereGeometry", { args: [geom.size[0] ?? 0.1, 16, 8] }),
+      /* @__PURE__ */ jsx(SplatCollisionProxyMaterial, { color, opacity })
+    ] });
+  }
+  if (geom.type === "plane") {
+    const width = geom.size[0] && geom.size[0] > 0 ? geom.size[0] * 2 : 4;
+    const height = geom.size[1] && geom.size[1] > 0 ? geom.size[1] * 2 : 4;
+    return /* @__PURE__ */ jsxs("mesh", { position: geom.position, children: [
+      /* @__PURE__ */ jsx("boxGeometry", { args: [width, height, 0.02] }),
+      /* @__PURE__ */ jsx(SplatCollisionProxyMaterial, { color: planeColor, opacity: planeOpacity })
+    ] });
+  }
+  const size = getCollisionProxyBoxSize(geom);
+  return /* @__PURE__ */ jsxs("mesh", { position: geom.position, children: [
+    /* @__PURE__ */ jsx("boxGeometry", { args: size }),
+    /* @__PURE__ */ jsx(SplatCollisionProxyMaterial, { color, opacity })
+  ] });
+}
+function SplatCollisionProxyMaterial({
+  color,
+  opacity
+}) {
+  return /* @__PURE__ */ jsx(
+    "meshBasicMaterial",
+    {
+      color,
+      transparent: true,
+      opacity,
+      wireframe: true
+    }
+  );
+}
+function getCollisionProxyGeomType(geom) {
+  const type = geom.getAttribute("type") ?? "sphere";
+  if (type === "box" || type === "plane" || type === "sphere" || type === "capsule" || type === "mesh") {
+    return type;
+  }
+  return null;
+}
+function getCollisionProxyBoxSize(geom) {
+  if (geom.type === "capsule") {
+    const radius = geom.size[0] ?? 0.05;
+    const halfLength = geom.size[1] ?? radius;
+    return [radius * 2, radius * 2, Math.max(radius * 2, halfLength * 2)];
+  }
+  if (geom.type === "mesh") return [0.2, 0.2, 0.2];
+  return [
+    (geom.size[0] ?? 0.1) * 2,
+    (geom.size[1] ?? geom.size[0] ?? 0.1) * 2,
+    (geom.size[2] ?? geom.size[0] ?? 0.1) * 2
+  ];
+}
+function parseProxyVector(value) {
+  const values = parseNumberList(value);
+  return [values[0] ?? 0, values[1] ?? 0, values[2] ?? 0];
+}
+function parseNumberList(value) {
+  if (!value) return [];
+  return value.trim().split(/\s+/).map((part) => Number(part)).filter((part) => Number.isFinite(part));
+}
+function addProxyVectors(a, b) {
+  return [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+}
 var JOINT_COLORS = {
   0: 16711680,
   // free - red
@@ -5421,6 +6366,90 @@ function useCameraSequenceRecorder() {
     reset
   };
 }
+function useMountedCameraSequenceRecorder(defaultOptions = {}) {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState("idle");
+  const [error, setError] = useState(null);
+  const [plan, setPlan] = useState(null);
+  const [readiness, setReadiness] = useState(null);
+  const [result, setResult] = useState(
+    null
+  );
+  const reset = useCallback(() => {
+    setStatus("idle");
+    setError(null);
+    setPlan(null);
+    setReadiness(null);
+    setResult(null);
+  }, []);
+  const createPlan = useCallback(
+    (cameraKeys, options = {}) => {
+      if (!mujoco.api) {
+        throw new Error("MuJoCo scene is not ready for mounted camera sequence planning.");
+      }
+      const nextPlan = createMountedCameraFrameSequencePlanFromApi(
+        mujoco.api,
+        cameraKeys,
+        {
+          ...defaultOptions,
+          ...options
+        }
+      );
+      setPlan(nextPlan);
+      setReadiness(null);
+      return nextPlan;
+    },
+    [defaultOptions, mujoco.api]
+  );
+  const checkReadiness = useCallback(
+    (cameraKeys, options = {}) => {
+      const nextPlan = createPlan(cameraKeys, options);
+      const nextReadiness = createMountedCameraFrameSequenceReadiness(nextPlan);
+      setReadiness(nextReadiness);
+      return nextReadiness;
+    },
+    [createPlan]
+  );
+  const record = useCallback(
+    async (options) => {
+      if (!mujoco.api) {
+        throw new Error("MuJoCo scene is not ready for mounted camera sequence recording.");
+      }
+      setStatus("capturing");
+      setError(null);
+      setResult(null);
+      try {
+        const nextResult = await recordMountedCameraFrameSequence(mujoco.api, {
+          ...defaultOptions,
+          ...options
+        });
+        setPlan(nextResult.plan);
+        setReadiness(nextResult.readiness);
+        setResult(nextResult);
+        setStatus("captured");
+        return nextResult;
+      } catch (nextError) {
+        const error2 = nextError instanceof Error ? nextError : new Error("Unable to record the requested mounted camera sequence.");
+        setError(error2);
+        setStatus("error");
+        throw error2;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+  return {
+    status,
+    error,
+    plan,
+    readiness,
+    result,
+    isRecording: status === "capturing",
+    createPlan,
+    checkReadiness,
+    record,
+    reset
+  };
+}
 function useCtrlNoise(config = {}) {
   const { mjModelRef } = useMujocoContext();
   const configRef = useRef(config);
@@ -5585,6 +6614,12 @@ function useCameraAnimation() {
  *
  * Offscreen camera-frame capture for R3F/MuJoCo 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
@@ -5730,6 +6765,12 @@ function useCameraAnimation() {
  *
  * React state wrapper around fixed-camera simulation sequence recording.
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * React state wrapper for named MuJoCo camera/site/body sequence recording.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -5760,6 +6801,6 @@ function useCameraAnimation() {
  * useCameraAnimation — composable camera animation hook.
  */
 
-export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, InstancedGeomRenderer, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, RobotActuators, RobotBodies, RobotGeoms, RobotJoints, RobotKeyframes, RobotResources, RobotSensors, RobotSites, SceneLights, TendonRenderer, TrajectoryPlayer, buildObservation, captureCameraFrame, captureCameraFrameBlob, captureFrame, captureFrameBlob, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, registerRobotResources, renderCameraFrameToCanvas, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useContactEvents, useContacts, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { Body, ContactListener, ContactMarkers, Debug, DragInteraction, FlexRenderer, IkGizmo, InstancedGeomRenderer, MountedCameraFrameSequenceManifestStatus, MountedCameraFrameSequenceReadinessStatus, MountedCameraFrameSourceSuggestionMatch, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, SceneLights, SplatCollisionProxyPreview, TendonRenderer, TrajectoryPlayer, buildObservation, canFetchSplatCollisionProxyXml, captureCameraFrame, captureCameraFrameBlob, captureFrame, captureFrameBlob, createCameraFrameCaptureSession, createContiguousControlGroup, createController, createControllerHook, createMountedCameraFrameSequenceManifest, createMountedCameraFrameSequencePlan, createMountedCameraFrameSequencePlanFromApi, createMountedCameraFrameSequenceReadiness, createMountedCameraFrameSourceSuggestions, fetchSplatCollisionProxyXml, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getCameraFrameCaptureSourceTarget, getControlMap, getMountedCameraFrameCaptureSource, getName, isMountedCameraFrameCaptureSource, loadScene, parseSplatCollisionProxyGeoms, recordMountedCameraFrameSequence, renderCameraFrameToCanvas, resolveControlGroup, resolveMountedCameraFrameSource, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useCameraFrameCapture, useCameraSequenceRecorder, useContactEvents, useContacts, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMountedCameraSequenceRecorder, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useSplatCollisionProxyGeoms, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map