mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-08-01 08:48:05 +00:00
68d03ea260
* feat(element-style): universal per-element style resolver One shared implementation of the three things every customizable plugin re-invented: a font loader, the customization.layout x/y-offset reader, and the "did the user actually override this font?" check. The override check is the load-bearing piece: the web UI's save flow writes full schema defaults into config.json on every save, and the plugin manager merges defaults again before instantiation, so key presence never means user intent. The resolver compares against the plugin's own schema defaults (via schema_manager), degrading to caller-supplied classic defaults when unavailable. This retires the hand-maintained _CLASSIC_FONT_DEFAULTS dicts that shipped broken twice. The loader is a superset of the four per-plugin variants: alias resolution (baseball), truetype for TTF/OTF/BDF (FreeType loads BDF at native size), .pil sidecar fallback for BDF (football), fallback font, PIL default — never raises. Also introduces the text_color convention ([r,g,b], absent = keep the plugin's hardcoded color). BasePlugin gains a lazy style_resolver property (invalidated on config change) and element_style() sugar; standalone helpers receive the resolver from their owning plugin. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * feat(element-style): x-style-elements schema expansion + color provenance Plugins can now declare styleable display elements once, compactly, on their customization schema ("x-style-elements") instead of hand-copying the ~50-line font/font_size/text_color/offset property blocks (currently duplicated 52x across the plugin monorepo). SchemaManager.load_schema expands declarations before caching, so the config form, save path, validation, and defaults generation all see the same shape; the single expansion implementation lives in src.element_style and is also applied by defaults_from_schema_file, keeping the web UI's view and a plugin's raw-schema-file view of the defaults provably identical (parity test). Generated blocks use only widgets the config form already renders (font-selector, color-picker, number inputs) and update x-propertyOrder when present (the template only renders listed keys). Expansion is idempotent, never mutates its input or the cached/on-disk schema, and a hand-written block for the same element always wins. Color gets the same provenance rule as fonts: the web form always posts the RGB inputs, so a saved config carries the schema-default color whether or not the user touched it — the resolver now only honors a color that DIFFERS from the schema default, and keeps the plugin's classic (possibly state-dependent, e.g. gold-on-touchdown) color otherwise. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * feat(web): live plugin preview on the config page Adds POST /api/v3/plugins/preview: renders a plugin headlessly with the CANDIDATE (unsaved) config and returns a PNG — so users can see exactly what the panel will show before saving, at their real panel size (from display.hardware) or a chosen test size. Two extractions make it drift-proof rather than parallel-implemented: - dev_server's _render_once moves to src/plugin_system/testing/render_service.py (pure PIL via VisualTestDisplayManager, install_deps=False always — safe in the web process, which never touches display hardware); the dev server now wraps it. - save_plugin_config's ~350-line form->config conversion is extracted verbatim as parse_plugin_config_form and shared by the preview endpoint, so preview and save can never interpret the form differently. update() is skipped by default (no network on the request thread); plugins with a test/harness.json get their mock-data fixture primed instead, and ?skip_update=0 opts into a live update. The config page gains a Live Preview panel (HTMX hx-include of the existing form, size selector, pixelated img fragment) — works for every plugin with zero per-plugin code, including the x-style-elements font/size/color fields. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(web): expand x-style-elements in the config-page form render too pages_v3's plugin-config partial loads config_schema.json directly from disk rather than through SchemaManager.load_schema, so declared style elements expanded everywhere EXCEPT the form the user actually sees. Found live on the devpi: the API served the expanded schema and the save path validated against it, but the config page rendered no font/color/offset fields. Apply the same (idempotent) expansion here. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(web): preview size selector — htmx caches hx-post, use hx-vals Found live on the devpi: selecting a preview size did nothing because htmx snapshots the request path when it processes the button, so the size dropdown's onchange mutation of hx-post never took effect. The size now travels as a __preview_size=WxH form field attached via hx-vals (evaluated at request time); the endpoint honors it (query args still win for API callers) and strips it before form parsing so it can't leak into the candidate config. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(web): allowlist plugin_id in the preview endpoint's dir lookup Same defense as the dev server's find_plugin_dir (and pages_v3's existing pattern): plugin_id arrives in request input and is used to build filesystem paths — reject anything outside ^[a-zA-Z0-9_-]{1,64}$ before touching the filesystem. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix: harden preview + resolver edges found in self-review - extract_schema_defaults now matches SchemaManager's array handling ([] for arrays without defaults, [item] for item-level defaults) — the documented parity guarantee was false for array-typed properties; parity test extended to cover them. - render_plugin_once calls plugin cleanup() in a finally (image captured first — cleanup may clear the canvas): preview instances could leak sessions/threads per request in the long-running web process. - Preview JSON path deep-merges the candidate onto the saved config, matching the form path — a shallow update() silently dropped saved sibling values in any nested section the candidate touched. - Preview render is bounded (15s, 504 on timeout, daemonized worker): a hanging plugin display() no longer pins a web worker forever. - ElementStyleResolver.is_for(config): public staleness check for callers that cache a resolver, instead of poking _config. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam * fix(render-service): adopt the dev server's exception-detail policy Port c6962701's convention into the shared render service (which supersedes the inline _render_once it patched): full tracebacks to the server log via exc_info, only the exception class name to the client. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FqzC1nzTWL4kaqgMaQZFam --------- Co-authored-by: Chuck <chuck@example.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
LED Matrix Web Interface V3
Modern, production web interface for controlling the LED Matrix display.
Overview
This directory contains the active V3 web interface with the following features:
- Real-time display preview via Server-Sent Events (SSE)
- Plugin management and configuration
- System monitoring and logs
- Modern, responsive UI
- RESTful API
Directory Structure
web_interface/
├── app.py # Main Flask application
├── start.py # Startup script
├── run.sh # Shell runner script
├── requirements.txt # Python dependencies
├── blueprints/ # Flask blueprints
│ ├── api_v3.py # API endpoints
│ └── pages_v3.py # Page routes
├── templates/ # HTML templates
│ └── v3/
│ ├── base.html
│ ├── index.html
│ └── partials/
└── static/ # CSS/JS assets
└── v3/
├── app.css
└── app.js
Running the Web Interface
Standalone (Development)
From the project root:
python3 web_interface/start.py
Or using the shell script:
./web_interface/run.sh
As a Service (Production)
The web interface can run as a systemd service that starts automatically based on the web_display_autostart configuration setting:
sudo systemctl start ledmatrix-web
sudo systemctl enable ledmatrix-web # Start on boot
Accessing the Interface
Once running, access the web interface at:
- Local: http://localhost:5000
- Network: http://:5000
Configuration
The web interface reads configuration from:
config/config.json- Main configurationconfig/config_secrets.json- API keys and secrets
API Documentation
The V3 API is mounted at /api/v3/ (app.py:144). For the complete
list and request/response formats, see
docs/REST_API_REFERENCE.md. Quick
reference for the most common endpoints:
Configuration
GET /api/v3/config/main- Get main configurationPOST /api/v3/config/main- Save main configurationGET /api/v3/config/secrets- Get secrets configurationPOST /api/v3/config/raw/main- Save raw main config (Config Editor)POST /api/v3/config/raw/secrets- Save raw secrets
Display & System Control
GET /api/v3/system/status- System statusPOST /api/v3/system/action- Control display (action body:start_display,stop_display,restart_display_service,restart_web_service,git_pull,reboot_system,shutdown_system,enable_autostart,disable_autostart)GET /api/v3/display/current- Current display frameGET /api/v3/display/on-demand/status- On-demand statusPOST /api/v3/display/on-demand/start- Trigger on-demand displayPOST /api/v3/display/on-demand/stop- Clear on-demand
Plugins
GET /api/v3/plugins/installed- List installed pluginsGET /api/v3/plugins/config?plugin_id=<id>- Get plugin configPOST /api/v3/plugins/config- Update plugin configurationGET /api/v3/plugins/schema?plugin_id=<id>- Get plugin schemaPOST /api/v3/plugins/toggle- Enable/disable pluginPOST /api/v3/plugins/install- Install from registryPOST /api/v3/plugins/install-from-url- Install from GitHub URLPOST /api/v3/plugins/uninstall- Uninstall pluginPOST /api/v3/plugins/update- Update plugin
Plugin Store
GET /api/v3/plugins/store/list- List available registry pluginsGET /api/v3/plugins/store/github-status- GitHub authentication statusPOST /api/v3/plugins/store/refresh- Refresh registry from GitHub
Real-time Streams (SSE)
SSE stream endpoints are defined directly on the Flask app
(app.py:607-619 — includes the CSRF exemption and rate-limit hookup
alongside the three route definitions), not on the api_v3 blueprint:
GET /api/v3/stream/stats- System statistics streamGET /api/v3/stream/display- Display preview streamGET /api/v3/stream/logs- Service logs stream
Development
When making changes to the web interface:
- Edit files in this directory
- Test changes by running
python3 web_interface/start.py - Restart the service if running:
sudo systemctl restart ledmatrix-web
Notes
- Templates and static files use the
v3/prefix to allow for future versions - The interface uses Flask blueprints for modular organization
- SSE streams provide real-time updates without polling