mujoco-react 0.1.0

package/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,510 @@
+# mujoco-react
+
+Composable [React Three Fiber](https://docs.pmnd.rs/react-three-fiber) building blocks for [MuJoCo](https://mujoco.org/) WASM simulations. Works with **any robot, any scene** — you provide the MJCF model, the library handles physics, rendering, and IK.
+
+
+## Install
+
+```bash
+npm install mujoco-react three @react-three/fiber @react-three/drei
+```
+
+## Quick Start
+
+```tsx
+import {
+  MujocoProvider,
+  MujocoCanvas,
+  SceneRenderer,
+  IkGizmo,
+} from 'mujoco-react';
+import type { SceneConfig, MujocoSimAPI } from 'mujoco-react';
+import { OrbitControls } from '@react-three/drei';
+
+const config: SceneConfig = {
+  robotId: 'franka_emika_panda',
+  sceneFile: 'scene.xml',
+  numArmJoints: 7,
+  tcpSiteName: 'tcp',
+  gripperActuatorName: 'gripper',
+  homeJoints: [1.707, -1.754, 0.003, -2.702, 0.003, 0.951, 2.490],
+};
+
+function App() {
+  const apiRef = useRef<MujocoSimAPI | null>(null);
+
+  return (
+    <MujocoProvider>
+      <MujocoCanvas
+        config={config}
+        onReady={(api) => { apiRef.current = api; }}
+        camera={{ position: [2, -1.5, 2.5], up: [0, 0, 1], fov: 45 }}
+        shadows
+        style={{ width: '100%', height: '100vh' }}
+      >
+        <OrbitControls enableDamping makeDefault />
+        <SceneRenderer />
+        <IkGizmo />
+        <ambientLight intensity={0.7} />
+        <directionalLight position={[1, 2, 5]} intensity={1.2} castShadow />
+      </MujocoCanvas>
+    </MujocoProvider>
+  );
+}
+```
+
+## Architecture
+
+```
+<MujocoProvider>              ← WASM module lifecycle
+  <MujocoCanvas config={...}> ← Thin R3F Canvas wrapper + physics context
+    <OrbitControls />          ← You add your own controls
+    <SceneRenderer />          ← Syncs MuJoCo bodies to Three.js meshes
+    <IkGizmo />                ← PivotControls-based IK handle
+    <YourLights />             ← You compose your own scene
+    <YourGrid />
+    <YourCustomLogic />        ← Your hooks + components
+  </MujocoCanvas>
+</MujocoProvider>
+```
+
+The library provides **only MuJoCo engine concerns**: WASM lifecycle, physics stepping, body rendering, IK solving. Everything else (lighting, grid, markers, game logic) is composed by the consumer as R3F children.
+
+## Loading Models
+
+Models are loaded from any HTTP source via `SceneConfig.baseUrl`. Defaults to [MuJoCo Menagerie](https://github.com/google-deepmind/mujoco_menagerie) on GitHub.
+
+```tsx
+// Menagerie robots — just set robotId
+const franka: SceneConfig = {
+  robotId: 'franka_emika_panda',
+  sceneFile: 'scene.xml',
+};
+
+// Any GitHub repo
+const so101: SceneConfig = {
+  robotId: 'so101',
+  sceneFile: 'SO101.xml',
+  baseUrl: 'https://raw.githubusercontent.com/Vector-Wangel/MuJoCo-GS-Web/main/assets/robots/xlerobot/',
+};
+
+// Self-hosted
+const custom: SceneConfig = {
+  robotId: 'my_robot',
+  sceneFile: 'robot.xml',
+  baseUrl: 'http://localhost:3000/models/my_robot/',
+};
+```
+
+The loader fetches the scene XML, parses it for dependencies (meshes, textures, includes), recursively fetches those too, applies any XML patches, and writes everything to MuJoCo's in-memory WASM filesystem.
+
+## SceneConfig
+
+```ts
+interface SceneConfig {
+  robotId: string;                  // e.g. 'franka_emika_panda'
+  sceneFile: string;                // Entry XML file, e.g. 'scene.xml'
+  baseUrl?: string;                 // Base URL for fetching model files
+  sceneObjects?: SceneObject[];     // Objects injected into scene XML at load time
+  tcpSiteName?: string;             // MuJoCo site for IK. Default: 'tcp'
+  gripperActuatorName?: string;     // Gripper actuator name. Default: 'gripper'
+  numArmJoints?: number;            // Number of arm joints for IK. Default: 7
+  homeJoints?: number[];            // Initial joint positions
+  xmlPatches?: XmlPatch[];          // Patches applied to XML files during loading
+  onReset?: (model, data) => void;  // Called during reset after mj_resetData
+}
+```
+
+### Adding Objects to Any Scene
+
+```tsx
+const config: SceneConfig = {
+  robotId: 'franka_emika_panda',
+  sceneFile: 'scene.xml',
+  sceneObjects: [
+    { name: 'ball', type: 'sphere', size: [0.03, 0.03, 0.03],
+      position: [0.5, 0, 0.1], rgba: [1, 0, 0, 1], mass: 0.1, freejoint: true },
+    { name: 'platform', type: 'box', size: [0.2, 0.2, 0.01],
+      position: [0.4, 0.3, 0], rgba: [0.5, 0.5, 0.5, 1] },
+  ],
+};
+```
+
+### XML Patching
+
+```tsx
+xmlPatches: [{
+  target: 'panda.xml',
+  replace: ['name="actuator8"', 'name="gripper"'],
+  inject: '<site name="tcp" pos="0 0 0.1" size="0.01"/>',
+  injectAfter: '<body name="hand"',
+}]
+```
+
+## Components
+
+### `<MujocoProvider>`
+
+Loads the MuJoCo WASM module. Wrap your entire app in this.
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `wasmUrl` | `string?` | Custom WASM URL override |
+| `onError` | `(error: Error) => void` | Called if WASM fails to load |
+
+### `<MujocoCanvas>`
+
+Thin wrapper around R3F `<Canvas>`. Accepts all R3F Canvas props plus:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `config` | `SceneConfig` | **Required.** Scene/robot configuration |
+| `onReady` | `(api: MujocoSimAPI) => void` | Fires when model is loaded |
+| `onError` | `(error: Error) => void` | Fires on scene load failure |
+| `onStep` | `(time: number) => void` | Called each physics step |
+| `onSelection` | `(bodyId: number, name: string) => void` | Called on double-click |
+| `gravity` | `[number, number, number]` | Override model gravity |
+| `timestep` | `number` | Override model.opt.timestep |
+| `substeps` | `number` | mj_step calls per frame |
+| `paused` | `boolean` | Declarative pause |
+| `speed` | `number` | Simulation speed multiplier |
+| `interpolate` | `boolean` | Interpolate body transforms between physics frames |
+| `gravityCompensation` | `boolean` | Auto-apply gravity compensation |
+| `mjcfLights` | `boolean` | Auto-create lights from MJCF model |
+
+### `<SceneRenderer />`
+
+Syncs MuJoCo bodies to Three.js meshes every frame. Must be inside `<MujocoCanvas>`.
+
+### `<IkGizmo />`
+
+drei PivotControls gizmo that tracks a MuJoCo site and drives IK on drag.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `siteName` | `string?` | config.tcpSiteName | MuJoCo site to track |
+| `scale` | `number?` | `0.18` | Gizmo handle scale |
+| `onDrag` | `(pos, quat) => void` | — | Custom drag handler (disables auto-IK) |
+
+### `<DragInteraction />`
+
+Click-drag to apply spring forces to bodies. Raycasts to find bodies, applies `F = (mouseWorld - grabWorld) * body_mass * stiffness` via `mj_applyFT`.
+
+### `<ContactMarkers />`
+
+InstancedMesh showing MuJoCo contact points for debugging.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `maxContacts` | `number?` | `100` | Max contacts to display |
+| `size` | `number?` | `0.005` | Marker sphere radius |
+| `color` | `string?` | `'red'` | Marker color |
+
+### `<SceneLights />`
+
+Auto-creates Three.js lights from MJCF `<light>` elements.
+
+### `<Debug />`
+
+Visualization overlays:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showGeoms` | `boolean?` | `false` | Wireframe collision geoms |
+| `showSites` | `boolean?` | `false` | Site markers |
+| `showJoints` | `boolean?` | `false` | Joint axes |
+| `showContacts` | `boolean?` | `false` | Contact force vectors |
+| `showCOM` | `boolean?` | `false` | Center of mass markers |
+
+### `<TendonRenderer />`
+
+Renders tendons as tube geometry from wrap paths.
+
+### `<FlexRenderer />`
+
+Renders deformable flex bodies from `flexvert_xpos`.
+
+### `<ContactListener />`
+
+Component wrapper for contact events:
+
+```tsx
+<ContactListener
+  body="block_1"
+  onContactEnter={(info) => console.log('contact!', info)}
+  onContactExit={(info) => console.log('released', info)}
+/>
+```
+
+### `<SelectionHighlight />`
+
+Emissive highlight on selected body meshes.
+
+### `<TrajectoryPlayer />`
+
+Plays back recorded qpos trajectories with scrubbing.
+
+## Hooks
+
+### `useMujocoSim()`
+
+Access the simulation API and internal refs:
+
+```tsx
+const { api, mjModelRef, mjDataRef } = useMujocoSim();
+```
+
+### `useBeforePhysicsStep(callback)`
+
+Run logic **before** `mj_step` each frame. Write to `data.ctrl`, apply forces, drive automation.
+
+```tsx
+useBeforePhysicsStep((model, data) => {
+  data.ctrl[0] = Math.sin(data.time);
+});
+```
+
+### `useAfterPhysicsStep(callback)`
+
+Run logic **after** `mj_step` each frame. Read results, compute rewards, log telemetry.
+
+### `useSensor(name)` / `useSensors()`
+
+Read sensor values by name (ref-based, no re-renders):
+
+```tsx
+const { value, size, type } = useSensor('force_sensor_1');
+```
+
+### `useBodyState(name)`
+
+Position, quaternion, linear/angular velocity of a body (ref-based):
+
+```tsx
+const { position, quaternion, linearVelocity, angularVelocity } = useBodyState('block_1');
+```
+
+### `useJointState(name)`
+
+Joint position and velocity:
+
+```tsx
+const { position, velocity } = useJointState('joint1');
+```
+
+### `useCtrl(name)`
+
+Read/write actuator control by name:
+
+```tsx
+const [value, setValue] = useCtrl('gripper');
+```
+
+### `useContacts(bodyName?)` / `useContactEvents(bodyName, handlers)`
+
+Query contacts or subscribe to enter/exit events:
+
+```tsx
+useContactEvents('block_1', {
+  onEnter: (info) => console.log('contact!', info),
+  onExit: (info) => console.log('released', info),
+});
+```
+
+### `useKeyboardTeleop(config)`
+
+Map keyboard keys to actuators:
+
+```tsx
+useKeyboardTeleop({
+  bindings: {
+    'w': { actuator: 'forward', delta: 0.1 },
+    's': { actuator: 'forward', delta: -0.1 },
+    'v': { actuator: 'gripper', toggle: [0, 0.04] },
+  },
+});
+```
+
+### `useGamepad(config)`
+
+Map gamepad axes/buttons to actuators:
+
+```tsx
+useGamepad({
+  axes: { 0: 'joint1', 1: 'joint2' },
+  buttons: { 0: 'gripper' },
+  deadzone: 0.1,
+});
+```
+
+### `usePolicy(config)`
+
+Framework-agnostic decimation loop for RL policies:
+
+```tsx
+const { step, isRunning } = usePolicy({
+  frequency: 50,
+  onObservation: (model, data) => buildObs(model, data),
+  onAction: (action, model, data) => applyAction(action, data),
+});
+```
+
+### `useTrajectoryRecorder(config)` / `useTrajectoryPlayer(trajectory, config)`
+
+Record and play back simulation trajectories:
+
+```tsx
+const recorder = useTrajectoryRecorder({ fields: ['qpos', 'qvel', 'ctrl'] });
+// recorder.start(), recorder.stop(), recorder.downloadJSON(), recorder.downloadCSV()
+
+const player = useTrajectoryPlayer(trajectory, { fps: 30, loop: true });
+// player.play(), player.pause(), player.seek(frameIdx)
+```
+
+### `useVideoRecorder(config)`
+
+Record the canvas as video:
+
+```tsx
+const video = useVideoRecorder({ fps: 30, mimeType: 'video/webm' });
+// video.start(), video.stop() → returns Blob
+```
+
+### `useCtrlNoise(config)`
+
+Apply Gaussian noise to controls for robustness testing:
+
+```tsx
+useCtrlNoise({ rate: 0.01, std: 0.05 });
+```
+
+### `useGravityCompensation(enabled?)`
+
+Applies `qfrc_bias` to `qfrc_applied` so joints hold position against gravity.
+
+### `useActuators()`
+
+Returns actuator metadata for building control UIs.
+
+### `useSitePosition(siteName)`
+
+Ref-based site position/quaternion tracking.
+
+## MujocoSimAPI
+
+The full API object returned by `onReady` and available via `useMujocoSim().api`:
+
+### Simulation Control
+
+| Method | Description |
+|--------|-------------|
+| `reset()` | Reset sim, re-apply home joints |
+| `setPaused(paused)` | Set pause state |
+| `togglePause()` | Toggle pause, returns new state |
+| `setSpeed(multiplier)` | Set simulation speed |
+| `step(n?)` | Advance exactly n steps while paused |
+| `getTime()` | Current simulation time |
+| `getTimestep()` | Current timestep |
+
+### State Management
+
+| Method | Description |
+|--------|-------------|
+| `saveState()` | Snapshot qpos, qvel, ctrl, time, act |
+| `restoreState(snapshot)` | Restore from snapshot |
+| `setQpos(values)` / `getQpos()` | Direct qpos access |
+| `setQvel(values)` / `getQvel()` | Direct qvel access |
+| `setCtrl(nameOrValues, value?)` | Set control by name or batch |
+| `getCtrl(name?)` | Get control values |
+| `applyKeyframe(nameOrIndex)` | Apply a keyframe |
+| `getKeyframeNames()` / `getKeyframeCount()` | Keyframe introspection |
+
+### Forces
+
+| Method | Description |
+|--------|-------------|
+| `applyForce(bodyName, force, point?)` | Apply force via `mj_applyFT` |
+| `applyTorque(bodyName, torque)` | Apply torque via `mj_applyFT` |
+| `setExternalForce(bodyName, force, torque)` | Write to `xfrc_applied` |
+| `applyGeneralizedForce(values)` | Write to `qfrc_applied` |
+
+### Model Introspection
+
+| Method | Description |
+|--------|-------------|
+| `getBodies()` | All bodies with id, name, mass, parentId |
+| `getJoints()` | All joints with id, name, type, range, bodyId |
+| `getGeoms()` | All geoms with id, name, type, size, bodyId |
+| `getSites()` | All sites with id, name, bodyId |
+| `getActuators()` | All actuators with id, name, range |
+| `getSensors()` | All sensors with id, name, type, dim |
+| `getSensorData(name)` | Read sensor value by name |
+| `getContacts()` | All active contacts |
+| `getModelOption()` | Timestep, gravity, integrator |
+
+### Model Mutation
+
+| Method | Description |
+|--------|-------------|
+| `setGravity(g)` | Set gravity vector |
+| `setTimestep(dt)` | Set timestep |
+| `setBodyMass(name, mass)` | Domain randomization |
+| `setGeomFriction(name, friction)` | Domain randomization |
+| `setGeomSize(name, size)` | Domain randomization |
+
+### Spatial Queries
+
+| Method | Description |
+|--------|-------------|
+| `raycast(origin, direction, maxDist?)` | Physics raycast via `mj_ray` |
+| `project2DTo3D(x, y, camPos, lookAt)` | Screen-to-world raycast (returns bodyId + geomId) |
+| `getCameraState()` | Camera position and orbit target |
+| `moveCameraTo(pos, target, ms)` | Smooth camera animation |
+
+### IK Control
+
+| Method | Description |
+|--------|-------------|
+| `setIkEnabled(enabled)` | Enable/disable IK tracking |
+| `moveTarget(pos, duration?)` | Move IK target with optional animation |
+| `syncTargetToSite()` | Snap IK target to current TCP position |
+| `solveIK(pos, quat, currentQ)` | Solve IK for a target pose |
+
+### Scene Management
+
+| Method | Description |
+|--------|-------------|
+| `loadScene(newConfig)` | Runtime model swap |
+| `getCanvasSnapshot(w?, h?, mime?)` | Base64 screenshot |
+
+## useFrame Priority
+
+| Priority | Owner | Purpose |
+|----------|-------|---------|
+| -1 | MujocoSimProvider | beforeStep, IK, mj_step, afterStep |
+| 0 (default) | SceneRenderer, your code | Body mesh sync, rendering |
+
+## Roadmap
+
+Features planned but not yet implemented:
+
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| **User-uploaded model loading** | P2 | `loadFromFiles(FileList)` — detect meshdir, write to VFS |
+| **URDF loading** | P2 | Load URDF models via MuJoCo's built-in URDF compiler |
+| **XML mutation / recompile** | P1 | `addBody()`, `removeBody()`, `recompile()` for runtime XML editing |
+| **Observation builder utilities** | P2 | Helpers for projected gravity, joint positions/velocities for RL |
+| **Physics interpolation** | P1 | Smooth rendering between physics ticks for 120Hz+ displays |
+| **Instanced geom rendering** | P2 | `<InstancedGeomRenderer />` for particle/granular sims |
+| **Web Worker physics** | P2 | Run `mj_step` off main thread via SharedArrayBuffer |
+
+### WASM Limitations (mujoco-js 0.0.7)
+
+These MuJoCo features are not yet exposed in the WASM binding:
+
+- `flex_faceadr` / `flex_facenum` / `flex_face` — FlexRenderer renders vertices without face indices
+- `ten_rgba` / `ten_width` — TendonRenderer uses default color/width
+
+## License
+
+Apache-2.0