Repo layout
===========

Top-level directories
---------------------

- ``app/``: main-thread entrypoint + Host contract wiring
- ``backend/``: Worker backend wrapper (spawns the Worker, exposes a UI/plugin-friendly surface)
- ``bridge/``: forge/WASM bridge helpers (heap views, ``MjSimLite``)
- ``core/``: shared runtime defaults/types/URL param helpers/logging helpers
- ``environment/``: sky/environment manager
- ``renderer/``: renderer pipeline + controllers + overlays
- ``ui/``: UI store/state/actions + control manager + panels/sections
- ``worker/``: module Worker entrypoint + generated protocol/dispatch
- ``assets/``: static assets (e.g., HDRIs)
- ``model/``: built-in demo models
- ``plugins/``: built-in demo plugins
- ``tools/``: generators and small CI/maintenance scripts
- ``tests/``: tests and tooling (unit: ``tests/unit/``, Playwright: ``tests/e2e/``)
- ``local_tools/``: local-only utilities/artifacts (gitignored)

Key runtime entrypoints
-----------------------

- ``index.html``: static page + import map
- ``app/main.mjs``: main entrypoint (UI + renderer + Worker backend + Host API)
- ``worker/physics.worker.mjs``: Worker entrypoint (loads forge + runs MuJoCo)

Key runtime modules
-------------------

- ``backend/backend_core.mjs``: backend (``createBackend(...)``; wraps the Worker protocol)
- ``core/viewer_runtime.mjs``: logging, strict/compat/perf helpers, URL param helpers
- ``ui/state.mjs``: viewer store/state/actions + snapshot merge
- ``ui/control_manager.mjs``: DOM wiring + UI panels/controls
- ``renderer/pipeline.mjs``: renderer pipeline + ``createRendererManager(...)``
- ``renderer/controllers.mjs``: camera + picking controllers
- ``environment/environment.mjs``: sky/environment presets + runtime manager
- ``bridge/heap_views.mjs`` / ``bridge/mj_sim_lite.mjs``: forge/WASM bridge helpers
- ``worker/snapshot_pool.mjs``: worker snapshot pool policy/state

Generated artifacts
-------------------------------

Generated files are committed for the static runtime and GitHub Pages.

- Worker protocol:
  - Source: ``tools/worker_protocol.json``
  - Generator: ``tools/generate_worker_protocol.mjs``
  - Outputs: ``worker/protocol.gen.mjs``, ``worker/dispatch.gen.mjs``

- UI artifacts / types:
  - Source: ``spec/ui_spec.json`` (+ schema/index)
  - Generator: ``tools/generate_ui_artifacts.mjs``
  - Outputs (examples): ``core/viewer_structs.mjs``, ``core/viewer_state_types.ts``

Forge dist bundles
------------------

This repo may vendor one or more forge bundles under ``dist/<ver>/`` for
local/demo convenience, but the build pipeline for these artifacts lives in the
forge repo (``mujoco-wasm-forge``).