mujoco-react 11.0.0 → 12.1.0

package/src/core/MujocoSimProvider.tsx

@@ -7,6 +7,10 @@ import { captureSimulationState, restoreSimulationState } from './engineState';
 import { getActuatorInfo, writeActuatorControl } from './SceneLoader';
 import type { ActuatorControlValue, MujocoIntegrator } from '../types';
 
+import { sceneIdentity } from './sceneIdentity';
+import { runStepBudget, type PhysicsPerformance } from './stepBudget';
+import { attachSimulationRuntime, assertMainThreadOwnership, isWorkerOwned, closeModelRuntime, runtimeContacts } from '../runtime/client';
+import type { RuntimeOptions } from '../runtime/types';
 import { useFrame, useThree } from '@react-three/fiber';
 import {
   createContext,
@@ -514,11 +518,12 @@ export function useMujoco(): UseMujocoResult {
 }
 
 export function useBeforePhysicsStep(callback: PhysicsStepCallback) {
-  const { beforeStepCallbacks } = useMujocoContext();
+  const { beforeStepCallbacks, mjModelRef } = useMujocoContext();
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
 
   useEffect(() => {
+    assertMainThreadOwnership(mjModelRef.current);
     const wrapped: PhysicsStepCallback = (input) => callbackRef.current(input);
     beforeStepCallbacks.current.add(wrapped);
     return () => { beforeStepCallbacks.current.delete(wrapped); };
@@ -526,11 +531,12 @@ export function useBeforePhysicsStep(callback: PhysicsStepCallback) {
 }
 
 export function useAfterPhysicsStep(callback: PhysicsStepCallback) {
-  const { afterStepCallbacks } = useMujocoContext();
+  const { afterStepCallbacks, mjModelRef } = useMujocoContext();
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
 
   useEffect(() => {
+    assertMainThreadOwnership(mjModelRef.current);
     const wrapped: PhysicsStepCallback = (input) => callbackRef.current(input);
     afterStepCallbacks.current.add(wrapped);
     return () => { afterStepCallbacks.current.delete(wrapped); };
@@ -550,6 +556,7 @@ interface MujocoSimProviderProps {
   timestep?: number;
   integrator?: MujocoIntegrator;
   substeps?: number;
+  physicsBudgetMs?: number;
   paused?: boolean;
   speed?: number;
   interpolate?: boolean;
@@ -570,6 +577,7 @@ export function MujocoSimProvider({
   timestep,
   integrator,
   substeps,
+  physicsBudgetMs = 8,
   paused,
   speed,
   interpolate,
@@ -577,7 +585,22 @@ export function MujocoSimProvider({
   hiddenBodies,
   children,
 }: MujocoSimProviderProps) {
-  const { gl, camera, scene } = useThree();
+  const { gl, camera, scene, invalidate } = useThree();
+  const modelIdentity = sceneIdentity(config);
+  const performanceRef = useRef<PhysicsPerformance>({ steps: 0, physicsMs: 0, realTimeFactor: 0, backlogSteps: 0, budgetExceeded: false });
+  const displayWaiters = useRef(new Set<() => void>());
+  useFrame(() => {
+    if (displayWaiters.current.size) {
+      const waiters = [...displayWaiters.current];
+      displayWaiters.current.clear();
+      queueMicrotask(() => { scene.updateMatrixWorld(true); for (const ready of waiters) ready(); });
+    }
+  }, 0);
+  const waitForDisplay = () => new Promise<void>((resolve, reject) => {
+    const ready = () => { clearTimeout(timer); resolve(); };
+    const timer = setTimeout(() => { displayWaiters.current.delete(ready); reject(new Error('Canvas did not produce an observation frame within 5 seconds')); }, 5000);
+    displayWaiters.current.add(ready); invalidate();
+  });
   const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
 
   // --- Refs ---
@@ -618,8 +641,8 @@ export function MujocoSimProvider({
 
   configRef.current = config;
   mujocoRef.current = mujoco;
-  pausedRef.current = paused ?? false;
-  speedRef.current = speed ?? 1;
+  useEffect(() => { pausedRef.current = paused ?? false; }, [paused]);
+  useEffect(() => { speedRef.current = speed ?? 1; }, [speed]);
   substepsRef.current = substeps ?? 1;
   interpolateRef.current = interpolate ?? false;
 
@@ -628,10 +651,11 @@ export function MujocoSimProvider({
     if (!gravity) return;
     const model = mjModelRef.current;
     if (!model?.opt?.gravity) return;
+    assertMainThreadOwnership(model);
     model.opt.gravity[0] = gravity[0];
     model.opt.gravity[1] = gravity[1];
     model.opt.gravity[2] = gravity[2];
-  }, [gravity]);
+  }, [gravity?.[0], gravity?.[1], gravity?.[2]]);
 
   const integratorRef = useRef(integrator);
   integratorRef.current = integrator;
@@ -640,7 +664,7 @@ export function MujocoSimProvider({
     if (value !== undefined) model.opt.integrator = { Euler: 0, RK4: 1, implicit: 2, implicitfast: 3, discrete: 4 }[value];
   };
   useEffect(() => {
-    if (mjModelRef.current) applyIntegrator(mjModelRef.current);
+    if (mjModelRef.current) { assertMainThreadOwnership(mjModelRef.current); applyIntegrator(mjModelRef.current); }
   }, [integrator]);
 
   // Sync timestep prop
@@ -648,6 +672,7 @@ export function MujocoSimProvider({
     if (timestep === undefined) return;
     const model = mjModelRef.current;
     if (!model?.opt) return;
+    assertMainThreadOwnership(model);
     model.opt.timestep = timestep;
   }, [timestep]);
 
@@ -694,6 +719,7 @@ export function MujocoSimProvider({
   // --- Load scene on mount ---
   useEffect(() => {
     let disposed = false;
+    setStatus('loading');
 
     (async () => {
       try {
@@ -734,6 +760,7 @@ export function MujocoSimProvider({
 
     return () => {
       disposed = true;
+      closeModelRuntime(mjModelRef.current);
       mjDataRef.current?.delete();
       mjModelRef.current?.delete();
       mjModelRef.current = null;
@@ -742,7 +769,7 @@ export function MujocoSimProvider({
       interpolationStateRef.current.valid = false;
       try { mujoco.FS.unmount('/working'); } catch { /* ignore */ }
     };
-  }, [mujoco, config]);
+  }, [mujoco, modelIdentity]);
 
   // Fire onReady and assign external ref when status changes to ready
   useEffect(() => {
@@ -766,77 +793,40 @@ export function MujocoSimProvider({
     const data = mjDataRef.current;
     if (!model || !data) return;
 
-    // Check single-step mode
-    const shouldStep = !pausedRef.current || stepsToRunRef.current > 0;
-    if (!shouldStep) return;
-
-    // Zero generalized applied forces
-    for (let i = 0; i < model.nv; i++) {
-      data.qfrc_applied[i] = 0;
-    }
-
-    // Before-step callbacks
-    for (const cb of beforeStepCallbacks.current) {
-      cb({ model, data });
-    }
-
-    const numSubsteps = substepsRef.current;
-    if (!interpolateRef.current) {
-      // Step physics with substeps
-      if (stepsToRunRef.current > 0) {
-        for (let s = 0; s < stepsToRunRef.current; s++) {
-          mujocoRef.current.mj_step(model, data);
-        }
-        stepsToRunRef.current = 0;
-      } else {
-        const startSimTime = data.time;
-        const clampedDelta = Math.min(delta, 1 / 15); // cap to avoid spiral of death
-        const frameTime = clampedDelta * speedRef.current;
-        while (data.time - startSimTime < frameTime) {
-          for (let s = 0; s < numSubsteps; s++) {
-            mujocoRef.current.mj_step(model, data);
-          }
-        }
-      }
-    } else if (stepsToRunRef.current > 0) {
+    if (isWorkerOwned(model)) { interpolationStateRef.current.valid = false; return; }
+    const queued = stepsToRunRef.current > 0;
+    if (pausedRef.current && !queued) return;
+    const startTime = data.time;
+    const dt = model.opt.timestep;
+    if (!Number.isFinite(dt) || dt <= 0) return;
+    const substeps = Math.max(1, Math.floor(substepsRef.current));
+    const frameTime = Math.max(0, Math.min(delta, 1 / 15) * speedRef.current);
+    if (!queued && interpolateRef.current) physicsAccumulatorRef.current += frameTime;
+    const desired = queued ? stepsToRunRef.current : interpolateRef.current
+      ? Math.floor(physicsAccumulatorRef.current / (dt * substeps)) * substeps
+      : Math.ceil(frameTime / (dt * substeps)) * substeps;
+    for (let i = 0; i < model.nv; i++) data.qfrc_applied[i] = 0;
+    for (const cb of beforeStepCallbacks.current) cb({ model, data });
+    if (interpolateRef.current) {
       ensureInterpolationBuffers(model);
-      copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
-      for (let s = 0; s < stepsToRunRef.current; s++) {
-        mujocoRef.current.mj_step(model, data);
-      }
+      if (!interpolationStateRef.current.valid) copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
+    }
+    const measured = runStepBudget(desired, () => {
+      if (interpolateRef.current) copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
+      mujocoRef.current.mj_step(model, data);
+    }, physicsBudgetMs);
+    if (queued) stepsToRunRef.current -= measured.steps;
+    // Viewer overload slows simulation; it never accumulates an unbounded catch-up debt.
+    performanceRef.current = { ...measured, backlogSteps: Math.max(0, desired - measured.steps),
+      realTimeFactor: (data.time - startTime) / Math.max(delta, .000001) };
+    if (interpolateRef.current) {
       copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
-      interpolationStateRef.current.alpha = 1;
+      if (!queued) {
+        physicsAccumulatorRef.current -= measured.steps * dt;
+        if (measured.budgetExceeded) physicsAccumulatorRef.current %= dt * substeps;
+      } else physicsAccumulatorRef.current = 0;
+      interpolationStateRef.current.alpha = queued ? 1 : Math.min(1, physicsAccumulatorRef.current / dt);
       interpolationStateRef.current.valid = true;
-      stepsToRunRef.current = 0;
-    } else {
-      ensureInterpolationBuffers(model);
-      const clampedDelta = Math.min(delta, 1 / 15); // cap to avoid spiral of death
-      physicsAccumulatorRef.current += clampedDelta * speedRef.current;
-      const stepDt = Math.max((model.opt?.timestep ?? 0.002) * Math.max(1, numSubsteps), 1e-6);
-      let stepped = false;
-
-      while (physicsAccumulatorRef.current >= stepDt) {
-        copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
-        for (let s = 0; s < numSubsteps; s++) {
-          mujocoRef.current.mj_step(model, data);
-        }
-        copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
-        physicsAccumulatorRef.current -= stepDt;
-        stepped = true;
-      }
-
-      if (!interpolationStateRef.current.valid) {
-        copyBodyPose(data, interpolationStateRef.current.previousXpos, interpolationStateRef.current.previousXquat);
-        copyBodyPose(data, interpolationStateRef.current.currentXpos, interpolationStateRef.current.currentXquat);
-      }
-
-      interpolationStateRef.current.alpha = Math.min(Math.max(physicsAccumulatorRef.current / stepDt, 0), 1);
-      interpolationStateRef.current.valid = true;
-
-      if (!stepped) {
-        onStepRef.current?.({ time: data.time, model, data });
-        return;
-      }
     }
 
     // After-step callbacks
@@ -906,6 +896,7 @@ export function MujocoSimProvider({
   }, []);
 
   const step = useCallback((n = 1) => {
+    if (!Number.isSafeInteger(n) || n <= 0) throw new Error('Step count must be a positive safe integer');
     stepsToRunRef.current = n;
   }, []);
 
@@ -1384,6 +1375,7 @@ export function MujocoSimProvider({
     const data = mjDataRef.current;
     if (!model || !data) return null;
 
+    assertMainThreadOwnership(model);
     _rayPnt[0] = origin.x; _rayPnt[1] = origin.y; _rayPnt[2] = origin.z;
     const dir = direction.clone().normalize();
     _rayVec[0] = dir.x; _rayVec[1] = dir.y; _rayVec[2] = dir.z;
@@ -1462,6 +1454,7 @@ export function MujocoSimProvider({
   const loadSceneApi = useCallback(async (newConfig: SceneConfig): Promise<void> => {
     const gen = ++loadGenRef.current;
     try {
+      closeModelRuntime(mjModelRef.current);
       mjDataRef.current?.delete();
       mjModelRef.current?.delete();
       mjModelRef.current = null;
@@ -1640,6 +1633,7 @@ export function MujocoSimProvider({
           throw new Error('MuJoCo scene is not ready for camera sequence stepping.');
         }
 
+        let sliceStarted = performance.now();
         for (let stepIndex = 0; stepIndex < steps; stepIndex += 1) {
           for (let i = 0; i < model.nv; i += 1) {
             data.qfrc_applied[i] = 0;
@@ -1659,6 +1653,11 @@ export function MujocoSimProvider({
             cb({ model, data });
           }
           onStepRef.current?.({ time: data.time, model, data });
+          if (performance.now() - sliceStarted >= 8) {
+            await new Promise(resolve => setTimeout(resolve, 0));
+            throwIfCameraSequenceAborted(options.signal);
+            sliceStarted = performance.now();
+          }
           await options.onAfterStep?.({
             frameIndex,
             stepIndex,
@@ -1890,8 +1889,15 @@ export function MujocoSimProvider({
   }, []);
 
   // --- Assemble API ---
-  const api = useMemo<MujocoSimAPI>(
-    () => ({
+  const api: MujocoSimAPI = useMemo<MujocoSimAPI>(
+    () => guardRuntimeOwnership({
+      createRuntime: (options?: RuntimeOptions) => {
+        if (beforeStepCallbacks.current.size || afterStepCallbacks.current.size) {
+          return Promise.reject(new Error('Unmount physics callbacks/controllers before creating a worker runtime; use runtime.advance({controls}) for policy actions.'));
+        }
+        return attachSimulationRuntime(mujocoRef.current, apiRef.current, waitForDisplay, invalidate, options);
+      },
+      getPerformance: () => ({ ...performanceRef.current }),
       get status() { return status; },
       get config() { return configRef.current; },
       reset,
@@ -1918,7 +1924,7 @@ export function MujocoSimProvider({
       setExternalForce,
       applyGeneralizedForce,
       getSensorData,
-      getContacts,
+      getContacts: () => { const model = mjModelRef.current; return model && isWorkerOwned(model) ? runtimeContacts(model)! : getContacts(); },
       getBodies,
       getJoints,
       getGeoms,
@@ -1954,7 +1960,7 @@ export function MujocoSimProvider({
       setGeomSize,
       mjModelRef,
       mjDataRef,
-    }),
+    }, () => mjModelRef.current),
     [
       status, reset, setSpeed, togglePause, setPaused, step,
       getTime, getTimestep, applyKeyframe, saveState, restoreState,
@@ -1975,7 +1981,7 @@ export function MujocoSimProvider({
       setBodyMass, setGeomFriction, setGeomSize,
     ]
   );
-  const apiRef = useRef(api);
+  const apiRef = useRef<MujocoSimAPI>(api);
   apiRef.current = api;
 
   const contextValue = useMemo<MujocoSimContextValue>(
@@ -2011,3 +2017,19 @@ export function MujocoSimProvider({
     </MujocoSimContext.Provider>
   );
 }
+
+
+const runtimeMutators = new Set<PropertyKey>([
+  'reset', 'setSpeed', 'togglePause', 'setPaused', 'step', 'applyKeyframe', 'saveState', 'restoreState',
+  'setQpos', 'setQvel', 'setCtrl', 'applyForce', 'applyTorque', 'setExternalForce', 'applyGeneralizedForce',
+  'setGravity', 'setTimestep', 'setBodyMass', 'setGeomFriction', 'setGeomSize',
+  'loadScene', 'loadFromFiles', 'addBody', 'removeBody', 'recompile', 'recordCameraSequence',
+]);
+function guardRuntimeOwnership(api: MujocoSimAPI, model: () => MujocoModel | null): MujocoSimAPI {
+  for (const key of runtimeMutators) {
+    const record = api as unknown as Record<PropertyKey, (...args: unknown[]) => unknown>;
+    const method = record[key];
+    record[key] = (...args) => { assertMainThreadOwnership(model()); return method(...args); };
+  }
+  return api;
+}

package/src/core/sceneIdentity.ts

@@ -0,0 +1,15 @@
+import type { SceneConfig } from '../types';
+const fileIds = new WeakMap<object, number>();
+let nextFileId = 0;
+/** Model inputs define lifetime. Callback identity never recompiles physics. */
+export function sceneIdentity(config: SceneConfig): string {
+  return JSON.stringify([
+    config.src, config.sceneFile, config.environmentFiles ?? [], config.sceneObjects ?? [],
+    config.homeJoints ?? [], config.xmlPatches ?? [], (config.files ?? []).map(file => {
+      if (!fileIds.has(file)) fileIds.set(file, ++nextFileId);
+      return fileIds.get(file);
+    }),
+  ], (_key, value: unknown) => value && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)))
+    : value);
+}

package/src/core/stepBudget.ts

@@ -0,0 +1,18 @@
+export interface PhysicsPerformance {
+  steps: number;
+  physicsMs: number;
+  realTimeFactor: number;
+  backlogSteps: number;
+  budgetExceeded: boolean;
+}
+/** A single mj_step cannot be preempted; always finish it, then yield. */
+export function runStepBudget(requested: number, step: () => void, budgetMs = 8, now = () => performance.now()) {
+  if (!Number.isFinite(budgetMs) || budgetMs <= 0) throw new Error('physicsBudgetMs must be positive and finite');
+  const start = now();
+  let steps = 0;
+  while (steps < requested && steps < 100) {
+    step(); steps++;
+    if (now() - start >= budgetMs) break;
+  }
+  return { steps, physicsMs: now() - start, budgetExceeded: steps < requested };
+}

package/src/hooks/useCameraStream.ts

@@ -2,16 +2,9 @@
  * @license
  * SPDX-License-Identifier: Apache-2.0
  *
- * Stream a live MuJoCo camera into a DOM `<canvas>`. Each frame the scene is
- * rendered offscreen from the selected camera and blitted into the canvas, so
- * it composites normally in the DOM (works inside opaque panels) and does NOT
- * take over the render loop. Prefer this over `useCameraViewport` for camera
- * tiles embedded in HTML UI; use `useCameraViewport` for transparent overlays
- * on a full-bleed canvas.
- *
- * Uses the async capture path so Gaussian-splat environments render through
- * their dedicated capture renderer — streaming a splat scene at full rate does
- * not disturb the main view's splat sort.
+ * Readback stream for DOM compositing/encoding. For interactive camera previews,
+ * use CameraView/useCameraViewport: they render on the GPU with no readback.
+ * This path defaults to 10 FPS and permits only one capture in flight.
  */
 
 import { useEffect, useRef } from 'react';
@@ -23,12 +16,12 @@ import type { CameraFrameCaptureOptions } from '../types';
 
 export interface CameraStreamOptions extends CameraFrameCaptureOptions {
   /**
-   * Optional cap on updates per second. Omit to stream as fast as captures
-   * complete (one capture is in flight at a time regardless).
+   * Readback rate, default 10 FPS. Must be positive and finite.
    */
   fps?: number;
   /** Pause updates without unmounting. */
   paused?: boolean;
+  onError?: (error: Error) => void;
 }
 
 function streamSignature(options: CameraStreamOptions): string {
@@ -77,10 +70,10 @@ export function useCameraStream(
     const opts = optionsRef.current;
     if (opts.paused) return;
 
-    if (opts.fps && opts.fps > 0) {
-      elapsedRef.current += delta;
-      if (elapsedRef.current < 1 / opts.fps) return;
-    }
+    const fps = opts.fps ?? 10;
+    if (!Number.isFinite(fps) || fps <= 0) throw new Error('Camera stream fps must be positive and finite');
+    elapsedRef.current += delta;
+    if (elapsedRef.current < 1 / fps) return;
     // One capture in flight at a time — naturally rate-limits to capture speed.
     if (inFlightRef.current) return;
     elapsedRef.current = 0;
@@ -107,7 +100,11 @@ export function useCameraStream(
         }
         ctx.drawImage(frame.canvas, 0, 0);
       })
-      .catch(() => {})
+      .catch(error => {
+        const failure = error instanceof Error ? error : new Error(String(error));
+        if (optionsRef.current.onError) optionsRef.current.onError(failure);
+        else console.error('Camera stream capture failed', failure);
+      })
       .finally(() => {
         inFlightRef.current = false;
       });

package/src/hooks/usePolicy.ts

@@ -5,7 +5,7 @@
  * usePolicy — policy decimation loop hook (spec 10.1)
  */
 
-import { useCallback, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { useBeforePhysicsStep } from '../core/MujocoSimProvider';
 import type { PolicyAPI, PolicyConfig, PolicyInferenceOutput, PolicyVector } from '../types';
 
@@ -39,8 +39,11 @@ function enqueuePolicyActions(
   queue: PendingPolicyAction[],
   actions: PolicyVector[],
   observation: PolicyVector,
-  strategy: PolicyConfig['queueStrategy']
+  strategy: PolicyConfig['queueStrategy'],
+  limit = 256
 ) {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new Error('maxQueuedActions must be a positive safe integer');
+  if ((strategy === 'replace' ? 0 : queue.length) + actions.length > limit) throw new Error(`Policy action queue exceeds maxQueuedActions (${limit})`);
   if (strategy === 'replace') {
     queue.splice(0, queue.length);
   }
@@ -73,7 +76,6 @@ export function usePolicy(config: PolicyConfig): PolicyAPI {
   const clearQueue = useCallback(() => {
     epochRef.current += 1;
     actionQueueRef.current.splice(0, actionQueueRef.current.length);
-    inFlightRef.current = false;
     lastErrorRef.current = null;
   }, []);
 
@@ -84,6 +86,11 @@ export function usePolicy(config: PolicyConfig): PolicyAPI {
     lastActionRef.current = null;
   }, [clearQueue]);
 
+  useEffect(() => {
+    isRunningRef.current = configRef.current.enabled ?? true;
+    return () => { epochRef.current++; isRunningRef.current = false; };
+  }, []);
+
   useBeforePhysicsStep(({ model, data }) => {
     if (!isRunningRef.current) return;
 
@@ -126,7 +133,8 @@ export function usePolicy(config: PolicyConfig): PolicyAPI {
               actionQueueRef.current,
               toPolicyActions(output),
               observation,
-              cfg.queueStrategy ?? 'append'
+              cfg.queueStrategy ?? 'append',
+              cfg.maxQueuedActions
             );
             lastErrorRef.current = null;
           })
@@ -136,7 +144,6 @@ export function usePolicy(config: PolicyConfig): PolicyAPI {
             cfg.onError?.(error);
           })
           .finally(() => {
-            if (epoch !== epochRef.current) return;
             inFlightRef.current = false;
           });
       } else {
@@ -146,7 +153,8 @@ export function usePolicy(config: PolicyConfig): PolicyAPI {
             actionQueueRef.current,
             actions,
             observation,
-            cfg.queueStrategy ?? 'append'
+            cfg.queueStrategy ?? 'append',
+              cfg.maxQueuedActions
           );
         } else {
           const [action, ...queuedActions] = actions;
@@ -155,7 +163,8 @@ export function usePolicy(config: PolicyConfig): PolicyAPI {
             actionQueueRef.current,
             queuedActions,
             observation,
-            cfg.queueStrategy ?? 'append'
+            cfg.queueStrategy ?? 'append',
+              cfg.maxQueuedActions
           );
           // Apply action. If `infer` is omitted, this preserves the legacy inline-controller path.
           cfg.onAction({ action, observation, model, data });

package/src/index.ts

@@ -470,3 +470,6 @@ export {
 // Re-export MuJoCo types for convenience
 export type { MujocoModule, MujocoModel, MujocoData, MujocoContact, MujocoContactArray } from './types';
 export { getContact } from './types';
+
+export type { SimulationRuntime, RuntimeOptions, RuntimeState, RuntimeSnapshot, RuntimeMetrics, AdvanceOptions, WorkerPort } from './runtime/types';
+export type { PhysicsPerformance } from './core/stepBudget';

package/src/physics.worker.ts

@@ -0,0 +1,13 @@
+import loadMujoco from '@mujoco/mujoco';
+import wasmUrl from '@mujoco/mujoco/mujoco.wasm?url';
+import { createRuntimeHandler, type Request, type Response } from './runtime/protocol';
+const scope = self as unknown as { onmessage: (event: MessageEvent<Request>) => void; postMessage: (response: Response, transfer: Transferable[]) => void };
+const handle = createRuntimeHandler(
+  () => loadMujoco({ locateFile: (file: string) => file.endsWith('.wasm') ? wasmUrl : file }),
+  response => {
+    const transfer: Transferable[] = response.display ? Object.values(response.display.fields).map(value => value.buffer as ArrayBuffer) : [];
+    if (response.display?.integration) transfer.push(response.display.integration.values.buffer as ArrayBuffer);
+    scope.postMessage(response, transfer);
+  },
+);
+scope.onmessage = event => { void handle(event.data); };

package/src/rendering/cameraFrameCapture.ts

@@ -354,9 +354,10 @@ function readRenderTargetToCanvas(
   width: number,
   height: number,
   outputColorSpace: string,
-  flipX = false
+  flipX = false,
+  readback = true
 ) {
-  renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
+  if (readback) renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
 
   const rowBytes = width * 4;
   const encodeSrgb = outputColorSpace === THREE.SRGBColorSpace;
@@ -646,6 +647,16 @@ export function createCameraFrameCaptureSession(
 
   const pixels = new Uint8Array(width * height * 4);
   const imageData = drawContext.createImageData(width, height);
+  let inFlight = false, disposed = false;
+  function assertAvailable() {
+    if (disposed) throw new Error('Camera capture session is disposed');
+    if (inFlight) throw new Error('Camera capture session is busy; await the current capture');
+  }
+  function releaseResources() {
+    target.dispose();
+    if (isolatedRenderer && !isolatedRenderer.cached) isolatedRenderer.renderer.dispose();
+  }
+
 
   function resolveCaptureOptions(nextOptions: CameraFrameCaptureOptions = {}) {
     const captureOptions = { ...options, ...nextOptions };
@@ -743,10 +754,12 @@ export function createCameraFrameCaptureSession(
   }
 
   function capture(nextOptions: CameraFrameCaptureOptions = {}) {
+    assertAvailable();
     return renderPreparedCapture(resolveCaptureOptions(nextOptions));
   }
 
   function capturePixels(nextOptions: CameraFrameCaptureOptions = {}): CameraFramePixelsResult {
+    assertAvailable();
     const captureOptions = resolveCaptureOptions(nextOptions);
     renderCaptureToTarget(captureOptions, () => {
       sessionRenderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
@@ -777,6 +790,13 @@ export function createCameraFrameCaptureSession(
   }
 
   async function captureAsync(nextOptions: CameraFrameCaptureOptions = {}) {
+    assertAvailable();
+    inFlight = true;
+    try { return await captureAsyncInternal(nextOptions); }
+    finally { inFlight = false; if (disposed) releaseResources(); }
+  }
+
+  async function captureAsyncInternal(nextOptions: CameraFrameCaptureOptions = {}) {
     const captureOptions = resolveCaptureOptions(nextOptions);
     runCapturePreRenderHooks(scene);
     scene.updateMatrixWorld(true);
@@ -841,7 +861,14 @@ export function createCameraFrameCaptureSession(
         restoreRendererState(sessionRenderer, previousState);
       }
     }
-    return renderPreparedCapture(captureOptions);
+    let readback: Promise<unknown> | undefined;
+    renderCaptureToTarget(captureOptions, () => {
+      readback = sessionRenderer.readRenderTargetPixelsAsync(target, 0, 0, width, height, pixels);
+    });
+    await readback;
+    readRenderTargetToCanvas(sessionRenderer, target, canvas, drawContext, pixels, imageData,
+      width, height, sessionRenderer.outputColorSpace, captureOptions.flipX ?? false, false);
+    return { canvas, camera, width, height, source: getCameraFrameCaptureSource(captureOptions) };
   }
 
   return {
@@ -891,10 +918,9 @@ export function createCameraFrameCaptureSession(
       return { ...result, blob, type };
     },
     dispose() {
-      target.dispose();
-      if (isolatedRenderer && !isolatedRenderer.cached) {
-        isolatedRenderer.renderer.dispose();
-      }
+      if (disposed) return;
+      disposed = true;
+      if (!inFlight) releaseResources();
     },
   };
 }