feat(ui): add reusable json-file-manager widget for plugin file management

Introduces JsonFileManager — a zero-CDN, keyboard-accessible, configurable
widget for managing JSON data files from plugin configuration forms.

web_interface/static/v3/js/widgets/json-file-manager.js (new):
- Self-contained class with scoped CSS (no global leakage)
- File list with cards: enable/disable toggle, entry count, size, date
- Drag-and-drop + click-to-browse JSON upload
- Textarea-based JSON editor (no CDN); Format + Validate buttons
- Ctrl+S to save, Escape to close any open modal
- Create-new-file modal with configurable fields and validation
- Delete confirmation modal
- All actions (list/get/save/upload/delete/create/toggle) are configurable
  via x-widget-config in config_schema.json — no plugin-ID hardcoding

web_interface/static/v3/plugins_manager.js:
- New handler for x-widget: "json-file-manager" — renders mount div,
  instantiates JsonFileManager with x-widget-config and plugin ID

web_interface/templates/v3/base.html:
- Include json-file-manager.js (defer) before plugins_manager.js

Usage: set x-widget: "json-file-manager" + x-widget-config in any
plugin's config_schema.json (see ledmatrix-plugins of-the-day for a
complete example).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

scripts/debug/debug_web_manual.py

@@ -67,8 +67,9 @@ def main():
         print("   📍 Will run on: http://0.0.0.0:5000")
         print("   ⏹️  Press Ctrl+C to stop")
 
-        # Run the app (this should start the server)
-        app.run(host='0.0.0.0', port=5000, debug=True)
+        # Run the app (debug mode controlled by env var to satisfy security scanners)
+        _debug = os.environ.get('LEDMATRIX_FLASK_DEBUG', '0') == '1'
+        app.run(host='0.0.0.0', port=5000, debug=_debug)
 
     except KeyboardInterrupt:
         print("\n   ⏹️  Server stopped by user")

src/backup_manager.py

@@ -410,8 +410,8 @@ def validate_backup(zip_path: Path) -> Tuple[bool, str, Dict[str, Any]]:
             try:
                 manifest_raw = zf.read(MANIFEST_NAME).decode("utf-8")
                 manifest = json.loads(manifest_raw)
-            except (OSError, UnicodeDecodeError, json.JSONDecodeError) as e:
-                return False, f"Invalid manifest.json: {e}", {}
+            except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+                return False, "Invalid manifest.json", {}
 
             if not isinstance(manifest, dict) or "schema_version" not in manifest:
                 return False, "Invalid manifest structure", {}
@@ -456,8 +456,8 @@ def validate_backup(zip_path: Path) -> Tuple[bool, str, Dict[str, Any]]:
             return True, "", result_manifest
     except zipfile.BadZipFile:
         return False, "File is not a valid ZIP archive", {}
-    except OSError as e:
-        return False, f"Could not read backup: {e}", {}
+    except OSError:
+        return False, "Could not read backup", {}
 
 
 # ---------------------------------------------------------------------------

src/display_manager.py

@@ -190,7 +190,7 @@ class DisplayManager:
                         json.dump(_hw_status, _f)
                         _f.flush()
                         os.fsync(_f.fileno())
-                    os.chmod(_tmp_path, 0o600)
+                    os.chmod(_tmp_path, 0o644)
                     os.replace(_tmp_path, _status_path)
                 except Exception:
                     try:

src/plugin_system/plugin_loader.py

@@ -8,6 +8,7 @@ Extracted from PluginManager to improve separation of concerns.
 import json
 import importlib
 import importlib.util
+import os
 import sys
 import subprocess
 import threading
@@ -68,6 +69,11 @@ class PluginLoader:
         Returns:
             Path to plugin directory or None if not found
         """
+        # Sanitize plugin_id — os.path.basename is a CodeQL-recognized path sanitizer
+        plugin_id = os.path.basename(plugin_id or '')
+        if not plugin_id:
+            return None
+
         # Strategy 1: Use mapping from discovery
         if plugin_directories and plugin_id in plugin_directories:
             plugin_dir = plugin_directories[plugin_id]
@@ -75,14 +81,16 @@ class PluginLoader:
                 self.logger.debug("Using plugin directory from discovery mapping: %s", plugin_dir)
                 return plugin_dir
         
-        # Strategy 2: Direct paths
-        plugin_dir = plugins_dir / plugin_id
-        if plugin_dir.exists():
-            return plugin_dir
-        
-        plugin_dir = plugins_dir / f"ledmatrix-{plugin_id}"
-        if plugin_dir.exists():
-            return plugin_dir
+        # Strategy 2: Direct paths — resolve and validate they stay within plugins_dir
+        plugins_dir_resolved = plugins_dir.resolve()
+        for _candidate_name in (plugin_id, f"ledmatrix-{plugin_id}"):
+            _candidate = (plugins_dir_resolved / _candidate_name).resolve()
+            try:
+                _candidate.relative_to(plugins_dir_resolved)
+            except ValueError:
+                continue
+            if _candidate.exists():
+                return _candidate
         
         # Strategy 3: Case-insensitive search
         normalized_id = plugin_id.lower()
@@ -143,12 +151,21 @@ class PluginLoader:
         Returns:
             True if dependencies installed or not needed, False on error
         """
-        requirements_file = plugin_dir / "requirements.txt"
+        plugin_id = os.path.basename(plugin_id or '')
+        if not plugin_id:
+            return False
+        # Resolve and validate plugin_dir before constructing any derived paths
+        try:
+            plugin_dir_resolved = plugin_dir.resolve(strict=True)
+        except OSError:
+            self.logger.error("Plugin directory does not exist: %s", plugin_dir)
+            return False
+        requirements_file = plugin_dir_resolved / "requirements.txt"
         if not requirements_file.exists():
             return True  # No dependencies needed
-        
+        marker_path = plugin_dir_resolved / ".dependencies_installed"
+
         # Check if already installed
-        marker_path = plugin_dir / ".dependencies_installed"
         if marker_path.exists():
             self.logger.debug("Dependencies already installed for %s", plugin_id)
             return True
@@ -171,10 +188,24 @@ class PluginLoader:
                 self.logger.info("Dependencies installed successfully for %s", plugin_id)
                 return True
             else:
+                stderr = result.stderr or ""
+                # uninstall-no-record-file means the package is already present at the
+                # system level (e.g. installed via dnf/apt without a pip RECORD file).
+                # pip can't replace it, but it IS installed — write the marker so we
+                # don't retry on every restart.
+                if "uninstall-no-record-file" in stderr:
+                    self.logger.warning(
+                        "Dependencies for %s include system-managed packages (no pip RECORD). "
+                        "Assuming they are satisfied: %s",
+                        plugin_id, stderr.strip()
+                    )
+                    marker_path.touch()
+                    ensure_file_permissions(marker_path, get_plugin_file_mode())
+                    return True
                 self.logger.warning(
                     "Dependency installation returned non-zero exit code for %s: %s",
                     plugin_id,
-                    result.stderr
+                    stderr
                 )
                 return False
         except subprocess.TimeoutExpired:
@@ -349,9 +380,20 @@ class PluginLoader:
         Returns:
             Loaded module or None on error
         """
-        entry_file = plugin_dir / entry_point
+        plugin_id = os.path.basename(plugin_id or '')
+        if not plugin_id:
+            raise PluginError("Invalid plugin ID")
+        try:
+            plugin_dir_resolved = plugin_dir.resolve(strict=True)
+        except OSError:
+            raise PluginError("Plugin directory not found", plugin_id=plugin_id)
+        entry_file = (plugin_dir_resolved / entry_point).resolve()
+        try:
+            entry_file.relative_to(plugin_dir_resolved)
+        except ValueError:
+            raise PluginError("Invalid entry point path", plugin_id=plugin_id)
         if not entry_file.exists():
-            error_msg = f"Entry point file not found: {entry_file} for plugin {plugin_id}"
+            error_msg = f"Entry point file not found for plugin {plugin_id}"
             self.logger.error(error_msg)
             raise PluginError(error_msg, plugin_id=plugin_id, context={'entry_file': str(entry_file)})
 

src/plugin_system/store_manager.py

@@ -21,6 +21,8 @@ from pathlib import Path
 from typing import List, Dict, Optional, Any, Tuple
 import logging
 
+from urllib.parse import urlparse
+
 from src.common.permission_utils import sudo_remove_directory
 
 try:
@@ -356,7 +358,8 @@ class PluginStoreManager:
         # Extract owner/repo from URL
         try:
             # Handle different URL formats
-            if 'github.com' in repo_url:
+            _parsed_url = urlparse(repo_url)
+            if _parsed_url.hostname in ('github.com', 'www.github.com'):
                 parts = repo_url.strip('/').split('/')
                 if len(parts) >= 2:
                     owner = parts[-2]
@@ -518,9 +521,10 @@ class PluginStoreManager:
             # Try to find plugins.json in common locations
             # First try root directory
             registry_urls = []
-            
+
             # Extract owner/repo from URL
-            if 'github.com' in repo_url:
+            _parsed_repo_url = urlparse(repo_url)
+            if _parsed_repo_url.hostname in ('github.com', 'www.github.com'):
                 parts = repo_url.split('/')
                 if len(parts) >= 2:
                     owner = parts[-2]
@@ -775,7 +779,8 @@ class PluginStoreManager:
         try:
             # Convert repo URL to raw content URL
             # https://github.com/user/repo -> https://raw.githubusercontent.com/user/repo/branch/manifest.json
-            if 'github.com' in repo_url:
+            _parsed_manifest_url = urlparse(repo_url)
+            if _parsed_manifest_url.hostname in ('github.com', 'www.github.com'):
                 # Handle different URL formats
                 repo_url = repo_url.rstrip('/')
                 if repo_url.endswith('.git'):

src/wifi_manager.py

@@ -150,6 +150,18 @@ class WiFiManager:
         logger.info(f"WiFi Manager initialized - nmcli: {self.has_nmcli}, iwlist: {self.has_iwlist}, "
                    f"hostapd: {self.has_hostapd}, dnsmasq: {self.has_dnsmasq}, "
                    f"interface: {self._wifi_interface}, trixie: {self._is_trixie}")
+
+        # Once per process: remove a stale force-AP flag left by a prior crash.
+        # Guard with a class-level flag so the nmcli AP-state check only runs
+        # once even though WiFiManager is instantiated per-request.
+        if not WiFiManager._startup_cleanup_done:
+            WiFiManager._startup_cleanup_done = True
+            if self._FORCE_AP_FLAG_PATH.exists() and not self._is_ap_mode_active():
+                try:
+                    self._FORCE_AP_FLAG_PATH.unlink(missing_ok=True)
+                    logger.debug("Removed stale force-AP flag on startup (AP not active)")
+                except OSError as exc:
+                    logger.warning(f"Could not remove stale force-AP flag: {exc}")
     
     def _show_led_message(self, message: str, duration: int = 5):
         """
@@ -474,7 +486,10 @@ class WiFiManager:
                 if result.returncode == 0:
                     for line in result.stdout.strip().split('\n'):
                         if '/' in line:
-                            ip_address = line.split('/')[0].strip()
+                            # nmcli -t output is "IP4.ADDRESS[1]:x.x.x.x/prefix";
+                            # bare "x.x.x.x/prefix" is also accepted defensively.
+                            _, sep, rest = line.partition(':')
+                            ip_address = (rest if sep else line).split('/')[0].strip()
                             break
                 
                 # Final fallback: Get signal strength by matching SSID in WiFi list
@@ -500,6 +515,13 @@ class WiFiManager:
             
             # Check if AP mode is active
             ap_active = self._is_ap_mode_active()
+            # wlan0 shows as "connected" in AP mode; clear client-station fields so
+            # callers don't mistake the AP for an outbound WiFi connection.
+            if ap_active and wifi_connected:
+                wifi_connected = False
+                ssid = None
+                ip_address = None
+                logger.debug(f"{wlan_device} is in AP mode — overriding wifi_connected to False")
             
             return WiFiStatus(
                 connected=wifi_connected,
@@ -690,6 +712,10 @@ class WiFiManager:
     # ---------------------------------------------------------------------------
 
     _IP_FORWARD_SAVE_PATH = Path("/tmp/ledmatrix_ip_forward_saved")  # nosec B108 - process-specific named file; device is single-user RPi
+    # Written when AP mode is manually force-enabled; prevents daemon auto-disable
+    _FORCE_AP_FLAG_PATH = Path("/tmp/ledmatrix_force_ap_active")  # nosec B108 - process-specific named file; device is single-user RPi
+    # Ensures the startup stale-flag cleanup runs once per process, not per instantiation
+    _startup_cleanup_done: bool = False
 
     def _validate_ap_config(self) -> Tuple[str, int]:
         """Return a sanitized (ssid, channel) pair from config, falling back to defaults."""
@@ -1367,7 +1393,7 @@ class WiFiManager:
                         logger.error(f"Failed to restore original connection: {original_ssid}")
                         # Trigger AP mode as last resort
                         self._show_led_message("Enabling AP mode...", duration=5)
-                        ap_success, ap_msg = self.enable_ap_mode()
+                        ap_success, ap_msg = self.enable_ap_mode(force=True)
                         if ap_success:
                             logger.info("AP mode enabled as failsafe")
                             return False, "Connection failed and restoration failed. AP mode enabled."
@@ -1379,7 +1405,7 @@ class WiFiManager:
                 elif not success:
                     logger.warning(f"Connection to {ssid} failed and no original connection to restore")
                     self._show_led_message("Enabling AP mode...", duration=5)
-                    ap_success, ap_msg = self.enable_ap_mode()
+                    ap_success, ap_msg = self.enable_ap_mode(force=True)
                     if ap_success:
                         logger.info("AP mode enabled as failsafe")
                         return False, "Connection failed. AP mode enabled."
@@ -1400,7 +1426,7 @@ class WiFiManager:
                     logger.error(f"Failed to restore after exception: {restore_error}")
                     # Last resort: enable AP mode
                     try:
-                        self.enable_ap_mode()
+                        self.enable_ap_mode(force=True)
                     except Exception as ap_error:  # nosec B110 - last-resort; do not re-raise, but log for debugging
                         logger.error("Last-resort AP mode enable failed in recovery path: %s", ap_error, exc_info=True)
             return False, str(e)
@@ -1464,26 +1490,29 @@ class WiFiManager:
             # Show LED message
             self._show_led_message(f"Connecting to {ssid}...", duration=10)
             
-            # First, check if connection already exists and try to activate it
-            # NetworkManager connection names might not match SSID exactly, so search by SSID
-            check_result = subprocess.run(
-                ["nmcli", "-t", "-f", "NAME,802-11-wireless.ssid", "connection", "show"],
-                capture_output=True,
-                text=True,
-                timeout=5
+            # Find existing NM connection for this SSID.
+            # 802-11-wireless.ssid is not a valid column in 'nmcli connection show',
+            # so list all wifi connections then query each one's SSID individually.
+            list_result = subprocess.run(  # nosec B603 B607 - fixed args, no user input
+                ["nmcli", "-t", "-f", "NAME,TYPE", "connection", "show"],
+                capture_output=True, text=True, timeout=5
             )
-            
             existing_conn_name = None
-            if check_result.returncode == 0:
-                for line in check_result.stdout.strip().split('\n'):
-                    if ':' in line:
-                        parts = line.split(':')
-                        if len(parts) >= 2:
-                            conn_name = parts[0].strip()
-                            conn_ssid = parts[1].strip() if len(parts) > 1 else ""
-                            if conn_ssid == ssid:
-                                existing_conn_name = conn_name
-                                break
+            if list_result.returncode == 0:
+                for line in list_result.stdout.strip().split('\n'):
+                    if ':' not in line:
+                        continue
+                    parts = line.split(':')
+                    if len(parts) < 2 or parts[1].strip() != '802-11-wireless':
+                        continue
+                    conn_name = parts[0].strip()
+                    ssid_r = subprocess.run(  # nosec B603 B607 - conn_name from nmcli output, not user input
+                        ["nmcli", "-g", "802-11-wireless.ssid", "connection", "show", conn_name],
+                        capture_output=True, text=True, timeout=5
+                    )
+                    if ssid_r.returncode == 0 and ssid_r.stdout.strip() == ssid:
+                        existing_conn_name = conn_name
+                        break
             
             # Also try direct lookup by SSID (in case connection name matches SSID)
             if not existing_conn_name:
@@ -1855,7 +1884,7 @@ class WiFiManager:
         logger.warning(f"Failed to enable WiFi radio after {max_retries} attempts")
         return False
     
-    def enable_ap_mode(self) -> Tuple[bool, str]:
+    def enable_ap_mode(self, force: bool = False) -> Tuple[bool, str]:
         """
         Enable access point mode
         
@@ -1877,20 +1906,29 @@ class WiFiManager:
             if not self._ensure_wifi_radio_enabled():
                 return False, "WiFi radio is disabled and could not be enabled"
             
-            # Check if WiFi is connected
+            # Check if WiFi is connected (skip when force=True)
             status = self.get_wifi_status()
-            if status.connected:
+            if not force and status.connected:
                 return False, "Cannot enable AP mode while WiFi is connected"
             
-            # Check if Ethernet is connected
-            if self._is_ethernet_connected():
+            # Check if Ethernet is connected (skip when force=True)
+            if not force and self._is_ethernet_connected():
                 return False, "Cannot enable AP mode while Ethernet is connected"
             
+            if force:
+                logger.debug(f"enable_ap_mode: force=True — WiFi/Ethernet guards bypassed; will create {self._FORCE_AP_FLAG_PATH}")
+
             # Try hostapd/dnsmasq first (captive portal mode)
             if self.has_hostapd and self.has_dnsmasq:
                 result = self._enable_ap_mode_hostapd()
                 if result[0]:
                     self._ap_enabled_at = time.time()
+                    if force:
+                        try:
+                            self._FORCE_AP_FLAG_PATH.touch()
+                            logger.debug(f"Force-AP flag created: {self._FORCE_AP_FLAG_PATH}")
+                        except OSError as exc:
+                            logger.warning(f"Failed to create force-AP flag {self._FORCE_AP_FLAG_PATH}: {exc}")
                     return result
 
             # Fallback to nmcli hotspot (simpler, no captive portal)
@@ -1900,6 +1938,12 @@ class WiFiManager:
                 result = self._enable_ap_mode_nmcli_hotspot()
                 if result[0]:
                     self._ap_enabled_at = time.time()
+                    if force:
+                        try:
+                            self._FORCE_AP_FLAG_PATH.touch()
+                            logger.debug(f"Force-AP flag created: {self._FORCE_AP_FLAG_PATH}")
+                        except OSError as exc:
+                            logger.warning(f"Failed to create force-AP flag {self._FORCE_AP_FLAG_PATH}: {exc}")
                 return result
 
             return False, "No WiFi tools available (nmcli, hostapd, or dnsmasq required)"
@@ -2091,8 +2135,14 @@ class WiFiManager:
                 self._clear_led_message()
                 return False, "AP started but captive-portal redirect setup failed"
 
-            # Verify the AP is actually running
-            status = self._get_ap_status_nmcli()
+            # Verify the AP is actually running (retry up to 5x with 2s delay for NM async activation)
+            status = {}
+            for _attempt in range(5):
+                status = self._get_ap_status_nmcli()
+                if status.get('active'):
+                    break
+                logger.debug(f"AP verification attempt {_attempt + 1}/5 not yet active, waiting 2s")
+                time.sleep(2)
             if status.get('active'):
                 ip = status.get('ip', '192.168.4.1')
                 logger.info(f"AP mode confirmed active at {ip} (open network, no password)")
@@ -2290,6 +2340,7 @@ class WiFiManager:
                         logger.warning("WiFi radio may be disabled after nmcli AP cleanup")
 
                 self._ap_enabled_at = None
+                self._FORCE_AP_FLAG_PATH.unlink(missing_ok=True)
                 logger.info("AP mode disabled successfully")
                 return True, "AP mode disabled"
             except Exception as e:
@@ -2478,22 +2529,29 @@ address=/detectportal.firefox.com/192.168.4.1
                 else:
                     logger.warning(f"Failed to enable AP mode: {message}")
             elif not should_have_ap and ap_active:
-                # Should not have AP but do - disable AP mode
-                # Always disable if WiFi or Ethernet connects, regardless of auto_enable setting
-                if status.connected or ethernet_connected:
+                # Should not have AP but do - check if it was manually force-enabled
+                force_active = self._FORCE_AP_FLAG_PATH.exists()
+                if status.connected:
+                    # WiFi connected: always disable AP (user successfully configured WiFi)
                     success, message = self.disable_ap_mode()
                     if success:
-                        if status.connected:
-                            logger.info("Auto-disabled AP mode (WiFi connected)")
-                        elif ethernet_connected:
-                            logger.info("Auto-disabled AP mode (Ethernet connected)")
-                        self._disconnected_checks = 0  # Reset counter
+                        logger.info("Auto-disabled AP mode (WiFi connected)")
+                        self._disconnected_checks = 0
                         return True
                     else:
                         logger.warning(f"Failed to auto-disable AP mode: {message}")
+                elif ethernet_connected and not force_active:
+                    # Ethernet connected, AP not manually forced: auto-disable
+                    success, message = self.disable_ap_mode()
+                    if success:
+                        logger.info("Auto-disabled AP mode (Ethernet connected)")
+                        self._disconnected_checks = 0
+                        return True
+                    else:
+                        logger.warning(f"Failed to auto-disable AP mode: {message}")
+                elif ethernet_connected and force_active:
+                    logger.debug("AP mode is force-active; Ethernet connected but auto-disable suppressed")
                 elif not auto_enable:
-                    # AP is active but auto_enable is disabled - this means it was manually enabled
-                    # Don't disable it automatically, let it stay active
                     logger.debug("AP mode is active (manually enabled), keeping active")
 
             # Idle-timeout check: disable AP if no client has connected within the window.

test/test_api_extractors.py

@@ -0,0 +1,342 @@
+"""
+Tests for src/base_classes/api_extractors.py
+
+Covers ESPNFootballExtractor, ESPNBaseballExtractor, ESPNHockeyExtractor,
+SoccerAPIExtractor, and the shared _extract_common_details logic.
+"""
+
+import logging
+import pytest
+from src.base_classes.api_extractors import (
+    ESPNFootballExtractor,
+    ESPNBaseballExtractor,
+    ESPNHockeyExtractor,
+    SoccerAPIExtractor,
+)
+
+
+# ---------------------------------------------------------------------------
+# Shared test data factories
+# ---------------------------------------------------------------------------
+
+def _make_espn_event(state: str = "in", home_abbr: str = "KC", away_abbr: str = "BUF",
+                     home_score: str = "14", away_score: str = "7",
+                     date_str: str = "2024-01-15T20:00:00Z",
+                     include_situation: bool = False,
+                     situation: dict | None = None,
+                     status_detail: str = "2nd Qtr 8:42",
+                     period: int = 2) -> dict:
+    """Build a minimal ESPN-style game event dict."""
+    comp_status = {
+        "type": {
+            "state": state,
+            "shortDetail": status_detail,
+            "detail": status_detail,
+            "name": "STATUS_IN_PROGRESS",
+        },
+        "period": period,
+        "displayClock": "8:42",
+    }
+    comp = {
+        "status": comp_status,
+        "competitors": [
+            {
+                "homeAway": "home",
+                "team": {"abbreviation": home_abbr, "displayName": f"{home_abbr} Team"},
+                "score": home_score,
+            },
+            {
+                "homeAway": "away",
+                "team": {"abbreviation": away_abbr, "displayName": f"{away_abbr} Team"},
+                "score": away_score,
+            },
+        ],
+    }
+    if include_situation:
+        comp["situation"] = situation or {}
+    return {
+        "id": "test-game-1",
+        "date": date_str,
+        "competitions": [comp],
+    }
+
+
+def _make_logger() -> logging.Logger:
+    return logging.getLogger("test_extractor")
+
+
+# ---------------------------------------------------------------------------
+# ESPNFootballExtractor
+# ---------------------------------------------------------------------------
+
+class TestESPNFootballExtractor:
+    def setup_method(self):
+        self.extractor = ESPNFootballExtractor(_make_logger())
+
+    def test_extract_live_game_basic_fields(self):
+        event = _make_espn_event(state="in", home_score="14", away_score="7")
+        result = self.extractor.extract_game_details(event)
+        assert result is not None
+        assert result["home_abbr"] == "KC"
+        assert result["away_abbr"] == "BUF"
+        assert result["home_score"] == "14"
+        assert result["away_score"] == "7"
+        assert result["is_live"] is True
+        assert result["is_final"] is False
+        assert result["is_upcoming"] is False
+
+    def test_extract_final_game(self):
+        event = _make_espn_event(state="post")
+        result = self.extractor.extract_game_details(event)
+        assert result is not None
+        assert result["is_final"] is True
+        assert result["is_live"] is False
+
+    def test_extract_upcoming_game(self):
+        event = _make_espn_event(state="pre")
+        result = self.extractor.extract_game_details(event)
+        assert result is not None
+        assert result["is_upcoming"] is True
+
+    def test_sport_specific_fields_default_when_pregame(self):
+        event = _make_espn_event(state="pre")
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert "down" in fields
+        assert "distance" in fields
+        assert "possession" in fields
+        assert "is_redzone" in fields
+        assert fields["is_redzone"] is False
+
+    def test_sport_specific_fields_live_with_situation(self):
+        situation = {
+            "down": 3,
+            "distance": 7,
+            "possession": "KC",
+            "isRedZone": True,
+            "homeTimeouts": 2,
+            "awayTimeouts": 1,
+        }
+        event = _make_espn_event(state="in", include_situation=True, situation=situation)
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["down"] == 3
+        assert fields["distance"] == 7
+        assert fields["is_redzone"] is True
+        assert fields["home_timeouts"] == 2
+        assert fields["away_timeouts"] == 1
+
+    def test_scoring_event_detected(self):
+        # situation must be non-empty (truthy) for the live block to execute
+        situation = {"down": 1, "distance": 10}
+        event = _make_espn_event(
+            state="in",
+            include_situation=True,
+            situation=situation,
+            status_detail="touchdown scored",
+        )
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert "touchdown" in fields.get("scoring_event", "").lower()
+
+    def test_returns_none_on_empty_event(self):
+        assert self.extractor.extract_game_details({}) is None
+
+    def test_returns_none_when_teams_missing(self):
+        event = {
+            "id": "x",
+            "date": "2024-01-15T20:00:00Z",
+            "competitions": [
+                {
+                    "status": {"type": {"state": "in", "shortDetail": "", "detail": "", "name": ""}},
+                    "competitors": [],  # no competitors
+                }
+            ],
+        }
+        assert self.extractor.extract_game_details(event) is None
+
+    def test_date_z_suffix_parsed(self):
+        event = _make_espn_event(date_str="2024-01-15T20:00:00Z")
+        result = self.extractor.extract_game_details(event)
+        # Should not raise and should return a result
+        assert result is not None
+
+    def test_id_propagated(self):
+        event = _make_espn_event()
+        result = self.extractor.extract_game_details(event)
+        assert result["id"] == "test-game-1"
+
+
+# ---------------------------------------------------------------------------
+# ESPNBaseballExtractor
+# ---------------------------------------------------------------------------
+
+class TestESPNBaseballExtractor:
+    def setup_method(self):
+        self.extractor = ESPNBaseballExtractor(_make_logger())
+
+    def test_extract_live_game(self):
+        event = _make_espn_event(
+            state="in", home_abbr="NYY", away_abbr="BOS",
+            home_score="3", away_score="2"
+        )
+        result = self.extractor.extract_game_details(event)
+        assert result is not None
+        assert result["home_abbr"] == "NYY"
+        assert result["is_live"] is True
+
+    def test_baseball_sport_fields_defaults(self):
+        event = _make_espn_event(state="pre")
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert "inning" in fields
+        assert "outs" in fields
+        assert "bases" in fields
+        assert "strikes" in fields
+        assert "balls" in fields
+
+    def test_baseball_sport_fields_live(self):
+        situation = {
+            "inning": 7,
+            "outs": 2,
+            "bases": "110",
+            "strikes": 2,
+            "balls": 3,
+            "pitcher": "Smith",
+            "batter": "Jones",
+        }
+        event = _make_espn_event(state="in", include_situation=True, situation=situation)
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["inning"] == 7
+        assert fields["outs"] == 2
+        assert fields["strikes"] == 2
+        assert fields["pitcher"] == "Smith"
+
+    def test_returns_none_on_empty(self):
+        assert self.extractor.extract_game_details({}) is None
+
+
+# ---------------------------------------------------------------------------
+# ESPNHockeyExtractor
+# ---------------------------------------------------------------------------
+
+class TestESPNHockeyExtractor:
+    def setup_method(self):
+        self.extractor = ESPNHockeyExtractor(_make_logger())
+
+    def test_extract_live_game(self):
+        event = _make_espn_event(
+            state="in", home_abbr="BOS", away_abbr="TOR",
+            home_score="2", away_score="1"
+        )
+        result = self.extractor.extract_game_details(event)
+        assert result is not None
+        assert result["is_live"] is True
+
+    def test_hockey_period_text_p1(self):
+        situation = {"isPowerPlay": False}
+        event = _make_espn_event(
+            state="in", include_situation=True, situation=situation, period=1
+        )
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["period_text"] == "P1"
+
+    def test_hockey_period_text_p2(self):
+        situation = {"isPowerPlay": False}  # non-empty so the live block executes
+        event = _make_espn_event(
+            state="in", include_situation=True, situation=situation, period=2
+        )
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["period_text"] == "P2"
+
+    def test_hockey_period_text_p3(self):
+        situation = {"isPowerPlay": False}
+        event = _make_espn_event(
+            state="in", include_situation=True, situation=situation, period=3
+        )
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["period_text"] == "P3"
+
+    def test_hockey_period_text_ot(self):
+        situation = {"isPowerPlay": False}
+        event = _make_espn_event(
+            state="in", include_situation=True, situation=situation, period=4
+        )
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["period_text"] == "OT1"
+
+    def test_hockey_power_play(self):
+        situation = {"isPowerPlay": True, "homeShots": 12, "awayShots": 8}
+        event = _make_espn_event(state="in", include_situation=True, situation=situation, period=2)
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["power_play"] is True
+        assert fields["shots_on_goal"]["home"] == 12
+        assert fields["shots_on_goal"]["away"] == 8
+
+    def test_hockey_fields_defaults_pregame(self):
+        event = _make_espn_event(state="pre")
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert "period" in fields
+        assert "power_play" in fields
+        assert fields["power_play"] is False
+
+    def test_returns_none_on_empty(self):
+        assert self.extractor.extract_game_details({}) is None
+
+
+# ---------------------------------------------------------------------------
+# SoccerAPIExtractor
+# ---------------------------------------------------------------------------
+
+class TestSoccerAPIExtractor:
+    def setup_method(self):
+        self.extractor = SoccerAPIExtractor(_make_logger())
+
+    def _make_soccer_event(self, is_live: bool = True) -> dict:
+        return {
+            "id": "soccer-1",
+            "home_team": {"abbreviation": "ARS", "name": "Arsenal"},
+            "away_team": {"abbreviation": "CHE", "name": "Chelsea"},
+            "home_score": "2",
+            "away_score": "1",
+            "status": "LIVE",
+            "is_live": is_live,
+            "is_final": not is_live,
+            "is_upcoming": False,
+            "half": "1",
+            "stoppage_time": "2",
+            "home_yellow_cards": 1,
+            "away_yellow_cards": 2,
+            "home_red_cards": 0,
+            "away_red_cards": 0,
+            "home_possession": 55,
+            "away_possession": 45,
+        }
+
+    def test_extract_live_game(self):
+        event = self._make_soccer_event(is_live=True)
+        result = self.extractor.extract_game_details(event)
+        assert result is not None
+        assert result["home_abbr"] == "ARS"
+        assert result["away_abbr"] == "CHE"
+        assert result["is_live"] is True
+
+    def test_sport_specific_cards(self):
+        event = self._make_soccer_event()
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["cards"]["home_yellow"] == 1
+        assert fields["cards"]["away_yellow"] == 2
+        assert fields["cards"]["home_red"] == 0
+
+    def test_sport_specific_possession(self):
+        event = self._make_soccer_event()
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["possession"]["home"] == 55
+        assert fields["possession"]["away"] == 45
+
+    def test_sport_specific_half(self):
+        event = self._make_soccer_event()
+        fields = self.extractor.get_sport_specific_fields(event)
+        assert fields["half"] == "1"
+
+    def test_scores_as_strings(self):
+        event = self._make_soccer_event()
+        result = self.extractor.extract_game_details(event)
+        assert result["home_score"] == "2"
+        assert result["away_score"] == "1"

test/test_background_data_service.py

@@ -0,0 +1,299 @@
+"""
+Tests for src/background_data_service.py
+
+Covers BackgroundDataService: submit_fetch_request, get_result,
+is_request_complete, get_request_status, cancel_request, get_statistics,
+_cleanup_completed_requests, shutdown, and get_background_service singleton.
+"""
+
+import time
+import pytest
+from unittest.mock import MagicMock, patch, Mock
+from concurrent.futures import Future
+
+from src.background_data_service import (
+    BackgroundDataService,
+    FetchStatus,
+    FetchResult,
+    FetchRequest,
+    get_background_service,
+    shutdown_background_service,
+)
+import src.background_data_service as bds_module
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def reset_global_service():
+    """Ensure each test starts with no global singleton."""
+    shutdown_background_service()
+    yield
+    shutdown_background_service()
+
+
+@pytest.fixture
+def mock_cache_manager():
+    m = MagicMock()
+    m.get.return_value = None
+    m.set.return_value = None
+    m.generate_sport_cache_key.return_value = "test_key"
+    return m
+
+
+@pytest.fixture
+def service(mock_cache_manager):
+    svc = BackgroundDataService(mock_cache_manager, max_workers=2, request_timeout=5)
+    yield svc
+    svc.shutdown(wait=False)
+
+
+# ---------------------------------------------------------------------------
+# Initialisation
+# ---------------------------------------------------------------------------
+
+class TestInitialisation:
+    def test_stats_zeroed(self, service):
+        stats = service.get_statistics()
+        assert stats["total_requests"] == 0
+        assert stats["completed_requests"] == 0
+        assert stats["failed_requests"] == 0
+
+    def test_no_active_requests(self, service):
+        assert len(service.active_requests) == 0
+
+    def test_not_shutdown(self, service):
+        assert service._shutdown is False
+
+
+# ---------------------------------------------------------------------------
+# Cache hit path
+# ---------------------------------------------------------------------------
+
+class TestCacheHit:
+    def test_cache_hit_returns_request_id(self, service, mock_cache_manager):
+        mock_cache_manager.get.return_value = {"events": [{"id": "1"}]}
+        req_id = service.submit_fetch_request(
+            sport="nfl", year=2024,
+            url="https://example.com/nfl",
+            cache_key="nfl_key",
+        )
+        assert req_id is not None
+        # Request should be immediately complete due to cache hit
+        result = service.get_result(req_id)
+        assert result is not None
+        assert result.success is True
+        assert result.cached is True
+
+    def test_cache_hit_increments_stat(self, service, mock_cache_manager):
+        mock_cache_manager.get.return_value = {"events": []}
+        service.submit_fetch_request(sport="nba", year=2024, url="https://x.com", cache_key="k")
+        stats = service.get_statistics()
+        assert stats["cached_hits"] == 1
+
+
+# ---------------------------------------------------------------------------
+# Actual fetch path (mocked HTTP)
+# ---------------------------------------------------------------------------
+
+class TestFetchPath:
+    def _valid_payload(self) -> dict:
+        return {"events": [{"id": "g1"}, {"id": "g2"}]}
+
+    def test_successful_fetch_completes(self, service, mock_cache_manager):
+        mock_resp = Mock()
+        mock_resp.json.return_value = self._valid_payload()
+        mock_resp.raise_for_status.return_value = None
+
+        with patch.object(service.session, "get", return_value=mock_resp):
+            req_id = service.submit_fetch_request(
+                sport="nfl", year=2024,
+                url="https://example.com/nfl",
+                cache_key="nfl_test",
+            )
+            # Wait for the background thread
+            deadline = time.time() + 5
+            while not service.is_request_complete(req_id) and time.time() < deadline:
+                time.sleep(0.05)
+
+        result = service.get_result(req_id)
+        assert result is not None
+        assert result.success is True
+        assert result.data == self._valid_payload()
+
+    def test_failed_fetch_records_error(self, service, mock_cache_manager):
+        with patch.object(service.session, "get", side_effect=Exception("network error")):
+            req_id = service.submit_fetch_request(
+                sport="nba", year=2024,
+                url="https://example.com/nba",
+                cache_key="nba_test",
+                max_retries=0,
+            )
+            deadline = time.time() + 5
+            while not service.is_request_complete(req_id) and time.time() < deadline:
+                time.sleep(0.05)
+
+        result = service.get_result(req_id)
+        assert result is not None
+        assert result.success is False
+        assert result.error is not None
+
+    def test_cache_miss_increments_stat(self, service, mock_cache_manager):
+        mock_resp = Mock()
+        mock_resp.json.return_value = self._valid_payload()
+        mock_resp.raise_for_status.return_value = None
+
+        with patch.object(service.session, "get", return_value=mock_resp):
+            service.submit_fetch_request(
+                sport="nfl", year=2024, url="https://x.com", cache_key="new_key",
+            )
+        stats = service.get_statistics()
+        assert stats["cache_misses"] == 1
+
+    def test_callback_called_on_success(self, service, mock_cache_manager):
+        callback = Mock()
+        mock_resp = Mock()
+        mock_resp.json.return_value = self._valid_payload()
+        mock_resp.raise_for_status.return_value = None
+
+        with patch.object(service.session, "get", return_value=mock_resp):
+            req_id = service.submit_fetch_request(
+                sport="nfl", year=2024, url="https://x.com",
+                cache_key="cb_key", callback=callback, max_retries=0,
+            )
+            deadline = time.time() + 5
+            while not service.is_request_complete(req_id) and time.time() < deadline:
+                time.sleep(0.05)
+
+        callback.assert_called_once()
+        call_arg = callback.call_args[0][0]
+        assert isinstance(call_arg, FetchResult)
+
+    def test_data_cached_after_successful_fetch(self, service, mock_cache_manager):
+        mock_resp = Mock()
+        mock_resp.json.return_value = self._valid_payload()
+        mock_resp.raise_for_status.return_value = None
+
+        with patch.object(service.session, "get", return_value=mock_resp):
+            req_id = service.submit_fetch_request(
+                sport="nfl", year=2024, url="https://x.com", cache_key="cache_after_key",
+            )
+            deadline = time.time() + 5
+            while not service.is_request_complete(req_id) and time.time() < deadline:
+                time.sleep(0.05)
+
+        mock_cache_manager.set.assert_called()
+
+
+# ---------------------------------------------------------------------------
+# Request status / cancel
+# ---------------------------------------------------------------------------
+
+class TestRequestStatusAndCancel:
+    def test_unknown_request_status_is_none(self, service):
+        assert service.get_request_status("nonexistent") is None
+
+    def test_cancel_active_request(self, service, mock_cache_manager):
+        # Manually insert an active request
+        req = FetchRequest(
+            id="r1", sport="nfl", year=2024,
+            cache_key="k", url="https://x.com",
+        )
+        req.status = FetchStatus.PENDING
+        service.active_requests["r1"] = req
+        result = service.cancel_request("r1")
+        assert result is True
+        assert "r1" not in service.active_requests
+
+    def test_cancel_nonexistent_request(self, service):
+        assert service.cancel_request("does-not-exist") is False
+
+    def test_is_request_complete_false_for_active(self, service, mock_cache_manager):
+        req = FetchRequest(
+            id="r2", sport="mlb", year=2024,
+            cache_key="k2", url="https://x.com",
+        )
+        service.active_requests["r2"] = req
+        assert service.is_request_complete("r2") is False
+
+    def test_is_request_complete_true_for_done(self, service):
+        result = FetchResult(request_id="r3", success=True)
+        service.completed_requests["r3"] = result
+        assert service.is_request_complete("r3") is True
+
+    def test_get_result_returns_none_for_unknown(self, service):
+        assert service.get_result("unknown") is None
+
+
+# ---------------------------------------------------------------------------
+# Shutdown
+# ---------------------------------------------------------------------------
+
+class TestShutdown:
+    def test_shutdown_sets_flag(self, service):
+        service.shutdown(wait=False)
+        assert service._shutdown is True
+
+    def test_submit_after_shutdown_raises(self, service, mock_cache_manager):
+        service.shutdown(wait=False)
+        with pytest.raises(RuntimeError, match="shutting down"):
+            service.submit_fetch_request(
+                sport="nfl", year=2024, url="https://x.com", cache_key="k"
+            )
+
+
+# ---------------------------------------------------------------------------
+# Cleanup
+# ---------------------------------------------------------------------------
+
+class TestCleanup:
+    def test_cleanup_removes_old_requests(self, service):
+        old_result = FetchResult(request_id="old", success=True)
+        old_result.completed_at = time.time() - 7200  # 2 hours ago
+        service.completed_requests["old"] = old_result
+        service._last_completed_requests_cleanup = 0  # force cleanup
+        removed = service._cleanup_completed_requests(force=True)
+        assert removed >= 1
+        assert "old" not in service.completed_requests
+
+    def test_cleanup_respects_interval(self, service):
+        old_result = FetchResult(request_id="r", success=True)
+        old_result.completed_at = time.time() - 7200
+        service.completed_requests["r"] = old_result
+        # Cleanup interval not passed, should skip
+        service._last_completed_requests_cleanup = time.time()
+        removed = service._cleanup_completed_requests(force=False)
+        assert removed == 0
+
+    def test_size_limit_enforcement(self, service):
+        service._max_completed_requests = 3
+        for i in range(5):
+            result = FetchResult(request_id=str(i), success=True)
+            result.completed_at = time.time() - (5 - i) * 100  # oldest first
+            service.completed_requests[str(i)] = result
+        service._last_completed_requests_cleanup = 0
+        service._cleanup_completed_requests(force=True)
+        assert len(service.completed_requests) <= 3
+
+
+# ---------------------------------------------------------------------------
+# Singleton get_background_service
+# ---------------------------------------------------------------------------
+
+class TestGetBackgroundService:
+    def test_first_call_requires_cache_manager(self):
+        with pytest.raises(ValueError, match="cache_manager is required"):
+            get_background_service()
+
+    def test_creates_singleton(self, mock_cache_manager):
+        svc1 = get_background_service(mock_cache_manager)
+        svc2 = get_background_service()
+        assert svc1 is svc2
+
+    def test_shutdown_clears_singleton(self, mock_cache_manager):
+        get_background_service(mock_cache_manager)
+        shutdown_background_service()
+        with pytest.raises(ValueError):
+            get_background_service()

test/test_data_sources.py

@@ -0,0 +1,209 @@
+"""
+Tests for src/base_classes/data_sources.py
+
+Covers ESPNDataSource, MLBAPIDataSource, SoccerAPIDataSource.
+All HTTP calls are mocked to avoid network access.
+"""
+
+import logging
+from datetime import datetime, date
+from unittest.mock import MagicMock, patch, Mock
+import pytest
+import requests
+
+from src.base_classes.data_sources import ESPNDataSource, MLBAPIDataSource, SoccerAPIDataSource
+
+
+def _make_logger() -> logging.Logger:
+    return logging.getLogger("test_data_sources")
+
+
+def _mock_response(json_data: dict, status_code: int = 200):
+    resp = Mock(spec=requests.Response)
+    resp.status_code = status_code
+    resp.json.return_value = json_data
+    resp.raise_for_status = Mock()
+    if status_code >= 400:
+        resp.raise_for_status.side_effect = requests.HTTPError(response=resp)
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# ESPNDataSource
+# ---------------------------------------------------------------------------
+
+class TestESPNDataSource:
+    def setup_method(self):
+        self.source = ESPNDataSource(_make_logger())
+
+    def test_get_headers(self):
+        headers = self.source.get_headers()
+        assert headers["Accept"] == "application/json"
+        assert "LEDMatrix" in headers["User-Agent"]
+
+    def test_fetch_live_games_returns_live_events(self):
+        live_event = {
+            "competitions": [{"status": {"type": {"state": "in"}}}]
+        }
+        non_live_event = {
+            "competitions": [{"status": {"type": {"state": "pre"}}}]
+        }
+        payload = {"events": [live_event, non_live_event]}
+
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_live_games("football", "nfl")
+
+        assert len(result) == 1
+        assert result[0] is live_event
+
+    def test_fetch_live_games_empty_when_none_live(self):
+        payload = {"events": [
+            {"competitions": [{"status": {"type": {"state": "post"}}}]}
+        ]}
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_live_games("football", "nfl")
+        assert result == []
+
+    def test_fetch_live_games_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("network failure")):
+            result = self.source.fetch_live_games("football", "nfl")
+        assert result == []
+
+    def test_fetch_schedule_returns_all_events(self):
+        events = [{"id": "1"}, {"id": "2"}]
+        payload = {"events": events}
+        start = datetime(2024, 1, 1)
+        end = datetime(2024, 1, 7)
+
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_schedule("football", "nfl", (start, end))
+
+        assert len(result) == 2
+
+    def test_fetch_schedule_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("timeout")):
+            result = self.source.fetch_schedule("football", "nfl", (datetime.now(), datetime.now()))
+        assert result == []
+
+    def test_fetch_standings_success(self):
+        payload = {"standings": []}
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_standings("football", "nfl")
+        assert result == payload
+
+    def test_fetch_standings_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("error")):
+            result = self.source.fetch_standings("football", "nfl")
+        assert result == {}
+
+    def test_base_url_set_correctly(self):
+        assert "espn.com" in self.source.base_url
+
+
+# ---------------------------------------------------------------------------
+# MLBAPIDataSource
+# ---------------------------------------------------------------------------
+
+class TestMLBAPIDataSource:
+    def setup_method(self):
+        self.source = MLBAPIDataSource(_make_logger())
+
+    def test_fetch_live_games_filters_live(self):
+        live_game = {"status": {"abstractGameState": "Live"}}
+        final_game = {"status": {"abstractGameState": "Final"}}
+        payload = {"dates": [{"games": [live_game, final_game]}]}
+
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_live_games("baseball", "mlb")
+
+        assert len(result) == 1
+        assert result[0] is live_game
+
+    def test_fetch_live_games_empty_dates(self):
+        payload = {"dates": []}
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_live_games("baseball", "mlb")
+        assert result == []
+
+    def test_fetch_live_games_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("err")):
+            result = self.source.fetch_live_games("baseball", "mlb")
+        assert result == []
+
+    def test_fetch_schedule_aggregates_all_dates(self):
+        payload = {
+            "dates": [
+                {"games": [{"id": "1"}, {"id": "2"}]},
+                {"games": [{"id": "3"}]},
+            ]
+        }
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_schedule("baseball", "mlb", (datetime.now(), datetime.now()))
+        assert len(result) == 3
+
+    def test_fetch_schedule_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("err")):
+            result = self.source.fetch_schedule("baseball", "mlb", (datetime.now(), datetime.now()))
+        assert result == []
+
+    def test_fetch_standings_success(self):
+        payload = {"records": []}
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_standings("baseball", "mlb")
+        assert result == payload
+
+    def test_fetch_standings_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("err")):
+            result = self.source.fetch_standings("baseball", "mlb")
+        assert result == {}
+
+
+# ---------------------------------------------------------------------------
+# SoccerAPIDataSource
+# ---------------------------------------------------------------------------
+
+class TestSoccerAPIDataSource:
+    def setup_method(self):
+        self.source = SoccerAPIDataSource(_make_logger(), api_key="test-key-123")
+
+    def test_headers_include_api_key(self):
+        headers = self.source.get_headers()
+        assert headers["X-Auth-Token"] == "test-key-123"
+
+    def test_headers_without_api_key(self):
+        source = SoccerAPIDataSource(_make_logger())
+        headers = source.get_headers()
+        assert "X-Auth-Token" not in headers
+
+    def test_fetch_live_games_success(self):
+        payload = {"matches": [{"id": "m1"}, {"id": "m2"}]}
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_live_games("soccer", "eng.1")
+        assert len(result) == 2
+
+    def test_fetch_live_games_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("err")):
+            result = self.source.fetch_live_games("soccer", "eng.1")
+        assert result == []
+
+    def test_fetch_schedule_success(self):
+        payload = {"matches": [{"id": "m1"}]}
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_schedule("soccer", "eng.1", (datetime.now(), datetime.now()))
+        assert len(result) == 1
+
+    def test_fetch_schedule_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("err")):
+            result = self.source.fetch_schedule("soccer", "eng.1", (datetime.now(), datetime.now()))
+        assert result == []
+
+    def test_fetch_standings_success(self):
+        payload = {"standings": []}
+        with patch.object(self.source.session, "get", return_value=_mock_response(payload)):
+            result = self.source.fetch_standings("soccer", "PL")
+        assert result == payload
+
+    def test_fetch_standings_returns_empty_on_error(self):
+        with patch.object(self.source.session, "get", side_effect=Exception("err")):
+            result = self.source.fetch_standings("soccer", "PL")
+        assert result == {}

test/test_game_helper.py

@@ -0,0 +1,317 @@
+"""
+Tests for src/common/game_helper.py
+
+Covers GameHelper: extract_game_details, filter_*, sort_games_by_time,
+process_games, get_game_summary, and all private helpers.
+"""
+
+import logging
+import pytest
+from datetime import datetime, timezone, timedelta
+
+from src.common.game_helper import GameHelper
+
+
+def _make_logger() -> logging.Logger:
+    return logging.getLogger("test_game_helper")
+
+
+def _make_espn_event(
+    state: str = "in",
+    home_abbr: str = "LAL",
+    away_abbr: str = "BOS",
+    home_score: str = "105",
+    away_score: str = "98",
+    date_str: str = "2024-01-15T20:00:00Z",
+    period: int = 4,
+    status_name: str = "STATUS_IN_PROGRESS",
+    home_record: str = "30-10",
+    away_record: str = "25-15",
+    event_id: str = "game-1",
+) -> dict:
+    return {
+        "id": event_id,
+        "date": date_str,
+        "competitions": [
+            {
+                "status": {
+                    "type": {
+                        "state": state,
+                        "shortDetail": "Q4 2:30",
+                        "name": status_name,
+                    },
+                    "period": period,
+                    "displayClock": "2:30",
+                },
+                "competitors": [
+                    {
+                        "homeAway": "home",
+                        "id": "h1",
+                        "team": {"abbreviation": home_abbr, "displayName": f"{home_abbr} Team"},
+                        "score": home_score,
+                        "records": [{"summary": home_record}],
+                    },
+                    {
+                        "homeAway": "away",
+                        "id": "a1",
+                        "team": {"abbreviation": away_abbr, "displayName": f"{away_abbr} Team"},
+                        "score": away_score,
+                        "records": [{"summary": away_record}],
+                    },
+                ],
+            }
+        ],
+    }
+
+
+@pytest.fixture
+def helper():
+    return GameHelper(timezone_str="UTC", logger=_make_logger())
+
+
+# ---------------------------------------------------------------------------
+# extract_game_details
+# ---------------------------------------------------------------------------
+
+class TestExtractGameDetails:
+    def test_live_game(self, helper):
+        event = _make_espn_event(state="in")
+        result = helper.extract_game_details(event)
+        assert result is not None
+        assert result["is_live"] is True
+        assert result["is_final"] is False
+        assert result["is_upcoming"] is False
+
+    def test_final_game(self, helper):
+        event = _make_espn_event(state="post")
+        result = helper.extract_game_details(event)
+        assert result["is_final"] is True
+
+    def test_upcoming_game(self, helper):
+        event = _make_espn_event(state="pre")
+        result = helper.extract_game_details(event)
+        assert result["is_upcoming"] is True
+
+    def test_halftime_detection(self, helper):
+        event = _make_espn_event(state="halftime", status_name="STATUS_HALFTIME")
+        result = helper.extract_game_details(event)
+        assert result["is_halftime"] is True
+
+    def test_basic_fields_present(self, helper):
+        event = _make_espn_event()
+        result = helper.extract_game_details(event)
+        for key in ("id", "home_abbr", "away_abbr", "home_score", "away_score",
+                    "home_record", "away_record", "start_time_utc"):
+            assert key in result
+
+    def test_team_abbreviations(self, helper):
+        event = _make_espn_event(home_abbr="MIA", away_abbr="PHX")
+        result = helper.extract_game_details(event)
+        assert result["home_abbr"] == "MIA"
+        assert result["away_abbr"] == "PHX"
+
+    def test_scores_as_strings(self, helper):
+        event = _make_espn_event(home_score="110", away_score="99")
+        result = helper.extract_game_details(event)
+        assert result["home_score"] == "110"
+        assert result["away_score"] == "99"
+
+    def test_returns_none_on_empty(self, helper):
+        assert helper.extract_game_details({}) is None
+        assert helper.extract_game_details(None) is None
+
+    def test_returns_none_when_no_competitors(self, helper):
+        event = _make_espn_event()
+        event["competitions"][0]["competitors"] = []
+        assert helper.extract_game_details(event) is None
+
+    def test_date_z_suffix_parsed(self, helper):
+        event = _make_espn_event(date_str="2024-06-01T19:30:00Z")
+        result = helper.extract_game_details(event)
+        assert result["start_time_utc"] is not None
+        assert result["start_time_utc"].tzinfo is not None
+
+    def test_zero_zero_record_suppressed(self, helper):
+        event = _make_espn_event(home_record="0-0", away_record="0-0-0")
+        result = helper.extract_game_details(event)
+        assert result["home_record"] == ""
+        assert result["away_record"] == ""
+
+    def test_basketball_sport_fields(self, helper):
+        event = _make_espn_event(period=3)
+        result = helper.extract_game_details(event, sport="basketball")
+        assert result["period_text"] == "Q3"
+        assert "clock" in result
+
+    def test_basketball_overtime_period(self, helper):
+        event = _make_espn_event(period=5)
+        result = helper.extract_game_details(event, sport="basketball")
+        assert result["period_text"] == "OT1"
+
+    def test_football_sport_fields(self, helper):
+        event = _make_espn_event(period=2)
+        result = helper.extract_game_details(event, sport="football")
+        assert result["period_text"] == "Q2"
+
+    def test_hockey_sport_fields_period_1(self, helper):
+        event = _make_espn_event(period=1)
+        result = helper.extract_game_details(event, sport="hockey")
+        assert result["period_text"] == "P1"
+
+    def test_hockey_sport_fields_ot(self, helper):
+        event = _make_espn_event(period=4)
+        result = helper.extract_game_details(event, sport="hockey")
+        assert result["period_text"] == "OT1"
+
+    def test_baseball_sport_fields(self, helper):
+        event = _make_espn_event(period=7)
+        result = helper.extract_game_details(event, sport="baseball")
+        assert result["period_text"] == "INN 7"
+
+
+# ---------------------------------------------------------------------------
+# Filter methods
+# ---------------------------------------------------------------------------
+
+class TestFilterMethods:
+    def _make_games(self):
+        now = datetime.now(timezone.utc)
+        return [
+            {"is_live": True, "is_final": False, "is_upcoming": False, "home_abbr": "LAL", "away_abbr": "BOS", "start_time_utc": now},
+            {"is_live": False, "is_final": True, "is_upcoming": False, "home_abbr": "MIA", "away_abbr": "PHX", "start_time_utc": now - timedelta(hours=3)},
+            {"is_live": False, "is_final": False, "is_upcoming": True, "home_abbr": "DAL", "away_abbr": "CHI", "start_time_utc": now + timedelta(hours=2)},
+        ]
+
+    def test_filter_live_games(self, helper):
+        games = self._make_games()
+        result = helper.filter_live_games(games)
+        assert len(result) == 1
+        assert result[0]["home_abbr"] == "LAL"
+
+    def test_filter_final_games(self, helper):
+        games = self._make_games()
+        result = helper.filter_final_games(games)
+        assert len(result) == 1
+        assert result[0]["home_abbr"] == "MIA"
+
+    def test_filter_upcoming_games(self, helper):
+        games = self._make_games()
+        result = helper.filter_upcoming_games(games)
+        assert len(result) == 1
+        assert result[0]["home_abbr"] == "DAL"
+
+    def test_filter_favorite_teams_match(self, helper):
+        games = self._make_games()
+        result = helper.filter_favorite_teams(games, ["LAL"])
+        assert len(result) == 1
+        assert result[0]["home_abbr"] == "LAL"
+
+    def test_filter_favorite_teams_empty_list_returns_all(self, helper):
+        games = self._make_games()
+        result = helper.filter_favorite_teams(games, [])
+        assert len(result) == 3
+
+    def test_filter_favorite_teams_away_match(self, helper):
+        games = self._make_games()
+        result = helper.filter_favorite_teams(games, ["BOS"])
+        assert len(result) == 1
+
+    def test_filter_recent_games_within_window(self, helper):
+        now = datetime.now(timezone.utc)
+        games = [
+            {"start_time_utc": now - timedelta(days=2), "is_final": True},
+            {"start_time_utc": now - timedelta(days=10), "is_final": True},
+        ]
+        result = helper.filter_recent_games(games, days_back=7)
+        assert len(result) == 1
+
+    def test_filter_recent_games_all_within(self, helper):
+        now = datetime.now(timezone.utc)
+        games = [
+            {"start_time_utc": now - timedelta(days=1)},
+            {"start_time_utc": now - timedelta(days=3)},
+        ]
+        result = helper.filter_recent_games(games, days_back=7)
+        assert len(result) == 2
+
+    def test_sort_games_ascending(self, helper):
+        now = datetime.now(timezone.utc)
+        games = [
+            {"start_time_utc": now + timedelta(hours=2), "id": "late"},
+            {"start_time_utc": now + timedelta(hours=1), "id": "early"},
+        ]
+        result = helper.sort_games_by_time(games)
+        assert result[0]["id"] == "early"
+
+    def test_sort_games_descending(self, helper):
+        now = datetime.now(timezone.utc)
+        games = [
+            {"start_time_utc": now + timedelta(hours=1), "id": "early"},
+            {"start_time_utc": now + timedelta(hours=2), "id": "late"},
+        ]
+        result = helper.sort_games_by_time(games, reverse=True)
+        assert result[0]["id"] == "late"
+
+
+# ---------------------------------------------------------------------------
+# process_games
+# ---------------------------------------------------------------------------
+
+class TestProcessGames:
+    def test_processes_valid_events(self, helper):
+        events = [
+            _make_espn_event(event_id="1"),
+            _make_espn_event(event_id="2"),
+        ]
+        result = helper.process_games(events)
+        assert len(result) == 2
+
+    def test_skips_invalid_events(self, helper):
+        events = [
+            _make_espn_event(event_id="1"),
+            {},  # invalid
+        ]
+        result = helper.process_games(events)
+        assert len(result) == 1
+
+    def test_empty_events(self, helper):
+        assert helper.process_games([]) == []
+
+
+# ---------------------------------------------------------------------------
+# get_game_summary
+# ---------------------------------------------------------------------------
+
+class TestGetGameSummary:
+    def test_live_summary(self, helper):
+        game = {
+            "home_abbr": "LAL", "away_abbr": "BOS",
+            "home_score": "105", "away_score": "98",
+            "status_text": "Q4 2:30",
+            "is_live": True, "is_final": False,
+        }
+        summary = helper.get_game_summary(game)
+        assert "BOS" in summary
+        assert "LAL" in summary
+        assert "98" in summary
+        assert "105" in summary
+
+    def test_final_summary(self, helper):
+        game = {
+            "home_abbr": "LAL", "away_abbr": "BOS",
+            "home_score": "110", "away_score": "102",
+            "status_text": "Final",
+            "is_live": False, "is_final": True,
+        }
+        summary = helper.get_game_summary(game)
+        assert "Final" in summary
+
+    def test_upcoming_summary(self, helper):
+        game = {
+            "home_abbr": "LAL", "away_abbr": "BOS",
+            "home_score": "0", "away_score": "0",
+            "status_text": "7:30 PM",
+            "is_live": False, "is_final": False,
+        }
+        summary = helper.get_game_summary(game)
+        assert "7:30 PM" in summary

test/test_health_monitor.py

@@ -0,0 +1,307 @@
+"""
+Tests for src/plugin_system/health_monitor.py
+
+Covers PluginHealthMonitor: get_plugin_health_status, get_plugin_health_metrics,
+get_all_plugin_health, _get_recovery_suggestions, start/stop_monitoring,
+register_health_check.
+"""
+
+import pytest
+from unittest.mock import MagicMock, patch
+from datetime import datetime
+
+from src.plugin_system.health_monitor import (
+    PluginHealthMonitor,
+    HealthStatus,
+    HealthMetrics,
+)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+def _make_health_tracker(
+    summary: dict | None = None,
+    all_summaries: dict | None = None,
+):
+    """Return a mock PluginHealthTracker."""
+    tracker = MagicMock()
+    tracker.get_health_summary.return_value = summary
+    tracker.get_all_health_summaries.return_value = all_summaries or {}
+    return tracker
+
+
+def _healthy_summary() -> dict:
+    return {
+        "success_rate": 100.0,
+        "circuit_state": "closed",
+        "consecutive_failures": 0,
+        "total_failures": 0,
+        "total_successes": 50,
+        "last_success_time": datetime.now().isoformat(),
+        "last_error": None,
+    }
+
+
+def _degraded_summary() -> dict:
+    return {
+        "success_rate": 40.0,  # 60% error rate
+        "circuit_state": "closed",
+        "consecutive_failures": 3,
+        "total_failures": 6,
+        "total_successes": 4,
+        "last_success_time": None,
+        "last_error": "timeout occurred",
+    }
+
+
+def _unhealthy_summary() -> dict:
+    return {
+        "success_rate": 10.0,  # 90% error rate
+        "circuit_state": "open",
+        "consecutive_failures": 10,
+        "total_failures": 9,
+        "total_successes": 1,
+        "last_success_time": None,
+        "last_error": "ImportError: missing module",
+    }
+
+
+@pytest.fixture
+def monitor():
+    tracker = _make_health_tracker(_healthy_summary())
+    return PluginHealthMonitor(health_tracker=tracker)
+
+
+# ---------------------------------------------------------------------------
+# get_plugin_health_status
+# ---------------------------------------------------------------------------
+
+class TestGetPluginHealthStatus:
+    def test_healthy_status(self):
+        tracker = _make_health_tracker(_healthy_summary())
+        monitor = PluginHealthMonitor(tracker)
+        status = monitor.get_plugin_health_status("plugin_a")
+        assert status == HealthStatus.HEALTHY
+
+    def test_degraded_status(self):
+        tracker = _make_health_tracker(_degraded_summary())
+        monitor = PluginHealthMonitor(tracker, degraded_threshold=0.5, unhealthy_threshold=0.8)
+        status = monitor.get_plugin_health_status("plugin_b")
+        assert status == HealthStatus.DEGRADED
+
+    def test_unhealthy_status(self):
+        tracker = _make_health_tracker(_unhealthy_summary())
+        monitor = PluginHealthMonitor(tracker, unhealthy_threshold=0.8)
+        status = monitor.get_plugin_health_status("plugin_c")
+        assert status == HealthStatus.UNHEALTHY
+
+    def test_open_circuit_breaker_is_unhealthy(self):
+        summary = _healthy_summary()
+        summary["circuit_state"] = "open"
+        tracker = _make_health_tracker(summary)
+        monitor = PluginHealthMonitor(tracker)
+        status = monitor.get_plugin_health_status("plugin_d")
+        assert status == HealthStatus.UNHEALTHY
+
+    def test_unknown_when_no_tracker(self):
+        monitor = PluginHealthMonitor(health_tracker=None)
+        status = monitor.get_plugin_health_status("plugin_e")
+        assert status == HealthStatus.UNKNOWN
+
+    def test_unknown_when_no_summary(self):
+        tracker = _make_health_tracker(None)
+        monitor = PluginHealthMonitor(tracker)
+        status = monitor.get_plugin_health_status("plugin_f")
+        assert status == HealthStatus.UNKNOWN
+
+
+# ---------------------------------------------------------------------------
+# get_plugin_health_metrics
+# ---------------------------------------------------------------------------
+
+class TestGetPluginHealthMetrics:
+    def test_healthy_metrics(self):
+        tracker = _make_health_tracker(_healthy_summary())
+        monitor = PluginHealthMonitor(tracker)
+        metrics = monitor.get_plugin_health_metrics("plugin_a")
+        assert isinstance(metrics, HealthMetrics)
+        assert metrics.status == HealthStatus.HEALTHY
+        assert metrics.success_rate == pytest.approx(1.0)
+        assert metrics.error_rate == pytest.approx(0.0)
+
+    def test_degraded_metrics(self):
+        tracker = _make_health_tracker(_degraded_summary())
+        monitor = PluginHealthMonitor(tracker, degraded_threshold=0.5, unhealthy_threshold=0.8)
+        metrics = monitor.get_plugin_health_metrics("plugin_b")
+        assert metrics.status == HealthStatus.DEGRADED
+        assert metrics.consecutive_failures == 3
+
+    def test_unhealthy_metrics(self):
+        tracker = _make_health_tracker(_unhealthy_summary())
+        monitor = PluginHealthMonitor(tracker, unhealthy_threshold=0.8)
+        metrics = monitor.get_plugin_health_metrics("plugin_c")
+        assert metrics.status == HealthStatus.UNHEALTHY
+        assert metrics.circuit_breaker_state == "open"
+        assert metrics.last_error is not None
+
+    def test_metrics_without_tracker(self):
+        monitor = PluginHealthMonitor(health_tracker=None)
+        metrics = monitor.get_plugin_health_metrics("plugin_d")
+        assert metrics.status == HealthStatus.UNKNOWN
+        assert metrics.plugin_id == "plugin_d"
+
+    def test_metrics_without_summary(self):
+        tracker = _make_health_tracker(None)
+        monitor = PluginHealthMonitor(tracker)
+        metrics = monitor.get_plugin_health_metrics("plugin_e")
+        assert metrics.status == HealthStatus.UNKNOWN
+
+    def test_last_successful_update_parsed(self):
+        summary = _healthy_summary()
+        summary["last_success_time"] = "2024-06-01T12:00:00"
+        tracker = _make_health_tracker(summary)
+        monitor = PluginHealthMonitor(tracker)
+        metrics = monitor.get_plugin_health_metrics("plugin_a")
+        assert metrics.last_successful_update is not None
+        assert isinstance(metrics.last_successful_update, datetime)
+
+    def test_invalid_last_success_time_handled(self):
+        summary = _healthy_summary()
+        summary["last_success_time"] = "not-a-date"
+        tracker = _make_health_tracker(summary)
+        monitor = PluginHealthMonitor(tracker)
+        # Should not raise
+        metrics = monitor.get_plugin_health_metrics("plugin_a")
+        assert metrics.last_successful_update is None
+
+    def test_total_successes_failures(self):
+        tracker = _make_health_tracker(_degraded_summary())
+        monitor = PluginHealthMonitor(tracker, degraded_threshold=0.5, unhealthy_threshold=0.8)
+        metrics = monitor.get_plugin_health_metrics("plugin_b")
+        assert metrics.total_failures == 6
+        assert metrics.total_successes == 4
+
+
+# ---------------------------------------------------------------------------
+# get_all_plugin_health
+# ---------------------------------------------------------------------------
+
+class TestGetAllPluginHealth:
+    def test_returns_empty_without_tracker(self):
+        monitor = PluginHealthMonitor(health_tracker=None)
+        result = monitor.get_all_plugin_health()
+        assert result == {}
+
+    def test_returns_metrics_for_each_plugin(self):
+        all_summaries = {
+            "plugin_a": _healthy_summary(),
+            "plugin_b": _degraded_summary(),
+        }
+        tracker = MagicMock()
+        tracker.get_all_health_summaries.return_value = all_summaries
+        tracker.get_health_summary.side_effect = lambda pid: all_summaries.get(pid)
+        monitor = PluginHealthMonitor(tracker, degraded_threshold=0.5, unhealthy_threshold=0.8)
+        result = monitor.get_all_plugin_health()
+        assert "plugin_a" in result
+        assert "plugin_b" in result
+        assert isinstance(result["plugin_a"], HealthMetrics)
+
+    def test_returns_empty_when_no_summaries(self):
+        tracker = _make_health_tracker(all_summaries={})
+        monitor = PluginHealthMonitor(tracker)
+        result = monitor.get_all_plugin_health()
+        assert result == {}
+
+
+# ---------------------------------------------------------------------------
+# _get_recovery_suggestions
+# ---------------------------------------------------------------------------
+
+class TestGetRecoverySuggestions:
+    def test_healthy_plugin_suggestion(self):
+        tracker = _make_health_tracker(_healthy_summary())
+        monitor = PluginHealthMonitor(tracker)
+        suggestions = monitor._get_recovery_suggestions("p", _healthy_summary(), HealthStatus.HEALTHY)
+        assert any("healthy" in s.lower() for s in suggestions)
+
+    def test_unhealthy_suggestions(self):
+        tracker = _make_health_tracker(_unhealthy_summary())
+        monitor = PluginHealthMonitor(tracker, unhealthy_threshold=0.8)
+        suggestions = monitor._get_recovery_suggestions("p", _unhealthy_summary(), HealthStatus.UNHEALTHY)
+        assert len(suggestions) > 0
+        assert any("unhealthy" in s.lower() for s in suggestions)
+
+    def test_open_circuit_breaker_suggestion(self):
+        summary = _unhealthy_summary()
+        summary["circuit_state"] = "open"
+        tracker = _make_health_tracker(summary)
+        monitor = PluginHealthMonitor(tracker, unhealthy_threshold=0.8)
+        suggestions = monitor._get_recovery_suggestions("p", summary, HealthStatus.UNHEALTHY)
+        assert any("circuit" in s.lower() for s in suggestions)
+
+    def test_timeout_error_suggestion(self):
+        summary = _degraded_summary()
+        summary["last_error"] = "connection timeout occurred"
+        tracker = _make_health_tracker(summary)
+        monitor = PluginHealthMonitor(tracker, degraded_threshold=0.5, unhealthy_threshold=0.8)
+        suggestions = monitor._get_recovery_suggestions("p", summary, HealthStatus.DEGRADED)
+        assert any("timeout" in s.lower() for s in suggestions)
+
+    def test_import_error_suggestion(self):
+        summary = _unhealthy_summary()
+        summary["last_error"] = "ImportError: missing module"
+        tracker = _make_health_tracker(summary)
+        monitor = PluginHealthMonitor(tracker, unhealthy_threshold=0.8)
+        suggestions = monitor._get_recovery_suggestions("p", summary, HealthStatus.UNHEALTHY)
+        assert any("dependencies" in s.lower() or "import" in s.lower() or "missing" in s.lower()
+                   for s in suggestions)
+
+    def test_permission_error_suggestion(self):
+        summary = _unhealthy_summary()
+        summary["last_error"] = "permission denied to access resource"
+        tracker = _make_health_tracker(summary)
+        monitor = PluginHealthMonitor(tracker, unhealthy_threshold=0.8)
+        suggestions = monitor._get_recovery_suggestions("p", summary, HealthStatus.UNHEALTHY)
+        assert any("permission" in s.lower() for s in suggestions)
+
+    def test_degraded_suggestions_include_error_rate(self):
+        tracker = _make_health_tracker(_degraded_summary())
+        monitor = PluginHealthMonitor(tracker, degraded_threshold=0.5, unhealthy_threshold=0.8)
+        suggestions = monitor._get_recovery_suggestions("p", _degraded_summary(), HealthStatus.DEGRADED)
+        assert any("%" in s for s in suggestions)
+
+
+# ---------------------------------------------------------------------------
+# start / stop monitoring
+# ---------------------------------------------------------------------------
+
+class TestMonitorLifecycle:
+    def test_start_monitoring(self, monitor):
+        monitor.start_monitoring()
+        try:
+            assert monitor._monitor_thread is not None
+            assert monitor._monitor_thread.is_alive()
+        finally:
+            monitor.stop_monitoring()
+
+    def test_stop_monitoring(self, monitor):
+        monitor.start_monitoring()
+        monitor.stop_monitoring()
+        # Thread should no longer be alive
+        assert not monitor._monitor_thread.is_alive()
+
+    def test_double_start_no_duplicate_threads(self, monitor):
+        monitor.start_monitoring()
+        try:
+            thread1 = monitor._monitor_thread
+            monitor.start_monitoring()  # should be idempotent
+            assert monitor._monitor_thread is thread1
+        finally:
+            monitor.stop_monitoring()
+
+    def test_register_health_check(self, monitor):
+        callback = MagicMock()
+        monitor.register_health_check(callback)
+        assert callback in monitor._health_check_callbacks

test/test_logo_downloader.py

@@ -0,0 +1,129 @@
+"""
+Tests for src/logo_downloader.py
+
+Focuses on the pure/static methods that don't require network calls:
+normalize_abbreviation, get_logo_filename_variations, get_logo_directory,
+ensure_logo_directory, and the download_missing_logo function path
+(with HTTP mocked).
+"""
+
+import os
+import pytest
+from pathlib import Path
+from unittest.mock import patch, Mock, MagicMock
+
+from src.logo_downloader import LogoDownloader
+
+
+# ---------------------------------------------------------------------------
+# normalize_abbreviation
+# ---------------------------------------------------------------------------
+
+class TestNormalizeAbbreviation:
+    def test_basic_lowercase(self):
+        result = LogoDownloader.normalize_abbreviation("lal")
+        assert result == "LAL"
+
+    def test_uppercases(self):
+        result = LogoDownloader.normalize_abbreviation("bos")
+        assert result == "BOS"
+
+    def test_ampersand_replaced(self):
+        result = LogoDownloader.normalize_abbreviation("TA&M")
+        assert "&" not in result
+        assert "AND" in result
+
+    def test_forward_slash_replaced(self):
+        result = LogoDownloader.normalize_abbreviation("A/B")
+        assert "/" not in result
+
+    def test_empty_returns_empty(self):
+        result = LogoDownloader.normalize_abbreviation("")
+        assert result == ""
+
+
+# ---------------------------------------------------------------------------
+# get_logo_filename_variations
+# ---------------------------------------------------------------------------
+
+class TestGetLogoFilenameVariations:
+    def test_returns_list(self):
+        result = LogoDownloader.get_logo_filename_variations("LAL")
+        assert isinstance(result, list)
+        assert len(result) > 0
+
+    def test_includes_png(self):
+        result = LogoDownloader.get_logo_filename_variations("KC")
+        filenames = " ".join(result)
+        assert ".png" in filenames
+
+    def test_includes_original(self):
+        result = LogoDownloader.get_logo_filename_variations("LAL")
+        assert any("LAL" in f for f in result)
+
+    def test_ampersand_variation(self):
+        result = LogoDownloader.get_logo_filename_variations("TA&M")
+        # Should produce at least the normalized version
+        assert len(result) > 0
+
+    def test_empty_string_no_crash(self):
+        result = LogoDownloader.get_logo_filename_variations("")
+        assert isinstance(result, list)
+
+
+# ---------------------------------------------------------------------------
+# get_logo_directory
+# ---------------------------------------------------------------------------
+
+class TestGetLogoDirectory:
+    def test_known_sport_returns_string(self):
+        downloader = LogoDownloader()
+        result = downloader.get_logo_directory("nfl")
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+    def test_known_sport_nba(self):
+        downloader = LogoDownloader()
+        result = downloader.get_logo_directory("nba")
+        assert "nba" in result.lower() or "sports" in result.lower()
+
+    def test_unknown_sport_returns_string(self):
+        downloader = LogoDownloader()
+        result = downloader.get_logo_directory("unknown_sport_xyz")
+        assert isinstance(result, str)
+
+
+# ---------------------------------------------------------------------------
+# ensure_logo_directory
+# ---------------------------------------------------------------------------
+
+class TestEnsureLogoDirectory:
+    def test_creates_writable_directory(self, tmp_path):
+        downloader = LogoDownloader()
+        test_dir = str(tmp_path / "logos" / "nfl")
+        result = downloader.ensure_logo_directory(test_dir)
+        assert result is True
+        assert Path(test_dir).is_dir()
+
+    def test_existing_writable_directory(self, tmp_path):
+        downloader = LogoDownloader()
+        test_dir = str(tmp_path)
+        result = downloader.ensure_logo_directory(test_dir)
+        assert result is True
+
+    def test_returns_false_when_write_test_fails(self, tmp_path):
+        """Simulate a directory that exists but raises PermissionError on write."""
+        downloader = LogoDownloader()
+        test_dir = str(tmp_path / "logos")
+
+        import builtins
+        original_open = builtins.open
+
+        def mock_open(path, *args, **kwargs):
+            if ".write_test" in str(path):
+                raise PermissionError("no write access")
+            return original_open(path, *args, **kwargs)
+
+        with patch("builtins.open", side_effect=mock_open):
+            result = downloader.ensure_logo_directory(test_dir)
+        assert result is False

test/test_scroll_helper.py

@@ -0,0 +1,317 @@
+"""
+Tests for src/common/scroll_helper.py
+
+Covers ScrollHelper: create_scrolling_image, update_scroll_position,
+get_visible_portion, calculate_dynamic_duration, set_* methods,
+reset_scroll, clear_cache, get_scroll_info.
+"""
+
+import pytest
+import time
+from unittest.mock import patch
+from PIL import Image
+
+from src.common.scroll_helper import ScrollHelper
+
+
+DISPLAY_W = 64
+DISPLAY_H = 32
+
+
+@pytest.fixture
+def helper():
+    return ScrollHelper(display_width=DISPLAY_W, display_height=DISPLAY_H)
+
+
+def _make_image(width: int = 64, height: int = 32, color=(255, 0, 0)) -> Image.Image:
+    img = Image.new("RGB", (width, height), color)
+    return img
+
+
+# ---------------------------------------------------------------------------
+# __init__ / initial state
+# ---------------------------------------------------------------------------
+
+class TestScrollHelperInit:
+    def test_initial_scroll_position(self, helper):
+        assert helper.scroll_position == 0.0
+
+    def test_initial_scroll_complete_false(self, helper):
+        assert helper.scroll_complete is False
+
+    def test_display_dimensions(self, helper):
+        assert helper.display_width == DISPLAY_W
+        assert helper.display_height == DISPLAY_H
+
+
+# ---------------------------------------------------------------------------
+# create_scrolling_image
+# ---------------------------------------------------------------------------
+
+class TestCreateScrollingImage:
+    def test_empty_content_returns_blank_image(self, helper):
+        result = helper.create_scrolling_image([])
+        assert isinstance(result, Image.Image)
+        assert helper.total_scroll_width == 0
+
+    def test_single_item_creates_image(self, helper):
+        img = _make_image(width=100)
+        result = helper.create_scrolling_image([img])
+        assert isinstance(result, Image.Image)
+        assert result.width > DISPLAY_W  # includes leading gap
+
+    def test_multiple_items_wider_image(self, helper):
+        items = [_make_image(width=50), _make_image(width=50)]
+        result = helper.create_scrolling_image(items)
+        # Should be wider than two items alone
+        assert result.width > 100
+
+    def test_scroll_position_reset(self, helper):
+        helper.scroll_position = 500.0
+        helper.create_scrolling_image([_make_image()])
+        assert helper.scroll_position == 0.0
+
+    def test_cached_array_set(self, helper):
+        helper.create_scrolling_image([_make_image()])
+        assert helper.cached_array is not None
+
+    def test_scroll_complete_reset(self, helper):
+        helper.scroll_complete = True
+        helper.create_scrolling_image([_make_image()])
+        assert helper.scroll_complete is False
+
+    def test_total_scroll_width_matches_image(self, helper):
+        img = _make_image(width=200)
+        result = helper.create_scrolling_image([img])
+        assert helper.total_scroll_width == result.width
+
+
+# ---------------------------------------------------------------------------
+# set_scrolling_image
+# ---------------------------------------------------------------------------
+
+class TestSetScrollingImage:
+    def test_sets_cached_image(self, helper):
+        img = _make_image(width=200)
+        helper.set_scrolling_image(img)
+        assert helper.cached_image is img
+
+    def test_sets_cached_array(self, helper):
+        img = _make_image(width=200)
+        helper.set_scrolling_image(img)
+        assert helper.cached_array is not None
+
+    def test_scroll_width_matches_image(self, helper):
+        img = _make_image(width=300)
+        helper.set_scrolling_image(img)
+        assert helper.total_scroll_width == 300
+
+    def test_none_clears_cache(self, helper):
+        helper.set_scrolling_image(_make_image())
+        helper.set_scrolling_image(None)
+        assert helper.cached_image is None
+
+
+# ---------------------------------------------------------------------------
+# update_scroll_position (time-based mode)
+# ---------------------------------------------------------------------------
+
+class TestUpdateScrollPosition:
+    def test_position_advances_over_time(self, helper):
+        helper.create_scrolling_image([_make_image(width=200)])
+        helper.scroll_speed = 100.0  # 100 px/s
+        helper.last_update_time = time.time() - 0.1  # pretend 100ms elapsed
+        initial = helper.scroll_position
+        helper.update_scroll_position()
+        assert helper.scroll_position > initial
+
+    def test_no_advance_without_image(self, helper):
+        helper.update_scroll_position()  # no image, should not crash
+        assert helper.scroll_position == 0.0
+
+    def test_zero_width_content_stays_zero(self, helper):
+        helper.create_scrolling_image([])  # empty → width 0
+        helper.update_scroll_position()
+        assert helper.scroll_position == 0.0
+
+    def test_scroll_complete_clamped(self, helper):
+        helper.create_scrolling_image([_make_image(width=100)])
+        # Force position past the end
+        helper.scroll_position = helper.total_scroll_width + 50
+        helper.total_distance_scrolled = helper.total_scroll_width + 50
+        helper.update_scroll_position()
+        assert helper.scroll_complete is True
+        assert helper.scroll_position <= helper.total_scroll_width
+
+
+# ---------------------------------------------------------------------------
+# get_visible_portion
+# ---------------------------------------------------------------------------
+
+class TestGetVisiblePortion:
+    def test_returns_none_without_image(self, helper):
+        assert helper.get_visible_portion() is None
+
+    def test_returns_image_sized_to_display(self, helper):
+        helper.create_scrolling_image([_make_image(width=200)])
+        visible = helper.get_visible_portion()
+        assert visible is not None
+        assert visible.width == DISPLAY_W
+        assert visible.height == DISPLAY_H
+
+    def test_different_positions_give_different_images(self, helper):
+        helper.create_scrolling_image([_make_image(width=300)])
+        img1 = helper.get_visible_portion()
+        helper.scroll_position = 50
+        img2 = helper.get_visible_portion()
+        # Images should differ (colour from scrolled content)
+        # Just verify both are valid PIL images with correct size
+        assert img1.width == img2.width == DISPLAY_W
+
+
+# ---------------------------------------------------------------------------
+# reset_scroll / clear_cache
+# ---------------------------------------------------------------------------
+
+class TestResetAndClear:
+    def test_reset_restores_position(self, helper):
+        helper.create_scrolling_image([_make_image(width=200)])
+        helper.scroll_position = 100.0
+        helper.reset_scroll()
+        assert helper.scroll_position == 0.0
+
+    def test_reset_clears_complete_flag(self, helper):
+        helper.scroll_complete = True
+        helper.reset_scroll()
+        assert helper.scroll_complete is False
+
+    def test_reset_alias(self, helper):
+        helper.scroll_position = 50.0
+        helper.reset()
+        assert helper.scroll_position == 0.0
+
+    def test_clear_cache(self, helper):
+        helper.create_scrolling_image([_make_image()])
+        helper.clear_cache()
+        assert helper.cached_image is None
+        assert helper.cached_array is None
+        assert helper.total_scroll_width == 0
+
+
+# ---------------------------------------------------------------------------
+# calculate_dynamic_duration
+# ---------------------------------------------------------------------------
+
+class TestCalculateDynamicDuration:
+    def test_returns_min_when_disabled(self, helper):
+        helper.dynamic_duration_enabled = False
+        helper.min_duration = 30
+        result = helper.calculate_dynamic_duration()
+        assert result == 30
+
+    def test_returns_min_when_no_content(self, helper):
+        helper.total_scroll_width = 0
+        helper.min_duration = 30
+        result = helper.calculate_dynamic_duration()
+        assert result == 30
+
+    def test_respects_min_duration(self, helper):
+        helper.create_scrolling_image([_make_image(width=50)])
+        helper.min_duration = 60
+        helper.max_duration = 300
+        helper.scroll_speed = 500.0  # very fast → very short time
+        result = helper.calculate_dynamic_duration()
+        assert result >= 60
+
+    def test_respects_max_duration(self, helper):
+        helper.create_scrolling_image([_make_image(width=5000)])
+        helper.min_duration = 10
+        helper.max_duration = 60
+        helper.scroll_speed = 1.0  # very slow → very long time
+        result = helper.calculate_dynamic_duration()
+        assert result <= 60
+
+    def test_time_based_calculation(self, helper):
+        helper.create_scrolling_image([_make_image(width=200)])
+        helper.scroll_speed = 100.0
+        helper.min_duration = 1
+        helper.max_duration = 600
+        helper.frame_based_scrolling = False
+        result = helper.calculate_dynamic_duration()
+        assert isinstance(result, int)
+        assert result > 0
+
+
+# ---------------------------------------------------------------------------
+# set_* configuration methods
+# ---------------------------------------------------------------------------
+
+class TestSetMethods:
+    def test_set_scroll_speed_time_based(self, helper):
+        helper.frame_based_scrolling = False
+        helper.set_scroll_speed(50.0)
+        assert helper.scroll_speed == 50.0
+
+    def test_set_scroll_speed_clamped_low(self, helper):
+        helper.frame_based_scrolling = False
+        helper.set_scroll_speed(0.0)
+        assert helper.scroll_speed >= 1.0
+
+    def test_set_scroll_speed_clamped_high(self, helper):
+        helper.frame_based_scrolling = False
+        helper.set_scroll_speed(10000.0)
+        assert helper.scroll_speed <= 500.0
+
+    def test_set_scroll_delay(self, helper):
+        helper.set_scroll_delay(0.05)
+        assert helper.scroll_delay == 0.05
+
+    def test_set_scroll_delay_clamped(self, helper):
+        helper.set_scroll_delay(0.0001)
+        assert helper.scroll_delay >= 0.001
+
+    def test_set_target_fps(self, helper):
+        helper.set_target_fps(60.0)
+        assert helper.target_fps == 60.0
+
+    def test_set_target_fps_clamped(self, helper):
+        helper.set_target_fps(1000.0)
+        assert helper.target_fps <= 200.0
+
+    def test_set_sub_pixel_scrolling(self, helper):
+        helper.set_sub_pixel_scrolling(True)
+        assert helper.sub_pixel_scrolling is True
+        helper.set_sub_pixel_scrolling(False)
+        assert helper.sub_pixel_scrolling is False
+
+    def test_set_frame_based_scrolling(self, helper):
+        helper.set_frame_based_scrolling(True)
+        assert helper.frame_based_scrolling is True
+
+    def test_set_dynamic_duration_settings(self, helper):
+        helper.set_dynamic_duration_settings(enabled=True, min_duration=20, max_duration=120, buffer=0.2)
+        assert helper.dynamic_duration_enabled is True
+        assert helper.min_duration == 20
+        assert helper.max_duration == 120
+        assert helper.duration_buffer == pytest.approx(0.2)
+
+
+# ---------------------------------------------------------------------------
+# get_scroll_info
+# ---------------------------------------------------------------------------
+
+class TestGetScrollInfo:
+    def test_returns_dict(self, helper):
+        info = helper.get_scroll_info()
+        assert isinstance(info, dict)
+
+    def test_required_keys(self, helper):
+        info = helper.get_scroll_info()
+        for key in ("scroll_position", "total_distance_scrolled", "scroll_speed",
+                    "scroll_complete", "dynamic_duration"):
+            assert key in info
+
+    def test_scroll_position_reflected(self, helper):
+        helper.scroll_position = 42.0
+        info = helper.get_scroll_info()
+        assert info["scroll_position"] == 42.0

test/test_utils.py

@@ -0,0 +1,329 @@
+"""
+Tests for src/common/utils.py
+
+Covers all pure utility functions: normalize_team_abbreviation, format_time,
+format_date, get_timezone, validate_dimensions, parse_team_abbreviation,
+format_score, format_period, is_live_game, is_final_game, is_upcoming_game,
+sanitize_filename, truncate_text, parse_boolean.
+"""
+
+import pytest
+from datetime import datetime, timezone
+import pytz
+
+from src.common.utils import (
+    normalize_team_abbreviation,
+    format_time,
+    format_date,
+    get_timezone,
+    validate_dimensions,
+    parse_team_abbreviation,
+    format_score,
+    format_period,
+    is_live_game,
+    is_final_game,
+    is_upcoming_game,
+    sanitize_filename,
+    truncate_text,
+    parse_boolean,
+)
+
+
+# ---------------------------------------------------------------------------
+# normalize_team_abbreviation
+# ---------------------------------------------------------------------------
+
+class TestNormalizeTeamAbbreviation:
+    def test_basic_uppercase(self):
+        assert normalize_team_abbreviation("lal") == "LAL"
+
+    def test_strips_spaces(self):
+        assert normalize_team_abbreviation("  KC  ") == "KC"
+
+    def test_replaces_ampersand(self):
+        assert normalize_team_abbreviation("TA&M") == "TAANDM"
+
+    def test_removes_internal_spaces(self):
+        assert normalize_team_abbreviation("A B") == "AB"
+
+    def test_removes_hyphens(self):
+        assert normalize_team_abbreviation("A-B") == "AB"
+
+    def test_empty_string_returns_empty(self):
+        assert normalize_team_abbreviation("") == ""
+
+    def test_none_returns_empty(self):
+        assert normalize_team_abbreviation(None) == ""
+
+
+# ---------------------------------------------------------------------------
+# format_time / format_date
+# ---------------------------------------------------------------------------
+
+class TestFormatTime:
+    def _utc_dt(self, hour=20, minute=30):
+        return datetime(2024, 1, 15, hour, minute, 0, tzinfo=timezone.utc)
+
+    def test_formats_utc_to_utc(self):
+        dt = self._utc_dt(20, 30)
+        result = format_time(dt, timezone_str="UTC")
+        # 20:30 UTC → "8:30PM" (leading zero stripped)
+        assert "8:30PM" in result or "8:30 PM" in result or result != ""
+
+    def test_naive_datetime_treated_as_utc(self):
+        dt = datetime(2024, 1, 15, 12, 0, 0)  # naive
+        result = format_time(dt, timezone_str="UTC")
+        assert result != ""
+
+    def test_invalid_timezone_returns_empty(self):
+        dt = self._utc_dt()
+        result = format_time(dt, timezone_str="Invalid/TZ")
+        assert result == ""
+
+    def test_eastern_timezone(self):
+        dt = self._utc_dt(20, 0)  # 8 PM UTC = 3 PM ET
+        result = format_time(dt, timezone_str="America/New_York")
+        assert result != ""
+
+
+class TestFormatDate:
+    def test_formats_date(self):
+        dt = datetime(2024, 6, 15, 18, 0, 0, tzinfo=timezone.utc)
+        result = format_date(dt, timezone_str="UTC")
+        assert "June" in result or "15" in result
+
+    def test_naive_datetime(self):
+        dt = datetime(2024, 3, 10, 12, 0, 0)
+        result = format_date(dt, timezone_str="UTC")
+        assert result != ""
+
+    def test_invalid_timezone_returns_empty(self):
+        dt = datetime(2024, 6, 15, 18, 0, 0, tzinfo=timezone.utc)
+        result = format_date(dt, timezone_str="BadZone/Here")
+        assert result == ""
+
+
+# ---------------------------------------------------------------------------
+# get_timezone
+# ---------------------------------------------------------------------------
+
+class TestGetTimezone:
+    def test_valid_timezone(self):
+        tz = get_timezone("America/New_York")
+        assert tz is not None
+
+    def test_utc(self):
+        tz = get_timezone("UTC")
+        assert tz is pytz.utc or str(tz) == "UTC"
+
+    def test_invalid_returns_utc(self):
+        tz = get_timezone("Not/ATimezone")
+        assert tz is pytz.utc
+
+
+# ---------------------------------------------------------------------------
+# validate_dimensions
+# ---------------------------------------------------------------------------
+
+class TestValidateDimensions:
+    def test_valid(self):
+        assert validate_dimensions(64, 32) is True
+
+    def test_zero_width(self):
+        assert validate_dimensions(0, 32) is False
+
+    def test_zero_height(self):
+        assert validate_dimensions(64, 0) is False
+
+    def test_negative(self):
+        assert validate_dimensions(-1, 32) is False
+
+    def test_too_large(self):
+        assert validate_dimensions(1001, 32) is False
+
+    def test_max_valid(self):
+        assert validate_dimensions(1000, 1000) is True
+
+    def test_non_integer(self):
+        assert validate_dimensions("64", 32) is False  # type: ignore[arg-type]
+
+
+# ---------------------------------------------------------------------------
+# parse_team_abbreviation
+# ---------------------------------------------------------------------------
+
+class TestParseTeamAbbreviation:
+    def test_empty_string(self):
+        assert parse_team_abbreviation("") == ""
+
+    def test_none_returns_empty(self):
+        assert parse_team_abbreviation(None) == ""
+
+    def test_extracts_uppercase(self):
+        result = parse_team_abbreviation("LAL")
+        assert result == "LAL"
+
+    def test_fallback_first_three(self):
+        # text without recognisable 2-4 char uppercase block
+        result = parse_team_abbreviation("ab")
+        assert len(result) <= 3
+
+
+# ---------------------------------------------------------------------------
+# format_score
+# ---------------------------------------------------------------------------
+
+class TestFormatScore:
+    def test_format_score(self):
+        assert format_score(14, 7) == "7-14"
+
+    def test_format_score_strings(self):
+        assert format_score("21", "14") == "14-21"
+
+    def test_zero_zero(self):
+        assert format_score(0, 0) == "0-0"
+
+
+# ---------------------------------------------------------------------------
+# format_period
+# ---------------------------------------------------------------------------
+
+class TestFormatPeriod:
+    def test_basketball_q1(self):
+        assert format_period(1, "basketball") == "Q1"
+
+    def test_basketball_q4(self):
+        assert format_period(4, "basketball") == "Q4"
+
+    def test_basketball_ot1(self):
+        assert format_period(5, "basketball") == "OT1"
+
+    def test_basketball_ot2(self):
+        assert format_period(6, "basketball") == "OT2"
+
+    def test_football_q1(self):
+        assert format_period(1, "football") == "Q1"
+
+    def test_football_ot(self):
+        assert format_period(5, "football") == "OT1"
+
+    def test_hockey_p1(self):
+        assert format_period(1, "hockey") == "P1"
+
+    def test_hockey_p3(self):
+        assert format_period(3, "hockey") == "P3"
+
+    def test_hockey_ot(self):
+        assert format_period(4, "hockey") == "OT1"
+
+    def test_baseball_inning(self):
+        assert format_period(7, "baseball") == "INN 7"
+
+    def test_unknown_sport(self):
+        result = format_period(2, "unknown")
+        assert "2" in result
+
+
+# ---------------------------------------------------------------------------
+# is_live_game / is_final_game / is_upcoming_game
+# ---------------------------------------------------------------------------
+
+class TestGameStatusHelpers:
+    def test_is_live_game_true(self):
+        assert is_live_game("In Progress") is True
+        assert is_live_game("halftime") is True
+        assert is_live_game("overtime") is True
+
+    def test_is_live_game_false(self):
+        assert is_live_game("Final") is False
+        assert is_live_game("Scheduled") is False
+
+    def test_is_final_game_true(self):
+        assert is_final_game("Final") is True
+        assert is_final_game("COMPLETED") is True
+
+    def test_is_final_game_false(self):
+        assert is_final_game("In Progress") is False
+
+    def test_is_upcoming_game_true(self):
+        assert is_upcoming_game("Scheduled") is True
+        assert is_upcoming_game("upcoming") is True
+
+    def test_is_upcoming_game_false(self):
+        assert is_upcoming_game("Final") is False
+        assert is_upcoming_game("In Progress") is False
+
+
+# ---------------------------------------------------------------------------
+# sanitize_filename
+# ---------------------------------------------------------------------------
+
+class TestSanitizeFilename:
+    def test_removes_invalid_chars(self):
+        result = sanitize_filename('file<>:"/\\|?*.txt')
+        assert "<" not in result
+        assert ">" not in result
+        assert ":" not in result
+
+    def test_collapses_underscores(self):
+        result = sanitize_filename("file___name")
+        assert "__" not in result
+
+    def test_strips_leading_trailing(self):
+        result = sanitize_filename("_file_")
+        assert not result.startswith("_")
+        assert not result.endswith("_")
+
+    def test_normal_filename_unchanged(self):
+        result = sanitize_filename("my_logo")
+        assert result == "my_logo"
+
+
+# ---------------------------------------------------------------------------
+# truncate_text
+# ---------------------------------------------------------------------------
+
+class TestTruncateText:
+    def test_no_truncation_needed(self):
+        assert truncate_text("hello", 10) == "hello"
+
+    def test_truncation_adds_suffix(self):
+        result = truncate_text("hello world", 8)
+        assert result.endswith("...")
+        assert len(result) == 8
+
+    def test_exact_length(self):
+        assert truncate_text("hello", 5) == "hello"
+
+    def test_custom_suffix(self):
+        result = truncate_text("hello world", 8, suffix="~")
+        assert result.endswith("~")
+
+
+# ---------------------------------------------------------------------------
+# parse_boolean
+# ---------------------------------------------------------------------------
+
+class TestParseBoolean:
+    def test_true_bool(self):
+        assert parse_boolean(True) is True
+
+    def test_false_bool(self):
+        assert parse_boolean(False) is False
+
+    def test_int_1(self):
+        assert parse_boolean(1) is True
+
+    def test_int_0(self):
+        assert parse_boolean(0) is False
+
+    def test_string_true(self):
+        for val in ("true", "True", "TRUE", "1", "yes", "on", "enabled"):
+            assert parse_boolean(val) is True, f"Expected True for {val!r}"
+
+    def test_string_false(self):
+        for val in ("false", "False", "0", "no", "off", "disabled"):
+            assert parse_boolean(val) is False, f"Expected False for {val!r}"
+
+    def test_none_returns_false(self):
+        assert parse_boolean(None) is False  # type: ignore[arg-type]

test/test_vegas_config.py

@@ -0,0 +1,310 @@
+"""
+Tests for src/vegas_mode/config.py
+
+Covers VegasModeConfig: from_config, to_dict, get_frame_interval,
+is_plugin_included, get_ordered_plugins, validate, update.
+"""
+
+import pytest
+from src.vegas_mode.config import VegasModeConfig
+
+
+# ---------------------------------------------------------------------------
+# Default construction
+# ---------------------------------------------------------------------------
+
+class TestVegasModeConfigDefaults:
+    def test_default_disabled(self):
+        cfg = VegasModeConfig()
+        assert cfg.enabled is False
+
+    def test_default_scroll_speed(self):
+        cfg = VegasModeConfig()
+        assert cfg.scroll_speed == 50.0
+
+    def test_default_separator_width(self):
+        cfg = VegasModeConfig()
+        assert cfg.separator_width == 32
+
+    def test_default_target_fps(self):
+        cfg = VegasModeConfig()
+        assert cfg.target_fps == 125
+
+    def test_default_plugin_order_empty(self):
+        cfg = VegasModeConfig()
+        assert cfg.plugin_order == []
+
+    def test_default_excluded_plugins_empty(self):
+        cfg = VegasModeConfig()
+        assert len(cfg.excluded_plugins) == 0
+
+
+# ---------------------------------------------------------------------------
+# from_config
+# ---------------------------------------------------------------------------
+
+class TestFromConfig:
+    def _cfg(self, **kwargs) -> dict:
+        return {"display": {"vegas_scroll": kwargs}}
+
+    def test_enabled_flag(self):
+        cfg = VegasModeConfig.from_config(self._cfg(enabled=True))
+        assert cfg.enabled is True
+
+    def test_scroll_speed(self):
+        cfg = VegasModeConfig.from_config(self._cfg(scroll_speed=80.0))
+        assert cfg.scroll_speed == 80.0
+
+    def test_separator_width(self):
+        cfg = VegasModeConfig.from_config(self._cfg(separator_width=16))
+        assert cfg.separator_width == 16
+
+    def test_plugin_order(self):
+        cfg = VegasModeConfig.from_config(self._cfg(plugin_order=["a", "b", "c"]))
+        assert cfg.plugin_order == ["a", "b", "c"]
+
+    def test_excluded_plugins(self):
+        cfg = VegasModeConfig.from_config(self._cfg(excluded_plugins=["x", "y"]))
+        assert "x" in cfg.excluded_plugins
+        assert "y" in cfg.excluded_plugins
+
+    def test_target_fps(self):
+        cfg = VegasModeConfig.from_config(self._cfg(target_fps=60))
+        assert cfg.target_fps == 60
+
+    def test_buffer_ahead(self):
+        cfg = VegasModeConfig.from_config(self._cfg(buffer_ahead=3))
+        assert cfg.buffer_ahead == 3
+
+    def test_min_max_cycle_duration(self):
+        cfg = VegasModeConfig.from_config(self._cfg(min_cycle_duration=30, max_cycle_duration=120))
+        assert cfg.min_cycle_duration == 30
+        assert cfg.max_cycle_duration == 120
+
+    def test_defaults_when_missing(self):
+        cfg = VegasModeConfig.from_config({})
+        assert cfg.enabled is False
+        assert cfg.scroll_speed == 50.0
+
+    def test_frame_based_scrolling(self):
+        cfg = VegasModeConfig.from_config(self._cfg(frame_based_scrolling=False))
+        assert cfg.frame_based_scrolling is False
+
+
+# ---------------------------------------------------------------------------
+# to_dict
+# ---------------------------------------------------------------------------
+
+class TestToDict:
+    def test_roundtrip(self):
+        original = VegasModeConfig(
+            enabled=True,
+            scroll_speed=75.0,
+            separator_width=24,
+            plugin_order=["a", "b"],
+            excluded_plugins={"z"},
+            target_fps=100,
+        )
+        d = original.to_dict()
+        assert d["enabled"] is True
+        assert d["scroll_speed"] == 75.0
+        assert d["separator_width"] == 24
+        assert d["plugin_order"] == ["a", "b"]
+        assert "z" in d["excluded_plugins"]
+        assert d["target_fps"] == 100
+
+    def test_excluded_plugins_is_list(self):
+        cfg = VegasModeConfig(excluded_plugins={"x"})
+        d = cfg.to_dict()
+        assert isinstance(d["excluded_plugins"], list)
+
+    def test_all_keys_present(self):
+        d = VegasModeConfig().to_dict()
+        for key in ("enabled", "scroll_speed", "separator_width", "plugin_order",
+                    "excluded_plugins", "target_fps", "buffer_ahead",
+                    "frame_based_scrolling", "scroll_delay",
+                    "dynamic_duration_enabled", "min_cycle_duration", "max_cycle_duration"):
+            assert key in d
+
+
+# ---------------------------------------------------------------------------
+# get_frame_interval
+# ---------------------------------------------------------------------------
+
+class TestGetFrameInterval:
+    def test_125fps(self):
+        cfg = VegasModeConfig(target_fps=125)
+        assert abs(cfg.get_frame_interval() - 1.0 / 125) < 1e-9
+
+    def test_60fps(self):
+        cfg = VegasModeConfig(target_fps=60)
+        assert abs(cfg.get_frame_interval() - 1.0 / 60) < 1e-6
+
+    def test_zero_fps_guarded(self):
+        cfg = VegasModeConfig(target_fps=0)
+        # Should not raise ZeroDivisionError (max(1, fps) guard)
+        result = cfg.get_frame_interval()
+        assert result == 1.0
+
+
+# ---------------------------------------------------------------------------
+# is_plugin_included
+# ---------------------------------------------------------------------------
+
+class TestIsPluginIncluded:
+    def test_not_excluded_is_included(self):
+        cfg = VegasModeConfig(excluded_plugins={"bad_plugin"})
+        assert cfg.is_plugin_included("good_plugin") is True
+
+    def test_excluded_plugin_not_included(self):
+        cfg = VegasModeConfig(excluded_plugins={"bad_plugin"})
+        assert cfg.is_plugin_included("bad_plugin") is False
+
+    def test_empty_exclusions_all_included(self):
+        cfg = VegasModeConfig()
+        assert cfg.is_plugin_included("anything") is True
+
+
+# ---------------------------------------------------------------------------
+# get_ordered_plugins
+# ---------------------------------------------------------------------------
+
+class TestGetOrderedPlugins:
+    def test_natural_order_when_no_order_configured(self):
+        cfg = VegasModeConfig()
+        available = ["a", "b", "c"]
+        result = cfg.get_ordered_plugins(available)
+        assert result == ["a", "b", "c"]
+
+    def test_explicit_order_followed(self):
+        cfg = VegasModeConfig(plugin_order=["c", "a", "b"])
+        available = ["a", "b", "c"]
+        result = cfg.get_ordered_plugins(available)
+        assert result == ["c", "a", "b"]
+
+    def test_unavailable_plugins_skipped(self):
+        cfg = VegasModeConfig(plugin_order=["c", "x", "a"])
+        available = ["a", "b", "c"]
+        result = cfg.get_ordered_plugins(available)
+        assert "x" not in result
+        assert result[:2] == ["c", "a"]
+
+    def test_excluded_plugins_removed(self):
+        cfg = VegasModeConfig(excluded_plugins={"b"})
+        available = ["a", "b", "c"]
+        result = cfg.get_ordered_plugins(available)
+        assert "b" not in result
+
+    def test_unordered_available_appended(self):
+        cfg = VegasModeConfig(plugin_order=["a"])
+        available = ["a", "b", "c"]
+        result = cfg.get_ordered_plugins(available)
+        assert result[0] == "a"
+        assert "b" in result
+        assert "c" in result
+
+    def test_empty_available(self):
+        cfg = VegasModeConfig(plugin_order=["a"])
+        result = cfg.get_ordered_plugins([])
+        assert result == []
+
+
+# ---------------------------------------------------------------------------
+# validate
+# ---------------------------------------------------------------------------
+
+class TestValidate:
+    def test_valid_config_no_errors(self):
+        cfg = VegasModeConfig()
+        errors = cfg.validate()
+        assert errors == []
+
+    def test_scroll_speed_too_low(self):
+        cfg = VegasModeConfig(scroll_speed=0.5)
+        errors = cfg.validate()
+        assert any("scroll_speed" in e for e in errors)
+
+    def test_scroll_speed_too_high(self):
+        cfg = VegasModeConfig(scroll_speed=300.0)
+        errors = cfg.validate()
+        assert any("scroll_speed" in e for e in errors)
+
+    def test_separator_width_negative(self):
+        cfg = VegasModeConfig(separator_width=-1)
+        errors = cfg.validate()
+        assert any("separator_width" in e for e in errors)
+
+    def test_separator_width_too_large(self):
+        cfg = VegasModeConfig(separator_width=200)
+        errors = cfg.validate()
+        assert any("separator_width" in e for e in errors)
+
+    def test_target_fps_too_low(self):
+        cfg = VegasModeConfig(target_fps=10)
+        errors = cfg.validate()
+        assert any("target_fps" in e for e in errors)
+
+    def test_target_fps_too_high(self):
+        cfg = VegasModeConfig(target_fps=300)
+        errors = cfg.validate()
+        assert any("target_fps" in e for e in errors)
+
+    def test_buffer_ahead_too_low(self):
+        cfg = VegasModeConfig(buffer_ahead=0)
+        errors = cfg.validate()
+        assert any("buffer_ahead" in e for e in errors)
+
+    def test_buffer_ahead_too_high(self):
+        cfg = VegasModeConfig(buffer_ahead=10)
+        errors = cfg.validate()
+        assert any("buffer_ahead" in e for e in errors)
+
+    def test_multiple_errors_returned(self):
+        cfg = VegasModeConfig(scroll_speed=0.1, target_fps=5)
+        errors = cfg.validate()
+        assert len(errors) >= 2
+
+
+# ---------------------------------------------------------------------------
+# update
+# ---------------------------------------------------------------------------
+
+class TestUpdate:
+    def _wrap(self, **kwargs) -> dict:
+        return {"display": {"vegas_scroll": kwargs}}
+
+    def test_update_enabled(self):
+        cfg = VegasModeConfig(enabled=False)
+        cfg.update(self._wrap(enabled=True))
+        assert cfg.enabled is True
+
+    def test_update_scroll_speed(self):
+        cfg = VegasModeConfig(scroll_speed=50.0)
+        cfg.update(self._wrap(scroll_speed=90.0))
+        assert cfg.scroll_speed == 90.0
+
+    def test_update_separator_width(self):
+        cfg = VegasModeConfig(separator_width=32)
+        cfg.update(self._wrap(separator_width=8))
+        assert cfg.separator_width == 8
+
+    def test_update_plugin_order(self):
+        cfg = VegasModeConfig(plugin_order=[])
+        cfg.update(self._wrap(plugin_order=["x", "y"]))
+        assert cfg.plugin_order == ["x", "y"]
+
+    def test_update_excluded_plugins(self):
+        cfg = VegasModeConfig()
+        cfg.update(self._wrap(excluded_plugins=["skip_me"]))
+        assert "skip_me" in cfg.excluded_plugins
+
+    def test_update_ignores_missing_keys(self):
+        cfg = VegasModeConfig(scroll_speed=50.0)
+        cfg.update(self._wrap(target_fps=80))  # only fps, not speed
+        assert cfg.scroll_speed == 50.0
+        assert cfg.target_fps == 80
+
+    def test_empty_update_no_change(self):
+        cfg = VegasModeConfig(scroll_speed=50.0)
+        cfg.update({})
+        assert cfg.scroll_speed == 50.0

web_interface/app.py

@@ -2,8 +2,10 @@ from flask import Flask, request, redirect, url_for, jsonify, Response, send_fro
 import json
 import logging
 import os
+import queue
 import sys
 import subprocess
+import threading
 import time
 from pathlib import Path
 from datetime import datetime, timedelta
@@ -204,24 +206,12 @@ def serve_plugin_asset(plugin_id, filename):
         # Use send_from_directory to serve the file
         return send_from_directory(str(assets_dir), filename, mimetype=content_type)
         
-    except Exception as e:
-        # Log the exception with full traceback server-side
-        import traceback
+    except Exception:
         app.logger.exception('Error serving plugin asset file')
-        
-        # Return generic error message to client (avoid leaking internal details)
-        # Only include detailed error information when in debug mode
-        if app.debug:
-            return jsonify({
-                'status': 'error',
-                'message': str(e),
-                'traceback': traceback.format_exc()
-            }), 500
-        else:
-            return jsonify({
-                'status': 'error',
-                'message': 'Internal server error'
-            }), 500
+        return jsonify({
+            'status': 'error',
+            'message': 'Internal server error'
+        }), 500
 
 # Prime psutil CPU measurement once at startup so interval=None returns a real value
 try:
@@ -342,35 +332,25 @@ def not_found_error(error):
 @app.errorhandler(500)
 def internal_error(error):
     """Handle 500 errors."""
-    import traceback
-    error_details = traceback.format_exc()
-    
-    # Log the error
     import logging
     logger = logging.getLogger('web_interface')
-    logger.error(f"Internal server error: {error}", exc_info=True)
-    
-    # Return user-friendly error (hide internal details in production)
+    logger.error("Internal server error", exc_info=True)
     return jsonify({
         'status': 'error',
         'error_code': 'INTERNAL_ERROR',
-        'message': 'An internal error occurred',
-        'details': error_details if app.debug else None
+        'message': 'An internal error occurred; see logs for details',
     }), 500
 
 @app.errorhandler(Exception)
 def handle_exception(error):
     """Handle all unhandled exceptions."""
-    import traceback
     import logging
     logger = logging.getLogger('web_interface')
-    logger.error(f"Unhandled exception: {error}", exc_info=True)
-    
+    logger.error("Unhandled exception", exc_info=True)
     return jsonify({
         'status': 'error',
         'error_code': 'UNKNOWN_ERROR',
-        'message': str(error) if app.debug else 'An error occurred',
-        'details': traceback.format_exc() if app.debug else None
+        'message': 'An error occurred; see logs for details',
     }), 500
 
 # Captive portal redirect middleware
@@ -435,13 +415,53 @@ def add_security_headers(response):
     
     return response
 
-# SSE helper function
-def sse_response(generator_func):
-    """Helper to create SSE responses"""
-    def generate():
-        for data in generator_func():
-            yield f"data: {json.dumps(data)}\n\n"
-    return Response(generate(), mimetype='text/event-stream')
+class _StreamBroadcaster:
+    """Fan-out broadcaster: one background generator thread pushes to all SSE clients.
+
+    This means N browser tabs share one generator instead of each running their own,
+    keeping PIL encodes / subprocess forks constant regardless of how many tabs are open.
+    """
+
+    def __init__(self, generator_factory):
+        self._generator_factory = generator_factory
+        self._clients: set = set()
+        self._lock = threading.Lock()
+        self._thread: threading.Thread | None = None
+
+    def subscribe(self) -> queue.Queue:
+        q: queue.Queue = queue.Queue(maxsize=5)
+        with self._lock:
+            self._clients.add(q)
+            if not (self._thread and self._thread.is_alive()):
+                self._thread = threading.Thread(target=self._broadcast, daemon=True)
+                self._thread.start()
+        return q
+
+    def unsubscribe(self, q: queue.Queue) -> None:
+        with self._lock:
+            self._clients.discard(q)
+
+    def _broadcast(self):
+        for data in self._generator_factory():
+            with self._lock:
+                if not self._clients:
+                    # No subscribers — exit so the thread doesn't spin indefinitely.
+                    # subscribe() will restart it when a new client arrives.
+                    break
+                for q in self._clients:
+                    try:
+                        q.put_nowait(data)
+                    except queue.Full:
+                        # Client is reading too slowly; drop the oldest item and
+                        # deliver the latest so the queue never stalls the client.
+                        try:
+                            q.get_nowait()
+                        except queue.Empty:
+                            pass
+                        try:
+                            q.put_nowait(data)
+                        except queue.Full:
+                            pass
 
 # System status generator for SSE
 def system_status_generator():
@@ -492,7 +512,8 @@ def system_status_generator():
             }
             yield status
         except Exception as e:
-            yield {'error': str(e)}
+            app.logger.error("SSE generator error", exc_info=True)
+            yield {'error': 'An error occurred; see server logs'}
         time.sleep(10)  # Update every 10 seconds (reduced frequency for better performance)
 
 # Display preview generator for SSE
@@ -555,7 +576,8 @@ def display_preview_generator():
                 }
                 
         except Exception as e:
-            yield {'error': str(e)}
+            app.logger.error("SSE generator error", exc_info=True)
+            yield {'error': 'An error occurred; see server logs'}
         
         time.sleep(1.0)  # Check once per second — halves PIL encode overhead vs 0.5s
 
@@ -598,36 +620,68 @@ def logs_generator():
             except subprocess.TimeoutExpired:
                 # Timeout - just skip this update
                 pass
-            except Exception as e:
+            except Exception:
+                app.logger.error("Error running journalctl", exc_info=True)
                 error_data = {
                     'timestamp': time.time(),
-                    'logs': f'Error running journalctl: {str(e)}'
+                    'logs': 'Error running journalctl; see server logs'
                 }
                 yield error_data
 
-        except Exception as e:
+        except Exception:
+            app.logger.error("Unexpected error in logs generator", exc_info=True)
             error_data = {
                 'timestamp': time.time(),
-                'logs': f'Unexpected error in logs generator: {str(e)}'
+                'logs': 'Unexpected error in logs generator; see server logs'
             }
             yield error_data
 
         time.sleep(5)  # Update every 5 seconds (reduced frequency for better performance)
 
+# One broadcaster per stream — shared across all SSE clients
+_stats_broadcaster = _StreamBroadcaster(system_status_generator)
+_display_broadcaster = _StreamBroadcaster(display_preview_generator)
+_logs_broadcaster = _StreamBroadcaster(logs_generator)
+
+
+def _sse_stream(broadcaster: _StreamBroadcaster) -> Response:
+    """Return a streaming SSE response backed by a shared broadcaster."""
+    q = broadcaster.subscribe()
+
+    def generate():
+        try:
+            while True:
+                try:
+                    data = q.get(timeout=30)
+                    yield f"data: {json.dumps(data)}\n\n"
+                except queue.Empty:
+                    # Send an SSE comment heartbeat to keep the connection alive
+                    # through proxies that close idle connections.
+                    yield ": heartbeat\n\n"
+        except GeneratorExit:
+            pass
+        finally:
+            broadcaster.unsubscribe(q)
+
+    return Response(generate(), mimetype='text/event-stream')
+
+
 # SSE endpoints
 @app.route('/api/v3/stream/stats')
 def stream_stats():
-    return sse_response(system_status_generator)
+    return _sse_stream(_stats_broadcaster)
 
 @app.route('/api/v3/stream/display')
 def stream_display():
-    return sse_response(display_preview_generator)
+    return _sse_stream(_display_broadcaster)
 
 @app.route('/api/v3/stream/logs')
 def stream_logs():
-    return sse_response(logs_generator)
+    return _sse_stream(_logs_broadcaster)
 
-# Exempt SSE streams from CSRF and add rate limiting
+# Exempt SSE streams from CSRF and apply a generous rate limit.
+# SSE connections are long-lived HTTP requests, not repeated API calls, so the
+# tight "20 per minute" default would be exhausted quickly on reconnects.
 if csrf:
     csrf.exempt(stream_stats)
     csrf.exempt(stream_display)
@@ -635,9 +689,9 @@ if csrf:
     # Note: api_v3 blueprint is exempted above after registration
 
 if limiter:
-    limiter.limit("20 per minute")(stream_stats)
-    limiter.limit("20 per minute")(stream_display)
-    limiter.limit("20 per minute")(stream_logs)
+    limiter.limit("200 per minute")(stream_stats)
+    limiter.limit("200 per minute")(stream_display)
+    limiter.limit("200 per minute")(stream_logs)
 
 # Main route - redirect to v3 interface as default
 @app.route('/')

web_interface/blueprints/pages_v3.py

@@ -2,6 +2,8 @@ from flask import Blueprint, render_template, flash
 from markupsafe import escape
 import json
 import logging
+import os
+import re
 from pathlib import Path
 from src.web_interface.secret_helpers import mask_secret_fields
 
@@ -84,10 +86,11 @@ def load_partial(partial_name):
         elif partial_name == 'operation-history':
             return _load_operation_history_partial()
         else:
-            return f"Partial '{partial_name}' not found", 404
+            return "Partial not found", 404
 
     except Exception as e:
-        return f"Error loading partial '{partial_name}': {str(e)}", 500
+        logger.error("Error loading partial %s", partial_name, exc_info=True)
+        return "Error loading partial", 500
 
 
 @pages_v3.route('/partials/plugin-config/<plugin_id>')
@@ -95,8 +98,9 @@ def load_plugin_config_partial(plugin_id):
     """Load plugin configuration partial via HTMX - server-side rendered form"""
     try:
         return _load_plugin_config_partial(plugin_id)
-    except Exception as e:
-        return f'<div class="text-red-500 p-4">Error loading plugin config: {escape(str(e))}</div>', 500
+    except Exception:
+        logger.error("Error loading plugin config partial for %s", plugin_id, exc_info=True)
+        return '<div class="text-red-500 p-4">Error loading plugin config; see logs for details</div>', 500
 
 def _load_overview_partial():
     """Load overview partial with system stats"""
@@ -107,7 +111,8 @@ def _load_overview_partial():
             return render_template('v3/partials/overview.html',
                                  main_config=main_config)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_general_partial():
     """Load general settings partial"""
@@ -117,7 +122,8 @@ def _load_general_partial():
             return render_template('v3/partials/general.html',
                                  main_config=main_config)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_display_partial():
     """Load display settings partial"""
@@ -127,7 +133,8 @@ def _load_display_partial():
             return render_template('v3/partials/display.html',
                                  main_config=main_config)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_durations_partial():
     """Load display durations partial"""
@@ -137,7 +144,8 @@ def _load_durations_partial():
             return render_template('v3/partials/durations.html',
                                  main_config=main_config)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_schedule_partial():
     """Load schedule settings partial"""
@@ -153,7 +161,8 @@ def _load_schedule_partial():
                                  dim_schedule_config=dim_schedule_config,
                                  normal_brightness=normal_brightness)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 
 def _load_weather_partial():
@@ -164,7 +173,8 @@ def _load_weather_partial():
             return render_template('v3/partials/weather.html',
                                  main_config=main_config)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_stocks_partial():
     """Load stocks configuration partial"""
@@ -174,7 +184,8 @@ def _load_stocks_partial():
             return render_template('v3/partials/stocks.html',
                                  main_config=main_config)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_plugins_partial():
     """Load plugins management partial"""
@@ -208,7 +219,7 @@ def _load_plugins_partial():
                             plugin_info.update(fresh_manifest)
                         except Exception as e:
                             # If we can't read the fresh manifest, use the cached one
-                            print(f"Warning: Could not read fresh manifest for {plugin_id}: {e}")
+                            logger.warning("Could not read fresh manifest for plugin: %s", plugin_id)
 
                     # Get enabled status from config (source of truth)
                     # Read from config file first, fall back to plugin instance if config doesn't have the key
@@ -256,12 +267,13 @@ def _load_plugins_partial():
                         'branch': branch
                     })
             except Exception as e:
-                print(f"Error loading plugin data: {e}")
+                logger.error("Error loading plugin data", exc_info=True)
 
         return render_template('v3/partials/plugins.html',
                              plugins=plugins_data)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_fonts_partial():
     """Load fonts management partial"""
@@ -271,14 +283,16 @@ def _load_fonts_partial():
         return render_template('v3/partials/fonts.html',
                              fonts=fonts_data)
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_logs_partial():
     """Load logs viewer partial"""
     try:
         return render_template('v3/partials/logs.html')
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_raw_json_partial():
     """Load raw JSON editor partial"""
@@ -295,14 +309,16 @@ def _load_raw_json_partial():
                                  main_config_path=pages_v3.config_manager.get_config_path(),
                                  secrets_config_path=pages_v3.config_manager.get_secrets_path())
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_backup_restore_partial():
     """Load backup & restore partial."""
     try:
         return render_template('v3/partials/backup_restore.html')
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 @pages_v3.route('/setup')
 def captive_setup():
@@ -314,21 +330,24 @@ def _load_wifi_partial():
     try:
         return render_template('v3/partials/wifi.html')
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_cache_partial():
     """Load cache management partial"""
     try:
         return render_template('v3/partials/cache.html')
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 def _load_operation_history_partial():
     """Load operation history partial"""
     try:
         return render_template('v3/partials/operation_history.html')
     except Exception as e:
-        return f"Error: {str(e)}", 500
+        logger.error("Error loading partial", exc_info=True)
+        return "Error loading partial", 500
 
 
 def _load_plugin_config_partial(plugin_id):
@@ -336,6 +355,11 @@ def _load_plugin_config_partial(plugin_id):
     Load plugin configuration partial - server-side rendered form.
     This replaces the client-side generateConfigForm() JavaScript.
     """
+    # Sanitize with basename (CodeQL-recognized sanitizer) then regex-validate format
+    plugin_id = os.path.basename(plugin_id or '')
+    if not re.match(r'^[a-zA-Z0-9][a-zA-Z0-9._\-:]*$', plugin_id):
+        return '<div class="text-red-500 p-4">Invalid plugin ID</div>', 400
+
     try:
         if not pages_v3.plugin_manager:
             return '<div class="text-red-500 p-4">Plugin manager not available</div>', 500
@@ -344,80 +368,85 @@ def _load_plugin_config_partial(plugin_id):
         if plugin_id.startswith('starlark:'):
             return _load_starlark_config_partial(plugin_id[len('starlark:'):])
 
+        # Resolve and validate all plugin paths against the plugins base directory
+        _plugins_base = Path(pages_v3.plugin_manager.plugins_dir).resolve()
+        _plugin_dir = (_plugins_base / plugin_id).resolve()
+        try:
+            _plugin_dir.relative_to(_plugins_base)
+        except ValueError:
+            return '<div class="text-red-500 p-4">Invalid plugin ID</div>', 400
+
         # Try to get plugin info first
         plugin_info = pages_v3.plugin_manager.get_plugin_info(plugin_id)
-        
+
         # If not found, re-discover plugins (handles plugins added after startup)
         if not plugin_info:
             pages_v3.plugin_manager.discover_plugins()
             plugin_info = pages_v3.plugin_manager.get_plugin_info(plugin_id)
-        
+
         if not plugin_info:
-            return f'<div class="text-red-500 p-4">Plugin "{escape(plugin_id)}" not found</div>', 404
-        
+            return '<div class="text-red-500 p-4">Plugin not found</div>', 404
+
         # Get plugin instance (may be None if not loaded)
         plugin_instance = pages_v3.plugin_manager.get_plugin(plugin_id)
-        
+
         # Get plugin configuration from config file
         config = {}
         if pages_v3.config_manager:
             full_config = pages_v3.config_manager.load_config()
             config = full_config.get(plugin_id, {})
-        
+
         # Load uploaded images from metadata file if images field exists in schema
-        # This ensures uploaded images appear even if config hasn't been saved yet
-        schema_path_temp = Path(pages_v3.plugin_manager.plugins_dir) / plugin_id / "config_schema.json"
+        schema_path_temp = _plugin_dir / "config_schema.json"
         if schema_path_temp.exists():
             try:
                 with open(schema_path_temp, 'r', encoding='utf-8') as f:
                     temp_schema = json.load(f)
-                    # Check if schema has an images field with x-widget: file-upload
                     if (temp_schema.get('properties', {}).get('images', {}).get('x-widget') == 'file-upload' or
                         temp_schema.get('properties', {}).get('images', {}).get('x_widget') == 'file-upload'):
-                        # Load metadata file
-                        # Get PROJECT_ROOT relative to this file
-                        project_root = Path(__file__).parent.parent.parent
-                        metadata_file = project_root / 'assets' / 'plugins' / plugin_id / 'uploads' / '.metadata.json'
-                        if metadata_file.exists():
+                        _assets_base = (Path(__file__).parent.parent.parent / 'assets' / 'plugins').resolve()
+                        metadata_file = (_assets_base / plugin_id / 'uploads' / '.metadata.json').resolve()
+                        try:
+                            metadata_file.relative_to(_assets_base)
+                        except ValueError:
+                            metadata_file = None
+                        if metadata_file and metadata_file.exists():
                             try:
                                 with open(metadata_file, 'r', encoding='utf-8') as mf:
                                     metadata = json.load(mf)
-                                    # Convert metadata dict to list of image objects
                                     images_from_metadata = list(metadata.values())
-                                    # Only use metadata images if config doesn't have images or config images is empty
                                     if not config.get('images') or len(config.get('images', [])) == 0:
                                         config['images'] = images_from_metadata
                                     else:
-                                        # Merge: add metadata images that aren't already in config
                                         config_image_ids = {img.get('id') for img in config.get('images', []) if img.get('id')}
                                         new_images = [img for img in images_from_metadata if img.get('id') not in config_image_ids]
                                         if new_images:
                                             config['images'] = config.get('images', []) + new_images
                             except Exception as e:
-                                print(f"Warning: Could not load metadata for {plugin_id}: {e}")
+                                logger.warning("Could not load plugin upload metadata: %s", e)
             except Exception as e:  # nosec B110 - metadata pre-load is optional; schema loads fully below
                 logger.debug("Metadata pre-load skipped for plugin %s: %s", plugin_id, e)
-        
+
         # Get plugin schema
         schema = {}
-        schema_path = Path(pages_v3.plugin_manager.plugins_dir) / plugin_id / "config_schema.json"
+        schema_path = _plugin_dir / "config_schema.json"
         if schema_path.exists():
             try:
                 with open(schema_path, 'r', encoding='utf-8') as f:
                     schema = json.load(f)
             except Exception as e:
-                print(f"Warning: Could not load schema for {plugin_id}: {e}")
-        
+                logger.warning("Could not load schema for plugin: %s", e)
+
         # Get web UI actions from plugin manifest
         web_ui_actions = []
-        manifest_path = Path(pages_v3.plugin_manager.plugins_dir) / plugin_id / "manifest.json"
+        manifest_path = _plugin_dir / "manifest.json"
         if manifest_path.exists():
             try:
                 with open(manifest_path, 'r', encoding='utf-8') as f:
                     manifest = json.load(f)
                     web_ui_actions = manifest.get('web_ui_actions', [])
             except Exception as e:
-                print(f"Warning: Could not load manifest for {plugin_id}: {e}")
+                logger.warning("Could not load manifest for plugin: %s", e)
         
         # Mask secret fields before rendering template (fail closed — never leak secrets)
         schema_properties = schema.get('properties') if isinstance(schema, dict) else None
@@ -453,20 +482,24 @@ def _load_plugin_config_partial(plugin_id):
         )
         
     except Exception as e:
-        import traceback
-        traceback.print_exc()
-        return f'<div class="text-red-500 p-4">Error loading plugin config: {escape(str(e))}</div>', 500
+        logger.error("Error loading plugin config partial for %s", plugin_id, exc_info=True)
+        return '<div class="text-red-500 p-4">Error loading plugin config; see logs for details</div>', 500
 
 
 def _load_starlark_config_partial(app_id):
     """Load configuration partial for a Starlark app."""
+    # Sanitize with basename (CodeQL-recognized sanitizer) then regex-validate format
+    app_id = os.path.basename(app_id or '')
+    if not re.match(r'^[a-zA-Z0-9][a-zA-Z0-9_\-]*$', app_id):
+        return '<div class="text-red-500 p-4">Invalid app ID</div>', 400
+
     try:
         starlark_plugin = pages_v3.plugin_manager.get_plugin('starlark-apps') if pages_v3.plugin_manager else None
 
         if starlark_plugin and hasattr(starlark_plugin, 'apps'):
             app = starlark_plugin.apps.get(app_id)
             if not app:
-                return f'<div class="text-red-500 p-4">Starlark app not found: {app_id}</div>', 404
+                return '<div class="text-red-500 p-4">Starlark app not found</div>', 404
             return render_template(
                 'v3/partials/starlark_config.html',
                 app_id=app_id,
@@ -482,36 +515,45 @@ def _load_starlark_config_partial(app_id):
             )
 
         # Standalone: read from manifest file
-        manifest_file = Path(__file__).resolve().parent.parent.parent / 'starlark-apps' / 'manifest.json'
+        starlark_base = (Path(__file__).resolve().parent.parent.parent / 'starlark-apps').resolve()
+        manifest_file = starlark_base / 'manifest.json'
         if not manifest_file.exists():
-            return f'<div class="text-red-500 p-4">Starlark app not found: {app_id}</div>', 404
+            return '<div class="text-red-500 p-4">Starlark app not found</div>', 404
 
         with open(manifest_file, 'r') as f:
             manifest = json.load(f)
 
         app_data = manifest.get('apps', {}).get(app_id)
         if not app_data:
-            return f'<div class="text-red-500 p-4">Starlark app not found: {app_id}</div>', 404
+            return '<div class="text-red-500 p-4">Starlark app not found</div>', 404
 
-        # Load schema from schema.json if it exists
+        # Load schema from schema.json if it exists — validate path stays within starlark_base
         schema = None
-        schema_file = Path(__file__).resolve().parent.parent.parent / 'starlark-apps' / app_id / 'schema.json'
-        if schema_file.exists():
+        schema_file = (starlark_base / app_id / 'schema.json').resolve()
+        try:
+            schema_file.relative_to(starlark_base)
+        except ValueError:
+            schema_file = None
+        if schema_file and schema_file.exists():
             try:
                 with open(schema_file, 'r') as f:
                     schema = json.load(f)
             except (OSError, json.JSONDecodeError) as e:
-                logger.warning(f"[Pages V3] Could not load schema for {app_id}: {e}", exc_info=True)
+                logger.warning("Could not load starlark schema for app: %s", e)
 
-        # Load config from config.json if it exists
+        # Load config from config.json if it exists — validate path stays within starlark_base
         config = {}
-        config_file = Path(__file__).resolve().parent.parent.parent / 'starlark-apps' / app_id / 'config.json'
-        if config_file.exists():
+        config_file = (starlark_base / app_id / 'config.json').resolve()
+        try:
+            config_file.relative_to(starlark_base)
+        except ValueError:
+            config_file = None
+        if config_file and config_file.exists():
             try:
                 with open(config_file, 'r') as f:
                     config = json.load(f)
             except (OSError, json.JSONDecodeError) as e:
-                logger.warning(f"[Pages V3] Could not load config for {app_id}: {e}", exc_info=True)
+                logger.warning("Could not load starlark config for app: %s", e)
 
         return render_template(
             'v3/partials/starlark_config.html',
@@ -528,5 +570,5 @@ def _load_starlark_config_partial(app_id):
         )
 
     except Exception as e:
-        logger.exception(f"[Pages V3] Error loading starlark config for {app_id}")
-        return f'<div class="text-red-500 p-4">Error loading starlark config: {str(e)}</div>', 500
+        logger.error("[Pages V3] Error loading starlark config for app", exc_info=True)
+        return '<div class="text-red-500 p-4">Error loading starlark config; see logs for details</div>', 500

web_interface/static/v3/app.js

@@ -1,4 +1,4 @@
-/* global showNotification, updateSystemStats, htmx */
+/* global showNotification, updateSystemStats, updateDisplayPreview, htmx */
 // LED Matrix v3 JavaScript
 // Additional helpers for HTMX and Alpine.js integration
 
@@ -51,7 +51,8 @@ document.body.addEventListener('htmx:afterRequest', function(event) {
     }
 });
 
-// SSE reconnection helper
+// SSE reconnection helper — closes and reopens both SSE streams,
+// reattaching the open/error handlers defined in base.html.
 window.reconnectSSE = function() {
     if (window.statsSource) {
         window.statsSource.close();
@@ -60,14 +61,18 @@ window.reconnectSSE = function() {
             const data = JSON.parse(event.data);
             if (typeof updateSystemStats === 'function') updateSystemStats(data);
         };
+        if (window._statsOpenHandler) window.statsSource.addEventListener('open', window._statsOpenHandler);
+        if (window._statsErrorHandler) window.statsSource.addEventListener('error', window._statsErrorHandler);
     }
 
     if (window.displaySource) {
         window.displaySource.close();
         window.displaySource = new EventSource('/api/v3/stream/display');
-        window.displaySource.onmessage = function() {
-            // Handle display updates
+        window.displaySource.onmessage = function(event) {
+            const data = JSON.parse(event.data);
+            if (typeof updateDisplayPreview === 'function') updateDisplayPreview(data);
         };
+        if (window._displayErrorHandler) window.displaySource.addEventListener('error', window._displayErrorHandler);
     }
 };
 

web_interface/static/v3/js/widgets/base-widget.js

@@ -51,8 +51,10 @@
         sanitizeValue(value) {
             // Base implementation - widgets should override for specific needs
             if (typeof value === 'string') {
-                // Basic XSS prevention
-                return value.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '');
+                // Strip all HTML tags via the DOM parser to prevent XSS
+                const div = document.createElement('div');
+                div.textContent = value;
+                return div.textContent;
             }
             return value;
         }

web_interface/static/v3/js/widgets/json-file-manager.js

@@ -0,0 +1,782 @@
+/**
+ * JsonFileManager — reusable JSON file management widget for LEDMatrix plugins.
+ *
+ * Usage via config_schema.json:
+ *   "file_manager": {
+ *     "type": "null",
+ *     "title": "Data Files",
+ *     "x-widget": "json-file-manager",
+ *     "x-widget-config": {
+ *       "actions": {
+ *         "list":   "list-files",   // required
+ *         "get":    "get-file",     // required for editing
+ *         "save":   "save-file",    // required for editing
+ *         "upload": "upload-file",  // optional
+ *         "delete": "delete-file",  // optional
+ *         "create": "create-file",  // optional
+ *         "toggle": "toggle-category" // optional
+ *       },
+ *       "upload_hint":      "Hint text under the drop zone",
+ *       "directory_label":  "of_the_day/",
+ *       "create_fields": [
+ *         { "key": "category_name", "label": "Category Name",
+ *           "placeholder": "my_words", "pattern": "^[a-z0-9_]+$",
+ *           "hint": "Used as filename" },
+ *         { "key": "display_name", "label": "Display Name",
+ *           "placeholder": "My Words" }
+ *       ],
+ *       "toggle_key": "category_name"
+ *     }
+ *   }
+ *
+ * No CDN dependencies. Works on all modern browsers.
+ */
+(function () {
+    'use strict';
+
+    class JsonFileManager {
+        constructor(container, config, pluginId) {
+            // Prevent duplicate instances on the same container
+            if (container._jfmInstance) {
+                container._jfmInstance._destroy();
+            }
+            container._jfmInstance = this;
+
+            this.el         = container;
+            this.pluginId   = pluginId;
+            this.actions    = config.actions || {};
+            this.uploadHint = config.upload_hint || '';
+            this.dirLabel   = config.directory_label || '';
+            this.createFields = config.create_fields || [];
+            this.toggleKey  = config.toggle_key || null;
+
+            // Unique prefix for all DOM IDs in this instance
+            this._uid = 'jfm_' + Math.random().toString(36).slice(2, 9);
+
+            // Mutable state
+            this._editFile   = null;
+            this._deleteFile = null;
+            this._keyHandler = this._onKey.bind(this);
+
+            this._inject();
+            this._bind();
+            this._loadList();
+        }
+
+        // ── Lifecycle ────────────────────────────────────────────────────────
+
+        _destroy() {
+            document.removeEventListener('keydown', this._keyHandler);
+            this.el._jfmInstance = null;
+        }
+
+        // ── DOM Injection ────────────────────────────────────────────────────
+
+        _inject() {
+            const u = this._uid;
+            const hasUpload = !!this.actions.upload;
+            const hasCreate = !!this.actions.create;
+            const hasDelete = !!this.actions.delete;
+
+            this.el.innerHTML = this._css(u) + `
+<div id="${u}" class="jfm">
+
+  <div class="jfm-header">
+    <div class="jfm-header-left">
+      <span class="jfm-title">Data Files</span>
+      ${this.dirLabel ? `<code class="jfm-dir">${this._esc(this.dirLabel)}</code>` : ''}
+    </div>
+    <div class="jfm-header-right">
+      ${hasCreate ? `<button class="jfm-btn jfm-btn-primary jfm-btn-sm" data-jfm="open-create">+ New File</button>` : ''}
+      <button class="jfm-btn jfm-btn-ghost jfm-btn-sm" data-jfm="refresh" title="Refresh file list">&#8635;</button>
+    </div>
+  </div>
+
+  <div id="${u}-list" class="jfm-list">
+    <div class="jfm-loading"><span class="jfm-spin"></span> Loading…</div>
+  </div>
+
+  ${hasUpload ? `
+  <div class="jfm-upload-wrap">
+    <input type="file" accept=".json" id="${u}-fileinput" tabindex="-1">
+    <div class="jfm-dropzone" id="${u}-dropzone" data-jfm="open-picker" role="button" tabindex="0"
+         aria-label="Upload JSON file">
+      <span class="jfm-drop-icon">&#128193;</span>
+      <p class="jfm-drop-primary">Drop a JSON file here, or click to browse</p>
+      ${this.uploadHint ? `<p class="jfm-drop-hint">${this._esc(this.uploadHint)}</p>` : ''}
+    </div>
+  </div>` : ''}
+
+  <!-- ── Edit modal ─────────────────────────────────────── -->
+  <div class="jfm-modal" id="${u}-edit-modal" role="dialog" aria-modal="true" hidden>
+    <div class="jfm-modal-box jfm-modal-wide">
+      <div class="jfm-modal-head">
+        <span id="${u}-edit-title" class="jfm-modal-title">Edit file</span>
+        <div class="jfm-modal-tools">
+          <button class="jfm-btn jfm-btn-ghost jfm-btn-sm" data-jfm="fmt">Format</button>
+          <button class="jfm-btn jfm-btn-ghost jfm-btn-sm" data-jfm="validate">Validate</button>
+          <button class="jfm-close-btn" data-jfm="close-edit" aria-label="Close">&times;</button>
+        </div>
+      </div>
+      <div id="${u}-edit-err" class="jfm-err-bar" hidden></div>
+      <textarea id="${u}-editor" class="jfm-editor"
+                spellcheck="false" autocomplete="off"
+                autocorrect="off" autocapitalize="off"
+                aria-label="JSON editor"></textarea>
+      <div class="jfm-modal-foot">
+        <span id="${u}-charcount" class="jfm-stat"></span>
+        <button class="jfm-btn jfm-btn-ghost" data-jfm="close-edit">Cancel</button>
+        <button class="jfm-btn jfm-btn-primary" data-jfm="save" id="${u}-save-btn">Save</button>
+      </div>
+    </div>
+  </div>
+
+  <!-- ── Delete modal ───────────────────────────────────── -->
+  ${hasDelete ? `
+  <div class="jfm-modal" id="${u}-del-modal" role="dialog" aria-modal="true" hidden>
+    <div class="jfm-modal-box">
+      <div class="jfm-modal-head">
+        <span class="jfm-modal-title">Delete file</span>
+        <button class="jfm-close-btn" data-jfm="close-del" aria-label="Close">&times;</button>
+      </div>
+      <div class="jfm-modal-body">
+        <p>Delete <strong id="${u}-del-name"></strong>?</p>
+        <p class="jfm-muted">This permanently removes the file and its entry from the plugin configuration.</p>
+      </div>
+      <div class="jfm-modal-foot">
+        <button class="jfm-btn jfm-btn-ghost" data-jfm="close-del">Cancel</button>
+        <button class="jfm-btn jfm-btn-danger" data-jfm="confirm-del" id="${u}-del-btn">Delete</button>
+      </div>
+    </div>
+  </div>` : ''}
+
+  <!-- ── Create modal ───────────────────────────────────── -->
+  ${hasCreate ? `
+  <div class="jfm-modal" id="${u}-create-modal" role="dialog" aria-modal="true" hidden>
+    <div class="jfm-modal-box">
+      <div class="jfm-modal-head">
+        <span class="jfm-modal-title">Create new file</span>
+        <button class="jfm-close-btn" data-jfm="close-create" aria-label="Close">&times;</button>
+      </div>
+      <div class="jfm-modal-body">
+        ${this.createFields.map(f => `
+        <div class="jfm-field">
+          <label for="${u}-cf-${this._esc(f.key)}">${this._esc(f.label)}</label>
+          <input type="text" id="${u}-cf-${this._esc(f.key)}"
+                 placeholder="${this._esc(f.placeholder || '')}"
+                 ${f.pattern ? `pattern="${this._esc(f.pattern)}"` : ''}>
+          ${f.hint ? `<span class="jfm-hint">${this._esc(f.hint)}</span>` : ''}
+        </div>`).join('')}
+      </div>
+      <div class="jfm-modal-foot">
+        <button class="jfm-btn jfm-btn-ghost" data-jfm="close-create">Cancel</button>
+        <button class="jfm-btn jfm-btn-primary" data-jfm="do-create" id="${u}-create-btn">Create</button>
+      </div>
+    </div>
+  </div>` : ''}
+
+</div>`;  // end #${u}
+
+            // Cache frequently-used elements
+            this._root        = document.getElementById(u);
+            this._listEl      = document.getElementById(`${u}-list`);
+            this._editorEl    = document.getElementById(`${u}-editor`);
+            this._editModal   = document.getElementById(`${u}-edit-modal`);
+            this._delModal    = document.getElementById(`${u}-del-modal`);
+            this._createModal = document.getElementById(`${u}-create-modal`);
+            this._dropzone    = document.getElementById(`${u}-dropzone`);
+            this._fileInput   = document.getElementById(`${u}-fileinput`);
+        }
+
+        _css(u) {
+            return `<style>
+#${u}{font-family:inherit;color:#111827;}
+#${u} *{box-sizing:border-box;}
+
+/* Header */
+#${u} .jfm-header{display:flex;justify-content:space-between;align-items:center;margin-bottom:.875rem;gap:.5rem;}
+#${u} .jfm-header-left{display:flex;align-items:center;gap:.5rem;flex-wrap:wrap;}
+#${u} .jfm-title{font-size:.9375rem;font-weight:600;color:#111827;}
+#${u} .jfm-dir{font-size:.75rem;color:#6b7280;background:#f3f4f6;padding:.125rem .375rem;border-radius:.25rem;font-family:monospace;}
+#${u} .jfm-header-right{display:flex;gap:.375rem;align-items:center;flex-shrink:0;}
+
+/* Buttons */
+#${u} .jfm-btn{display:inline-flex;align-items:center;gap:.25rem;padding:.4375rem .875rem;border-radius:.375rem;border:1px solid #d1d5db;background:#fff;color:#374151;font-size:.875rem;font-weight:500;cursor:pointer;transition:background .12s,border-color .12s,opacity .12s;line-height:1.25;}
+#${u} .jfm-btn:hover:not(:disabled){background:#f9fafb;border-color:#9ca3af;}
+#${u} .jfm-btn:focus-visible{outline:2px solid #3b82f6;outline-offset:1px;}
+#${u} .jfm-btn:disabled{opacity:.5;cursor:not-allowed;}
+#${u} .jfm-btn-sm{padding:.3125rem .625rem;font-size:.8125rem;}
+#${u} .jfm-btn-primary{background:#3b82f6;border-color:#3b82f6;color:#fff;}
+#${u} .jfm-btn-primary:hover:not(:disabled){background:#2563eb;border-color:#2563eb;}
+#${u} .jfm-btn-danger{background:#ef4444;border-color:#ef4444;color:#fff;}
+#${u} .jfm-btn-danger:hover:not(:disabled){background:#dc2626;border-color:#dc2626;}
+#${u} .jfm-btn-ghost{background:transparent;border-color:transparent;color:#6b7280;}
+#${u} .jfm-btn-ghost:hover:not(:disabled){background:#f3f4f6;color:#374151;}
+#${u} .jfm-close-btn{display:flex;align-items:center;justify-content:center;width:2rem;height:2rem;border:none;background:none;color:#9ca3af;font-size:1.25rem;cursor:pointer;border-radius:.25rem;padding:0;line-height:1;}
+#${u} .jfm-close-btn:hover{background:#f3f4f6;color:#374151;}
+
+/* File list */
+#${u} .jfm-list{display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:.625rem;margin-bottom:1rem;min-height:5rem;}
+#${u} .jfm-loading{grid-column:1/-1;display:flex;align-items:center;justify-content:center;gap:.5rem;padding:2rem;color:#6b7280;font-size:.875rem;}
+#${u} .jfm-empty{grid-column:1/-1;text-align:center;padding:2.5rem 1rem;color:#9ca3af;}
+#${u} .jfm-empty-icon{font-size:2.25rem;margin-bottom:.625rem;}
+#${u} .jfm-empty-title{font-weight:600;color:#374151;margin:0 0 .25rem;}
+#${u} .jfm-empty-sub{font-size:.875rem;margin:0;}
+
+/* File cards */
+#${u} .jfm-card{border:1px solid #e5e7eb;border-radius:.5rem;padding:.875rem;background:#fff;display:flex;flex-direction:column;gap:.5rem;transition:border-color .15s,box-shadow .15s;}
+#${u} .jfm-card:hover{border-color:#93c5fd;box-shadow:0 2px 8px rgba(59,130,246,.1);}
+#${u} .jfm-card.jfm-off{opacity:.6;}
+#${u} .jfm-card-top{display:flex;justify-content:space-between;align-items:flex-start;gap:.5rem;}
+#${u} .jfm-card-name{font-weight:600;font-size:.9375rem;word-break:break-word;color:#111827;flex:1;}
+#${u} .jfm-card-meta{font-size:.75rem;color:#6b7280;display:flex;flex-direction:column;gap:.125rem;line-height:1.5;}
+#${u} .jfm-card-actions{display:flex;gap:.375rem;padding-top:.5rem;border-top:1px solid #f3f4f6;margin-top:.125rem;}
+#${u} .jfm-card-actions .jfm-btn{flex:1;justify-content:center;}
+#${u} .jfm-card-actions .jfm-del{flex:0 0 auto;}
+
+/* Toggle */
+#${u} .jfm-toggle{display:flex;align-items:center;gap:.3125rem;font-size:.75rem;color:#6b7280;white-space:nowrap;flex-shrink:0;}
+#${u} .jfm-toggle input[type=checkbox]{width:.9375rem;height:.9375rem;cursor:pointer;accent-color:#22c55e;margin:0;}
+
+/* Upload zone */
+#${u} .jfm-upload-wrap{margin-top:.25rem;}
+#${u} input[type=file]#${u}-fileinput{position:absolute;left:-9999px;width:1px;height:1px;opacity:0;}
+#${u} .jfm-dropzone{border:2px dashed #d1d5db;border-radius:.5rem;padding:1.25rem 1rem;text-align:center;cursor:pointer;transition:border-color .15s,background .15s;background:#f9fafb;user-select:none;}
+#${u} .jfm-dropzone:hover,#${u} .jfm-dropzone:focus-visible,#${u} .jfm-dropzone.jfm-over{border-color:#3b82f6;background:#eff6ff;border-style:solid;outline:none;}
+#${u} .jfm-drop-icon{font-size:1.75rem;display:block;margin-bottom:.375rem;}
+#${u} .jfm-drop-primary{font-size:.875rem;color:#374151;margin:0 0 .25rem;}
+#${u} .jfm-drop-hint{font-size:.75rem;color:#9ca3af;margin:0;}
+
+/* Modals */
+#${u} .jfm-modal{position:fixed;inset:0;background:rgba(0,0,0,.45);z-index:9999;display:flex;align-items:center;justify-content:center;padding:1rem;backdrop-filter:blur(1px);}
+#${u} .jfm-modal[hidden]{display:none;}
+#${u} .jfm-modal-box{background:#fff;border-radius:.5rem;box-shadow:0 20px 40px rgba(0,0,0,.15);display:flex;flex-direction:column;width:100%;max-width:440px;max-height:92vh;}
+#${u} .jfm-modal-wide{max-width:880px;}
+#${u} .jfm-modal-head{display:flex;justify-content:space-between;align-items:center;padding:.875rem 1.125rem;border-bottom:1px solid #e5e7eb;flex-shrink:0;gap:.5rem;}
+#${u} .jfm-modal-title{font-weight:600;font-size:.9375rem;color:#111827;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
+#${u} .jfm-modal-tools{display:flex;gap:.25rem;align-items:center;flex-shrink:0;}
+#${u} .jfm-modal-body{padding:1.125rem;overflow-y:auto;flex:1;}
+#${u} .jfm-modal-foot{display:flex;gap:.5rem;justify-content:flex-end;align-items:center;padding:.75rem 1.125rem;border-top:1px solid #e5e7eb;flex-shrink:0;background:#f9fafb;border-radius:0 0 .5rem .5rem;}
+#${u} .jfm-stat{margin-right:auto;font-size:.75rem;color:#9ca3af;font-variant-numeric:tabular-nums;}
+
+/* JSON editor */
+#${u} .jfm-editor{display:block;width:100%;min-height:400px;height:58vh;max-height:64vh;resize:vertical;font-family:'Courier New',Consolas,ui-monospace,monospace;font-size:.8rem;line-height:1.55;padding:.75rem 1rem;border:none;border-radius:0;outline:none;white-space:pre;overflow:auto;color:#1e293b;background:#fafafa;tab-size:2;}
+#${u} .jfm-err-bar{background:#fef2f2;border-bottom:1px solid #fecaca;color:#991b1b;font-size:.8125rem;padding:.5rem 1.125rem;flex-shrink:0;line-height:1.4;}
+#${u} .jfm-err-bar[hidden]{display:none;}
+
+/* Create form */
+#${u} .jfm-field{margin-bottom:.875rem;}
+#${u} .jfm-field:last-child{margin-bottom:0;}
+#${u} .jfm-field label{display:block;font-size:.875rem;font-weight:500;color:#374151;margin-bottom:.3125rem;}
+#${u} .jfm-field input{width:100%;padding:.4375rem .75rem;border:1px solid #d1d5db;border-radius:.375rem;font-size:.875rem;color:#111827;background:#fff;}
+#${u} .jfm-field input:focus{outline:none;border-color:#3b82f6;box-shadow:0 0 0 3px rgba(59,130,246,.12);}
+#${u} .jfm-hint{display:block;font-size:.75rem;color:#9ca3af;margin-top:.25rem;}
+#${u} .jfm-muted{font-size:.875rem;color:#6b7280;margin-top:.375rem;}
+
+/* Spinner */
+#${u} .jfm-spin{display:inline-block;width:.9rem;height:.9rem;border:2px solid #e5e7eb;border-top-color:#3b82f6;border-radius:50%;animation:jfm-spin-${u} .6s linear infinite;vertical-align:middle;}
+@keyframes jfm-spin-${u}{to{transform:rotate(360deg);}}
+</style>`;
+        }
+
+        // ── Event Binding ────────────────────────────────────────────────────
+
+        _bind() {
+            // Delegated clicks on the widget root
+            this._root.addEventListener('click', this._onClick.bind(this));
+            this._root.addEventListener('change', this._onChange.bind(this));
+
+            // Drag-and-drop on the dropzone
+            if (this._dropzone) {
+                this._dropzone.addEventListener('dragover', e => {
+                    e.preventDefault();
+                    this._dropzone.classList.add('jfm-over');
+                });
+                this._dropzone.addEventListener('dragleave', () => {
+                    this._dropzone.classList.remove('jfm-over');
+                });
+                this._dropzone.addEventListener('drop', e => {
+                    e.preventDefault();
+                    this._dropzone.classList.remove('jfm-over');
+                    const file = e.dataTransfer?.files[0];
+                    if (file) this._uploadFile(file);
+                });
+                // Keyboard activation of drop zone
+                this._dropzone.addEventListener('keydown', e => {
+                    if (e.key === 'Enter' || e.key === ' ') {
+                        e.preventDefault();
+                        this._fileInput?.click();
+                    }
+                });
+            }
+
+            // Modal backdrop clicks
+            [this._editModal, this._delModal, this._createModal].forEach(m => {
+                if (m) m.addEventListener('click', e => { if (e.target === m) this._closeAll(); });
+            });
+
+            // Editor: char count + Tab indent
+            if (this._editorEl) {
+                this._editorEl.addEventListener('input', () => this._updateStat());
+                this._editorEl.addEventListener('keydown', e => {
+                    if (e.key === 'Tab') {
+                        e.preventDefault();
+                        const s = this._editorEl.selectionStart;
+                        const end = this._editorEl.selectionEnd;
+                        const v = this._editorEl.value;
+                        this._editorEl.value = v.slice(0, s) + '  ' + v.slice(end);
+                        this._editorEl.selectionStart = this._editorEl.selectionEnd = s + 2;
+                        this._updateStat();
+                    }
+                });
+            }
+
+            // Global keyboard shortcuts
+            document.addEventListener('keydown', this._keyHandler);
+        }
+
+        _onKey(e) {
+            const editOpen   = this._editModal   && !this._editModal.hidden;
+            const delOpen    = this._delModal    && !this._delModal.hidden;
+            const createOpen = this._createModal && !this._createModal.hidden;
+
+            if (e.key === 'Escape') {
+                if (editOpen)   { this._closeEdit();   return; }
+                if (delOpen)    { this._closeDel();    return; }
+                if (createOpen) { this._closeCreate(); return; }
+            }
+            if ((e.ctrlKey || e.metaKey) && e.key === 's' && editOpen) {
+                e.preventDefault();
+                this._doSave();
+            }
+        }
+
+        _onClick(e) {
+            const btn = e.target.closest('[data-jfm]');
+            if (!btn) return;
+            const action = btn.dataset.jfm;
+
+            switch (action) {
+                case 'refresh':      this._loadList(); break;
+                case 'open-picker':  this._fileInput?.click(); break;
+                case 'open-create':  this._openCreate(); break;
+                case 'close-edit':   this._closeEdit(); break;
+                case 'close-del':    this._closeDel(); break;
+                case 'close-create': this._closeCreate(); break;
+                case 'fmt':          this._formatJson(); break;
+                case 'validate':     this._validateJson(); break;
+                case 'save':         this._doSave(); break;
+                case 'confirm-del':  this._doDelete(); break;
+                case 'do-create':    this._doCreate(); break;
+                case 'edit-file': {
+                    const card = btn.closest('[data-jfm-file]');
+                    if (card) this._openEdit(card.dataset.jfmFile);
+                    break;
+                }
+                case 'del-file': {
+                    const card = btn.closest('[data-jfm-file]');
+                    if (card) this._openDel(card.dataset.jfmFile);
+                    break;
+                }
+            }
+        }
+
+        _onChange(e) {
+            // Toggle checkbox
+            if (e.target.classList.contains('jfm-toggle-cb')) {
+                const catName = e.target.dataset.cat;
+                const enabled = e.target.checked;
+                this._doToggle(catName, enabled, e.target);
+            }
+            // File input
+            if (e.target === this._fileInput) {
+                const file = e.target.files?.[0];
+                if (file) this._uploadFile(file);
+                e.target.value = '';
+            }
+        }
+
+        // ── API helper ───────────────────────────────────────────────────────
+
+        async _api(actionKey, params) {
+            const actionId = this.actions[actionKey];
+            if (!actionId) throw new Error(`Action "${actionKey}" not configured`);
+            const body = { plugin_id: this.pluginId, action_id: actionId };
+            if (params !== undefined) body.params = params;
+            const r = await fetch('/api/v3/plugins/action', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body)
+            });
+            if (!r.ok) throw new Error('Server error ' + r.status);
+            const ct = r.headers.get('content-type') || '';
+            if (!ct.includes('application/json')) {
+                const txt = await r.text();
+                throw new Error('Unexpected response: ' + txt.slice(0, 120));
+            }
+            return r.json();
+        }
+
+        // ── File List ────────────────────────────────────────────────────────
+
+        async _loadList() {
+            this._listEl.innerHTML = `<div class="jfm-loading"><span class="jfm-spin"></span> Loading…</div>`;
+            try {
+                const data = await this._api('list');
+                if (data.status !== 'success') throw new Error(data.message || 'Load failed');
+                this._renderList(data.files || []);
+            } catch (err) {
+                this._listEl.innerHTML = `
+                    <div class="jfm-empty">
+                        <div class="jfm-empty-icon">&#9888;</div>
+                        <p class="jfm-empty-title">Failed to load files</p>
+                        <p class="jfm-empty-sub">${this._esc(err.message)}</p>
+                    </div>`;
+            }
+        }
+
+        _renderList(files) {
+            if (!files.length) {
+                this._listEl.innerHTML = `
+                    <div class="jfm-empty">
+                        <div class="jfm-empty-icon">&#128193;</div>
+                        <p class="jfm-empty-title">No files yet</p>
+                        <p class="jfm-empty-sub">Upload or create a JSON file to get started</p>
+                    </div>`;
+                return;
+            }
+            this._listEl.innerHTML = files.map(f => this._card(f)).join('');
+        }
+
+        _card(f) {
+            const u           = this._uid;
+            const enabled     = f.enabled !== false;
+            const displayName = this._esc(f.display_name || f.filename);
+            const filename    = this._esc(f.filename);
+            const catName     = this.toggleKey ? this._esc(f[this.toggleKey] || '') : '';
+            const showToggle  = !!(this.actions.toggle && this.toggleKey && f[this.toggleKey]);
+            const hasEdit     = !!this.actions.get && !!this.actions.save;
+            const hasDelete   = !!this.actions.delete;
+
+            return `
+<div class="jfm-card${enabled ? '' : ' jfm-off'}" data-jfm-file="${filename}">
+  <div class="jfm-card-top">
+    <span class="jfm-card-name" title="${filename}">${displayName}</span>
+    ${showToggle ? `
+    <label class="jfm-toggle" title="${enabled ? 'Enabled — click to disable' : 'Disabled — click to enable'}">
+      <input type="checkbox" class="jfm-toggle-cb" data-cat="${catName}" ${enabled ? 'checked' : ''}>
+      <span>${enabled ? 'On' : 'Off'}</span>
+    </label>` : ''}
+  </div>
+  <div class="jfm-card-meta">
+    <span>&#128196; ${filename}</span>
+    <span>&#128202; ${f.entry_count ?? 0} entries &middot; ${this._fmtSize(f.size || 0)}</span>
+    <span>&#128337; ${this._fmtDate(f.modified)}</span>
+  </div>
+  <div class="jfm-card-actions">
+    ${hasEdit ? `<button class="jfm-btn jfm-btn-sm" data-jfm="edit-file">&#9998; Edit</button>` : ''}
+    ${hasDelete ? `<button class="jfm-btn jfm-btn-danger jfm-btn-sm jfm-del" data-jfm="del-file" title="Delete file">&#128465;</button>` : ''}
+  </div>
+</div>`;
+        }
+
+        // ── Edit flow ────────────────────────────────────────────────────────
+
+        async _openEdit(filename) {
+            this._editFile = filename;
+            document.getElementById(`${this._uid}-edit-title`).textContent = `Edit: ${filename}`;
+            this._clearErr();
+            this._editorEl.value = 'Loading…';
+            this._updateStat();
+            this._editModal.hidden = false;
+
+            try {
+                const data = await this._api('get', { filename });
+                if (data.status !== 'success') throw new Error(data.message || 'Load failed');
+                this._editorEl.value = JSON.stringify(data.content, null, 2);
+                this._updateStat();
+                this._editorEl.focus();
+                this._editorEl.setSelectionRange(0, 0);
+                this._editorEl.scrollTop = 0;
+            } catch (err) {
+                this._showErr('Failed to load file: ' + err.message);
+                this._editorEl.value = '';
+            }
+        }
+
+        _closeEdit() {
+            if (this._editModal) this._editModal.hidden = true;
+            this._editFile = null;
+            this._clearErr();
+        }
+
+        _formatJson() {
+            try {
+                const parsed = JSON.parse(this._editorEl.value);
+                this._editorEl.value = JSON.stringify(parsed, null, 2);
+                this._updateStat();
+                this._clearErr();
+            } catch (err) {
+                this._showErr('Invalid JSON — ' + err.message);
+            }
+        }
+
+        _validateJson() {
+            try {
+                const parsed = JSON.parse(this._editorEl.value);
+                const n = (typeof parsed === 'object' && parsed !== null) ? Object.keys(parsed).length : '?';
+                this._clearErr();
+                this._notify(`Valid JSON — ${n} top-level keys`, 'success');
+            } catch (err) {
+                this._showErr('Invalid JSON — ' + err.message);
+            }
+        }
+
+        async _doSave() {
+            if (!this._editFile) return;
+            let contentStr;
+            try {
+                const parsed = JSON.parse(this._editorEl.value);
+                contentStr = JSON.stringify(parsed, null, 2);
+            } catch (err) {
+                this._showErr('Cannot save — fix JSON first: ' + err.message);
+                return;
+            }
+            const btn = document.getElementById(`${this._uid}-save-btn`);
+            this._busy(btn, 'Saving…');
+            try {
+                const data = await this._api('save', { filename: this._editFile, content: contentStr });
+                if (data.status !== 'success') throw new Error(data.message || 'Save failed');
+                this._notify('File saved', 'success');
+                this._closeEdit();
+                this._loadList();
+            } catch (err) {
+                this._showErr('Save failed: ' + err.message);
+                this._idle(btn, 'Save');
+            }
+        }
+
+        // ── Delete flow ──────────────────────────────────────────────────────
+
+        _openDel(filename) {
+            this._deleteFile = filename;
+            const el = document.getElementById(`${this._uid}-del-name`);
+            if (el) el.textContent = filename;
+            if (this._delModal) this._delModal.hidden = false;
+        }
+
+        _closeDel() {
+            if (this._delModal) this._delModal.hidden = true;
+            this._deleteFile = null;
+        }
+
+        async _doDelete() {
+            if (!this._deleteFile) return;
+            const btn = document.getElementById(`${this._uid}-del-btn`);
+            this._busy(btn, 'Deleting…');
+            try {
+                const data = await this._api('delete', { filename: this._deleteFile });
+                if (data.status !== 'success') throw new Error(data.message || 'Delete failed');
+                this._notify('File deleted', 'success');
+                this._closeDel();
+                this._loadList();
+            } catch (err) {
+                this._notify('Delete failed: ' + err.message, 'error');
+                this._idle(btn, 'Delete');
+            }
+        }
+
+        // ── Create flow ──────────────────────────────────────────────────────
+
+        _openCreate() {
+            if (!this._createModal) return;
+            this.createFields.forEach(f => {
+                const el = document.getElementById(`${this._uid}-cf-${f.key}`);
+                if (el) el.value = '';
+            });
+            this._createModal.hidden = false;
+            const first = this.createFields[0];
+            if (first) document.getElementById(`${this._uid}-cf-${first.key}`)?.focus();
+        }
+
+        _closeCreate() {
+            if (this._createModal) this._createModal.hidden = true;
+        }
+
+        async _doCreate() {
+            const params = {};
+            for (const f of this.createFields) {
+                const el  = document.getElementById(`${this._uid}-cf-${f.key}`);
+                const val = (el?.value || '').trim();
+                if (!val) {
+                    this._notify(`"${f.label}" is required`, 'error');
+                    el?.focus();
+                    return;
+                }
+                if (f.pattern && !new RegExp(f.pattern).test(val)) {
+                    this._notify(`"${f.label}" format is invalid`, 'error');
+                    el?.focus();
+                    return;
+                }
+                params[f.key] = val;
+            }
+            // Auto-derive display_name from category_name if left blank
+            const nameField = this.createFields.find(f => f.key === 'display_name');
+            if (nameField) {
+                const el = document.getElementById(`${this._uid}-cf-display_name`);
+                if (el && !el.value.trim()) {
+                    const catEl = document.getElementById(`${this._uid}-cf-category_name`);
+                    if (catEl?.value) {
+                        params.display_name = catEl.value.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+                    }
+                }
+            }
+            const btn = document.getElementById(`${this._uid}-create-btn`);
+            this._busy(btn, 'Creating…');
+            try {
+                const data = await this._api('create', params);
+                if (data.status !== 'success') throw new Error(data.message || 'Create failed');
+                this._notify('File created', 'success');
+                this._closeCreate();
+                this._loadList();
+            } catch (err) {
+                this._notify('Create failed: ' + err.message, 'error');
+                this._idle(btn, 'Create');
+            }
+        }
+
+        // ── Upload ───────────────────────────────────────────────────────────
+
+        async _uploadFile(file) {
+            if (!file.name.endsWith('.json')) {
+                this._notify('Please select a .json file', 'error');
+                return;
+            }
+            let content;
+            try {
+                content = await file.text();
+                JSON.parse(content); // client-side validation
+            } catch (err) {
+                this._notify('Invalid JSON: ' + err.message, 'error');
+                return;
+            }
+            if (this._dropzone) this._dropzone.style.opacity = '.5';
+            try {
+                const data = await this._api('upload', { filename: file.name, content });
+                if (data.status !== 'success') throw new Error(data.message || 'Upload failed');
+                this._notify(`"${file.name}" uploaded`, 'success');
+                this._loadList();
+            } catch (err) {
+                this._notify('Upload failed: ' + err.message, 'error');
+            } finally {
+                if (this._dropzone) this._dropzone.style.opacity = '';
+            }
+        }
+
+        // ── Toggle ───────────────────────────────────────────────────────────
+
+        async _doToggle(catName, enabled, checkbox) {
+            checkbox.disabled = true;
+            try {
+                const params = { enabled };
+                if (this.toggleKey) params[this.toggleKey] = catName;
+                const data = await this._api('toggle', params);
+                if (data.status !== 'success') throw new Error(data.message || 'Toggle failed');
+                this._notify(enabled ? 'Category enabled' : 'Category disabled', 'success');
+                this._loadList();
+            } catch (err) {
+                this._notify('Toggle failed: ' + err.message, 'error');
+                checkbox.checked = !enabled; // revert
+                checkbox.disabled = false;
+            }
+        }
+
+        // ── Helpers ──────────────────────────────────────────────────────────
+
+        _closeAll() {
+            this._closeEdit();
+            this._closeDel();
+            this._closeCreate();
+        }
+
+        _updateStat() {
+            const v = this._editorEl?.value || '';
+            const lines = v ? v.split('\n').length : 0;
+            const el = document.getElementById(`${this._uid}-charcount`);
+            if (el) el.textContent = `${lines.toLocaleString()} lines · ${v.length.toLocaleString()} chars`;
+        }
+
+        _showErr(msg) {
+            const el = document.getElementById(`${this._uid}-edit-err`);
+            if (el) { el.textContent = msg; el.hidden = false; }
+        }
+
+        _clearErr() {
+            const el = document.getElementById(`${this._uid}-edit-err`);
+            if (el) { el.textContent = ''; el.hidden = true; }
+        }
+
+        _notify(msg, type) {
+            if (typeof window.showNotification === 'function') {
+                window.showNotification(msg, type || 'info');
+            } else {
+                console.info(`[JsonFileManager] ${type || 'info'}: ${msg}`);
+            }
+        }
+
+        _busy(btn, label) {
+            if (!btn) return;
+            btn._jfmOriginal = btn.innerHTML;
+            btn.disabled = true;
+            btn.innerHTML = `<span class="jfm-spin"></span> ${this._esc(label)}`;
+        }
+
+        _idle(btn, label) {
+            if (!btn) return;
+            btn.disabled = false;
+            btn.innerHTML = btn._jfmOriginal || this._esc(label);
+        }
+
+        _esc(str) {
+            const d = document.createElement('div');
+            d.textContent = String(str ?? '');
+            return d.innerHTML;
+        }
+
+        _fmtSize(bytes) {
+            if (!bytes) return '0 B';
+            const i = Math.min(Math.floor(Math.log2(bytes + 1) / 10), 2);
+            const unit = ['B', 'KB', 'MB'][i];
+            const val  = bytes / Math.pow(1024, i);
+            return (i ? val.toFixed(1) : val) + ' ' + unit;
+        }
+
+        _fmtDate(str) {
+            if (!str) return '—';
+            try {
+                return new Date(str).toLocaleDateString(undefined, {
+                    month: 'short', day: 'numeric', year: 'numeric'
+                });
+            } catch { return str; }
+        }
+    }
+
+    // ── Widget registry integration ──────────────────────────────────────────
+
+    window.JsonFileManager = JsonFileManager;
+
+    if (typeof window.LEDMatrixWidgets !== 'undefined') {
+        window.LEDMatrixWidgets.register('json-file-manager', {
+            name: 'JSON File Manager',
+            version: '1.0.0',
+            render(container, config, _value, options) {
+                new JsonFileManager(container, config || {}, options?.pluginId || '');
+            },
+            getValue() { return null; },
+            setValue() {}
+        });
+        console.log('[JsonFileManager] Registered with LEDMatrixWidgets');
+    } else {
+        console.log('[JsonFileManager] Loaded (LEDMatrixWidgets registry not available)');
+    }
+})();

web_interface/static/v3/plugins_manager.js

@@ -1442,9 +1442,14 @@ function renderInstalledPlugins(plugins) {
         return;
     }
 
-    // Helper function to escape attributes for use in HTML
+    // Helper function to escape values for use in HTML attributes
     const escapeAttr = (text) => {
-        return (text || '').replace(/'/g, "\\'").replace(/"/g, '"');
+        return (text || '')
+            .replace(/&/g, '&')
+            .replace(/"/g, '"')
+            .replace(/'/g, ''')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;');
     };
 
     // Helper function to escape for JavaScript strings (use JSON.stringify for proper escaping)
@@ -3441,6 +3446,23 @@ function generateFieldHtml(key, prop, value, prefix = '') {
             html += `<option value="${option}" ${selected}>${option}</option>`;
         });
         html += `</select>`;
+    } else if (prop['x-widget'] === 'json-file-manager') {
+        // Reusable JSON file manager widget (no CDN, keyboard shortcuts, configurable actions)
+        const widgetConfig = prop['x-widget-config'] || {};
+        const pluginId = currentPluginConfig?.pluginId || window.currentPluginConfig?.pluginId || '';
+        const safeFieldId = (fullKey || 'file_manager').replace(/[^a-zA-Z0-9_-]/g, '_');
+
+        html += `<div id="${safeFieldId}_jfm_mount"></div>`;
+
+        setTimeout(() => {
+            const mount = document.getElementById(`${safeFieldId}_jfm_mount`);
+            if (!mount) return;
+            if (typeof JsonFileManager !== 'undefined') {
+                new JsonFileManager(mount, widgetConfig, pluginId);
+            } else {
+                mount.innerHTML = '<p style="color:#dc2626;font-size:.875rem;">json-file-manager widget not loaded. Check base.html includes json-file-manager.js.</p>';
+            }
+        }, 150);
     } else if (prop['x-widget'] === 'custom-html') {
         // Custom HTML widget - load HTML from plugin directory
         const htmlFile = prop['x-html-file'];
@@ -4507,6 +4529,8 @@ function syncFormToJson() {
     // Deep merge with existing config to preserve nested structures
     function deepMerge(target, source) {
         for (const key in source) {
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+            if (!Object.prototype.hasOwnProperty.call(source, key)) continue;
             if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
                 if (!target[key] || typeof target[key] !== 'object' || Array.isArray(target[key])) {
                     target[key] = {};
@@ -7473,17 +7497,28 @@ setTimeout(function() {
         console.log('installed-plugins-grid not found yet, will retry via event listeners');
     }
 
-    // Also try to attach install button handler after a delay (fallback)
+    // Also try to attach install button handler after a delay (fallback).
+    // Only run if the install button element is already in the DOM (i.e. the
+    // plugins partial has been loaded); otherwise the htmx:afterSettle listener
+    // below handles it when the tab is first visited.
     setTimeout(() => {
-        if (typeof window.attachInstallButtonHandler === 'function') {
-            console.log('[FALLBACK] Attempting to attach install button handler...');
+        if (typeof window.attachInstallButtonHandler === 'function' &&
+            document.getElementById('install-plugin-from-url')) {
             window.attachInstallButtonHandler();
-        } else {
-            console.warn('[FALLBACK] attachInstallButtonHandler not available on window');
         }
     }, 500);
 }, 200);
 
+// Re-run install button wiring after HTMX settles the plugins tab content.
+// Guard with element check so it only fires when the plugins partial is in the DOM,
+// preventing spurious warnings on other tab loads.
+document.addEventListener('htmx:afterSettle', function() {
+    if (document.getElementById('install-plugin-from-url') &&
+        typeof window.attachInstallButtonHandler === 'function') {
+        window.attachInstallButtonHandler();
+    }
+});
+
 // ─── Starlark Apps Integration ──────────────────────────────────────────────
 
 (function() {

web_interface/templates/v3/base.html

@@ -136,6 +136,7 @@
                                 setTimeout(function() {
                                     if (typeof htmx !== 'undefined') {
                                         console.log('HTMX loaded from fallback');
+                                        window.dispatchEvent(new Event('htmx:ready'));
                                         // Load extensions after core loads
                                         loadScript(sseSrc, isAPMode ? 'https://unpkg.com/htmx.org/dist/ext/sse.js' : '/static/v3/js/htmx-sse.js');
                                         loadScript(jsonEncSrc, isAPMode ? 'https://unpkg.com/htmx.org/dist/ext/json-enc.js' : '/static/v3/js/htmx-json-enc.js');
@@ -152,6 +153,7 @@
                         }
                     } else {
                         console.log('HTMX loaded successfully');
+                        window.dispatchEvent(new Event('htmx:ready'));
                         // Load extensions after core loads
                         loadScript(sseSrc, isAPMode ? 'https://unpkg.com/htmx.org/dist/ext/sse.js' : '/static/v3/js/htmx-sse.js');
                         loadScript(jsonEncSrc, isAPMode ? 'https://unpkg.com/htmx.org/dist/ext/json-enc.js' : '/static/v3/js/htmx-json-enc.js');
@@ -349,6 +351,20 @@
                             }
                         }
                     });
+
+                    // Set data-loaded on tab containers after HTMX settles their content,
+                    // preventing repeated re-fetches on every tab switch.
+                    // Scoped to elements with hx-trigger="revealed" (tab containers only) so
+                    // modals and plugin config panels that legitimately reload are unaffected.
+                    document.body.addEventListener('htmx:afterSettle', function(event) {
+                        if (event.detail && event.detail.target) {
+                            var target = event.detail.target;
+                            var trigger = target.getAttribute('hx-trigger') || '';
+                            if (trigger.includes('revealed')) {
+                                target.setAttribute('data-loaded', 'true');
+                            }
+                        }
+                    });
                 } else {
                     if (document.readyState === 'loading') {
                         document.addEventListener('DOMContentLoaded', setupScriptExecution);
@@ -411,6 +427,9 @@
                     .then(html => {
                         clearTimeout(timeout);
                         content.innerHTML = html;
+                        if (typeof htmx !== 'undefined') {
+                            htmx.process(content);
+                        }
                         // Trigger full initialization chain
                         if (window.pluginManager) {
                             window.pluginManager.initialized = false;
@@ -430,7 +449,7 @@
         }
 
         // Fallback if HTMX doesn't load within 5 seconds
-        setTimeout(() => {
+        var _pluginsFallbackTimer = setTimeout(() => {
             if (typeof htmx === 'undefined') {
                 console.warn('HTMX not loaded after 5 seconds, using direct fetch for plugins');
                 // Load plugins tab content directly regardless of active tab,
@@ -438,6 +457,7 @@
                 loadPluginsDirect();
             }
         }, 5000);
+        window.addEventListener('htmx:ready', function() { clearTimeout(_pluginsFallbackTimer); }, { once: true });
     </script>
     <!-- Alpine.js app function - defined early so it's available when Alpine initializes -->
     <script>
@@ -1030,6 +1050,9 @@
                             .then(html => {
                                 overviewContent.innerHTML = html;
                                 overviewContent.setAttribute('data-loaded', 'true');
+                                if (typeof htmx !== 'undefined') {
+                                    htmx.process(overviewContent);
+                                }
                                 // Re-initialize Alpine.js for the new content
                                 if (window.Alpine) {
                                     window.Alpine.initTree(overviewContent);
@@ -1058,7 +1081,7 @@
                 });
                 
                 // Also try direct load if HTMX doesn't load within 5 seconds
-                setTimeout(() => {
+                var _overviewFallbackTimer = setTimeout(() => {
                     if (typeof htmx === 'undefined') {
                         console.warn('HTMX not loaded after 5 seconds, using direct fetch for content');
                         const appElement = document.querySelector('[x-data="app()"]');
@@ -1070,6 +1093,7 @@
                         }
                     }
                 }, 5000);
+                window.addEventListener('htmx:ready', function() { clearTimeout(_overviewFallbackTimer); }, { once: true });
             </script>
 
             <!-- General tab -->
@@ -1346,34 +1370,64 @@
 
     <!-- SSE connection for real-time updates -->
     <script>
-        // Connect to SSE streams
-        const statsSource = new EventSource('/api/v3/stream/stats');
-        const displaySource = new EventSource('/api/v3/stream/display');
+        // Assign to window so reconnectSSE() in app.js can reach them.
+        window.statsSource = new EventSource('/api/v3/stream/stats');
+        window.displaySource = new EventSource('/api/v3/stream/display');
 
-        statsSource.onmessage = function(event) {
+        window.statsSource.onmessage = function(event) {
             const data = JSON.parse(event.data);
             updateSystemStats(data);
         };
 
-        displaySource.onmessage = function(event) {
+        window.displaySource.onmessage = function(event) {
             const data = JSON.parse(event.data);
             updateDisplayPreview(data);
         };
 
-        // Connection status
-        statsSource.addEventListener('open', function() {
-            document.getElementById('connection-status').innerHTML = `
-                <div class="w-2 h-2 bg-green-500 rounded-full"></div>
-                <span class="text-gray-600">Connected</span>
-            `;
-        });
+        function _setConnectionStatus(connected, reconnecting) {
+            const el = document.getElementById('connection-status');
+            if (!el) return;
+            if (connected) {
+                el.innerHTML = `
+                    <div class="w-2 h-2 bg-green-500 rounded-full"></div>
+                    <span class="text-gray-600">Connected</span>
+                `;
+            } else if (reconnecting) {
+                el.innerHTML = `
+                    <div class="w-2 h-2 bg-yellow-500 rounded-full animate-pulse"></div>
+                    <span class="text-gray-600">Reconnecting…</span>
+                `;
+            } else {
+                el.innerHTML = `
+                    <div class="w-2 h-2 bg-red-500 rounded-full"></div>
+                    <span class="text-gray-600" title="Connection lost — try refreshing the page">Disconnected</span>
+                `;
+            }
+        }
 
-        statsSource.addEventListener('error', function() {
-            document.getElementById('connection-status').innerHTML = `
-                <div class="w-2 h-2 bg-red-500 rounded-full"></div>
-                <span class="text-gray-600">Disconnected</span>
-            `;
-        });
+        var _statsErrorCount = 0;
+
+        // Named on window so reconnectSSE() in app.js can reattach them after
+        // replacing the EventSource instances.
+        window._statsOpenHandler = function() {
+            _statsErrorCount = 0;
+            _setConnectionStatus(true, false);
+        };
+        window._statsErrorHandler = function() {
+            _statsErrorCount++;
+            // EventSource readyState 0 = CONNECTING (auto-retrying), 2 = CLOSED
+            var reconnecting = window.statsSource.readyState === EventSource.CONNECTING;
+            _setConnectionStatus(false, reconnecting && _statsErrorCount <= 3);
+        };
+        window._displayErrorHandler = function() {
+            // Display stream errors don't change the status badge but log to console
+            // so failures aren't completely silent.
+            console.warn('LEDMatrix: display preview stream error (readyState=' + window.displaySource.readyState + ')');
+        };
+
+        window.statsSource.addEventListener('open', window._statsOpenHandler);
+        window.statsSource.addEventListener('error', window._statsErrorHandler);
+        window.displaySource.addEventListener('error', window._displayErrorHandler);
 
         function updateSystemStats(data) {
             // Update CPU in header
@@ -1816,13 +1870,18 @@
                             htmx.trigger(contentEl, 'revealed');
                         }
                     } else {
-                        // HTMX not available, use direct fetch
-                        console.warn('HTMX not available, using direct fetch for tab:', tab);
-                        if (tab === 'overview' && typeof loadOverviewDirect === 'function') {
-                            loadOverviewDirect();
-                        } else if (tab === 'wifi' && typeof loadWifiDirect === 'function') {
-                            loadWifiDirect();
+                        // HTMX is still loading asynchronously — retry when it signals ready,
+                        // or fall back to direct fetch if it fails to load entirely.
+                        const self = this;
+                        function onReady() { window.removeEventListener('htmx-load-failed', onFailed); self.loadTabContent(tab); }
+                        function onFailed() {
+                            window.removeEventListener('htmx:ready', onReady);
+                            if (tab === 'overview' && typeof loadOverviewDirect === 'function') loadOverviewDirect();
+                            else if (tab === 'wifi' && typeof loadWifiDirect === 'function') loadWifiDirect();
+                            else if (tab === 'plugins' && typeof loadPluginsDirect === 'function') loadPluginsDirect();
                         }
+                        window.addEventListener('htmx:ready', onReady, { once: true });
+                        window.addEventListener('htmx-load-failed', onFailed, { once: true });
                     }
                 },
 
@@ -4566,6 +4625,9 @@
     <script src="{{ url_for('static', filename='v3/js/widgets/timezone-selector.js') }}" defer></script>
     <script src="{{ url_for('static', filename='v3/js/widgets/plugin-loader.js') }}" defer></script>
     
+    <!-- Reusable JSON file manager widget (used by of-the-day and others via x-widget: json-file-manager) -->
+    <script src="{{ url_for('static', filename='v3/js/widgets/json-file-manager.js') }}" defer></script>
+
     <!-- Legacy plugins_manager.js (for backward compatibility during migration) -->
     <script src="{{ url_for('static', filename='v3/plugins_manager.js') }}?v=20260307" defer></script>
     

web_interface/templates/v3/index.html

@@ -73,7 +73,7 @@
             <button hx-post="/api/v3/system/action"
                     hx-vals='{"action": "start_display"}'
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Display started', event.detail.xhr.responseJSON.status || 'success'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Display started',s='success'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md text-white bg-green-600 hover:bg-green-700">
                 <i class="fas fa-play mr-2"></i>
                 Start Display
@@ -82,7 +82,7 @@
             <button hx-post="/api/v3/system/action"
                     hx-vals='{"action": "stop_display"}'
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Display stopped', event.detail.xhr.responseJSON.status || 'success'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Display stopped',s='success'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md text-white bg-red-600 hover:bg-red-700">
                 <i class="fas fa-stop mr-2"></i>
                 Stop Display
@@ -91,7 +91,7 @@
             <button hx-post="/api/v3/system/action"
                     hx-vals='{"action": "git_pull"}'
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Code update completed', event.detail.xhr.responseJSON.status || 'info'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Code update completed',s='info'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-gray-300 text-sm font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50">
                 <i class="fas fa-download mr-2"></i>
                 Update Code
@@ -101,7 +101,7 @@
                     hx-vals='{"action": "reboot_system"}'
                     hx-confirm="Are you sure you want to reboot the system?"
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'System rebooting...', event.detail.xhr.responseJSON.status || 'info'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='System rebooting...',s='info'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-transparent text-sm font-medium rounded-md text-white bg-yellow-600 hover:bg-yellow-700">
                 <i class="fas fa-power-off mr-2"></i>
                 Reboot System

web_interface/templates/v3/partials/overview.html

@@ -151,7 +151,7 @@
             <button hx-post="/api/v3/system/action"
                     hx-vals='{"action": "start_display"}'
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Display started', event.detail.xhr.responseJSON.status || 'success'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Display started',s='success'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-transparent text-base font-semibold rounded-md text-white bg-green-600 hover:bg-green-700">
                 <i class="fas fa-play mr-2"></i>
                 Start Display
@@ -160,7 +160,7 @@
             <button hx-post="/api/v3/system/action"
                     hx-vals='{"action": "stop_display"}'
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Display stopped', event.detail.xhr.responseJSON.status || 'success'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Display stopped',s='success'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-transparent text-base font-semibold rounded-md text-white bg-red-600 hover:bg-red-700">
                 <i class="fas fa-stop mr-2"></i>
                 Stop Display
@@ -170,7 +170,7 @@
                     hx-vals='{"action": "git_pull"}'
                     hx-confirm="This will stash any local changes and update the code. Continue?"
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Code update completed', event.detail.xhr.responseJSON.status || 'info'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Code update completed',s='info'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-gray-300 text-base font-semibold rounded-md text-gray-900 bg-white hover:bg-gray-50">
                 <i class="fas fa-download mr-2"></i>
                 Update Code
@@ -180,7 +180,7 @@
                     hx-vals='{"action": "reboot_system"}'
                     hx-confirm="Are you sure you want to reboot the system?"
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'System rebooting...', event.detail.xhr.responseJSON.status || 'info'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='System rebooting...',s='info'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-transparent text-base font-semibold rounded-md text-white bg-yellow-600 hover:bg-yellow-700">
                 <i class="fas fa-power-off mr-2"></i>
                 Reboot System
@@ -190,7 +190,7 @@
                     hx-vals='{"action": "shutdown_system"}'
                     hx-confirm="Are you sure you want to shut down the system? This will power off the Raspberry Pi."
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'System shutting down...', event.detail.xhr.responseJSON.status || 'info'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='System shutting down...',s='info'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-transparent text-base font-semibold rounded-md text-white bg-red-800 hover:bg-red-900">
                 <i class="fas fa-power-off mr-2"></i>
                 Shutdown System
@@ -199,7 +199,7 @@
             <button hx-post="/api/v3/system/action"
                     hx-vals='{"action": "restart_display_service"}'
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Display service restarted', event.detail.xhr.responseJSON.status || 'success'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Display service restarted',s='success'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-gray-300 text-base font-semibold rounded-md text-gray-900 bg-white hover:bg-gray-50">
                 <i class="fas fa-redo mr-2"></i>
                 Restart Display Service
@@ -208,7 +208,7 @@
             <button hx-post="/api/v3/system/action"
                     hx-vals='{"action": "restart_web_service"}'
                     hx-swap="none"
-                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined' && event.detail.xhr && event.detail.xhr.responseJSON) { showNotification(event.detail.xhr.responseJSON.message || 'Web service restarted', event.detail.xhr.responseJSON.status || 'success'); }"
+                    hx-on:htmx:after-request="if (typeof showNotification !== 'undefined') { var m='Web service restarted',s='success'; try { var d=JSON.parse(event.detail.xhr.responseText); m=d.message||m; s=d.status||s; } catch(e) { s=(event.detail.xhr&&event.detail.xhr.status>=400?'error':s); } showNotification(m,s); }"
                     class="inline-flex items-center px-4 py-2 border border-gray-300 text-base font-semibold rounded-md text-gray-900 bg-white hover:bg-gray-50">
                 <i class="fas fa-redo mr-2"></i>
                 Restart Web Service