# beadnet

Python package (numba solver, Zarr v2 output) plus browser components (`beadnet/static/beadnet.js`, plain ES module, no build step) for bead-and-spring percussion models. Port of the solver in `~/projects/bead-percussion` (TypeScript); keep the two in agreement.

## Building and running models for the user

Read `beadnet/AGENT_GUIDE.md` first and follow it. The workspace is `work/` (gitignored): scripts in `work/scripts/`, results in `work/runs/`, saved models in `work/models/`, pages in `work/pages/`. View with `beadnet serve work` (port 8790). Run anything longer than about a minute in the background.

## Development

- `python -m venv .venv && . .venv/bin/activate && pip install -e '.[test]'`; `python -m pytest -q`.
- Keep the code Python 3.9 compatible (`from __future__ import annotations`; no runtime `X | Y` types).
- `tests/fixtures/ts_reference.json` holds runs exported from the TypeScript solver; the cross-check test compares per-bead signals with them. Regenerate it if the TS solver changes.
- The JS has no tests; check changes in a browser against runs in `work/`.
- Update `AGENT_GUIDE.md` and `README.md` when the API, the store layout or the components change.