mujoco-react 9.0.0 → 9.2.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-izZlUweI.js';
+import { n as SplatEnvironmentProps } from './types-S8ggQY2n.js';
 import 'react';
 import '@react-three/fiber';
 import 'three';

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

@@ -837,7 +837,13 @@ interface MujocoSimAPI {
     addBody(body: SceneObject): Promise<void>;
     removeBody(name: Bodies): Promise<void>;
     recompile(patches?: XmlPatch[]): Promise<void>;
+    getCanvas(): HTMLCanvasElement | null;
     getCanvasSnapshot(width?: number, height?: number, mimeType?: string): string;
+    captureFrame(options?: MujocoFrameCaptureOptions): Promise<FrameCaptureResult>;
+    captureFrameBlob(options?: MujocoFrameCaptureOptions): Promise<FrameCaptureBlobResult>;
+    captureCameraFrame(options?: CameraFrameCaptureOptions): Promise<CameraFrameCaptureResult>;
+    captureCameraFrameBlob(options?: CameraFrameCaptureOptions): Promise<CameraFrameCaptureBlobResult>;
+    recordCameraSequence(options: CameraFrameSequenceOptions): Promise<CameraFrameSequenceResult>;
     project2DTo3D(x: number, y: number, cameraPos: THREE.Vector3, lookAt: THREE.Vector3): {
         point: THREE.Vector3;
         bodyId: number;
@@ -849,6 +855,102 @@ interface MujocoSimAPI {
     readonly mjModelRef: React__default.RefObject<MujocoModel | null>;
     readonly mjDataRef: React__default.RefObject<MujocoData | null>;
 }
+type FrameCaptureStatus = 'idle' | 'capturing' | 'captured' | 'error';
+type FrameCaptureTarget = HTMLCanvasElement | HTMLElement | null | undefined;
+type FrameCaptureTargetRef = React__default.RefObject<HTMLCanvasElement | HTMLElement | null>;
+interface FrameCaptureOptions {
+    target?: FrameCaptureTarget | FrameCaptureTargetRef;
+    type?: string;
+    quality?: number;
+    waitForAnimationFrame?: boolean;
+}
+type MujocoFrameCaptureOptions = Omit<FrameCaptureOptions, 'target'>;
+interface FrameCaptureResult {
+    canvas: HTMLCanvasElement;
+    dataUrl: string;
+    type: string;
+}
+interface FrameCaptureBlobResult {
+    canvas: HTMLCanvasElement;
+    blob: Blob;
+    type: string;
+}
+interface FrameCaptureAPI {
+    status: FrameCaptureStatus;
+    error: Error | null;
+    isCapturing: boolean;
+    capture: (options?: FrameCaptureOptions) => Promise<FrameCaptureResult>;
+    captureBlob: (options?: FrameCaptureOptions) => Promise<FrameCaptureBlobResult>;
+    reset: () => void;
+}
+type CameraFrameCaptureVector3 = THREE.Vector3 | readonly [number, number, number];
+type CameraFrameCaptureQuaternion = THREE.Quaternion | readonly [number, number, number, number];
+interface CameraFrameCaptureOptions {
+    camera?: THREE.Camera;
+    position?: CameraFrameCaptureVector3;
+    lookAt?: CameraFrameCaptureVector3;
+    quaternion?: CameraFrameCaptureQuaternion;
+    up?: CameraFrameCaptureVector3;
+    width?: number;
+    height?: number;
+    type?: string;
+    quality?: number;
+    fov?: number;
+    near?: number;
+    far?: number;
+}
+interface CameraFrameCaptureResult {
+    canvas: HTMLCanvasElement;
+    camera: THREE.Camera;
+    dataUrl: string;
+    type: string;
+    width: number;
+    height: number;
+}
+interface CameraFrameCaptureBlobResult {
+    canvas: HTMLCanvasElement;
+    camera: THREE.Camera;
+    blob: Blob;
+    type: string;
+    width: number;
+    height: number;
+}
+interface CameraFrameCaptureAPI {
+    status: FrameCaptureStatus;
+    error: Error | null;
+    isCapturing: boolean;
+    capture: (options?: CameraFrameCaptureOptions) => Promise<CameraFrameCaptureResult>;
+    captureBlob: (options?: CameraFrameCaptureOptions) => Promise<CameraFrameCaptureBlobResult>;
+    reset: () => void;
+}
+interface CameraFrameSequenceCamera extends CameraFrameCaptureOptions {
+    key: string;
+}
+interface CameraFrameSequenceFrame {
+    frameIndex: number;
+    time: number;
+    cameras: Record<string, CameraFrameCaptureResult>;
+}
+interface CameraFrameSequenceOptions {
+    cameras: readonly CameraFrameSequenceCamera[];
+    frames: number;
+    stepsPerFrame?: number;
+    reset?: boolean;
+    captureInitialFrame?: boolean;
+    onFrame?: (frame: CameraFrameSequenceFrame) => void | Promise<void>;
+}
+interface CameraFrameSequenceResult {
+    frames: CameraFrameSequenceFrame[];
+    cameraKeys: string[];
+    frameCount: number;
+}
+interface CameraFrameSequenceRecorderAPI {
+    status: FrameCaptureStatus;
+    error: Error | null;
+    isRecording: boolean;
+    record: (options: CameraFrameSequenceOptions) => Promise<CameraFrameSequenceResult>;
+    reset: () => void;
+}
 type MujocoCanvasProps = Omit<CanvasProps, 'onError'> & {
     config: SceneConfig;
     /** R3F content rendered while the MuJoCo WASM module is still loading. */
@@ -907,4 +1009,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 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 };
+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 };

package/package.json

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

package/src/core/MujocoSimProvider.tsx

@@ -20,6 +20,10 @@ import {
   ActuatedJointInfo,
   ActuatorInfo,
   BodyInfo,
+  CameraFrameCaptureResult,
+  CameraFrameSequenceFrame,
+  CameraFrameSequenceOptions,
+  CameraFrameSequenceResult,
   ControlGroupInfo,
   ControlGroupSelector,
   ContactInfo,
@@ -41,6 +45,14 @@ import {
   StepCallbackInput,
   XmlPatch,
 } from '../types';
+import {
+  captureFrame as captureCanvasFrame,
+  captureFrameBlob as captureCanvasFrameBlob,
+} from '../hooks/useFrameCapture';
+import {
+  captureCameraFrame,
+  captureCameraFrameBlob,
+} from '../rendering/cameraFrameCapture';
 import {
   loadScene,
   createSceneConfigFromFiles,
@@ -106,6 +118,12 @@ const _rayGeomId = new Int32Array(1);
 const _projRaycaster = new THREE.Raycaster();
 const _projNdc = new THREE.Vector2();
 
+function waitForNextAnimationFrame() {
+  return new Promise<void>((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
+}
+
 // ---- Internal context types ----
 
 export interface MujocoSimContextValue {
@@ -252,7 +270,7 @@ export function MujocoSimProvider({
   interpolate,
   children,
 }: MujocoSimProviderProps) {
-  const { gl, camera } = useThree();
+  const { gl, camera, scene } = useThree();
   const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
 
   // --- Refs ---
@@ -544,6 +562,30 @@ export function MujocoSimProvider({
     stepsToRunRef.current = n;
   }, []);
 
+  const stepImmediately = useCallback((steps = 1) => {
+    const model = mjModelRef.current;
+    const data = mjDataRef.current;
+    if (!model || !data) return false;
+
+    for (let stepIndex = 0; stepIndex < steps; stepIndex += 1) {
+      for (let i = 0; i < model.nv; i += 1) {
+        data.qfrc_applied[i] = 0;
+      }
+      for (const cb of beforeStepCallbacks.current) {
+        cb({ model, data });
+      }
+      mujoco.mj_step(model, data);
+      for (const cb of afterStepCallbacks.current) {
+        cb({ model, data });
+      }
+      onStepRef.current?.({ time: data.time, model, data });
+    }
+
+    physicsAccumulatorRef.current = 0;
+    interpolationStateRef.current.valid = false;
+    return true;
+  }, [mujoco]);
+
   const getTime = useCallback((): number => {
     return mjDataRef.current?.time ?? 0;
   }, []);
@@ -1019,6 +1061,99 @@ export function MujocoSimProvider({
     [gl]
   );
 
+  const getCanvas = useCallback((): HTMLCanvasElement | null => {
+    return gl.domElement ?? null;
+  }, [gl]);
+
+  const captureFrameApi = useCallback(
+    (options = {}) => {
+      return captureCanvasFrame({ ...options, target: gl.domElement });
+    },
+    [gl]
+  );
+
+  const captureFrameBlobApi = useCallback(
+    (options = {}) => {
+      return captureCanvasFrameBlob({ ...options, target: gl.domElement });
+    },
+    [gl]
+  );
+
+  const captureCameraFrameApi = useCallback(
+    (options = {}) => {
+      return captureCameraFrame(gl, scene, camera, options);
+    },
+    [camera, gl, scene]
+  );
+
+  const captureCameraFrameBlobApi = useCallback(
+    (options = {}) => {
+      return captureCameraFrameBlob(gl, scene, camera, options);
+    },
+    [camera, gl, scene]
+  );
+
+  const recordCameraSequenceApi = useCallback(
+    async (
+      options: CameraFrameSequenceOptions
+    ): Promise<CameraFrameSequenceResult> => {
+      const frameCount = Math.max(0, Math.floor(options.frames));
+      const stepsPerFrame = Math.max(1, Math.floor(options.stepsPerFrame ?? 1));
+      const cameras = options.cameras;
+      const frames: CameraFrameSequenceFrame[] = [];
+      const wasPaused = pausedRef.current;
+
+      if (frameCount === 0 || cameras.length === 0) {
+        return {
+          frames,
+          cameraKeys: cameras.map((sequenceCamera) => sequenceCamera.key),
+          frameCount: 0,
+        };
+      }
+
+      try {
+        pausedRef.current = true;
+        stepsToRunRef.current = 0;
+        if (options.reset) reset();
+
+        for (let frameIndex = 0; frameIndex < frameCount; frameIndex += 1) {
+          if (frameIndex > 0 || options.captureInitialFrame === false) {
+            stepImmediately(stepsPerFrame);
+          }
+          await waitForNextAnimationFrame();
+
+          const cameraFrames: Record<string, CameraFrameCaptureResult> = {};
+          for (const sequenceCamera of cameras) {
+            const { key, ...captureOptions } = sequenceCamera;
+            cameraFrames[key] = await captureCameraFrame(
+              gl,
+              scene,
+              camera,
+              captureOptions
+            );
+          }
+
+          const frame = {
+            frameIndex,
+            time: getTime(),
+            cameras: cameraFrames,
+          };
+          frames.push(frame);
+          await options.onFrame?.(frame);
+        }
+      } finally {
+        pausedRef.current = wasPaused;
+      }
+
+      return {
+        frames,
+        cameraKeys: cameras.map((sequenceCamera) => sequenceCamera.key),
+        frameCount: frames.length,
+      };
+    },
+    [camera, getTime, gl, reset, scene, stepImmediately]
+  );
+
   const project2DTo3D = useCallback(
     (x: number, y: number, cameraPos: THREE.Vector3, lookAt: THREE.Vector3): { point: THREE.Vector3; bodyId: number; geomId: number } | null => {
       const virtCam = (camera as THREE.PerspectiveCamera).clone();
@@ -1128,7 +1263,13 @@ export function MujocoSimProvider({
       addBody: addBodyApi,
       removeBody: removeBodyApi,
       recompile: recompileApi,
+      getCanvas,
       getCanvasSnapshot,
+      captureFrame: captureFrameApi,
+      captureFrameBlob: captureFrameBlobApi,
+      captureCameraFrame: captureCameraFrameApi,
+      captureCameraFrameBlob: captureCameraFrameBlobApi,
+      recordCameraSequence: recordCameraSequenceApi,
       project2DTo3D,
       setBodyMass,
       setGeomFriction,
@@ -1146,7 +1287,10 @@ export function MujocoSimProvider({
       getActuatorsApi, getSensors, getModelOption, setGravity, setTimestepApi,
       raycast, getKeyframeNames, getKeyframeCount, loadSceneApi,
       loadFromFilesApi, addBodyApi, removeBodyApi, recompileApi,
-      getCanvasSnapshot, project2DTo3D,
+      getCanvas, getCanvasSnapshot, captureFrameApi, captureFrameBlobApi,
+      captureCameraFrameApi, captureCameraFrameBlobApi,
+      recordCameraSequenceApi,
+      project2DTo3D,
       setBodyMass, setGeomFriction, setGeomSize,
     ]
   );

package/src/core/createController.tsx

@@ -43,8 +43,10 @@ export type ControllerComponent<TConfig> = React.FC<{
  * const MyController = createController<{ speed: number }>(
  *   { name: 'my-controller', defaultConfig: { speed: 1.0 } },
  *   function MyControllerImpl({ config }) {
+ *     const wheel = useCtrl(RobotActuators.mobile.leftWheel);
+ *
  *     useBeforePhysicsStep(({ data }) => {
- *       data.ctrl[0] = config.speed;
+ *       wheel.write(config.speed);
  *     });
  *     return null;
  *   },
@@ -100,9 +102,11 @@ export function createController<TConfig>(
  *   { name: 'useMyController', defaultConfig: { gain: 1.0 } },
  *   function useMyControllerImpl(config) {
  *     // config is MyConfig | null — hooks must be called unconditionally
+ *     const joint = useCtrl(config?.actuator ?? RobotActuators.franka.actuator1);
+ *
  *     useBeforePhysicsStep(({ data }) => {
  *       if (!config) return;
- *       data.ctrl[0] = config.gain * Math.sin(data.time);
+ *       joint.write(config.gain * Math.sin(data.time));
  *     });
  *     if (!config) return null;
  *     return { /* value *\/ };

package/src/hooks/useCameraFrameCapture.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * React state wrapper around MuJoCo/R3F offscreen camera-frame capture.
+ */
+
+import { useCallback, useState } from 'react';
+import { useMujoco } from '../core/MujocoSimProvider';
+import type {
+  CameraFrameCaptureAPI,
+  CameraFrameCaptureOptions,
+  FrameCaptureStatus,
+} from '../types';
+
+export function useCameraFrameCapture(
+  defaultOptions: CameraFrameCaptureOptions = {}
+): CameraFrameCaptureAPI {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState<FrameCaptureStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+
+  const capture = useCallback(
+    async (options: CameraFrameCaptureOptions = {}) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for camera frame capture.');
+      }
+
+      setStatus('capturing');
+      setError(null);
+
+      try {
+        const result = await mujoco.api.captureCameraFrame({
+          ...defaultOptions,
+          ...options,
+        });
+        setStatus('captured');
+        return result;
+      } catch (nextError) {
+        const error =
+          nextError instanceof Error
+            ? nextError
+            : new Error('Unable to capture the requested camera frame.');
+        setError(error);
+        setStatus('error');
+        throw error;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+
+  const captureBlob = useCallback(
+    async (options: CameraFrameCaptureOptions = {}) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for camera frame capture.');
+      }
+
+      setStatus('capturing');
+      setError(null);
+
+      try {
+        const result = await mujoco.api.captureCameraFrameBlob({
+          ...defaultOptions,
+          ...options,
+        });
+        setStatus('captured');
+        return result;
+      } catch (nextError) {
+        const error =
+          nextError instanceof Error
+            ? nextError
+            : new Error('Unable to capture the requested camera frame.');
+        setError(error);
+        setStatus('error');
+        throw error;
+      }
+    },
+    [defaultOptions, mujoco.api]
+  );
+
+  return {
+    status,
+    error,
+    isCapturing: status === 'capturing',
+    capture,
+    captureBlob,
+    reset,
+  };
+}

package/src/hooks/useCameraSequenceRecorder.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * React state wrapper around fixed-camera simulation sequence recording.
+ */
+
+import { useCallback, useState } from 'react';
+import { useMujoco } from '../core/MujocoSimProvider';
+import type {
+  CameraFrameSequenceOptions,
+  CameraFrameSequenceRecorderAPI,
+  FrameCaptureStatus,
+} from '../types';
+
+export function useCameraSequenceRecorder(): CameraFrameSequenceRecorderAPI {
+  const mujoco = useMujoco();
+  const [status, setStatus] = useState<FrameCaptureStatus>('idle');
+  const [error, setError] = useState<Error | null>(null);
+
+  const reset = useCallback(() => {
+    setStatus('idle');
+    setError(null);
+  }, []);
+
+  const record = useCallback(
+    async (options: CameraFrameSequenceOptions) => {
+      if (!mujoco.api) {
+        throw new Error('MuJoCo scene is not ready for camera sequence recording.');
+      }
+
+      setStatus('capturing');
+      setError(null);
+
+      try {
+        const result = await mujoco.api.recordCameraSequence(options);
+        setStatus('captured');
+        return result;
+      } catch (nextError) {
+        const error =
+          nextError instanceof Error
+            ? nextError
+            : new Error('Unable to record the requested camera sequence.');
+        setError(error);
+        setStatus('error');
+        throw error;
+      }
+    },
+    [mujoco.api]
+  );
+
+  return {
+    status,
+    error,
+    isRecording: status === 'capturing',
+    record,
+    reset,
+  };
+}

package/src/hooks/useFrameCapture.ts

@@ -6,48 +6,14 @@
  */
 
 import { useCallback, useState } from 'react';
-import type React from 'react';
-
-export type FrameCaptureStatus = 'idle' | 'capturing' | 'captured' | 'error';
-
-export type FrameCaptureTarget =
-  | HTMLCanvasElement
-  | HTMLElement
-  | null
-  | undefined;
-
-export type FrameCaptureTargetRef =
-  React.RefObject<HTMLCanvasElement | HTMLElement | null>;
-
-export interface FrameCaptureOptions {
-  target?: FrameCaptureTarget | FrameCaptureTargetRef;
-  type?: string;
-  quality?: number;
-  waitForAnimationFrame?: boolean;
-}
-
-export interface FrameCaptureResult {
-  canvas: HTMLCanvasElement;
-  dataUrl: string;
-  type: string;
-}
-
-export interface FrameCaptureBlobResult {
-  canvas: HTMLCanvasElement;
-  blob: Blob;
-  type: string;
-}
-
-export interface FrameCaptureAPI {
-  status: FrameCaptureStatus;
-  error: Error | null;
-  isCapturing: boolean;
-  capture: (options?: FrameCaptureOptions) => Promise<FrameCaptureResult>;
-  captureBlob: (
-    options?: FrameCaptureOptions
-  ) => Promise<FrameCaptureBlobResult>;
-  reset: () => void;
-}
+import type {
+  FrameCaptureAPI,
+  FrameCaptureBlobResult,
+  FrameCaptureOptions,
+  FrameCaptureResult,
+  FrameCaptureStatus,
+  FrameCaptureTargetRef,
+} from '../types';
 
 function isTargetRef(
   target: FrameCaptureOptions['target']

package/src/index.ts

@@ -82,15 +82,13 @@ export {
   captureFrameBlob,
   useFrameCapture,
 } from './hooks/useFrameCapture';
-export type {
-  FrameCaptureAPI,
-  FrameCaptureBlobResult,
-  FrameCaptureOptions,
-  FrameCaptureResult,
-  FrameCaptureStatus,
-  FrameCaptureTarget,
-  FrameCaptureTargetRef,
-} from './hooks/useFrameCapture';
+export { useCameraFrameCapture } from './hooks/useCameraFrameCapture';
+export { useCameraSequenceRecorder } from './hooks/useCameraSequenceRecorder';
+export {
+  captureCameraFrame,
+  captureCameraFrameBlob,
+  renderCameraFrameToCanvas,
+} from './rendering/cameraFrameCapture';
 export { useCtrlNoise } from './hooks/useCtrlNoise';
 export { useBodyMeshes } from './hooks/useBodyMeshes';
 export { useSelectionHighlight } from './hooks/useSelectionHighlight';
@@ -189,9 +187,28 @@ export type {
   ContactListenerProps,
   // API
   MujocoSimAPI,
+  MujocoFrameCaptureOptions,
+  CameraFrameCaptureAPI,
+  CameraFrameCaptureBlobResult,
+  CameraFrameCaptureOptions,
+  CameraFrameCaptureQuaternion,
+  CameraFrameCaptureResult,
+  CameraFrameCaptureVector3,
+  CameraFrameSequenceCamera,
+  CameraFrameSequenceFrame,
+  CameraFrameSequenceOptions,
+  CameraFrameSequenceRecorderAPI,
+  CameraFrameSequenceResult,
   MujocoCanvasProps,
   MujocoContextValue,
   // Hook return types
+  FrameCaptureAPI,
+  FrameCaptureBlobResult,
+  FrameCaptureOptions,
+  FrameCaptureResult,
+  FrameCaptureStatus,
+  FrameCaptureTarget,
+  FrameCaptureTargetRef,
   SitePositionResult,
   SensorResult,
   CtrlHandle,