mujoco-react 9.2.0 → 9.4.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 { n as SplatEnvironmentProps } from './types-S8ggQY2n.js';
+import { n as SplatEnvironmentProps, q as PairedSplatEnvironmentConfig, S as SceneConfig, t as SplatEnvironmentReadiness, o as VisualScenarioConfig } from './types-BuJ4boaq.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';
@@ -17,6 +17,14 @@ interface SparkSplatLifecycle {
     props: Pick<SparkSplatEnvironmentProps, 'onStatusChange' | 'onError'>;
     reset: () => void;
 }
+interface SparkSplatEnvironmentState {
+    environment: PairedSplatEnvironmentConfig | undefined;
+    sceneConfig: SceneConfig;
+    readiness: SplatEnvironmentReadiness;
+    lifecycle: SparkSplatLifecycle;
+    props: Pick<SparkSplatEnvironmentProps, 'environment' | 'scenario' | 'src' | 'format' | 'onStatusChange' | 'onError'>;
+    enabled: boolean;
+}
 interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {
     /** Enable Spark LoD handling for large splat assets. Default: true. */
     lod?: boolean | 'quality';
@@ -30,6 +38,20 @@ interface SparkSplatEnvironmentProps extends SplatEnvironmentProps {
     onLoad?: (mesh: SparkSplatMeshInstance) => void;
     onError?: (error: Error) => void;
 }
+/**
+ * Resolve a visual scenario's paired splat environment, compose its MJCF
+ * collision proxy into the MuJoCo scene config, and expose Spark lifecycle
+ * props for `<SparkSplatEnvironment />`.
+ */
+declare function useSparkSplatEnvironment({ sceneConfig, scenario, environment, enabled, renderer, onError, onStatusChange, }: {
+    sceneConfig: SceneConfig;
+    scenario?: VisualScenarioConfig;
+    environment?: PairedSplatEnvironmentConfig;
+    enabled?: boolean;
+    renderer?: 'spark';
+    onError?: (error: Error) => void;
+    onStatusChange?: (status: SparkSplatStatus) => void;
+}): SparkSplatEnvironmentState;
 /**
  * Tracks Spark 3DGS loading state for UI that wraps `SparkSplatEnvironment`.
  *
@@ -50,4 +72,4 @@ declare function useSparkSplatLifecycle({ enabled, initialStatus, onError, onSta
  */
 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 SparkSplatLifecycle, type SparkSplatStatus, useSparkSplatLifecycle };
+export { SparkSplatEnvironment, type SparkSplatEnvironmentProps, type SparkSplatEnvironmentState, type SparkSplatLifecycle, type SparkSplatStatus, useSparkSplatEnvironment, useSparkSplatLifecycle };

package/dist/spark.js

@@ -1,9 +1,56 @@
-import { useSplatEnvironment, SplatEnvironment } from './chunk-33CV6HSV.js';
+import { useSplatSceneConfig, useSplatEnvironment, SplatEnvironment } from './chunk-VDSEPZYQ.js';
 import { useThree } from '@react-three/fiber';
-import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
+import { useMemo, useState, useEffect, useCallback, useRef } from 'react';
 import * as THREE from 'three';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
+var sparkDisposeRejectionHandlerRegistered = false;
+function useSparkSplatEnvironment({
+  sceneConfig,
+  scenario,
+  environment,
+  enabled = true,
+  renderer = "spark",
+  onError,
+  onStatusChange
+}) {
+  const splatScene = useSplatSceneConfig({
+    sceneConfig,
+    scenario,
+    environment,
+    enabled,
+    renderer
+  });
+  const metadata = useSplatEnvironment({
+    scenario,
+    environment: splatScene.environment,
+    renderer
+  });
+  const renderEnabled = enabled && Boolean(metadata.src);
+  const readiness = enabled ? metadata.readiness : splatScene.readiness;
+  const lifecycle = useSparkSplatLifecycle({
+    enabled: renderEnabled,
+    onError,
+    onStatusChange
+  });
+  return useMemo(
+    () => ({
+      environment: splatScene.environment,
+      sceneConfig: splatScene.sceneConfig,
+      readiness,
+      lifecycle,
+      props: {
+        environment: splatScene.environment,
+        scenario: enabled ? scenario : void 0,
+        src: enabled ? metadata.src : void 0,
+        format: metadata.format,
+        ...lifecycle.props
+      },
+      enabled: renderEnabled
+    }),
+    [enabled, lifecycle, metadata, readiness, renderEnabled, scenario, splatScene]
+  );
+}
 function useSparkSplatLifecycle({
   enabled = true,
   initialStatus,
@@ -101,6 +148,7 @@ function SparkSplatEnvironment({
   }, [onError]);
   useEffect(() => {
     let disposed = false;
+    ensureSparkDisposeRejectionHandler();
     function setLifecycleStatus(nextStatus) {
       setStatus(nextStatus);
       onStatusChangeRef.current?.(nextStatus);
@@ -208,6 +256,7 @@ function SparkSplatEnvironment({
 }
 function safelyDisposeSparkResource(resource) {
   try {
+    silenceSparkWorkerTerminateRejections(resource);
     const result = resource.dispose?.();
     if (isPromiseLike(result)) {
       void Promise.resolve(result).catch(handleSparkDisposeError);
@@ -219,17 +268,54 @@ function safelyDisposeSparkResource(resource) {
 function isPromiseLike(value) {
   return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
 }
+function silenceSparkWorkerTerminateRejections(resource) {
+  const workers = getSparkWorkers(resource);
+  for (const worker of workers) {
+    if (!worker.messages) continue;
+    for (const message of Object.values(worker.messages)) {
+      const reject = message.reject;
+      if (!reject) continue;
+      message.reject = (error) => {
+        if (!isSparkWorkerTerminateError(error)) {
+          reject(error);
+        }
+      };
+    }
+  }
+}
+function getSparkWorkers(resource) {
+  const sparkResource = resource;
+  return [
+    sparkResource.worker,
+    sparkResource.sortWorker,
+    sparkResource.lodWorker
+  ].filter((worker) => Boolean(worker));
+}
 function handleSparkDisposeError(error) {
   if (error instanceof Error && error.message.toLowerCase().includes("worker terminate")) {
     return;
   }
   console.warn("[mujoco-react] Spark resource disposal failed.", error);
 }
+function ensureSparkDisposeRejectionHandler() {
+  if (sparkDisposeRejectionHandlerRegistered || typeof window === "undefined" || typeof window.addEventListener !== "function") {
+    return;
+  }
+  sparkDisposeRejectionHandlerRegistered = true;
+  window.addEventListener("unhandledrejection", (event) => {
+    if (isSparkWorkerTerminateError(event.reason)) {
+      event.preventDefault();
+    }
+  });
+}
+function isSparkWorkerTerminateError(reason) {
+  return reason instanceof Error && reason.message.toLowerCase().includes("worker terminate");
+}
 /**
  * @license
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export { SparkSplatEnvironment, useSparkSplatLifecycle };
+export { SparkSplatEnvironment, useSparkSplatEnvironment, 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 {\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"]}
+{"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  useSplatSceneConfig,\n} from './components/VisualScenario';\nimport type {\n  PairedSplatEnvironmentConfig,\n  SceneConfig,\n  SplatEnvironmentProps,\n  SplatEnvironmentReadiness,\n  VisualScenarioConfig,\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};\ntype SparkWorkerMessage = {\n  reject?: (error: unknown) => void;\n};\ntype SparkWorkerLike = {\n  messages?: Record<string, SparkWorkerMessage>;\n};\ntype SparkResourceWithWorkers = SparkDisposable & {\n  worker?: SparkWorkerLike;\n  sortWorker?: SparkWorkerLike;\n  lodWorker?: SparkWorkerLike;\n};\n\nexport type SparkSplatStatus = 'idle' | 'loading' | 'ready' | 'error';\n\nlet sparkDisposeRejectionHandlerRegistered = false;\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 SparkSplatEnvironmentState {\n  environment: PairedSplatEnvironmentConfig | undefined;\n  sceneConfig: SceneConfig;\n  readiness: SplatEnvironmentReadiness;\n  lifecycle: SparkSplatLifecycle;\n  props: Pick<\n    SparkSplatEnvironmentProps,\n    'environment' | 'scenario' | 'src' | 'format' | 'onStatusChange' | 'onError'\n  >;\n  enabled: boolean;\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 * Resolve a visual scenario's paired splat environment, compose its MJCF\n * collision proxy into the MuJoCo scene config, and expose Spark lifecycle\n * props for `<SparkSplatEnvironment />`.\n */\nexport function useSparkSplatEnvironment({\n  sceneConfig,\n  scenario,\n  environment,\n  enabled = true,\n  renderer = 'spark',\n  onError,\n  onStatusChange,\n}: {\n  sceneConfig: SceneConfig;\n  scenario?: VisualScenarioConfig;\n  environment?: PairedSplatEnvironmentConfig;\n  enabled?: boolean;\n  renderer?: 'spark';\n  onError?: (error: Error) => void;\n  onStatusChange?: (status: SparkSplatStatus) => void;\n}): SparkSplatEnvironmentState {\n  const splatScene = useSplatSceneConfig({\n    sceneConfig,\n    scenario,\n    environment,\n    enabled,\n    renderer,\n  });\n  const metadata = useSplatEnvironment({\n    scenario,\n    environment: splatScene.environment,\n    renderer,\n  });\n  const renderEnabled = enabled && Boolean(metadata.src);\n  const readiness = enabled ? metadata.readiness : splatScene.readiness;\n  const lifecycle = useSparkSplatLifecycle({\n    enabled: renderEnabled,\n    onError,\n    onStatusChange,\n  });\n\n  return useMemo(\n    () => ({\n      environment: splatScene.environment,\n      sceneConfig: splatScene.sceneConfig,\n      readiness,\n      lifecycle,\n      props: {\n        environment: splatScene.environment,\n        scenario: enabled ? scenario : undefined,\n        src: enabled ? metadata.src : undefined,\n        format: metadata.format,\n        ...lifecycle.props,\n      },\n      enabled: renderEnabled,\n    }),\n    [enabled, lifecycle, metadata, readiness, renderEnabled, scenario, splatScene]\n  );\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    ensureSparkDisposeRejectionHandler();\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    silenceSparkWorkerTerminateRejections(resource);\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 silenceSparkWorkerTerminateRejections(resource: SparkDisposable) {\n  const workers = getSparkWorkers(resource);\n  for (const worker of workers) {\n    if (!worker.messages) continue;\n\n    for (const message of Object.values(worker.messages)) {\n      const reject = message.reject;\n      if (!reject) continue;\n\n      message.reject = (error: unknown) => {\n        if (!isSparkWorkerTerminateError(error)) {\n          reject(error);\n        }\n      };\n    }\n  }\n}\n\nfunction getSparkWorkers(resource: SparkDisposable): SparkWorkerLike[] {\n  const sparkResource = resource as SparkResourceWithWorkers;\n  return [\n    sparkResource.worker,\n    sparkResource.sortWorker,\n    sparkResource.lodWorker,\n  ].filter((worker): worker is SparkWorkerLike => Boolean(worker));\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\nfunction ensureSparkDisposeRejectionHandler() {\n  if (\n    sparkDisposeRejectionHandlerRegistered ||\n    typeof window === 'undefined' ||\n    typeof window.addEventListener !== 'function'\n  ) {\n    return;\n  }\n\n  sparkDisposeRejectionHandlerRegistered = true;\n  window.addEventListener('unhandledrejection', (event) => {\n    if (isSparkWorkerTerminateError(event.reason)) {\n      event.preventDefault();\n    }\n  });\n}\n\nfunction isSparkWorkerTerminateError(reason: unknown) {\n  return (\n    reason instanceof Error &&\n    reason.message.toLowerCase().includes('worker terminate')\n  );\n}\n"]}

package/dist/{types-S8ggQY2n.d.ts → types-BuJ4boaq.d.ts}

@@ -39,7 +39,7 @@ type Robots = [RegisteredRobotMap] extends [never] ? string : Extract<keyof Regi
 type RobotResource<TRobot extends string, TKey extends string> = [
     RegisteredRobotMap
 ] extends [never] ? string : TRobot extends keyof RegisteredRobotMap ? TKey extends keyof RegisteredRobotMap[TRobot] ? RegisteredRobotMap[TRobot][TKey] : string : never;
-type RegisterResourceKey = 'actuators' | 'sensors' | 'bodies' | 'joints' | 'sites' | 'geoms' | 'keyframes';
+type RegisterResourceKey = 'actuators' | 'sensors' | 'bodies' | 'joints' | 'sites' | 'geoms' | 'keyframes' | 'cameras';
 type RobotResourceObject<TRobot extends string, TKey extends RegisterResourceKey> = string extends RobotResource<TRobot, TKey> ? Record<string, string> : {
     readonly [K in RobotResource<TRobot, TKey>]: K;
 };
@@ -68,6 +68,8 @@ type RobotGeoms<TRobot extends string> = RobotResource<TRobot, 'geoms'>;
 declare const RobotGeoms: RobotResourceCategory<'geoms'>;
 type RobotKeyframes<TRobot extends string> = RobotResource<TRobot, 'keyframes'>;
 declare const RobotKeyframes: RobotResourceCategory<'keyframes'>;
+type RobotCameras<TRobot extends string> = RobotResource<TRobot, 'cameras'>;
+declare const RobotCameras: RobotResourceCategory<'cameras'>;
 type Actuators = Register extends {
     actuators: infer T extends string;
 } ? T : string;
@@ -89,6 +91,9 @@ type Geoms = Register extends {
 type Keyframes = Register extends {
     keyframes: infer T extends string;
 } ? T : string;
+type Cameras = Register extends {
+    cameras: infer T extends string;
+} ? T : string;
 /**
  * A single MuJoCo contact from the WASM module.
  * Accessed via `data.contact.get(i)`.
@@ -131,6 +136,7 @@ interface MujocoModel {
     nflex: number;
     nmesh: number;
     nmat: number;
+    ncam?: number;
     names: Int8Array;
     name_bodyadr: Int32Array;
     name_jntadr: Int32Array;
@@ -140,6 +146,7 @@ interface MujocoModel {
     name_keyadr: Int32Array;
     name_sensoradr: Int32Array;
     name_tendonadr: Int32Array;
+    name_camadr?: Int32Array;
     body_mass: Float64Array;
     body_parentid: Int32Array;
     body_jntnum: Int32Array;
@@ -204,6 +211,10 @@ interface MujocoModel {
     light_cutoff: Float32Array;
     light_exponent: Float32Array;
     light_intensity: Float32Array;
+    cam_bodyid?: Int32Array;
+    cam_pos?: Float64Array;
+    cam_quat?: Float64Array;
+    cam_fovy?: Float64Array;
     ten_wrapadr: Int32Array;
     ten_wrapnum: Int32Array;
     ten_range: Float64Array;
@@ -240,6 +251,9 @@ interface MujocoData {
     qfrc_bias: Float64Array;
     site_xpos: Float64Array;
     site_xmat: Float64Array;
+    cam_xpos?: Float64Array;
+    cam_xmat?: Float64Array;
+    xmat?: Float64Array;
     sensordata: Float64Array;
     ncon: number;
     contact: MujocoContactArray;
@@ -519,6 +533,14 @@ interface SensorInfo {
     dim: number;
     adr: number;
 }
+interface CameraInfo {
+    id: number;
+    name: string;
+    bodyId: number;
+    fov: number | null;
+    position: [number, number, number] | null;
+    quaternion: [number, number, number, number] | null;
+}
 interface ContactInfo {
     geom1: number;
     geom1Name: string;
@@ -691,11 +713,28 @@ interface PairedSplatEnvironmentConfig {
     description?: string;
     /** Visual-only Gaussian splat asset. */
     splat: SplatAssetConfig;
-    /** MJCF/XML contact geometry paired with the visual splat. */
-    collisionProxy: SplatCollisionProxyConfig & {
+    /** Optional MJCF/XML contact geometry paired with the visual splat. */
+    collisionProxy?: SplatCollisionProxyConfig & {
         xmlPath: string;
     };
 }
+declare const SplatEnvironmentReadinessStatus: {
+    readonly Disabled: "disabled";
+    readonly MissingSplat: "missing-splat";
+    readonly MissingCollisionProxy: "missing-collision-proxy";
+    readonly UnsupportedFormat: "unsupported-format";
+    readonly Ready: "ready";
+};
+type SplatEnvironmentReadinessStatus = (typeof SplatEnvironmentReadinessStatus)[keyof typeof SplatEnvironmentReadinessStatus];
+interface SplatEnvironmentReadiness {
+    status: SplatEnvironmentReadinessStatus;
+    ready: boolean;
+    requiresCollisionProxy: boolean;
+    missing: Array<'splat' | 'collisionProxy'>;
+    format?: SplatFormat;
+    renderer?: SplatRendererKind;
+    message: string;
+}
 interface SplatEnvironmentMetadataInput {
     environment?: PairedSplatEnvironmentConfig;
     scenario?: VisualScenarioConfig;
@@ -708,9 +747,61 @@ interface SplatEnvironmentMetadata {
     src?: string;
     format: SplatFormat;
     collisionProxy?: SplatCollisionProxyConfig;
+    readiness: SplatEnvironmentReadiness;
     userData: Record<string, unknown>;
 }
+interface ResolvedScenarioCameraConfig {
+    jitter: number;
+    exposure: number;
+    noise: number;
+    blur: number;
+}
+interface ResolvedScenarioMaterialConfig {
+    randomizeObjectColors: boolean;
+    randomizeTableMaterial: boolean;
+    roughness?: number;
+    metalness?: number;
+}
+interface VisualScenarioExecutionContext {
+    scenarioId: string;
+    scenarioLabel: string;
+    variantId?: string;
+    seed: number;
+    lighting: ScenarioLightingPreset;
+    environment?: string;
+    camera: ResolvedScenarioCameraConfig;
+    materials: ResolvedScenarioMaterialConfig;
+    splatEnabled: boolean;
+    splatSrc?: string;
+    splatFormat: SplatFormat;
+    splatRenderer?: SplatRendererKind;
+    collisionProxyXmlPath?: string;
+    collisionProxyStatus?: SplatCollisionProxyConfig['status'];
+    collisionProxyPrimitives: SplatCollisionPrimitive[];
+    readiness: SplatEnvironmentReadiness;
+    transformSource: 'visualScenario.camera';
+}
+interface VisualScenarioExecutionContextInput {
+    scenario?: VisualScenarioConfig;
+    environment?: PairedSplatEnvironmentConfig;
+    renderer?: SplatRendererKind;
+    variantId?: string;
+    enabled?: boolean;
+}
 type SplatSceneInput = PairedSplatEnvironmentConfig | VisualScenarioConfig | undefined | null;
+interface SplatSceneConfigInput {
+    sceneConfig: SceneConfig;
+    scenario?: VisualScenarioConfig;
+    environment?: PairedSplatEnvironmentConfig;
+    enabled?: boolean;
+    renderer?: SplatRendererKind;
+}
+interface SplatSceneConfigState {
+    environment: PairedSplatEnvironmentConfig | undefined;
+    sceneConfig: SceneConfig;
+    enabled: boolean;
+    readiness: SplatEnvironmentReadiness;
+}
 interface VisualScenarioConfig {
     id?: string;
     label?: string;
@@ -826,6 +917,7 @@ interface MujocoSimAPI {
     getSites(): SiteInfo[];
     getActuators(): ActuatorInfo[];
     getSensors(): SensorInfo[];
+    getCameras(): CameraInfo[];
     getModelOption(): ModelOptions;
     setGravity(g: [number, number, number]): void;
     setTimestep(dt: number): void;
@@ -886,7 +978,14 @@ interface FrameCaptureAPI {
 type CameraFrameCaptureVector3 = THREE.Vector3 | readonly [number, number, number];
 type CameraFrameCaptureQuaternion = THREE.Quaternion | readonly [number, number, number, number];
 interface CameraFrameCaptureOptions {
+    /** Existing Three camera to clone before applying pose overrides. */
     camera?: THREE.Camera;
+    /** Named MuJoCo `<camera>` to render from when available in the loaded model. */
+    cameraName?: Cameras;
+    /** Named MuJoCo site to use as the rendered camera pose. Useful for robot-mounted optical frames. */
+    siteName?: Sites;
+    /** Named MuJoCo body to use as the rendered camera pose. */
+    bodyName?: Bodies;
     position?: CameraFrameCaptureVector3;
     lookAt?: CameraFrameCaptureVector3;
     quaternion?: CameraFrameCaptureQuaternion;
@@ -898,7 +997,25 @@ interface CameraFrameCaptureOptions {
     fov?: number;
     near?: number;
     far?: number;
-}
+    /** Provenance for the camera pose used by the capture. Usually set by the MuJoCo provider. */
+    source?: CameraFrameCaptureSource;
+}
+type CameraFrameCaptureSource = {
+    kind: 'mujoco-camera';
+    cameraName: Cameras;
+} | {
+    kind: 'mujoco-site';
+    siteName: Sites;
+} | {
+    kind: 'mujoco-body';
+    bodyName: Bodies;
+} | {
+    kind: 'custom-camera';
+} | {
+    kind: 'explicit-pose';
+} | {
+    kind: 'fallback-camera';
+};
 interface CameraFrameCaptureResult {
     canvas: HTMLCanvasElement;
     camera: THREE.Camera;
@@ -906,6 +1023,7 @@ interface CameraFrameCaptureResult {
     type: string;
     width: number;
     height: number;
+    source: CameraFrameCaptureSource;
 }
 interface CameraFrameCaptureBlobResult {
     canvas: HTMLCanvasElement;
@@ -914,6 +1032,7 @@ interface CameraFrameCaptureBlobResult {
     type: string;
     width: number;
     height: number;
+    source: CameraFrameCaptureSource;
 }
 interface CameraFrameCaptureAPI {
     status: FrameCaptureStatus;
@@ -931,17 +1050,53 @@ interface CameraFrameSequenceFrame {
     time: number;
     cameras: Record<string, CameraFrameCaptureResult>;
 }
+interface CameraFrameSequenceCameraSummary {
+    key: string;
+    width: number;
+    height: number;
+    source: CameraFrameCaptureSource;
+    frameCount: number;
+    firstFrameIndex: number | null;
+    lastFrameIndex: number | null;
+    firstTimestamp: number | null;
+    lastTimestamp: number | null;
+}
+interface CameraFrameSequenceSampleInput extends PhysicsStepInput {
+    frameIndex: number;
+    time: number;
+}
+interface CameraFrameSequenceStepInput extends PhysicsStepInput {
+    frameIndex: number;
+    stepIndex: number;
+    time: number;
+}
 interface CameraFrameSequenceOptions {
     cameras: readonly CameraFrameSequenceCamera[];
     frames: number;
+    /** Number of MuJoCo steps between captured frames. Use 0 for static camera provenance captures. */
     stepsPerFrame?: number;
     reset?: boolean;
     captureInitialFrame?: boolean;
+    retainFrames?: boolean;
+    /**
+     * Require each recorded stream to resolve from exactly one mounted MuJoCo
+     * camera/site/body selector. Defaults to true because sequence recording is
+     * intended for dataset/policy camera streams.
+     */
+    requireMountedSources?: boolean;
+    signal?: AbortSignal;
+    /** Called after stepping and before image capture for this frame. Use this to record synchronized state/action rows. */
+    onSample?: (input: CameraFrameSequenceSampleInput) => void | Promise<void>;
+    /** Called before each MuJoCo step inside sequence recording. Use this to apply policy/control actions. */
+    onBeforeStep?: (input: CameraFrameSequenceStepInput) => void | Promise<void>;
+    /** Called after each MuJoCo step inside sequence recording. Use this for step-level telemetry. */
+    onAfterStep?: (input: CameraFrameSequenceStepInput) => void | Promise<void>;
     onFrame?: (frame: CameraFrameSequenceFrame) => void | Promise<void>;
 }
 interface CameraFrameSequenceResult {
     frames: CameraFrameSequenceFrame[];
     cameraKeys: string[];
+    cameraSummaries: Record<string, CameraFrameSequenceCameraSummary>;
     frameCount: number;
 }
 interface CameraFrameSequenceRecorderAPI {
@@ -1009,4 +1164,4 @@ interface JointStateResult {
     velocity: React__default.RefObject<number | Float64Array>;
 }
 
-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 SensorResult 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 FrameCaptureOptions as a6, type FrameCaptureResult as a7, type FrameCaptureBlobResult as a8, type FrameCaptureAPI as a9, type MujocoFrameCaptureOptions as aA, type ObservationLayoutItem as aB, type ObservationOutput as aC, type PhysicsConfig as aD, type PhysicsStepInput as aE, type PolicyActionInput as aF, type PolicyInferenceInput as aG, type PolicyObservationInput as aH, type RayHit as aI, type Register as aJ, type RegisteredRobotMap as aK, type ResetCallbackInput as aL, type ResourceSelector as aM, RobotActuators as aN, RobotBodies as aO, RobotGeoms as aP, RobotJoints as aQ, RobotKeyframes as aR, type RobotResource as aS, RobotResources as aT, RobotSensors as aU, RobotSites as aV, type Robots as aW, type ScenarioCameraConfig as aX, type ScenarioMaterialConfig as aY, type SceneMarker as aZ, type SceneObject as a_, type CameraFrameCaptureOptions as aa, type CameraFrameCaptureAPI as ab, type CameraFrameSequenceRecorderAPI as ac, type CameraFrameCaptureResult as ad, type CameraFrameCaptureBlobResult as ae, type BodyInfo as af, type CameraFrameCaptureQuaternion as ag, type CameraFrameCaptureVector3 as ah, type CameraFrameSequenceCamera as ai, type CameraFrameSequenceFrame as aj, type CameraFrameSequenceOptions as ak, type CameraFrameSequenceResult as al, type ControlJointInfo as am, type FrameCaptureStatus as an, type FrameCaptureTarget as ao, type FrameCaptureTargetRef as ap, type Geoms as aq, type IKSolveFn as ar, type IkGizmoDragInput as as, type IkSolveInput as at, type JointInfo as au, type KeyBinding as av, type Keyframes as aw, type ModelOptions as ax, type MujocoContact as ay, type MujocoContactArray as az, type MujocoSimAPI as b, type SiteInfo as b0, type SplatAssetConfig as b1, type SplatScenarioConfig as b2, type StateSnapshot as b3, type TrajectoryData as b4, type TrajectoryFrameCallbackInput as b5, type VisualScenarioMaterialFilterInput as b6, type XmlPatch as b7, getContact as b8, registerRobotResources as b9, 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 };
+export { type Bodies as $, type ActuatedJointInfo as A, type BodyProps as B, type ControlGroupInfo as C, type DragInteractionProps as D, type ScenarioLightingPreset as E, type SplatEnvironmentMetadataInput as F, type SplatEnvironmentMetadata as G, type SplatSceneInput as H, type IkConfig as I, type DebugProps as J, type GeomInfo as K, type ContactListenerProps as L, type MujocoContextValue as M, type ActuatorInfo as N, type ObservationConfig as O, type PhysicsStepCallback as P, type Sites as Q, type ReadyCallbackInput as R, type SceneConfig as S, type TrajectoryPlayerProps as T, type SitePositionResult as U, type VisualScenarioEffectsProps as V, type Sensors as W, type SensorHandle as X, type SensorInfo as Y, type Joints as Z, type JointStateResult as _, type MujocoCanvasProps as a, RobotActuators as a$, type BodyStateResult as a0, type Actuators as a1, type CtrlHandle as a2, type ContactInfo as a3, type KeyboardTeleopConfig as a4, type PolicyConfig as a5, type PolicyVector as a6, type ObservationHandle as a7, type TrajectoryInput as a8, type TrajectoryStateChangeInput as a9, type FrameCaptureTarget as aA, type FrameCaptureTargetRef as aB, type Geoms as aC, type IKSolveFn as aD, type IkGizmoDragInput as aE, type IkSolveInput as aF, type JointInfo as aG, type KeyBinding as aH, type Keyframes as aI, type ModelOptions as aJ, type MujocoContact as aK, type MujocoContactArray as aL, type MujocoFrameCaptureOptions as aM, type ObservationLayoutItem as aN, type ObservationOutput as aO, type PhysicsConfig as aP, type PhysicsStepInput as aQ, type PolicyActionInput as aR, type PolicyInferenceInput as aS, type PolicyObservationInput as aT, type RayHit as aU, type Register as aV, type RegisteredRobotMap as aW, type ResetCallbackInput as aX, type ResolvedScenarioCameraConfig as aY, type ResolvedScenarioMaterialConfig as aZ, type ResourceSelector as a_, type PlaybackState as aa, type TrajectoryFrame as ab, type FrameCaptureOptions as ac, type FrameCaptureResult as ad, type FrameCaptureBlobResult as ae, type FrameCaptureAPI as af, type CameraFrameCaptureOptions as ag, type CameraFrameCaptureAPI as ah, type CameraFrameSequenceRecorderAPI as ai, type Cameras as aj, type CameraFrameSequenceCamera as ak, type CameraFrameCaptureSource as al, type CameraFrameSequenceOptions as am, type CameraFrameSequenceResult as an, type CameraFrameCaptureResult as ao, type CameraFrameCaptureBlobResult as ap, type BodyInfo as aq, type CameraFrameCaptureQuaternion as ar, type CameraFrameCaptureVector3 as as, type CameraFrameSequenceCameraSummary as at, type CameraFrameSequenceFrame as au, type CameraFrameSequenceSampleInput as av, type CameraFrameSequenceStepInput as aw, type CameraInfo as ax, type ControlJointInfo as ay, type FrameCaptureStatus as az, type MujocoSimAPI as b, RobotBodies as b0, RobotCameras as b1, RobotGeoms as b2, RobotJoints as b3, RobotKeyframes as b4, type RobotResource as b5, RobotResources as b6, RobotSensors as b7, RobotSites as b8, type Robots as b9, type ScenarioCameraConfig as ba, type ScenarioMaterialConfig as bb, type SceneMarker as bc, type SceneObject as bd, type SensorResult as be, type SiteInfo as bf, type SplatAssetConfig as bg, type SplatScenarioConfig as bh, type StateSnapshot as bi, type TrajectoryData as bj, type TrajectoryFrameCallbackInput as bk, type VisualScenarioMaterialFilterInput as bl, type XmlPatch as bm, getContact as bn, registerRobotResources as bo, 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 SplatEnvironmentReadiness as t, type SplatCollisionPrimitive as u, SplatEnvironmentReadinessStatus as v, type SplatSceneConfigInput as w, type SplatSceneConfigState as x, type VisualScenarioExecutionContextInput as y, type VisualScenarioExecutionContext as z };

package/dist/vite.d.ts

@@ -32,7 +32,7 @@ interface MujocoRegisterCodegenResult {
     files: string[];
     counts: Record<RegisterKey, number>;
 }
-type RegisterKey = 'actuators' | 'sensors' | 'bodies' | 'joints' | 'sites' | 'geoms' | 'keyframes';
+type RegisterKey = 'actuators' | 'sensors' | 'bodies' | 'joints' | 'sites' | 'geoms' | 'keyframes' | 'cameras';
 type ModelInput = string | readonly string[] | Record<string, string>;
 declare function mujocoReact(options: MujocoReactPluginOptions): {
     name: string;

package/dist/vite.js

@@ -2,7 +2,7 @@ import { mkdir, writeFile, readFile } from 'fs/promises';
 import path from 'path';
 
 // src/vite.ts
-var REGISTER_KEYS = ["actuators", "sensors", "bodies", "joints", "sites", "geoms", "keyframes"];
+var REGISTER_KEYS = ["actuators", "sensors", "bodies", "joints", "sites", "geoms", "keyframes", "cameras"];
 var MODEL_EXTENSIONS = /* @__PURE__ */ new Set([".xml", ".mjcf", ".urdf"]);
 function createEmptyNames() {
   return {
@@ -12,7 +12,8 @@ function createEmptyNames() {
     joints: /* @__PURE__ */ new Set(),
     sites: /* @__PURE__ */ new Set(),
     geoms: /* @__PURE__ */ new Set(),
-    keyframes: /* @__PURE__ */ new Set()
+    keyframes: /* @__PURE__ */ new Set(),
+    cameras: /* @__PURE__ */ new Set()
   };
 }
 function mujocoReact(options) {
@@ -91,7 +92,7 @@ async function generateMujocoRegister(options) {
   };
 }
 async function scanModel(filePath, root, seen, names) {
-  const normalized = path.normalize(filePath);
+  const normalized = path.resolve(filePath);
   if (seen.has(normalized)) return;
   seen.add(normalized);
   const xml = await readFile(normalized, "utf8");
@@ -99,12 +100,13 @@ async function scanModel(filePath, root, seen, names) {
   collectSimpleTagNames(xml, "joint", names.joints);
   collectSimpleTagNames(xml, "site", names.sites);
   collectSimpleTagNames(xml, "geom", names.geoms);
+  collectSimpleTagNames(xml, "camera", names.cameras);
   collectSimpleTagNames(xml, "key", names.keyframes);
   collectSectionNames(xml, "actuator", names.actuators);
   collectSectionNames(xml, "sensor", names.sensors);
   for (const includePath of collectIncludePaths(xml)) {
     const next = path.resolve(path.dirname(normalized), includePath);
-    if (next.startsWith(root)) await scanModel(next, root, seen, names);
+    if (isPathInsideRoot(next, root)) await scanModel(next, root, seen, names);
   }
 }
 function collectSimpleTagNames(xml, tag, target) {
@@ -217,7 +219,8 @@ function renderNamespaceAliases(models) {
     joints: "RobotJoints",
     sites: "RobotSites",
     geoms: "RobotGeoms",
-    keyframes: "RobotKeyframes"
+    keyframes: "RobotKeyframes",
+    cameras: "RobotCameras"
   };
   const blocks = REGISTER_KEYS.map((key) => {
     const aliases = models.filter((model) => isIdentifier(model.id)).map((model) => `    export type ${model.id} = RobotResource<'${escapeTs(model.id)}', '${key}'>;`);
@@ -251,7 +254,7 @@ function shouldInjectRegisterImport(id, root, generatedRegister) {
   if (file.includes(`${path.sep}node_modules${path.sep}`)) return false;
   const absolute = path.resolve(file);
   if (absolute === generatedRegister) return false;
-  return absolute.startsWith(root);
+  return isPathInsideRoot(absolute, root);
 }
 function renderGeneratedImport(id, generatedRegister) {
   const fromDir = path.dirname(stripQuery(id));
@@ -292,7 +295,11 @@ function shouldRegenerate(file, watchedFiles, models, root) {
   if (watchedFiles.includes(absolute)) return true;
   if (!MODEL_EXTENSIONS.has(path.extname(absolute).toLowerCase())) return false;
   const modelDirs = models.map((model) => path.dirname(path.resolve(root, model.file)));
-  return modelDirs.some((dir) => absolute.startsWith(dir));
+  return modelDirs.some((dir) => isPathInsideRoot(absolute, dir));
+}
+function isPathInsideRoot(filePath, root) {
+  const relative = path.relative(path.resolve(root), path.resolve(filePath));
+  return relative === "" || relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
 }
 /**
  * @license