mujoco-react 0.1.0

package/src/components/FlexRenderer.tsx

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * FlexRenderer — render deformable flex bodies (spec 6.4)
+ */
+
+import { useEffect, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+
+/**
+ * Renders MuJoCo flex (deformable) bodies as dynamic meshes.
+ * Vertices are updated every frame from flexvert_xpos.
+ */
+export function FlexRenderer() {
+  const { mjModelRef, mjDataRef, status } = useMujocoSim();
+  const groupRef = useRef<THREE.Group>(null);
+  const meshesRef = useRef<THREE.Mesh[]>([]);
+
+  // Build flex meshes once when model is ready
+  useEffect(() => {
+    const model = mjModelRef.current;
+    const group = groupRef.current;
+    if (!model || !group || status !== 'ready') return;
+
+    const nflex = model.nflex ?? 0;
+    if (nflex === 0) return;
+
+    for (let f = 0; f < nflex; f++) {
+      const vertAdr = model.flex_vertadr[f];
+      const vertNum = model.flex_vertnum[f];
+
+      if (vertNum === 0) continue;
+
+      const geometry = new THREE.BufferGeometry();
+      const positions = new Float32Array(vertNum * 3);
+      geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+
+      // Note: flex_faceadr/flex_facenum/flex_face are NOT available in mujoco-js WASM.
+      // Without face data we render as a point cloud. If future WASM versions expose
+      // face arrays, index-based triangle rendering can be added here.
+
+      geometry.computeVertexNormals();
+
+      let color = new THREE.Color(0.5, 0.5, 0.5);
+      if (model.flex_rgba) {
+        color = new THREE.Color(
+          model.flex_rgba[4 * f],
+          model.flex_rgba[4 * f + 1],
+          model.flex_rgba[4 * f + 2],
+        );
+      }
+
+      const material = new THREE.MeshStandardMaterial({
+        color,
+        roughness: 0.7,
+        side: THREE.DoubleSide,
+      });
+
+      const mesh = new THREE.Mesh(geometry, material);
+      mesh.userData.flexId = f;
+      mesh.userData.vertAdr = vertAdr;
+      mesh.userData.vertNum = vertNum;
+      group.add(mesh);
+      meshesRef.current.push(mesh);
+    }
+
+    return () => {
+      for (const mesh of meshesRef.current) {
+        group.remove(mesh);
+        mesh.geometry.dispose();
+        (mesh.material as THREE.Material).dispose();
+      }
+      meshesRef.current = [];
+    };
+  }, [status, mjModelRef]);
+
+  // Update vertex positions every frame
+  useFrame(() => {
+    const data = mjDataRef.current;
+    if (!data || !data.flexvert_xpos) return;
+
+    for (const mesh of meshesRef.current) {
+      const vertAdr = mesh.userData.vertAdr;
+      const vertNum = mesh.userData.vertNum;
+      const posAttr = mesh.geometry.getAttribute('position') as THREE.BufferAttribute;
+      if (!posAttr) continue;
+
+      for (let v = 0; v < vertNum; v++) {
+        const srcIdx = (vertAdr + v) * 3;
+        posAttr.setXYZ(v, data.flexvert_xpos[srcIdx], data.flexvert_xpos[srcIdx + 1], data.flexvert_xpos[srcIdx + 2]);
+      }
+      posAttr.needsUpdate = true;
+      mesh.geometry.computeVertexNormals();
+    }
+  });
+
+  if (status !== 'ready') return null;
+  return <group ref={groupRef} />;
+}

package/src/components/IkGizmo.tsx

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { PivotControls } from '@react-three/drei';
+import { useFrame, useThree } from '@react-three/fiber';
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+import { findSiteByName } from '../core/SceneLoader';
+import type { IkGizmoProps } from '../types';
+
+// Preallocated temps to avoid GC pressure in useFrame
+const _mat4 = new THREE.Matrix4();
+const _pos = new THREE.Vector3();
+const _quat = new THREE.Quaternion();
+const _scale = new THREE.Vector3(1, 1, 1);
+
+/**
+ * IkGizmo — drei PivotControls that tracks a MuJoCo site.
+ *
+ * Props:
+ * - `siteName` — MuJoCo site to track. Defaults to `SceneConfig.tcpSiteName`.
+ * - `scale` — Gizmo handle scale. Default: 0.18.
+ * - `onDrag` — Custom drag callback `(pos, quat) => void`.
+ *   When omitted, dragging enables IK and writes to the provider's IK target.
+ *   When provided, the consumer handles what happens during drag.
+ *
+ * Multiple gizmos can be rendered — each tracks its own site.
+ * Zero gizmos is fine — programmatic IK control works via the provider API.
+ *
+ * Uses a tiny invisible mesh as child instead of axesHelper — PivotControls
+ * computes an anchor offset from children's bounding box, and axesHelper's
+ * (0→0.15) bounds would shift the handles away from the TCP origin.
+ */
+export function IkGizmo({ siteName, scale = 0.18, onDrag }: IkGizmoProps) {
+  const {
+    ikTargetRef, mjModelRef, mjDataRef, siteIdRef,
+    api, ikEnabledRef, status,
+  } = useMujocoSim();
+
+  const wrapperRef = useRef<THREE.Group>(null);
+  const pivotRef = useRef<THREE.Group>(null);
+  const draggingRef = useRef(false);
+  const localSiteIdRef = useRef(-1);
+  const { controls } = useThree();
+
+  // Resolve the site ID from siteName (or fall back to provider's tcpSiteName)
+  useEffect(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== 'ready') {
+      localSiteIdRef.current = -1;
+      return;
+    }
+    if (siteName) {
+      localSiteIdRef.current = findSiteByName(model, siteName);
+    } else {
+      // Default: use the provider's siteIdRef (from SceneConfig.tcpSiteName)
+      localSiteIdRef.current = siteIdRef.current;
+    }
+  }, [siteName, status, mjModelRef, siteIdRef]);
+
+  // Every frame: sync the visual wrapper to the tracked site (when not dragging)
+  useFrame(() => {
+    const data = mjDataRef.current;
+    const sid = localSiteIdRef.current;
+    if (!data || sid < 0 || !wrapperRef.current) return;
+
+    if (!draggingRef.current) {
+      const p = data.site_xpos;
+      const m = data.site_xmat;
+      const i3 = sid * 3;
+      const i9 = sid * 9;
+
+      // Position wrapper at the site
+      wrapperRef.current.position.set(p[i3], p[i3 + 1], p[i3 + 2]);
+      // MuJoCo site_xmat is row-major 3x3; THREE.Matrix4.set() is row-major
+      _mat4.set(
+        m[i9],     m[i9 + 1], m[i9 + 2], 0,
+        m[i9 + 3], m[i9 + 4], m[i9 + 5], 0,
+        m[i9 + 6], m[i9 + 7], m[i9 + 8], 0,
+        0,          0,          0,          1,
+      );
+      wrapperRef.current.quaternion.setFromRotationMatrix(_mat4);
+
+      // Reset any accumulated drag delta so handles stay at wrapper origin
+      if (pivotRef.current) {
+        pivotRef.current.matrix.identity();
+      }
+    }
+  });
+
+  // Don't render until the model is loaded (avoids gizmo at origin)
+  if (status !== 'ready') return null;
+
+  return (
+    <group ref={wrapperRef}>
+      <PivotControls
+        ref={pivotRef}
+        autoTransform
+        scale={scale}
+        fixed={false}
+        depthTest={false}
+        disableScaling
+        onDragStart={() => {
+          draggingRef.current = true;
+          if (!onDrag) {
+            // Default: enable IK so the robot follows
+            if (!ikEnabledRef.current) api.setIkEnabled(true);
+          }
+          if (controls) (controls as unknown as { enabled: boolean }).enabled = false;
+        }}
+        onDragEnd={() => {
+          draggingRef.current = false;
+          // Reset PivotControls so it doesn't accumulate across drags
+          if (pivotRef.current) {
+            pivotRef.current.matrix.identity();
+            pivotRef.current.matrixWorldNeedsUpdate = true;
+          }
+          if (controls) (controls as unknown as { enabled: boolean }).enabled = true;
+        }}
+        onDrag={(_l, _dl, world) => {
+          world.decompose(_pos, _quat, _scale);
+          if (onDrag) {
+            // Custom: consumer handles the drag
+            onDrag(_pos.clone(), _quat.clone());
+          } else {
+            // Default: write to provider's IK target
+            const target = ikTargetRef.current;
+            if (target) {
+              target.position.copy(_pos);
+              target.quaternion.copy(_quat);
+            }
+          }
+        }}
+      >
+        {/* Invisible zero-size child: gives PivotControls a valid child
+            without creating bounding-box anchor offset */}
+        <mesh visible={false}>
+          <sphereGeometry args={[0.001]} />
+        </mesh>
+      </PivotControls>
+    </group>
+  );
+}

package/src/components/SceneLights.tsx

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * SceneLights — auto-create Three.js lights from MJCF <light> elements (spec 6.3)
+ *
+ * WASM fields used: model.nlight, light_pos, light_dir, light_diffuse,
+ * light_specular, light_active, light_type, light_castshadow,
+ * light_attenuation, light_cutoff, light_exponent, light_intensity
+ *
+ * light_type: 0 = directional, 1 = spot (maps to mjLIGHT_DIRECTIONAL/mjLIGHT_SPOT)
+ * Note: light_directional does NOT exist in WASM — use light_type instead.
+ */
+
+import { useEffect, useRef } from 'react';
+import * as THREE from 'three';
+import { useThree } from '@react-three/fiber';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+import type { SceneLightsProps } from '../types';
+
+export function SceneLights({ intensity = 1.0 }: SceneLightsProps) {
+  const { mjModelRef, status } = useMujocoSim();
+  const { scene } = useThree();
+  const lightsRef = useRef<THREE.Light[]>([]);
+  const targetsRef = useRef<THREE.Object3D[]>([]);
+
+  useEffect(() => {
+    const model = mjModelRef.current;
+    if (!model || status !== 'ready') return;
+
+    // Clean up previous lights
+    for (const light of lightsRef.current) {
+      scene.remove(light);
+      light.dispose();
+    }
+    for (const t of targetsRef.current) scene.remove(t);
+    lightsRef.current = [];
+    targetsRef.current = [];
+
+    const nlight = model.nlight ?? 0;
+    if (nlight === 0) return;
+
+    for (let i = 0; i < nlight; i++) {
+      // Check if light is active
+      const active = model.light_active ? model.light_active[i] : 1;
+      if (!active) continue;
+
+      // light_type: 0 = directional, 1 = spot (no light_directional in WASM)
+      const lightType = model.light_type ? model.light_type[i] : 0;
+      const isDirectional = lightType === 0;
+      const castShadow = model.light_castshadow ? model.light_castshadow[i] !== 0 : false;
+
+      // Read intensity from model if available, otherwise use prop
+      const mjIntensity = model.light_intensity ? model.light_intensity[i] : 1.0;
+      const finalIntensity = intensity * mjIntensity;
+
+      // Read diffuse color
+      const dr = model.light_diffuse ? model.light_diffuse[3 * i] : 1;
+      const dg = model.light_diffuse ? model.light_diffuse[3 * i + 1] : 1;
+      const db = model.light_diffuse ? model.light_diffuse[3 * i + 2] : 1;
+      const color = new THREE.Color(dr, dg, db);
+
+      // Read position and direction
+      const px = model.light_pos[3 * i];
+      const py = model.light_pos[3 * i + 1];
+      const pz = model.light_pos[3 * i + 2];
+      const dx = model.light_dir[3 * i];
+      const dy = model.light_dir[3 * i + 1];
+      const dz = model.light_dir[3 * i + 2];
+
+      if (isDirectional) {
+        const light = new THREE.DirectionalLight(color, finalIntensity);
+        light.position.set(px, py, pz);
+        light.target.position.set(px + dx, py + dy, pz + dz);
+        light.castShadow = castShadow;
+        if (castShadow) {
+          light.shadow.mapSize.width = 1024;
+          light.shadow.mapSize.height = 1024;
+          light.shadow.camera.near = 0.1;
+          light.shadow.camera.far = 50;
+          const d = 5;
+          light.shadow.camera.left = -d;
+          light.shadow.camera.right = d;
+          light.shadow.camera.top = d;
+          light.shadow.camera.bottom = -d;
+        }
+        scene.add(light);
+        scene.add(light.target);
+        lightsRef.current.push(light);
+        targetsRef.current.push(light.target);
+      } else {
+        // Spot light
+        const cutoff = model.light_cutoff ? model.light_cutoff[i] : 45;
+        const exponent = model.light_exponent ? model.light_exponent[i] : 10;
+        const angle = (cutoff * Math.PI) / 180;
+        const light = new THREE.SpotLight(color, finalIntensity, 0, angle, exponent / 128);
+        light.position.set(px, py, pz);
+        light.target.position.set(px + dx, py + dy, pz + dz);
+        light.castShadow = castShadow;
+
+        if (model.light_attenuation) {
+          const att1 = model.light_attenuation[3 * i + 1]; // linear
+          const att2 = model.light_attenuation[3 * i + 2]; // quadratic
+          light.decay = att2 > 0 ? 2 : (att1 > 0 ? 1 : 0);
+          light.distance = att1 > 0 ? 1 / att1 : 0;
+        }
+
+        if (castShadow) {
+          light.shadow.mapSize.width = 512;
+          light.shadow.mapSize.height = 512;
+        }
+        scene.add(light);
+        scene.add(light.target);
+        lightsRef.current.push(light);
+        targetsRef.current.push(light.target);
+      }
+    }
+
+    return () => {
+      for (const light of lightsRef.current) {
+        scene.remove(light);
+        light.dispose();
+      }
+      for (const t of targetsRef.current) scene.remove(t);
+      lightsRef.current = [];
+      targetsRef.current = [];
+    };
+  }, [status, mjModelRef, scene, intensity]);
+
+  return null;
+}

package/src/components/SceneRenderer.tsx

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { useFrame } from '@react-three/fiber';
+import { useEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { GeomBuilder } from '../rendering/GeomBuilder';
+import { MujocoModel } from '../types';
+import { getName } from '../core/SceneLoader';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+
+/**
+ * SceneRenderer — creates and syncs MuJoCo body meshes every frame.
+ * Replaces RenderSystem.initScene() + RenderSystem.update() body loop.
+ */
+export function SceneRenderer() {
+  const { mjModelRef, mjDataRef, mujocoRef, onSelectionRef, status } = useMujocoSim();
+  const groupRef = useRef<THREE.Group>(null);
+  const bodyRefs = useRef<(THREE.Group | null)[]>([]);
+  const prevModelRef = useRef<MujocoModel | null>(null);
+
+  const geomBuilder = useMemo(() => {
+    return new GeomBuilder(mujocoRef.current);
+  }, [mujocoRef.current]);
+
+  // Build body groups when model loads
+  useEffect(() => {
+    if (status !== 'ready') return;
+    const model = mjModelRef.current;
+    const group = groupRef.current;
+    if (!model || !group) return;
+
+    // Skip if model hasn't changed
+    if (prevModelRef.current === model) return;
+    prevModelRef.current = model;
+
+    // Clear previous bodies
+    while (group.children.length > 0) {
+      group.remove(group.children[0]);
+    }
+
+    // Create body groups with geometry
+    const refs: (THREE.Group | null)[] = [];
+    for (let i = 0; i < model.nbody; i++) {
+      const bodyGroup = new THREE.Group();
+      bodyGroup.userData.bodyID = i;
+
+      for (let g = 0; g < model.ngeom; g++) {
+        if (model.geom_bodyid[g] === i) {
+          const mesh = geomBuilder.create(model, g);
+          if (mesh) bodyGroup.add(mesh);
+        }
+      }
+
+      group.add(bodyGroup);
+      refs.push(bodyGroup);
+    }
+    bodyRefs.current = refs;
+  }, [status, geomBuilder, mjModelRef]);
+
+  // Sync body positions from mjData every frame
+  useFrame(() => {
+    const data = mjDataRef.current;
+    if (!data) return;
+    const bodies = bodyRefs.current;
+    for (let i = 0; i < bodies.length; i++) {
+      const ref = bodies[i];
+      if (!ref) continue;
+      ref.position.set(
+        data.xpos[i * 3],
+        data.xpos[i * 3 + 1],
+        data.xpos[i * 3 + 2]
+      );
+      ref.quaternion.set(
+        data.xquat[i * 4 + 1],
+        data.xquat[i * 4 + 2],
+        data.xquat[i * 4 + 3],
+        data.xquat[i * 4]
+      );
+    }
+  });
+
+  return (
+    <group
+      ref={groupRef}
+      onDoubleClick={(e) => {
+        e.stopPropagation();
+        let obj: THREE.Object3D | null = e.object;
+        while (obj && obj.userData.bodyID === undefined && obj.parent) {
+          obj = obj.parent;
+        }
+        if (obj && obj.userData.bodyID !== undefined && obj.userData.bodyID > 0) {
+          const model = mjModelRef.current;
+          if (model && onSelectionRef.current) {
+            const name = getName(model, model.name_bodyadr[obj.userData.bodyID]);
+            onSelectionRef.current(obj.userData.bodyID, name);
+          }
+        }
+      }}
+    />
+  );
+}

package/src/components/SelectionHighlight.tsx

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * SelectionHighlight — highlight a selected body with emissive color (spec 6.5)
+ */
+
+import { useEffect, useRef } from 'react';
+import { useThree } from '@react-three/fiber';
+import * as THREE from 'three';
+import type { SelectionHighlightProps } from '../types';
+
+/**
+ * Applies emissive highlight to all meshes belonging to a body.
+ * Restores original emissive when bodyId changes or component unmounts.
+ */
+export function SelectionHighlight({
+  bodyId,
+  color = '#ff4444',
+  emissiveIntensity = 0.3,
+}: SelectionHighlightProps) {
+  const { scene } = useThree();
+  const prevMeshesRef = useRef<{ mesh: THREE.Mesh; originalEmissive: THREE.Color; originalIntensity: number }[]>([]);
+
+  useEffect(() => {
+    // Restore previous highlights
+    for (const entry of prevMeshesRef.current) {
+      const mat = entry.mesh.material as THREE.MeshStandardMaterial;
+      if (mat.emissive) {
+        mat.emissive.copy(entry.originalEmissive);
+        mat.emissiveIntensity = entry.originalIntensity;
+      }
+    }
+    prevMeshesRef.current = [];
+
+    if (bodyId === null || bodyId < 0) return;
+
+    // Find all meshes belonging to this body
+    const highlightColor = new THREE.Color(color);
+    scene.traverse((obj) => {
+      if (obj.userData.bodyID === bodyId && (obj as THREE.Mesh).isMesh) {
+        const mesh = obj as THREE.Mesh;
+        const mat = mesh.material as THREE.MeshStandardMaterial;
+        if (mat.emissive) {
+          prevMeshesRef.current.push({
+            mesh,
+            originalEmissive: mat.emissive.clone(),
+            originalIntensity: mat.emissiveIntensity ?? 0,
+          });
+          mat.emissive.copy(highlightColor);
+          mat.emissiveIntensity = emissiveIntensity;
+        }
+      }
+    });
+
+    return () => {
+      for (const entry of prevMeshesRef.current) {
+        const mat = entry.mesh.material as THREE.MeshStandardMaterial;
+        if (mat.emissive) {
+          mat.emissive.copy(entry.originalEmissive);
+          mat.emissiveIntensity = entry.originalIntensity;
+        }
+      }
+      prevMeshesRef.current = [];
+    };
+  }, [bodyId, color, emissiveIntensity, scene]);
+
+  return null;
+}

package/src/components/TendonRenderer.tsx

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * TendonRenderer — render tendons as tube geometries (spec 6.4)
+ *
+ * WASM fields used: model.ntendon, model.ten_wrapadr, model.ten_wrapnum
+ * data.wrap_xpos, data.ten_wrapadr (runtime)
+ *
+ * Note: ten_rgba and ten_width are NOT available in mujoco-js 0.0.7.
+ * Tendons use a default color and width.
+ */
+
+import { useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+import * as THREE from 'three';
+import { useMujocoSim } from '../core/MujocoSimProvider';
+
+const DEFAULT_TENDON_COLOR = new THREE.Color(0.3, 0.3, 0.8);
+const DEFAULT_TENDON_WIDTH = 0.002;
+
+export function TendonRenderer() {
+  const { mjModelRef, mjDataRef, status } = useMujocoSim();
+  const groupRef = useRef<THREE.Group>(null);
+  const meshesRef = useRef<THREE.Mesh[]>([]);
+
+  useFrame(() => {
+    const model = mjModelRef.current;
+    const data = mjDataRef.current;
+    const group = groupRef.current;
+    if (!model || !data || !group) return;
+
+    const ntendon = model.ntendon ?? 0;
+    if (ntendon === 0) return;
+
+    // Clean up old meshes
+    for (const mesh of meshesRef.current) {
+      group.remove(mesh);
+      mesh.geometry.dispose();
+      (mesh.material as THREE.Material).dispose();
+    }
+    meshesRef.current = [];
+
+    for (let t = 0; t < ntendon; t++) {
+      const wrapAdr = model.ten_wrapadr[t];
+      const wrapNum = model.ten_wrapnum[t];
+      if (wrapNum < 2) continue;
+
+      // Get wrap path points from data
+      const points: THREE.Vector3[] = [];
+      for (let w = 0; w < wrapNum; w++) {
+        const idx = (wrapAdr + w) * 3;
+        if (data.wrap_xpos && idx + 2 < data.wrap_xpos.length) {
+          const x = data.wrap_xpos[idx];
+          const y = data.wrap_xpos[idx + 1];
+          const z = data.wrap_xpos[idx + 2];
+          // Skip zero points (uninitialized wrap points)
+          if (x !== 0 || y !== 0 || z !== 0) {
+            points.push(new THREE.Vector3(x, y, z));
+          }
+        }
+      }
+
+      if (points.length < 2) continue;
+
+      const curve = new THREE.CatmullRomCurve3(points, false);
+      const geometry = new THREE.TubeGeometry(
+        curve, Math.max(points.length * 2, 4), DEFAULT_TENDON_WIDTH, 6, false
+      );
+
+      const material = new THREE.MeshStandardMaterial({
+        color: DEFAULT_TENDON_COLOR,
+        roughness: 0.6,
+        metalness: 0.1,
+      });
+      const mesh = new THREE.Mesh(geometry, material);
+      group.add(mesh);
+      meshesRef.current.push(mesh);
+    }
+  });
+
+  if (status !== 'ready') return null;
+  return <group ref={groupRef} />;
+}

package/src/components/TrajectoryPlayer.tsx

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * TrajectoryPlayer — component form of trajectory playback (spec 13.2)
+ */
+
+import { useEffect } from 'react';
+import { useTrajectoryPlayer } from '../hooks/useTrajectoryPlayer';
+import type { TrajectoryPlayerProps } from '../types';
+
+/**
+ * Component wrapper for useTrajectoryPlayer.
+ * Provides declarative trajectory playback controlled via props.
+ */
+export function TrajectoryPlayer({
+  trajectory,
+  fps = 30,
+  loop = false,
+  playing = false,
+  onFrame,
+}: TrajectoryPlayerProps) {
+  const player = useTrajectoryPlayer(trajectory, { fps, loop });
+
+  useEffect(() => {
+    if (playing) {
+      player.play();
+    } else {
+      player.pause();
+    }
+  }, [playing]);
+
+  useEffect(() => {
+    if (onFrame) {
+      // Poll frame changes (lightweight, no extra useFrame needed)
+      const interval = setInterval(() => {
+        if (player.playing) onFrame(player.frame);
+      }, 1000 / fps);
+      return () => clearInterval(interval);
+    }
+  }, [onFrame, fps]);
+
+  return null;
+}