feat(web): ES-module page lifecycle and one schema field model (stage 1)

CHANGELOG.md

@@ -19,6 +19,33 @@ accepts both, but the store flags the old spelling as deprecated
 
 ## Unreleased
 
+### Web UI: ES modules and one form model (stage 1)
+
+- The web UI gains a native ES-module layer, loaded with
+  `<script type="module">` and served as-is (no bundler, nothing built on
+  the Pi): `static/v3/js/core/` (`boot.js`, `registry.js`, `api.js`,
+  `facade.js`) and `static/v3/js/pages/`. `window.LEDMatrix` is its one
+  global: `api`, `pages`, `notify`, `escape`, `widgets` and `deprecate`, the
+  last keeping old `window.*` names working as aliases that warn once.
+- Tab partials can become page modules: a partial whose root says
+  `data-page="<name>"` carries no inline script, and the page registry calls
+  the page's `init` once when htmx swaps it in and `destroy` when it is
+  swapped out, aborting a signal that removes its listeners and cancels its
+  requests. The Cache tab is converted as the reference
+  (`js/pages/cache.js`); `window.deleteCacheFile` remains as an alias.
+- Static `.js` files are always served as `text/javascript`, which module
+  scripts require, and a `.js` request without the `?v=` content version
+  (how modules import each other) is revalidated instead of cached as
+  immutable for a year.
+- `src/plugin_system/field_model.py`: `build_field_model(schema, config)`
+  describes a plugin's config form as one JSON field model. Nothing renders
+  from it yet; `test/test_field_model_parity.py` checks it names exactly the
+  form controls and starting values the `render_field` macro emits, for every
+  schema available (all 46 official plugins, when a checkout is present).
+- `docs/WEB_FRONTEND_ARCHITECTURE.md`: the target architecture, the
+  page-by-page migration order, and how forms switch to the model and to
+  JSON submit behind a flag.
+
 ### Update channels
 
 - Devices no longer pick up every merge to `main`. A new setting,

docs/HOW_TO_RUN_TESTS.md

@@ -170,6 +170,31 @@ pytest test/test_config_manager.py
 pytest
 ```
 
+### Web UI JavaScript Tests
+
+The suites in `test/js` need node; the DOM ones also need jsdom and a running
+web interface (details in [`test/js/README.md`](../test/js/README.md)):
+
+```bash
+npm install --no-audit --no-fund --prefix test/js   # jsdom; node_modules is gitignored
+EMULATOR=true python3 web_interface/app.py           # in another shell
+BASE=http://localhost:5000 REQUIRE_DOM=1 node test/js/run_all.js
+```
+
+`pytest test/test_js_unit_suites.py` runs just the unit suites.
+
+### Plugin Config Form Parity
+
+`test/test_field_model_parity.py` checks `build_field_model` against the
+`render_field` macro for every plugin schema it finds
+([WEB_FRONTEND_ARCHITECTURE.md](WEB_FRONTEND_ARCHITECTURE.md)). It always
+covers `plugin-repos/` and the test fixtures; point it at a checkout of the
+official plugins to cover those too:
+
+```bash
+LEDMATRIX_MONOREPO_PLUGINS=../ledmatrix-plugins/plugins pytest test/test_field_model_parity.py
+```
+
 ### Debug a Failing Test
 
 ```bash

docs/README.md

@@ -72,6 +72,7 @@ Going deeper:
 ## Contributing to LEDMatrix itself
 
 - [ARCHITECTURE.md](ARCHITECTURE.md) — processes, display loop, plugin system, web UI; where to start reading
+- [WEB_FRONTEND_ARCHITECTURE.md](WEB_FRONTEND_ARCHITECTURE.md) — the web UI's ES modules, page lifecycle and form model, and the page-by-page migration to them
 - [DEVELOPMENT.md](DEVELOPMENT.md) — environment setup
 - [HOW_TO_RUN_TESTS.md](HOW_TO_RUN_TESTS.md) — running the test suite
 - [MULTI_ROOT_WORKSPACE_SETUP.md](MULTI_ROOT_WORKSPACE_SETUP.md) — multi-repo workspace

mypy-clean.txt

@@ -52,6 +52,7 @@ src/matrix_support.py
 src/pi5_matrix_support.py
 src/plugin_system/__init__.py
 src/plugin_system/compatibility.py
+src/plugin_system/field_model.py
 src/plugin_system/operation_history.py
 src/plugin_system/operation_queue.py
 src/plugin_system/operation_types.py