mujoco-react 8.10.0 → 9.0.0

package/dist/spark.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _sparkjsdev_spark from '@sparkjsdev/spark';
-import { l as SplatEnvironmentProps } from './types-FFW7ykBu.js';
+import { n as SplatEnvironmentProps } from './types-izZlUweI.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';
@@ -8,6 +8,15 @@ import 'three';
 type SparkModule = typeof _sparkjsdev_spark;
 type SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;
 type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';
+interface SparkSplatLifecycle {
+    status: SparkSplatStatus;
+    error: Error | null;
+    isLoading: boolean;
+    isReady: boolean;
+    isError: boolean;
+    props: Pick<SparkSplatEnvironmentProps, 'onStatusChange' | 'onError'>;
+    reset: () => void;
+}
 interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {
     /** Enable Spark LoD handling for large splat assets. Default: true. */
     lod?: boolean | 'quality';
@@ -21,12 +30,24 @@ interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {
     onLoad?: (mesh: SparkSplatMeshInstance) => void;
     onError?: (error: Error) => void;
 }
+/**
+ * Tracks Spark 3DGS loading state for UI that wraps `SparkSplatEnvironment`.
+ *
+ * Use the returned `props` with `<SparkSplatEnvironment {...lifecycle.props} />`
+ * to avoid repeating status/error state in app code.
+ */
+declare function useSparkSplatLifecycle({ enabled, initialStatus, onError, onStatusChange, }?: {
+    enabled?: boolean;
+    initialStatus?: SparkSplatStatus;
+    onError?: (error: Error) => void;
+    onStatusChange?: (status: SparkSplatStatus) => void;
+}): SparkSplatLifecycle;
 /**
  * Optional SparkJS-backed Gaussian splat renderer for React Three Fiber scenes.
  *
  * Import from `mujoco-react/spark` and install `@sparkjsdev/spark` in the app
  * that uses it. The core `mujoco-react` entrypoint does not depend on Spark.
  */
-declare function SparkSplatEnvironment({ environment, src, format, collisionProxy, collisionProxyMetadata, showPlaceholder, children, lod, hideGroundMeshes, onStatusChange, onLoad, onError, ...groupProps }: SparkSplatEnvironmentProps): react_jsx_runtime.JSX.Element;
+declare function SparkSplatEnvironment({ environment, scenario, renderer, src, format, collisionProxy, collisionProxyMetadata, showPlaceholder, children, lod, hideGroundMeshes, onStatusChange, onLoad, onError, ...groupProps }: SparkSplatEnvironmentProps): react_jsx_runtime.JSX.Element;
 
-export { SparkSplatEnvironment, type SparkSplatEnvironmentProps, type SparkSplatStatus };
+export { SparkSplatEnvironment, type SparkSplatEnvironmentProps, type SparkSplatLifecycle, type SparkSplatStatus, useSparkSplatLifecycle };

package/dist/spark.js

@@ -1,11 +1,65 @@
-import { useSplatEnvironment, SplatEnvironment } from './chunk-KGFRKPLS.js';
+import { useSplatEnvironment, SplatEnvironment } from './chunk-33CV6HSV.js';
 import { useThree } from '@react-three/fiber';
-import { useRef, useState, useEffect } from 'react';
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import * as THREE from 'three';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
+function useSparkSplatLifecycle({
+  enabled = true,
+  initialStatus,
+  onError,
+  onStatusChange
+} = {}) {
+  const [status, setStatus] = useState(
+    initialStatus ?? (enabled ? "loading" : "idle")
+  );
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    setStatus(enabled ? initialStatus ?? "loading" : "idle");
+    setError(null);
+  }, [enabled, initialStatus]);
+  const handleStatusChange = useCallback(
+    (nextStatus) => {
+      setStatus(nextStatus);
+      if (nextStatus !== "error") {
+        setError(null);
+      }
+      onStatusChange?.(nextStatus);
+    },
+    [onStatusChange]
+  );
+  const handleError = useCallback(
+    (nextError) => {
+      setError(nextError);
+      setStatus("error");
+      onError?.(nextError);
+    },
+    [onError]
+  );
+  const reset = useCallback(() => {
+    setStatus(enabled ? initialStatus ?? "loading" : "idle");
+    setError(null);
+  }, [enabled, initialStatus]);
+  return useMemo(
+    () => ({
+      status,
+      error,
+      isLoading: status === "loading",
+      isReady: status === "ready",
+      isError: status === "error",
+      props: {
+        onStatusChange: handleStatusChange,
+        onError: handleError
+      },
+      reset
+    }),
+    [error, handleError, handleStatusChange, reset, status]
+  );
+}
 function SparkSplatEnvironment({
   environment,
+  scenario,
+  renderer = "spark",
   src,
   format,
   collisionProxy,
@@ -30,6 +84,8 @@ function SparkSplatEnvironment({
   const { gl, invalidate } = useThree();
   const metadata = useSplatEnvironment({
     environment,
+    scenario,
+    renderer,
     src,
     format,
     collisionProxy: collisionProxyMetadata
@@ -56,10 +112,18 @@ function SparkSplatEnvironment({
       hiddenMeshesRef.current = [];
     }
     async function loadSplat() {
-      if (!metadata.src || metadata.format !== "spz") {
+      if (!metadata.src) {
         setLifecycleStatus("idle");
         return;
       }
+      if (metadata.format !== "spz") {
+        const unsupportedFormatError = new Error(
+          `SparkSplatEnvironment only supports .spz assets; received "${metadata.format}".`
+        );
+        setLifecycleStatus("error");
+        onErrorRef.current?.(unsupportedFormatError);
+        return;
+      }
       setLifecycleStatus("loading");
       try {
         const sparkModule = await import('@sparkjsdev/spark');
@@ -106,12 +170,12 @@ function SparkSplatEnvironment({
       restoreHiddenMeshes();
       if (meshRef.current) {
         groupRef.current?.remove(meshRef.current);
-        meshRef.current.dispose?.();
+        safelyDisposeSparkResource(meshRef.current);
         meshRef.current = null;
       }
       if (sparkRef.current) {
         groupRef.current?.remove(sparkRef.current);
-        sparkRef.current.dispose?.();
+        safelyDisposeSparkResource(sparkRef.current);
         sparkRef.current = null;
       }
     };
@@ -128,6 +192,8 @@ function SparkSplatEnvironment({
     {
       ...groupProps,
       environment,
+      scenario,
+      renderer,
       src: metadata.src,
       format: metadata.format,
       collisionProxyMetadata: metadata.collisionProxy,
@@ -140,11 +206,30 @@ function SparkSplatEnvironment({
     }
   );
 }
+function safelyDisposeSparkResource(resource) {
+  try {
+    const result = resource.dispose?.();
+    if (isPromiseLike(result)) {
+      void Promise.resolve(result).catch(handleSparkDisposeError);
+    }
+  } catch (error) {
+    handleSparkDisposeError(error);
+  }
+}
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+function handleSparkDisposeError(error) {
+  if (error instanceof Error && error.message.toLowerCase().includes("worker terminate")) {
+    return;
+  }
+  console.warn("[mujoco-react] Spark resource disposal failed.", error);
+}
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export { SparkSplatEnvironment };
+export { SparkSplatEnvironment, useSparkSplatLifecycle };
 //# sourceMappingURL=spark.js.map
 //# sourceMappingURL=spark.js.map

package/dist/spark.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/spark.tsx"],"names":[],"mappings":"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","file":"spark.js","sourcesContent":["/**\n * @license\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { useThree } from '@react-three/fiber';\nimport { useEffect, useRef, useState } from 'react';\nimport * as THREE from 'three';\nimport {\n  SplatEnvironment,\n  useSplatEnvironment,\n} from './components/VisualScenario';\nimport type {\n  SplatEnvironmentProps,\n} from './types';\n\ntype SparkModule = typeof import('@sparkjsdev/spark');\ntype SparkRendererInstance = InstanceType<SparkModule['SparkRenderer']>;\ntype SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;\n\nexport type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';\n\nexport interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {\n  /** Enable Spark LoD handling for large splat assets. Default: true. */\n  lod?: boolean | 'quality';\n  /**\n   * Hide meshes whose names include floor, ground, or plane while the splat is\n   * active. This mirrors the common hybrid-rendering setup where MJCF keeps\n   * collision geometry but the splat owns the visual environment.\n   */\n  hideGroundMeshes?: boolean;\n  onStatusChange?: (status: SparkSplatStatus) => void;\n  onLoad?: (mesh: SparkSplatMeshInstance) => void;\n  onError?: (error: Error) => void;\n}\n\n/**\n * Optional SparkJS-backed Gaussian splat renderer for React Three Fiber scenes.\n *\n * Import from `mujoco-react/spark` and install `@sparkjsdev/spark` in the app\n * that uses it. The core `mujoco-react` entrypoint does not depend on Spark.\n */\nexport function SparkSplatEnvironment({\n  environment,\n  src,\n  format,\n  collisionProxy,\n  collisionProxyMetadata,\n  showPlaceholder,\n  children,\n  lod = true,\n  hideGroundMeshes = false,\n  onStatusChange,\n  onLoad,\n  onError,\n  ...groupProps\n}: SparkSplatEnvironmentProps) {\n  const groupRef = useRef<THREE.Group>(null);\n  const sparkRef = useRef<SparkRendererInstance | null>(null);\n  const meshRef = useRef<SparkSplatMeshInstance | null>(null);\n  const hiddenMeshesRef = useRef<THREE.Mesh[]>([]);\n  const onStatusChangeRef = useRef(onStatusChange);\n  const onLoadRef = useRef(onLoad);\n  const onErrorRef = useRef(onError);\n  const [status, setStatus] = useState<SparkSplatStatus>('idle');\n  const { gl, invalidate } = useThree();\n  const metadata = useSplatEnvironment({\n    environment,\n    src,\n    format,\n    collisionProxy: collisionProxyMetadata,\n  });\n\n  useEffect(() => {\n    onStatusChangeRef.current = onStatusChange;\n  }, [onStatusChange]);\n\n  useEffect(() => {\n    onLoadRef.current = onLoad;\n  }, [onLoad]);\n\n  useEffect(() => {\n    onErrorRef.current = onError;\n  }, [onError]);\n\n  useEffect(() => {\n    let disposed = false;\n\n    function setLifecycleStatus(nextStatus: SparkSplatStatus) {\n      setStatus(nextStatus);\n      onStatusChangeRef.current?.(nextStatus);\n    }\n\n    function restoreHiddenMeshes() {\n      for (const mesh of hiddenMeshesRef.current) {\n        mesh.visible = true;\n      }\n      hiddenMeshesRef.current = [];\n    }\n\n    async function loadSplat() {\n      if (!metadata.src || metadata.format !== 'spz') {\n        setLifecycleStatus('idle');\n        return;\n      }\n\n      setLifecycleStatus('loading');\n\n      try {\n        const sparkModule = await import('@sparkjsdev/spark');\n        if (disposed || !groupRef.current) return;\n\n        const spark = new sparkModule.SparkRenderer({\n          renderer: gl,\n          onDirty: invalidate,\n        });\n        const mesh = new sparkModule.SplatMesh({\n          url: metadata.src,\n          lod,\n        });\n        mesh.name = 'GaussianSplatMesh';\n\n        groupRef.current.add(spark);\n        groupRef.current.add(mesh);\n        sparkRef.current = spark;\n        meshRef.current = mesh;\n\n        if (hideGroundMeshes && groupRef.current.parent) {\n          groupRef.current.parent.traverse((object) => {\n            if (\n              !(object instanceof THREE.Mesh) ||\n              object === (mesh as unknown as THREE.Object3D)\n            ) {\n              return;\n            }\n            const name = object.name.toLowerCase();\n            if (\n              name.includes('floor') ||\n              name.includes('ground') ||\n              name.includes('plane')\n            ) {\n              object.visible = false;\n              hiddenMeshesRef.current.push(object);\n            }\n          });\n        }\n\n        await mesh.initialized;\n        if (disposed) return;\n        setLifecycleStatus('ready');\n        onLoadRef.current?.(mesh);\n        invalidate();\n      } catch (error) {\n        const normalizedError =\n          error instanceof Error ? error : new Error(String(error));\n        setLifecycleStatus('error');\n        onErrorRef.current?.(normalizedError);\n      }\n    }\n\n    void loadSplat();\n\n    return () => {\n      disposed = true;\n      restoreHiddenMeshes();\n\n      if (meshRef.current) {\n        groupRef.current?.remove(meshRef.current);\n        meshRef.current.dispose?.();\n        meshRef.current = null;\n      }\n\n      if (sparkRef.current) {\n        groupRef.current?.remove(sparkRef.current);\n        sparkRef.current.dispose?.();\n        sparkRef.current = null;\n      }\n    };\n  }, [\n    gl,\n    hideGroundMeshes,\n    invalidate,\n    lod,\n    metadata.format,\n    metadata.src,\n  ]);\n\n  return (\n    <SplatEnvironment\n      {...groupProps}\n      environment={environment}\n      src={metadata.src}\n      format={metadata.format}\n      collisionProxyMetadata={metadata.collisionProxy}\n      collisionProxy={collisionProxy}\n      showPlaceholder={showPlaceholder ?? status !== 'ready'}\n    >\n      <group ref={groupRef} />\n      {children}\n    </SplatEnvironment>\n  );\n}\n"]}
+{"version":3,"sources":["../src/spark.tsx"],"names":[],"mappings":"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","file":"spark.js","sourcesContent":["/**\n * @license\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { useThree } from '@react-three/fiber';\nimport {\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport * as THREE from 'three';\nimport {\n  SplatEnvironment,\n  useSplatEnvironment,\n} from './components/VisualScenario';\nimport type {\n  SplatEnvironmentProps,\n} from './types';\n\ntype SparkModule = typeof import('@sparkjsdev/spark');\ntype SparkRendererInstance = InstanceType<SparkModule['SparkRenderer']>;\ntype SparkSplatMeshInstance = InstanceType<SparkModule['SplatMesh']>;\ntype SparkDisposable = {\n  dispose?: () => unknown;\n};\n\nexport type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';\n\nexport interface SparkSplatLifecycle {\n  status: SparkSplatStatus;\n  error: Error | null;\n  isLoading: boolean;\n  isReady: boolean;\n  isError: boolean;\n  props: Pick<SparkSplatEnvironmentProps, 'onStatusChange' | 'onError'>;\n  reset: () => void;\n}\n\nexport interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {\n  /** Enable Spark LoD handling for large splat assets. Default: true. */\n  lod?: boolean | 'quality';\n  /**\n   * Hide meshes whose names include floor, ground, or plane while the splat is\n   * active. This mirrors the common hybrid-rendering setup where MJCF keeps\n   * collision geometry but the splat owns the visual environment.\n   */\n  hideGroundMeshes?: boolean;\n  onStatusChange?: (status: SparkSplatStatus) => void;\n  onLoad?: (mesh: SparkSplatMeshInstance) => void;\n  onError?: (error: Error) => void;\n}\n\n/**\n * Tracks Spark 3DGS loading state for UI that wraps `SparkSplatEnvironment`.\n *\n * Use the returned `props` with `<SparkSplatEnvironment {...lifecycle.props} />`\n * to avoid repeating status/error state in app code.\n */\nexport function useSparkSplatLifecycle({\n  enabled = true,\n  initialStatus,\n  onError,\n  onStatusChange,\n}: {\n  enabled?: boolean;\n  initialStatus?: SparkSplatStatus;\n  onError?: (error: Error) => void;\n  onStatusChange?: (status: SparkSplatStatus) => void;\n} = {}): SparkSplatLifecycle {\n  const [status, setStatus] = useState<SparkSplatStatus>(\n    initialStatus ?? (enabled ? 'loading' : 'idle')\n  );\n  const [error, setError] = useState<Error | null>(null);\n\n  useEffect(() => {\n    setStatus(enabled ? initialStatus ?? 'loading' : 'idle');\n    setError(null);\n  }, [enabled, initialStatus]);\n\n  const handleStatusChange = useCallback(\n    (nextStatus: SparkSplatStatus) => {\n      setStatus(nextStatus);\n      if (nextStatus !== 'error') {\n        setError(null);\n      }\n      onStatusChange?.(nextStatus);\n    },\n    [onStatusChange]\n  );\n\n  const handleError = useCallback(\n    (nextError: Error) => {\n      setError(nextError);\n      setStatus('error');\n      onError?.(nextError);\n    },\n    [onError]\n  );\n\n  const reset = useCallback(() => {\n    setStatus(enabled ? initialStatus ?? 'loading' : 'idle');\n    setError(null);\n  }, [enabled, initialStatus]);\n\n  return useMemo(\n    () => ({\n      status,\n      error,\n      isLoading: status === 'loading',\n      isReady: status === 'ready',\n      isError: status === 'error',\n      props: {\n        onStatusChange: handleStatusChange,\n        onError: handleError,\n      },\n      reset,\n    }),\n    [error, handleError, handleStatusChange, reset, status]\n  );\n}\n\n/**\n * Optional SparkJS-backed Gaussian splat renderer for React Three Fiber scenes.\n *\n * Import from `mujoco-react/spark` and install `@sparkjsdev/spark` in the app\n * that uses it. The core `mujoco-react` entrypoint does not depend on Spark.\n */\nexport function SparkSplatEnvironment({\n  environment,\n  scenario,\n  renderer = 'spark',\n  src,\n  format,\n  collisionProxy,\n  collisionProxyMetadata,\n  showPlaceholder,\n  children,\n  lod = true,\n  hideGroundMeshes = false,\n  onStatusChange,\n  onLoad,\n  onError,\n  ...groupProps\n}: SparkSplatEnvironmentProps) {\n  const groupRef = useRef<THREE.Group>(null);\n  const sparkRef = useRef<SparkRendererInstance | null>(null);\n  const meshRef = useRef<SparkSplatMeshInstance | null>(null);\n  const hiddenMeshesRef = useRef<THREE.Mesh[]>([]);\n  const onStatusChangeRef = useRef(onStatusChange);\n  const onLoadRef = useRef(onLoad);\n  const onErrorRef = useRef(onError);\n  const [status, setStatus] = useState<SparkSplatStatus>('idle');\n  const { gl, invalidate } = useThree();\n  const metadata = useSplatEnvironment({\n    environment,\n    scenario,\n    renderer,\n    src,\n    format,\n    collisionProxy: collisionProxyMetadata,\n  });\n\n  useEffect(() => {\n    onStatusChangeRef.current = onStatusChange;\n  }, [onStatusChange]);\n\n  useEffect(() => {\n    onLoadRef.current = onLoad;\n  }, [onLoad]);\n\n  useEffect(() => {\n    onErrorRef.current = onError;\n  }, [onError]);\n\n  useEffect(() => {\n    let disposed = false;\n\n    function setLifecycleStatus(nextStatus: SparkSplatStatus) {\n      setStatus(nextStatus);\n      onStatusChangeRef.current?.(nextStatus);\n    }\n\n    function restoreHiddenMeshes() {\n      for (const mesh of hiddenMeshesRef.current) {\n        mesh.visible = true;\n      }\n      hiddenMeshesRef.current = [];\n    }\n\n    async function loadSplat() {\n      if (!metadata.src) {\n        setLifecycleStatus('idle');\n        return;\n      }\n\n      if (metadata.format !== 'spz') {\n        const unsupportedFormatError = new Error(\n          `SparkSplatEnvironment only supports .spz assets; received \"${metadata.format}\".`\n        );\n        setLifecycleStatus('error');\n        onErrorRef.current?.(unsupportedFormatError);\n        return;\n      }\n\n      setLifecycleStatus('loading');\n\n      try {\n        const sparkModule = await import('@sparkjsdev/spark');\n        if (disposed || !groupRef.current) return;\n\n        const spark = new sparkModule.SparkRenderer({\n          renderer: gl,\n          onDirty: invalidate,\n        });\n        const mesh = new sparkModule.SplatMesh({\n          url: metadata.src,\n          lod,\n        });\n        mesh.name = 'GaussianSplatMesh';\n\n        groupRef.current.add(spark);\n        groupRef.current.add(mesh);\n        sparkRef.current = spark;\n        meshRef.current = mesh;\n\n        if (hideGroundMeshes && groupRef.current.parent) {\n          groupRef.current.parent.traverse((object) => {\n            if (\n              !(object instanceof THREE.Mesh) ||\n              object === (mesh as unknown as THREE.Object3D)\n            ) {\n              return;\n            }\n            const name = object.name.toLowerCase();\n            if (\n              name.includes('floor') ||\n              name.includes('ground') ||\n              name.includes('plane')\n            ) {\n              object.visible = false;\n              hiddenMeshesRef.current.push(object);\n            }\n          });\n        }\n\n        await mesh.initialized;\n        if (disposed) return;\n        setLifecycleStatus('ready');\n        onLoadRef.current?.(mesh);\n        invalidate();\n      } catch (error) {\n        const normalizedError =\n          error instanceof Error ? error : new Error(String(error));\n        setLifecycleStatus('error');\n        onErrorRef.current?.(normalizedError);\n      }\n    }\n\n    void loadSplat();\n\n    return () => {\n      disposed = true;\n      restoreHiddenMeshes();\n\n      if (meshRef.current) {\n        groupRef.current?.remove(meshRef.current);\n        safelyDisposeSparkResource(meshRef.current);\n        meshRef.current = null;\n      }\n\n      if (sparkRef.current) {\n        groupRef.current?.remove(sparkRef.current);\n        safelyDisposeSparkResource(sparkRef.current);\n        sparkRef.current = null;\n      }\n    };\n  }, [\n    gl,\n    hideGroundMeshes,\n    invalidate,\n    lod,\n    metadata.format,\n    metadata.src,\n  ]);\n\n  return (\n    <SplatEnvironment\n      {...groupProps}\n      environment={environment}\n      scenario={scenario}\n      renderer={renderer}\n      src={metadata.src}\n      format={metadata.format}\n      collisionProxyMetadata={metadata.collisionProxy}\n      collisionProxy={collisionProxy}\n      showPlaceholder={showPlaceholder ?? status !== 'ready'}\n    >\n      <group ref={groupRef} />\n      {children}\n    </SplatEnvironment>\n  );\n}\n\nfunction safelyDisposeSparkResource(resource: SparkDisposable) {\n  try {\n    const result = resource.dispose?.();\n    if (isPromiseLike(result)) {\n      void Promise.resolve(result).catch(handleSparkDisposeError);\n    }\n  } catch (error) {\n    handleSparkDisposeError(error);\n  }\n}\n\nfunction isPromiseLike(value: unknown): value is PromiseLike<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'then' in value &&\n    typeof (value as { then?: unknown }).then === 'function'\n  );\n}\n\nfunction handleSparkDisposeError(error: unknown) {\n  if (\n    error instanceof Error &&\n    error.message.toLowerCase().includes('worker terminate')\n  ) {\n    return;\n  }\n\n  console.warn('[mujoco-react] Spark resource disposal failed.', error);\n}\n"]}

package/dist/{types-FFW7ykBu.d.ts → types-izZlUweI.d.ts}

@@ -309,6 +309,8 @@ interface SceneObject {
     solref?: string;
     solimp?: string;
     condim?: number;
+    /** MuJoCo geom group. Group 3 is conventionally used for collision-only helper geoms. */
+    group?: number;
 }
 interface XmlPatch {
     target: string;
@@ -320,10 +322,12 @@ type LocalMujocoFile = File;
 interface LoadFromFilesOptions {
     /** Entry MJCF/URDF file. Inferred from scene.xml, model.xml, robot.xml, or the first XML/URDF file when omitted. */
     sceneFile?: string;
+    /** Additional MJCF environment XML files merged into the entry scene before MuJoCo compilation. */
+    environmentFiles?: string[];
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
     sceneObjects?: SceneObject[];
-    onReset?: (model: MujocoModel, data: MujocoData) => void;
+    onReset?: (input: ResetCallbackInput) => void;
 }
 interface SceneConfig {
     /** Base URL for fetching model files. The loader fetches `src + sceneFile` and follows dependencies. */
@@ -332,10 +336,18 @@ interface SceneConfig {
     sceneFile: string;
     /** Browser-selected files for local MJCF/URDF loading. Preserves webkitRelativePath when available. */
     files?: readonly LocalMujocoFile[];
+    /**
+     * Additional MJCF environment XML files merged into the entry scene before compilation.
+     *
+     * Use this for static collision/physics layers such as a Gaussian-splat
+     * environment's proxy `scene.xml`; render the splat itself as a separate
+     * visual layer.
+     */
+    environmentFiles?: string[];
     sceneObjects?: SceneObject[];
     homeJoints?: number[];
     xmlPatches?: XmlPatch[];
-    onReset?: (model: MujocoModel, data: MujocoData) => void;
+    onReset?: (input: ResetCallbackInput) => void;
 }
 type ResourceSelector<TInfo, TName extends string = string> = TName | readonly TName[] | RegExp | ((info: TInfo) => boolean);
 interface IkConfig {
@@ -368,7 +380,7 @@ interface IkContextValue {
     setIkEnabled: (enabled: boolean) => void;
     moveTarget: (pos: THREE.Vector3, duration?: number) => void;
     syncTargetToSite: () => void;
-    solveIK: (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[]) => number[] | null;
+    solveIK: (input: IkSolveInput) => number[] | null;
     getGizmoStats: () => {
         pos: THREE.Vector3;
         rot: THREE.Euler;
@@ -386,14 +398,38 @@ interface PhysicsConfig {
     paused?: boolean;
     speed?: number;
 }
-type IKSolveFn = (pos: THREE.Vector3, quat: THREE.Quaternion, currentQ: number[], context?: IKSolveContext) => number[] | null;
+type IKSolveFn = (input: IkSolveInput) => number[] | null;
+interface IkSolveInput {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
+    currentQ: number[];
+    context?: IKSolveContext;
+}
 interface IKSolveContext {
     model: MujocoModel;
     data: MujocoData;
     siteId: number;
     controlGroup: ControlGroupInfo;
 }
-type PhysicsStepCallback = (model: MujocoModel, data: MujocoData) => void;
+interface PhysicsStepInput {
+    model: MujocoModel;
+    data: MujocoData;
+}
+interface ResetCallbackInput extends PhysicsStepInput {
+}
+interface ReadyCallbackInput {
+    api: MujocoSimAPI;
+}
+interface StepCallbackInput {
+    time: number;
+    model: MujocoModel;
+    data: MujocoData;
+}
+interface SelectionCallbackInput {
+    bodyId: number;
+    name: string;
+}
+type PhysicsStepCallback = (input: PhysicsStepInput) => void;
 interface StateSnapshot {
     time: number;
     qpos: Float64Array;
@@ -524,10 +560,24 @@ interface KeyboardTeleopConfig {
     bindings: Record<string, KeyBinding>;
     enabled?: boolean;
 }
+type PolicyVector = Float32Array | Float64Array | number[];
+interface PolicyObservationInput {
+    model: MujocoModel;
+    data: MujocoData;
+}
+interface PolicyInferenceInput extends PolicyObservationInput {
+    observation: PolicyVector;
+}
+interface PolicyActionInput extends PolicyInferenceInput {
+    action: PolicyVector;
+}
 interface PolicyConfig {
     frequency: number;
-    onObservation: (model: MujocoModel, data: MujocoData) => Float32Array | Float64Array | number[];
-    onAction: (action: Float32Array | Float64Array | number[], model: MujocoModel, data: MujocoData) => void;
+    enabled?: boolean;
+    onObservation: (input: PolicyObservationInput) => PolicyVector;
+    /** Run policy inference. Omit to pass observations directly to `onAction` for custom inline controllers. */
+    infer?: (input: PolicyInferenceInput) => PolicyVector;
+    onAction: (input: PolicyActionInput) => void;
 }
 type ObservationOutput = 'float32' | 'float64';
 interface ObservationConfig {
@@ -580,7 +630,11 @@ interface IkGizmoProps {
     controller: IkContextValue;
     siteName?: string;
     scale?: number;
-    onDrag?: (position: THREE.Vector3, quaternion: THREE.Quaternion) => void;
+    onDrag?: (input: IkGizmoDragInput) => void;
+}
+interface IkGizmoDragInput {
+    position: THREE.Vector3;
+    quaternion: THREE.Quaternion;
 }
 interface DragInteractionProps {
     stiffness?: number;
@@ -600,6 +654,12 @@ interface ScenarioCameraConfig {
     noise?: number;
     blur?: number;
 }
+interface ScenarioMaterialConfig {
+    randomizeObjectColors?: boolean;
+    randomizeTableMaterial?: boolean;
+    roughness?: number;
+    metalness?: number;
+}
 interface SplatAssetConfig {
     src: string;
     /** Common browser-friendly splat format. Renderer-specific loaders may accept more. */
@@ -613,7 +673,7 @@ interface SplatScenarioConfig {
     format?: SplatFormat;
     src?: string;
     requiresCollisionProxy?: boolean;
-    collisionProxy?: SplatCollisionProxyConfig;
+    collisionProxy?: SplatCollisionProxyConfig | null;
 }
 interface SplatCollisionProxyConfig {
     /** MJCF/XML file or artifact path that provides physics collision for the visual splat. */
@@ -638,6 +698,8 @@ interface PairedSplatEnvironmentConfig {
 }
 interface SplatEnvironmentMetadataInput {
     environment?: PairedSplatEnvironmentConfig;
+    scenario?: VisualScenarioConfig;
+    renderer?: SplatRendererKind;
     src?: string;
     format?: SplatFormat;
     collisionProxy?: SplatCollisionProxyConfig;
@@ -648,6 +710,7 @@ interface SplatEnvironmentMetadata {
     collisionProxy?: SplatCollisionProxyConfig;
     userData: Record<string, unknown>;
 }
+type SplatSceneInput = PairedSplatEnvironmentConfig | VisualScenarioConfig | undefined | null;
 interface VisualScenarioConfig {
     id?: string;
     label?: string;
@@ -655,7 +718,8 @@ interface VisualScenarioConfig {
     lighting?: ScenarioLightingPreset;
     environment?: string;
     camera?: ScenarioCameraConfig;
-    splat?: SplatScenarioConfig;
+    materials?: ScenarioMaterialConfig;
+    splat?: SplatScenarioConfig | null;
 }
 interface ScenarioLightingProps {
     preset?: ScenarioLightingPreset;
@@ -664,12 +728,30 @@ interface ScenarioLightingProps {
 }
 interface SplatEnvironmentProps extends Omit<ThreeElements['group'], 'ref'> {
     environment?: PairedSplatEnvironmentConfig;
+    scenario?: VisualScenarioConfig;
+    renderer?: SplatRendererKind;
     src?: string;
     format?: SplatFormat;
     collisionProxy?: ReactNode;
     collisionProxyMetadata?: SplatCollisionProxyConfig;
     showPlaceholder?: boolean;
 }
+interface VisualScenarioEffectsProps {
+    scenario?: VisualScenarioConfig;
+    enabled?: boolean;
+    applyBackground?: boolean;
+    applyFog?: boolean;
+    applyRenderer?: boolean;
+    applyMaterials?: boolean;
+    background?: THREE.ColorRepresentation;
+    fogNear?: number;
+    fogFar?: number;
+    materialFilter?: (input: VisualScenarioMaterialFilterInput) => boolean;
+}
+interface VisualScenarioMaterialFilterInput {
+    object: THREE.Object3D;
+    material: THREE.Material;
+}
 type TrajectoryInput = TrajectoryFrame[] | number[][];
 interface TrajectoryPlayerProps {
     trajectory: TrajectoryInput;
@@ -678,9 +760,16 @@ interface TrajectoryPlayerProps {
     loop?: boolean;
     playing?: boolean;
     mode?: 'kinematic' | 'physics';
-    onFrame?: (frameIdx: number) => void;
+    onFrame?: (input: TrajectoryFrameCallbackInput) => void;
     onComplete?: () => void;
-    onStateChange?: (state: PlaybackState) => void;
+    onStateChange?: (input: TrajectoryStateChangeInput) => void;
+}
+interface TrajectoryFrameCallbackInput {
+    frameIndex: number;
+    frame: TrajectoryFrame | number[] | undefined;
+}
+interface TrajectoryStateChangeInput {
+    state: PlaybackState;
 }
 interface ContactListenerProps {
     body: Bodies;
@@ -699,6 +788,8 @@ interface BodyProps {
     solref?: string;
     solimp?: string;
     condim?: number;
+    /** MuJoCo geom group. Group 3 is conventionally used for collision-only helper geoms. */
+    group?: number;
     children?: ReactNode;
 }
 interface MujocoSimAPI {
@@ -760,10 +851,12 @@ interface MujocoSimAPI {
 }
 type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
     config: SceneConfig;
-    onReady?: (api: MujocoSimAPI) => void;
+    /** R3F content rendered while the MuJoCo WASM module is still loading. */
+    loadingFallback?: ReactNode;
+    onReady?: (input: ReadyCallbackInput) => void;
     onError?: (error: Error) => void;
-    onStep?: (time: number) => void;
-    onSelection?: (bodyId: number, name: string) => void;
+    onStep?: (input: StepCallbackInput) => void;
+    onSelection?: (input: SelectionCallbackInput) => void;
     gravity?: [number, number, number];
     timestep?: number;
     substeps?: number;
@@ -814,4 +907,4 @@ interface JointStateResult {
     velocity: React__default.RefObject<number | Float64Array>;
 }
 
-export { type BodyInfo as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type SensorHandle as E, type SensorInfo as F, type GeomInfo as G, type JointStateResult as H, type IkConfig as I, type Joints as J, type Bodies as K, type BodyStateResult as L, type MujocoContextValue as M, type Actuators as N, type ObservationConfig as O, type PhysicsStepCallback as P, type CtrlHandle as Q, type ContactInfo as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type KeyboardTeleopConfig as U, type VisualScenarioConfig as V, type PolicyConfig as W, type ObservationHandle as X, type TrajectoryInput as Y, type PlaybackState as Z, type TrajectoryFrame as _, type MujocoCanvasProps as a, type ControlJointInfo as a0, type Geoms as a1, type IKSolveFn as a2, type JointInfo as a3, type KeyBinding as a4, type Keyframes as a5, type ModelOptions as a6, type MujocoContact as a7, type MujocoContactArray as a8, type ObservationLayoutItem as a9, getContact as aA, registerRobotResources as aB, type ObservationOutput as aa, type PhysicsConfig as ab, type RayHit as ac, type Register as ad, type RegisteredRobotMap as ae, type ResourceSelector as af, RobotActuators as ag, RobotBodies as ah, RobotGeoms as ai, RobotJoints as aj, RobotKeyframes as ak, type RobotResource as al, RobotResources as am, RobotSensors as an, RobotSites as ao, type Robots as ap, type ScenarioCameraConfig as aq, type SceneMarker as ar, type SceneObject as as, type SensorResult as at, type SiteInfo as au, type SplatAssetConfig as av, type SplatScenarioConfig as aw, type StateSnapshot as ax, type TrajectoryData as ay, type XmlPatch as az, type MujocoSimAPI as b, type MujocoModule as c, type MujocoModel as d, type MujocoData as e, type ControlGroupSelector as f, type ObservationResult as g, type IkContextValue as h, type IkGizmoProps as i, type SceneLightsProps as j, type ScenarioLightingProps as k, type SplatEnvironmentProps as l, type PairedSplatEnvironmentConfig as m, type SplatFormat as n, type SplatCollisionProxyConfig as o, type SplatRendererKind as p, type SplatCollisionPrimitive as q, type ScenarioLightingPreset as r, type SplatEnvironmentMetadataInput as s, type SplatEnvironmentMetadata as t, type DebugProps as u, type ContactListenerProps as v, type ActuatorInfo as w, type Sites as x, type SitePositionResult as y, type Sensors as z };
+export { type PolicyConfig as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type ActuatorInfo as E, type Sites as F, type GeomInfo as G, type SitePositionResult as H, type IkConfig as I, type Sensors as J, type SensorHandle as K, type SensorInfo as L, type MujocoContextValue as M, type Joints as N, type ObservationConfig as O, type PhysicsStepCallback as P, type JointStateResult as Q, type ReadyCallbackInput as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type Bodies as U, type VisualScenarioEffectsProps as V, type BodyStateResult as W, type Actuators as X, type CtrlHandle as Y, type ContactInfo as Z, type KeyboardTeleopConfig as _, type MujocoCanvasProps as a, type PolicyVector as a0, type ObservationHandle as a1, type TrajectoryInput as a2, type TrajectoryStateChangeInput as a3, type PlaybackState as a4, type TrajectoryFrame as a5, type BodyInfo as a6, type ControlJointInfo as a7, type Geoms as a8, type IKSolveFn as a9, RobotResources as aA, RobotSensors as aB, RobotSites as aC, type Robots as aD, type ScenarioCameraConfig as aE, type ScenarioMaterialConfig as aF, type SceneMarker as aG, type SceneObject as aH, type SensorResult as aI, type SiteInfo as aJ, type SplatAssetConfig as aK, type SplatScenarioConfig as aL, type StateSnapshot as aM, type TrajectoryData as aN, type TrajectoryFrameCallbackInput as aO, type VisualScenarioMaterialFilterInput as aP, type XmlPatch as aQ, getContact as aR, registerRobotResources as aS, type IkGizmoDragInput as aa, type IkSolveInput as ab, type JointInfo as ac, type KeyBinding as ad, type Keyframes as ae, type ModelOptions as af, type MujocoContact as ag, type MujocoContactArray as ah, type ObservationLayoutItem as ai, type ObservationOutput as aj, type PhysicsConfig as ak, type PhysicsStepInput as al, type PolicyActionInput as am, type PolicyInferenceInput as an, type PolicyObservationInput as ao, type RayHit as ap, type Register as aq, type RegisteredRobotMap as ar, type ResetCallbackInput as as, type ResourceSelector as at, RobotActuators as au, RobotBodies as av, RobotGeoms as aw, RobotJoints as ax, RobotKeyframes as ay, type RobotResource as az, type MujocoSimAPI as b, type StepCallbackInput as c, type SelectionCallbackInput as d, type MujocoModule as e, type MujocoModel as f, type MujocoData as g, type ControlGroupSelector as h, type ObservationResult as i, type IkContextValue as j, type IkGizmoProps as k, type SceneLightsProps as l, type ScenarioLightingProps as m, type SplatEnvironmentProps as n, type VisualScenarioConfig as o, type SplatRendererKind as p, type PairedSplatEnvironmentConfig as q, type SplatFormat as r, type SplatCollisionProxyConfig as s, type SplatCollisionPrimitive as t, type ScenarioLightingPreset as u, type SplatEnvironmentMetadataInput as v, type SplatEnvironmentMetadata as w, type SplatSceneInput as x, type DebugProps as y, type ContactListenerProps as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mujoco-react",
-  "version": "8.10.0",
+  "version": "9.0.0",
   "description": "Composable React Three Fiber building blocks for MuJoCo WASM simulations",
   "type": "module",
   "main": "./dist/index.js",

package/src/components/Body.tsx

@@ -30,6 +30,7 @@ export function Body({
   solref,
   solimp,
   condim,
+  group,
   children,
 }: BodyProps) {
   const { bodyRegistryRef, hiddenBodiesRef, requestBodyReload, mjDataRef, mjModelRef, status } =
@@ -53,6 +54,7 @@ export function Body({
       solref,
       solimp,
       condim,
+      group,
     };
     bodyRegistryRef.current.set(name, { definition, hasCustomChildren: hasChildren });
     if (hasChildren) {
@@ -66,7 +68,7 @@ export 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]);
 
   // Resolve body ID once the scene is ready
   useEffect(() => {

package/src/components/DragInteraction.tsx

@@ -168,7 +168,7 @@ export function DragInteraction({
   }, [gl, camera, scene, controls, mjDataRef]);
 
   // Apply spring force each physics frame
-  useBeforePhysicsStep((model, data) => {
+  useBeforePhysicsStep(({ model, data }) => {
     if (!draggingRef.current || bodyIdRef.current <= 0) return;
 
     const bid = bodyIdRef.current;

package/src/components/IkGizmo.tsx

@@ -26,7 +26,7 @@ const _scale = new THREE.Vector3(1, 1, 1);
  * - `controller` — IkContextValue from `useIkController()`.
  * - `siteName` — MuJoCo site to track. Defaults to the controller's configured site.
  * - `scale` — Gizmo handle scale. Default: 0.18.
- * - `onDrag` — Custom drag callback `(pos, quat) => void`.
+ * - `onDrag` — Custom drag callback `({ position, quaternion }) => void`.
  *   When omitted, dragging enables IK and writes to the IK target.
  *   When provided, the consumer handles what happens during drag.
  */
@@ -112,7 +112,7 @@ export function IkGizmo({ controller, siteName, scale = 0.18, onDrag }: IkGizmoP
           world.decompose(_pos, _quat, _scale);
           if (onDrag) {
             // Custom: consumer handles the drag
-            onDrag(_pos.clone(), _quat.clone());
+            onDrag({ position: _pos.clone(), quaternion: _quat.clone() });
           } else {
             // Default: write to IK target
             const target = ikTargetRef.current;

package/src/components/SceneRenderer.tsx

@@ -139,7 +139,7 @@ export function SceneRenderer(props: Omit<ThreeElements['group'], 'ref'>) {
           const model = mjModelRef.current;
           if (model && bodyID < model.nbody && onSelectionRef.current) {
             const name = getName(model, model.name_bodyadr[bodyID]);
-            onSelectionRef.current(bodyID, name);
+            onSelectionRef.current({ bodyId: bodyID, name });
           }
         }
       }}

package/src/components/TrajectoryPlayer.tsx

@@ -54,7 +54,10 @@ export function TrajectoryPlayer({
     const currentFrame = player.frame;
     if (currentFrame !== lastReportedFrameRef.current && player.playing) {
       lastReportedFrameRef.current = currentFrame;
-      onFrameRef.current(currentFrame);
+      onFrameRef.current({
+        frameIndex: currentFrame,
+        frame: trajectory[currentFrame],
+      });
     }
   });