mujoco-react 8.10.0 → 8.11.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { M as MujocoContextValue, a as MujocoCanvasProps, b as MujocoSimAPI, S as SceneConfig, c as MujocoModule, P as PhysicsStepCallback, d as MujocoModel, e as MujocoData, C as ControlGroupInfo, A as ActuatedJointInfo, f as ControlGroupSelector, O as ObservationConfig, g as ObservationResult, I as IkConfig, h as IkContextValue, B as BodyProps, i as IkGizmoProps, D as DragInteractionProps, j as SceneLightsProps, k as ScenarioLightingProps, l as SplatEnvironmentProps, m as PairedSplatEnvironmentConfig, n as SplatFormat, o as SplatCollisionProxyConfig, p as SplatRendererKind, q as SplatCollisionPrimitive, r as ScenarioLightingPreset, V as VisualScenarioConfig, s as SplatEnvironmentMetadataInput, t as SplatEnvironmentMetadata, u as DebugProps, G as GeomInfo, v as ContactListenerProps, T as TrajectoryPlayerProps, w as ActuatorInfo, x as Sites, y as SitePositionResult, z as Sensors, E as SensorHandle, F as SensorInfo, J as Joints, H as JointStateResult, K as Bodies, L as BodyStateResult, N as Actuators, Q as CtrlHandle, R as ContactInfo, U as KeyboardTeleopConfig, W as PolicyConfig, X as ObservationHandle, Y as TrajectoryInput, Z as PlaybackState, _ as TrajectoryFrame } from './types-FFW7ykBu.js';
-export { $ as BodyInfo, a0 as ControlJointInfo, a1 as Geoms, a2 as IKSolveFn, a3 as JointInfo, a4 as KeyBinding, a5 as Keyframes, a6 as ModelOptions, a7 as MujocoContact, a8 as MujocoContactArray, a9 as ObservationLayoutItem, aa as ObservationOutput, ab as PhysicsConfig, ac as RayHit, ad as Register, ae as RegisteredRobotMap, af as ResourceSelector, ag as RobotActuators, ah as RobotBodies, ai as RobotGeoms, aj as RobotJoints, ak as RobotKeyframes, al as RobotResource, am as RobotResources, an as RobotSensors, ao as RobotSites, ap as Robots, aq as ScenarioCameraConfig, ar as SceneMarker, as as SceneObject, at as SensorResult, au as SiteInfo, av as SplatAssetConfig, aw as SplatScenarioConfig, ax as StateSnapshot, ay as TrajectoryData, az as XmlPatch, aA as getContact, aB as registerRobotResources } from './types-FFW7ykBu.js';
+import { M as MujocoContextValue, a as MujocoCanvasProps, b as MujocoSimAPI, S as SceneConfig, c as MujocoModule, P as PhysicsStepCallback, d as MujocoModel, e as MujocoData, C as ControlGroupInfo, A as ActuatedJointInfo, f as ControlGroupSelector, O as ObservationConfig, g as ObservationResult, I as IkConfig, h as IkContextValue, B as BodyProps, i as IkGizmoProps, D as DragInteractionProps, j as SceneLightsProps, k as ScenarioLightingProps, l as SplatEnvironmentProps, V as VisualScenarioEffectsProps, m as VisualScenarioConfig, n as SplatRendererKind, o as PairedSplatEnvironmentConfig, p as SplatFormat, q as SplatCollisionProxyConfig, r as SplatCollisionPrimitive, s as ScenarioLightingPreset, t as SplatEnvironmentMetadataInput, u as SplatEnvironmentMetadata, v as SplatSceneInput, w as DebugProps, G as GeomInfo, x as ContactListenerProps, T as TrajectoryPlayerProps, y as ActuatorInfo, z as Sites, E as SitePositionResult, F as Sensors, H as SensorHandle, J as SensorInfo, K as Joints, L as JointStateResult, N as Bodies, Q as BodyStateResult, R as Actuators, U as CtrlHandle, W as ContactInfo, X as KeyboardTeleopConfig, Y as PolicyConfig, Z as PolicyVector, _ as ObservationHandle, $ as TrajectoryInput, a0 as PlaybackState, a1 as TrajectoryFrame } from './types-BmneHLBM.js';
+export { a2 as BodyInfo, a3 as ControlJointInfo, a4 as Geoms, a5 as IKSolveFn, a6 as JointInfo, a7 as KeyBinding, a8 as Keyframes, a9 as ModelOptions, aa as MujocoContact, ab as MujocoContactArray, ac as ObservationLayoutItem, ad as ObservationOutput, ae as PhysicsConfig, af as PolicyActionInput, ag as PolicyInferenceInput, ah as PolicyObservationInput, ai as RayHit, aj as Register, ak as RegisteredRobotMap, al as ResourceSelector, am as RobotActuators, an as RobotBodies, ao as RobotGeoms, ap as RobotJoints, aq as RobotKeyframes, ar as RobotResource, as as RobotResources, at as RobotSensors, au as RobotSites, av as Robots, aw as ScenarioCameraConfig, ax as ScenarioMaterialConfig, ay as SceneMarker, az as SceneObject, aA as SensorResult, aB as SiteInfo, aC as SplatAssetConfig, aD as SplatScenarioConfig, aE as StateSnapshot, aF as TrajectoryData, aG as XmlPatch, aH as getContact, aI as registerRobotResources } from './types-BmneHLBM.js';
 import * as React$1 from 'react';
+import React__default from 'react';
 import { ThreeElements } from '@react-three/fiber';
 import * as THREE from 'three';
 
@@ -300,7 +301,7 @@ declare const useIkController: (config: IkConfig | null) => IkContextValue | nul
  * runs before the provider's loadScene useEffect). Bodies added/removed after
  * the initial load trigger a debounced scene reload.
  */
-declare function Body({ name, type, size, position, rgba, mass, freejoint, friction, solref, solimp, condim, children, }: BodyProps): react_jsx_runtime.JSX.Element | null;
+declare function Body({ name, type, size, position, rgba, mass, freejoint, friction, solref, solimp, condim, group, children, }: BodyProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * IkGizmo — drei PivotControls that tracks a MuJoCo site.
@@ -363,6 +364,8 @@ declare function SceneLights({ intensity }: SceneLightsProps): null;
 declare function ScenarioLighting({ preset, castShadow, intensity, }: ScenarioLightingProps): react_jsx_runtime.JSX.Element;
 declare function getScenarioBackground(preset: ScenarioLightingPreset | undefined, fallback?: string): string;
 declare function getScenarioCameraPosition(basePosition: readonly [number, number, number], scenario?: Pick<VisualScenarioConfig, 'camera'>): [number, number, number];
+declare function VisualScenarioEffects(props: VisualScenarioEffectsProps): null;
+declare function useVisualScenarioEffects({ scenario, enabled, applyBackground, applyFog, applyRenderer, applyMaterials, background, fogNear, fogFar, materialFilter, }: VisualScenarioEffectsProps): void;
 /**
  * Renderer-agnostic Gaussian splat environment boundary.
  *
@@ -370,8 +373,29 @@ declare function getScenarioCameraPosition(basePosition: readonly [number, numbe
  * Spark/GaussianSplats3D object as `children` once the app chooses a renderer,
  * and pass MuJoCo/MJCF collision proxy visuals via `collisionProxy`.
  */
-declare function SplatEnvironment({ environment, src, format, collisionProxy, collisionProxyMetadata, children, showPlaceholder, ...groupProps }: SplatEnvironmentProps): react_jsx_runtime.JSX.Element;
-declare function useSplatEnvironment({ environment, src, format, collisionProxy, }: SplatEnvironmentMetadataInput): SplatEnvironmentMetadata;
+declare function SplatEnvironment({ environment, scenario, renderer, src, format, collisionProxy, collisionProxyMetadata, children, showPlaceholder, ...groupProps }: SplatEnvironmentProps): react_jsx_runtime.JSX.Element;
+declare function useSplatEnvironment({ environment, scenario, renderer, src, format, collisionProxy, }: SplatEnvironmentMetadataInput): SplatEnvironmentMetadata;
+/**
+ * Convert a generic visual scenario splat block into a paired visual/physics
+ * environment config. Returns undefined until both the splat asset and MJCF
+ * collision proxy are present.
+ */
+declare function createPairedSplatEnvironment(scenario: Pick<VisualScenarioConfig, 'id' | 'label' | 'environment' | 'splat'>, options?: {
+    id?: string;
+    label?: string;
+    description?: string;
+    renderer?: SplatRendererKind;
+}): PairedSplatEnvironmentConfig | undefined;
+/**
+ * Compose a MuJoCo scene config with a paired splat collision proxy.
+ *
+ * This keeps the common hybrid setup declarative:
+ * robot XML remains `sceneFile`, the `.spz` remains a visual-only layer, and
+ * the paired MJCF collision proxy is added to `environmentFiles`.
+ */
+declare function withSplatEnvironment(sceneConfig: SceneConfig, input: SplatSceneInput, options?: {
+    renderer?: SplatRendererKind;
+}): SceneConfig;
 declare function createSplatEnvironmentUserData({ environment, src, format, collisionProxy, }: {
     environment?: PairedSplatEnvironmentConfig;
     src?: string;
@@ -587,13 +611,6 @@ declare function useContactEvents(bodyName: Bodies, handlers: {
  */
 declare function useKeyboardTeleop(config: KeyboardTeleopConfig): void;
 
-/**
- * @license
- * SPDX-License-Identifier: Apache-2.0
- *
- * usePolicy — policy decimation loop hook (spec 10.1)
- */
-
 /**
  * Framework-agnostic policy execution hook.
  *
@@ -608,7 +625,8 @@ declare function usePolicy(config: PolicyConfig): {
     readonly isRunning: boolean;
     start: () => void;
     stop: () => void;
-    readonly lastObservation: Float64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | number[] | null;
+    readonly lastObservation: PolicyVector | null;
+    readonly lastAction: Float64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | number[] | null;
 };
 
 /**
@@ -733,6 +751,56 @@ declare function useVideoRecorder(options?: VideoRecorderOptions): {
     readonly recording: boolean;
 };
 
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useFrameCapture — still-frame capture for canvas-backed MuJoCo/R3F scenes.
+ */
+
+type FrameCaptureStatus = 'idle' | 'capturing' | 'captured' | 'error';
+type FrameCaptureTarget = HTMLCanvasElement | HTMLElement | null | undefined;
+type FrameCaptureTargetRef = React__default.RefObject<HTMLCanvasElement | HTMLElement | null>;
+interface FrameCaptureOptions {
+    target?: FrameCaptureTarget | FrameCaptureTargetRef;
+    type?: string;
+    quality?: number;
+    waitForAnimationFrame?: boolean;
+}
+interface FrameCaptureResult {
+    canvas: HTMLCanvasElement;
+    dataUrl: string;
+    type: string;
+}
+interface FrameCaptureBlobResult {
+    canvas: HTMLCanvasElement;
+    blob: Blob;
+    type: string;
+}
+interface FrameCaptureAPI {
+    status: FrameCaptureStatus;
+    error: Error | null;
+    isCapturing: boolean;
+    capture: (options?: FrameCaptureOptions) => Promise<FrameCaptureResult>;
+    captureBlob: (options?: FrameCaptureOptions) => Promise<FrameCaptureBlobResult>;
+    reset: () => void;
+}
+/**
+ * Capture the current canvas frame as a data URL.
+ *
+ * For WebGL scenes, create the renderer with `preserveDrawingBuffer: true`
+ * when you need deterministic captures after the frame has presented.
+ */
+declare function captureFrame(options: FrameCaptureOptions): Promise<FrameCaptureResult>;
+/**
+ * Capture the current canvas frame as a Blob.
+ */
+declare function captureFrameBlob(options: FrameCaptureOptions): Promise<FrameCaptureBlobResult>;
+/**
+ * React state wrapper around `captureFrame` and `captureFrameBlob`.
+ */
+declare function useFrameCapture(defaultOptions?: FrameCaptureOptions): FrameCaptureAPI;
+
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -828,4 +896,4 @@ interface CameraAnimationAPI {
  */
 declare function useCameraAnimation(): CameraAnimationAPI;
 
-export { ActuatedJointInfo, ActuatorInfo, Actuators, Bodies, Body, BodyProps, BodyStateResult, type CameraAnimationAPI, ContactInfo, ContactListener, ContactListenerProps, ContactMarkers, ControlGroupInfo, ControlGroupSelector, type ControllerComponent, type ControllerOptions, CtrlHandle, Debug, DebugProps, DragInteraction, DragInteractionProps, FlexRenderer, GeomInfo, IkConfig, IkContextValue, IkGizmo, IkGizmoProps, InstancedGeomRenderer, JointStateResult, Joints, KeyboardTeleopConfig, MujocoCanvas, MujocoCanvasProps, MujocoContextValue, MujocoData, type MujocoLoader, type MujocoLoaderOptions, MujocoModel, MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoProviderProps, MujocoSimAPI, MujocoSimProvider, type MujocoWasmVariant, ObservationConfig, ObservationHandle, ObservationResult, PairedSplatEnvironmentConfig, PhysicsStepCallback, PlaybackState, PolicyConfig, ScenarioLighting, ScenarioLightingPreset, ScenarioLightingProps, SceneConfig, SceneLights, SceneLightsProps, SensorHandle, SensorInfo, Sensors, SitePositionResult, Sites, SplatCollisionPrimitive, SplatCollisionProxyConfig, SplatEnvironment, SplatEnvironmentMetadata, SplatEnvironmentMetadataInput, SplatEnvironmentProps, SplatFormat, SplatRendererKind, TendonRenderer, TrajectoryFrame, TrajectoryInput, TrajectoryPlayer, TrajectoryPlayerProps, VisualScenarioConfig, buildObservation, createContiguousControlGroup, createController, createControllerHook, createSparkSplatViewerUrl, createSplatEnvironmentUserData, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getControlMap, getName, getScenarioBackground, getScenarioCameraPosition, loadScene, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useSplatEnvironment, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
+export { ActuatedJointInfo, ActuatorInfo, Actuators, Bodies, Body, BodyProps, BodyStateResult, type CameraAnimationAPI, ContactInfo, ContactListener, ContactListenerProps, ContactMarkers, ControlGroupInfo, ControlGroupSelector, type ControllerComponent, type ControllerOptions, CtrlHandle, Debug, DebugProps, DragInteraction, DragInteractionProps, FlexRenderer, type FrameCaptureAPI, type FrameCaptureBlobResult, type FrameCaptureOptions, type FrameCaptureResult, type FrameCaptureStatus, type FrameCaptureTarget, type FrameCaptureTargetRef, GeomInfo, IkConfig, IkContextValue, IkGizmo, IkGizmoProps, InstancedGeomRenderer, JointStateResult, Joints, KeyboardTeleopConfig, MujocoCanvas, MujocoCanvasProps, MujocoContextValue, MujocoData, type MujocoLoader, type MujocoLoaderOptions, MujocoModel, MujocoModule, MujocoPhysics, type MujocoPhysicsProps, MujocoProvider, type MujocoProviderProps, MujocoSimAPI, MujocoSimProvider, type MujocoWasmVariant, ObservationConfig, ObservationHandle, ObservationResult, PairedSplatEnvironmentConfig, PhysicsStepCallback, PlaybackState, PolicyConfig, PolicyVector, ScenarioLighting, ScenarioLightingPreset, ScenarioLightingProps, SceneConfig, SceneLights, SceneLightsProps, SensorHandle, SensorInfo, Sensors, SitePositionResult, Sites, SplatCollisionPrimitive, SplatCollisionProxyConfig, SplatEnvironment, SplatEnvironmentMetadata, SplatEnvironmentMetadataInput, SplatEnvironmentProps, SplatFormat, SplatRendererKind, SplatSceneInput, TendonRenderer, TrajectoryFrame, TrajectoryInput, TrajectoryPlayer, TrajectoryPlayerProps, VisualScenarioConfig, VisualScenarioEffects, VisualScenarioEffectsProps, buildObservation, captureFrame, captureFrameBlob, createContiguousControlGroup, createController, createControllerHook, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getControlMap, getName, getScenarioBackground, getScenarioCameraPosition, loadScene, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useSplatEnvironment, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder, useVisualScenarioEffects, withSplatEnvironment };

package/dist/index.js

@@ -1,4 +1,4 @@
-export { ScenarioLighting, SplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getScenarioBackground, getScenarioCameraPosition, useSplatEnvironment } from './chunk-KGFRKPLS.js';
+export { ScenarioLighting, SplatEnvironment, VisualScenarioEffects, createPairedSplatEnvironment, createSparkSplatViewerUrl, createSplatEnvironmentUserData, getScenarioBackground, getScenarioCameraPosition, useSplatEnvironment, useVisualScenarioEffects, withSplatEnvironment } from './chunk-SEWQULWO.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';
@@ -776,7 +776,8 @@ function sceneObjectToXml(obj) {
   const solref = obj.solref ? ` solref="${obj.solref}"` : "";
   const solimp = obj.solimp ? ` solimp="${obj.solimp}"` : "";
   const condim = obj.condim ? ` condim="${obj.condim}"` : "";
-  return `<body name="${obj.name}" pos="${pos}">${joint}<geom type="${obj.type}" size="${size}" rgba="${rgba}" contype="1" conaffinity="1"${mass}${friction}${solref}${solimp}${condim}/></body>`;
+  const group = obj.group !== void 0 ? ` group="${obj.group}"` : "";
+  return `<body name="${obj.name}" pos="${pos}">${joint}<geom type="${obj.type}" size="${size}" rgba="${rgba}" contype="1" conaffinity="1"${mass}${friction}${solref}${solimp}${condim}${group}/></body>`;
 }
 function ensureDir(mujoco, fname) {
   const dirParts = fname.split("/");
@@ -816,6 +817,20 @@ function normalizeVfsPath(path) {
 function localFilePath(file) {
   return normalizeVfsPath(file.webkitRelativePath || file.name);
 }
+function dirname(path) {
+  const normalized = normalizeVfsPath(path);
+  const idx = normalized.lastIndexOf("/");
+  return idx === -1 ? "" : normalized.slice(0, idx + 1);
+}
+function relativeVfsPath(fromDir, targetPath) {
+  const from = normalizeVfsPath(fromDir).split("/").filter(Boolean);
+  const target = normalizeVfsPath(targetPath).split("/").filter(Boolean);
+  while (from.length && target.length && from[0] === target[0]) {
+    from.shift();
+    target.shift();
+  }
+  return [...from.map(() => ".."), ...target].join("/") || ".";
+}
 function inferSceneFile(files, options) {
   if (options?.sceneFile) return normalizeVfsPath(options.sceneFile);
   const paths = files.map(localFilePath);
@@ -834,12 +849,120 @@ function createSceneConfigFromFiles(files, options = {}) {
     src: "",
     sceneFile: inferSceneFile(fileArray, options),
     files: fileArray,
+    environmentFiles: options.environmentFiles?.map(normalizeVfsPath),
     homeJoints: options.homeJoints,
     xmlPatches: options.xmlPatches,
     sceneObjects: options.sceneObjects,
     onReset: options.onReset
   };
 }
+var ENVIRONMENT_MERGE_SECTIONS = [
+  "asset",
+  "worldbody",
+  "contact",
+  "equality",
+  "tendon",
+  "sensor",
+  "keyframe",
+  "custom",
+  "extension"
+];
+function directChild(parent, tagName) {
+  const lower = tagName.toLowerCase();
+  for (const child of Array.from(parent.children)) {
+    if (child.tagName.toLowerCase() === lower) return child;
+  }
+  return null;
+}
+function ensureTopLevelSection(doc, tagName) {
+  const root = doc.documentElement;
+  const existing = directChild(root, tagName);
+  if (existing) return existing;
+  const section = doc.createElement(tagName);
+  if (tagName === "asset") {
+    const worldbody = directChild(root, "worldbody");
+    if (worldbody) root.insertBefore(section, worldbody);
+    else root.appendChild(section);
+  } else {
+    root.appendChild(section);
+  }
+  return section;
+}
+function readCompilerDirs(doc) {
+  const compiler = directChild(doc.documentElement, "compiler");
+  const assetDir = compiler?.getAttribute("assetdir") || "";
+  return {
+    meshDir: compiler?.getAttribute("meshdir") || assetDir,
+    textureDir: compiler?.getAttribute("texturedir") || assetDir
+  };
+}
+function isExternalPath(path) {
+  return /^[a-z]+:\/\//i.test(path) || path.startsWith("package://") || path.startsWith("/");
+}
+function fileReferencePrefix(el, compilerDirs) {
+  const tag = el.tagName.toLowerCase();
+  if (tag === "mesh") return compilerDirs.meshDir ? compilerDirs.meshDir + "/" : "";
+  if (tag === "texture" || tag === "hfield") return compilerDirs.textureDir ? compilerDirs.textureDir + "/" : "";
+  return "";
+}
+function rewriteFileReferencesForMerge(node, sourceFile, targetFile, sourceDoc) {
+  const sourceDir = dirname(sourceFile);
+  const targetDir = dirname(targetFile);
+  const compilerDirs = readCompilerDirs(sourceDoc);
+  node.querySelectorAll("[file], [filename]").forEach((el) => {
+    const attr = el.hasAttribute("file") ? "file" : "filename";
+    const value = el.getAttribute(attr);
+    if (!value || isExternalPath(value)) return;
+    const sourceRelativePath = normalizeVfsPath(fileReferencePrefix(el, compilerDirs) + value);
+    const resolvedPath = normalizeVfsPath(sourceDir + sourceRelativePath);
+    el.setAttribute(attr, relativeVfsPath(targetDir, resolvedPath));
+  });
+}
+function hasParseError(doc) {
+  return doc.getElementsByTagName("parsererror").length > 0;
+}
+function composeEnvironmentXml(sceneXml, config, parser, environmentXmlByPath) {
+  const environmentFiles = config.environmentFiles?.map(normalizeVfsPath) ?? [];
+  if (!environmentFiles.length) return sceneXml;
+  const sceneDoc = parser.parseFromString(sceneXml, "text/xml");
+  if (hasParseError(sceneDoc)) {
+    console.warn(`Could not compose environments: failed to parse ${config.sceneFile}`);
+    return sceneXml;
+  }
+  for (const environmentFile of environmentFiles) {
+    const environmentXml = environmentXmlByPath.get(environmentFile);
+    if (!environmentXml) {
+      console.warn(`Environment XML not found: ${environmentFile}`);
+      continue;
+    }
+    const environmentDoc = parser.parseFromString(environmentXml, "text/xml");
+    if (hasParseError(environmentDoc)) {
+      console.warn(`Skipping environment XML with parse errors: ${environmentFile}`);
+      continue;
+    }
+    for (const sectionName of ENVIRONMENT_MERGE_SECTIONS) {
+      const environmentSection = directChild(environmentDoc.documentElement, sectionName);
+      if (!environmentSection?.children.length) continue;
+      const targetSection = ensureTopLevelSection(sceneDoc, sectionName);
+      for (const child of Array.from(environmentSection.children)) {
+        const imported = sceneDoc.importNode(child, true);
+        rewriteFileReferencesForMerge(imported, environmentFile, config.sceneFile, environmentDoc);
+        targetSection.appendChild(imported);
+      }
+    }
+  }
+  return new XMLSerializer().serializeToString(sceneDoc);
+}
+function findTextByConfiguredPath(textByPath, configuredPath) {
+  const normalized = normalizeVfsPath(configuredPath);
+  const direct = textByPath.get(normalized);
+  if (direct) return direct;
+  const suffix = "/" + normalized;
+  for (const [path, text] of textByPath) {
+    if (path.endsWith(suffix) || path === normalized.split("/").pop()) return text;
+  }
+  return void 0;
+}
 function applyXmlPatches(text, fname, config) {
   let result = text;
   for (const patch of config.xmlPatches ?? []) {
@@ -902,10 +1025,21 @@ async function loadSceneFromFiles(mujoco, config, onProgress) {
     if (isModelTextFile(path)) {
       const text = applyXmlPatches(await file.text(), path, config);
       textByPath.set(path, text);
-      mujoco.FS.writeFile(`/working/${path}`, text);
     } else {
       mujoco.FS.writeFile(`/working/${path}`, new Uint8Array(await file.arrayBuffer()));
+      written.add(path);
     }
+  }
+  const environmentXmlByPath = /* @__PURE__ */ new Map();
+  for (const environmentFile of config.environmentFiles?.map(normalizeVfsPath) ?? []) {
+    const environmentXml = findTextByConfiguredPath(textByPath, environmentFile);
+    if (environmentXml) environmentXmlByPath.set(environmentFile, environmentXml);
+  }
+  for (const [path, text] of textByPath) {
+    const composedText = path === config.sceneFile ? composeEnvironmentXml(text, config, parser, environmentXmlByPath) : text;
+    textByPath.set(path, composedText);
+    ensureDir(mujoco, path);
+    mujoco.FS.writeFile(`/working/${path}`, composedText);
     written.add(path);
   }
   for (const [path, text] of textByPath) {
@@ -954,6 +1088,17 @@ async function loadScene(mujoco, config, onProgress) {
   } catch {
   }
   const baseUrl = config.src.endsWith("/") ? config.src : config.src + "/";
+  const environmentXmlByPath = /* @__PURE__ */ new Map();
+  const environmentFiles = config.environmentFiles?.map(normalizeVfsPath) ?? [];
+  for (const environmentFile of environmentFiles) {
+    onProgress?.(`Downloading ${environmentFile}...`);
+    const res = await fetch(baseUrl + environmentFile);
+    if (!res.ok) {
+      console.warn(`Failed to fetch environment XML ${environmentFile}: ${res.status} ${res.statusText}`);
+      continue;
+    }
+    environmentXmlByPath.set(environmentFile, applyXmlPatches(await res.text(), environmentFile, config));
+  }
   const downloaded = /* @__PURE__ */ new Set();
   const xmlQueue = [config.sceneFile];
   const assetFiles = [];
@@ -972,7 +1117,8 @@ async function loadScene(mujoco, config, onProgress) {
       console.warn(`Failed to fetch ${fname}: ${res.status} ${res.statusText}`);
       continue;
     }
-    const text = applyXmlPatches(await res.text(), fname, config);
+    const patchedText = applyXmlPatches(await res.text(), fname, config);
+    const text = fname === config.sceneFile ? composeEnvironmentXml(patchedText, config, parser, environmentXmlByPath) : patchedText;
     ensureDir(mujoco, fname);
     mujoco.FS.writeFile(`/working/${fname}`, text);
     scanDependencies(text, fname, parser, downloaded, xmlQueue);
@@ -2209,6 +2355,7 @@ var MujocoCanvas = forwardRef(
     paused,
     speed,
     interpolate,
+    loadingFallback,
     children,
     ...canvasProps
   }, ref) {
@@ -2218,7 +2365,10 @@ var MujocoCanvas = forwardRef(
         onError(new Error(wasmError ?? "WASM load failed"));
       }
     }, [wasmStatus, wasmError, onError]);
-    if (wasmStatus === "error" || wasmStatus === "loading" || !mujoco) {
+    if (wasmStatus === "loading" || !mujoco) {
+      return loadingFallback ? /* @__PURE__ */ jsx(Canvas, { ...canvasProps, children: loadingFallback }) : null;
+    }
+    if (wasmStatus === "error") {
       return null;
     }
     return /* @__PURE__ */ jsx(Canvas, { ...canvasProps, children: /* @__PURE__ */ jsx(
@@ -2860,6 +3010,7 @@ function Body({
   solref,
   solimp,
   condim,
+  group,
   children
 }) {
   const { bodyRegistryRef, hiddenBodiesRef, requestBodyReload, mjDataRef, mjModelRef, status } = useMujocoContext();
@@ -2879,7 +3030,8 @@ function Body({
       friction,
       solref,
       solimp,
-      condim
+      condim,
+      group
     };
     bodyRegistryRef.current.set(name, { definition, hasCustomChildren: hasChildren });
     if (hasChildren) {
@@ -2892,7 +3044,7 @@ function Body({
         requestBodyReload();
       }
     };
-  }, [name, type, size, position, rgba, mass, freejoint, friction, solref, solimp, condim, hasChildren, bodyRegistryRef, hiddenBodiesRef, requestBodyReload]);
+  }, [name, type, size, position, rgba, mass, freejoint, friction, solref, solimp, condim, group, hasChildren, bodyRegistryRef, hiddenBodiesRef, requestBodyReload]);
   useEffect(() => {
     if (status !== "ready") return;
     const model = mjModelRef.current;
@@ -2904,12 +3056,12 @@ function Body({
     if (!hasChildren) return;
     const data = mjDataRef.current;
     const id = bodyIdRef.current;
-    const group = groupRef.current;
-    if (!data || id < 0 || !group) return;
+    const group2 = groupRef.current;
+    if (!data || id < 0 || !group2) return;
     const i3 = id * 3;
     const i4 = id * 4;
-    group.position.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
-    group.quaternion.set(
+    group2.position.set(data.xpos[i3], data.xpos[i3 + 1], data.xpos[i3 + 2]);
+    group2.quaternion.set(
       data.xquat[i4 + 1],
       data.xquat[i4 + 2],
       data.xquat[i4 + 3],
@@ -4584,22 +4736,25 @@ function useKeyboardTeleop(config) {
   });
 }
 function usePolicy(config) {
-  const { mjModelRef } = useMujocoContext();
   const lastActionTimeRef = useRef(0);
+  const lastObservationRef = useRef(null);
   const lastActionRef = useRef(null);
-  const isRunningRef = useRef(true);
+  const isRunningRef = useRef(config.enabled ?? true);
   const configRef = useRef(config);
   configRef.current = config;
+  isRunningRef.current = config.enabled ?? isRunningRef.current;
   useBeforePhysicsStep((model, data) => {
     if (!isRunningRef.current) return;
     const cfg = configRef.current;
     model.opt?.timestep ?? 2e-3;
     const interval = 1 / cfg.frequency;
     if (data.time - lastActionTimeRef.current >= interval) {
-      const obs = cfg.onObservation(model, data);
-      cfg.onAction(obs, model, data);
+      const observation = cfg.onObservation({ model, data });
+      const action = cfg.infer ? cfg.infer({ observation, model, data }) : observation;
+      cfg.onAction({ action, observation, model, data });
       lastActionTimeRef.current = data.time;
-      lastActionRef.current = obs;
+      lastObservationRef.current = observation;
+      lastActionRef.current = action;
     }
   });
   return {
@@ -4613,6 +4768,9 @@ function usePolicy(config) {
       isRunningRef.current = false;
     },
     get lastObservation() {
+      return lastObservationRef.current;
+    },
+    get lastAction() {
       return lastActionRef.current;
     }
   };
@@ -4809,6 +4967,114 @@ function useVideoRecorder(options = {}) {
     }
   };
 }
+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 (resolvedTarget instanceof HTMLCanvasElement) {
+    return resolvedTarget;
+  }
+  const canvas = resolvedTarget.querySelector("canvas");
+  if (!canvas) {
+    throw new Error("Frame capture target does not contain a canvas.");
+  }
+  return canvas;
+}
+function waitForNextAnimationFrame() {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
+}
+async function captureFrame(options) {
+  const type = options.type ?? "image/png";
+  const canvas = resolveCanvasTarget(options.target);
+  if (options.waitForAnimationFrame ?? true) {
+    await waitForNextAnimationFrame();
+  }
+  return {
+    canvas,
+    dataUrl: canvas.toDataURL(type, options.quality),
+    type
+  };
+}
+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 {
+    status,
+    error,
+    isCapturing: status === "capturing",
+    capture,
+    captureBlob,
+    reset
+  };
+}
 function useCtrlNoise(config = {}) {
   const { mjModelRef } = useMujocoContext();
   const configRef = useRef(config);
@@ -5094,6 +5360,12 @@ function useCameraAnimation() {
  *
  * useVideoRecorder — canvas video recording hook (spec 13.3)
  */
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * useFrameCapture — still-frame capture for canvas-backed MuJoCo/R3F scenes.
+ */
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
@@ -5124,6 +5396,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, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, registerRobotResources, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, 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, MujocoCanvas, MujocoPhysics, MujocoProvider, MujocoSimProvider, RobotActuators, RobotBodies, RobotGeoms, RobotJoints, RobotKeyframes, RobotResources, RobotSensors, RobotSites, SceneLights, TendonRenderer, TrajectoryPlayer, buildObservation, captureFrame, captureFrameBlob, createContiguousControlGroup, createController, createControllerHook, findActuatorByName, findBodyByName, findGeomByName, findJointByName, findKeyframeByName, findSensorByName, findSiteByName, findTendonByName, getActuatedJoints, getContact, getControlMap, getName, loadScene, registerRobotResources, resolveControlGroup, useActuators, useAfterPhysicsStep, useBeforePhysicsStep, useBodyMeshes, useBodyState, useCameraAnimation, useContactEvents, useContacts, useCtrl, useCtrlNoise, useFrameCapture, useGamepad, useGravityCompensation, useIkController, useJointState, useKeyboardTeleop, useMujoco, useMujocoWasm, useObservation, usePolicy, useSceneLights, useSelectionHighlight, useSensor, useSensors, useSitePosition, useTrajectoryPlayer, useTrajectoryRecorder, useVideoRecorder };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map