Requirements status¶
Status of each requirement of the specification (version 0.14).
Legend: ✅ implemented and tested · 🟡 partial / not verifiable here · ⬜ not started
Test layers: py = pytest, js = vitest, e2e = Playwright in
JupyterLab / Notebook 7 / marimo (e2e/).
GEN – General and architecture¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| GEN-001 | M | 🟡 | Wheel/sdist build ready (hatch + npm hook) and release workflow; not yet published on PyPI / conda-forge |
| GEN-002 | M | ✅ | Every widget subclasses anywidget.AnyWidget |
| GEN-003 | M | 🟡 | JupyterLab 4, Notebook 7, marimo: e2e. VS Code and Colab not covered by automated tests (see docs/hosts.md) |
| GEN-004 | M | ✅ | Pre-bundled ESM in the wheel |
| GEN-005 | M | ✅ | No runtime network access (py test on the bundle); skins sanitized of external references |
| GEN-006 | M | ✅ | BSD 3-Clause (LICENSE), CITATION.cff; py test keeps the license and version of the metadata files consistent |
| GEN-007 | M | ✅ | Python ≥ 3.10, CI matrix 3.10–3.13 |
| GEN-008 | S | ✅ | Single AFM module (initialize + render) using only the AFM model API (plus optional widget_manager for nested widgets) |
| GEN-009 | S | ✅ | Runtime deps: anywidget, traitlets, numpy |
| GEN-010 | M | ✅ | No global state on import; CSS scoped under .awi-root |
| GEN-011 | S | ✅ | mo.ui.anywidget(...) triggers reactive re-execution (e2e marimo) |
| GEN-012 | M | ✅ | Base view, contract reading and generator, styles, liveness and base class from the anywidget-instruments core (package.json, pyproject.toml); base schema by $id |
API – Common widget API¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| API-001 … API-009 | M | ✅ | py + e2e (allwidgets.spec.js, both directions for every widget) |
| API-010 | S | ✅ | size; SVG / DPR-aware canvas |
| API-011 | M | ✅ | js |
| API-012 | S | ✅ | Panel |
| API-014 | M | ✅ | Drawing and form entry for every control (see Getting started); vitest, e2e |
| API-013 | C | ✅ | Panel.to_dict() / from_dict() |
NUM – Numeric widgets¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| NUM-001 … NUM-007 | M | ✅ | Nice ticks (exact divisions for Compass), log scale, format spec, step/clamp, out-of-range marker, invalid state (js + py) |
| NUM-008, NUM-009 | S | ✅ | coerce; update_rate throttling |
| NUM-010 | M | ✅ | Value field: parsing (decimal comma, exponent, SI prefix, unit), step, range check with message, kernel check of front-end values (js, py, e2e) |
| NUM-101 … NUM-104, NUM-106 … NUM-108 | M | ✅ | Knob, Dial (multi-turn), Gauge, Meter, Tank, Thermometer, FillSlide |
| NUM-105, NUM-109, NUM-110 | S | ✅ | VUMeter, SevenSegment, peak hold / decay |
| NUM-111 | C | ✅ | animate (≤ 300 ms) |
BOOL – Boolean widgets¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| BOOL-001 … BOOL-012 | M/S | ✅ | LED (blink), 4 switches, push button, six mechanical actions, read_latched(), latch_timeout, EmergencyStop |
| BOOL-013 | M | ✅ | Callback dispatcher: in a batch (every front-end update, ai.batch()) EmergencyStop callbacks run first (py) |
| BOOL-014 | S | ✅ | Two-step confirmation |
| BOOL-015 | S | ✅ | PushButton(lamp=…, lamp_color=…, lamp_blink=…), cap color, shape="round"; lamp state in the ARIA description and a ring when lit (py, js, e2e) |
CHART – Graphs¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| CHART-001 … CHART-004, CHART-006 | M | ✅ | Strip / scope / sweep, binary float32, circular buffer |
| CHART-005 | M | ✅ | e2e benchmark: ≥ 30 fps with a 1 kHz feed (≈ 49 fps measured) |
| CHART-007 … CHART-009 | S | ✅ | Trace styles, autoscale with hysteresis, pause |
| CHART-101, CHART-102 | S | ✅ | IntensityChart (6 colormaps, colorbar), DigitalWaveformGraph (buses, hex) |
| CHART-104, CHART-106 | S | ✅ | Draggable cursors with kernel-computed values; box zoom, wheel, pan, double-click reset (e2e) |
| CHART-103, CHART-105, CHART-107 | C | ✅ | MixedSignalGraph, annotations, CSV / PNG / SVG export (e2e CSV) |
| CHART-108 | S | ✅ | Axes panel (X / Y limits, Apply, Auto) on every graph; Y limits of WaveformChart and the radial range of PolarPlot (typed or mouse wheel) update the kernel settings (js, e2e) |
SPEC – Specialized displays¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| SPEC-001, SPEC-002 | S | ✅ | Compass, PolarPlot |
| SPEC-003, SPEC-004 | C | ✅ | SmithChart (z0 normalization, Z tooltips), RadarChart |
| SPEC-005, SPEC-006 | S | ✅ | PictureControl primitives; clicks to the kernel (e2e) |
| SPEC-007 | M | ✅ | Commands batched per cell (IPython post_run_cell, 20 ms coalescing elsewhere), one message, one frame |
SCADA – Supervisory objects¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| SCADA-001 … SCADA-004 | S | ✅ | Valve, Pump, Motor, Pipe |
| SCADA-005, SCADA-008 | M | ✅ | AlarmIndicator; alarm conventions |
| SCADA-006, SCADA-007 | S | ✅ | AlarmBanner, acknowledgement events (e2e) |
| SCADA-009, SCADA-010 | C | ✅ | Faceplates (auto/manual, commands); SynopticCanvas with nested widgets and pipe runs (e2e, Jupyter hosts) |
ALARM, UNIT, STYLE¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| ALARM-001 … ALARM-005 | M/S | ✅ | |
| UNIT-001 … UNIT-004 | M/S | ✅ | pint conversion, engineering scaling, SI prefixes |
| STYLE-001 … STYLE-004 | M/S | ✅ | modern / classic / system (dark hosts), CSS custom properties, set_default_style |
| STYLE-005 | C | ✅ | Skin parts background, housing, knob, needle |
| STYLE-006 | M | ✅ | Sanitized in the kernel and again in the browser |
| STYLE-007 | S | ✅ | theme trait (auto, light, dark, system), set_theme(), theme_switch() in every example and demo; contrast audit of both forced palettes (js), visual baseline of the dark theme |
| STYLE-008 | S | ✅ | ThemeSwitch (light / system / dark radio group); marimo page theme through its <body> classes (py, js, e2e marimo) |
PERF, A11Y, ROB, SEC¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| PERF-001 | M | ✅ | e2e benchmark: p95 < 50 ms (≈ 23 ms measured) |
| PERF-002 | M | ✅ | e2e benchmark: 50 indicators at 20 Hz, keydown p95 < 100 ms; CI runners measured 96–104 ms until off-screen updates were coalesced, 72–80 ms since on a machine throttled to CI speed |
| PERF-003, PERF-005 | S | ✅ | One render per frame; off-screen widgets skip drawing and refresh their DOM state (text, ARIA) at most every 100 ms (js test) |
| PERF-004 | M | ✅ | ≈ 32 kB gzipped (JS + CSS), CI budget 150 kB |
| A11Y-001 … A11Y-003 | M | ✅ | Keyboard (host shortcuts suppressed), ARIA roles, text/shape redundancy |
| A11Y-004 | S | ✅ | WCAG 2.1 AA contrast of light and dark palettes (js) |
| A11Y-005 | S | ✅ | prefers-reduced-motion |
| ROB-001 | M | ✅ | Kernel heartbeat; STALE badge and input rejection after a kernel restart (e2e JupyterLab, marimo) |
| ROB-002, ROB-003 | M | ✅ | |
| ROB-004 | S | ✅ | Saved widget state reopened without kernel: values shown read-only with NO KERNEL badge (e2e) |
| ROB-005 | S | ✅ | Views request history snapshots (charts, pictures); other traits synced by anywidget |
| SEC-001, SEC-002 | M | ✅ | ESLint rules; text via textContent / canvas text |
| SEC-003 | M | 🟡 | Trusted publishing + build provenance workflow (release.yml); needs the PyPI trusted publisher to be configured |
| SEC-004 | S | ✅ | npm run check:reproducible in CI (byte-identical rebuild) |
IND – Industrial operator objects¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| IND-001 … IND-003 | S/C | ✅ | AnalogIndicator: normal band, limit marks, target; grey scale unless in alarm |
| IND-010 … IND-013 | S/C | ✅ | SelectorSwitch: 2–5 positions, keyboard and ARIA, key lock enforced in the kernel, spring return |
| IND-020 … IND-022 | S/M/C | ✅ | StackLight: IEC 60073 colors, state glyph and text per tier, buzzer indicator |
| IND-030 … IND-034 | S | ✅ | PID (standard form, derivative on PV, anti-windup, bumpless) and PIDFaceplate (mode rules, clamping, confirmation, SP tracking) |
| IND-040 … IND-043 | S | ✅ | Annunciator: ISA-18.1 sequences A, M, R with lock-in, first out, horn, Silence / Ack / Reset / Test |
| IND-050 … IND-053 | S | ✅ | AlarmList: sort and filter, timed shelving with automatic unshelving, suppressed / out of service |
| IND-060 … IND-063 | S/C | ✅ | StateMachine: PackML model (17 states), valid commands only, state_complete(), custom models |
| IND-064 | S | ✅ | StateMachine("gemma"), GEMMA_MODEL: 16 procedures in families A, F, D; py, js (parity), preview |
| IND-065 | C | ✅ | StateMachine("isa88"), ISA88_MODEL: 12 states, 8 commands; py, js (parity) |
| IND-066 | C | ✅ | State title and group, global_commands; models as x-awi-presets in the contract; path_to(), state_title |
| IND-067 | S | ✅ | Model zones and routes (py + js parity), right-angle router and label placement (js/src/widgets/smlayout.ts, js), PackML / GEMMA / ISA-88 zone arrows (js hostless), visual baselines |
| IND-070 … IND-075 | S/C | ✅ | TrendChart: pens with own scales, float64 times over binary buffers, live / history (◀ ▶, zoom, span, Live), limit and setpoint lines, history bound, cursors, time entry, CSV / PNG / SVG (py, js, e2e) |
| IND-080 … IND-083 | S/C | ✅ | Transmitter: ISA-5.1 style bubble, NE 107 status by shape and text, ✕ BAD and no aria-valuenow on failure, alarm limits (py, js, e2e) |
| IND-090 … IND-093 | S/C | ✅ | EventLog: log(), max_events, category chips, filter by category and text, CSV, connect() / disconnect() audit trail (py, js, e2e) |
| IND-100 … IND-104 | S | ✅ | DeviationIndicator, Sparkline (binary history), BarGraph (per-bar alarm levels), KPITile with oee(), NumericEntry keypad with range check and confirm_delta (py, js, e2e) |
| IND-110 | S | ✅ | %x, %X, %b, %o with zero-padded width in every numeric widget and scale; entry field and keypad take values in that base (A..F keys in hexadecimal) (js) |
| IND-111, IND-112 | S | ✅ | BitField: 8, 16 or 32 bits, labels and colors per bit, word in hexadecimal, bits toggled in control mode (py, js, e2e) |
| IND-113, IND-114 | S/C | ✅ | RecipeTable: number, choice, Boolean and text columns, cells checked in the front end and again by the kernel (rejections shown), sort by column, rows added and deleted with row_edit; parity of the cell checks (py, js, e2e) |
| IND-115 | S | ✅ | XYGraph: line, markers, both, step and bar styles, float64 buffers, cursors (readout shared with Python), annotations, zoom, axis ranges, export (py, js, e2e) |
| IND-116 | S | ✅ | setpoint pointer of Gauge, Meter |
| IND-117 | C | ✅ | Logarithmic and secondary Y axes of WaveformChart |
| IND-118 | C | ✅ | value_labels |
| IND-119 | C | ✅ | EquipmentTree |
| IND-120 | S | ✅ | SvgPanel; py, js, e2e |
| IND-121 | S | ✅ | Role convention awi:<role>=<name>;… in data-awi or inkscape:label; py, js (parity) |
| IND-122 | S | ✅ | text, rotate, scale, show, state / case, color |
| IND-123 | S | ✅ | button, momentary, set, step; keyboard, ARIA |
| IND-124 | S | ✅ | Entry fields of step values; kernel range check |
| IND-125 | S | ✅ | problems, message under the panel |
| IND-126 | C | ✅ | SvgPanel.template(): voltmeter, pressure gauge, pilot lamp, selector, tank |
Tests: py (tests/test_industrial.py), js (js/test/industrial.test.js), e2e
(allwidgets.spec.js, both directions for each object), visual baselines;
example examples/filling_line.ipynb.
HOST – Host independence¶
All 47 widgets follow the trait contract: one JSON Schema each in
src/anywidget_instruments_industrial/schema/, a TypeScript view reading its traits
through it, and the front-end logic they share with Python checked by parity
cases. The trait contract page describes it for host
authors; the migration inventory
records the analysis it started from.
| ID | Pri | Status | Notes |
|---|---|---|---|
| HOST-001 | M | ✅ | A schema per widget and per base class (47 widgets); generated TypeScript types and static/contract.json, shipped in the wheel (py, js) |
| HOST-002 | M | ✅ | Every view reads its traits through the schema: wrong types replaced by the default, bounds applied, "nan" decoded, heading wrapped (x-awi-modulo), invalid array items dropped; reads are cached per raw value (js, e2e host page) |
| HOST-003 | M | ✅ | Every widget: neutral class defaults, Python widgets announce the kernel session; no stale indication without an announcement (py, js, e2e host page) |
| HOST-004 | M | ✅ | Derived traits computed by the front end without a host, host values kept otherwise: alarm_level, peak, BarGraph alarm levels, StateMachine state, PIDFaceplate summary, Annunciator windows and horn, shelving expiry, PictureControl click (js, e2e host page) |
| HOST-005 | M | ✅ | Parity cases in tests/parity/ (alarm levels, coerce, scales, heading wrap, peak hold, resolved defaults, bar graph, process commands, state machine, PID, the 72 annunciator transitions, alarm list, graph readouts of the waveform, intensity, digital and trend charts, Smith chart conversions, radar ranges, trend pens, image type); transition and simulation tables checked against the schemas (py, js) |
| HOST-006 | S | ✅ | Unminified bundle with a linked source map, still reproducible |
| HOST-007 | M | ✅ | Class and instance defaults of every widget checked against its schema by tests/test_contract.py (py) |
| HOST-008 | S | ✅ | ArrayBuffer, DataView and typed arrays accepted (core/buffers.ts); every buffer layout documented in the schemas; sizes of the buffers Python sends checked against them; short buffers never over-read (py, js) |
| HOST-009 | S | ✅ | SynopticCanvas children through the widget manager in Jupyter (e2e), placeholders with pipes and background without one (js) |
| HOST-010 | S | ✅ | SynopticCanvas.background as a buffer (e2e) or base64 text, with the image type detected as in Python (py, js) |
| HOST-011 | M | ✅ | tests/test_contract.py (every exported widget has a schema; trait names, types, bounds, read-only state, defaults, states and sent messages against the schemas) and npm run typecheck, both in CI |
| HOST-012 | M | ✅ | Operator actions sent as messages; applied by the front end only without a host owning the state (js host-less tests, e2e) |
DOC, QA¶
| ID | Pri | Status | Notes |
|---|---|---|---|
| DOC-001 | M | ✅ | MkDocs + mkdocstrings API reference (mkdocs build --strict) |
| DOC-002 | M | ✅ | Gallery notebook |
| DOC-003 | — | — | Withdrawn in specification 0.2 |
| DOC-004 | S | ✅ | PID tuning, tank supervision, signal acquisition (executed by pytest and e2e) |
| DOC-005 | S | ✅ | Offline-capable static site (no web fonts / CDN), docs.yml deploys to GitHub Pages from main |
| DOC-006 | C | ✅ | Four demos (gallery, PID tuning, operator station, signal analysis), each as a marimo WebAssembly app and a JupyterLite notebook with the package wheel; the Docs workflow opens all eight in a browser and checks that an input drives a computed output (e2e-site/) |
| DOC-007 | M | ✅ | Safety notice, linked from the home page, the README, the widget catalog, the examples and the demos, and from the docstrings (py test); shown on the page of each safety-related widget (py test) |
| DOC-008 | S | ✅ | js/scripts/widget-pages.mjs captures every widget from the preview page in both themes and writes docs/widgets/*.md from the trait contract; pytest runs the examples and checks every page and picture |
| QA-001, QA-002 | M | ✅ | pytest, vitest |
| QA-003 | M | ✅ | e2e JupyterLab (every widget, both directions), marimo, Notebook 7 |
| QA-004 | S | ✅ | Screenshot comparison of every widget per style |
| QA-005 | S | ✅ | Benchmarks with thresholds in CI |
| QA-006 | M | ✅ | CI: lint, type check, unit, e2e, reproducible build, bundle budget |
Open questions (spec §21): decisions for this implementation¶
- Name:
anywidget-instruments-industrial(importanywidget_instruments_industrial). - Rendering: SVG for instruments, Canvas 2D for graphs and PictureControl.
- Julia binding: out of scope for 1.0; the single AFM module is ready for it.
- Latch semantics: explicit
read_latched(). - ISA-101: alarm colors, redundant shape/text coding and faceplates; a full grey-scale high-performance HMI theme is not provided.