# AGENTS.md — bimr-web

Browser app on the BIMR stack — batch-DSL Python over
[`bimr-wasm`](../bimr-wasm)'s single `compile()` export. Plan:
[`task/refactor/2026-08-13/white_web.md`](../task/refactor/2026-08-13/white_web.md).

## Build

```bash
make serve          # Vite HMR dev server at /editor/ (sync-wasm + samples + mp)
make build-web      # production build (sync-viewer + wasm + samples)
make build-web-dev  # build for /editor/ deployment path
make sync-viewer    # rebuild + sync viewer from bimr-viewer-ifcx
make sync-wasm      # copy the bimr-wasm pkg into src/wasm (built by make -C ../bimr-wasm pkg)
make sync-samples   # copy the subset samples from bimr-engine
make download-mp    # fetch MicroPython WASM runtime (jsDelivr, pinned @1.28.0-6)
make test           # Playwright app tests (after make build-web)
```

`serve`/`build-web` depend on `download-mp` (needs network on first use).

## Architecture (D8 — whole-source only)

```
User Python → micropython.wasm → bimr_api.py (string-buffer .bimr emitter)
            → bimrModule = { compile } → compile(dsl) once → IFCX → viewer
```

- `bimr_api.py` is a **subset-only buffer emitter** (`Point`, `Line`, `Wall`,
  `List`, `Column`, `Circle`, `Curve`, `Divide`, `Cut`, `Vector`,
  `Extrusion`, `Frame`, `Explode`, `Random`, `Slab`, `Level`, `Building` —
  `Column` lifts over a `List` of Points or a `Divide`; `Extrusion` takes a
  `List` of Lines or a `Cut`; `Frame` lifts over `Explode` pairs) — no
  per-op WASM calls, no handles, no
  `_h()`. Unsupported vocabulary does not exist. It lives in `src/` and is
  **inlined into the bundle at build time** (`?raw` import) — never fetched
  at runtime (cache-skew incident: a stale cached body made `_bimr_reset`
  vanish in Firefox).
- `bimrModule` is exactly `{ compile }` — no session, no other exports.
- `run()` compiles whole-source in both modes (python buffer / bimr doc);
  there is no session juggling.
- The bimr view shows the **live buffer** (last compiled source).

## Viewer

Viewer source is `bimr-viewer-ifcx/src/viewer/render.ts` — never edit
`src/viewer.render.mjs` (generated, gitignored). Run `make sync-viewer`; the
app bundle uses bare imports that Vite resolves from `node_modules` — no
runtime CDN dependency (offline-capable).

## Samples

Subset corpus — canonical source is
`bimr-engine/samples/python/` (`building.py`, `grid.py`,
`cylinders.py`; whitelisted in the Makefile). `make
sync-samples` copies them into
`public/samples/` to match `public/samples/index.json`. Never edit
`public/samples/*.py` directly.

*This document should be updated as the codebase evolves.*