mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-10-04 22:35:08 +00:00
ChuckandClaude Opus 5.5
a8b3e86775
* refactor(web): drop validators nothing calls escape_html, validate_image_url, validate_font_awesome_class, validate_mime_type, validate_numeric_range, validate_string_length and sanitize_plugin_config had no callers outside their own tests. Only validate_file_upload (fonts upload) is imported by the web interface. dedup_unique_arrays is kept: its one caller in save_plugin_config was removed by the unrelated sync PR (#330), which looks accidental. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(api): remove the music-auth and of-the-day JSON routes POST /plugins/authenticate/spotify and /plugins/authenticate/ytm had no caller but their tests: the music plugin authenticates through its web_ui_actions (authenticate_spotify.py / authenticate_ytm.py) via /plugins/action. POST /plugins/of-the-day/json/upload and /json/delete looked the plugin up by the id ledmatrix-of-the-day (its manifest id is of-the-day), were reachable only from a file_type "json" upload field that no schema declares, and put the plugin directory on sys.path per request to import scripts.update_config. of-the-day manages its files through plugin-file-manager and its own web_ui_actions. The of-the-day branch of GET /plugins/config stays: it matches the real manifest id and still merges the on-disk category files into the form. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(api): read managers only from the blueprints api_v3/__init__.py and pages_v3.py declared module globals (plugin_store_manager, saved_repositories_manager, schema_manager, operation_queue, plugin_state_manager, operation_history, sync_manager, config_manager, plugin_manager) that nothing assigns: app.py sets the managers as attributes on the Blueprint objects, and every route reads them there. The one reader, backup restore's fallback to the module plugin_store_manager, could only ever fall back to None. _ensure_cache_manager() built a second CacheManager in the web process instead of using the one app.py puts on api_v3. The display routes now read api_v3.cache_manager, creating it on the blueprint only when nothing set it (the same None handling as the /cache routes). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(web): drop run.sh and the unused log_config_change web_interface/run.sh was referenced only by web_interface/README.md; the service starts the UI through scripts/utils/start_web_conditionally.py and the README already documents `python3 web_interface/start.py`. log_config_change() in web_interface/logging_config.py was never called. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): delete unreferenced store_manager.js, diff_viewer.js, htmx-sse.js - js/plugins/store_manager.js (window.PluginStoreManager) and js/config/diff_viewer.js (window.ConfigDiffViewer) were loaded on every page but nothing reads either global. - htmx-sse.js (plus its CDN fallback) was loaded after HTMX, but no template or plugin page uses sse-connect / hx-ext="sse": the live streams run through LEDStreams in app-shell.js. js/plugins/state_manager.js stays: install_manager.js's updateAll() reads and refreshes window.PluginStateManager. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): remove app.js helpers nothing calls - hexToRgb, rgbToHex, validateForm, uploadFont and switchTab (whose 'switch-tab' event had no listener) have no caller in the templates, static JS or the plugin monorepo. - installPlugin: plugins_manager.js (loaded last) assigns window.installPlugin, and its own store cards are the only callers. - The showNotification fallback could never install: app-shell.js is deferred ahead of app.js and defines the same fallback at top level. - performanceMonitor only logged with ?debug=perf and read an unset this.measures; the marks it took on every load had no reader. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): drop app-shell.js refreshPlugin A top-level function in app-shell.js, so a window global, but nothing calls it (no inline handler, no window lookup, no string-built name). The other plugin actions in that block stay. updatePlugin is the live window.updatePlugin: plugins_manager.js only installs its own copy when none exists. uninstallPlugin/pollUninstallOperation, updateAllPlugins, executePluginAction and toggleNestedSection are replaced by later deferred scripts, but a click that lands while those scripts are still downloading reaches the app-shell copies, so removing them is not a pure no-op. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): remove definitions plugins_manager.js always overrides All of these are replaced before anything can call them, checked against the load order in base.html and the live window.* values: - openOnDemandModal/requestOnDemandStop stubs: the IIFE later in the same script assigns the real functions synchronously. - updatePlugin and uninstallPlugin stubs (`window.X || stub`): app-shell.js already defined both, so the fallback never installed. Same for the later updatePlugin override, gated on the live function containing '[UPDATE]', which app-shell.js's never does. - The first addArrayObjectItem/removeArrayObjectItem: reassigned by the top-level copies after the IIFE. - The first `function formatDate` in the IIFE: a later declaration of the same name in the same scope wins. - deleteUploadedImage, getCurrentImages, showUploadProgress, formatFileSize and getScheduleSummary: character-for-character copies of js/widgets/file-upload.js, which stays the owner. - `typeof X === 'undefined'` fallbacks and `typeof X !== 'undefined'` re-exports after the IIFE: always false, or a self-assignment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(web): render the shell directly and delete index.html index.html extended base.html with {% block content %}, but base.html defines no blocks, so none of index.html ever rendered: rendering both with jinja2 gives byte-identical output. index() still loaded the config, read config.json and config_secrets.json raw and json.dumps'd them on every page load for variables base.html never reads, and flashed errors that base.html never shows. It now renders base.html with no context. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(web): stop htmx-config.js replacing console.error and console.warn It swapped both globals for filters that dropped any error mentioning insertBefore / "Cannot read properties of null" when "htmx" appeared in the message or stack, and a list of Permissions-Policy warnings. That hid real errors from every script on the page, and made every logged error and warning report htmx-config.js as its source. The beforeSwap target validation above it, which prevents the insertBefore errors in the first place, stays. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * chore(web): quiet the widget load announcements and debug logs About 30 lines hit the console on every page load: one "... widget registered" per widget file, one "[WidgetRegistry] Registered widget: X" per registration, plus the registry, base widget and plugin loader announcing themselves. The load-time announcements are removed; the per-call ones (registry register, plugin widget loads, "Render called") now go through the page's debugLog switch (localStorage.pluginDebug), guarded because the widgets also load in node tests without it. fonts.html and wifi.html debug logging goes through debugLog as well. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(api): drop the removed music-auth and of-the-day JSON routes Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
135 lines
4.8 KiB
Markdown
135 lines
4.8 KiB
Markdown
# 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
|
|
├── requirements.txt # Python dependencies
|
|
├── blueprints/ # Flask blueprints
|
|
│ ├── api_v3/ # API endpoints (package: config, display,
|
|
│ │ # plugins, system, backup, fonts, misc,
|
|
│ │ # wifi, starlark)
|
|
│ └── pages_v3.py # Page routes
|
|
├── templates/ # HTML templates
|
|
│ └── v3/
|
|
│ ├── base.html
|
|
│ └── partials/
|
|
└── static/ # CSS/JS assets
|
|
└── v3/
|
|
├── app.css
|
|
├── app.js
|
|
├── manifest.json # PWA manifest
|
|
├── plugins_manager.js
|
|
├── icons/ # PWA / touch icons
|
|
├── js/ # Alpine, htmx, app shell, widgets, utils
|
|
└── vendor/ # codemirror, fontawesome
|
|
```
|
|
|
|
## Running the Web Interface
|
|
|
|
### Standalone (Development)
|
|
|
|
From the project root:
|
|
```bash
|
|
python3 web_interface/start.py
|
|
```
|
|
|
|
### As a Service (Production)
|
|
|
|
The web interface can run as a systemd service that starts automatically based on the `web_display_autostart` configuration setting:
|
|
|
|
```bash
|
|
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://<raspberry-pi-ip>:5000
|
|
|
|
## Configuration
|
|
|
|
The web interface reads configuration from:
|
|
- `config/config.json` - Main configuration
|
|
- `config/config_secrets.json` - API keys and secrets
|
|
|
|
## API Documentation
|
|
|
|
The V3 API is the `api_v3` blueprint, registered at `/api/v3/` in
|
|
`app.py`. For the complete
|
|
list and request/response formats, see
|
|
[`docs/REST_API_REFERENCE.md`](../docs/REST_API_REFERENCE.md). Quick
|
|
reference for the most common endpoints:
|
|
|
|
### Configuration
|
|
- `GET /api/v3/config/main` - Get main configuration
|
|
- `POST /api/v3/config/main` - Save main configuration
|
|
- `GET /api/v3/config/secrets` - Get secrets configuration
|
|
- `POST /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 status
|
|
- `POST /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 frame
|
|
- `GET /api/v3/display/on-demand/status` - On-demand status
|
|
- `POST /api/v3/display/on-demand/start` - Trigger on-demand display
|
|
- `POST /api/v3/display/on-demand/stop` - Clear on-demand
|
|
|
|
### Plugins
|
|
- `GET /api/v3/plugins/installed` - List installed plugins
|
|
- `GET /api/v3/plugins/config?plugin_id=<id>` - Get plugin config
|
|
- `POST /api/v3/plugins/config` - Update plugin configuration
|
|
- `GET /api/v3/plugins/schema?plugin_id=<id>` - Get plugin schema
|
|
- `POST /api/v3/plugins/toggle` - Enable/disable plugin
|
|
- `POST /api/v3/plugins/install` - Install from registry
|
|
- `POST /api/v3/plugins/install-from-url` - Install from GitHub URL
|
|
- `POST /api/v3/plugins/uninstall` - Uninstall plugin
|
|
- `POST /api/v3/plugins/update` - Update plugin
|
|
|
|
### Plugin Store
|
|
- `GET /api/v3/plugins/store/list` - List available registry plugins
|
|
- `GET /api/v3/plugins/store/github-status` - GitHub authentication status
|
|
- `POST /api/v3/plugins/store/refresh` - Refresh registry from GitHub
|
|
|
|
### Real-time Streams (SSE)
|
|
SSE stream endpoints are defined directly on the Flask app in `app.py`
|
|
(`stream_stats`, `stream_display`, `stream_logs`, followed by their CSRF
|
|
exemption and rate-limit hookup), not on the api_v3 blueprint:
|
|
- `GET /api/v3/stream/stats` - System statistics stream
|
|
- `GET /api/v3/stream/display` - Display preview stream
|
|
- `GET /api/v3/stream/logs` - Service logs stream
|
|
|
|
## Development
|
|
|
|
When making changes to the web interface:
|
|
|
|
1. Edit files in this directory
|
|
2. Test changes by running `python3 web_interface/start.py`
|
|
3. 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
|
|
|