# Overview

## What is mujoco-wasm-forge?

`mujoco-wasm-forge` is a toolchain that builds a specific upstream MuJoCo ref into WebAssembly, while keeping the
exported symbols and wrapper surface explicit and reviewable.

The goal is not just “MuJoCo compiles to WASM”, but:

- build a given MuJoCo ref into a predictable `dist/<ver>/` output layout,
- keep exported symbols under control via a single export list (`exports.lst`),
- generate ABI/audit artifacts so upgrades can be reviewed with diffs,
- run automated checks (smoke + quality gates) so CI can catch drift early.

## What it guarantees (and what it doesn’t)

**Designed guarantees**

- A single entrypoint (`forge_cli.py build`) that regenerates the full pipeline for one version/ref.
- An explicit exported C symbol list (`dist/<ver>/abi/exports.lst`) used by the link step.
- A consistent “dist layout” (`dist/<ver>/...`) consumed by all checks.
- Gate scripts that can be run locally and in CI.

**Non-goals**

- Freezing upstream MuJoCo ABI across versions (MuJoCo itself can change).
- Providing a high-level ergonomic JS API (the core output is Emscripten `mujoco.js/.wasm` plus wrappers).
- Guaranteeing byte-for-byte identical artifacts across arbitrary toolchains (use `verify-dist` for CI-grade
  reproducibility checks).

## Key terms

See `glossary` for a short definition of ABI, wrappers, `exports.lst`, introspection, and gates.