Development¶
Contributor conventions are in AGENTS.md at the repository root.
npm install # also installs the anywidget-instruments core, at the commit package.json pins
npm run build # front-end bundle (esbuild, js/build.mjs)
npm test # front-end unit tests (vitest), including the WCAG contrast audit
npm run lint # eslint, including the SEC-001 rules (no eval / innerHTML)
npm run check:reproducible # byte-identical rebuild (SEC-004)
pip install "anywidget-instruments @ git+https://github.com/AnywidgetInstruments/anywidget-instruments@<commit of package.json>"
pip install -e ".[dev]"
pytest # Python unit tests + headless execution of the example notebooks
ruff check . && ruff format --check . && mypy src
npx playwright test # end-to-end: JupyterLab, Notebook 7, marimo, every widget,
# performance benchmarks, visual regression, saved state
The documentation is built with pip install -e ".[docs]" and
mkdocs serve (or mkdocs build --strict).
Front end and trait contract¶
The widgets derive from the
anywidget-instruments
core, which holds the base view (BaseView), the model interface, the
schema-driven trait reading, the contract generator (js/scripts/contract.mjs),
the palettes and themes (its styles.css, imported first), the liveness and
the Python base class. Its TypeScript sources are bundled with the widgets of
this library; js/src/index.js registers the contracts of the widgets with
the base view (registerContracts). The base schema
(instrument.schema.json) comes from the core too, by its $id
https://anywidgetinstruments.github.io/anywidget-instruments/schema/instrument.schema.json.
The front end is written in TypeScript (js/src/), bundled by esbuild into
one unminified ES module with its source map (HOST-006). It depends on no
Python code: any anywidget host can run it with a dictionary of traits (see
Hosts and the trait contract).
- Schemas.
src/anywidget_instruments_industrial/schema/*.schema.jsondescribe the traits and messages of every widget: they are the single source of truth.npm run gen(also run bynpm run build,npm run typecheckandnpm test) generatesjs/src/generated/contract.ts(TypeScript types and specs) andstatic/contract.json(for hosts). - Reading traits.
BaseView.getreads each trait through its spec (js/src/contract/traits.tsof the core): wrong types give the default, numbers are clamped,"nan"is decoded. Reads are cached per raw value. - Authority.
js/src/contract/derived.tscomputes the derived traits (alarm levels, peaks, states) when no host owns the state (empty_session) and writes them back; with a host (the Python kernel sets_session), the host values are shown. Operator actions are always sent as messages and applied locally only without a host (HOST-004, HOST-012). - Shared rules. A rule implemented both in Python and in TypeScript lives
in
js/src/contract/and has cases intests/parity/*.json, run bytests/test_parity.pyandjs/test/parity.test.ts(HOST-005). - Divergence.
tests/test_contract.pychecks every exported widget against its schema: trait names, types, bounds, read-only state, class and instance defaults, states and the messages Python sends (with their buffer sizes).npm run typecheckchecks the views against the generated types. Both run in CI (HOST-011). - Without a kernel.
js/test/hostless.test.tsrenders each widget from a plain trait dictionary, ande2e/host.spec.jsdrivese2e/host/index.html, a host page without Python.
Visual baselines¶
After an intended visual change, refresh the screenshot baselines with
npx playwright test e2e/visual.spec.js --update-snapshots and check the new
images before committing them.
Documentation images¶
The pictures of docs/img/ are captures of the real widgets: refresh them
with the visual baselines whenever a drawing changes, so that the site never
shows an older look.
- Example notebooks (
filling_line.png,gallery.png, ...):AWI_SHOTS=docs/img npx playwright test e2e/examples.spec.js. - Widget pages (
docs/widgets/*.md,docs/img/widgets/, the widget pages of the nav and the links of the catalog), from the preview page and the trait contract:npm run build && node js/scripts/widget-pages.mjs. Run it when a widget, a schema or a drawing changes; do not edit the pages by hand. - Batch reactor showcase (
showcase-reactor.png,showcase-reactor-hero.png): startmarimo run lite/marimo/batch_reactor.py --headless --port 2719 --no-token, then runnode js/scripts/docs-images.mjs.
Preview page¶
js/preview/index.html renders every widget with an in-memory model, without
a kernel. Run python -m http.server at the repository root and open
http://localhost:8000/js/preview/index.html. Add ?style=classic or
?style=system&dark to switch styles.