v0.34.9_css_refactor

scripts/README.md

@@ -10,6 +10,74 @@ External development and QA helpers live under `tools/`; external platform integ
 
 Keep these paths stable because Rust source, `build.rs` and shell entry points reference them directly.
 
+## Panel stylesheet sources
+
+The dashboard stylesheet lives in `src/admin/web/css/`, with its complete cascade
+order declared in `manifest.json`. Edit those modules, not a generated bundle.
+`build.rs` invokes `build/panel_css.py` using Python 3.10+ (or
+`RUST_PROXY_PYTHON`) and embeds the compact `OUT_DIR/panel-style.css`. Login and
+the dashboard continue to load one fingerprinted stylesheet, using the existing
+panel compression and access rules; no npm install or runtime CSS imports are
+needed. The documentation page retains its separate `src/admin/web/docs.css`.
+
+```bash
+python3 scripts/build/panel_css.py --check
+python3 tools/dev/test_panel_css.py
+python3 scripts/audit_css_usage.py --strict
+```
+
+The first two commands use only the Python standard library. The optional
+selector/structure audit needs `tinycss2` and `cssselect2`; it checks all manifest
+modules together and reviews the documentation stylesheet separately. Use
+`--json PATH` for selector references and `--structure-json PATH` for repeated
+selectors, conditional blocks, properties and identical declaration blocks.
+Missing class tokens are review candidates: classes assembled by JavaScript
+must be checked before deleting their styles. Strict mode also rejects identical
+declaration bodies within a compatible selector family. It permits separate
+standard/WebKit/Gecko rules only when joining them would create an incompatible
+vendor selector list. Choose shared-rule placement by checking the cascade,
+not by mechanically moving every matching block to the beginning of a module.
+
+Preflight rejects missing, repeated or unlisted CSS modules and stale monolithic
+`style.css` files. `./dev.sh repair` backs up only the exact original 0.34.9
+monolith; custom or unknown content requires manual review and is never moved
+or discarded automatically. Rebuild the Rust binary after changing CSS.
+
+Keep `scripts/__init__.py` and `scripts/build/__init__.py` in the source package.
+They keep preflight, audit, tests and packaging imports local even when unrelated
+Python packages named `scripts` or `build` are installed. An older CSS-refactor
+archive without the build marker can fail
+with `ModuleNotFoundError: No module named 'build.panel_css'`; restore the marker
+from the complete source archive and run `bash dev.sh repair` again. Installing
+another Python package is not required.
+
+### Missing generated CSS during Rust compilation
+
+`panel-style.css` is generated inside Cargo's `OUT_DIR`. `bash dev.sh repair`
+validates the source layout and preserves known obsolete files; it does not
+generate Cargo outputs. Preflight also checks that the current `build.rs` calls
+the panel generator from `main` and reports a mixed source tree before Cargo.
+
+After overlaying a source ZIP onto a previously built checkout, a compiler error
+for a missing `OUT_DIR/panel-style.css` can indicate an old cached build script
+or a `build.rs` from another source version. Restore the complete matching
+archive, including the root `build.rs`, then run from the project root:
+
+```bash
+bash dev.sh repair
+touch build.rs
+bash dev.sh build
+```
+
+The source ZIP uses reproducible timestamps. Cargo's
+[build-script change detection](https://doc.rust-lang.org/cargo/reference/build-scripts.html#change-detection)
+uses file modification times, so refreshing `build.rs` forces regeneration after
+an archive overlay. This works with the target directory selected by `dev.sh`.
+The generator now also registers its output as a watched Cargo dependency and
+recreates a removed bundle. An identical bundle keeps its modification time.
+The Rust build script rejects a missing, empty or non-file output immediately
+after the helper returns.
+
 ## Stream TCP/UDP test helpers
 
 - `start_stream_backends.sh` — launches two TCP echo mocks (9101, 9102) and two UDP echo/probe mocks (9201, 9202), defaulting to loopback, and terminates all on Ctrl+C.