From a62d4529fb66c75e57e5f3452f118d009219e102 Mon Sep 17 00:00:00 2001 From: Chuck Date: Tue, 7 Apr 2026 09:39:46 -0400 Subject: [PATCH] docs: flag aspirational/regressed features in plugin docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These docs describe features that exist as documented in the doc but either never wired up or regressed when v3 shipped. Each gets a clear status banner so plugin authors don't waste time chasing features that don't actually work. FONT_MANAGER.md - The "For Plugin Developers / Plugin Font Registration" section documents adding a "fonts" block to manifest.json that gets registered via FontManager.register_plugin_fonts(). The method exists at src/font_manager.py:150 but is **never called from anywhere** in the codebase (verified: zero callers). A plugin shipping a manifest "fonts" block has its fonts silently ignored. Added a status warning and a note about how to actually ship plugin fonts (regular files in the plugin dir, loaded directly). PLUGIN_IMPLEMENTATION_SUMMARY.md - Added a top-level status banner. - Architecture diagram referenced src/plugin_system/registry_manager.py (which doesn't exist) and listed plugins/ as the install location. Replaced with the real file list (plugin_loader, schema_manager, health_monitor, operation_queue, state_manager) and pointed at plugin-repos/ as the default install location. - "Dependency Management: Virtual Environments" — verified there's no per-plugin venv. Removed the bullet and added a note that plugin Python deps install into the system Python environment, with no conflict resolution. - "Permission System: File Access Control / Network Access / Resource Limits / CPU and memory constraints" — none of these exist. There's a resource_monitor.py and health_monitor.py for metrics/warnings, but no hard caps or sandboxing. Replaced the section with what's actually implemented and a clear note that plugins run in the same process with full file/network access. PLUGIN_CUSTOM_ICONS.md and PLUGIN_CUSTOM_ICONS_FEATURE.md - The custom-icon feature was implemented in the v2 web interface via a getPluginIcon() helper in templates/index_v2.html that read the manifest "icon" field. When the v3 web interface was built, that helper wasn't ported. Verified in web_interface/templates/v3/base.html:515 and :774, plugin tab icons are hardcoded to `fas fa-puzzle-piece`. The "icon" field in plugin manifests is currently silently ignored (verified with grep across web_interface/ and src/plugin_system/ — zero non-action- related reads of plugin.icon or manifest.icon). - Added a status banner to both docs noting the regression so plugin authors don't think their custom icons are broken in their own plugin code. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/FONT_MANAGER.md | 16 ++++++++- docs/PLUGIN_CUSTOM_ICONS.md | 11 +++++++ docs/PLUGIN_CUSTOM_ICONS_FEATURE.md | 11 ++++++- docs/PLUGIN_IMPLEMENTATION_SUMMARY.md | 47 +++++++++++++++++++++------ 4 files changed, 73 insertions(+), 12 deletions(-) diff --git a/docs/FONT_MANAGER.md b/docs/FONT_MANAGER.md index 63b1a132..10527d4e 100644 --- a/docs/FONT_MANAGER.md +++ b/docs/FONT_MANAGER.md @@ -138,7 +138,21 @@ font = self.font_manager.resolve_font( ## For Plugin Developers -### Plugin Font Registration +> ⚠️ **Status**: the plugin-font registration described below is +> implemented in `src/font_manager.py:150` (`register_plugin_fonts()`) +> but is **not currently wired into the plugin loader**. Adding a +> `"fonts"` block to your plugin's `manifest.json` will silently have +> no effect — the FontManager method exists but nothing calls it. +> +> Until that's connected, plugin authors should ship custom fonts as +> regular files inside the plugin directory (e.g., `assets/myfont.ttf`) +> and reference them by relative path from the plugin's `manager.py` +> via `display_manager.font_manager.resolve_font(...)` or by loading +> with PIL directly. The user-facing font override system in the +> **Fonts** tab still works for any element that's been registered via +> `register_manager_font()`. + +### Plugin Font Registration (planned) In your plugin's `manifest.json`: diff --git a/docs/PLUGIN_CUSTOM_ICONS.md b/docs/PLUGIN_CUSTOM_ICONS.md index da9db63c..e6fad128 100644 --- a/docs/PLUGIN_CUSTOM_ICONS.md +++ b/docs/PLUGIN_CUSTOM_ICONS.md @@ -1,5 +1,16 @@ # Plugin Custom Icons Guide +> ⚠️ **Status:** the `icon` field in `manifest.json` is currently +> **not honored by the v3 web interface**. Plugin tab icons are +> hardcoded to `fas fa-puzzle-piece` in +> `web_interface/templates/v3/base.html:515` and `:774`. The icon +> field was originally read by a `getPluginIcon()` helper in the v2 +> templates, but that helper wasn't ported to v3. Setting `icon` in a +> manifest is harmless (it's just ignored) so plugin authors can leave +> it in place for when this regression is fixed. +> +> Tracking issue: see the LEDMatrix repo for the open ticket. + ## Overview Plugins can specify custom icons that appear next to their name in the web interface tabs. This makes your plugin instantly recognizable and adds visual polish to the UI. diff --git a/docs/PLUGIN_CUSTOM_ICONS_FEATURE.md b/docs/PLUGIN_CUSTOM_ICONS_FEATURE.md index 8e84a099..ea78d0f3 100644 --- a/docs/PLUGIN_CUSTOM_ICONS_FEATURE.md +++ b/docs/PLUGIN_CUSTOM_ICONS_FEATURE.md @@ -1,4 +1,13 @@ -# ✅ Plugin Custom Icons Feature - Complete +# Plugin Custom Icons Feature + +> ⚠️ **Status:** this doc describes the v2 web interface +> implementation of plugin custom icons. The feature **regressed when +> the v3 web interface was built** — the `getPluginIcon()` helper +> referenced below lived in `templates/index_v2.html` (which is now +> archived) and was not ported to the v3 templates. Plugin tab icons +> in v3 are hardcoded to `fas fa-puzzle-piece` +> (`web_interface/templates/v3/base.html:515` and `:774`). The +> `icon` field in `manifest.json` is currently silently ignored. ## What Was Implemented diff --git a/docs/PLUGIN_IMPLEMENTATION_SUMMARY.md b/docs/PLUGIN_IMPLEMENTATION_SUMMARY.md index e53e6d86..3e5d866a 100644 --- a/docs/PLUGIN_IMPLEMENTATION_SUMMARY.md +++ b/docs/PLUGIN_IMPLEMENTATION_SUMMARY.md @@ -1,5 +1,11 @@ # LEDMatrix Plugin System - Implementation Summary +> **Status note:** this is a high-level summary written during the +> initial plugin system rollout. Most of it is accurate, but a few +> sections describe features that are aspirational or only partially +> implemented (per-plugin virtual envs, resource limits, registry +> manager). Drift from current reality is called out inline. + This document provides a comprehensive overview of the plugin architecture implementation, consolidating details from multiple plugin-related implementation summaries. ## Executive Summary @@ -14,16 +20,25 @@ The LEDMatrix plugin system transforms the project into a modular, extensible pl LEDMatrix/ ├── src/plugin_system/ │ ├── base_plugin.py # Plugin interface contract +│ ├── plugin_loader.py # Discovery + dynamic import │ ├── plugin_manager.py # Lifecycle management -│ ├── store_manager.py # GitHub integration -│ └── registry_manager.py # Plugin discovery -├── plugins/ # User-installed plugins +│ ├── store_manager.py # GitHub install / store integration +│ ├── schema_manager.py # Config schema validation +│ ├── health_monitor.py # Plugin health metrics +│ ├── operation_queue.py # Async install/update operations +│ └── state_manager.py # Persistent plugin state +├── plugin-repos/ # Default plugin install location │ ├── football-scoreboard/ │ ├── ledmatrix-music/ │ └── ledmatrix-stocks/ └── config/config.json # Plugin configurations ``` +> Earlier drafts of this doc referenced `registry_manager.py`. It was +> never created — discovery happens in `plugin_loader.py`. The earlier +> default plugin location of `plugins/` has been replaced with +> `plugin-repos/` (see `config/config.template.json:130`). + ### Key Design Decisions ✅ **Gradual Migration**: Plugin system added alongside existing managers @@ -77,14 +92,26 @@ LEDMatrix/ - **Fallback System**: Default icons when custom ones unavailable #### Dependency Management -- **Requirements.txt**: Per-plugin dependencies -- **Virtual Environments**: Isolated dependency management -- **Version Pinning**: Explicit version constraints +- **Requirements.txt**: Per-plugin dependencies, installed system-wide + via pip on first plugin load +- **Version Pinning**: Standard pip version constraints in + `requirements.txt` -#### Permission System -- **File Access Control**: Configurable file system permissions -- **Network Access**: Controlled API access -- **Resource Limits**: CPU and memory constraints +> Earlier plans called for per-plugin virtual environments. That isn't +> implemented — plugin Python deps install into the system Python +> environment (or whatever environment the LEDMatrix service is using). +> Conflicting versions across plugins are not auto-resolved. + +#### Health monitoring +- **Resource Monitor** (`src/plugin_system/resource_monitor.py`): tracks + CPU and memory metrics per plugin and warns about slow plugins +- **Health Monitor** (`src/plugin_system/health_monitor.py`): tracks + plugin failures and last-success timestamps + +> Earlier plans called for hard CPU/memory limits and a sandboxed +> permission system. Neither is implemented. Plugins run in the same +> process as the display loop with full file-system and network access +> — review third-party plugin code before installing. ## Plugin Development