test(sync): probe for a free port on loopback, not every interface

CodeQL flagged the ephemeral-port probe in the handshake test for
binding to all interfaces. The probe only needs a free port number, so
loopback is both sufficient and correct — a test should not open a port
to the network to discover one.

The manager under test still binds to all interfaces, which is
deliberate and already marked nosec: a follower has to receive the
leader's UDP broadcast.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NohXi78cwsAKtN1sCfxjUh

.github/workflows/test.yml

@@ -72,4 +72,4 @@ jobs:
             --ignore=test/plugins \
             --cov=src --cov=web_interface \
             --cov-report=term \
-            --cov-fail-under=48
+            --cov-fail-under=52

README.md

@@ -600,6 +600,14 @@ These settings are typically only needed for non-standard panels or custom confi
   - Leave empty unless you need custom mapping
   - See rpi-rgb-led-matrix documentation for full options
 
+- **`orientation`** (string, default: "normal")
+  - Rotates the rendered image to match how the panel is physically mounted
+  - Set to `"180"` (or use the "Upside Down" option in the web UI's Display
+    settings) if the panel is mounted upside down — useful for optimizing
+    where the Raspberry Pi and wiring sit relative to the mounting location
+  - Applied independently of `pixel_mapper_config` (appended as a trailing
+    `Rotate:180` mapper), so custom mapper configs keep working alongside it
+
 - **`row_address_type`** (integer, default: 0)
   - How rows are addressed on the panel
   - Most panels use 0 (direct addressing)

config/config.template.json

@@ -112,6 +112,7 @@
             "led_rgb_sequence": "RGB",
             "limit_refresh_rate_hz": 100,
             "pixel_mapper_config": "",
+            "orientation": "normal",
             "row_address_type": 0,
             "multiplexing": 0,
             "panel_type": ""

docs/CONFIG_REFERENCE.md

@@ -66,6 +66,7 @@ in `DisplayManager` (`src/display_manager.py`, ~lines 270–295).
 | `led_rgb_sequence` | string, `"RGB"` |
 | `limit_refresh_rate_hz` | int, `100` (code default 90) |
 | `pixel_mapper_config` | string, `""` — e.g. `"U-mapper"` / `"Rotate:90"` |
+| `orientation` | string, `"normal"` — `"180"` rotates the rendered image 180° for panels physically mounted upside down (e.g. to move the Pi/wiring to a more convenient side); composed onto `pixel_mapper_config` as a trailing `Rotate:180` mapper, so it stays independent of any custom `pixel_mapper_config` value |
 | `row_address_type` | int, `0` — non-standard panel row addressing |
 | `multiplexing` | int, `0` — panel multiplexing scheme |
 | `panel_type` | string, `""` — set to `"FM6126A"` or `"FM6127"` for panels needing init |

src/base_odds_manager.py

@@ -45,6 +45,24 @@ class BaseOddsManager:
         self.logger = logging.getLogger(__name__)
         self.base_url = "https://sports.core.api.espn.com/v2/sports"
 
+        # This path used a bare requests.get, so it identified itself as
+        # python-requests/x.y -- the one thing ESPN is known to reject. Around
+        # 2026-08-04 it began 403ing browser strings and bare custom tokens
+        # alike; what it accepts is a token with a URL that says who is
+        # calling. Every other ESPN caller in the tree already sends this
+        # (src/common/api_helper.py, src/base_classes/data_sources.py); the
+        # odds path was simply missed, and it is the one whose failures cost
+        # the caller its whole update budget.
+        #
+        # Deliberately no retry adapter, unlike api_helper: retries multiply
+        # request_timeout, which is set to 5s precisely to stay inside that
+        # budget. One try, then the cooldown below.
+        self.session = requests.Session()
+        self.session.headers.update({
+            'User-Agent': 'LEDMatrix/1.0 (+https://github.com/ChuckBuilds/LEDMatrix)',
+            'Accept': 'application/json',
+        })
+        
         # Configuration with defaults
         self.update_interval = 3600  # 1 hour default
         # Well under the plugin executor's 30s operation budget. At 30s a
@@ -144,7 +162,7 @@ class BaseOddsManager:
             url = f"{self.base_url}/{sport}/leagues/{espn_league}/events/{event_id}/competitions/{event_id}/odds"
             self.logger.info(f"Requesting odds from URL: {url}")
             
-            response = requests.get(url, timeout=self.request_timeout)
+            response = self.session.get(url, timeout=self.request_timeout)
             response.raise_for_status()
             raw_data = response.json()
 

src/cache/disk_cache.py

@@ -14,6 +14,13 @@ import zlib
 from typing import Dict, Any, Optional, Protocol
 from datetime import datetime
 
+# How old an abandoned write's temp file must be before the sweep removes it.
+# A real write holds its temp file for milliseconds, so an hour is far beyond
+# any in-flight write while still clearing the same day's debris. Deliberately
+# not tied to the retention policies: those describe how long data stays
+# useful, and a half-written file was never useful.
+_ORPHAN_TEMP_MAX_AGE_SECONDS = 3600
+
 
 
 class CacheStrategyProtocol(Protocol):
@@ -347,6 +354,23 @@ class DiskCache:
         """Get the cache directory path."""
         return self.cache_dir
     
+    @staticmethod
+    def _is_orphaned_temp(filename: str) -> bool:
+        """Whether a name is one of set()'s temp files rather than real data.
+
+        Matches only what this class creates: mkstemp with a prefix of
+        ".<cache filename>." , so ".weather.json.a1b2c3d4". The shape is
+        checked rather than just the leading dot, because this predicate
+        deletes things -- a stray dotfile someone left in the cache directory
+        is not ours to remove, and a completed ".json" never is either.
+        """
+        if not filename.startswith('.') or filename.endswith('.json'):
+            return False
+        head, sep, suffix = filename.rpartition('.json.')
+        # head is the key (non-empty after the leading dot), suffix is
+        # mkstemp's random component.
+        return bool(sep) and len(head) > 1 and bool(suffix)
+
     def cleanup_expired_files(self, cache_strategy: CacheStrategyProtocol, retention_policies: Dict[str, int]) -> Dict[str, Any]:
         """
         Clean up expired cache files based on retention policies.
@@ -381,12 +405,51 @@ class DiskCache:
             try:
                 with self._lock:
                     # Get snapshot of files while holding lock briefly
-                    filenames = [f for f in os.listdir(self.cache_dir) if f.endswith('.json')]
+                    entries = os.listdir(self.cache_dir)
             except OSError as list_error:
                 self.logger.error("Error listing cache directory %s: %s", self.cache_dir, list_error, exc_info=True)
                 stats['errors'] += 1
                 return stats
 
+            filenames = [f for f in entries if f.endswith('.json')]
+
+            # Sweep temp files abandoned by a write that never finished. set()
+            # removes its own in a finally, so these are the ones where the
+            # process died between mkstemp and os.replace -- a SIGKILL, a lost
+            # restart race, a power cut. Nothing ever collected them: they are
+            # named ".<key>.json.<random>", and the scan above only matches
+            # names ending in .json, so they accumulated indefinitely. Measured
+            # on a live rig: 76 files, 1,050 MB, 81% of the whole cache
+            # directory, the oldest six months old.
+            stats['orphan_temp_files_deleted'] = 0
+            for filename in (f for f in entries if self._is_orphaned_temp(f)):
+                # Counted as scanned like any other candidate, so files_deleted
+                # can never exceed files_scanned and the summary line reads
+                # honestly ("77/8864", not "77/0").
+                stats['files_scanned'] += 1
+                path = os.path.join(self.cache_dir, filename)
+                try:
+                    # An in-flight write lives for milliseconds, so anything
+                    # this old is certainly abandoned rather than in progress.
+                    if (current_time - os.path.getmtime(path)) <= _ORPHAN_TEMP_MAX_AGE_SECONDS:
+                        continue
+                    with self._lock:
+                        size = os.path.getsize(path)
+                        os.remove(path)
+                    stats['files_deleted'] += 1
+                    stats['orphan_temp_files_deleted'] += 1
+                    stats['space_freed_bytes'] += size
+                except FileNotFoundError:
+                    continue          # another sweep got there first
+                except OSError as e:
+                    stats['errors'] += 1
+                    self.logger.warning("Error deleting orphaned temp file %s: %s", filename, e)
+
+            if stats['orphan_temp_files_deleted']:
+                self.logger.info(
+                    "Removed %d abandoned cache temp file(s)",
+                    stats['orphan_temp_files_deleted'])
+            
             # Process files outside the lock to avoid blocking get/set operations
             for filename in filenames:
                 stats['files_scanned'] += 1

src/cache_manager.py

@@ -47,6 +47,20 @@ from src.cache.disk_cache import DateTimeEncoder  # noqa: F401 - deliberate re-e
 class CacheManager:
     """Manages caching of API responses to reduce API calls."""
 
+    # Which cache directories already have a cleanup thread in this process.
+    #
+    # The sweep is directory-scoped work -- it lists a directory and deletes
+    # from it -- so one per directory is the right number no matter how many
+    # managers exist. Nothing enforced that before: every instance started its
+    # own, and because the loop closes over `self`, a discarded manager could
+    # never be collected and its thread woke to re-scan the same directory
+    # every 24 hours for the life of the process. Startup validation runs
+    # twice and built a throwaway manager each time, so a display process
+    # carried three threads for one cache.
+    _cleanup_owners: Dict[str, 'CacheManager'] = {}
+    _cleanup_owners_lock = threading.Lock()
+
+
     def __init__(self) -> None:
         # Initialize logger first
         self.logger: logging.Logger = get_logger(__name__)
@@ -718,11 +732,29 @@ class CacheManager:
             }
     
     def start_cleanup_thread(self) -> None:
-        """Start background thread for periodic disk cache cleanup."""
+        """Start background thread for periodic disk cache cleanup.
+
+        At most one thread per cache directory per process: the sweep is
+        directory-scoped, so a second one only duplicates the scan.
+        """
         if self._cleanup_thread and self._cleanup_thread.is_alive():
             self.logger.debug("Cleanup thread already running")
             return
 
+        with CacheManager._cleanup_owners_lock:
+            owner = CacheManager._cleanup_owners.get(self.cache_dir)
+            if owner is not None and owner is not self:
+                thread = owner._cleanup_thread
+                if thread is not None and thread.is_alive():
+                    self.logger.debug(
+                        "Cleanup thread for %s already owned by another cache "
+                        "manager in this process; not starting a second",
+                        self.cache_dir)
+                    return
+                # The owner's thread died or was stopped -- take over.
+            CacheManager._cleanup_owners[self.cache_dir] = self
+
+
         def cleanup_loop():
             """Background loop that runs cleanup periodically."""
             self.logger.info("Disk cache cleanup thread started (interval: %d hours)", 
@@ -770,6 +802,13 @@ class CacheManager:
         Signals the thread to stop and waits for it to finish (with timeout).
         This allows for clean shutdown during testing or application termination.
         """
+        # Release ownership first and unconditionally, so a manager that never
+        # started a thread (or whose thread already exited) cannot keep the
+        # directory claimed and block a live manager from sweeping it.
+        with CacheManager._cleanup_owners_lock:
+            if CacheManager._cleanup_owners.get(self.cache_dir) is self:
+                del CacheManager._cleanup_owners[self.cache_dir]
+
         if not self._cleanup_thread or not self._cleanup_thread.is_alive():
             self.logger.debug("Cleanup thread not running")
             return

src/common/logo_helper.py

@@ -19,6 +19,10 @@ from src.common.permission_utils import (
 )
 
 
+# Well above any real team logo; bounds what a remote URL can write to disk.
+MAX_LOGO_BYTES = 10 * 1024 * 1024
+
+
 class LogoHelper:
     """
     Helper class for logo loading, caching, and resizing.
@@ -226,7 +230,10 @@ class LogoHelper:
         return {
             'cached_logos': len(self._logo_cache),
             'cache_size_limit': self.cache_size,
-            'cache_usage_percent': (len(self._logo_cache) / self.cache_size) * 100
+            'cache_usage_percent': (
+                (len(self._logo_cache) / self.cache_size) * 100
+                if self.cache_size else 0
+            ),
         }
     
     def _resize_logo(self, logo: Image.Image, max_width: Optional[int] = None, 
@@ -258,7 +265,13 @@ class LogoHelper:
         self._cache_order.append(cache_key)
     
     def _download_logo(self, url: str, file_path: Path) -> None:
-        """Download logo from URL."""
+        """Download logo from URL.
+
+        The response size is capped and the saved file is verified as a
+        decodable image before it is left on disk: a logo URL is remote
+        input, and without this an oversized or malformed response would
+        be cached for every later load_logo() call to trip over.
+        """
         # Ensure directory exists with proper permissions
         ensure_directory_permissions(file_path.parent, get_assets_dir_mode())
 
@@ -266,9 +279,25 @@ class LogoHelper:
         response = self.session.get(url, timeout=30)
         response.raise_for_status()
 
+        content = response.content
+        if len(content) > MAX_LOGO_BYTES:
+            raise ValueError(
+                f"Logo at {url} is {len(content)} bytes, over the "
+                f"{MAX_LOGO_BYTES}-byte limit; not saved")
+
         # Save to file
         with open(file_path, 'wb') as f:
-            f.write(response.content)
+            f.write(content)
+
+        # Verify it decodes before leaving it on disk. PIL raises
+        # DecompressionBombError past its own pixel limit; a partial or
+        # non-image response raises UnidentifiedImageError/OSError.
+        try:
+            with Image.open(file_path) as probe:
+                probe.load()
+        except Exception:
+            file_path.unlink(missing_ok=True)
+            raise
 
         # Set proper file permissions after saving
         ensure_file_permissions(file_path, get_assets_file_mode())

src/common/sync_manager.py

@@ -101,6 +101,7 @@ class DisplaySyncManager:
         self._peer_chain: int = 0
         self._last_heartbeat_time: float = 0.0
         self._leader_width: int = 0  # set by display_controller after init
+        self._oversized_frame_warned: bool = False
 
         # Follower state
         self._follower_state = FollowerState.STANDALONE
@@ -174,6 +175,10 @@ class DisplaySyncManager:
                 continue
             except Exception as exc:
                 self.logger.debug("Sync leader recv error: %s", exc)
+                # Brief backoff: a socket left in a bad state raises
+                # immediately, which would otherwise spin this thread at
+                # 100% CPU logging the same error.
+                time.sleep(0.1)
 
     def _handle_hello(self, msg: dict, sender_ip: str) -> None:
         hw = self._hw_config
@@ -396,7 +401,7 @@ class DisplaySyncManager:
             data = header + arr.tobytes()
             if len(data) <= 65000:
                 self._send_sock.sendto(data, (self._peer_ip, self.port))
-            elif not getattr(self, '_oversized_frame_warned', False):
+            elif not self._oversized_frame_warned:
                 self._oversized_frame_warned = True
                 self.logger.warning(
                     "Sync: frame too large for UDP (%d bytes, max 65000) — "
@@ -451,41 +456,44 @@ class DisplaySyncManager:
         )
         self.write_status_file()
 
+    def _handle_received_frame(self, img: Image.Image, sender_ip: str) -> None:
+        """Record a decoded leader frame and enter follower mode if needed."""
+        with self._frame_lock:
+            self._latest_frame = img
+        self._last_leader_frame_time = time.time()
+        self._leader_ip = sender_ip
+
+        if self._follower_state == FollowerState.STANDALONE:
+            self._follower_state = FollowerState.FOLLOWER
+            self.logger.info(
+                "Sync: leader active at %s — switching to follower mode",
+                sender_ip,
+            )
+            self.write_status_file()
+
     def _follower_recv_loop(self) -> None:
         while self._running:
             try:
                 data, addr = self._recv_sock.recvfrom(65535)
                 sender_ip = addr[0]
 
-                if data[:8] == _RAW_MAGIC or len(data) > 512:
-                    # Frame data: prefer magic-tagged raw RGB; fall back to legacy PNG
+                if data[:8] == _RAW_MAGIC:
+                    # Magic-tagged raw RGB frame — self-describing, no guessing.
                     try:
-                        if data[:8] == _RAW_MAGIC:
-                            w, h = _RAW_HEADER.unpack(data[8:12])
-                            raw = data[12:]
-                            img = Image.frombuffer(
-                                "RGB", (w, h), raw, "raw", "RGB", 0, 1
-                            )
-                        else:
-                            # Fallback: try legacy PNG
-                            img = Image.open(io.BytesIO(data))
-                            img.load()
-                        with self._frame_lock:
-                            self._latest_frame = img
-                        self._last_leader_frame_time = time.time()
-                        self._leader_ip = sender_ip
-
-                        if self._follower_state == FollowerState.STANDALONE:
-                            self._follower_state = FollowerState.FOLLOWER
-                            self.logger.info(
-                                "Sync: leader active at %s — switching to follower mode",
-                                sender_ip,
-                            )
-                            self.write_status_file()
+                        w, h = _RAW_HEADER.unpack(data[8:12])
+                        raw = data[12:]
+                        img = Image.frombuffer(
+                            "RGB", (w, h), raw, "raw", "RGB", 0, 1
+                        )
+                        self._handle_received_frame(img, sender_ip)
                     except Exception as exc:
                         self.logger.debug("Sync: frame decode error: %s", exc)
                 else:
-                    # Control message
+                    # No magic prefix: try control-message JSON, and treat a
+                    # parse failure as a legacy (pre-magic) PNG frame. Both
+                    # wire formats are self-describing, so no size heuristic
+                    # is needed — a >512-byte control message used to be
+                    # misrouted into image decode and silently dropped.
                     try:
                         msg = json.loads(data.decode("utf-8"))
                         t = msg.get("t")
@@ -518,12 +526,19 @@ class DisplaySyncManager:
                             if self._on_new_cycle:
                                 self._on_new_cycle()
                     except (json.JSONDecodeError, UnicodeDecodeError, KeyError):
-                        pass
+                        # Not a control message — try legacy PNG frame.
+                        try:
+                            img = Image.open(io.BytesIO(data))
+                            img.load()
+                            self._handle_received_frame(img, sender_ip)
+                        except Exception as exc:
+                            self.logger.debug("Sync: frame decode error: %s", exc)
 
             except socket.timeout:
                 continue
             except Exception as exc:
                 self.logger.debug("Sync follower recv error: %s", exc)
+                time.sleep(0.1)
 
     def _follower_announce_loop(self) -> None:
         hw = self._hw_config

src/display_controller.py

@@ -44,6 +44,20 @@ from src.common.sync_manager import DisplaySyncManager, SyncRole
 # Get logger with consistent configuration
 logger = get_logger(__name__)
 
+# How long startup will wait for plugins to fetch their first data before
+# showing anything. Each plugin's update blocks for up to the executor's 30s
+# timeout and they run one after another, so the uncapped total is the sum of
+# every slow plugin: 82 seconds on the worst boot measured, with a blank panel
+# throughout. Whatever does not finish in time is picked up by the scheduled
+# update tick moments later, with the display already running.
+_INITIAL_UPDATE_BUDGET_SECONDS = 20.0
+
+# The least budget worth starting a plugin with. Below this the plugin is
+# deferred instead: granting it a floor would let the pass run past its
+# deadline, and granting it the true remainder would record a timeout for a
+# slot it never had a chance to use.
+_MIN_INITIAL_UPDATE_TIMEOUT_SECONDS = 2.0
+
 # Vegas mode import (lazy loaded to avoid circular imports)
 _vegas_mode_imported = False
 VegasModeCoordinator = None
@@ -90,7 +104,8 @@ class DisplayController:
         # Validate startup configuration
         try:
             from src.startup_validator import StartupValidator
-            validator = StartupValidator(self.config_manager)
+            validator = StartupValidator(self.config_manager,
+                                         cache_manager=self.cache_manager)
             is_valid, errors, warnings = validator.validate_all()
             
             if warnings:
@@ -258,7 +273,8 @@ class DisplayController:
             # Validate plugins after plugin manager is created
             try:
                 from src.startup_validator import StartupValidator
-                validator = StartupValidator(self.config_manager, self.plugin_manager)
+                validator = StartupValidator(self.config_manager, self.plugin_manager,
+                                             cache_manager=self.cache_manager)
                 is_valid, errors, warnings = validator.validate_all()
                 
                 if warnings:
@@ -461,7 +477,7 @@ class DisplayController:
         # Initial data update for plugins (ensures data available on first display)
         logger.info("Performing initial plugin data update...")
         update_start = time.time()
-        self._update_modules()
+        self._update_modules(deadline=update_start + _INITIAL_UPDATE_BUDGET_SECONDS)
         logger.info("Initial plugin update completed in %.3f seconds", time.time() - update_start)
 
         # Initialize Vegas mode coordinator
@@ -817,14 +833,42 @@ class DisplayController:
             self._cached_target_brightness = normal_brightness  # persist for minute-gate
             return normal_brightness
 
-    def _update_modules(self):
-        """Update all plugin modules."""
+    def _update_modules(self, deadline: Optional[float] = None):
+        """Update all plugin modules.
+
+        Args:
+            deadline: Wall-clock time after which remaining plugins are left
+                for the scheduled update tick instead of being waited on. Each
+                update blocks this thread for up to the executor's timeout, and
+                they run one after another, so without a bound the total is the
+                sum of every slow plugin on the system. Measured at startup on
+                a live rig: 82 seconds, 55 and 26 on the two boots before -- all
+                of it with nothing on the panel.
+        """
         if not self.plugin_manager:
             return
 
         # Update all loaded plugins
         plugins_dict = getattr(self.plugin_manager, 'loaded_plugins', None) or getattr(self.plugin_manager, 'plugins', {})
+        deferred = []
         for plugin_id, plugin_instance in plugins_dict.items():
+            update_timeout = None
+            if deadline is not None:
+                update_timeout = deadline - time.time()
+                if update_timeout < _MIN_INITIAL_UPDATE_TIMEOUT_SECONDS:
+                    # Too little left to be worth starting. Deferring rather
+                    # than granting a floor keeps the budget a real ceiling --
+                    # clamping up to a minimum let a plugin that began with a
+                    # sliver left run on past the deadline -- and a plugin
+                    # handed a slot it cannot use would just be recorded as
+                    # having timed out.
+                    #
+                    # Nothing is lost either way: a plugin that has never
+                    # updated is immediately due, so run_scheduled_updates()
+                    # picks it up within seconds, with the display already
+                    # running.
+                    deferred.append(plugin_id)
+                    continue
             # Check circuit breaker before attempting update
             if hasattr(self.plugin_manager, 'health_tracker') and self.plugin_manager.health_tracker:
                 if self.plugin_manager.health_tracker.should_skip_plugin(plugin_id):
@@ -833,7 +877,13 @@ class DisplayController:
             
             # Use PluginExecutor if available for safe execution
             if hasattr(self.plugin_manager, 'plugin_executor'):
-                success = self.plugin_manager.plugin_executor.execute_update(plugin_instance, plugin_id)
+                # The remaining budget is the timeout, so the pass cannot
+                # run past its deadline. Bounding the loop alone did not do
+                # it: the last plugin to start could still block for the
+                # executor's full 30s, which turned a 20s budget into a 31.8s
+                # pass on the rig.
+                success = self.plugin_manager.plugin_executor.execute_update(
+                    plugin_instance, plugin_id, timeout=update_timeout)
                 if success and hasattr(self.plugin_manager, 'plugin_last_update'):
                     self.plugin_manager.plugin_last_update[plugin_id] = time.time()
             else:
@@ -852,6 +902,12 @@ class DisplayController:
                     if hasattr(self.plugin_manager, 'health_tracker') and self.plugin_manager.health_tracker:
                         self.plugin_manager.health_tracker.record_failure(plugin_id, exc)
 
+        if deferred:
+            logger.info(
+                "Initial update budget spent; %d plugin(s) left to the update "
+                "tick so the display can start: %s",
+                len(deferred), ", ".join(deferred))
+
     def _tick_plugin_updates_for_vegas(self) -> None:
         """Run scheduled plugin updates and tell Vegas mode which plugins
         actually got fresh data, so it can hot-swap them into the scroll

src/display_manager.py

@@ -25,6 +25,7 @@ the same object.
 
 import json
 import os
+import socket
 import tempfile
 if os.getenv("EMULATOR", "false") == "true":
     from RGBMatrixEmulator import RGBMatrix, RGBMatrixOptions
@@ -258,6 +259,26 @@ class DisplayManager:
         # Initialize managers
         # Calendar manager is now initialized by DisplayController
         
+    # Orientation setting -> rpi-rgb-led-matrix "Rotate:<deg>" pixel-mapper suffix.
+    # "normal" needs no suffix since 0 degrees is the identity transform.
+    _ORIENTATION_ROTATE_DEGREES = {'normal': None, '90': 90, '180': 180, '270': 270}
+
+    def _build_pixel_mapper_config(self, hardware_config: dict) -> str:
+        """Compose the raw pixel_mapper_config string with the orientation setting.
+
+        `pixel_mapper_config` stays available as a free-form advanced field (e.g.
+        for "U-mapper" chain layouts); `orientation` is the user-facing dropdown
+        for physical mounting (e.g. panels mounted upside down) and is appended as
+        a "Rotate:<deg>" mapper rather than overwriting any existing config.
+        """
+        base_mapper = (hardware_config.get('pixel_mapper_config') or '').strip()
+        orientation = hardware_config.get('orientation', 'normal')
+        degrees = self._ORIENTATION_ROTATE_DEGREES.get(orientation)
+        if degrees is None:
+            return base_mapper
+        rotate_mapper = f'Rotate:{degrees}'
+        return f'{base_mapper};{rotate_mapper}' if base_mapper else rotate_mapper
+
     def _setup_matrix(self):
         """Initialize the RGB matrix with configuration settings."""
         _init_error_str = None
@@ -283,7 +304,7 @@ class DisplayManager:
             options.pwm_bits = hardware_config.get('pwm_bits', 10)
             options.pwm_lsb_nanoseconds = hardware_config.get('pwm_lsb_nanoseconds', 150)
             options.led_rgb_sequence = hardware_config.get('led_rgb_sequence', 'RGB')
-            options.pixel_mapper_config = hardware_config.get('pixel_mapper_config', '')
+            options.pixel_mapper_config = self._build_pixel_mapper_config(hardware_config)
             options.row_address_type = hardware_config.get('row_address_type', 0)
             options.multiplexing = hardware_config.get('multiplexing', 0)
             options.panel_type = hardware_config.get('panel_type', '')
@@ -497,6 +518,91 @@ class DisplayManager:
             logger.warning(f"[BRIGHTNESS] Matrix does not support brightness property: {e}", exc_info=True)
             return -1
 
+    @staticmethod
+    def _local_ip() -> Optional[str]:
+        """This device's address on the network it routes through, or None.
+
+        Deliberately not `hostname -I` or a systemctl probe for AP mode, which
+        is how the web launcher does it: both spawn processes with multi-second
+        timeouts, and this runs on the startup path the rest of this change
+        exists to shorten. Connecting a UDP socket sends no packets -- it only
+        asks the kernel which source address it would use -- so it costs
+        microseconds and works with the network down, as long as a route
+        exists.
+        """
+        sock = None
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+            sock.settimeout(0.2)
+            sock.connect(("8.8.8.8", 80))  # nosec B104 - no traffic; selects a route
+            ip = sock.getsockname()[0]
+            return ip if ip and not ip.startswith("127.") else None
+        except OSError:
+            return None
+        finally:
+            if sock is not None:
+                try:
+                    sock.close()
+                except OSError:
+                    pass
+
+    def _fitting_font(self, lines, width):
+        """The largest font from the usual ladder that fits every line."""
+        candidates = [self.font,
+                      ("assets/fonts/4x6-font.ttf", 6)]
+        for candidate in candidates:
+            try:
+                font = candidate
+                if isinstance(candidate, tuple):
+                    font = ImageFont.truetype(candidate[0], candidate[1])
+                if all(self.draw.textlength(t, font=font) <= width for t in lines):
+                    return font
+            except (OSError, ValueError, AttributeError):
+                continue
+        return self.font
+
+    def _draw_startup_banner(self, lines, width: int, height: int) -> None:
+        """Centre `lines` over whatever the test pattern already drew.
+
+        This screen stays on the panel for the whole initial plugin update, and
+        on a headless Pi it is the only place the device's address appears
+        without going looking for it -- so it has to be readable off a wall,
+        not merely present.
+
+        The font is chosen to fit rather than fixed at 8px: "Initializing" is
+        96px in PressStart2P, which ran off the side of a 64px panel even
+        before an address was added. And the pattern is punched out behind the
+        text, because the diagonal runs through the middle of the panel, which
+        is exactly where this sits.
+
+        The text stays blue. It is not decoration: the pattern draws one pure
+        channel per element -- red border, green diagonal, blue text -- so that
+        a glance at the panel says whether led_rgb_sequence is right. Swap the
+        wiring to BGR and the border comes up blue and this text red. Drawing
+        it white would light all three channels and destroy the only blue
+        reference on the screen, which is why it is worth a comment rather
+        than a quiet preference.
+        """
+        if not lines:
+            return
+        font = self._fitting_font(lines, width - 2)
+        line_height = self.draw.textbbox((0, 0), "Ag", font=font)[3] + 1
+        block_height = line_height * len(lines)
+        block_top = max(1, (height - block_height) // 2)
+        block_width = max(self.draw.textlength(t, font=font) for t in lines)
+        block_left = max(0, (width - block_width) // 2)
+
+        self.draw.rectangle(
+            [block_left - 2, block_top - 1,
+             block_left + block_width + 1, block_top + block_height],
+            fill=(0, 0, 0))
+
+        for row, line in enumerate(lines):
+            line_width = self.draw.textlength(line, font=font)
+            self.draw.text(
+                (max(0, (width - line_width) // 2), block_top + row * line_height),
+                line, font=font, fill=(0, 0, 255))
+
     def _draw_test_pattern(self):
         """Draw a test pattern to verify the display is working."""
         try:
@@ -516,8 +622,11 @@ class DisplayManager:
             # Draw a diagonal line
             self.draw.line([0, 0, self.matrix.width-1, self.matrix.height-1], fill=(0, 255, 0))
             
-            # Draw some text - changed from "TEST" to "Initializing" with smaller font
-            self.draw.text((10, 10), "Initializing", font=self.font, fill=(0, 0, 255))
+            lines = ["Initializing"]
+            ip = self._local_ip()
+            if ip:
+                lines.append(ip)
+            self._draw_startup_banner(lines, self.matrix.width, self.matrix.height)
             
             # Update the display once after everything is drawn
             self.update_display()

src/startup_validator.py

@@ -15,16 +15,23 @@ from src.logging_config import get_logger
 class StartupValidator:
     """Validates system state on startup."""
     
-    def __init__(self, config_manager: Any, plugin_manager: Optional[Any] = None) -> None:
+    def __init__(self, config_manager: Any, plugin_manager: Optional[Any] = None,
+                 cache_manager: Optional[Any] = None) -> None:
         """
         Initialize the startup validator.
 
         Args:
             config_manager: ConfigManager instance
             plugin_manager: Optional PluginManager instance
+            cache_manager: The CacheManager the application will actually use.
+                Pass it. Without one this validator builds its own just to read
+                a directory path, which reports on a cache the app does not
+                use and leaves behind a cleanup thread that nothing stops --
+                validation runs twice per startup, so that was two of them.
         """
         self.config_manager = config_manager
         self.plugin_manager = plugin_manager
+        self.cache_manager = cache_manager
         self.logger = get_logger(__name__)
         self.errors: List[str] = []
         self.warnings: List[str] = []
@@ -91,9 +98,21 @@ class StartupValidator:
     def _validate_cache_directory(self) -> None:
         """Validate cache directory permissions."""
         try:
-            from src.cache_manager import CacheManager
-            cache_manager = CacheManager()
-            cache_dir = cache_manager.get_cache_dir()
+            cache_manager = self.cache_manager
+            if cache_manager is None:
+                # No caller supplied one (older embedders, direct use in a
+                # script). Build one, but do not leave its cleanup thread
+                # running behind us -- this instance is discarded on the next
+                # line but the thread is a closure over it, so it would never
+                # be collected.
+                from src.cache_manager import CacheManager
+                cache_manager = CacheManager()
+                try:
+                    cache_dir = cache_manager.get_cache_dir()
+                finally:
+                    cache_manager.stop_cleanup_thread()
+            else:
+                cache_dir = cache_manager.get_cache_dir()
             
             if not cache_dir:
                 self.warnings.append("Cache directory not available - caching will be disabled")

src/vegas_mode/coordinator.py

@@ -12,6 +12,7 @@ Supports three display modes per plugin:
 """
 
 import logging
+import math
 import time
 import threading
 from typing import Optional, Dict, Any, List, Callable, TYPE_CHECKING
@@ -30,6 +31,21 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _percentile(ordered: List[float], fraction: float) -> float:
+    """Nearest-rank percentile of an already-sorted list.
+
+    Index ceil(n * fraction) - 1, so 100 samples at 0.99 give the 99th-ranked
+    value. The obvious int(n * fraction) is off by one and, at exactly 100
+    samples, lands on the maximum -- which is the number already reported
+    alongside this one as the worst frame, so the two columns would agree
+    precisely when the sample was smallest.
+    """
+    if not ordered:
+        return 0.0
+    index = math.ceil(len(ordered) * fraction) - 1
+    return ordered[min(len(ordered) - 1, max(0, index))]
+
+
 class VegasModeCoordinator:
     """
     Orchestrates Vegas scroll mode operation.
@@ -382,6 +398,12 @@ class VegasModeCoordinator:
         fps_log_interval = 5.0  # Log FPS every 5 seconds
         last_fps_log_time = start_time
         fps_frame_count = 0
+        # A mean hides stutter completely. At 120fps a five-second window is
+        # ~600 frames, so a 200ms freeze -- plainly visible on a marquee --
+        # moves the average from 120.0 to 115.4 and reads as healthy. What a
+        # viewer actually notices is the worst frame, so track that too.
+        frame_worst = 0.0
+        frame_times: List[float] = []
 
         logger.info("Starting Vegas iteration for %.1fs", duration)
 
@@ -417,6 +439,11 @@ class VegasModeCoordinator:
             frame_elapsed = time.time() - frame_started
             time.sleep(max(0.0, frame_interval - frame_elapsed))
 
+            # Measured before the sleep: time spent working, not pacing.
+            if frame_elapsed > frame_worst:
+                frame_worst = frame_elapsed
+            frame_times.append(frame_elapsed)
+
             # Increment frame count and check for interrupt periodically
             frame_count += 1
             fps_frame_count += 1
@@ -425,12 +452,16 @@ class VegasModeCoordinator:
             current_time = time.time()
             if current_time - last_fps_log_time >= fps_log_interval:
                 fps = fps_frame_count / (current_time - last_fps_log_time)
+                p99 = _percentile(sorted(frame_times), 0.99)
                 logger.info(
-                    "Vegas FPS: %.1f (target: %d, frames: %d)",
-                    fps, self.vegas_config.target_fps, fps_frame_count
+                    "Vegas FPS: %.1f (target: %d, frames: %d) p99 %.1fms worst %.1fms",
+                    fps, self.vegas_config.target_fps, fps_frame_count,
+                    p99 * 1000.0, frame_worst * 1000.0
                 )
                 last_fps_log_time = current_time
                 fps_frame_count = 0
+                frame_worst = 0.0
+                frame_times.clear()
 
             if (self._interrupt_check and
                     frame_count % self._interrupt_check_interval == 0):

src/web_interface/api_helpers.py

@@ -30,16 +30,14 @@ def success_response(
     """
     response_data = create_success_response(data, message, metadata)
 
-    # Add request metadata if available
-    if metadata is None:
-        metadata = {}
-    
-    # Add timing if request start time is available
+    # Timing is merged into whatever the caller passed, without inventing a
+    # metadata block for responses that have neither.
+    enriched = dict(metadata) if metadata is not None else {}
     if hasattr(request, 'start_time'):
-        metadata['response_time_ms'] = int((time.time() - request.start_time) * 1000)
+        enriched['response_time_ms'] = int((time.time() - request.start_time) * 1000)
 
-    if metadata:
-        response_data['metadata'] = metadata
+    if metadata is not None or enriched:
+        response_data['metadata'] = enriched
 
     return jsonify(response_data)
 

src/web_interface/error_handler.py

@@ -77,25 +77,6 @@ def describe_exception(exc: BaseException,
     """
     message = str(exc).strip()
     text = f"{type(exc).__name__}: {message}" if message else type(exc).__name__
-    return redact_text(text, max_length)
-
-
-def redact_text(text: str, max_length: int = _MAX_DETAIL_LENGTH) -> str:
-    """Make arbitrary text safe to hand back over HTTP.
-
-    Split out of describe_exception because exceptions are not the only thing
-    worth returning: a subprocess's stderr, or a message a helper script
-    printed, is just as useful to a user and just as capable of carrying a
-    token or a password in it.
-
-    Args:
-        text: The text to redact
-        max_length: Truncate beyond this many characters
-
-    Returns:
-        A single line, credentials replaced, length capped.
-    """
-    text = text or ''
     # Order matters: the URL and header forms are more specific than the
     # generic key=value pattern, which would otherwise chew the scheme.
     text = _REDACT_URL_USERINFO.sub(r'\1<redacted>\3', text)
@@ -161,13 +142,16 @@ def create_success_response(
         "status": "success"
     }
     
+    # All three use `is not None` rather than truthiness: "" and {} are
+    # values a caller chose to send, and dropping them silently would make
+    # the response shape depend on the data.
     if data is not None:
         response["data"] = data
 
-    if message:
+    if message is not None:
         response["message"] = message
 
-    if metadata:
+    if metadata is not None:
         response["metadata"] = metadata
 
     return response

src/web_interface/errors.py

@@ -89,7 +89,11 @@ class WebInterfaceError:
         self.category = category or self._infer_category(error_code)
         self.details = details
         self.context = context or {}
-        self.suggested_fixes = suggested_fixes or self._get_default_suggestions(error_code)
+        # `is None`, not truthiness: an explicit [] means "this caller has
+        # no suggestions to offer", which the default list would override.
+        self.suggested_fixes = (
+            suggested_fixes if suggested_fixes is not None
+            else self._get_default_suggestions(error_code))
         self.original_error = original_error
     
     def _infer_category(self, error_code: ErrorCode) -> ErrorCategory:

src/web_interface/validators.py

@@ -43,10 +43,15 @@ def validate_image_url(url: str) -> Tuple[bool, Optional[str]]:
     if any(handler in url_lower for handler in ['onerror=', 'onload=', 'onclick=']):
         return False, "Event handlers not allowed in URLs"
     
+    # Reject directory traversal anywhere, not only in relative paths:
+    # http://host/../secret is as much a traversal attempt as /../secret.
+    if '..' in url:
+        return False, "Invalid path: directory traversal not allowed"
+
     # Allow relative paths starting with /
     if url.startswith('/'):
-        # Validate it's a safe relative path (no directory traversal)
-        if '..' in url or url.startswith('//'):
+        # // would be a protocol-relative URL, not a local path
+        if url.startswith('//'):
             return False, "Invalid relative path"
         return True, None
     
@@ -104,10 +109,11 @@ def validate_file_upload(filename: str, max_size_mb: int = 10,
     if '..' in filename or '/' in filename or '\\' in filename:
         return False, "Filename contains invalid characters"
     
-    # Check extension if specified
+    # Check extension if specified. Both sides are lowercased: the caller's
+    # list is as likely to hold '.TTF' as the filename is.
     if allowed_extensions:
         file_ext = Path(filename).suffix.lower()
-        if file_ext not in allowed_extensions:
+        if file_ext not in [ext.lower() for ext in allowed_extensions]:
             return False, f"File extension must be one of: {', '.join(allowed_extensions)}"
     
     return True, None
@@ -147,7 +153,8 @@ def validate_numeric_range(value: float, min_val: Optional[float] = None,
     Returns:
         Tuple of (is_valid, error_message)
     """
-    if not isinstance(value, (int, float)):
+    # bool is an int subclass, so True would otherwise validate as 1.
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
         return False, "Value must be a number"
     
     if min_val is not None and value < min_val:
@@ -183,7 +190,15 @@ def validate_string_length(text: str, min_length: Optional[int] = None,
 
 def sanitize_plugin_config(config: dict) -> dict:
     """
-    Sanitize plugin configuration input to prevent injection.
+    Restrict a plugin config to safe key names and value types.
+
+    Drops keys that are not plain identifiers and values that are not
+    JSON-ish scalars, lists, or dicts, recursing into the latter two.
+
+    String values are returned **unescaped**: output escaping is the
+    template layer's job, and escaping here would store the escaped form
+    in config.json. Do not read this function as XSS protection for
+    rendered output.
 
     Args:
         config: Configuration dictionary

test/_api_v3_test_helpers.py

@@ -0,0 +1,75 @@
+"""
+Shared scaffolding for api_v3 blueprint tests.
+
+Not a test module (the leading underscore keeps pytest from collecting
+it). It is the pytest-fixture equivalent of ``_make_client()`` in
+test_uninstall_and_reconcile_endpoint.py, which is unittest-style and
+requires ``self.addCleanup``.
+
+The api_v3 blueprint keeps its managers as attributes on a module-level
+singleton, not in Flask app state, so replacing them with mocks leaks
+into every later test that imports api_v3 unless the originals are put
+back. ``api_v3_client`` snapshots and restores them around each test.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+from flask import Flask
+
+
+# Every manager attribute the blueprint reads. Anything missing here keeps
+# whatever a previously-run test left on the singleton.
+API_V3_MANAGER_ATTRS = (
+    'config_manager', 'plugin_manager', 'plugin_store_manager',
+    'plugin_state_manager', 'saved_repositories_manager', 'schema_manager',
+    'operation_queue', 'operation_history', 'cache_manager',
+)
+
+_SENTINEL = object()
+
+
+def build_app(blueprint):
+    app = Flask(__name__)
+    app.config['TESTING'] = True
+    app.config['SECRET_KEY'] = 'test'
+    app.register_blueprint(blueprint, url_prefix='/api/v3')
+    return app
+
+
+@pytest.fixture
+def api_v3_module():
+    """The api_v3 module with every manager replaced by a MagicMock.
+
+    Restores the original attributes afterwards. Tests point individual
+    managers at real objects (a ConfigManager over tmp_path, say) or set
+    them to None to exercise the not-initialized branches.
+    """
+    from web_interface.blueprints import api_v3 as module
+
+    originals = {
+        name: getattr(module.api_v3, name, _SENTINEL)
+        for name in API_V3_MANAGER_ATTRS
+    }
+    for name in API_V3_MANAGER_ATTRS:
+        setattr(module.api_v3, name, MagicMock())
+    # Default to the direct path; queue tests opt in explicitly.
+    module.api_v3.operation_queue = None
+
+    yield module
+
+    for name, original in originals.items():
+        if original is _SENTINEL:
+            if hasattr(module.api_v3, name):
+                try:
+                    delattr(module.api_v3, name)
+                except AttributeError:
+                    pass
+        else:
+            setattr(module.api_v3, name, original)
+
+
+@pytest.fixture
+def api_v3_client(api_v3_module):
+    """Flask test client wired to the mocked blueprint."""
+    return build_app(api_v3_module.api_v3).test_client()

test/test_api_v3_calendar_credentials.py

@@ -0,0 +1,214 @@
+"""
+Endpoint tests for POST /plugins/calendar/upload-credentials.
+
+The endpoint takes an uploaded Google OAuth credentials file, writes it
+into the calendar plugin's directory as credentials.json at mode 0600, and
+copies any previous file aside first. It had no tests.
+
+Regression coverage for two fixed bugs:
+- The OAuth-shape check sat inside `except Exception: pass`, so a valid
+  JSON document that is not an object — a bare `42`, a list, a string —
+  raised TypeError on the membership test, was swallowed, and got saved
+  as credentials.json anyway.
+- Each overwrite created a timestamped backup and nothing ever removed
+  them, so every re-upload left another complete copy of the user's OAuth
+  client credentials in the plugin directory, indefinitely.
+"""
+
+import io
+import json
+import os
+import stat
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+URL = "/api/v3/plugins/calendar/upload-credentials"
+
+VALID_CREDENTIALS = {
+    "installed": {
+        "client_id": "abc.apps.googleusercontent.com",
+        "client_secret": "shh",
+        "redirect_uris": ["http://localhost"],
+    }
+}
+
+
+@pytest.fixture
+def plugin_dir(tmp_path, api_v3_module):
+    directory = tmp_path / "plugins" / "calendar"
+    directory.mkdir(parents=True)
+    api_v3_module.api_v3.plugin_manager.get_plugin_directory.return_value = str(directory)
+    return directory
+
+
+def upload(client, content, filename="credentials.json"):
+    # bytes are sent verbatim (to exercise malformed input); anything else
+    # is serialized, so None becomes the JSON literal null rather than an
+    # empty body.
+    payload = content if isinstance(content, bytes) else json.dumps(content).encode()
+    return client.post(
+        URL,
+        data={"file": (io.BytesIO(payload), filename)},
+        content_type="multipart/form-data",
+    )
+
+
+def backups(plugin_dir):
+    return sorted(plugin_dir.glob("credentials.json.backup.*"))
+
+
+class TestRequestValidation:
+    def test_no_file_part_is_a_400(self, api_v3_client, plugin_dir):
+        response = api_v3_client.post(URL, data={}, content_type="multipart/form-data")
+        assert response.status_code == 400
+        assert "No file provided" in response.get_json()["message"]
+
+    def test_empty_filename_is_a_400(self, api_v3_client, plugin_dir):
+        response = upload(api_v3_client, VALID_CREDENTIALS, filename="")
+        assert response.status_code == 400
+
+    @pytest.mark.parametrize("filename", ["creds.txt", "creds.pem", "creds"])
+    def test_non_json_extension_is_a_400(self, api_v3_client, plugin_dir, filename):
+        response = upload(api_v3_client, VALID_CREDENTIALS, filename=filename)
+        assert response.status_code == 400
+        assert "JSON file" in response.get_json()["message"]
+
+    def test_uppercase_json_extension_accepted(self, api_v3_client, plugin_dir):
+        assert upload(api_v3_client, VALID_CREDENTIALS,
+                      filename="CREDENTIALS.JSON").status_code == 200
+
+    def test_oversized_file_is_a_400(self, api_v3_client, plugin_dir):
+        response = upload(api_v3_client, b"x" * (1024 * 1024 + 1))
+        assert response.status_code == 400
+        assert "1MB" in response.get_json()["message"]
+        assert not (plugin_dir / "credentials.json").exists()
+
+    def test_invalid_json_is_a_400(self, api_v3_client, plugin_dir):
+        response = upload(api_v3_client, b"{not json")
+        assert response.status_code == 400
+        assert "not valid JSON" in response.get_json()["message"]
+        assert not (plugin_dir / "credentials.json").exists()
+
+    def test_missing_plugin_directory_is_a_404(self, api_v3_client, api_v3_module, tmp_path):
+        api_v3_module.api_v3.plugin_manager.get_plugin_directory.return_value = str(
+            tmp_path / "not-installed")
+        assert upload(api_v3_client, VALID_CREDENTIALS).status_code == 404
+
+
+class TestOAuthShapeValidation:
+    def test_installed_key_accepted(self, api_v3_client, plugin_dir):
+        assert upload(api_v3_client, VALID_CREDENTIALS).status_code == 200
+
+    def test_web_key_accepted(self, api_v3_client, plugin_dir):
+        assert upload(api_v3_client, {"web": {"client_id": "x"}}).status_code == 200
+
+    def test_object_without_oauth_keys_is_a_400(self, api_v3_client, plugin_dir):
+        response = upload(api_v3_client, {"something": "else"})
+        assert response.status_code == 400
+        assert "valid Google OAuth" in response.get_json()["message"]
+        assert not (plugin_dir / "credentials.json").exists()
+
+    @pytest.mark.parametrize("content", [42, "a string", [1, 2, 3], True, None])
+    def test_valid_json_that_is_not_an_object_is_rejected(
+            self, api_v3_client, plugin_dir, content):
+        # Regression: `'installed' not in 42` raises TypeError, which the
+        # bare `except Exception: pass` swallowed — the file was then saved
+        # as credentials.json despite being unusable as credentials.
+        response = upload(api_v3_client, content)
+        assert response.status_code == 400
+        assert "valid Google OAuth" in response.get_json()["message"]
+        assert not (plugin_dir / "credentials.json").exists()
+
+
+class TestSaving:
+    def test_file_written_with_contents_intact(self, api_v3_client, plugin_dir):
+        response = upload(api_v3_client, VALID_CREDENTIALS)
+        assert response.status_code == 200
+        saved = json.loads((plugin_dir / "credentials.json").read_text())
+        assert saved == VALID_CREDENTIALS
+
+    def test_response_reports_the_path(self, api_v3_client, plugin_dir):
+        body = upload(api_v3_client, VALID_CREDENTIALS).get_json()
+        assert body["path"].endswith("credentials.json")
+
+    def test_permissions_are_owner_only(self, api_v3_client, plugin_dir):
+        upload(api_v3_client, VALID_CREDENTIALS)
+        mode = stat.S_IMODE((plugin_dir / "credentials.json").stat().st_mode)
+        assert mode == 0o600
+
+    def test_first_upload_creates_no_backup(self, api_v3_client, plugin_dir):
+        upload(api_v3_client, VALID_CREDENTIALS)
+        assert backups(plugin_dir) == []
+
+    def test_overwrite_backs_up_the_previous_file(self, api_v3_client, plugin_dir):
+        (plugin_dir / "credentials.json").write_text(json.dumps({"installed": {"old": 1}}))
+        upload(api_v3_client, VALID_CREDENTIALS)
+        assert len(backups(plugin_dir)) == 1
+        assert json.loads(backups(plugin_dir)[0].read_text()) == {"installed": {"old": 1}}
+        assert json.loads((plugin_dir / "credentials.json").read_text()) == VALID_CREDENTIALS
+
+
+class TestBackupPruning:
+    def _seed(self, plugin_dir, count):
+        """Create `count` backups with distinct, increasing mtimes."""
+        now = int(time.time())
+        for i in range(count):
+            path = plugin_dir / f"credentials.json.backup.{now - (count - i) * 10}"
+            path.write_text(json.dumps({"installed": {"gen": i}}))
+            os.utime(path, (now - (count - i) * 10, now - (count - i) * 10))
+
+    def test_old_backups_are_pruned(self, api_v3_client, plugin_dir):
+        # Regression: nothing ever removed these, so a plugin directory
+        # accumulated one full copy of the user's OAuth credentials per
+        # re-upload, forever.
+        (plugin_dir / "credentials.json").write_text(json.dumps({"installed": {"cur": 1}}))
+        self._seed(plugin_dir, 7)
+        assert len(backups(plugin_dir)) == 7
+
+        upload(api_v3_client, VALID_CREDENTIALS)
+        assert len(backups(plugin_dir)) == 5
+
+    def test_the_newest_backups_are_the_ones_kept(self, api_v3_client, plugin_dir):
+        (plugin_dir / "credentials.json").write_text(json.dumps({"installed": {"cur": 1}}))
+        self._seed(plugin_dir, 7)
+
+        upload(api_v3_client, VALID_CREDENTIALS)
+        remaining = backups(plugin_dir)
+        # The just-created backup (of "cur") plus the four newest seeds.
+        contents = [json.loads(p.read_text()) for p in remaining]
+        assert {"installed": {"cur": 1}} in contents
+        assert {"installed": {"gen": 0}} not in contents  # oldest seed gone
+
+    def test_under_the_limit_nothing_is_removed(self, api_v3_client, plugin_dir):
+        (plugin_dir / "credentials.json").write_text(json.dumps({"installed": {"cur": 1}}))
+        self._seed(plugin_dir, 2)
+        upload(api_v3_client, VALID_CREDENTIALS)
+        assert len(backups(plugin_dir)) == 3  # 2 seeded + 1 new
+
+    def test_repeated_uploads_stay_bounded(self, api_v3_client, plugin_dir):
+        for i in range(10):
+            upload(api_v3_client, {"installed": {"round": i}})
+            # Distinct mtimes so ordering is well-defined between rounds.
+            for path in backups(plugin_dir):
+                os.utime(path, (path.stat().st_mtime, path.stat().st_mtime))
+            time.sleep(0.01)
+        assert len(backups(plugin_dir)) <= 5
+
+    def test_unremovable_backup_does_not_fail_the_upload(
+            self, api_v3_client, plugin_dir, monkeypatch):
+        (plugin_dir / "credentials.json").write_text(json.dumps({"installed": {"cur": 1}}))
+        self._seed(plugin_dir, 7)
+
+        def refuse(self):
+            raise OSError("read-only filesystem")
+        monkeypatch.setattr(Path, "unlink", refuse)
+
+        # Pruning is housekeeping; failing it must not lose the upload.
+        assert upload(api_v3_client, VALID_CREDENTIALS).status_code == 200

test/test_api_v3_music_auth_endpoints.py

@@ -0,0 +1,302 @@
+"""
+Endpoint tests for /plugins/authenticate/spotify and .../ytm.
+
+The Spotify step-2 handler writes a Python wrapper script to a temp file
+with the user's redirect URL embedded in it, then runs that file through
+subprocess. That is the most dangerous shape in the blueprint and had no
+tests: the URL is user input reaching generated source code.
+
+The two endpoints are NOT symmetrical, despite the matching names. Only
+Spotify has a two-step flow, a wrapper script, and a redirect_url; YTM
+just runs its script directly.
+
+Regression coverage for one fixed bug: the wrapper file was unlinked in
+the success/failure branch and again in the TimeoutExpired handler, so
+any other failure from subprocess.run — the interpreter missing, a fork
+failure, an interrupted call — left a temp file containing the user's
+redirect URL behind.
+"""
+
+import ast
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+
+@pytest.fixture
+def plugin_dir(tmp_path, api_v3_module):
+    """A plugin directory containing both auth scripts."""
+    directory = tmp_path / "plugins" / "ledmatrix-music"
+    directory.mkdir(parents=True)
+    (directory / "authenticate_spotify.py").write_text("print('spotify')\n")
+    (directory / "authenticate_ytm.py").write_text("print('ytm')\n")
+    api_v3_module.api_v3.plugin_manager.get_plugin_directory.return_value = str(directory)
+    return directory
+
+
+def completed(returncode=0, stdout="ok", stderr=""):
+    return subprocess.CompletedProcess(
+        args=["python3"], returncode=returncode, stdout=stdout, stderr=stderr)
+
+
+class TestSpotifyPreconditions:
+    URL = "/api/v3/plugins/authenticate/spotify"
+
+    def test_missing_plugin_directory_is_404(self, api_v3_client, api_v3_module, tmp_path):
+        api_v3_module.api_v3.plugin_manager.get_plugin_directory.return_value = str(
+            tmp_path / "not-installed")
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 404
+        assert response.get_json()["message"] == "Plugin not found"
+
+    def test_none_plugin_directory_is_404(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_manager.get_plugin_directory.return_value = None
+        assert api_v3_client.post(self.URL, json={}).status_code == 404
+
+    def test_missing_auth_script_is_404(self, api_v3_client, plugin_dir):
+        (plugin_dir / "authenticate_spotify.py").unlink()
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 404
+        assert "script not found" in response.get_json()["message"]
+
+
+class TestSpotifyStepTwo:
+    """redirect_url present — the wrapper-script path."""
+
+    URL = "/api/v3/plugins/authenticate/spotify"
+
+    def test_success(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed(0, "done")):
+            response = api_v3_client.post(self.URL, json={"redirect_url": "http://cb/?code=x"})
+        assert response.status_code == 200
+        body = response.get_json()
+        assert body["status"] == "success"
+        assert body["output"] == "done"
+
+    def test_script_failure_is_a_400_with_combined_output(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed(1, "out", "err")):
+            response = api_v3_client.post(self.URL, json={"redirect_url": "http://cb/?code=x"})
+        assert response.status_code == 400
+        assert response.get_json()["output"] == "outerr"
+
+    def test_timeout_is_a_408(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run",
+                          side_effect=subprocess.TimeoutExpired("python3", 120)):
+            response = api_v3_client.post(self.URL, json={"redirect_url": "http://cb/?code=x"})
+        assert response.status_code == 408
+        assert "timed out" in response.get_json()["message"]
+
+    def test_runs_a_list_argv_never_a_shell(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed()) as run:
+            api_v3_client.post(self.URL, json={"redirect_url": "http://cb/?code=x"})
+        args, kwargs = run.call_args
+        assert isinstance(args[0], list)
+        assert args[0][0] == "python3"
+        assert kwargs.get("shell") in (None, False)
+
+    def test_timeout_is_bounded(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed()) as run:
+            api_v3_client.post(self.URL, json={"redirect_url": "http://cb/?code=x"})
+        assert run.call_args.kwargs["timeout"] == 120
+
+
+class TestSpotifyWrapperCleanup:
+    URL = "/api/v3/plugins/authenticate/spotify"
+
+    def _wrapper_paths_after(self, api_v3_client, run_mock):
+        """Run the endpoint and return the wrapper path subprocess saw."""
+        seen = {}
+
+        def capture(args, **kwargs):
+            seen["path"] = args[1]
+            return run_mock(args, **kwargs)
+
+        with patch.object(subprocess, "run", side_effect=capture):
+            api_v3_client.post(self.URL, json={"redirect_url": "http://cb/?code=x"})
+        return seen["path"]
+
+    def test_removed_after_success(self, api_v3_client, plugin_dir):
+        path = self._wrapper_paths_after(api_v3_client, lambda *a, **kw: completed())
+        assert not os.path.exists(path)
+
+    def test_removed_after_script_failure(self, api_v3_client, plugin_dir):
+        path = self._wrapper_paths_after(
+            api_v3_client, lambda *a, **kw: completed(1, "out", "err"))
+        assert not os.path.exists(path)
+
+    def test_removed_after_timeout(self, api_v3_client, plugin_dir):
+        def raise_timeout(*a, **kw):
+            raise subprocess.TimeoutExpired("python3", 120)
+        path = self._wrapper_paths_after(api_v3_client, raise_timeout)
+        assert not os.path.exists(path)
+
+    def test_removed_when_subprocess_cannot_start(self, api_v3_client, plugin_dir):
+        # Regression: cleanup lived in the success/failure branch and in the
+        # TimeoutExpired handler only. An OSError from subprocess.run itself
+        # — no interpreter, fork failure — skipped both and left the wrapper,
+        # which contains the user's redirect URL, on disk.
+        def raise_oserror(*a, **kw):
+            raise OSError("[Errno 12] Cannot allocate memory")
+        path = self._wrapper_paths_after(api_v3_client, raise_oserror)
+        assert not os.path.exists(path)
+
+
+class TestSpotifyRedirectUrlIsNotInjectable:
+    """The wrapper embeds redirect_url into generated Python source."""
+
+    URL = "/api/v3/plugins/authenticate/spotify"
+
+    ADVERSARIAL = [
+        '''http://cb/?code=x"''',
+        """http://cb/?code=x'""",
+        'http://cb/?code=x\\',
+        'http://cb/?code=x\nimport os; os.system("id")',
+        'http://cb/?code=x"""\nimport os\n"""',
+        "http://cb/?code=x'''",
+        'http://cb/?code=x\\"\\n',
+        '"; import os; os.system("id"); "',
+    ]
+
+    def _wrapper_source(self, api_v3_client, redirect_url):
+        captured = {}
+
+        def capture(args, **kwargs):
+            captured["source"] = Path(args[1]).read_text()
+            return completed()
+
+        with patch.object(subprocess, "run", side_effect=capture):
+            api_v3_client.post(self.URL, json={"redirect_url": redirect_url})
+        return captured["source"]
+
+    @pytest.mark.parametrize("redirect_url", ADVERSARIAL)
+    def test_wrapper_is_still_valid_python(self, api_v3_client, plugin_dir, redirect_url):
+        # If escaping failed, the generated file would not parse at all.
+        source = self._wrapper_source(api_v3_client, redirect_url)
+        ast.parse(source)
+
+    @pytest.mark.parametrize("redirect_url", ADVERSARIAL)
+    def test_url_survives_as_one_string_literal(
+            self, api_v3_client, plugin_dir, redirect_url):
+        # Stronger than "it parses": the URL must still be a single string
+        # assigned to redirect_url, not code that escaped into statements.
+        source = self._wrapper_source(api_v3_client, redirect_url)
+        tree = ast.parse(source)
+        assigned = [
+            node.value.value for node in ast.walk(tree)
+            if isinstance(node, ast.Assign)
+            and isinstance(node.value, ast.Constant)
+            and any(getattr(t, "id", None) == "redirect_url" for t in node.targets)
+        ]
+        assert assigned == [redirect_url.strip()]
+
+    def test_injected_call_does_not_become_a_statement(self, api_v3_client, plugin_dir):
+        source = self._wrapper_source(
+            api_v3_client, 'http://cb/\nimport os; os.system("id")')
+        tree = ast.parse(source)
+        imported = {
+            alias.name for node in ast.walk(tree)
+            if isinstance(node, ast.Import) for alias in node.names
+        }
+        # The wrapper legitimately imports sys, subprocess and os; what it
+        # must not gain is a *call* smuggled in through the URL.
+        calls = [
+            node for node in ast.walk(tree)
+            if isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and node.func.attr == "system"
+        ]
+        assert calls == []
+
+
+class TestSpotifyStepOne:
+    """No redirect_url — the OAuth-URL path, which imports the script."""
+
+    URL = "/api/v3/plugins/authenticate/spotify"
+
+    def test_script_without_credentials_helper_is_an_error(
+            self, api_v3_client, plugin_dir):
+        # The stub script defines neither get_auth_url nor
+        # load_spotify_credentials, so no URL can be produced.
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code in (400, 500)
+        assert response.get_json()["status"] == "error"
+
+    def test_unusable_credentials_do_not_leak_into_the_response(
+            self, api_v3_client, plugin_dir):
+        (plugin_dir / "authenticate_spotify.py").write_text(
+            "def load_spotify_credentials():\n"
+            "    return ('id-abc', 'super-secret-value', None)\n"
+        )
+        response = api_v3_client.post(self.URL, json={})
+        assert "super-secret-value" not in response.get_data(as_text=True)
+
+    def test_script_raising_on_import_is_handled(self, api_v3_client, plugin_dir):
+        (plugin_dir / "authenticate_spotify.py").write_text("raise RuntimeError('boom')\n")
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 500
+        assert response.get_json()["status"] == "error"
+
+    def test_bodyless_post_reaches_step_one(self, api_v3_client, plugin_dir):
+        # Covered by the silent=True fix: previously a 500 from body parsing.
+        response = api_v3_client.post(self.URL)
+        assert response.status_code in (400, 500)
+        assert response.get_json()["status"] == "error"
+
+    def test_whitespace_redirect_url_is_treated_as_absent(
+            self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed()) as run:
+            api_v3_client.post(self.URL, json={"redirect_url": "   "})
+        # Step 2 never runs, so no wrapper is executed.
+        run.assert_not_called()
+
+
+class TestYouTubeMusic:
+    """No wrapper script and no redirect_url — deliberately not symmetric."""
+
+    URL = "/api/v3/plugins/authenticate/ytm"
+
+    def test_missing_plugin_directory_is_404(self, api_v3_client, api_v3_module, tmp_path):
+        api_v3_module.api_v3.plugin_manager.get_plugin_directory.return_value = str(
+            tmp_path / "not-installed")
+        assert api_v3_client.post(self.URL).status_code == 404
+
+    def test_missing_script_is_404(self, api_v3_client, plugin_dir):
+        (plugin_dir / "authenticate_ytm.py").unlink()
+        response = api_v3_client.post(self.URL)
+        assert response.status_code == 404
+        assert "script not found" in response.get_json()["message"]
+
+    def test_success(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed(0, "authorized")):
+            response = api_v3_client.post(self.URL)
+        assert response.status_code == 200
+        assert response.get_json()["output"] == "authorized"
+
+    def test_failure_is_a_400_with_combined_output(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed(1, "out", "err")):
+            response = api_v3_client.post(self.URL)
+        assert response.status_code == 400
+        assert response.get_json()["output"] == "outerr"
+
+    def test_timeout_is_a_408(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run",
+                          side_effect=subprocess.TimeoutExpired("python3", 60)):
+            assert api_v3_client.post(self.URL).status_code == 408
+
+    def test_runs_the_script_directly_without_a_shell(self, api_v3_client, plugin_dir):
+        with patch.object(subprocess, "run", return_value=completed()) as run:
+            api_v3_client.post(self.URL)
+        args, kwargs = run.call_args
+        assert args[0][0] == "python3"
+        assert args[0][1].endswith("authenticate_ytm.py")
+        assert kwargs.get("shell") in (None, False)
+        assert kwargs["timeout"] == 60

test/test_api_v3_optional_body.py

@@ -0,0 +1,136 @@
+"""
+Regression tests: POST endpoints whose body is optional must accept a
+request that has no body at all.
+
+Six handlers in api_v3 read their body as ``request.get_json() or {}``.
+The ``or {}`` states the intent plainly — every field is optional, so a
+bodyless POST should fall back to defaults. But ``get_json()`` without
+``silent=True`` raises ``UnsupportedMediaType`` when the request carries
+no JSON Content-Type, and it raises *before* ``or {}`` is evaluated. Each
+handler's catch-all then turned that into a 500.
+
+So the natural way to call these endpoints — a POST with no body, which
+is what curl, a fetch() without options, and most HTTP clients send by
+default — failed on every one of them. The shipped UI always sends a JSON
+object, which is why this went unnoticed.
+
+This file covers the endpoints whose bodyless behaviour is not already
+tested in their own suite.
+"""
+
+import re
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+
+class TestOnDemandStart:
+    URL = "/api/v3/display/on-demand/start"
+
+    def test_bodyless_post_is_not_a_server_error(self, api_v3_client, api_v3_module):
+        response = api_v3_client.post(self.URL)
+        # The endpoint may still reject the request on its own terms (no
+        # plugin_id, nothing to display); what it must not do is fail with
+        # a 500 raised out of body parsing.
+        assert response.status_code != 500
+
+    def test_json_body_still_works(self, api_v3_client, api_v3_module):
+        assert api_v3_client.post(self.URL, json={}).status_code != 500
+
+
+class TestResetPluginConfig:
+    URL = "/api/v3/plugins/config/reset"
+
+    def test_bodyless_post_is_not_a_server_error(self, api_v3_client, api_v3_module):
+        assert api_v3_client.post(self.URL).status_code != 500
+
+    def test_json_body_still_works(self, api_v3_client, api_v3_module):
+        assert api_v3_client.post(self.URL, json={}).status_code != 500
+
+
+class TestDeleteOfTheDayJson:
+    URL = "/api/v3/plugins/of-the-day/json/delete"
+
+    def test_bodyless_post_is_not_a_server_error(self, api_v3_client, api_v3_module):
+        assert api_v3_client.post(self.URL).status_code != 500
+
+    def test_json_body_still_works(self, api_v3_client, api_v3_module):
+        assert api_v3_client.post(self.URL, json={}).status_code != 500
+
+
+class TestPluginLimits:
+    URL = "/api/v3/plugins/clock/limits"
+
+    def test_bodyless_post_is_not_a_server_error(self, api_v3_client, api_v3_module):
+        assert api_v3_client.post(self.URL).status_code != 500
+
+
+class TestMissingBodyGivesTheDeclaredError:
+    """Handlers that answer "No data provided" must actually be able to.
+
+    A second group of handlers reads `data = request.get_json()` and then
+    guards with `if not data: return 400`. That guard is unreachable for a
+    request with no JSON body, because get_json() raises first — so the
+    caller got a 500 "an error occurred; see logs for details" instead of
+    the 400 the handler plainly intends to send.
+    """
+
+    @pytest.mark.parametrize("url", [
+        "/api/v3/plugins/install",
+        "/api/v3/plugins/install-from-url",
+        "/api/v3/plugins/registry-from-url",
+        "/api/v3/config/raw/main",
+        "/api/v3/config/raw/secrets",
+        "/api/v3/cache/delete",
+    ])
+    def test_bodyless_post_gets_a_400_not_a_500(self, api_v3_client, api_v3_module, url):
+        response = api_v3_client.post(url)
+        assert response.status_code == 400, (
+            f"{url} answered {response.status_code}: "
+            f"{response.get_data(as_text=True)[:200]}")
+
+    @pytest.mark.parametrize("url", [
+        "/api/v3/plugins/install",
+        "/api/v3/config/raw/main",
+    ])
+    def test_malformed_json_gets_a_400_not_a_500(self, api_v3_client, api_v3_module, url):
+        response = api_v3_client.post(
+            url, data="{not json", content_type="application/json")
+        assert response.status_code == 400
+
+
+class TestNoBodyReadContradictsItsOwnGuard:
+    SOURCE = Path(__file__).parent.parent / "web_interface/blueprints/api_v3.py"
+
+    def test_no_or_default_read_is_unguarded(self):
+        """`get_json() or <default>` is a contradiction without silent=True.
+
+        Writing `or {}` declares the body optional; omitting silent=True
+        means the call raises before the default can apply.
+        """
+        offenders = [
+            line.strip() for line in self.SOURCE.read_text().splitlines()
+            if "request.get_json()" in line and " or " in line
+        ]
+        assert offenders == [], (
+            "these reads declare a default but raise before reaching it; "
+            f"use get_json(silent=True): {offenders}")
+
+    def test_no_not_data_guard_is_unreachable(self):
+        """A `if not data:` guard needs a read that can actually return None."""
+        lines = self.SOURCE.read_text().splitlines()
+        offenders = []
+        for i, line in enumerate(lines):
+            if re.search(r"=\s*request\.get_json\(\)\s*$", line):
+                window = "\n".join(lines[i + 1:i + 3])
+                if re.search(r"if\s+(not\s+data\b|data\s+is\s+None)", window):
+                    offenders.append(f"line {i + 1}: {line.strip()}")
+        assert offenders == [], (
+            "these handlers guard on a missing body but raise before the "
+            f"guard runs; use get_json(silent=True): {offenders}")

test/test_api_v3_plugin_install_endpoints.py

@@ -0,0 +1,302 @@
+"""
+Endpoint tests for POST /plugins/install and POST /plugins/install-from-url.
+
+Both were only ever tested at the PluginStoreManager layer, so the route
+logic — the queue-vs-direct branch, schema invalidation, plugin discovery,
+state and history recording — was unexercised.
+
+/plugins/install carries the same install logic twice: once inside the
+operation-queue callback and once in the direct fallback. The paired
+tests below assert both branches produce the same side effects, so the
+duplication cannot quietly drift.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+INSTALL = "/api/v3/plugins/install"
+FROM_URL = "/api/v3/plugins/install-from-url"
+
+
+@pytest.fixture
+def queued(api_v3_module):
+    """Enable the operation queue and run its callback synchronously."""
+    queue = MagicMock()
+
+    def enqueue(operation_type, plugin_id, operation_callback=None):
+        queue.callback_result = operation_callback(MagicMock())
+        return "op-123"
+
+    queue.enqueue_operation.side_effect = enqueue
+    api_v3_module.api_v3.operation_queue = queue
+    return queue
+
+
+def side_effects(module):
+    """The manager calls a successful install is expected to make."""
+    api = module.api_v3
+    return {
+        "schema_invalidated": api.schema_manager.invalidate_cache.call_args_list,
+        "discovered": api.plugin_manager.discover_plugins.call_count,
+        "loaded": api.plugin_manager.load_plugin.call_args_list,
+        "state_set": api.plugin_state_manager.set_plugin_installed.call_args_list,
+        "history": api.operation_history.record_operation.call_args_list,
+    }
+
+
+class TestInstallValidation:
+    def test_uninitialized_store_manager_is_a_500(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager = None
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert response.status_code == 500
+        assert "not initialized" in response.get_json()["message"]
+
+    def test_missing_plugin_id_is_a_400(self, api_v3_client, api_v3_module):
+        response = api_v3_client.post(INSTALL, json={})
+        assert response.status_code == 400
+        assert "plugin_id required" in response.get_json()["message"]
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.assert_not_called()
+
+    def test_empty_body_is_a_400(self, api_v3_client, api_v3_module):
+        assert api_v3_client.post(INSTALL, json=None).status_code == 400
+
+
+class TestInstallDirectPath:
+    """operation_queue is None — the fallback branch."""
+
+    def test_success(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert response.status_code == 200
+        assert response.get_json()["status"] == "success"
+
+    def test_success_side_effects(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        effects = side_effects(api_v3_module)
+        assert effects["schema_invalidated"] == [(("clock",), {})]
+        assert effects["discovered"] == 1
+        assert effects["loaded"] == [(("clock",), {})]
+        assert effects["state_set"] == [(("clock",), {})]
+        assert effects["history"][0].kwargs["status"] == "success"
+
+    def test_branch_forwarded_to_the_manager(self, api_v3_client, api_v3_module):
+        manager = api_v3_module.api_v3.plugin_store_manager
+        manager.install_plugin.return_value = True
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock", "branch": "dev"})
+        manager.install_plugin.assert_called_once_with("clock", branch="dev")
+
+    def test_branch_named_in_the_message(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock", "branch": "dev"})
+        assert "(branch: dev)" in response.get_json()["message"]
+
+    def test_failure_is_a_500(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = False
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert response.status_code == 500
+        assert "Failed to install" in response.get_json()["message"]
+
+    def test_failure_mentions_missing_registry_entry(self, api_v3_client, api_v3_module):
+        manager = api_v3_module.api_v3.plugin_store_manager
+        manager.install_plugin.return_value = False
+        manager.get_plugin_info.return_value = None
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "ghost"})
+        assert "not found in registry" in response.get_json()["message"]
+
+    def test_failure_omits_registry_note_when_plugin_is_known(
+            self, api_v3_client, api_v3_module):
+        manager = api_v3_module.api_v3.plugin_store_manager
+        manager.install_plugin.return_value = False
+        manager.get_plugin_info.return_value = {"id": "clock"}
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert "not found in registry" not in response.get_json()["message"]
+
+    def test_failure_recorded_in_history(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = False
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        record = api_v3_module.api_v3.operation_history.record_operation.call_args
+        assert record.kwargs["status"] == "failed"
+
+    def test_no_side_effects_on_failure(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = False
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        effects = side_effects(api_v3_module)
+        assert effects["schema_invalidated"] == []
+        assert effects["loaded"] == []
+        assert effects["state_set"] == []
+
+
+class TestInstallQueuedPath:
+    """operation_queue present — the callback branch."""
+
+    def test_returns_an_operation_id(self, api_v3_client, api_v3_module, queued):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert response.status_code == 200
+        assert response.get_json()["data"]["operation_id"] == "op-123"
+
+    def test_message_says_queued(self, api_v3_client, api_v3_module, queued):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert "queued" in response.get_json()["message"]
+
+    def test_callback_success_side_effects(self, api_v3_client, api_v3_module, queued):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        effects = side_effects(api_v3_module)
+        assert effects["schema_invalidated"] == [(("clock",), {})]
+        assert effects["discovered"] == 1
+        assert effects["loaded"] == [(("clock",), {})]
+        assert effects["state_set"] == [(("clock",), {})]
+        assert effects["history"][0].kwargs["status"] == "success"
+
+    def test_callback_reports_success(self, api_v3_client, api_v3_module, queued):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert queued.callback_result["success"] is True
+
+    def test_callback_failure_raises_for_the_queue(self, api_v3_client, api_v3_module, queued):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = False
+        # The callback signals failure by raising, so the queue can mark the
+        # operation failed; the route's catch-all turns it into a 500.
+        response = api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        assert response.status_code == 500
+
+    def test_callback_failure_recorded_in_history(self, api_v3_client, api_v3_module, queued):
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = False
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock"})
+        record = api_v3_module.api_v3.operation_history.record_operation.call_args
+        assert record.kwargs["status"] == "failed"
+
+    def test_branch_forwarded_from_the_callback(self, api_v3_client, api_v3_module, queued):
+        manager = api_v3_module.api_v3.plugin_store_manager
+        manager.install_plugin.return_value = True
+        api_v3_client.post(INSTALL, json={"plugin_id": "clock", "branch": "dev"})
+        manager.install_plugin.assert_called_once_with("clock", branch="dev")
+
+
+class TestInstallPathsAgree:
+    """The queue callback and the direct fallback duplicate the same logic."""
+
+    def _run(self, client, module, install_ok, queue):
+        module.api_v3.plugin_store_manager.install_plugin.return_value = install_ok
+        client.post(INSTALL, json={"plugin_id": "clock", "branch": "dev"})
+        return side_effects(module)
+
+    def test_success_side_effects_match(self, api_v3_client, api_v3_module):
+        direct = self._run(api_v3_client, api_v3_module, True, None)
+
+        # Reset and re-run through the queue.
+        for mock in (api_v3_module.api_v3.schema_manager,
+                     api_v3_module.api_v3.plugin_manager,
+                     api_v3_module.api_v3.plugin_state_manager,
+                     api_v3_module.api_v3.operation_history):
+            mock.reset_mock()
+        queue = MagicMock()
+        queue.enqueue_operation.side_effect = (
+            lambda t, p, operation_callback=None: operation_callback(MagicMock()) and "op")
+        api_v3_module.api_v3.operation_queue = queue
+        queued = self._run(api_v3_client, api_v3_module, True, queue)
+
+        assert direct["schema_invalidated"] == queued["schema_invalidated"]
+        assert direct["discovered"] == queued["discovered"]
+        assert direct["loaded"] == queued["loaded"]
+        assert direct["state_set"] == queued["state_set"]
+        assert (direct["history"][0].kwargs["status"]
+                == queued["history"][0].kwargs["status"])
+        assert (direct["history"][0].kwargs["details"]
+                == queued["history"][0].kwargs["details"])
+
+    def test_only_the_message_wording_differs(self, api_v3_client, api_v3_module):
+        # Characterized: the direct path says "Plugin installed
+        # successfully" while the queue callback says "Plugin clock
+        # installed successfully". Cosmetic, and the queue's text is
+        # internal to the operation record rather than the HTTP response.
+        api_v3_module.api_v3.plugin_store_manager.install_plugin.return_value = True
+        direct = api_v3_client.post(INSTALL, json={"plugin_id": "clock"}).get_json()
+        assert direct["message"] == "Plugin installed successfully"
+
+
+class TestInstallFromUrl:
+    def test_uninitialized_store_manager_is_a_500(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager = None
+        assert api_v3_client.post(FROM_URL, json={"repo_url": "http://x"}).status_code == 500
+
+    def test_missing_repo_url_is_a_400(self, api_v3_client, api_v3_module):
+        response = api_v3_client.post(FROM_URL, json={})
+        assert response.status_code == 400
+        assert "repo_url required" in response.get_json()["message"]
+
+    def test_success(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_from_url.return_value = {
+            "success": True, "plugin_id": "clock", "name": "Clock"}
+        response = api_v3_client.post(FROM_URL, json={"repo_url": "https://github.com/o/r"})
+        assert response.status_code == 200
+        body = response.get_json()
+        assert body["plugin_id"] == "clock"
+        assert body["name"] == "Clock"
+
+    def test_all_optional_arguments_forwarded(self, api_v3_client, api_v3_module):
+        manager = api_v3_module.api_v3.plugin_store_manager
+        manager.install_from_url.return_value = {"success": True, "plugin_id": "clock"}
+        api_v3_client.post(FROM_URL, json={
+            "repo_url": "  https://github.com/o/r  ",
+            "plugin_id": "clock",
+            "plugin_path": "plugins/clock",
+            "branch": "dev",
+        })
+        manager.install_from_url.assert_called_once_with(
+            repo_url="https://github.com/o/r",
+            plugin_id="clock",
+            plugin_path="plugins/clock",
+            branch="dev",
+        )
+
+    def test_success_invalidates_schema_and_loads_plugin(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_from_url.return_value = {
+            "success": True, "plugin_id": "clock"}
+        api_v3_client.post(FROM_URL, json={"repo_url": "http://x"})
+        api_v3_module.api_v3.schema_manager.invalidate_cache.assert_called_once_with("clock")
+        api_v3_module.api_v3.plugin_manager.load_plugin.assert_called_once_with("clock")
+
+    def test_success_without_plugin_id_skips_discovery(self, api_v3_client, api_v3_module):
+        # install_from_url can succeed without naming the plugin; there is
+        # then nothing to invalidate or load.
+        api_v3_module.api_v3.plugin_store_manager.install_from_url.return_value = {
+            "success": True, "plugin_id": None}
+        api_v3_client.post(FROM_URL, json={"repo_url": "http://x"})
+        api_v3_module.api_v3.schema_manager.invalidate_cache.assert_not_called()
+        api_v3_module.api_v3.plugin_manager.load_plugin.assert_not_called()
+
+    def test_branch_from_result_included(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_from_url.return_value = {
+            "success": True, "plugin_id": "clock", "branch": "dev"}
+        body = api_v3_client.post(FROM_URL, json={"repo_url": "http://x"}).get_json()
+        assert body["branch"] == "dev"
+        assert "(branch: dev)" in body["message"]
+
+    def test_failure_reports_the_managers_error(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_from_url.return_value = {
+            "success": False, "error": "repo not found"}
+        response = api_v3_client.post(FROM_URL, json={"repo_url": "http://x"})
+        assert response.status_code == 500
+        assert response.get_json()["message"] == "repo not found"
+
+    def test_failure_without_error_uses_fallback_text(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_from_url.return_value = {
+            "success": False}
+        response = api_v3_client.post(FROM_URL, json={"repo_url": "http://x"})
+        assert "Failed to install plugin from URL" in response.get_json()["message"]
+
+    def test_manager_exception_is_a_500(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.install_from_url.side_effect = (
+            RuntimeError("boom"))
+        assert api_v3_client.post(FROM_URL, json={"repo_url": "http://x"}).status_code == 500

test/test_api_v3_registry_endpoints.py

@@ -0,0 +1,174 @@
+"""
+Endpoint tests for the plugin-registry routes in api_v3:
+POST /plugins/store/refresh and POST /plugins/registry-from-url.
+
+Both reach out to the network through PluginStoreManager (mocked here) and
+had no endpoint-level coverage; registry-from-url in particular takes a
+user-supplied URL and hands it straight to the manager.
+"""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+
+class TestRefreshPluginStore:
+    URL = "/api/v3/plugins/store/refresh"
+
+    def test_uninitialized_manager_is_a_500(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager = None
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 500
+        assert "not initialized" in response.get_json()["message"]
+
+    def test_success_reports_plugin_count(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.return_value = {
+            "plugins": [{"id": "a"}, {"id": "b"}, {"id": "c"}]}
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 200
+        assert response.get_json()["plugin_count"] == 3
+
+    def test_forces_a_refresh_rather_than_using_cache(self, api_v3_client, api_v3_module):
+        manager = api_v3_module.api_v3.plugin_store_manager
+        manager.fetch_registry.return_value = {"plugins": []}
+        api_v3_client.post(self.URL, json={})
+        manager.fetch_registry.assert_called_once_with(force_refresh=True)
+
+    def test_empty_registry_reports_zero(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.return_value = {}
+        response = api_v3_client.post(self.URL, json={})
+        assert response.get_json()["plugin_count"] == 0
+
+    def test_no_body_is_accepted(self, api_v3_client, api_v3_module):
+        # Regression: `request.get_json() or {}` says a missing body is
+        # fine, but get_json() raises UnsupportedMediaType before `or {}`
+        # is reached, so a bodyless POST — the natural way to call a
+        # refresh endpoint — came back 500.
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.return_value = {"plugins": []}
+        assert api_v3_client.post(self.URL).status_code == 200
+
+    def test_body_without_json_content_type_is_accepted(
+            self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.return_value = {"plugins": []}
+        response = api_v3_client.post(self.URL, data="", content_type="text/plain")
+        assert response.status_code == 200
+
+    def test_malformed_json_body_falls_back_to_defaults(
+            self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.return_value = {"plugins": []}
+        response = api_v3_client.post(
+            self.URL, data="{not json", content_type="application/json")
+        assert response.status_code == 200
+
+    @pytest.mark.parametrize("key", ["fetch_commit_info", "fetch_latest_versions"])
+    def test_either_commit_info_key_extends_the_message(
+            self, api_v3_client, api_v3_module, key):
+        # fetch_latest_versions is the older spelling; both must work.
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.return_value = {"plugins": []}
+        response = api_v3_client.post(self.URL, json={key: True})
+        assert "commit metadata" in response.get_json()["message"]
+
+    def test_message_stays_plain_without_the_flag(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.return_value = {"plugins": []}
+        response = api_v3_client.post(self.URL, json={})
+        assert response.get_json()["message"] == "Plugin store refreshed"
+
+    def test_network_failure_is_a_500(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.side_effect = (
+            ConnectionError("github unreachable"))
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 500
+        assert response.get_json()["message"] == "An error occurred; see logs for details"
+
+    def test_failure_body_carries_no_traceback_or_paths(
+            self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry.side_effect = (
+            RuntimeError("failed at /home/user/LEDMatrix/src/secret.py line 42"))
+        body = api_v3_client.post(self.URL, json={}).get_json()
+        assert "Traceback" not in str(body)
+        # `details` is describe_exception output: one line, type-named,
+        # credential-redacted. It may quote the message, but never a stack.
+        assert body["details"].startswith("RuntimeError:")
+        assert "\n" not in body["details"]
+
+
+class TestRegistryFromUrl:
+    URL = "/api/v3/plugins/registry-from-url"
+
+    def test_uninitialized_manager_is_a_500(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager = None
+        response = api_v3_client.post(self.URL, json={"repo_url": "http://x"})
+        assert response.status_code == 500
+
+    def test_missing_repo_url_is_a_400(self, api_v3_client, api_v3_module):
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 400
+        assert "repo_url required" in response.get_json()["message"]
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry_from_url.assert_not_called()
+
+    def test_success_returns_the_plugin_list(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry_from_url.return_value = {
+            "plugins": [{"id": "clock"}]}
+        response = api_v3_client.post(
+            self.URL, json={"repo_url": "https://github.com/o/r"})
+        assert response.status_code == 200
+        body = response.get_json()
+        assert body["plugins"] == [{"id": "clock"}]
+        assert body["registry_url"] == "https://github.com/o/r"
+
+    def test_url_is_trimmed_before_use(self, api_v3_client, api_v3_module):
+        manager = api_v3_module.api_v3.plugin_store_manager
+        manager.fetch_registry_from_url.return_value = {"plugins": []}
+        api_v3_client.post(self.URL, json={"repo_url": "  https://github.com/o/r  "})
+        manager.fetch_registry_from_url.assert_called_once_with("https://github.com/o/r")
+
+    def test_registry_without_plugins_key_returns_empty_list(
+            self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry_from_url.return_value = {
+            "other": 1}
+        response = api_v3_client.post(self.URL, json={"repo_url": "http://x"})
+        assert response.get_json()["plugins"] == []
+
+    def test_no_registry_found_is_a_400(self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry_from_url.return_value = None
+        response = api_v3_client.post(self.URL, json={"repo_url": "http://x/not-a-registry"})
+        assert response.status_code == 400
+        assert "Failed to fetch registry" in response.get_json()["message"]
+
+    @pytest.mark.parametrize("url", [
+        "not a url",
+        "javascript:alert(1)",
+        "file:///etc/passwd",
+        "http://localhost:8080/admin",
+    ])
+    def test_unusable_urls_fail_cleanly(self, api_v3_client, api_v3_module, url):
+        # Characterization: the handler performs no URL validation of its
+        # own — whatever the manager makes of the URL decides the outcome.
+        # What is pinned here is that a rejected URL produces a clean 400
+        # rather than a traceback or a 500.
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry_from_url.return_value = None
+        response = api_v3_client.post(self.URL, json={"repo_url": url})
+        assert response.status_code == 400
+        assert "Traceback" not in str(response.get_json())
+
+    def test_fetch_exception_is_a_500_without_internals(
+            self, api_v3_client, api_v3_module):
+        api_v3_module.api_v3.plugin_store_manager.fetch_registry_from_url.side_effect = (
+            ValueError("parse failed in /srv/app/internal.py"))
+        response = api_v3_client.post(self.URL, json={"repo_url": "http://x"})
+        assert response.status_code == 500
+        body = response.get_json()
+        assert body["message"] == "An error occurred; see logs for details"
+        assert "Traceback" not in str(body)
+
+    def test_non_string_repo_url_is_a_500_not_a_crash(
+            self, api_v3_client, api_v3_module):
+        # .strip() on a non-string raises; the handler's catch-all turns
+        # that into a 500 rather than propagating.
+        response = api_v3_client.post(self.URL, json={"repo_url": 12345})
+        assert response.status_code == 500

test/test_api_v3_wifi_endpoints.py

@@ -0,0 +1,240 @@
+"""
+Endpoint tests for the /wifi/* routes in api_v3.
+
+These routes drive the host's actual networking — connecting, dropping a
+connection, switching the radio off — and had no endpoint-level tests at
+all. WiFiManager is mocked throughout; nothing here may touch real
+networking.
+
+Each handler does `from src.wifi_manager import WiFiManager` inside the
+function body, so the patch target is the class at its definition site.
+"""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from test._api_v3_test_helpers import api_v3_client, api_v3_module  # noqa: F401,E402
+
+
+@pytest.fixture
+def wifi_manager():
+    """Patch WiFiManager where it is defined; yield the instance mock."""
+    with patch("src.wifi_manager.WiFiManager") as cls:
+        instance = MagicMock()
+        cls.return_value = instance
+        yield instance
+
+
+class TestConnect:
+    URL = "/api/v3/wifi/connect"
+
+    def test_success(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (True, "Connected to HomeNet")
+        response = api_v3_client.post(self.URL, json={"ssid": "HomeNet", "password": "pw"})
+        assert response.status_code == 200
+        assert response.get_json()["message"] == "Connected to HomeNet"
+        wifi_manager.connect_to_network.assert_called_once_with("HomeNet", "pw")
+
+    def test_missing_body_rejected(self, api_v3_client, wifi_manager):
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 400
+        wifi_manager.connect_to_network.assert_not_called()
+
+    def test_missing_ssid_rejected(self, api_v3_client, wifi_manager):
+        response = api_v3_client.post(self.URL, json={"password": "pw"})
+        assert response.status_code == 400
+        assert "SSID is required" in response.get_json()["message"]
+        wifi_manager.connect_to_network.assert_not_called()
+
+    @pytest.mark.parametrize("ssid", ["", "   ", "\t"])
+    def test_blank_ssid_rejected(self, api_v3_client, wifi_manager, ssid):
+        response = api_v3_client.post(self.URL, json={"ssid": ssid})
+        assert response.status_code == 400
+        wifi_manager.connect_to_network.assert_not_called()
+
+    def test_ssid_is_trimmed(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (True, "ok")
+        api_v3_client.post(self.URL, json={"ssid": "  HomeNet  "})
+        wifi_manager.connect_to_network.assert_called_once_with("HomeNet", "")
+
+    def test_missing_password_becomes_empty_string(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (True, "ok")
+        api_v3_client.post(self.URL, json={"ssid": "OpenNet"})
+        wifi_manager.connect_to_network.assert_called_once_with("OpenNet", "")
+
+    def test_null_password_becomes_empty_string(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (True, "ok")
+        api_v3_client.post(self.URL, json={"ssid": "OpenNet", "password": None})
+        wifi_manager.connect_to_network.assert_called_once_with("OpenNet", "")
+
+    def test_failure_reports_the_managers_reason(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (False, "Bad password")
+        response = api_v3_client.post(self.URL, json={"ssid": "HomeNet"})
+        assert response.status_code == 400
+        assert response.get_json()["message"] == "Bad password"
+
+    def test_failure_without_reason_uses_fallback_text(self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.return_value = (False, None)
+        response = api_v3_client.post(self.URL, json={"ssid": "HomeNet"})
+        assert response.status_code == 400
+        assert response.get_json()["message"] == "Failed to connect to network"
+
+    def test_manager_exception_is_a_500_without_leaking_internals(
+            self, api_v3_client, wifi_manager):
+        wifi_manager.connect_to_network.side_effect = RuntimeError(
+            "/usr/lib/secret/path blew up")
+        response = api_v3_client.post(self.URL, json={"ssid": "HomeNet"})
+        assert response.status_code == 500
+        body = response.get_json()
+        assert body["message"] == "An error occurred; see logs for details"
+        # `details` comes from describe_exception, which is deliberately
+        # safe to return (redacted, capped) — it names the type.
+        assert "RuntimeError" in body["details"]
+
+
+class TestDisconnect:
+    URL = "/api/v3/wifi/disconnect"
+
+    def test_success(self, api_v3_client, wifi_manager):
+        wifi_manager.disconnect_from_network.return_value = (True, "Disconnected")
+        response = api_v3_client.post(self.URL)
+        assert response.status_code == 200
+        assert response.get_json()["message"] == "Disconnected"
+
+    def test_failure(self, api_v3_client, wifi_manager):
+        wifi_manager.disconnect_from_network.return_value = (False, "Not connected")
+        response = api_v3_client.post(self.URL)
+        assert response.status_code == 400
+        assert response.get_json()["message"] == "Not connected"
+
+    def test_failure_without_reason_uses_fallback(self, api_v3_client, wifi_manager):
+        wifi_manager.disconnect_from_network.return_value = (False, "")
+        response = api_v3_client.post(self.URL)
+        assert response.get_json()["message"] == "Failed to disconnect from network"
+
+    def test_exception_is_a_500(self, api_v3_client, wifi_manager):
+        wifi_manager.disconnect_from_network.side_effect = OSError("nmcli missing")
+        assert api_v3_client.post(self.URL).status_code == 500
+
+
+class TestApMode:
+    ENABLE = "/api/v3/wifi/ap/enable"
+    DISABLE = "/api/v3/wifi/ap/disable"
+
+    def test_enable_success(self, api_v3_client, wifi_manager):
+        wifi_manager.enable_ap_mode.return_value = (True, "AP enabled")
+        response = api_v3_client.post(self.ENABLE, json={})
+        assert response.status_code == 200
+        wifi_manager.enable_ap_mode.assert_called_once_with(force=False)
+
+    @pytest.mark.parametrize("raw,expected", [
+        (True, True), (False, False),
+        ("true", True), ("TRUE", True), ("1", True),
+        ("false", False), ("no", False), ("yes", False),
+        (1, False),  # only real True or the listed strings count
+    ])
+    def test_force_coercion(self, api_v3_client, wifi_manager, raw, expected):
+        wifi_manager.enable_ap_mode.return_value = (True, "ok")
+        api_v3_client.post(self.ENABLE, json={"force": raw})
+        wifi_manager.enable_ap_mode.assert_called_once_with(force=expected)
+
+    def test_enable_without_body(self, api_v3_client, wifi_manager):
+        wifi_manager.enable_ap_mode.return_value = (True, "ok")
+        assert api_v3_client.post(self.ENABLE).status_code == 200
+
+    def test_enable_failure(self, api_v3_client, wifi_manager):
+        wifi_manager.enable_ap_mode.return_value = (False, "hostapd missing")
+        response = api_v3_client.post(self.ENABLE, json={})
+        assert response.status_code == 400
+        assert response.get_json()["message"] == "hostapd missing"
+
+    def test_disable_success(self, api_v3_client, wifi_manager):
+        wifi_manager.disable_ap_mode.return_value = (True, "AP disabled")
+        assert api_v3_client.post(self.DISABLE).status_code == 200
+
+    def test_disable_failure(self, api_v3_client, wifi_manager):
+        wifi_manager.disable_ap_mode.return_value = (False, "not running")
+        assert api_v3_client.post(self.DISABLE).status_code == 400
+
+    def test_enable_exception_is_a_500(self, api_v3_client, wifi_manager):
+        wifi_manager.enable_ap_mode.side_effect = RuntimeError("boom")
+        assert api_v3_client.post(self.ENABLE, json={}).status_code == 500
+
+
+class TestRadio:
+    URL = "/api/v3/wifi/radio"
+
+    def test_get_state(self, api_v3_client, wifi_manager):
+        wifi_manager.get_wifi_radio_state.return_value = {
+            "enabled": True, "ethernet_connected": False}
+        response = api_v3_client.get(self.URL)
+        assert response.status_code == 200
+        assert response.get_json()["data"]["enabled"] is True
+
+    def test_get_state_exception_is_a_500(self, api_v3_client, wifi_manager):
+        wifi_manager.get_wifi_radio_state.side_effect = OSError("rfkill missing")
+        assert api_v3_client.get(self.URL).status_code == 500
+
+    def test_enabled_is_required(self, api_v3_client, wifi_manager):
+        response = api_v3_client.post(self.URL, json={})
+        assert response.status_code == 400
+        assert "enabled is required" in response.get_json()["message"]
+        wifi_manager.set_wifi_radio.assert_not_called()
+
+    def test_enable_success(self, api_v3_client, wifi_manager):
+        wifi_manager.set_wifi_radio.return_value = (True, "Radio on", None)
+        wifi_manager.get_wifi_radio_state.return_value = {"enabled": True}
+        response = api_v3_client.post(self.URL, json={"enabled": True})
+        assert response.status_code == 200
+        wifi_manager.set_wifi_radio.assert_called_once_with(True, force=False)
+
+    @pytest.mark.parametrize("raw,expected", [
+        (True, True), ("true", True), ("1", True), ("yes", True),
+        (False, False), ("false", False), ("off", False), (0, False),
+    ])
+    def test_enabled_coercion_is_string_aware(
+            self, api_v3_client, wifi_manager, raw, expected):
+        # bool("false") is True, so the endpoint parses strings explicitly
+        # rather than trusting truthiness — it is a public contract, not
+        # only the shipped UI which always sends real JSON booleans.
+        wifi_manager.set_wifi_radio.return_value = (True, "ok", None)
+        wifi_manager.get_wifi_radio_state.return_value = {}
+        api_v3_client.post(self.URL, json={"enabled": raw})
+        wifi_manager.set_wifi_radio.assert_called_once_with(expected, force=False)
+
+    def test_force_passed_through(self, api_v3_client, wifi_manager):
+        wifi_manager.set_wifi_radio.return_value = (True, "ok", None)
+        wifi_manager.get_wifi_radio_state.return_value = {}
+        api_v3_client.post(self.URL, json={"enabled": False, "force": "true"})
+        wifi_manager.set_wifi_radio.assert_called_once_with(False, force=True)
+
+    def test_refusal_reports_reason(self, api_v3_client, wifi_manager):
+        # Disabling the radio without Ethernet would lock the user out of
+        # this very interface, so the manager can refuse with a reason.
+        wifi_manager.set_wifi_radio.return_value = (
+            False, "Refusing: no wired fallback", "no_ethernet")
+        response = api_v3_client.post(self.URL, json={"enabled": False})
+        assert response.status_code == 400
+        body = response.get_json()
+        assert body["reason"] == "no_ethernet"
+        assert "Refusing" in body["message"]
+
+    def test_exception_is_a_500(self, api_v3_client, wifi_manager):
+        wifi_manager.set_wifi_radio.side_effect = RuntimeError("boom")
+        assert api_v3_client.post(self.URL, json={"enabled": True}).status_code == 500
+
+
+class TestNoRealNetworking:
+    def test_wifi_manager_is_never_constructed_for_real(self, api_v3_client):
+        # Guard against a future refactor moving the import to module level,
+        # where the fixture's patch of the definition site would stop
+        # applying and the tests would start driving real networking.
+        with patch("src.wifi_manager.WiFiManager") as cls:
+            cls.return_value.disconnect_from_network.return_value = (True, "ok")
+            api_v3_client.post("/api/v3/wifi/disconnect")
+            assert cls.called

test/test_base_odds_manager.py

@@ -8,7 +8,9 @@ is_odds_available's ML-blind truth table, the fixed format_odds_summary
 gate (money-line-only odds now format), get_odds_for_games, and
 configuration loading.
 
-No real network: src.base_odds_manager.requests.get is always patched.
+No real network: requests.Session.get is always patched. The odds path sends
+its requests through a session so it can identify itself to ESPN, so patching
+the module-level requests.get would no longer intercept anything.
 """
 
 from unittest.mock import MagicMock, patch
@@ -59,7 +61,7 @@ def manager(cache_manager):
 
 @pytest.fixture
 def mock_get():
-    with patch('src.base_odds_manager.requests.get') as m:
+    with patch('src.base_odds_manager.requests.Session.get') as m:
         m.return_value = _make_response({'items': [dict(FULL_ITEM)]})
         yield m
 

test/test_cache_cleanup_thread_ownership.py

@@ -0,0 +1,146 @@
+"""Tests that one cache directory gets one cleanup thread per process.
+
+The sweep lists a directory and deletes from it, so a second thread over the
+same directory only duplicates the scan. Nothing enforced that: every
+CacheManager started its own, and since the loop closes over `self`, a
+discarded manager could never be collected -- its thread stayed alive and
+re-scanned the same directory every 24 hours for the life of the process.
+
+On the dev rig a display process carried three, for one cache directory:
+
+    14:22:59.954  display_controller       (the real one)
+    14:22:59.973  startup validation, run 1  (discarded)
+    14:23:01.055  startup validation, run 2  (discarded)
+
+Startup validation runs twice and built a throwaway manager each time, purely
+to read a directory path.
+"""
+
+import threading
+
+import pytest
+
+from src.cache_manager import CacheManager
+
+
+@pytest.fixture(autouse=True)
+def _clean_registry():
+    CacheManager._cleanup_owners.clear()
+    yield
+    for owner in list(CacheManager._cleanup_owners.values()):
+        owner.stop_cleanup_thread()
+    CacheManager._cleanup_owners.clear()
+
+
+def _live_cleanup_threads():
+    return [t for t in threading.enumerate()
+            if t.name == 'DiskCacheCleanup' and t.is_alive()]
+
+
+@pytest.fixture
+def manager(tmp_path, monkeypatch):
+    """A CacheManager pinned to a temp dir, so tests never touch the real one."""
+    monkeypatch.setattr(CacheManager, '_get_writable_cache_dir',
+                        lambda self: str(tmp_path))
+    return CacheManager
+
+
+class TestOneThreadPerDirectory:
+    def test_a_single_manager_starts_one(self, manager):
+        before = len(_live_cleanup_threads())
+        m = manager()
+        try:
+            assert len(_live_cleanup_threads()) == before + 1
+        finally:
+            m.stop_cleanup_thread()
+
+    def test_three_managers_still_start_one(self, manager):
+        # Exactly the rig's shape: the real manager plus two throwaways.
+        before = len(_live_cleanup_threads())
+        managers = [manager() for _ in range(3)]
+        try:
+            assert len(_live_cleanup_threads()) == before + 1
+        finally:
+            for m in managers:
+                m.stop_cleanup_thread()
+
+    def test_the_first_one_owns_it(self, manager):
+        first, second = manager(), manager()
+        try:
+            assert CacheManager._cleanup_owners[first.cache_dir] is first
+            assert second._cleanup_thread is None
+        finally:
+            first.stop_cleanup_thread()
+            second.stop_cleanup_thread()
+
+    def test_the_survivor_can_take_over(self, manager):
+        first = manager()
+        first.stop_cleanup_thread()
+        assert not _live_cleanup_threads()
+
+        second = manager()
+        try:
+            # Ownership was released, so the directory is swept again rather
+            # than being left permanently unclaimed by a dead owner.
+            assert len(_live_cleanup_threads()) == 1
+            assert CacheManager._cleanup_owners[second.cache_dir] is second
+        finally:
+            second.stop_cleanup_thread()
+
+    def test_stopping_a_non_owner_does_not_unclaim_the_directory(self, manager):
+        first, second = manager(), manager()
+        try:
+            second.stop_cleanup_thread()      # never owned it
+            assert CacheManager._cleanup_owners[first.cache_dir] is first
+            assert len(_live_cleanup_threads()) == 1
+        finally:
+            first.stop_cleanup_thread()
+
+    def test_separate_directories_get_separate_threads(self, tmp_path, monkeypatch):
+        a, b = tmp_path / 'a', tmp_path / 'b'
+        a.mkdir()
+        b.mkdir()
+        dirs = iter([str(a), str(b)])
+        monkeypatch.setattr(CacheManager, '_get_writable_cache_dir',
+                            lambda self: next(dirs))
+        first, second = CacheManager(), CacheManager()
+        try:
+            assert first.cache_dir != second.cache_dir
+            assert len(_live_cleanup_threads()) == 2
+        finally:
+            first.stop_cleanup_thread()
+            second.stop_cleanup_thread()
+
+    def test_no_thread_leaks_across_many_constructions(self, manager):
+        before = len(_live_cleanup_threads())
+        made = [manager() for _ in range(12)]
+        try:
+            assert len(_live_cleanup_threads()) == before + 1
+        finally:
+            for m in made:
+                m.stop_cleanup_thread()
+        assert len(_live_cleanup_threads()) == before
+
+
+class TestValidatorDoesNotBuildItsOwn:
+    def test_it_uses_the_cache_manager_it_is_given(self, manager):
+        from src.startup_validator import StartupValidator
+
+        shared = manager()
+        try:
+            before = len(_live_cleanup_threads())
+            v = StartupValidator(config_manager=object(), cache_manager=shared)
+            v._validate_cache_directory()
+            assert len(_live_cleanup_threads()) == before, (
+                "validation started another cleanup thread")
+        finally:
+            shared.stop_cleanup_thread()
+
+    def test_without_one_it_cleans_up_after_itself(self, manager):
+        from src.startup_validator import StartupValidator
+
+        before = len(_live_cleanup_threads())
+        v = StartupValidator(config_manager=object())
+        v._validate_cache_directory()
+        assert len(_live_cleanup_threads()) == before, (
+            "the fallback manager left its cleanup thread running")

test/test_cache_orphan_temp_sweep.py

@@ -0,0 +1,188 @@
+"""Tests that abandoned cache temp files get collected.
+
+DiskCache.set() writes through tempfile.mkstemp and os.replace, removing its
+own temp file in a finally. That covers a failed write, but not a process that
+dies between the two -- a SIGKILL, a lost restart race, a power cut, all
+ordinary on a Pi. Nothing collected what was left behind: the temp names are
+".<key>.json.<random>", and the expiry sweep only listed names ending in
+.json, so they accumulated for as long as the card had been in service.
+
+Measured on a live rig before this fix: 76 orphans totalling 1,050 MB -- 81%
+of the entire cache directory -- the oldest six months old.
+
+The predicate that decides what to delete is tested harder than the sweep
+itself, because a false positive here destroys real data.
+"""
+
+import os
+import time
+
+import pytest
+
+from src.cache.disk_cache import DiskCache, _ORPHAN_TEMP_MAX_AGE_SECONDS
+
+
+class FakeStrategy:
+    @staticmethod
+    def get_data_type_from_key(key):
+        return 'default'
+
+
+POLICIES = {'default': 30}
+
+
+@pytest.fixture
+def cache(tmp_path):
+    return DiskCache(str(tmp_path))
+
+
+def _age(path, seconds):
+    old = time.time() - seconds
+    os.utime(path, (old, old))
+
+
+def _write(tmp_path, name, body='{}'):
+    p = tmp_path / name
+    p.write_text(body, encoding='utf-8')
+    return p
+
+
+class TestWhatCountsAsAnOrphan:
+    @pytest.mark.parametrize('name', [
+        '.weather.json.a1b2c3d4',
+        '.odds_espn_football_nfl_401.json.xyz00000',
+        '.a.json.b',
+    ])
+    def test_our_temp_files_are_orphans(self, name):
+        assert DiskCache._is_orphaned_temp(name)
+
+    @pytest.mark.parametrize('name', [
+        'weather.json',            # real data
+        '.weather.json',           # a dotted key that completed
+        '.gitignore',              # not ours
+        '.hidden',                 # not ours
+        'weather.json.bak',        # no leading dot: someone else's
+        '.json.abc',               # no key between the dot and .json.
+        '.weather.json.',          # no random component
+        'notes.txt',
+    ])
+    def test_everything_else_is_left_alone(self, name):
+        assert not DiskCache._is_orphaned_temp(name)
+
+    def test_the_names_set_actually_creates_are_matched(self, cache, tmp_path):
+        """Guard against the predicate and the writer drifting apart."""
+        created = []
+        real = os.replace
+
+        def capture(src, dst):
+            created.append(os.path.basename(src))
+            return real(src, dst)
+
+        import src.cache.disk_cache as mod
+        mod.os.replace = capture
+        try:
+            cache.set('weather', {'v': 1})
+        finally:
+            mod.os.replace = real
+
+        assert created, "set() did not go through the temp-file path"
+        assert all(DiskCache._is_orphaned_temp(n) for n in created), created
+
+
+class TestTheSweep:
+    def test_an_old_orphan_is_removed(self, cache, tmp_path):
+        p = _write(tmp_path, '.weather.json.a1b2c3d4', 'x' * 5000)
+        _age(p, _ORPHAN_TEMP_MAX_AGE_SECONDS + 60)
+
+        stats = cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+
+        assert not p.exists()
+        assert stats['orphan_temp_files_deleted'] == 1
+        assert stats['space_freed_bytes'] >= 5000
+
+    def test_an_in_flight_write_is_not_snatched_away(self, cache, tmp_path):
+        # The whole risk of this sweep: deleting a temp file another thread is
+        # about to os.replace into place.
+        p = _write(tmp_path, '.weather.json.inflight')
+
+        cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+
+        assert p.exists()
+
+    def test_real_cache_files_survive(self, cache, tmp_path):
+        fresh = _write(tmp_path, 'weather.json')
+        dotted = _write(tmp_path, '.weather.json')
+        _age(dotted, _ORPHAN_TEMP_MAX_AGE_SECONDS + 60)
+
+        cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+
+        assert fresh.exists()
+        assert dotted.exists(), "a completed .json was treated as a temp file"
+
+    def test_unrelated_dotfiles_survive(self, cache, tmp_path):
+        keep = _write(tmp_path, '.gitignore')
+        _age(keep, 400 * 86400)
+
+        cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+
+        assert keep.exists()
+
+    def test_expiry_still_works_alongside_it(self, cache, tmp_path):
+        stale = _write(tmp_path, 'old.json')
+        _age(stale, 40 * 86400)          # past the 30-day default
+        orphan = _write(tmp_path, '.old.json.zz999999')
+        _age(orphan, _ORPHAN_TEMP_MAX_AGE_SECONDS + 60)
+
+        stats = cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+
+        assert not stale.exists()
+        assert not orphan.exists()
+        assert stats['files_deleted'] == 2
+        assert stats['orphan_temp_files_deleted'] == 1
+
+    def test_the_rig_scenario(self, cache, tmp_path):
+        """76 orphans of assorted ages, none of them reachable before."""
+        for i in range(76):
+            p = _write(tmp_path, '.sched_%d.json.r%06d' % (i, i), 'x' * 1000)
+            _age(p, (i + 2) * 86400)
+        keep = _write(tmp_path, 'sched.json')
+
+        stats = cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+
+        assert stats['orphan_temp_files_deleted'] == 76
+        assert keep.exists()
+        assert not list(tmp_path.glob('.sched_*'))
+        # The summary line is "<deleted>/<scanned>", so an orphan that is
+        # deleted but never counted as scanned renders as "76/1".
+        assert stats['files_scanned'] == 77
+        assert stats['files_deleted'] <= stats['files_scanned']
+
+    def test_deleted_never_exceeds_scanned(self, cache, tmp_path):
+        p = _write(tmp_path, '.only.json.a1b2c3d4')
+        _age(p, _ORPHAN_TEMP_MAX_AGE_SECONDS + 60)
+
+        stats = cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+
+        assert stats['files_deleted'] == 1
+        assert stats['files_scanned'] == 1
+
+    def test_a_missing_file_mid_sweep_is_not_an_error(self, cache, tmp_path):
+        p = _write(tmp_path, '.weather.json.a1b2c3d4')
+        _age(p, _ORPHAN_TEMP_MAX_AGE_SECONDS + 60)
+
+        import src.cache.disk_cache as mod
+        real = mod.os.path.getsize
+
+        def vanish(path):
+            if path.endswith('.a1b2c3d4'):
+                os.remove(path)
+                raise FileNotFoundError(path)
+            return real(path)
+
+        mod.os.path.getsize = vanish
+        try:
+            stats = cache.cleanup_expired_files(FakeStrategy(), POLICIES)
+        finally:
+            mod.os.path.getsize = real
+
+        assert stats['errors'] == 0

test/test_display_manager.py

@@ -237,3 +237,45 @@ class TestDisplayManagerDoubleSided:
                                 suppress_test_pattern=True)
             assert dm.set_brightness(70) is True
             assert mock_rgb_matrix['matrix_instance'].brightness == 70
+
+
+class TestDisplayManagerOrientation:
+    """The orientation setting composes onto pixel_mapper_config for panels
+    mounted upside down, without disturbing a custom pixel_mapper_config."""
+
+    def _config(self, **hardware_overrides):
+        config = {
+            'display': {
+                'hardware': {
+                    'rows': 32, 'cols': 64, 'chain_length': 2, 'parallel': 1,
+                    'hardware_mapping': 'adafruit-hat-pwm', 'brightness': 90,
+                },
+                'runtime': {'gpio_slowdown': 2},
+            },
+            'timezone': 'UTC',
+            'plugin_system': {'plugins_directory': 'plugins'},
+        }
+        config['display']['hardware'].update(hardware_overrides)
+        return config
+
+    def test_default_orientation_leaves_pixel_mapper_config_untouched(self, mock_rgb_matrix):
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'false'}):
+            DisplayManager(self._config(), suppress_test_pattern=True)
+            options = mock_rgb_matrix['options_class'].return_value
+            assert options.pixel_mapper_config == ''
+
+    def test_orientation_180_appends_rotate_mapper(self, mock_rgb_matrix):
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'false'}):
+            DisplayManager(self._config(orientation='180'), suppress_test_pattern=True)
+            options = mock_rgb_matrix['options_class'].return_value
+            assert options.pixel_mapper_config == 'Rotate:180'
+
+    def test_orientation_180_composes_with_existing_pixel_mapper_config(self, mock_rgb_matrix):
+        DisplayManager._instance = None
+        with patch.dict('os.environ', {'EMULATOR': 'false'}):
+            DisplayManager(self._config(orientation='180', pixel_mapper_config='U-mapper'),
+                           suppress_test_pattern=True)
+            options = mock_rgb_matrix['options_class'].return_value
+            assert options.pixel_mapper_config == 'U-mapper;Rotate:180'

test/test_initial_update_budget.py

@@ -0,0 +1,224 @@
+"""Tests that startup does not wait indefinitely for plugins to fetch data.
+
+DisplayController.__init__ calls _update_modules() once, to populate plugin
+data before the first frame. It walks every loaded plugin in turn, and each
+update blocks the calling thread for up to the executor's 30s timeout, so the
+uncapped total is the sum of every slow plugin on the system.
+
+Profiled on a live rig with py-spy, the main thread sat 9.34s in
+
+    display_controller._update_modules
+      -> plugin_executor.execute_update
+        -> execute_with_timeout -> threading.join
+
+and the controller's own log put the full pass at 82 seconds on the worst
+boot measured (55 and 26 on the two before). The panel shows nothing for all
+of it.
+
+Nothing is lost by stopping early: a plugin that has never updated is
+immediately due, so run_scheduled_updates() collects it seconds later with the
+display already running.
+"""
+
+import os
+import time
+from unittest.mock import Mock
+
+import pytest
+
+# display_controller imports display_manager, which binds the hardware
+# rgbmatrix module unless EMULATOR=true is set before import (same convention
+# as test_display_controller_vegas_tick.py).
+os.environ.setdefault("EMULATOR", "true")
+
+from src.display_controller import (  # noqa: E402
+    DisplayController, _INITIAL_UPDATE_BUDGET_SECONDS,
+    _MIN_INITIAL_UPDATE_TIMEOUT_SECONDS)
+
+
+class FakeExecutor:
+    """Records which plugins were updated, and can make some of them slow."""
+
+    def __init__(self, cost=0.0, slow=()):
+        self.updated = []
+        self.cost = cost
+        self.slow = set(slow)
+
+    def execute_update(self, plugin, plugin_id, timeout=None):
+        self.updated.append(plugin_id)
+        if plugin_id in self.slow:
+            time.sleep(self.cost)
+        return True
+
+
+@pytest.fixture
+def tiny_floor(monkeypatch):
+    """Shrink the "worth starting" floor so timing tests stay quick."""
+    import src.display_controller as mod
+    monkeypatch.setattr(mod, "_MIN_INITIAL_UPDATE_TIMEOUT_SECONDS", 0.01)
+
+
+def _controller(plugin_ids, executor):
+    c = DisplayController.__new__(DisplayController)
+    c.plugin_manager = Mock()
+    # Both attributes, because _update_modules reads
+    # `loaded_plugins or plugins` and an empty dict is falsy.
+    c.plugin_manager.loaded_plugins = {pid: Mock() for pid in plugin_ids}
+    c.plugin_manager.plugins = dict(c.plugin_manager.loaded_plugins)
+    c.plugin_manager.plugin_executor = executor
+    c.plugin_manager.plugin_last_update = {}
+    c.plugin_manager.health_tracker = None
+    return c
+
+
+class TestTheBudgetIsRespected:
+    def test_without_a_deadline_every_plugin_is_updated(self):
+        ex = FakeExecutor()
+        _controller(['a', 'b', 'c'], ex)._update_modules()
+        assert ex.updated == ['a', 'b', 'c']
+
+    def test_a_passed_deadline_stops_the_pass(self):
+        ex = FakeExecutor()
+        _controller(['a', 'b', 'c'], ex)._update_modules(deadline=time.time() - 1)
+        assert ex.updated == [], "updated %r after the deadline" % ex.updated
+
+    def test_slow_plugins_do_not_drag_in_the_rest(self, tiny_floor):
+        # One plugin burns the whole budget; the remainder must be left alone
+        # rather than each adding its own wait.
+        ex = FakeExecutor(cost=0.3, slow={'slow'})
+        c = _controller(['slow'] + ['p%d' % i for i in range(20)], ex)
+        started = time.time()
+        c._update_modules(deadline=started + 0.2)
+        elapsed = time.time() - started
+
+        assert ex.updated == ['slow'], "updated %r" % ex.updated
+        # Bounded by the one in-flight update, not by twenty more.
+        assert elapsed < 1.0, "%.2fs" % elapsed
+
+    def test_a_generous_deadline_still_gets_everything(self):
+        ex = FakeExecutor()
+        c = _controller(['a', 'b', 'c'], ex)
+        c._update_modules(deadline=time.time() + 30)
+        assert ex.updated == ['a', 'b', 'c']
+
+    def test_the_deadline_is_checked_before_each_plugin(self, tiny_floor):
+        # Not just once up front: the budget can be spent partway through.
+        ex = FakeExecutor(cost=0.15, slow={'a', 'b', 'c', 'd'})
+        c = _controller(['a', 'b', 'c', 'd'], ex)
+        c._update_modules(deadline=time.time() + 0.2)
+        assert 0 < len(ex.updated) < 4, "updated %r" % ex.updated
+
+
+class TestThePassIsBoundedInPractice:
+    def test_the_last_plugin_cannot_overrun_the_budget(self):
+        # Checking the deadline before each plugin is not enough on its own:
+        # one that starts with a moment left could still block for the
+        # executor's full timeout. On the rig that turned a 20s budget into a
+        # 31.8s pass, so the remaining budget is passed down as the timeout.
+        seen = []
+
+        class Executor:
+            def execute_update(self, plugin, plugin_id, timeout=None):
+                seen.append(timeout)
+                return True
+
+        c = _controller(['a', 'b', 'c'], Executor())
+        deadline = time.time() + 5
+        c._update_modules(deadline=deadline)
+
+        assert seen and all(t is not None for t in seen), seen
+        assert all(t <= 5.01 for t in seen), seen
+        # The exact remainder, never clamped up: clamping would let the pass
+        # run past its deadline. Anything below the floor is deferred instead,
+        # so what does start always has a usable slot.
+        assert all(t >= _MIN_INITIAL_UPDATE_TIMEOUT_SECONDS for t in seen), seen
+
+    def test_without_a_deadline_the_executor_default_is_left_alone(self):
+        seen = []
+
+        class Executor:
+            def execute_update(self, plugin, plugin_id, timeout=None):
+                seen.append(timeout)
+                return True
+
+        _controller(['a'], Executor())._update_modules()
+        assert seen == [None], seen
+
+
+class TestTheBudgetItself:
+    def test_it_is_short_enough_to_be_worth_having(self):
+        # The measured uncapped worst case was 82s; a budget near that would
+        # not bound anything.
+        assert _INITIAL_UPDATE_BUDGET_SECONDS <= 30
+
+    def test_it_is_long_enough_for_a_quick_plugin_or_two(self):
+        assert _INITIAL_UPDATE_BUDGET_SECONDS >= 5
+
+
+class TestNothingIsSilentlyDropped:
+    def test_deferred_plugins_are_named_in_the_log(self, caplog):
+        ex = FakeExecutor()
+        c = _controller(['a', 'b'], ex)
+        with caplog.at_level('INFO'):
+            c._update_modules(deadline=time.time() - 1)
+        text = "\n".join(r.getMessage() for r in caplog.records)
+        assert 'a' in text and 'b' in text, text
+        assert 'budget' in text.lower(), text
+
+    def test_nothing_is_logged_when_all_of_them_ran(self, caplog):
+        ex = FakeExecutor()
+        c = _controller(['a'], ex)
+        with caplog.at_level('INFO'):
+            c._update_modules(deadline=time.time() + 30)
+        assert not any('budget' in r.getMessage().lower() for r in caplog.records)
+
+
+class TestItDoesNotBreakTheOrdinaryPaths:
+    def test_no_plugin_manager_is_harmless(self):
+        c = DisplayController.__new__(DisplayController)
+        c.plugin_manager = None
+        c._update_modules(deadline=time.time() - 1)      # must not raise
+
+    def test_an_empty_plugin_set_is_harmless(self):
+        ex = FakeExecutor()
+        _controller([], ex)._update_modules(deadline=time.time() + 5)
+        assert ex.updated == []
+
+
+class TestTooLittleBudgetDefersRatherThanClamps:
+    def test_a_plugin_starting_below_the_floor_is_deferred(self):
+        ex = FakeExecutor()
+        c = _controller(['a'], ex)
+        # Just under the floor: previously this was clamped up to the floor and
+        # run anyway, which pushed the pass past its deadline.
+        c._update_modules(
+            deadline=time.time() + _MIN_INITIAL_UPDATE_TIMEOUT_SECONDS - 0.05)
+        assert ex.updated == [], "started a plugin it could not give a slot to"
+
+    def test_a_plugin_starting_above_the_floor_still_runs(self):
+        ex = FakeExecutor()
+        c = _controller(['a'], ex)
+        c._update_modules(
+            deadline=time.time() + _MIN_INITIAL_UPDATE_TIMEOUT_SECONDS + 1)
+        assert ex.updated == ['a']
+
+    def test_the_timeout_is_the_remainder_not_the_floor(self):
+        seen = []
+
+        class Executor:
+            def execute_update(self, plugin, plugin_id, timeout=None):
+                seen.append(timeout)
+                return True
+
+        c = _controller(['a'], Executor())
+        c._update_modules(deadline=time.time() + 9)
+        assert seen and 8.5 <= seen[0] <= 9.01, seen
+
+    def test_the_pass_cannot_outlast_its_deadline(self, tiny_floor):
+        # Every plugin sleeps well past the budget; the deferral keeps the
+        # whole pass inside it rather than overrunning by a floor's worth.
+        ex = FakeExecutor(cost=0.4, slow={'a', 'b', 'c', 'd', 'e'})
+        c = _controller(['a', 'b', 'c', 'd', 'e'], ex)
+        started = time.time()
+        c._update_modules(deadline=started + 0.5)
+        assert time.time() - started < 1.2, "%.2fs" % (time.time() - started)

test/test_initializing_screen.py

@@ -0,0 +1,190 @@
+"""Tests the startup screen that shows while plugins fetch their first data.
+
+That screen is on the panel for the whole initial-update window, and on a
+headless Pi it is the only place the device's address appears without going
+looking for it -- so it now carries the address as well as "Initializing".
+
+Two things have to hold. It must fit every supported panel: the old fixed
+8px PressStart2P drew "Initializing" 96px wide at x=10, which ran off the
+side of a 64px panel before an address was ever added. And the lookup must be
+cheap, because this runs on the startup path that the rest of this change
+exists to shorten.
+"""
+
+import os
+import time
+
+from PIL import Image, ImageDraw, ImageFont
+import pytest
+
+os.environ.setdefault("EMULATOR", "true")
+
+from src.display_manager import DisplayManager  # noqa: E402
+
+SIZES = [(64, 32), (128, 32), (128, 64), (256, 32), (512, 64)]
+
+
+class FakeMatrix:
+    def __init__(self, width, height):
+        self.width, self.height = width, height
+
+
+def _manager(width, height):
+    dm = DisplayManager.__new__(DisplayManager)
+    dm.image = Image.new('RGB', (width, height))
+    dm.draw = ImageDraw.Draw(dm.image)
+    dm.matrix = FakeMatrix(width, height)
+    dm.font = ImageFont.truetype('assets/fonts/PressStart2P-Regular.ttf', 8)
+    return dm
+
+
+def _layout(dm, lines):
+    """The geometry _draw_startup_banner uses."""
+    font = dm._fitting_font(lines, dm.matrix.width - 2)
+    line_height = dm.draw.textbbox((0, 0), "Ag", font=font)[3] + 1
+    top = max(1, (dm.matrix.height - line_height * len(lines)) // 2)
+    widths = [dm.draw.textlength(t, font=font) for t in lines]
+    return font, widths, top, top + line_height * len(lines)
+
+
+def _render_over_pattern(width, height, lines):
+    """Draw the test pattern, then the banner over it, as startup does."""
+    dm = _manager(width, height)
+    dm.draw.rectangle([0, 0, width - 1, height - 1], outline=(255, 0, 0))
+    dm.draw.line([0, 0, width - 1, height - 1], fill=(0, 255, 0))
+    dm._draw_startup_banner(lines, width, height)
+    return dm
+
+
+class TestTheAddressLookup:
+    def test_it_never_reports_loopback(self):
+        # A loopback address on the panel would be actively misleading -- it is
+        # not something anyone can browse to.
+        ip = DisplayManager._local_ip()
+        assert ip is None or not ip.startswith("127."), ip
+
+    def test_it_looks_like_an_address_when_there_is_one(self):
+        ip = DisplayManager._local_ip()
+        if ip is None:
+            pytest.skip("host has no routable address")
+        parts = ip.split(".")
+        assert len(parts) == 4 and all(p.isdigit() for p in parts), ip
+
+    def test_it_is_cheap_enough_for_the_startup_path(self):
+        DisplayManager._local_ip()          # warm anything cacheable
+        started = time.perf_counter()
+        for _ in range(20):
+            DisplayManager._local_ip()
+        per_call = (time.perf_counter() - started) / 20
+        # `hostname -I` with its 2s timeout, which the web launcher uses, would
+        # be thousands of times this.
+        assert per_call < 0.05, "%.1f ms per call" % (per_call * 1000)
+
+    def test_it_returns_none_rather_than_raising(self, monkeypatch):
+        import src.display_manager as mod
+
+        def no_network(*a, **k):
+            raise OSError("network is unreachable")
+
+        monkeypatch.setattr(mod.socket, "socket", no_network)
+        assert DisplayManager._local_ip() is None
+
+
+class TestItFitsEveryPanel:
+    @pytest.mark.parametrize("width,height", SIZES)
+    def test_both_lines_fit_with_an_address(self, width, height):
+        dm = _manager(width, height)
+        _font, widths, top, bottom = _layout(dm, ["Initializing", "255.255.255.255"])
+        assert all(w <= width - 2 for w in widths), (width, widths)
+        assert bottom <= height and top >= 0, (top, bottom, height)
+
+    @pytest.mark.parametrize("width,height", SIZES)
+    def test_it_still_fits_with_no_address(self, width, height):
+        dm = _manager(width, height)
+        _font, widths, _top, bottom = _layout(dm, ["Initializing"])
+        assert all(w <= width - 2 for w in widths), (width, widths)
+        assert bottom <= height, (bottom, height)
+
+    def test_the_smallest_panel_drops_to_a_narrower_font(self):
+        # The regression this guards: PressStart2P at 8px is 96px wide for
+        # "Initializing", which does not fit 64px however it is positioned.
+        dm = _manager(64, 32)
+        font, widths, _t, _b = _layout(dm, ["Initializing", "10.0.20.104"])
+        assert font is not dm.font, "kept a font that cannot fit"
+        assert max(widths) <= 62, widths
+
+    def test_a_roomy_panel_keeps_the_larger_font(self):
+        dm = _manager(256, 32)
+        font, _w, _t, _b = _layout(dm, ["Initializing", "10.0.20.104"])
+        assert font is dm.font, "needlessly shrank on a panel with room"
+
+
+class TestPlacement:
+    @pytest.mark.parametrize("width,height", SIZES)
+    def test_the_lines_are_centred(self, width, height):
+        dm = _manager(width, height)
+        lines = ["Initializing", "10.0.20.104"]
+        _font, widths, _t, _b = _layout(dm, lines)
+        for w in widths:
+            left = max(0, (width - w) // 2)
+            assert abs((left + (left + w)) - width) <= 2, (left, w, width)
+
+    def test_the_address_sits_under_the_word(self):
+        dm = _manager(128, 64)
+        font, _w, top, bottom = _layout(dm, ["Initializing", "10.0.20.104"])
+        line_height = dm.draw.textbbox((0, 0), "Ag", font=font)[3] + 1
+        assert bottom - top == line_height * 2
+
+
+class TestItIsActuallyReadable:
+    """The point of the address is that someone can read it off the wall."""
+
+    @pytest.mark.parametrize("width,height", SIZES)
+    def test_the_diagonal_does_not_cross_the_text(self, width, height):
+        lines = ["Initializing", "10.0.20.104"]
+        dm = _render_over_pattern(width, height, lines)
+        _font, widths, top, bottom = _layout(dm, lines)
+        # textlength returns a float, so these must be floored before they
+        # can index pixels.
+        block_width = int(max(widths))
+        left = int(max(0, (width - block_width) // 2))
+
+        px = dm.image.load()
+        green = 0
+        for y in range(int(top), min(int(bottom), height)):
+            for x in range(left, min(left + block_width, width)):
+                r, g, b = px[x, y]
+                if g > 128 and r < 128 and b < 128:
+                    green += 1
+        assert green == 0, "%d green pixels behind the text at %dx%d" % (
+            green, width, height)
+
+    @pytest.mark.parametrize("width,height", SIZES)
+    def test_the_text_stays_pure_blue(self, width, height):
+        # Not a style choice. The pattern lights one channel per element --
+        # red border, green diagonal, blue text -- so a glance says whether
+        # led_rgb_sequence is right: wire it BGR and the border comes up blue
+        # and this text red. White text would light all three and destroy the
+        # only blue reference on the screen.
+        dm = _render_over_pattern(width, height, ["Initializing", "10.0.20.104"])
+        px = dm.image.load()
+        blue = sum(1 for y in range(height) for x in range(width)
+                   if px[x, y] == (0, 0, 255))
+        assert blue > 20, "only %d blue pixels at %dx%d" % (blue, width, height)
+        white = sum(1 for y in range(height) for x in range(width)
+                    if px[x, y] == (255, 255, 255))
+        assert white == 0, "%d white pixels would muddy the channel check" % white
+
+    def test_each_element_lights_one_channel(self):
+        # The whole point of the pattern: three pure primaries on screen.
+        dm = _render_over_pattern(128, 64, ["Initializing", "10.0.20.104"])
+        seen = set(dm.image.getdata())
+        assert (255, 0, 0) in seen, "no pure red border"
+        assert (0, 255, 0) in seen, "no pure green diagonal"
+        assert (0, 0, 255) in seen, "no pure blue text"
+
+    def test_nothing_is_drawn_for_no_lines(self):
+        dm = _manager(128, 64)
+        before = dm.image.tobytes()
+        dm._draw_startup_banner([], 128, 64)
+        assert dm.image.tobytes() == before

test/test_logo_helper.py

@@ -0,0 +1,315 @@
+"""
+Tests for src/common/logo_helper.py — logo loading, LRU caching, resizing,
+and download-with-fallback. Previously untested: nothing in test/ referenced
+this module at all.
+
+Real PIL images under tmp_path are used rather than mocked ones, since
+load_logo() does real Path.exists() and Image.open() calls; only the HTTP
+session and the permission helpers are patched.
+
+Regression coverage for two fixed bugs:
+- _download_logo wrote response.content to disk with no size cap and no
+  check that the bytes decoded as an image, so a hostile or broken URL
+  could leave arbitrary/oversized content cached in the assets directory.
+- get_cache_stats() divided by self.cache_size unguarded, raising
+  ZeroDivisionError for a helper constructed with cache_size=0.
+"""
+
+import logging
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+import requests
+from PIL import Image
+
+from src.common.logo_helper import MAX_LOGO_BYTES, LogoHelper
+
+
+@pytest.fixture(autouse=True)
+def _no_real_chmod(monkeypatch):
+    # Keep the permission helpers out of the way: their own env detection
+    # is not what these tests are about.
+    monkeypatch.setattr("src.common.logo_helper.ensure_directory_permissions", MagicMock())
+    monkeypatch.setattr("src.common.logo_helper.ensure_file_permissions", MagicMock())
+
+
+@pytest.fixture
+def helper():
+    return LogoHelper(display_width=64, display_height=32,
+                      logger=logging.getLogger("test.logo_helper"))
+
+
+def write_logo(path: Path, size=(20, 20), color=(255, 0, 0), fmt="PNG") -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    Image.new("RGB", size, color).save(path, format=fmt)
+    return path
+
+
+def fake_response(content: bytes):
+    response = MagicMock()
+    response.content = content
+    response.raise_for_status = MagicMock()
+    return response
+
+
+def png_bytes(size=(20, 20), color=(0, 128, 0)) -> bytes:
+    import io
+    buf = io.BytesIO()
+    Image.new("RGB", size, color).save(buf, format="PNG")
+    return buf.getvalue()
+
+
+class TestLoadLogo:
+    def test_loads_and_converts_to_rgba(self, helper, tmp_path):
+        path = write_logo(tmp_path / "PHI.png")
+        logo = helper.load_logo("PHI", path)
+        assert logo is not None
+        assert logo.mode == "RGBA"
+
+    def test_missing_file_returns_none(self, helper, tmp_path, caplog):
+        with caplog.at_level(logging.WARNING):
+            assert helper.load_logo("NOPE", tmp_path / "missing.png") is None
+        assert "Logo not found" in caplog.text
+
+    def test_second_load_is_served_from_cache(self, helper, tmp_path):
+        path = write_logo(tmp_path / "PHI.png")
+        first = helper.load_logo("PHI", path)
+        path.unlink()  # cache hit must not touch the filesystem
+        assert helper.load_logo("PHI", path) is first
+
+    def test_cache_key_includes_requested_size(self, helper, tmp_path):
+        # A panel-size change must not hand back a logo sized for the old
+        # dimensions, so the two sizes get separate cache entries.
+        path = write_logo(tmp_path / "PHI.png", size=(100, 100))
+        small = helper.load_logo("PHI", path, max_width=10, max_height=10)
+        large = helper.load_logo("PHI", path, max_width=50, max_height=50)
+        assert small is not large
+        assert small.size != large.size
+        assert len(helper._logo_cache) == 2
+
+    def test_default_size_is_one_and_a_half_display(self, helper, tmp_path):
+        path = write_logo(tmp_path / "PHI.png", size=(500, 500))
+        logo = helper.load_logo("PHI", path)
+        assert logo.width <= int(64 * 1.5)
+        assert logo.height <= int(32 * 1.5)
+
+    def test_smaller_image_is_not_upscaled(self, helper, tmp_path):
+        path = write_logo(tmp_path / "PHI.png", size=(8, 8))
+        assert helper.load_logo("PHI", path, max_width=64, max_height=64).size == (8, 8)
+
+    def test_larger_image_is_downscaled_preserving_aspect(self, helper, tmp_path):
+        path = write_logo(tmp_path / "PHI.png", size=(200, 100))
+        logo = helper.load_logo("PHI", path, max_width=50, max_height=50)
+        assert logo.width <= 50 and logo.height <= 50
+        assert logo.width == 50 and logo.height == 25  # 2:1 preserved
+
+    def test_string_path_accepted(self, helper, tmp_path):
+        path = write_logo(tmp_path / "PHI.png")
+        assert helper.load_logo("PHI", str(path)) is not None
+
+    def test_corrupt_file_returns_none(self, helper, tmp_path, caplog):
+        bad = tmp_path / "bad.png"
+        bad.write_bytes(b"not an image")
+        with caplog.at_level(logging.ERROR):
+            assert helper.load_logo("BAD", bad) is None
+        assert "Error loading logo" in caplog.text
+
+
+class TestCacheManagement:
+    def test_lru_evicts_oldest(self, tmp_path):
+        helper = LogoHelper(64, 32, cache_size=2, logger=MagicMock())
+        paths = [write_logo(tmp_path / f"T{i}.png") for i in range(3)]
+        for i, path in enumerate(paths):
+            helper.load_logo(f"T{i}", path)
+        assert len(helper._logo_cache) == 2
+        assert not any(k.startswith("T0_") for k in helper._logo_cache)
+
+    def test_cache_hit_refreshes_lru_position(self, tmp_path):
+        helper = LogoHelper(64, 32, cache_size=2, logger=MagicMock())
+        a, b, c = [write_logo(tmp_path / f"{n}.png") for n in ("A", "B", "C")]
+        helper.load_logo("A", a)
+        helper.load_logo("B", b)
+        helper.load_logo("A", a)   # A is now most-recently used
+        helper.load_logo("C", c)   # evicts B, not A
+        assert any(k.startswith("A_") for k in helper._logo_cache)
+        assert not any(k.startswith("B_") for k in helper._logo_cache)
+
+    def test_clear_cache_empties_both_structures(self, helper, tmp_path):
+        helper.load_logo("PHI", write_logo(tmp_path / "PHI.png"))
+        helper.clear_cache()
+        assert helper._logo_cache == {}
+        assert helper._cache_order == []
+
+    def test_cache_stats(self, tmp_path):
+        helper = LogoHelper(64, 32, cache_size=4, logger=MagicMock())
+        helper.load_logo("PHI", write_logo(tmp_path / "PHI.png"))
+        stats = helper.get_cache_stats()
+        assert stats["cached_logos"] == 1
+        assert stats["cache_size_limit"] == 4
+        assert stats["cache_usage_percent"] == 25
+
+    def test_zero_cache_size_does_not_divide_by_zero(self):
+        # Regression: this raised ZeroDivisionError.
+        stats = LogoHelper(64, 32, cache_size=0, logger=MagicMock()).get_cache_stats()
+        assert stats["cache_usage_percent"] == 0
+        assert stats["cache_size_limit"] == 0
+
+
+class TestLoadLogoWithDownload:
+    def test_existing_file_skips_download(self, helper, tmp_path):
+        path = write_logo(tmp_path / "PHI.png")
+        helper.session.get = MagicMock()
+        assert helper.load_logo_with_download("PHI", path, "http://x/logo.png") is not None
+        helper.session.get.assert_not_called()
+
+    def test_downloads_then_loads(self, helper, tmp_path):
+        path = tmp_path / "PHI.png"
+        helper.session.get = MagicMock(return_value=fake_response(png_bytes()))
+        logo = helper.load_logo_with_download("PHI", path, "http://x/logo.png")
+        assert logo is not None
+        assert path.exists()
+        helper.session.get.assert_called_once_with("http://x/logo.png", timeout=30)
+
+    def test_download_failure_falls_back_to_placeholder(self, helper, tmp_path):
+        helper.session.get = MagicMock(
+            side_effect=requests.RequestException("connection reset"))
+        logo = helper.load_logo_with_download(
+            "PHI", tmp_path / "PHI.png", "http://x/logo.png",
+            max_width=20, max_height=20)
+        assert logo is not None and logo.size == (20, 20)  # placeholder
+
+    def test_http_error_falls_back_to_placeholder(self, helper, tmp_path):
+        response = fake_response(b"")
+        response.raise_for_status.side_effect = requests.HTTPError("404")
+        helper.session.get = MagicMock(return_value=response)
+        logo = helper.load_logo_with_download(
+            "PHI", tmp_path / "PHI.png", "http://x/logo.png",
+            max_width=20, max_height=20)
+        assert logo is not None and logo.size == (20, 20)
+
+    def test_no_url_and_no_file_gives_placeholder(self, helper, tmp_path):
+        logo = helper.load_logo_with_download(
+            "PHI", tmp_path / "missing.png", None, max_width=16, max_height=16)
+        assert logo is not None and logo.size == (16, 16)
+
+
+class TestDownloadLogo:
+    def test_writes_file_and_sets_permissions(self, helper, tmp_path):
+        path = tmp_path / "assets" / "PHI.png"
+        # Directory creation is ensure_directory_permissions' job, and the
+        # autouse fixture stubs it out — so make the directory here.
+        path.parent.mkdir()
+        helper.session.get = MagicMock(return_value=fake_response(png_bytes()))
+        with patch("src.common.logo_helper.ensure_directory_permissions") as dirs, \
+             patch("src.common.logo_helper.ensure_file_permissions") as files:
+            helper._download_logo("http://x/logo.png", path)
+        assert path.exists()
+        dirs.assert_called_once()
+        files.assert_called_once()
+        assert dirs.call_args[0][0] == path.parent
+
+    def test_oversized_response_is_rejected_without_writing(self, helper, tmp_path):
+        # Regression: an unbounded response.content was written straight to
+        # disk, so a hostile URL chose how many bytes landed in assets/.
+        path = tmp_path / "huge.png"
+        helper.session.get = MagicMock(
+            return_value=fake_response(b"\x00" * (MAX_LOGO_BYTES + 1)))
+        with pytest.raises(ValueError, match="over the"):
+            helper._download_logo("http://x/huge.png", path)
+        assert not path.exists()
+
+    def test_non_image_response_is_deleted_and_raises(self, helper, tmp_path):
+        # Regression: undecodable bytes stayed on disk, so every later
+        # load_logo() call hit the corrupt file instead of re-downloading.
+        path = tmp_path / "bad.png"
+        helper.session.get = MagicMock(return_value=fake_response(b"<html>404</html>"))
+        with pytest.raises(Exception):
+            helper._download_logo("http://x/bad.png", path)
+        assert not path.exists()
+
+    def test_decompression_bomb_is_deleted_and_raises(self, helper, tmp_path, monkeypatch):
+        path = tmp_path / "bomb.png"
+        helper.session.get = MagicMock(return_value=fake_response(png_bytes()))
+
+        class Bomb:
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *a):
+                return False
+
+            def load(self):
+                raise Image.DecompressionBombError("too many pixels")
+
+        monkeypatch.setattr("src.common.logo_helper.Image.open", lambda *a, **kw: Bomb())
+        with pytest.raises(Image.DecompressionBombError):
+            helper._download_logo("http://x/bomb.png", path)
+        assert not path.exists()
+
+    def test_bad_download_surfaces_as_placeholder_not_crash(self, helper, tmp_path):
+        # The new guards raise, and load_logo_with_download's existing
+        # broad except turns that into the placeholder path.
+        helper.session.get = MagicMock(return_value=fake_response(b"garbage"))
+        logo = helper.load_logo_with_download(
+            "PHI", tmp_path / "PHI.png", "http://x/bad.png",
+            max_width=12, max_height=12)
+        assert logo is not None and logo.size == (12, 12)
+
+
+class TestLogoVariations:
+    def test_plain_abbreviation_returns_itself(self, helper):
+        assert helper.get_logo_variations("PHI") == ["PHI"]
+
+    def test_ampersand_expanded(self, helper):
+        assert "TAAND M" in helper.get_logo_variations("TA& M")
+
+    def test_and_contracted(self, helper):
+        assert "T&M" in helper.get_logo_variations("TANDM")
+
+    def test_special_case_appends_known_aliases(self, helper):
+        variations = helper.get_logo_variations("TA&M")
+        assert "TAMU" in variations and "TEXASAM" in variations
+        assert "TAANDM" in variations  # the generic & rule still applies
+
+
+class TestNormalizeAbbreviation:
+    def test_uppercases_and_strips(self, helper):
+        assert helper.normalize_abbreviation("  phi  ") == "PHI"
+
+    def test_ampersand_becomes_and(self, helper):
+        assert helper.normalize_abbreviation("TA&M") == "TAANDM"
+
+    def test_internal_spaces_removed(self, helper):
+        assert helper.normalize_abbreviation("New York") == "NEWYORK"
+
+    def test_deliberately_differs_from_logo_downloader(self, helper):
+        # Pinned, not a bug: LogoDownloader.normalize_abbreviation replaces
+        # filesystem-unsafe characters but keeps spaces, and plugins call
+        # that one. Changing either changes which logo filenames resolve on
+        # existing installs. Both docstrings say so explicitly.
+        from src.logo_downloader import LogoDownloader
+        assert helper.normalize_abbreviation("New York") == "NEWYORK"
+        assert LogoDownloader.normalize_abbreviation("New York") == "NEW YORK"
+
+
+class TestPlaceholderLogo:
+    def test_uses_requested_dimensions(self, helper):
+        assert helper._create_placeholder_logo("PHI", 30, 20).size == (30, 20)
+
+    def test_defaults_to_one_and_a_half_display(self, helper):
+        assert helper._create_placeholder_logo("PHI").size == (96, 48)
+
+    def test_is_rgba(self, helper):
+        assert helper._create_placeholder_logo("PHI", 10, 10).mode == "RGBA"
+
+    def test_invalid_dimensions_return_none(self, helper, caplog):
+        with caplog.at_level(logging.ERROR):
+            assert helper._create_placeholder_logo("PHI", -5, -5) is None
+        assert "Error creating placeholder" in caplog.text
+
+
+class TestSessionConfiguration:
+    def test_user_agent_and_accept_headers(self, helper):
+        assert helper.session.headers["User-Agent"] == "LEDMatrix-Common/1.0"
+        assert helper.session.headers["Accept"] == "image/*"

test/test_odds_request_budget.py

@@ -10,10 +10,15 @@ and the update carrying every game's score was killed:
 
 Invisible out of season -- preseason week 1 returns a single game -- and a
 Sunday slate is around sixteen.
+
+The request now goes through a session that identifies the caller, so the
+tests patch `manager.session.get` rather than the module's `requests.get`.
 """
 
 from unittest.mock import Mock
 
+import requests
+
 from src.base_odds_manager import BaseOddsManager
 
 PLUGIN_BUDGET = 30.0   # PluginExecutor(default_timeout=30.0)
@@ -25,43 +30,83 @@ def _manager(cache=None):
     return BaseOddsManager(cache_manager=cache, config_manager=None)
 
 
+def _timing_out(manager):
+    """Point the manager's session at a request that always times out."""
+    manager.session.get = Mock(side_effect=requests.exceptions.Timeout("x"))
+    return manager.session.get
+
+
+def _returning(manager, payload):
+    resp = Mock()
+    resp.json.return_value = payload
+    resp.raise_for_status.return_value = None
+    manager.session.get = Mock(return_value=resp)
+    return manager.session.get
+
+
 class TestRequestTimeout:
     def test_leaves_room_in_the_operation_budget(self):
         assert _manager().request_timeout < PLUGIN_BUDGET / 2
 
     def test_the_timeout_is_the_one_actually_used(self):
         m = _manager()
-        import src.base_odds_manager as mod
-        real = mod.requests.get
-        try:
-            mod.requests.get = Mock(side_effect=mod.requests.exceptions.Timeout("x"))
-            m.get_odds("football", "nfl", "401")
-            assert mod.requests.get.call_args.kwargs["timeout"] == m.request_timeout
-        finally:
-            mod.requests.get = real
+        get = _timing_out(m)
+        m.get_odds("football", "nfl", "401")
+        assert get.call_args.kwargs["timeout"] == m.request_timeout
+
+
+class TestIdentifiesItselfToEspn:
+    """ESPN 403s python-requests' default agent, and bare custom tokens.
+
+    What it accepts is a token carrying a URL that says who is calling. This
+    path used a bare requests.get and so sent the default -- the one thing
+    known to be rejected. Everything else in the tree that talks to ESPN
+    already sends the header below.
+    """
+
+    def test_the_user_agent_names_the_project_and_links_to_it(self):
+        ua = _manager().session.headers["User-Agent"]
+        assert "python-requests" not in ua
+        assert "LEDMatrix" in ua
+        assert "github.com/ChuckBuilds/LEDMatrix" in ua
+
+    def test_it_is_the_same_agent_the_rest_of_the_tree_sends(self):
+        # Compared against the live value rather than a copied literal, so the
+        # two cannot drift apart the next time ESPN moves the goalposts.
+        from src.common.api_helper import APIHelper
+        assert (_manager().session.headers["User-Agent"]
+                == APIHelper().session.headers["User-Agent"])
+
+    def test_the_header_reaches_the_request(self):
+        m = _manager()
+        get = _returning(m, {})
+        m._extract_espn_data = Mock(return_value=None)
+        m.get_odds("football", "nfl", "401")
+        # Sent via the session, so it applies without being passed per-call.
+        assert get.call_count == 1
+        assert "User-Agent" in m.session.headers
+
+    def test_no_retry_adapter_multiplies_the_timeout(self):
+        # api_helper mounts a retrying adapter; this path must not, or a 5s
+        # timeout becomes 15s and the budget fix is undone.
+        m = _manager()
+        for adapter in m.session.adapters.values():
+            retries = getattr(adapter, "max_retries", None)
+            assert getattr(retries, "total", 0) in (0, None), (
+                "odds session mounts a retrying adapter (total=%r); retries "
+                "multiply request_timeout" % getattr(retries, "total", None))
 
 
 class TestSlowEspnCannotKillTheUpdate:
     def test_one_failure_stops_the_rest_of_the_slate_hitting_the_network(self):
         m = _manager()
-        import src.base_odds_manager as mod
-        real = mod.requests.get
-        calls = {"n": 0}
+        get = _timing_out(m)
+        for i in range(16):          # a full slate, one game at a time
+            m.get_odds("football", "nfl", "4018730%02d" % i)
 
-        def timeout(*a, **k):
-            calls["n"] += 1
-            raise mod.requests.exceptions.Timeout("timed out")
-
-        try:
-            mod.requests.get = timeout
-            for i in range(16):          # a full slate, one game at a time
-                m.get_odds("football", "nfl", "4018730%02d" % i)
-        finally:
-            mod.requests.get = real
-
-        assert calls["n"] == 1, (
+        assert get.call_count == 1, (
             "%d games each paid the timeout; the breaker should have stopped "
-            "after the first" % calls["n"])
+            "after the first" % get.call_count)
 
     def test_worst_case_slate_stays_inside_the_budget(self):
         m = _manager()
@@ -70,53 +115,48 @@ class TestSlowEspnCannotKillTheUpdate:
     def test_recovery_is_automatic(self):
         m = _manager()
         import src.base_odds_manager as mod
-        real_get, real_monotonic = mod.requests.get, mod.time.monotonic
+        real_monotonic = mod.time.monotonic
         clock = {"t": 1000.0}
         try:
             mod.time.monotonic = lambda: clock["t"]
-            mod.requests.get = Mock(
-                side_effect=mod.requests.exceptions.Timeout("timed out"))
+            get = _timing_out(m)
             m.get_odds("football", "nfl", "401")
             assert m._skip_network_until > clock["t"], "breaker did not open"
 
             clock["t"] += 1
-            before = mod.requests.get.call_count
+            before = get.call_count
             m.get_odds("football", "nfl", "402")
-            assert mod.requests.get.call_count == before, "should not have retried"
+            assert get.call_count == before, "should not have retried"
 
             clock["t"] += m._FAILURE_COOLDOWN
             m.get_odds("football", "nfl", "403")
-            assert mod.requests.get.call_count > before, "never retried"
+            assert get.call_count > before, "never retried"
         finally:
-            mod.requests.get, mod.time.monotonic = real_get, real_monotonic
+            mod.time.monotonic = real_monotonic
 
     def test_a_healthy_fetch_clears_the_breaker(self):
         m = _manager()
         m._skip_network_until = 0.0
         m._extract_espn_data = Mock(return_value=None)
-        import src.base_odds_manager as mod
-        real = mod.requests.get
-        try:
-            resp = Mock()
-            resp.json.return_value = {}
-            resp.raise_for_status.return_value = None
-            mod.requests.get = Mock(return_value=resp)
-            m.get_odds("football", "nfl", "401")
-        finally:
-            mod.requests.get = real
+        _returning(m, {})
+        m.get_odds("football", "nfl", "401")
         assert m._skip_network_until == 0.0
 
+    def test_a_403_opens_the_breaker_rather_than_hammering(self):
+        # raise_for_status raises HTTPError, a RequestException -- so a wrong
+        # or missing agent backs off instead of 403ing once per game.
+        m = _manager()
+        resp = Mock()
+        resp.raise_for_status.side_effect = requests.exceptions.HTTPError("403")
+        m.session.get = Mock(return_value=resp)
+        m.get_odds("football", "nfl", "401")
+        assert m._skip_network_until > 0.0
+
     def test_the_stale_cache_fallback_still_works(self):
         # The failing request must still hand back whatever was cached; only
         # the *subsequent* games skip the network.
         cache = Mock()
         cache.get_with_auto_strategy.side_effect = [None, {"details": "stale"}]
         m = BaseOddsManager(cache_manager=cache, config_manager=None)
-        import src.base_odds_manager as mod
-        real = mod.requests.get
-        try:
-            mod.requests.get = Mock(
-                side_effect=mod.requests.exceptions.Timeout("timed out"))
-            assert m.get_odds("football", "nfl", "401") == {"details": "stale"}
-        finally:
-            mod.requests.get = real
+        _timing_out(m)
+        assert m.get_odds("football", "nfl", "401") == {"details": "stale"}

test/test_sync_manager.py

@@ -0,0 +1,829 @@
+"""
+Tests for src/common/sync_manager.py — the UDP leader/follower protocol
+that synchronizes scrolling content across two LED matrix displays.
+
+This module had zero coverage: it only ever appeared in the suite as a
+MagicMock() stand-in (test_vegas_continuous_refresh.py,
+test_display_controller_vegas_tick.py), so none of its real framing,
+handshake, or socket logic was exercised.
+
+Most tests build the manager via object.__new__() + manual attribute
+assignment (the test_display_controller_vegas_tick.py bare-stub pattern)
+so no real sockets open and no background threads start. Receive loops are
+driven synchronously by once_then_stop(): the mocked socket call returns
+one crafted packet, then flips _running False and raises socket.timeout,
+so `while self._running:` exits after exactly one real iteration.
+
+Regression coverage for three fixed bugs:
+- Both recv loops' generic `except Exception` retried with no delay, so a
+  socket stuck raising a non-timeout error spun the thread at 100% CPU.
+- _follower_recv_loop dispatched on `data[:8] == _RAW_MAGIC or
+  len(data) > 512`, which routed any control message over 512 bytes into
+  the image decoder (dropping it) and any raw frame under 512 bytes into
+  the JSON parser.
+- _oversized_frame_warned was read via getattr(self, ..., False) instead of
+  being initialized in __init__.
+"""
+
+import io
+import json
+import socket
+import threading
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import numpy as np
+import pytest
+from PIL import Image
+
+from src.common import sync_manager
+from src.common.sync_manager import (
+    DisplaySyncManager,
+    FollowerState,
+    LeaderState,
+    SyncRole,
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolated_status_file(tmp_path, monkeypatch):
+    # STATUS_FILE is a module-level fixed path under tempfile.gettempdir() —
+    # genuinely shared state between tests and even between processes.
+    monkeypatch.setattr(
+        sync_manager, "STATUS_FILE", str(tmp_path / "led_matrix_sync_status.json"))
+
+
+def make_manager(role=SyncRole.STANDALONE, hw_config=None):
+    """Bare stub bypassing __init__'s socket/thread setup."""
+    mgr = object.__new__(DisplaySyncManager)
+    mgr.role = role
+    mgr.logger = MagicMock()
+    mgr.port = sync_manager.SYNC_PORT
+    mgr._hw_config = hw_config or {"rows": 32, "cols": 64, "chain_length": 1}
+
+    mgr._leader_state = LeaderState.NO_PEER
+    mgr._peer_ip = None
+    mgr._peer_compatible = False
+    mgr._peer_chain = 0
+    mgr._last_heartbeat_time = 0.0
+    mgr._leader_width = 0
+    mgr._oversized_frame_warned = False
+
+    mgr._follower_state = FollowerState.STANDALONE
+    mgr._latest_frame = None
+    mgr._latest_scroll_x = None
+    mgr._last_leader_frame_time = 0.0
+    mgr._frame_lock = threading.Lock()
+    mgr._leader_ip = None
+    mgr._on_new_cycle = None
+    mgr._on_scroll_image = None
+    mgr._pending_scroll_image = None
+    mgr._scroll_image_lock = threading.Lock()
+    mgr._img_server_sock = None
+
+    mgr._on_follower_connected = None
+    mgr._error_message = None
+    mgr._running = False
+    mgr._recv_sock = None
+    mgr._send_sock = None
+    return mgr
+
+
+def once_then_stop(mgr, value):
+    """side_effect returning `value` once, then stopping the enclosing loop."""
+    state = {"served": False}
+
+    def _side_effect(*args, **kwargs):
+        if not state["served"]:
+            state["served"] = True
+            return value
+        mgr._running = False
+        raise socket.timeout()
+
+    return _side_effect
+
+
+def raise_n_then_stop(mgr, exc, count):
+    """side_effect raising `exc` `count` times, then stopping the loop."""
+    state = {"n": 0}
+
+    def _side_effect(*args, **kwargs):
+        state["n"] += 1
+        if state["n"] <= count:
+            raise exc
+        mgr._running = False
+        raise socket.timeout()
+
+    return _side_effect
+
+
+def run_watchdog_once(monkeypatch, mgr, watchdog, now):
+    """Run exactly one watchdog iteration at a frozen wall-clock time."""
+    monkeypatch.setattr(sync_manager.time, "time", lambda: now)
+    monkeypatch.setattr(
+        sync_manager.time, "sleep", lambda _: setattr(mgr, "_running", False))
+    mgr._running = True
+    watchdog()
+
+
+class FakeConn:
+    """Minimal TCP connection stand-in whose recv() drains a byte buffer."""
+
+    def __init__(self, payload: bytes):
+        self._buf = payload
+        self.closed = False
+
+    def settimeout(self, _):
+        pass
+
+    def recv(self, n):
+        chunk, self._buf = self._buf[:n], self._buf[n:]
+        return chunk
+
+    def close(self):
+        self.closed = True
+
+
+def png_bytes(size=(10, 10), color=(1, 2, 3)) -> bytes:
+    buf = io.BytesIO()
+    Image.new("RGB", size, color).save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def raw_frame_packet(width, height, color=(10, 20, 30)) -> bytes:
+    arr = np.asarray(Image.new("RGB", (width, height), color), dtype=np.uint8)
+    return _magic_header(width, height) + arr.tobytes()
+
+
+def _magic_header(width, height) -> bytes:
+    return sync_manager._RAW_MAGIC + sync_manager._RAW_HEADER.pack(width, height)
+
+
+def length_prefixed(payload: bytes) -> bytes:
+    return len(payload).to_bytes(4, "big") + payload
+
+
+class TestRoleParsing:
+    def test_leader_role(self, monkeypatch):
+        monkeypatch.setattr(DisplaySyncManager, "_start_leader", lambda self: None)
+        assert DisplaySyncManager("leader", {}, {}, MagicMock()).role is SyncRole.LEADER
+
+    def test_follower_role(self, monkeypatch):
+        monkeypatch.setattr(DisplaySyncManager, "_start_follower", lambda self: None)
+        assert DisplaySyncManager("follower", {}, {}, MagicMock()).role is SyncRole.FOLLOWER
+
+    def test_standalone_starts_nothing(self):
+        mgr = DisplaySyncManager("standalone", {}, {}, MagicMock())
+        assert mgr.role is SyncRole.STANDALONE
+        assert mgr._running is False
+        assert mgr._recv_sock is None
+
+    def test_invalid_role_warns_and_falls_back(self):
+        logger = MagicMock()
+        assert DisplaySyncManager("bogus", {}, {}, logger).role is SyncRole.STANDALONE
+        assert logger.warning.called
+
+    def test_role_matching_is_case_sensitive(self):
+        # Pinned: SyncRole's values are lowercase, so "LEADER" is not
+        # normalized — it is simply invalid and falls back to standalone.
+        logger = MagicMock()
+        assert DisplaySyncManager("LEADER", {}, {}, logger).role is SyncRole.STANDALONE
+        assert logger.warning.called
+
+    def test_port_defaults_to_module_constant(self):
+        assert DisplaySyncManager("standalone", {}, {}, MagicMock()).port == sync_manager.SYNC_PORT
+
+    def test_port_read_from_config(self):
+        assert DisplaySyncManager("standalone", {"port": 9999}, {}, MagicMock()).port == 9999
+
+    def test_oversized_frame_warned_initialized_in_init(self, monkeypatch):
+        # Regression: this attribute was only ever created on first use via
+        # getattr(self, '_oversized_frame_warned', False).
+        monkeypatch.setattr(DisplaySyncManager, "_start_leader", lambda self: None)
+        mgr = DisplaySyncManager("leader", {}, {}, MagicMock())
+        assert mgr._oversized_frame_warned is False
+
+
+class TestHandleHello:
+    def test_matching_panels_connect(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._send_sock = MagicMock()
+        mgr._handle_hello({"t": "hello", "rows": 32, "cols": 64, "chain": 3}, "10.0.0.5")
+        assert mgr._leader_state is LeaderState.CONNECTED
+        assert mgr._peer_ip == "10.0.0.5"
+        assert mgr._peer_compatible is True
+        assert mgr._peer_chain == 3
+        assert mgr._error_message is None
+
+    def test_ack_reports_compatibility(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._send_sock = MagicMock()
+        mgr._leader_width = 128
+        mgr._handle_hello({"t": "hello", "rows": 32, "cols": 64, "chain": 1}, "10.0.0.5")
+        payload, dest = mgr._send_sock.sendto.call_args[0]
+        ack = json.loads(payload.decode("utf-8"))
+        assert ack["compatible"] is True
+        assert ack["leader_width"] == 128
+        assert dest == ("10.0.0.5", mgr.port)
+
+    def test_mismatched_panels_are_incompatible(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._send_sock = MagicMock()
+        mgr._handle_hello({"t": "hello", "rows": 16, "cols": 32, "chain": 1}, "10.0.0.5")
+        assert mgr._leader_state is LeaderState.INCOMPATIBLE
+        assert "Incompatible panels" in mgr._error_message
+        ack = json.loads(mgr._send_sock.sendto.call_args[0][0].decode("utf-8"))
+        assert ack["compatible"] is False
+        assert ack["error"] == mgr._error_message
+
+    def test_chain_length_may_differ(self):
+        # Documented rule: rows/cols must match, chain_length need not.
+        mgr = make_manager(role=SyncRole.LEADER, hw_config={"rows": 32, "cols": 64, "chain_length": 1})
+        mgr._send_sock = MagicMock()
+        mgr._handle_hello({"t": "hello", "rows": 32, "cols": 64, "chain": 4}, "10.0.0.5")
+        assert mgr._leader_state is LeaderState.CONNECTED
+
+    def test_connect_callback_fires_only_on_first_transition(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._send_sock = MagicMock()
+        fired = threading.Event()
+        calls = []
+        mgr._on_follower_connected = lambda: (calls.append(1), fired.set())
+
+        hello = {"t": "hello", "rows": 32, "cols": 64, "chain": 1}
+        mgr._handle_hello(hello, "10.0.0.5")
+        assert fired.wait(timeout=1)
+        assert len(calls) == 1
+
+        fired.clear()
+        mgr._handle_hello(hello, "10.0.0.5")  # already CONNECTED
+        assert not fired.wait(timeout=0.2)
+        assert len(calls) == 1
+
+    def test_ack_send_failure_is_swallowed(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._send_sock = MagicMock()
+        mgr._send_sock.sendto.side_effect = OSError("network unreachable")
+        mgr._handle_hello({"t": "hello", "rows": 32, "cols": 64, "chain": 1}, "10.0.0.5")
+        assert mgr._leader_state is LeaderState.CONNECTED  # state still updated
+        assert mgr.logger.debug.called
+
+
+class TestWatchdogs:
+    def test_leader_drops_peer_after_heartbeat_timeout(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        mgr._peer_ip = "10.0.0.1"
+        mgr._peer_compatible = True
+        mgr._last_heartbeat_time = 0.0
+        run_watchdog_once(monkeypatch, mgr, mgr._leader_watchdog,
+                          now=sync_manager.PEER_TIMEOUT + 1)
+        assert mgr._leader_state is LeaderState.NO_PEER
+        assert mgr._peer_ip is None
+        assert mgr._peer_compatible is False
+
+    def test_leader_keeps_peer_within_timeout(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        mgr._peer_ip = "10.0.0.1"
+        mgr._last_heartbeat_time = 100.0
+        run_watchdog_once(monkeypatch, mgr, mgr._leader_watchdog, now=101.0)
+        assert mgr._leader_state is LeaderState.CONNECTED
+        assert mgr._peer_ip == "10.0.0.1"
+
+    def test_leader_watchdog_ignores_disconnected_state(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.INCOMPATIBLE
+        mgr._last_heartbeat_time = 0.0
+        run_watchdog_once(monkeypatch, mgr, mgr._leader_watchdog, now=10_000)
+        assert mgr._leader_state is LeaderState.INCOMPATIBLE
+
+    def test_follower_returns_to_standalone_after_frame_timeout(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._follower_state = FollowerState.FOLLOWER
+        mgr._last_leader_frame_time = 0.0
+        mgr._latest_frame = Image.new("RGB", (2, 2))
+        run_watchdog_once(monkeypatch, mgr, mgr._follower_watchdog,
+                          now=sync_manager.LEADER_TIMEOUT + 1)
+        assert mgr._follower_state is FollowerState.STANDALONE
+        assert mgr.get_latest_frame() is None
+
+    def test_follower_keeps_frames_within_timeout(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._follower_state = FollowerState.FOLLOWER
+        mgr._last_leader_frame_time = 100.0
+        mgr._latest_frame = Image.new("RGB", (2, 2))
+        run_watchdog_once(monkeypatch, mgr, mgr._follower_watchdog, now=101.0)
+        assert mgr._follower_state is FollowerState.FOLLOWER
+        assert mgr.get_latest_frame() is not None
+
+
+class TestLeaderRecvLoop:
+    def _drive(self, mgr, payload, sender="10.0.0.8"):
+        mgr._recv_sock = MagicMock()
+        mgr._recv_sock.recvfrom.side_effect = once_then_stop(mgr, (payload, (sender, 1)))
+        mgr._running = True
+        mgr._leader_recv_loop()
+
+    def test_hello_is_dispatched(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._send_sock = MagicMock()
+        self._drive(mgr, json.dumps(
+            {"t": "hello", "rows": 32, "cols": 64, "chain": 1}).encode())
+        assert mgr._leader_state is LeaderState.CONNECTED
+        assert mgr._peer_ip == "10.0.0.8"
+
+    def test_heartbeat_from_known_peer_refreshes_timer(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._peer_ip = "10.0.0.8"
+        with patch.object(sync_manager.time, "time", return_value=12345.0):
+            self._drive(mgr, json.dumps({"t": "hb"}).encode())
+        assert mgr._last_heartbeat_time == 12345.0
+
+    def test_heartbeat_from_stranger_is_ignored(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._peer_ip = "10.0.0.8"
+        mgr._last_heartbeat_time = 5.0
+        self._drive(mgr, json.dumps({"t": "hb"}).encode(), sender="10.0.0.99")
+        assert mgr._last_heartbeat_time == 5.0
+
+    def test_unknown_message_type_ignored(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        self._drive(mgr, json.dumps({"t": "who-knows"}).encode())
+        assert mgr._leader_state is LeaderState.NO_PEER
+
+    def test_malformed_json_is_swallowed(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        self._drive(mgr, b"{not json")
+        assert mgr._leader_state is LeaderState.NO_PEER
+
+    def test_undecodable_bytes_are_swallowed(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        self._drive(mgr, b"\xff\xfe\x00bad")
+        assert mgr._leader_state is LeaderState.NO_PEER
+
+    def test_backs_off_between_repeated_errors(self, monkeypatch):
+        # Regression: without a sleep this loop spun at 100% CPU whenever
+        # the socket raised a non-timeout error on every call.
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._recv_sock = MagicMock()
+        mgr._recv_sock.recvfrom.side_effect = raise_n_then_stop(mgr, OSError("boom"), 3)
+        sleeps = MagicMock()
+        monkeypatch.setattr(sync_manager.time, "sleep", sleeps)
+        mgr._running = True
+        mgr._leader_recv_loop()
+        assert sleeps.call_count == 3
+        sleeps.assert_called_with(0.1)
+
+
+class TestFollowerRecvLoop:
+    def _drive(self, mgr, payload, sender="10.0.0.2"):
+        mgr._recv_sock = MagicMock()
+        mgr._recv_sock.recvfrom.side_effect = once_then_stop(mgr, (payload, (sender, 1)))
+        mgr._running = True
+        mgr._follower_recv_loop()
+
+    def test_small_raw_frame_is_decoded(self):
+        # Regression: a raw frame under the old 512-byte threshold was sent
+        # to the JSON parser and dropped.
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        packet = raw_frame_packet(4, 3)
+        assert len(packet) <= 512
+        self._drive(mgr, packet)
+        frame = mgr.get_latest_frame()
+        assert frame is not None and frame.size == (4, 3)
+        assert mgr._follower_state is FollowerState.FOLLOWER
+
+    def test_large_raw_frame_is_decoded(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        packet = raw_frame_packet(64, 32)
+        assert len(packet) > 512
+        self._drive(mgr, packet)
+        assert mgr.get_latest_frame().size == (64, 32)
+
+    def test_large_control_message_is_not_routed_to_image_decode(self):
+        # Regression: the old `len(data) > 512` branch treated any large
+        # control message as frame data and silently discarded it.
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        long_error = "x" * 600
+        payload = json.dumps(
+            {"t": "hello_ack", "compatible": False, "error": long_error}).encode()
+        assert len(payload) > 512
+        self._drive(mgr, payload, sender="10.0.0.9")
+        assert mgr._leader_ip == "10.0.0.9"
+        assert mgr._peer_compatible is False
+        assert mgr._error_message == long_error
+        assert mgr.get_latest_frame() is None
+        assert mgr.logger.error.called
+
+    def test_legacy_png_frame_without_magic_is_decoded(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        self._drive(mgr, png_bytes(size=(5, 5)))
+        frame = mgr.get_latest_frame()
+        assert frame is not None and frame.size == (5, 5)
+        assert mgr._follower_state is FollowerState.FOLLOWER
+
+    def test_truncated_raw_frame_is_swallowed(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        self._drive(mgr, _magic_header(64, 32) + b"\x00" * 10)  # far too short
+        assert mgr.get_latest_frame() is None
+        assert mgr.logger.debug.called
+
+    def test_garbage_payload_is_swallowed(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        self._drive(mgr, b"neither json nor a png, just bytes 1234567890")
+        assert mgr.get_latest_frame() is None
+
+    def test_hello_ack_updates_peer_state(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        self._drive(mgr, json.dumps(
+            {"t": "hello_ack", "compatible": True, "error": None}).encode(),
+            sender="10.0.0.6")
+        assert mgr._leader_ip == "10.0.0.6"
+        assert mgr._peer_compatible is True
+        assert mgr.logger.error.called is False
+
+    def test_scroll_x_switches_to_follower_and_builds_cycle(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        calls = []
+        mgr._on_new_cycle = lambda: calls.append(1)
+        self._drive(mgr, json.dumps({"t": "sx", "x": 12.34}).encode())
+        assert mgr._follower_state is FollowerState.FOLLOWER
+        assert mgr.get_latest_scroll_x() == 12.34
+        assert calls == [1]
+
+    def test_scroll_x_while_already_following_does_not_rebuild(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._follower_state = FollowerState.FOLLOWER
+        calls = []
+        mgr._on_new_cycle = lambda: calls.append(1)
+        self._drive(mgr, json.dumps({"t": "sx", "x": 5.0}).encode())
+        assert mgr.get_latest_scroll_x() == 5.0
+        assert calls == []
+
+    def test_new_cycle_message_triggers_callback(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._follower_state = FollowerState.FOLLOWER
+        calls = []
+        mgr._on_new_cycle = lambda: calls.append(1)
+        self._drive(mgr, json.dumps({"t": "nc"}).encode())
+        assert calls == [1]
+
+    def test_scroll_x_missing_key_is_swallowed(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        self._drive(mgr, json.dumps({"t": "sx"}).encode())  # no "x"
+        assert mgr.get_latest_scroll_x() is None
+
+    def test_backs_off_between_repeated_errors(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._recv_sock = MagicMock()
+        mgr._recv_sock.recvfrom.side_effect = raise_n_then_stop(mgr, OSError("boom"), 3)
+        sleeps = MagicMock()
+        monkeypatch.setattr(sync_manager.time, "sleep", sleeps)
+        mgr._running = True
+        mgr._follower_recv_loop()
+        assert sleeps.call_count == 3
+        sleeps.assert_called_with(0.1)
+
+
+class TestSendFrame:
+    def _connected_leader(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        mgr._peer_ip = "10.0.0.1"
+        mgr._send_sock = MagicMock()
+        return mgr
+
+    def test_frame_sent_with_magic_header(self):
+        mgr = self._connected_leader()
+        mgr.send_frame(Image.new("RGB", (8, 8)))
+        packet = mgr._send_sock.sendto.call_args[0][0]
+        assert packet[:8] == sync_manager._RAW_MAGIC
+        assert sync_manager._RAW_HEADER.unpack(packet[8:12]) == (8, 8)
+
+    def test_oversized_frame_warns_once_and_is_dropped(self):
+        mgr = self._connected_leader()
+        big = Image.new("RGB", (300, 300))  # 270000 bytes > 65000 UDP cap
+
+        mgr.send_frame(big)
+        assert mgr._oversized_frame_warned is True
+        assert mgr.logger.warning.call_count == 1
+        assert not mgr._send_sock.sendto.called
+
+        mgr.send_frame(big)
+        assert mgr.logger.warning.call_count == 1  # still warned only once
+
+    def test_not_sent_when_no_peer(self):
+        mgr = self._connected_leader()
+        mgr._leader_state = LeaderState.NO_PEER
+        mgr.send_frame(Image.new("RGB", (8, 8)))
+        assert not mgr._send_sock.sendto.called
+
+    def test_follower_never_sends(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._send_sock = MagicMock()
+        mgr.send_frame(Image.new("RGB", (8, 8)))
+        assert not mgr._send_sock.sendto.called
+
+    def test_send_error_is_swallowed(self):
+        mgr = self._connected_leader()
+        mgr._send_sock.sendto.side_effect = OSError("no route")
+        mgr.send_frame(Image.new("RGB", (8, 8)))  # must not raise
+        assert mgr.logger.debug.called
+
+
+class TestSendControlMessages:
+    def _connected_leader(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        mgr._peer_ip = "10.0.0.1"
+        mgr._send_sock = MagicMock()
+        return mgr
+
+    def test_send_scroll_x_rounds_to_two_places(self):
+        mgr = self._connected_leader()
+        mgr.send_scroll_x(3.14159)
+        msg = json.loads(mgr._send_sock.sendto.call_args[0][0].decode())
+        assert msg == {"t": "sx", "x": 3.14}
+
+    def test_send_new_cycle(self):
+        mgr = self._connected_leader()
+        mgr.send_new_cycle()
+        msg = json.loads(mgr._send_sock.sendto.call_args[0][0].decode())
+        assert msg == {"t": "nc"}
+
+    def test_control_messages_noop_when_disconnected(self):
+        mgr = self._connected_leader()
+        mgr._leader_state = LeaderState.NO_PEER
+        mgr.send_scroll_x(1.0)
+        mgr.send_new_cycle()
+        assert not mgr._send_sock.sendto.called
+
+    def test_set_leader_width(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr.set_leader_width(256)
+        assert mgr._leader_width == 256
+
+
+class TestImageServerLoop:
+    def _drive(self, mgr, conn):
+        mgr._img_server_sock = MagicMock()
+        mgr._img_server_sock.accept.side_effect = once_then_stop(
+            mgr, (conn, ("10.0.0.1", 1)))
+        mgr._running = True
+        mgr._image_server_loop()
+
+    def test_rejects_non_positive_length(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._on_scroll_image = MagicMock()
+        self._drive(mgr, FakeConn((0).to_bytes(4, "big")))
+        assert mgr.logger.warning.called
+        mgr._on_scroll_image.assert_not_called()
+
+    def test_rejects_oversized_length(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._on_scroll_image = MagicMock()
+        self._drive(mgr, FakeConn((11 * 1024 * 1024).to_bytes(4, "big")))
+        assert mgr.logger.warning.called
+        mgr._on_scroll_image.assert_not_called()
+
+    def test_rejects_oversized_dimensions(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._on_scroll_image = MagicMock()
+        self._drive(mgr, FakeConn(length_prefixed(png_bytes(size=(300, 300)))))
+        assert mgr.logger.warning.called
+        mgr._on_scroll_image.assert_not_called()
+
+    def test_rejects_decompression_bomb(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._on_scroll_image = MagicMock()
+
+        class BombImage:
+            width = height = 10
+
+            def load(self):
+                raise Image.DecompressionBombError("too many pixels")
+
+        monkeypatch.setattr(sync_manager.Image, "open", lambda *a, **kw: BombImage())
+        self._drive(mgr, FakeConn(length_prefixed(png_bytes())))
+        assert mgr.logger.warning.called
+        mgr._on_scroll_image.assert_not_called()
+
+    def test_valid_image_invokes_callback(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        received = []
+        mgr._on_scroll_image = received.append
+        self._drive(mgr, FakeConn(length_prefixed(png_bytes(size=(10, 10)))))
+        assert len(received) == 1
+        assert received[0].size == (10, 10)
+
+    def test_image_cached_when_callback_not_yet_registered(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._on_scroll_image = None
+        self._drive(mgr, FakeConn(length_prefixed(png_bytes(size=(6, 6)))))
+        assert mgr._pending_scroll_image is not None
+        assert mgr._pending_scroll_image.size == (6, 6)
+
+    def test_short_header_is_skipped(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._on_scroll_image = MagicMock()
+        self._drive(mgr, FakeConn(b"\x00\x01"))  # under the 4-byte prefix
+        mgr._on_scroll_image.assert_not_called()
+
+    def test_connection_always_closed(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        conn = FakeConn(length_prefixed(png_bytes()))
+        self._drive(mgr, conn)
+        assert conn.closed is True
+
+
+class TestScrollImageCallback:
+    def test_pending_image_delivered_on_late_registration(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        img = Image.new("RGB", (3, 3))
+        mgr._pending_scroll_image = img
+        received = []
+        mgr.set_on_scroll_image(received.append)
+        assert received == [img]
+        assert mgr._pending_scroll_image is None
+
+    def test_no_pending_image_means_no_immediate_call(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        received = []
+        mgr.set_on_scroll_image(received.append)
+        assert received == []
+
+
+class TestFollowerConnectedCallback:
+    def test_fires_immediately_when_already_connected(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        fired = threading.Event()
+        mgr.set_on_follower_connected(fired.set)
+        assert fired.wait(timeout=1)
+
+    def test_does_not_fire_when_no_peer(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        fired = threading.Event()
+        mgr.set_on_follower_connected(fired.set)
+        assert not fired.wait(timeout=0.2)
+
+
+class TestSendScrollImage:
+    def test_noop_when_not_connected(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.NO_PEER
+        with patch.object(sync_manager.socket, "socket") as sock:
+            mgr.send_scroll_image(Image.new("RGB", (4, 4)))
+            sock.assert_not_called()
+
+    def test_noop_for_follower_role(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        with patch.object(sync_manager.socket, "socket") as sock:
+            mgr.send_scroll_image(Image.new("RGB", (4, 4)))
+            sock.assert_not_called()
+
+    def test_sends_length_prefixed_png(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        mgr._peer_ip = "10.0.0.1"
+        fake_sock = MagicMock()
+        fake_sock.__enter__ = lambda s: s
+        fake_sock.__exit__ = lambda s, *a: False
+        with patch.object(sync_manager.socket, "socket", return_value=fake_sock):
+            mgr.send_scroll_image(Image.new("RGB", (4, 4)))
+        payload = fake_sock.sendall.call_args[0][0]
+        assert int.from_bytes(payload[:4], "big") == len(payload) - 4
+        assert payload[4:8] == b"\x89PNG"
+
+    def test_connection_error_is_swallowed(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        mgr._peer_ip = "10.0.0.1"
+        with patch.object(sync_manager.socket, "socket", side_effect=OSError("refused")):
+            mgr.send_scroll_image(Image.new("RGB", (4, 4)))  # must not raise
+        assert mgr.logger.debug.called
+
+
+class TestGetStatus:
+    def test_standalone_shape(self):
+        status = make_manager(role=SyncRole.STANDALONE).get_status()
+        assert status["role"] == "standalone"
+        assert status["state"] == "standalone"
+        assert status["local_rows"] == 32 and status["local_cols"] == 64
+
+    def test_leader_shape(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._leader_state = LeaderState.CONNECTED
+        mgr._peer_ip = "10.0.0.1"
+        mgr._peer_compatible = True
+        mgr._peer_chain = 2
+        mgr._leader_width = 128
+        status = mgr.get_status()
+        assert status["role"] == "leader"
+        assert status["state"] == "connected"
+        assert status["peer_ip"] == "10.0.0.1"
+        assert status["peer_chain"] == 2
+        assert status["leader_width"] == 128
+
+    def test_follower_shape(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        mgr._follower_state = FollowerState.FOLLOWER
+        mgr._leader_ip = "10.0.0.2"
+        status = mgr.get_status()
+        assert status["role"] == "follower"
+        assert status["state"] == "follower"
+        assert status["leader_ip"] == "10.0.0.2"
+        assert "peer_chain" not in status
+
+    def test_is_follower_active(self):
+        mgr = make_manager(role=SyncRole.FOLLOWER)
+        assert mgr.is_follower_active() is False
+        mgr._follower_state = FollowerState.FOLLOWER
+        assert mgr.is_follower_active() is True
+
+    def test_leader_is_never_follower_active(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._follower_state = FollowerState.FOLLOWER
+        assert mgr.is_follower_active() is False
+
+
+class TestWriteStatusFile:
+    def test_writes_status_and_cleans_up_temp(self):
+        mgr = make_manager(role=SyncRole.STANDALONE)
+        mgr.write_status_file()
+        data = json.loads(Path(sync_manager.STATUS_FILE).read_text())
+        assert data["role"] == "standalone"
+        assert "ts" in data
+        assert not Path(sync_manager.STATUS_FILE + ".tmp").exists()
+
+    def test_write_failure_is_swallowed(self, monkeypatch):
+        mgr = make_manager(role=SyncRole.STANDALONE)
+        monkeypatch.setattr("builtins.open", MagicMock(side_effect=OSError("disk full")))
+        mgr.write_status_file()  # must not raise
+        assert mgr.logger.debug.called
+
+
+class TestStop:
+    def _stub_with_sockets(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._recv_sock = MagicMock()
+        mgr._send_sock = MagicMock()
+        mgr._img_server_sock = MagicMock()
+        return mgr
+
+    def test_closes_every_socket(self):
+        mgr = self._stub_with_sockets()
+        mgr.stop()
+        assert mgr._running is False
+        mgr._recv_sock.close.assert_called_once()
+        mgr._send_sock.close.assert_called_once()
+        mgr._img_server_sock.close.assert_called_once()
+
+    def test_is_idempotent(self):
+        mgr = self._stub_with_sockets()
+        mgr.stop()
+        mgr.stop()  # must not raise
+
+    def test_close_failure_is_swallowed(self):
+        mgr = make_manager(role=SyncRole.LEADER)
+        mgr._recv_sock = MagicMock()
+        mgr._recv_sock.close.side_effect = OSError("already closed")
+        mgr.stop()  # must not raise
+        assert mgr.logger.debug.called
+
+    def test_handles_unset_sockets(self):
+        make_manager(role=SyncRole.STANDALONE).stop()  # all sockets None
+
+
+class TestLoopbackHandshake:
+    def test_leader_and_follower_negotiate_over_real_sockets(self, monkeypatch):
+        # One end-to-end check that the wire format actually round-trips:
+        # every other test drives the loops with mocked sockets.
+        monkeypatch.setattr(sync_manager, "HELLO_INTERVAL", 0.02)
+        monkeypatch.setattr(sync_manager, "HEARTBEAT_INTERVAL", 0.02)
+
+        # Pick a free port by binding one on loopback and releasing it.
+        # Loopback, not "", so this test never opens a port to the network.
+        probe = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        probe.bind(("127.0.0.1", 0))
+        port = probe.getsockname()[1]
+        probe.close()
+
+        hw = {"rows": 32, "cols": 64, "chain_length": 1}
+        leader = DisplaySyncManager("leader", {"port": port}, hw, MagicMock())
+        follower = DisplaySyncManager("follower", {"port": port}, hw, MagicMock())
+        try:
+            deadline = time.time() + 5.0
+            while time.time() < deadline:
+                if (leader._leader_state is LeaderState.CONNECTED
+                        and follower._peer_compatible):
+                    break
+                time.sleep(0.02)
+            assert leader._leader_state is LeaderState.CONNECTED
+            assert follower._peer_compatible is True
+            assert follower._leader_ip is not None
+        finally:
+            leader.stop()
+            follower.stop()

test/test_vegas_frame_percentile.py

@@ -0,0 +1,64 @@
+"""Tests the percentile used by the Vegas frame-time log line.
+
+The FPS line reports p99 next to the worst frame, and the point of having both
+is that they say different things: p99 is the bad-but-ordinary frame, worst is
+the outlier. The obvious index, int(n * 0.99), is off by one and at exactly
+100 samples selects the maximum -- so the two columns would report the same
+number precisely when the sample was smallest.
+"""
+
+import math
+
+import pytest
+
+from src.vegas_mode.coordinator import _percentile
+
+
+class TestNearestRank:
+    def test_a_hundred_samples_do_not_return_the_maximum(self):
+        ordered = [float(i) for i in range(100)]      # 0..99
+        assert _percentile(ordered, 0.99) == 98.0
+        assert _percentile(ordered, 0.99) != max(ordered)
+
+    def test_it_matches_the_nearest_rank_definition(self):
+        for n in (1, 2, 3, 10, 99, 100, 101, 600, 1000):
+            ordered = [float(i) for i in range(n)]
+            expected = ordered[min(n - 1, max(0, math.ceil(n * 0.99) - 1))]
+            assert _percentile(ordered, 0.99) == expected, n
+
+    @pytest.mark.parametrize('fraction,expected', [
+        (0.0, 0.0),      # first
+        (0.5, 49.0),     # median, nearest-rank
+        (1.0, 99.0),     # last
+    ])
+    def test_other_fractions(self, fraction, expected):
+        assert _percentile([float(i) for i in range(100)], fraction) == expected
+
+
+class TestEdges:
+    def test_empty_is_zero_not_an_error(self):
+        # The loop calls this before any frame has been timed.
+        assert _percentile([], 0.99) == 0.0
+
+    def test_a_single_sample_is_itself(self):
+        assert _percentile([4.2], 0.99) == 4.2
+
+    def test_it_never_indexes_past_the_end(self):
+        for n in range(1, 50):
+            _percentile([float(i) for i in range(n)], 1.0)   # must not raise
+
+
+class TestItSaysSomethingUsefulAboutFrames:
+    def test_one_freeze_does_not_drag_p99_up(self):
+        # 599 healthy frames and one 3.2s freeze: p99 should still describe
+        # the healthy population, while the worst frame is reported separately.
+        frames = [0.0083] * 599 + [3.2]
+        p99 = _percentile(sorted(frames), 0.99)
+        assert p99 == pytest.approx(0.0083), p99
+        assert max(frames) == 3.2
+
+    def test_sustained_slowness_does_move_it(self):
+        # Ten percent of frames slow is not an outlier, it is the shape of the
+        # distribution, and p99 must reflect that.
+        frames = [0.0083] * 540 + [0.05] * 60
+        assert _percentile(sorted(frames), 0.99) == pytest.approx(0.05)

test/web_interface/test_api_v3_backup_paths.py

@@ -0,0 +1,220 @@
+"""
+Path-containment tests for the backup file routes:
+GET /backup/download/<filename>, DELETE /backup/<filename>, and the
+listing/validation routes alongside them.
+
+Both filename routes take user input straight from the URL and turn it
+into a filesystem path, one to read and one to unlink. `_safe_backup_path`
+is what stops that from reaching outside the export directory, and it had
+no tests.
+
+This is verification of existing containment, not a fix: no bypass was
+found. The tests exist so that a later "just let dots through" change has
+to argue with something.
+"""
+
+import io
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from flask import Flask
+
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from web_interface.blueprints import api_v3 as api_v3_module  # noqa: E402
+from web_interface.blueprints.api_v3 import api_v3  # noqa: E402
+
+_MANAGER_ATTRS = (
+    'config_manager', 'plugin_manager', 'plugin_store_manager',
+    'plugin_state_manager', 'saved_repositories_manager', 'schema_manager',
+    'operation_queue', 'operation_history', 'cache_manager',
+)
+_SENTINEL = object()
+
+# Anything that tries to name a file outside the export directory, or that
+# is not a plain <name>.zip.
+TRAVERSAL_ATTEMPTS = [
+    "../../etc/passwd",
+    "../config.json",
+    "..%2f..%2fetc%2fpasswd",
+    "....//....//etc/passwd",
+    "/etc/passwd",
+    "..\\..\\config.json",
+    "backup.zip/../../../etc/passwd",
+    ".hidden.zip",
+    "backup.txt",
+    "backup.zip.exe",
+    "",
+    ".",
+    "..",
+]
+
+
+@pytest.fixture
+def env(tmp_path, monkeypatch):
+    export_dir = tmp_path / "backups"
+    export_dir.mkdir()
+    monkeypatch.setattr(api_v3_module, "_BACKUP_EXPORT_DIR", export_dir)
+
+    # A file outside the export dir that a traversal would be reaching for.
+    secret = tmp_path / "config.json"
+    secret.write_text(json.dumps({"secret": "do not touch"}))
+
+    originals = {name: getattr(api_v3, name, _SENTINEL) for name in _MANAGER_ATTRS}
+    for name in _MANAGER_ATTRS:
+        setattr(api_v3, name, MagicMock())
+
+    app = Flask(__name__)
+    app.config["TESTING"] = True
+    app.register_blueprint(api_v3, url_prefix="/api/v3")
+
+    class Env:
+        pass
+
+    e = Env()
+    e.client = app.test_client()
+    e.export_dir = export_dir
+    e.secret = secret
+    yield e
+
+    for name, original in originals.items():
+        if original is _SENTINEL:
+            if hasattr(api_v3, name):
+                delattr(api_v3, name)
+        else:
+            setattr(api_v3, name, original)
+
+
+def make_backup(export_dir, name="backup-2026-01-01.zip"):
+    path = export_dir / name
+    path.write_bytes(b"PK\x03\x04fake zip")
+    return path
+
+
+class TestSafeBackupPath:
+    """The containment helper itself."""
+
+    @pytest.mark.parametrize("filename", TRAVERSAL_ATTEMPTS)
+    def test_rejects_unsafe_names(self, env, filename):
+        assert api_v3_module._safe_backup_path(filename) is None
+
+    def test_rejects_none(self, env):
+        assert api_v3_module._safe_backup_path(None) is None
+
+    @pytest.mark.parametrize("filename", [
+        "backup.zip",
+        "backup-2026-01-01.zip",
+        "backup_2026.01.01-v2.zip",
+        "a.zip",
+    ])
+    def test_accepts_plain_zip_names(self, env, filename):
+        resolved = api_v3_module._safe_backup_path(filename)
+        assert resolved is not None
+        assert resolved.parent == env.export_dir.resolve()
+
+    def test_result_is_always_inside_the_export_dir(self, env):
+        resolved = api_v3_module._safe_backup_path("backup.zip")
+        resolved.relative_to(env.export_dir.resolve())  # raises if outside
+
+    def test_overlong_name_rejected(self, env):
+        assert api_v3_module._safe_backup_path("a" * 250 + ".zip") is None
+
+
+class TestDownload:
+    def test_downloads_an_existing_backup(self, env):
+        make_backup(env.export_dir)
+        response = env.client.get("/api/v3/backup/download/backup-2026-01-01.zip")
+        assert response.status_code == 200
+        assert response.data == b"PK\x03\x04fake zip"
+
+    def test_missing_file_is_a_404(self, env):
+        response = env.client.get("/api/v3/backup/download/never-made.zip")
+        assert response.status_code == 404
+
+    @pytest.mark.parametrize("filename", TRAVERSAL_ATTEMPTS)
+    def test_traversal_attempts_are_refused(self, env, filename):
+        response = env.client.get(f"/api/v3/backup/download/{filename}")
+        # However the request is turned away — 404 from the containment
+        # check, or 308/405 from routing never matching at all — what
+        # matters is that no file outside the export directory is served.
+        assert response.status_code != 200
+        assert b"do not touch" not in response.data
+
+
+class TestDelete:
+    def test_deletes_an_existing_backup(self, env):
+        path = make_backup(env.export_dir)
+        response = env.client.delete("/api/v3/backup/backup-2026-01-01.zip")
+        assert response.status_code == 200
+        assert not path.exists()
+
+    def test_missing_file_is_a_404(self, env):
+        response = env.client.delete("/api/v3/backup/never-made.zip")
+        assert response.status_code == 404
+
+    @pytest.mark.parametrize("filename", TRAVERSAL_ATTEMPTS)
+    def test_traversal_attempts_delete_nothing(self, env, filename):
+        response = env.client.delete(f"/api/v3/backup/{filename}")
+        assert response.status_code != 200
+        assert env.secret.exists()  # the file a traversal was aiming at
+
+    def test_only_the_named_backup_is_removed(self, env):
+        keep = make_backup(env.export_dir, "keep.zip")
+        drop = make_backup(env.export_dir, "drop.zip")
+        env.client.delete("/api/v3/backup/drop.zip")
+        assert keep.exists()
+        assert not drop.exists()
+
+    def test_directory_with_a_matching_name_is_not_removed(self, env):
+        # The delete loop matches by name but requires a regular file.
+        (env.export_dir / "sneaky.zip").mkdir()
+        response = env.client.delete("/api/v3/backup/sneaky.zip")
+        assert response.status_code == 404
+        assert (env.export_dir / "sneaky.zip").is_dir()
+
+
+class TestList:
+    def test_lists_only_zip_files(self, env):
+        make_backup(env.export_dir, "one.zip")
+        (env.export_dir / "notes.txt").write_text("ignore me")
+        response = env.client.get("/api/v3/backup/list")
+        assert response.status_code == 200
+        names = [entry["filename"] for entry in response.get_json()["data"]]
+        assert names == ["one.zip"]
+
+    def test_empty_directory_lists_nothing(self, env):
+        response = env.client.get("/api/v3/backup/list")
+        assert response.get_json()["data"] == []
+
+    def test_entries_carry_size_and_timestamp(self, env):
+        make_backup(env.export_dir, "one.zip")
+        entry = env.client.get("/api/v3/backup/list").get_json()["data"][0]
+        assert entry["size"] == len(b"PK\x03\x04fake zip")
+        assert entry["created_at"]
+
+
+class TestValidate:
+    def test_missing_file_is_a_400(self, env):
+        response = env.client.post("/api/v3/backup/validate", data={},
+                                   content_type="multipart/form-data")
+        assert response.status_code == 400
+        assert "No backup_file" in response.get_json()["message"]
+
+    def test_invalid_archive_is_a_400(self, env):
+        response = env.client.post(
+            "/api/v3/backup/validate",
+            data={"backup_file": (io.BytesIO(b"not a zip"), "bad.zip")},
+            content_type="multipart/form-data")
+        assert response.status_code == 400
+        assert "Invalid or corrupted" in response.get_json()["message"]
+
+    def test_validation_does_not_leave_temp_files_in_the_export_dir(self, env):
+        env.client.post(
+            "/api/v3/backup/validate",
+            data={"backup_file": (io.BytesIO(b"not a zip"), "bad.zip")},
+            content_type="multipart/form-data")
+        assert list(env.export_dir.iterdir()) == []

test/web_interface/test_api_v3_backup_restore.py

@@ -0,0 +1,262 @@
+"""
+Endpoint tests for POST /backup/restore.
+
+Restore is the most destructive operation the web interface exposes: it
+overwrites config, secrets, WiFi settings and fonts, and reinstalls
+plugins. It had no tests.
+
+restore_backup itself is mocked — this file is about what the route does
+with the request and with the result, not about ZIP handling, which
+belongs to backup_manager's own tests.
+
+Regression coverage for one fixed bug: a malformed `options` field fell
+back to {}, and since every RestoreOptions flag defaults to True, that
+turned a mis-serialized narrow restore into a full one — secrets
+included — with no indication anything had been ignored.
+"""
+
+import io
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from flask import Flask
+
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from web_interface.blueprints.api_v3 import api_v3  # noqa: E402
+
+URL = "/api/v3/backup/restore"
+
+_MANAGER_ATTRS = (
+    'config_manager', 'plugin_manager', 'plugin_store_manager',
+    'plugin_state_manager', 'saved_repositories_manager', 'schema_manager',
+    'operation_queue', 'operation_history', 'cache_manager',
+)
+_SENTINEL = object()
+
+
+class FakeResult:
+    """Stand-in for backup_manager.RestoreResult."""
+
+    def __init__(self, success=True, restored=None, errors=None,
+                 plugins_to_install=None):
+        self.success = success
+        self.restored = restored if restored is not None else ["config"]
+        self.errors = errors or []
+        self.plugins_to_install = plugins_to_install or []
+        self.plugins_installed = []
+        self.plugins_failed = []
+
+    def to_dict(self):
+        return {
+            "success": self.success,
+            "restored": self.restored,
+            "errors": self.errors,
+            "plugins_installed": self.plugins_installed,
+            "plugins_failed": self.plugins_failed,
+        }
+
+
+@pytest.fixture
+def client():
+    originals = {name: getattr(api_v3, name, _SENTINEL) for name in _MANAGER_ATTRS}
+    for name in _MANAGER_ATTRS:
+        setattr(api_v3, name, MagicMock())
+
+    app = Flask(__name__)
+    app.config["TESTING"] = True
+    app.register_blueprint(api_v3, url_prefix="/api/v3")
+    yield app.test_client()
+
+    for name, original in originals.items():
+        if original is _SENTINEL:
+            if hasattr(api_v3, name):
+                delattr(api_v3, name)
+        else:
+            setattr(api_v3, name, original)
+
+
+@pytest.fixture
+def restore():
+    """Patch backup_manager.restore_backup (imported inside the handler)."""
+    with patch("src.backup_manager.restore_backup") as mock:
+        mock.return_value = FakeResult()
+        yield mock
+
+
+def post(client, options=None, filename="backup.zip", content=b"PK\x03\x04fake"):
+    data = {"backup_file": (io.BytesIO(content), filename)}
+    if options is not None:
+        data["options"] = options
+    return client.post(URL, data=data, content_type="multipart/form-data")
+
+
+class TestRequestValidation:
+    def test_missing_file_is_a_400(self, client, restore):
+        response = client.post(URL, data={}, content_type="multipart/form-data")
+        assert response.status_code == 400
+        assert "No backup_file" in response.get_json()["message"]
+        restore.assert_not_called()
+
+    def test_absent_options_defaults_to_a_full_restore(self, client, restore):
+        # Documented default, not the bug: omitting options entirely means
+        # "restore everything".
+        post(client)
+        options = restore.call_args[0][2]
+        assert options.restore_config is True
+        assert options.restore_secrets is True
+        assert options.reinstall_plugins is True
+
+    def test_partial_options_are_honoured(self, client, restore):
+        post(client, options=json.dumps({
+            "restore_secrets": False, "reinstall_plugins": False}))
+        options = restore.call_args[0][2]
+        assert options.restore_secrets is False
+        assert options.reinstall_plugins is False
+        assert options.restore_config is True  # unspecified stays default
+
+    @pytest.mark.parametrize("raw", ["{not json", "", "{'single': 'quotes'}"])
+    def test_malformed_options_are_refused(self, client, restore, raw):
+        # Regression: this fell back to {}, and every flag defaults to
+        # True, so a caller asking for a narrow restore and mis-serializing
+        # it got a full one — secrets overwritten — and no warning.
+        response = post(client, options=raw)
+        assert response.status_code == 400
+        assert "Invalid options" in response.get_json()["message"]
+        restore.assert_not_called()
+
+    @pytest.mark.parametrize("raw", ["[1,2,3]", '"a string"', "42", "true", "null"])
+    def test_options_that_are_not_an_object_are_refused(self, client, restore, raw):
+        response = post(client, options=raw)
+        assert response.status_code == 400
+        restore.assert_not_called()
+
+    def test_empty_object_is_accepted_as_all_defaults(self, client, restore):
+        assert post(client, options="{}").status_code == 200
+        assert restore.call_args[0][2].restore_config is True
+
+
+class TestSuccess:
+    def test_success_returns_the_result(self, client, restore):
+        restore.return_value = FakeResult(success=True, restored=["config", "secrets"])
+        response = post(client)
+        assert response.status_code == 200
+        body = response.get_json()
+        assert body["status"] == "success"
+        assert body["data"]["restored"] == ["config", "secrets"]
+
+    def test_temp_file_is_cleaned_up(self, client, restore):
+        seen = {}
+
+        def capture(path, project_root, options):
+            seen["path"] = Path(path)
+            assert seen["path"].exists()  # present while restoring
+            return FakeResult()
+
+        restore.side_effect = capture
+        post(client)
+        assert not seen["path"].exists()
+
+    def test_temp_file_cleaned_up_even_when_restore_raises(self, client, restore):
+        seen = {}
+
+        def blow_up(path, project_root, options):
+            seen["path"] = Path(path)
+            raise RuntimeError("corrupt archive")
+
+        restore.side_effect = blow_up
+        response = post(client)
+        assert response.status_code == 500
+        assert not seen["path"].exists()
+
+
+class TestPluginReinstall:
+    def test_plugins_are_reinstalled_when_requested(self, client, restore):
+        restore.return_value = FakeResult(
+            plugins_to_install=[{"plugin_id": "clock"}, {"plugin_id": "weather"}])
+        api_v3.plugin_store_manager.install_plugin.return_value = True
+        response = post(client)
+        assert response.status_code == 200
+        assert response.get_json()["data"]["plugins_installed"] == ["clock", "weather"]
+
+    def test_reinstall_skipped_when_not_requested(self, client, restore):
+        restore.return_value = FakeResult(plugins_to_install=[{"plugin_id": "clock"}])
+        post(client, options=json.dumps({"reinstall_plugins": False}))
+        api_v3.plugin_store_manager.install_plugin.assert_not_called()
+
+    def test_entries_without_a_plugin_id_are_skipped(self, client, restore):
+        restore.return_value = FakeResult(plugins_to_install=[{}, {"plugin_id": "clock"}])
+        api_v3.plugin_store_manager.install_plugin.return_value = True
+        post(client)
+        assert api_v3.plugin_store_manager.install_plugin.call_count == 1
+
+    def test_failed_reinstall_turns_the_whole_restore_into_an_error(
+            self, client, restore):
+        # Pinned as intentional: file restoration succeeded and does not
+        # touch result.errors, but a user whose plugins did not come back
+        # should not be told the restore was a success.
+        restore.return_value = FakeResult(
+            success=True, plugins_to_install=[{"plugin_id": "clock"}])
+        api_v3.plugin_store_manager.install_plugin.return_value = False
+        response = post(client)
+        assert response.status_code == 500
+        body = response.get_json()
+        assert body["status"] == "error"
+        assert "clock" in body["message"]
+
+    def test_message_names_what_landed_and_what_did_not(self, client, restore):
+        restore.return_value = FakeResult(
+            success=True, restored=["config", "fonts"],
+            plugins_to_install=[{"plugin_id": "clock"}])
+        api_v3.plugin_store_manager.install_plugin.return_value = False
+        message = post(client).get_json()["message"]
+        assert "restored: config, fonts" in message
+        assert "plugins not reinstalled: clock" in message
+
+    def test_install_exception_is_recorded_without_leaking_details(
+            self, client, restore):
+        restore.return_value = FakeResult(plugins_to_install=[{"plugin_id": "clock"}])
+        api_v3.plugin_store_manager.install_plugin.side_effect = RuntimeError(
+            "/srv/internal/path exploded")
+        body = post(client).get_json()
+        failures = body["data"]["plugins_failed"]
+        assert failures[0]["plugin_id"] == "clock"
+        assert "/srv/internal/path" not in json.dumps(body)
+
+    def test_missing_store_manager_is_reported_per_plugin(self, client, restore):
+        restore.return_value = FakeResult(plugins_to_install=[{"plugin_id": "clock"}])
+        api_v3.plugin_store_manager = None
+        with patch("web_interface.blueprints.api_v3.plugin_store_manager", None):
+            body = post(client).get_json()
+        assert body["data"]["plugins_failed"][0]["error"] == "Store manager unavailable"
+
+
+class TestFailureReporting:
+    def test_restore_errors_produce_a_500(self, client, restore):
+        restore.return_value = FakeResult(
+            success=False, restored=[], errors=["config: permission denied"])
+        response = post(client)
+        assert response.status_code == 500
+        assert "permission denied" in response.get_json()["message"]
+
+    def test_partial_restore_names_both_sides(self, client, restore):
+        restore.return_value = FakeResult(
+            success=False, restored=["config"], errors=["secrets: unwritable"])
+        message = post(client).get_json()["message"]
+        assert "restored: config" in message
+        assert "failed: secrets: unwritable" in message
+
+    def test_failure_without_detail_still_says_something(self, client, restore):
+        restore.return_value = FakeResult(success=False, restored=[], errors=[])
+        message = post(client).get_json()["message"]
+        assert "Restore incomplete" in message
+
+    def test_unexpected_exception_is_a_500(self, client, restore):
+        restore.side_effect = RuntimeError("boom")
+        response = post(client)
+        assert response.status_code == 500
+        assert response.get_json()["status"] == "error"

test/web_interface/test_api_v3_config_raw.py

@@ -0,0 +1,199 @@
+"""
+Endpoint tests for POST /config/raw/main and POST /config/raw/secrets.
+
+These write whatever JSON they are given straight to config.json and
+config_secrets.json, bypassing the secret-separation path that
+/config/main and the plugin-config endpoints go through. Given how much
+care the rest of the config surface takes to keep secrets out of
+config.json, an untested pair of endpoints that writes it verbatim is
+worth pinning precisely.
+
+Like test_api_v3_secret_roundtrip.py, these run a REAL ConfigManager over
+tmp_path so the assertions are against files on disk rather than mock
+calls.
+"""
+
+import json
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from flask import Flask
+
+project_root = Path(__file__).parent.parent.parent
+sys.path.insert(0, str(project_root))
+
+from src.config_manager import ConfigManager  # noqa: E402
+from src.exceptions import ConfigError  # noqa: E402
+from web_interface.blueprints.api_v3 import api_v3  # noqa: E402
+
+MAIN = "/api/v3/config/raw/main"
+SECRETS = "/api/v3/config/raw/secrets"
+
+
+@pytest.fixture
+def env(tmp_path):
+    config_file = tmp_path / "config.json"
+    config_file.write_text(json.dumps({"timezone": "UTC"}))
+    secrets_file = tmp_path / "config_secrets.json"
+
+    config_manager = ConfigManager(
+        config_path=str(config_file), secrets_path=str(secrets_file))
+    config_manager.template_path = str(tmp_path / "no-template.json")
+
+    _SENTINEL = object()
+    attrs = ('config_manager', 'plugin_manager', 'plugin_store_manager',
+             'plugin_state_manager', 'saved_repositories_manager',
+             'schema_manager', 'operation_queue', 'operation_history',
+             'cache_manager')
+    originals = {name: getattr(api_v3, name, _SENTINEL) for name in attrs}
+
+    for name in attrs:
+        setattr(api_v3, name, MagicMock())
+    api_v3.config_manager = config_manager
+
+    app = Flask(__name__)
+    app.config["TESTING"] = True
+    app.register_blueprint(api_v3, url_prefix="/api/v3")
+
+    class Env:
+        pass
+
+    e = Env()
+    e.client = app.test_client()
+    e.config_manager = config_manager
+    e.config_file = config_file
+    e.secrets_file = secrets_file
+    yield e
+
+    for name, original in originals.items():
+        if original is _SENTINEL:
+            if hasattr(api_v3, name):
+                delattr(api_v3, name)
+        else:
+            setattr(api_v3, name, original)
+
+
+class TestSaveRawMain:
+    def test_writes_the_body_to_config_json(self, env):
+        response = env.client.post(MAIN, json={"timezone": "America/Chicago"})
+        assert response.status_code == 200
+        assert json.loads(env.config_file.read_text()) == {"timezone": "America/Chicago"}
+
+    def test_replaces_rather_than_merges(self, env):
+        env.client.post(MAIN, json={"only": "this"})
+        assert json.loads(env.config_file.read_text()) == {"only": "this"}
+
+    def test_does_not_touch_the_secrets_file(self, env):
+        env.secrets_file.write_text(json.dumps({"weather": {"api_key": "k"}}))
+        env.client.post(MAIN, json={"timezone": "UTC"})
+        assert json.loads(env.secrets_file.read_text()) == {"weather": {"api_key": "k"}}
+
+    def test_uninitialized_manager_is_a_500(self, env):
+        api_v3.config_manager = None
+        response = env.client.post(MAIN, json={"timezone": "UTC"})
+        assert response.status_code == 500
+        assert "not initialized" in response.get_json()["message"]
+
+    def test_empty_object_is_a_400(self, env):
+        response = env.client.post(MAIN, json={})
+        assert response.status_code == 400
+        assert "No data provided" in response.get_json()["message"]
+
+    def test_bodyless_post_is_a_400(self, env):
+        response = env.client.post(MAIN)
+        assert response.status_code == 400
+        assert "No data provided" in response.get_json()["message"]
+
+    def test_malformed_json_is_a_400_in_the_app_shape(self, env):
+        response = env.client.post(MAIN, data="{not json",
+                                   content_type="application/json")
+        assert response.status_code == 400
+        body = response.get_json()
+        assert body["status"] == "error"
+
+    def test_config_error_is_a_500_with_context(self, env, monkeypatch):
+        def refuse(kind, data):
+            raise ConfigError("cannot write", config_path="/etc/x.json")
+        monkeypatch.setattr(env.config_manager, "save_raw_file_content", refuse)
+        response = env.client.post(MAIN, json={"timezone": "UTC"})
+        assert response.status_code == 500
+        assert "/etc/x.json" in json.dumps(response.get_json())
+
+    def test_unexpected_error_is_a_500(self, env, monkeypatch):
+        def boom(kind, data):
+            raise RuntimeError("disk on fire")
+        monkeypatch.setattr(env.config_manager, "save_raw_file_content", boom)
+        response = env.client.post(MAIN, json={"timezone": "UTC"})
+        assert response.status_code == 500
+        assert response.get_json()["status"] == "error"
+
+
+class TestSaveRawSecrets:
+    def test_writes_only_to_the_secrets_file(self, env):
+        response = env.client.post(SECRETS, json={"weather": {"api_key": "s3cret"}})
+        assert response.status_code == 200
+        assert json.loads(env.secrets_file.read_text()) == {"weather": {"api_key": "s3cret"}}
+
+    def test_secret_values_never_reach_config_json(self, env):
+        env.client.post(SECRETS, json={"weather": {"api_key": "s3cret"}})
+        assert "s3cret" not in env.config_file.read_text()
+
+    def test_existing_main_config_is_untouched(self, env):
+        before = env.config_file.read_text()
+        env.client.post(SECRETS, json={"weather": {"api_key": "k"}})
+        assert env.config_file.read_text() == before
+
+    def test_github_token_is_reloaded_for_the_store_manager(self, env):
+        store = MagicMock()
+        store._load_github_token.return_value = "ghp_new"
+        api_v3.plugin_store_manager = store
+        env.client.post(SECRETS, json={"github": {"token": "ghp_new"}})
+        store._load_github_token.assert_called_once()
+        assert store.github_token == "ghp_new"
+
+    def test_absent_store_manager_is_fine(self, env):
+        api_v3.plugin_store_manager = None
+        assert env.client.post(SECRETS, json={"a": 1}).status_code == 200
+
+    def test_uninitialized_manager_is_a_500(self, env):
+        api_v3.config_manager = None
+        assert env.client.post(SECRETS, json={"a": 1}).status_code == 500
+
+    def test_empty_object_is_a_400(self, env):
+        assert env.client.post(SECRETS, json={}).status_code == 400
+
+    def test_bodyless_post_is_a_400(self, env):
+        assert env.client.post(SECRETS).status_code == 400
+
+    def test_error_is_a_500(self, env, monkeypatch):
+        def boom(kind, data):
+            raise RuntimeError("nope")
+        monkeypatch.setattr(env.config_manager, "save_raw_file_content", boom)
+        assert env.client.post(SECRETS, json={"a": 1}).status_code == 500
+
+
+class TestRawEndpointsBypassSecretSeparation:
+    """Pinned behaviour, deliberately not "fixed".
+
+    These endpoints are the escape hatch for editing the config files
+    directly from the web UI's raw JSON editor. They write what they are
+    given, so a secret typed into the main-config editor lands in
+    config.json in plain text — unlike /config/main and the plugin-config
+    endpoints, which route x-secret fields into config_secrets.json.
+
+    That is the point of a raw editor, but it is a sharp edge worth
+    stating out loud: anyone adding a "convenience" that posts plugin
+    config through this endpoint would silently lose secret separation.
+    """
+
+    def test_secret_shaped_keys_are_written_verbatim_to_main(self, env):
+        env.client.post(MAIN, json={"weather": {"api_key": "PLAINTEXT-KEY"}})
+        on_disk = json.loads(env.config_file.read_text())
+        assert on_disk["weather"]["api_key"] == "PLAINTEXT-KEY"
+
+    def test_no_separation_happens_on_the_raw_path(self, env):
+        env.client.post(MAIN, json={"weather": {"api_key": "PLAINTEXT-KEY"}})
+        # Nothing was moved aside into the secrets file.
+        assert not env.secrets_file.exists() or "PLAINTEXT-KEY" not in env.secrets_file.read_text()

test/web_interface/test_calendar_oauth_endpoints.py

@@ -1,344 +0,0 @@
-"""Tests the calendar plugin's OAuth and calendar-listing endpoints.
-
-The plugin's config UI advertised a three-step setup, but only step 1 existed
-on the server. Step 3's picker fetched /api/v3/plugins/calendar/list-calendars,
-which was never registered, so Flask fell through to the global 404 handler and
-the user saw "Resource not found" — with nothing to say which resource. Step 2
-had no endpoint either, and no field in the schema at all, even though the
-plugin ships calendar_registration.py written expressly for a web-driven
-two-step flow.
-
-These cover the two new routes: that they exist, that they fail with something
-actionable rather than a bare 404, and that the shapes the widgets consume are
-what the server actually sends.
-"""
-
-import json
-import pickle
-import sys
-from pathlib import Path
-
-import pytest
-
-project_root = Path(__file__).parent.parent.parent
-sys.path.insert(0, str(project_root))
-
-from web_interface.blueprints import api_v3 as mod  # noqa: E402
-
-
-@pytest.fixture
-def client(monkeypatch, tmp_path):
-    """A test client whose calendar plugin lives in tmp_path."""
-    from flask import Flask
-
-    plugin_dir = tmp_path / 'calendar'
-    plugin_dir.mkdir()
-
-    app = Flask(__name__)
-    app.register_blueprint(mod.api_v3, url_prefix='/api/v3')
-    app.config['TESTING'] = True
-    monkeypatch.setattr(mod, '_calendar_plugin_dir', lambda: plugin_dir)
-    with app.test_client() as c:
-        c.plugin_dir = plugin_dir
-        yield c
-
-
-@pytest.fixture
-def uninstalled(monkeypatch):
-    from flask import Flask
-
-    app = Flask(__name__)
-    app.register_blueprint(mod.api_v3, url_prefix='/api/v3')
-    app.config['TESTING'] = True
-    monkeypatch.setattr(mod, '_calendar_plugin_dir', lambda: None)
-    with app.test_client() as c:
-        yield c
-
-
-class TestTheRoutesExistAtAll:
-    """The original bug: the URLs the widgets call were not registered."""
-
-    def test_list_calendars_is_routed(self, client):
-        response = client.get('/api/v3/plugins/calendar/list-calendars')
-        # Reaching the handler is the whole point; what it then says about
-        # missing setup is TestItSaysWhatIsWrong's business.
-        assert response.status_code != 404, "still unrouted"
-        assert response.get_json()['message'] != 'Resource not found'
-
-    def test_authenticate_is_routed(self, client):
-        response = client.post('/api/v3/plugins/calendar/authenticate', json={})
-        assert response.status_code != 404, "still unrouted"
-        assert response.get_json()['message'] != 'Resource not found'
-
-    def test_both_urls_match_what_the_widgets_request(self):
-        # The widgets hardcode these; a rename on either side reintroduces the
-        # original bug silently.
-        picker = Path(project_root) / 'web_interface/static/v3/js/widgets/google-calendar-picker.js'
-        oauth = Path(project_root) / 'web_interface/static/v3/js/widgets/google-oauth.js'
-        assert '/api/v3/plugins/calendar/list-calendars' in picker.read_text(encoding='utf-8')
-        assert '/api/v3/plugins/calendar/authenticate' in oauth.read_text(encoding='utf-8')
-        source = (Path(project_root) / 'web_interface/blueprints/api_v3.py').read_text(encoding='utf-8')
-        assert "'/plugins/calendar/list-calendars'" in source
-        assert "'/plugins/calendar/authenticate'" in source
-
-    def test_the_oauth_widget_is_dispatched_not_rendered_as_a_text_box(self):
-        # The string branch of the config template dispatches on an allow-list
-        # of widget names; anything missing from it silently falls through to a
-        # plain <input type="text">. That produced two boxes on the calendar
-        # page -- the widget's own, and a stray one for the same field -- and
-        # no way to tell which to paste into.
-        template = (Path(project_root)
-                    / 'web_interface/templates/v3/partials/plugin_config.html'
-                    ).read_text(encoding='utf-8')
-        allow_list_line = [ln for ln in template.splitlines()
-                           if "str_widget in [" in ln]
-        assert allow_list_line, "the string widget allow-list moved"
-        assert "'google-oauth'" in allow_list_line[0], allow_list_line[0]
-
-    def test_the_widget_script_is_served(self):
-        base = (Path(project_root) / 'web_interface/templates/v3/base.html'
-                ).read_text(encoding='utf-8')
-        assert 'widgets/google-oauth.js' in base
-
-    def test_the_failed_page_is_called_out_loudly(self):
-        # The loopback redirect lands on a browser error page at exactly the
-        # moment the user has to act. In small grey text it gets missed and the
-        # flow reads as broken while it is working.
-        widget = (Path(project_root)
-                  / 'web_interface/static/v3/js/widgets/google-oauth.js'
-                  ).read_text(encoding='utf-8')
-        assert 'expected' in widget.lower()
-        assert 'amber' in widget, "the warning is not visually distinguished"
-
-
-class TestItSaysWhatIsWrong:
-    def test_listing_without_a_token_asks_for_step_2(self, client):
-        response = client.get('/api/v3/plugins/calendar/list-calendars')
-        assert response.status_code == 400
-        body = response.get_json()
-        assert body['status'] == 'error'
-        assert 'step 2' in body['message'].lower(), body['message']
-
-    def test_authenticating_without_credentials_asks_for_step_1(self, client):
-        response = client.post('/api/v3/plugins/calendar/authenticate', json={})
-        assert response.status_code == 400
-        assert 'step 1' in response.get_json()['message'].lower()
-
-    def test_an_uninstalled_plugin_says_so(self, uninstalled):
-        for response in (
-            uninstalled.get('/api/v3/plugins/calendar/list-calendars'),
-            uninstalled.post('/api/v3/plugins/calendar/authenticate', json={}),
-        ):
-            assert response.status_code == 404
-            # A 404 here is honest -- but it must name the plugin, not read as
-            # the generic "Resource not found" that started this.
-            assert 'not installed' in response.get_json()['message'].lower()
-
-
-class TestTheScriptRunner:
-    def test_it_returns_the_json_the_script_prints(self, tmp_path):
-        script = tmp_path / 'calendar_registration.py'
-        script.write_text(
-            'print(\'{"status": "success", "auth_url": "https://x"}\')\n',
-            encoding='utf-8')
-        payload, error = mod._run_calendar_registration(tmp_path, '')
-        assert error is None
-        assert payload['auth_url'] == 'https://x'
-
-    def test_it_ignores_noise_before_the_json(self, tmp_path):
-        # An import warning or a library writing to stdout would otherwise
-        # make the last-line parse fail.
-        script = tmp_path / 'calendar_registration.py'
-        script.write_text(
-            'print("some library warning")\n'
-            'print(\'{"status": "success"}\')\n', encoding='utf-8')
-        payload, error = mod._run_calendar_registration(tmp_path, '')
-        assert error is None and payload['status'] == 'success'
-
-    def test_it_passes_stdin_through(self, tmp_path):
-        script = tmp_path / 'calendar_registration.py'
-        script.write_text(
-            'import sys, json\n'
-            'print(json.dumps({"status": "success", "got": sys.stdin.read().strip()}))\n',
-            encoding='utf-8')
-        payload, _ = mod._run_calendar_registration(tmp_path, 'http://127.0.0.1/?code=abc')
-        assert payload['got'] == 'http://127.0.0.1/?code=abc'
-
-    def test_a_missing_script_is_reported(self, tmp_path):
-        payload, error = mod._run_calendar_registration(tmp_path, '')
-        assert payload is None
-        assert 'script not found' in error.lower()
-
-    def test_output_that_is_not_json_is_reported_with_context(self, tmp_path):
-        script = tmp_path / 'calendar_registration.py'
-        script.write_text('import sys\nsys.stderr.write("boom\\n")\n', encoding='utf-8')
-        payload, error = mod._run_calendar_registration(tmp_path, '')
-        assert payload is None
-        assert 'no result' in error.lower()
-        assert 'boom' in error
-
-
-class TestListingShape:
-    """The picker reads cal.id, cal.summary and cal.primary."""
-
-    def _authenticate(self, client, monkeypatch, items):
-        creds = type('C', (), {'expired': False, 'refresh_token': None, 'valid': True})()
-        (client.plugin_dir / 'token.pickle').write_bytes(pickle.dumps({'x': 1}))
-        monkeypatch.setattr(mod.pickle if hasattr(mod, 'pickle') else pickle,
-                            'loads', lambda *a, **k: creds, raising=False)
-
-        import types
-        fake_pickle = types.SimpleNamespace(load=lambda f: creds, dump=lambda *a: None)
-        pages = items if isinstance(items, list) and items and isinstance(items[0], dict) \
-            else items
-        if isinstance(pages, list):
-            pages = [{'items': pages}]
-
-        state = {'i': 0}
-
-        def fake_list(**kwargs):
-            page = pages[min(state['i'], len(pages) - 1)]
-            state['i'] += 1
-            return types.SimpleNamespace(execute=lambda: page)
-
-        def fake_build(*args, **kwargs):
-            return types.SimpleNamespace(
-                calendarList=lambda: types.SimpleNamespace(list=fake_list))
-
-        real_import = __builtins__['__import__'] if isinstance(__builtins__, dict) \
-            else __builtins__.__import__
-
-        def fake_import(name, *args, **kwargs):
-            if name == 'pickle':
-                return fake_pickle
-            if name == 'google.auth.transport.requests':
-                return types.SimpleNamespace(Request=object)
-            if name == 'googleapiclient.discovery':
-                return types.SimpleNamespace(build=fake_build)
-            return real_import(name, *args, **kwargs)
-
-        monkeypatch.setattr('builtins.__import__', fake_import)
-
-    def test_it_returns_id_summary_and_primary(self, client, monkeypatch):
-        self._authenticate(client, monkeypatch, [
-            {'id': 'b@x', 'summary': 'Work'},
-            {'id': 'a@x', 'summary': 'Personal', 'primary': True},
-        ])
-        body = client.get('/api/v3/plugins/calendar/list-calendars').get_json()
-        assert body['status'] == 'success'
-        assert {c['id'] for c in body['calendars']} == {'a@x', 'b@x'}
-        assert all(set(c) == {'id', 'summary', 'primary'} for c in body['calendars'])
-
-    def test_the_primary_calendar_comes_first(self, client, monkeypatch):
-        # Short list, but the one the user wants is almost always their own.
-        self._authenticate(client, monkeypatch, [
-            {'id': 'z@x', 'summary': 'Aardvarks'},
-            {'id': 'a@x', 'summary': 'Zebras', 'primary': True},
-        ])
-        body = client.get('/api/v3/plugins/calendar/list-calendars').get_json()
-        assert body['calendars'][0]['id'] == 'a@x'
-        assert body['calendars'][0]['primary'] is True
-
-    def test_a_calendar_without_a_name_still_lists(self, client, monkeypatch):
-        self._authenticate(client, monkeypatch, [{'id': 'noname@x'}])
-        body = client.get('/api/v3/plugins/calendar/list-calendars').get_json()
-        assert body['calendars'][0]['summary'] == 'noname@x'
-
-    def test_entries_without_an_id_are_dropped(self, client, monkeypatch):
-        # Nothing could be selected by such a row, and the checkbox value
-        # would be undefined.
-        self._authenticate(client, monkeypatch, [{'summary': 'ghost'}, {'id': 'real@x'}])
-        body = client.get('/api/v3/plugins/calendar/list-calendars').get_json()
-        assert [c['id'] for c in body['calendars']] == ['real@x']
-
-
-class TestPagination:
-    """calendarList.list pages at 250 and defaults to 100."""
-
-    def _paged(self, client, monkeypatch, pages):
-        import types
-        creds = type('C', (), {'expired': False, 'refresh_token': None, 'valid': True})()
-        (client.plugin_dir / 'token.pickle').write_bytes(b'x')
-        state = {'i': 0}
-        seen = []
-
-        def fake_list(**kwargs):
-            seen.append(kwargs)
-            page = pages[min(state['i'], len(pages) - 1)]
-            state['i'] += 1
-            return types.SimpleNamespace(execute=lambda: page)
-
-        def fake_build(*args, **kwargs):
-            return types.SimpleNamespace(
-                calendarList=lambda: types.SimpleNamespace(list=fake_list))
-
-        real_import = __builtins__['__import__'] if isinstance(__builtins__, dict) \
-            else __builtins__.__import__
-
-        def fake_import(name, *args, **kwargs):
-            if name == 'pickle':
-                return types.SimpleNamespace(load=lambda f: creds, dump=lambda *a: None)
-            if name == 'google.auth.transport.requests':
-                return types.SimpleNamespace(Request=object)
-            if name == 'googleapiclient.discovery':
-                return types.SimpleNamespace(build=fake_build)
-            return real_import(name, *args, **kwargs)
-
-        monkeypatch.setattr('builtins.__import__', fake_import)
-        return seen
-
-    def test_every_page_is_collected(self, client, monkeypatch):
-        # Taking only the first page would hide calendars from the picker with
-        # nothing to say the list was cut short.
-        self._paged(client, monkeypatch, [
-            {'items': [{'id': 'a@x', 'summary': 'A'}], 'nextPageToken': 't1'},
-            {'items': [{'id': 'b@x', 'summary': 'B'}], 'nextPageToken': 't2'},
-            {'items': [{'id': 'c@x', 'summary': 'C'}]},
-        ])
-        body = client.get('/api/v3/plugins/calendar/list-calendars').get_json()
-        assert [c['id'] for c in body['calendars']] == ['a@x', 'b@x', 'c@x']
-
-    def test_the_page_token_is_passed_back(self, client, monkeypatch):
-        seen = self._paged(client, monkeypatch, [
-            {'items': [{'id': 'a@x', 'summary': 'A'}], 'nextPageToken': 'tok'},
-            {'items': [{'id': 'b@x', 'summary': 'B'}]},
-        ])
-        client.get('/api/v3/plugins/calendar/list-calendars')
-        assert seen[0]['pageToken'] is None
-        assert seen[1]['pageToken'] == 'tok'
-        assert all(k['maxResults'] == 250 for k in seen)
-
-    def test_a_looping_token_cannot_spin_forever(self, client, monkeypatch):
-        # Every page claims another follows.
-        self._paged(client, monkeypatch, [
-            {'items': [{'id': 'a@x', 'summary': 'A'}], 'nextPageToken': 'same'},
-        ])
-        body = client.get('/api/v3/plugins/calendar/list-calendars').get_json()
-        assert body['status'] == 'success'
-        assert len(body['calendars']) <= mod._CALENDAR_LIST_MAX_PAGES
-
-
-class TestDiagnosticsAreRedacted:
-    def test_script_stderr_is_redacted_on_the_way_out(self, tmp_path):
-        script = tmp_path / 'calendar_registration.py'
-        script.write_text(
-            'import sys\n'
-            'sys.stderr.write("boom client_secret=hunter2 more\\n")\n',
-            encoding='utf-8')
-        payload, error = mod._run_calendar_registration(tmp_path, '')
-        assert payload is None
-        assert 'hunter2' not in error, error
-        assert '<redacted>' in error, error
-
-    def test_a_failing_script_payload_is_redacted(self, client):
-        (client.plugin_dir / 'credentials.json').write_text('{}', encoding='utf-8')
-        (client.plugin_dir / 'calendar_registration.py').write_text(
-            'import json\n'
-            'print(json.dumps({"status": "error", '
-            '"message": "Failed: client_secret=topsecret"}))\n',
-            encoding='utf-8')
-        body = client.post('/api/v3/plugins/calendar/authenticate',
-                           json={}).get_json()
-        assert body['status'] == 'error'
-        assert 'topsecret' not in json.dumps(body), body
-        assert '<redacted>' in body['message'], body

test/web_interface/test_error_handler.py

@@ -0,0 +1,149 @@
+"""
+Tests for the response builders in src/web_interface/error_handler.py and
+the success path in src/web_interface/api_helpers.py.
+
+describe_exception() in the same module is already covered by
+test/test_web_error_detail.py and is not duplicated here.
+
+Regression coverage for one fixed bug: create_success_response used
+truthiness for `message` and `metadata` while using `is not None` for
+`data`, so an explicitly-passed "" or {} was silently dropped —
+api_helpers.success_response() repeated the same gate, which is the path
+every api_v3 endpoint actually calls.
+"""
+
+import pytest
+from flask import Flask
+
+from src.web_interface.api_helpers import success_response
+from src.web_interface.error_handler import (
+    create_error_response,
+    create_success_response,
+)
+from src.web_interface.errors import ErrorCode, WebInterfaceError
+
+
+@pytest.fixture
+def app():
+    return Flask(__name__)
+
+
+class TestCreateErrorResponse:
+    def test_returns_response_and_status_tuple(self, app):
+        with app.test_request_context():
+            response, status = create_error_response(
+                ErrorCode.CONFIG_SAVE_FAILED, "could not save")
+        assert status == 500
+        assert response.get_json()["message"] == "could not save"
+
+    def test_status_code_passthrough(self, app):
+        with app.test_request_context():
+            _, status = create_error_response(
+                ErrorCode.INVALID_INPUT, "bad", status_code=400)
+        assert status == 400
+
+    def test_body_matches_the_error_dataclass(self, app):
+        with app.test_request_context():
+            response, _ = create_error_response(
+                ErrorCode.NETWORK_ERROR, "offline",
+                details="connection refused", context={"url": "http://x"})
+        expected = WebInterfaceError(
+            error_code=ErrorCode.NETWORK_ERROR, message="offline",
+            details="connection refused", context={"url": "http://x"}).to_dict()
+        assert response.get_json() == expected
+
+    def test_none_context_produces_no_context_key(self, app):
+        with app.test_request_context():
+            response, _ = create_error_response(ErrorCode.SYSTEM_ERROR, "boom")
+        assert "context" not in response.get_json()
+
+    def test_suggested_fixes_passed_through(self, app):
+        with app.test_request_context():
+            response, _ = create_error_response(
+                ErrorCode.SYSTEM_ERROR, "boom", suggested_fixes=["Try again"])
+        assert response.get_json()["suggested_fixes"] == ["Try again"]
+
+
+class TestCreateSuccessResponse:
+    def test_bare_success(self):
+        assert create_success_response() == {"status": "success"}
+
+    def test_data_included(self):
+        assert create_success_response(data={"a": 1})["data"] == {"a": 1}
+
+    @pytest.mark.parametrize("falsy", [0, "", False, {}, []])
+    def test_falsy_data_is_still_included(self, falsy):
+        assert create_success_response(data=falsy)["data"] == falsy
+
+    def test_none_data_omitted(self):
+        assert "data" not in create_success_response(data=None)
+
+    def test_message_included(self):
+        assert create_success_response(message="done")["message"] == "done"
+
+    def test_empty_message_is_still_included(self):
+        # Regression: `if message:` dropped an explicitly-passed "".
+        assert create_success_response(message="")["message"] == ""
+
+    def test_none_message_omitted(self):
+        assert "message" not in create_success_response(message=None)
+
+    def test_metadata_included(self):
+        assert create_success_response(metadata={"v": 1})["metadata"] == {"v": 1}
+
+    def test_empty_metadata_is_still_included(self):
+        # Regression: `if metadata:` dropped an explicitly-passed {}.
+        assert create_success_response(metadata={})["metadata"] == {}
+
+    def test_none_metadata_omitted(self):
+        assert "metadata" not in create_success_response(metadata=None)
+
+
+class TestSuccessResponseHelper:
+    """api_helpers.success_response — the wrapper every endpoint calls."""
+
+    def test_plain_response_has_no_metadata_block(self, app):
+        with app.test_request_context():
+            body = success_response(data={"a": 1}).get_json()
+        assert body == {"status": "success", "data": {"a": 1}}
+
+    def test_explicit_empty_metadata_survives_the_wrapper(self, app):
+        # Regression: the wrapper re-gated metadata on truthiness after
+        # create_success_response had already included it, so {} was
+        # dropped again on the way out.
+        with app.test_request_context():
+            body = success_response(data=None, metadata={}).get_json()
+        assert body["metadata"] == {}
+
+    def test_caller_metadata_preserved(self, app):
+        with app.test_request_context():
+            body = success_response(metadata={"version": "1.2"}).get_json()
+        assert body["metadata"]["version"] == "1.2"
+
+    def test_timing_added_when_request_has_start_time(self, app):
+        with app.test_request_context() as ctx:
+            ctx.request.start_time = 0.0
+            body = success_response(data={"a": 1}).get_json()
+        assert "response_time_ms" in body["metadata"]
+
+    def test_timing_merges_with_caller_metadata(self, app):
+        with app.test_request_context() as ctx:
+            ctx.request.start_time = 0.0
+            body = success_response(metadata={"version": "1.2"}).get_json()
+        assert body["metadata"]["version"] == "1.2"
+        assert "response_time_ms" in body["metadata"]
+
+    def test_caller_metadata_dict_is_not_mutated(self, app):
+        # The helper used to add response_time_ms straight into the dict the
+        # caller passed, so a module-level or reused metadata dict would
+        # accumulate timings from previous requests.
+        caller_metadata = {"version": "1.2"}
+        with app.test_request_context() as ctx:
+            ctx.request.start_time = 0.0
+            success_response(metadata=caller_metadata)
+        assert caller_metadata == {"version": "1.2"}
+
+    def test_message_passed_through(self, app):
+        with app.test_request_context():
+            body = success_response(message="saved").get_json()
+        assert body["message"] == "saved"

test/web_interface/test_errors.py

@@ -0,0 +1,208 @@
+"""
+Tests for src/web_interface/errors.py — the structured error type behind
+every API error response (category inference, default suggestions, the
+JSON shape, and exception conversion).
+
+Pure logic; no Flask context needed.
+
+Regression coverage for one fixed bug: suggested_fixes used `or`, so a
+caller passing [] to mean "no suggestions" silently got the default list.
+"""
+
+import pytest
+
+from src.web_interface.errors import ErrorCategory, ErrorCode, WebInterfaceError
+
+
+class TestCategoryInference:
+    @pytest.mark.parametrize("code,expected", [
+        (ErrorCode.CONFIG_SAVE_FAILED, ErrorCategory.CONFIGURATION),
+        (ErrorCode.CONFIG_ROLLBACK_FAILED, ErrorCategory.CONFIGURATION),
+        (ErrorCode.PLUGIN_NOT_FOUND, ErrorCategory.PLUGIN),
+        (ErrorCode.PLUGIN_OPERATION_CONFLICT, ErrorCategory.PLUGIN),
+        (ErrorCode.VALIDATION_ERROR, ErrorCategory.VALIDATION),
+        (ErrorCode.SCHEMA_VALIDATION_FAILED, ErrorCategory.VALIDATION),
+        (ErrorCode.INVALID_INPUT, ErrorCategory.VALIDATION),
+        (ErrorCode.NETWORK_ERROR, ErrorCategory.NETWORK),
+        (ErrorCode.API_ERROR, ErrorCategory.NETWORK),
+        (ErrorCode.TIMEOUT, ErrorCategory.NETWORK),
+        (ErrorCode.PERMISSION_DENIED, ErrorCategory.PERMISSION),
+        (ErrorCode.FILE_PERMISSION_ERROR, ErrorCategory.PERMISSION),
+        (ErrorCode.SYSTEM_ERROR, ErrorCategory.SYSTEM),
+        (ErrorCode.SERVICE_UNAVAILABLE, ErrorCategory.SYSTEM),
+        (ErrorCode.UNKNOWN_ERROR, ErrorCategory.UNKNOWN),
+    ])
+    def test_every_code_prefix_maps_to_its_category(self, code, expected):
+        assert WebInterfaceError(code, "msg").category is expected
+
+    def test_explicit_category_overrides_inference(self):
+        error = WebInterfaceError(
+            ErrorCode.CONFIG_SAVE_FAILED, "msg", category=ErrorCategory.SYSTEM)
+        assert error.category is ErrorCategory.SYSTEM
+
+    def test_every_error_code_gets_a_category(self):
+        # No code may fall through uncategorized as the enum grows.
+        for code in ErrorCode:
+            assert isinstance(WebInterfaceError(code, "msg").category, ErrorCategory)
+
+
+class TestDefaultSuggestions:
+    def test_mapped_code_gets_specific_suggestions(self):
+        fixes = WebInterfaceError(ErrorCode.CONFIG_SAVE_FAILED, "msg").suggested_fixes
+        assert "Check available disk space" in fixes
+
+    def test_unmapped_code_gets_generic_fallback(self):
+        # PLUGIN_UPDATE_FAILED has no entry in suggestions_map.
+        fixes = WebInterfaceError(ErrorCode.PLUGIN_UPDATE_FAILED, "msg").suggested_fixes
+        assert fixes == ["Review error details and try again"]
+
+    def test_explicit_suggestions_win(self):
+        error = WebInterfaceError(
+            ErrorCode.CONFIG_SAVE_FAILED, "msg", suggested_fixes=["Do the thing"])
+        assert error.suggested_fixes == ["Do the thing"]
+
+    def test_explicit_empty_list_is_respected(self):
+        # Regression: `suggested_fixes or default` treated [] as "unset",
+        # so a caller could not express "I have no suggestions".
+        error = WebInterfaceError(
+            ErrorCode.CONFIG_SAVE_FAILED, "msg", suggested_fixes=[])
+        assert error.suggested_fixes == []
+
+    def test_none_still_gets_defaults(self):
+        error = WebInterfaceError(
+            ErrorCode.CONFIG_SAVE_FAILED, "msg", suggested_fixes=None)
+        assert len(error.suggested_fixes) > 0
+
+
+class TestToDict:
+    def test_base_keys_always_present(self):
+        result = WebInterfaceError(ErrorCode.SYSTEM_ERROR, "boom").to_dict()
+        assert result["status"] == "error"
+        assert result["error_code"] == "SYSTEM_ERROR"
+        assert result["error_category"] == "system"
+        assert result["message"] == "boom"
+
+    def test_details_included_when_set(self):
+        result = WebInterfaceError(
+            ErrorCode.SYSTEM_ERROR, "boom", details="disk full").to_dict()
+        assert result["details"] == "disk full"
+
+    def test_details_omitted_when_absent(self):
+        assert "details" not in WebInterfaceError(ErrorCode.SYSTEM_ERROR, "boom").to_dict()
+
+    def test_context_included_when_non_empty(self):
+        result = WebInterfaceError(
+            ErrorCode.SYSTEM_ERROR, "boom", context={"path": "/tmp/x"}).to_dict()
+        assert result["context"] == {"path": "/tmp/x"}
+
+    def test_empty_context_is_omitted(self):
+        # Pinned as intentional, not a bug: __init__ normalizes context to
+        # {}, and an empty context carries no information, so it is left out
+        # rather than padding every error body with "context": {}.
+        result = WebInterfaceError(ErrorCode.SYSTEM_ERROR, "boom", context={}).to_dict()
+        assert "context" not in result
+
+    def test_empty_suggestions_omitted(self):
+        result = WebInterfaceError(
+            ErrorCode.SYSTEM_ERROR, "boom", suggested_fixes=[]).to_dict()
+        assert "suggested_fixes" not in result
+
+    def test_is_json_serializable(self):
+        import json
+        error = WebInterfaceError(
+            ErrorCode.NETWORK_ERROR, "boom",
+            details="timeout", context={"url": "http://x"})
+        assert json.loads(json.dumps(error.to_dict()))["error_code"] == "NETWORK_ERROR"
+
+
+class TestFromException:
+    @pytest.mark.parametrize("exc_name,expected", [
+        ("ConfigError", ErrorCode.CONFIG_LOAD_FAILED),
+        ("PluginError", ErrorCode.PLUGIN_LOAD_FAILED),
+        ("PermissionError", ErrorCode.PERMISSION_DENIED),
+        ("AccessDenied", ErrorCode.PERMISSION_DENIED),
+        ("ValidationError", ErrorCode.VALIDATION_ERROR),
+        ("SchemaError", ErrorCode.VALIDATION_ERROR),
+        ("NetworkError", ErrorCode.NETWORK_ERROR),
+        ("ConnectionError", ErrorCode.NETWORK_ERROR),
+        ("TimeoutError", ErrorCode.TIMEOUT),
+        ("SomethingElse", ErrorCode.UNKNOWN_ERROR),
+    ])
+    def test_code_inferred_from_exception_class_name(self, exc_name, expected):
+        exc = type(exc_name, (Exception,), {})("boom")
+        assert WebInterfaceError.from_exception(exc).error_code is expected
+
+    def test_explicit_code_skips_inference(self):
+        error = WebInterfaceError.from_exception(
+            ValueError("boom"), error_code=ErrorCode.PLUGIN_NOT_FOUND)
+        assert error.error_code is ErrorCode.PLUGIN_NOT_FOUND
+
+    def test_message_is_the_safe_one_not_the_exception_text(self):
+        # The raw exception text is not echoed into `message`; that field is
+        # a fixed, user-facing string per code.
+        error = WebInterfaceError.from_exception(ValueError("secret-ish detail"))
+        assert error.message == "An unexpected error occurred"
+        assert "secret-ish" not in error.message
+
+    def test_exception_type_recorded_in_context(self):
+        error = WebInterfaceError.from_exception(ValueError("boom"))
+        assert error.context["exception_type"] == "ValueError"
+
+    def test_caller_context_is_preserved_alongside_type(self):
+        error = WebInterfaceError.from_exception(
+            ValueError("boom"), context={"plugin_id": "clock"})
+        assert error.context["plugin_id"] == "clock"
+        assert error.context["exception_type"] == "ValueError"
+
+    def test_caller_supplied_exception_type_is_overwritten(self):
+        error = WebInterfaceError.from_exception(
+            ValueError("boom"), context={"exception_type": "Fake"})
+        assert error.context["exception_type"] == "ValueError"
+
+    def test_original_error_retained(self):
+        exc = ValueError("boom")
+        assert WebInterfaceError.from_exception(exc).original_error is exc
+
+    def test_every_code_has_a_safe_message(self):
+        for code in ErrorCode:
+            assert WebInterfaceError._safe_message(code)
+
+
+class TestExceptionDetails:
+    def test_context_dict_is_flattened(self):
+        exc = ValueError("boom")
+        exc.context = {"config_path": "/etc/x.json", "line": 4}
+        details = WebInterfaceError._get_exception_details(exc)
+        assert "config_path: /etc/x.json" in details
+        assert "line: 4" in details
+        assert "; " in details
+
+    def test_exception_type_key_excluded(self):
+        exc = ValueError("boom")
+        exc.context = {"exception_type": "ValueError", "path": "/tmp/x"}
+        details = WebInterfaceError._get_exception_details(exc)
+        assert "exception_type" not in details
+        assert details == "path: /tmp/x"
+
+    def test_context_with_only_exception_type_gives_none(self):
+        exc = ValueError("boom")
+        exc.context = {"exception_type": "ValueError"}
+        assert WebInterfaceError._get_exception_details(exc) is None
+
+    def test_no_context_attribute_gives_none(self):
+        assert WebInterfaceError._get_exception_details(ValueError("boom")) is None
+
+    def test_non_dict_context_gives_none(self):
+        exc = ValueError("boom")
+        exc.context = "not a dict"
+        assert WebInterfaceError._get_exception_details(exc) is None
+
+    def test_empty_context_gives_none(self):
+        exc = ValueError("boom")
+        exc.context = {}
+        assert WebInterfaceError._get_exception_details(exc) is None
+
+    def test_details_flow_into_from_exception(self):
+        exc = ValueError("boom")
+        exc.context = {"config_path": "/etc/x.json"}
+        assert "config_path" in WebInterfaceError.from_exception(exc).details

test/web_interface/test_validators.py

@@ -0,0 +1,284 @@
+"""
+Tests for src/web_interface/validators.py.
+
+dedup_unique_arrays is already covered by test_dedup_unique_arrays.py and
+is not repeated here; this file covers the other eight functions, none of
+which had any tests.
+
+Regression coverage for three fixed bugs:
+- validate_numeric_range accepted True/False, since bool subclasses int.
+- validate_file_upload lowercased the filename's extension but not the
+  caller's allowed_extensions list, so ['.TTF'] rejected 'font.ttf'.
+- validate_image_url only checked for '..' inside the relative-path
+  branch, so http://host/../secret passed validation untouched.
+"""
+
+import pytest
+
+from src.web_interface.validators import (
+    escape_html,
+    sanitize_plugin_config,
+    validate_file_upload,
+    validate_font_awesome_class,
+    validate_image_url,
+    validate_mime_type,
+    validate_numeric_range,
+    validate_string_length,
+)
+
+
+class TestEscapeHtml:
+    def test_escapes_all_five_entities(self):
+        assert escape_html("""<a href="x">O'Neill & co</a>""") == (
+            "&lt;a href=&quot;x&quot;&gt;O&#x27;Neill &amp; co&lt;/a&gt;")
+
+    def test_ampersand_is_escaped_first_so_nothing_double_escapes(self):
+        # If '<' were replaced before '&', the '&' of '&lt;' would be
+        # escaped again into '&amp;lt;'.
+        assert escape_html("<") == "&lt;"
+        assert escape_html("&") == "&amp;"
+        assert escape_html("&<") == "&amp;&lt;"
+
+    def test_plain_text_unchanged(self):
+        assert escape_html("hello world") == "hello world"
+
+    def test_non_string_is_coerced(self):
+        assert escape_html(42) == "42"
+        assert escape_html(None) == "None"
+
+    def test_script_tag_neutralized(self):
+        assert "<script>" not in escape_html("<script>alert(1)</script>")
+
+
+class TestValidateImageUrl:
+    @pytest.mark.parametrize("url", [
+        "javascript:alert(1)",
+        "JavaScript:alert(1)",
+        "JAVASCRIPT:alert(1)",
+        "data:text/html;base64,PHNjcmlwdD4=",
+        "vbscript:msgbox(1)",
+        "file:///etc/passwd",
+    ])
+    def test_dangerous_protocols_rejected(self, url):
+        valid, error = validate_image_url(url)
+        assert valid is False and "protocol" in error.lower()
+
+    @pytest.mark.parametrize("url", [
+        "http://x/a.png?onerror=alert(1)",
+        "http://x/a.png#onload=alert(1)",
+        "http://x/onclick=alert(1).png",
+    ])
+    def test_event_handlers_rejected(self, url):
+        valid, error = validate_image_url(url)
+        assert valid is False and "Event handlers" in error
+
+    @pytest.mark.parametrize("url", ["", None, 123, []])
+    def test_empty_or_non_string_rejected(self, url):
+        assert validate_image_url(url)[0] is False
+
+    def test_http_and_https_allowed(self):
+        assert validate_image_url("http://example.com/logo.png") == (True, None)
+        assert validate_image_url("https://example.com/logo.png") == (True, None)
+
+    def test_other_schemes_rejected(self):
+        valid, error = validate_image_url("ftp://example.com/logo.png")
+        assert valid is False and "http://" in error
+
+    def test_relative_path_allowed(self):
+        assert validate_image_url("/static/logo.png") == (True, None)
+
+    def test_protocol_relative_url_rejected(self):
+        assert validate_image_url("//evil.com/logo.png")[0] is False
+
+    def test_relative_traversal_rejected(self):
+        assert validate_image_url("/static/../../etc/passwd")[0] is False
+
+    def test_absolute_url_traversal_rejected(self):
+        # Regression: the '..' check used to sit inside the leading-slash
+        # branch, so an absolute URL skipped it entirely.
+        valid, error = validate_image_url("http://example.com/../secret")
+        assert valid is False and "traversal" in error.lower()
+
+    def test_bare_traversal_rejected(self):
+        assert validate_image_url("../../etc/passwd")[0] is False
+
+
+class TestValidateFontAwesomeClass:
+    @pytest.mark.parametrize("cls", ["fa-star", "fas fa-star", "fa-solid fa-house"])
+    def test_valid_classes_accepted(self, cls):
+        assert validate_font_awesome_class(cls) == (True, None)
+
+    @pytest.mark.parametrize("cls", ["star", "glyphicon-star", ""])
+    def test_classes_without_fa_prefix_rejected(self, cls):
+        assert validate_font_awesome_class(cls)[0] is False
+
+    def test_injection_attempt_rejected(self):
+        assert validate_font_awesome_class('fa-star" onload="alert(1)')[0] is False
+
+    def test_angle_brackets_rejected(self):
+        assert validate_font_awesome_class("<script>fa-star</script>")[0] is False
+
+    def test_non_string_rejected(self):
+        valid, error = validate_font_awesome_class(None)
+        assert valid is False and "string" in error
+
+    def test_explicit_fa_check_is_unreachable_but_harmless(self):
+        # Characterized, not fixed: the regex already requires 'fa-', so the
+        # follow-up `if 'fa-' not in class_name` can never fire. Anything
+        # lacking 'fa-' is rejected by the pattern first, with the pattern's
+        # own message.
+        valid, error = validate_font_awesome_class("star")
+        assert valid is False
+        assert error == "Invalid Font Awesome class name format"
+
+
+class TestValidateFileUpload:
+    def test_plain_filename_accepted(self):
+        assert validate_file_upload("logo.png") == (True, None)
+
+    @pytest.mark.parametrize("filename", [
+        "../etc/passwd", "dir/file.png", "dir\\file.png", "..\\..\\secrets",
+    ])
+    def test_traversal_characters_rejected(self, filename):
+        valid, error = validate_file_upload(filename)
+        assert valid is False and "invalid characters" in error
+
+    @pytest.mark.parametrize("filename", ["", None, 123])
+    def test_empty_or_non_string_rejected(self, filename):
+        assert validate_file_upload(filename)[0] is False
+
+    def test_allowed_extension_accepted(self):
+        assert validate_file_upload("font.ttf", allowed_extensions=[".ttf", ".otf"]) == (True, None)
+
+    def test_disallowed_extension_rejected(self):
+        valid, error = validate_file_upload("evil.exe", allowed_extensions=[".ttf"])
+        assert valid is False and "extension" in error
+
+    def test_uppercase_filename_extension_matches(self):
+        assert validate_file_upload("FONT.TTF", allowed_extensions=[".ttf"]) == (True, None)
+
+    def test_uppercase_allowed_list_matches(self):
+        # Regression: only the filename side was lowercased, so a caller
+        # passing ['.TTF'] rejected every valid .ttf upload.
+        assert validate_file_upload("font.ttf", allowed_extensions=[".TTF"]) == (True, None)
+
+    def test_no_extension_list_skips_the_check(self):
+        assert validate_file_upload("anything.xyz") == (True, None)
+
+
+class TestValidateMimeType:
+    def test_known_type_accepted(self):
+        assert validate_mime_type("logo.png", ["image/png"]) == (True, None)
+
+    def test_mismatched_type_rejected(self):
+        valid, error = validate_mime_type("logo.png", ["image/jpeg"])
+        assert valid is False and "not allowed" in error
+
+    def test_undeterminable_type_rejected(self):
+        valid, error = validate_mime_type("mystery.zzz", ["image/png"])
+        assert valid is False and "Could not determine" in error
+
+    def test_guess_type_failure_is_caught(self, monkeypatch):
+        import mimetypes
+        monkeypatch.setattr(mimetypes, "guess_type",
+                            lambda *a, **kw: (_ for _ in ()).throw(RuntimeError("boom")))
+        valid, error = validate_mime_type("logo.png", ["image/png"])
+        assert valid is False and "Error validating MIME type" in error
+
+
+class TestValidateNumericRange:
+    def test_value_in_range(self):
+        assert validate_numeric_range(5, min_val=0, max_val=10) == (True, None)
+
+    def test_boundaries_are_inclusive(self):
+        assert validate_numeric_range(0, min_val=0, max_val=10) == (True, None)
+        assert validate_numeric_range(10, min_val=0, max_val=10) == (True, None)
+
+    def test_below_minimum_rejected(self):
+        valid, error = validate_numeric_range(-1, min_val=0)
+        assert valid is False and "at least" in error
+
+    def test_above_maximum_rejected(self):
+        valid, error = validate_numeric_range(11, max_val=10)
+        assert valid is False and "at most" in error
+
+    def test_floats_accepted(self):
+        assert validate_numeric_range(2.5, min_val=0, max_val=10) == (True, None)
+
+    def test_no_bounds_accepts_any_number(self):
+        assert validate_numeric_range(-9999) == (True, None)
+
+    @pytest.mark.parametrize("value", ["5", None, [], {}])
+    def test_non_numeric_rejected(self, value):
+        valid, error = validate_numeric_range(value, min_val=0, max_val=10)
+        assert valid is False and error == "Value must be a number"
+
+    @pytest.mark.parametrize("value", [True, False])
+    def test_booleans_rejected(self, value):
+        # Regression: bool subclasses int, so True passed the isinstance
+        # check and then compared as 1 against the range.
+        valid, error = validate_numeric_range(value, min_val=0, max_val=10)
+        assert valid is False and error == "Value must be a number"
+
+
+class TestValidateStringLength:
+    def test_within_range(self):
+        assert validate_string_length("hello", min_length=1, max_length=10) == (True, None)
+
+    def test_boundaries_are_inclusive(self):
+        assert validate_string_length("abc", min_length=3, max_length=3) == (True, None)
+
+    def test_too_short_rejected(self):
+        valid, error = validate_string_length("", min_length=1)
+        assert valid is False and "at least" in error
+
+    def test_too_long_rejected(self):
+        valid, error = validate_string_length("abcdef", max_length=3)
+        assert valid is False and "at most" in error
+
+    def test_non_string_rejected(self):
+        valid, error = validate_string_length(123, max_length=10)
+        assert valid is False and "must be a string" in error
+
+    def test_no_bounds_accepts_anything(self):
+        assert validate_string_length("") == (True, None)
+
+
+class TestSanitizePluginConfig:
+    def test_valid_keys_and_scalars_kept(self):
+        config = {"enabled": True, "count": 3, "ratio": 1.5, "name": "clock"}
+        assert sanitize_plugin_config(config) == config
+
+    @pytest.mark.parametrize("key", ["has space", "has-dash", "has.dot", "has/slash", ""])
+    def test_invalid_key_names_dropped(self, key):
+        assert sanitize_plugin_config({key: "value", "good": 1}) == {"good": 1}
+
+    def test_non_string_keys_dropped(self):
+        assert sanitize_plugin_config({1: "a", "good": 2}) == {"good": 2}
+
+    def test_nested_dicts_recursed(self):
+        result = sanitize_plugin_config({"outer": {"inner": 1, "bad key": 2}})
+        assert result == {"outer": {"inner": 1}}
+
+    def test_list_of_scalars_preserved(self):
+        assert sanitize_plugin_config({"teams": ["PHI", "NYG"]})["teams"] == ["PHI", "NYG"]
+
+    def test_list_of_dicts_recursed(self):
+        result = sanitize_plugin_config({"items": [{"ok": 1, "bad key": 2}]})
+        assert result["items"] == [{"ok": 1}]
+
+    def test_unknown_value_types_dropped(self):
+        assert sanitize_plugin_config({"weird": {1, 2, 3}, "good": 1}) == {"good": 1}
+
+    def test_none_values_dropped(self):
+        assert sanitize_plugin_config({"nothing": None, "good": 1}) == {"good": 1}
+
+    def test_strings_are_not_html_escaped(self):
+        # Pinned, not a bug: escaping here would persist the escaped form in
+        # config.json. Output escaping belongs to the template layer, which
+        # the function's docstring now says explicitly.
+        payload = "<script>alert(1)</script>"
+        assert sanitize_plugin_config({"title": payload})["title"] == payload
+
+    def test_empty_config(self):
+        assert sanitize_plugin_config({}) == {}

web_interface/blueprints/api_v3.py

@@ -22,7 +22,7 @@ logger = logging.getLogger(__name__)
 from src.web_interface.api_helpers import success_response, error_response, validate_request_json
 from src.web_interface.errors import ErrorCode
 from src.web_interface.secret_helpers import find_secret_fields, separate_secrets
-from src.web_interface.error_handler import describe_exception, redact_text
+from src.web_interface.error_handler import describe_exception
 from src.plugin_system.operation_types import OperationType
 from src.web_interface.validators import (
     validate_file_upload
@@ -328,7 +328,7 @@ def save_schedule_config():
         if not api_v3.config_manager:
             return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
@@ -536,7 +536,7 @@ def save_dim_schedule_config():
         if not api_v3.config_manager:
             return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
@@ -796,7 +796,7 @@ def save_main_config():
                          'gpio_slowdown', 'rp1_rio', 'scan_mode', 'disable_hardware_pulsing', 'inverse_colors', 'show_refresh_rate',
                          'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz', 'use_short_date_format',
                          'max_dynamic_duration_seconds', 'led_rgb_sequence', 'multiplexing', 'panel_type',
-                         'row_address_type', 'pixel_mapper_config']
+                         'row_address_type', 'pixel_mapper_config', 'orientation']
 
         if any(k in data for k in display_fields):
             if 'display' not in current_config:
@@ -831,6 +831,11 @@ def save_main_config():
             if 'pixel_mapper_config' in data and not isinstance(data['pixel_mapper_config'], str):
                 return jsonify({'status': 'error', 'message': 'pixel_mapper_config must be a string (e.g. "U-mapper;Rotate:90" or empty)'}), 400
 
+            # Validate orientation (physical mounting rotation; composed onto pixel_mapper_config at runtime)
+            ORIENTATION_ALLOWED = {'normal', '180'}
+            if 'orientation' in data and data['orientation'] not in ORIENTATION_ALLOWED:
+                return jsonify({'status': 'error', 'message': f"Invalid orientation '{data['orientation']}'. Allowed values: {', '.join(sorted(ORIENTATION_ALLOWED))}"}), 400
+
             # Validate row_address_type
             if 'row_address_type' in data:
                 try:
@@ -844,7 +849,7 @@ def save_main_config():
             for field in ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'hardware_mapping', 'scan_mode',
                          'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz',
                          'led_rgb_sequence', 'multiplexing', 'panel_type', 'row_address_type',
-                         'pixel_mapper_config']:
+                         'pixel_mapper_config', 'orientation']:
                 if field in data:
                     if field in ['rows', 'cols', 'chain_length', 'parallel', 'brightness', 'scan_mode',
                                'pwm_bits', 'pwm_dither_bits', 'pwm_lsb_nanoseconds', 'limit_refresh_rate_hz',
@@ -1340,7 +1345,7 @@ def save_raw_main_config():
         if not api_v3.config_manager:
             return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
@@ -1386,7 +1391,7 @@ def save_raw_secrets_config():
         if not api_v3.config_manager:
             return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
@@ -2406,7 +2411,7 @@ def get_on_demand_status():
 def start_on_demand_display():
     """Request the display controller to run a specific plugin on-demand."""
     try:
-        data = request.get_json() or {}
+        data = request.get_json(silent=True) or {}
         plugin_id = data.get('plugin_id')
         mode = data.get('mode')
         duration = data.get('duration')
@@ -2930,7 +2935,7 @@ def manage_plugin_limits(plugin_id):
                 })
         else:
             # POST - Set limits
-            data = request.get_json() or {}
+            data = request.get_json(silent=True) or {}
             from src.plugin_system.resource_monitor import ResourceLimits
 
             limits = ResourceLimits(
@@ -2961,7 +2966,7 @@ def toggle_plugin():
         content_type = request.content_type or ''
 
         if 'application/json' in content_type:
-            data = request.get_json()
+            data = request.get_json(silent=True)
             if not data or 'plugin_id' not in data or 'enabled' not in data:
                 return jsonify({'status': 'error', 'message': 'plugin_id and enabled required'}), 400
             plugin_id = data['plugin_id']
@@ -3832,7 +3837,7 @@ def install_plugin():
         if not api_v3.plugin_store_manager:
             return jsonify({'status': 'error', 'message': 'Plugin store manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data or 'plugin_id' not in data:
             return jsonify({'status': 'error', 'message': 'plugin_id required'}), 400
 
@@ -3966,7 +3971,7 @@ def install_plugin_from_url():
         if not api_v3.plugin_store_manager:
             return jsonify({'status': 'error', 'message': 'Plugin store manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data or 'repo_url' not in data:
             return jsonify({'status': 'error', 'message': 'repo_url required'}), 400
 
@@ -4021,7 +4026,7 @@ def get_registry_from_url():
         if not api_v3.plugin_store_manager:
             return jsonify({'status': 'error', 'message': 'Plugin store manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data or 'repo_url' not in data:
             return jsonify({'status': 'error', 'message': 'repo_url required'}), 400
 
@@ -4066,7 +4071,7 @@ def add_saved_repository():
         if not api_v3.saved_repositories_manager:
             return jsonify({'status': 'error', 'message': 'Saved repositories manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data or 'repo_url' not in data:
             return jsonify({'status': 'error', 'message': 'repo_url required'}), 400
 
@@ -4097,7 +4102,7 @@ def remove_saved_repository():
         if not api_v3.saved_repositories_manager:
             return jsonify({'status': 'error', 'message': 'Saved repositories manager not initialized'}), 500
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data or 'repo_url' not in data:
             return jsonify({'status': 'error', 'message': 'repo_url required'}), 400
 
@@ -4231,7 +4236,7 @@ def refresh_plugin_store():
         if not api_v3.plugin_store_manager:
             return jsonify({'status': 'error', 'message': 'Plugin store manager not initialized'}), 500
 
-        data = request.get_json() or {}
+        data = request.get_json(silent=True) or {}
         fetch_commit_info = data.get('fetch_commit_info', data.get('fetch_latest_versions', False))
 
         # Force refresh the registry
@@ -5817,7 +5822,7 @@ def reset_plugin_config():
         if not api_v3.config_manager:
             return jsonify({'status': 'error', 'message': 'Config manager not initialized'}), 500
 
-        data = request.get_json() or {}
+        data = request.get_json(silent=True) or {}
         plugin_id = data.get('plugin_id')
         preserve_secrets = data.get('preserve_secrets', True)
 
@@ -6204,7 +6209,7 @@ sys.exit(proc.returncode)
 def authenticate_spotify():
     """Run Spotify authentication script"""
     try:
-        data = request.get_json() or {}
+        data = request.get_json(silent=True) or {}
         redirect_url = data.get('redirect_url', '').strip()
 
         # Get plugin directory
@@ -6267,7 +6272,6 @@ sys.exit(proc.returncode)
                     timeout=120,
                     env=env
                 )
-                os.unlink(wrapper_path)
 
                 if result.returncode == 0:
                     return jsonify({
@@ -6282,9 +6286,13 @@ sys.exit(proc.returncode)
                         'output': result.stdout + result.stderr
                     }), 400
             except subprocess.TimeoutExpired:
+                return jsonify({'status': 'error', 'message': 'Authentication timed out'}), 408
+            finally:
+                # The wrapper carries the user's redirect URL, so it must not
+                # survive the request on any path — including a failure to
+                # launch, which the previous per-branch unlinks missed.
                 if os.path.exists(wrapper_path):
                     os.unlink(wrapper_path)
-                return jsonify({'status': 'error', 'message': 'Authentication timed out'}), 408
         else:
             # Step 1: Get authorization URL
             # Import the script's functions directly to get the auth URL
@@ -6521,7 +6529,7 @@ def get_fonts_overrides():
 def save_fonts_overrides():
     """Save font overrides"""
     try:
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data:
             return jsonify({'status': 'error', 'message': 'No data provided'}), 400
 
@@ -7141,7 +7149,7 @@ def upload_of_the_day_json():
 def delete_of_the_day_json():
     """Delete a JSON file from of-the-day plugin"""
     try:
-        data = request.get_json() or {}
+        data = request.get_json(silent=True) or {}
         file_id = data.get('file_id')  # This is the category_name
 
         if not file_id:
@@ -7231,6 +7239,29 @@ def serve_plugin_static(plugin_id, file_path):
         return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details', 'details': describe_exception(e)}), 500
 
 
+_MAX_CREDENTIAL_BACKUPS = 5
+
+
+def _prune_credential_backups(plugin_dir: Path) -> None:
+    """Keep only the newest _MAX_CREDENTIAL_BACKUPS credential backups.
+
+    Every re-upload copies the previous credentials.json aside. Without
+    pruning those accumulate for the life of the install — each one a
+    complete set of OAuth client credentials sitting in the plugin
+    directory.
+    """
+    backups = sorted(
+        plugin_dir.glob('credentials.json.backup.*'),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    for stale in backups[_MAX_CREDENTIAL_BACKUPS:]:
+        try:
+            stale.unlink()
+        except OSError:
+            logger.warning("Could not remove old credential backup %s", stale.name)
+
+
 @api_v3.route('/plugins/calendar/upload-credentials', methods=['POST'])
 def upload_calendar_credentials():
     """Upload credentials.json file for calendar plugin"""
@@ -7262,20 +7293,25 @@ def upload_calendar_credentials():
         except json.JSONDecodeError:
             return jsonify({'status': 'error', 'message': 'File is not valid JSON'}), 400
 
-        # Validate it looks like Google OAuth credentials
+        # Validate it looks like Google OAuth credentials. The content
+        # already parsed as JSON above, so anything raising here means it is
+        # not credentials-shaped — a bare scalar, for instance, where the
+        # membership test raises TypeError. Reject rather than swallow: a
+        # file saved as credentials.json but not usable as credentials only
+        # fails later, somewhere less obvious.
         try:
             file.seek(0)
             creds_data = json.loads(file.read())
             file.seek(0)
-
-            # Check for required Google OAuth fields
-            if 'installed' not in creds_data and 'web' not in creds_data:
-                return jsonify({
-                    'status': 'error',
-                    'message': 'File does not appear to be a valid Google OAuth credentials file'
-                }), 400
+            is_oauth_shaped = 'installed' in creds_data or 'web' in creds_data
         except Exception:
-            pass  # Continue even if validation fails
+            is_oauth_shaped = False
+
+        if not is_oauth_shaped:
+            return jsonify({
+                'status': 'error',
+                'message': 'File does not appear to be a valid Google OAuth credentials file'
+            }), 400
 
         # Get plugin directory
         plugin_id = 'calendar'
@@ -7295,6 +7331,7 @@ def upload_calendar_credentials():
             backup_path = Path(plugin_dir) / f'credentials.json.backup.{int(time.time())}'
             import shutil
             shutil.copy2(credentials_path, backup_path)
+            _prune_credential_backups(Path(plugin_dir))
 
         # Save new file
         file.save(str(credentials_path))
@@ -7312,222 +7349,6 @@ def upload_calendar_credentials():
         logger.error('Error in upload_calendar_credentials', exc_info=True)
         return jsonify({'status': 'error', 'message': 'An error occurred; see logs for details', 'details': describe_exception(e)}), 500
 
-# calendarList.list pages at 250 entries maximum. Ten pages is far past any
-# real account and exists only so a malformed nextPageToken cannot spin here.
-_CALENDAR_LIST_MAX_PAGES = 10
-
-
-def _calendar_plugin_dir() -> Optional[Path]:
-    """Where the calendar plugin is installed, or None if it is not."""
-    if api_v3.plugin_manager:
-        plugin_dir = api_v3.plugin_manager.get_plugin_directory('calendar')
-    else:
-        plugin_dir = PROJECT_ROOT / 'plugins' / 'calendar'
-    if not plugin_dir:
-        return None
-    plugin_dir = Path(plugin_dir)
-    return plugin_dir if plugin_dir.exists() else None
-
-
-def _run_calendar_registration(plugin_dir: Path, stdin_payload: str):
-    """Run the plugin's OAuth script and return the JSON object it prints.
-
-    The script decides between web and terminal mode by whether stdin is a
-    tty, so it must be given a pipe. It emits one JSON object on stdout; the
-    last parsable line is taken, because an import warning or a library's
-    stderr redirection can land in front of it.
-
-    Returns (payload, error_message). Exactly one is None.
-    """
-    script = plugin_dir / 'calendar_registration.py'
-    if not script.exists():
-        return None, 'Authentication script not found in the calendar plugin'
-
-    try:
-        result = subprocess.run(  # nosec B603 - fixed script path inside the plugin dir
-            [sys.executable, str(script)],
-            input=stdin_payload,
-            capture_output=True,
-            text=True,
-            timeout=120,
-            cwd=str(plugin_dir),
-        )
-    except subprocess.TimeoutExpired:
-        return None, 'Authentication timed out after 120s'
-    except OSError as e:
-        return None, 'Could not run the authentication script: %s' % e
-
-    for line in reversed((result.stdout or '').splitlines()):
-        line = line.strip()
-        if not line:
-            continue
-        try:
-            payload = json.loads(line)
-        except json.JSONDecodeError:
-            continue
-        if isinstance(payload, dict):
-            return payload, None
-
-    raw = (result.stderr or result.stdout or '').strip()
-    # The unredacted text goes to the log, where it is worth having in full.
-    # What comes back over HTTP is redacted: this is a script that handles
-    # OAuth client secrets, and its stderr can quote them.
-    if raw:
-        logger.error('calendar_registration.py failed (exit %s): %s',
-                     result.returncode, raw)
-    return None, 'Authentication script produced no result%s' % (
-        ': %s' % redact_text(raw) if raw else '')
-
-
-@api_v3.route('/plugins/calendar/authenticate', methods=['POST'])
-def authenticate_calendar():
-    """Google OAuth for the calendar plugin, in the two steps it requires.
-
-    Step 1 (no body) returns the consent URL to open. Step 2 posts back the
-    URL Google redirected to -- it fails to load, because the redirect points
-    at a loopback address nothing is listening on, but the address bar carries
-    the authorization code -- and the script exchanges it for a token.
-
-    Two calls rather than one because the user has to visit Google in between.
-    The script persists the PKCE verifier from step 1 for step 2 to reuse; the
-    exchange fails with "Missing code verifier" otherwise.
-    """
-    try:
-        plugin_dir = _calendar_plugin_dir()
-        if plugin_dir is None:
-            return jsonify({
-                'status': 'error',
-                'message': 'The calendar plugin is not installed'
-            }), 404
-
-        if not (plugin_dir / 'credentials.json').exists():
-            return jsonify({
-                'status': 'error',
-                'message': ('No credentials.json yet. Upload your Google OAuth '
-                            'client file first (Step 1).')
-            }), 400
-
-        data = request.get_json(silent=True) or {}
-        redirect_url = (data.get('redirect_url') or data.get('code') or '').strip()
-
-        payload, error = _run_calendar_registration(plugin_dir, redirect_url)
-        if error:
-            return jsonify({'status': 'error', 'message': error}), 500
-        if payload.get('status') != 'success':
-            # The script's own diagnosis is more useful than anything that
-            # could be reconstructed here -- but it interpolates exceptions
-            # into its messages, so it reaches the client redacted and the
-            # original goes to the log.
-            logger.error('calendar authentication failed: %s', payload)
-            safe = dict(payload)
-            safe['message'] = redact_text(str(payload.get('message', '')
-                                              or 'Authentication failed'))
-            return jsonify(safe), 400
-        return jsonify(payload)
-
-    except Exception as e:
-        logger.error('Error in authenticate_calendar', exc_info=True)
-        return jsonify({'status': 'error',
-                        'message': 'An error occurred; see logs for details',
-                        'details': describe_exception(e)}), 500
-
-
-@api_v3.route('/plugins/calendar/list-calendars', methods=['GET'])
-def list_calendar_calendars():
-    """The calendars this account can see, for the config picker.
-
-    Reads the token the OAuth flow wrote rather than shelling out again: the
-    picker is used interactively and a subprocess per click is slower than the
-    API call it would be wrapping.
-    """
-    try:
-        plugin_dir = _calendar_plugin_dir()
-        if plugin_dir is None:
-            return jsonify({
-                'status': 'error',
-                'message': 'The calendar plugin is not installed'
-            }), 404
-
-        token_file = plugin_dir / 'token.pickle'
-        if not token_file.exists():
-            return jsonify({
-                'status': 'error',
-                'message': ('Not authenticated with Google yet. Complete Step 2 '
-                            'first, then load your calendars.')
-            }), 400
-
-        try:
-            import pickle
-            from google.auth.transport.requests import Request as GoogleRequest
-            from googleapiclient.discovery import build as build_google_service
-        except ImportError as e:
-            return jsonify({
-                'status': 'error',
-                'message': ('The Google API libraries are not installed. Install '
-                            "the calendar plugin's requirements.txt. (%s)" % e)
-            }), 500
-
-        with open(token_file, 'rb') as handle:
-            # Written only by this plugin's own OAuth flow, into its own
-            # directory, and read here exactly as the plugin itself reads it.
-            creds = pickle.load(handle)  # nosec B301 - locally generated token
-
-        if creds and creds.expired and creds.refresh_token:
-            creds.refresh(GoogleRequest())
-            with open(token_file, 'wb') as handle:
-                pickle.dump(creds, handle)
-            os.chmod(token_file, 0o600)
-
-        if not creds or not creds.valid:
-            return jsonify({
-                'status': 'error',
-                'message': ('Stored Google credentials are no longer valid. '
-                            'Run Step 2 again to re-authenticate.')
-            }), 400
-
-        service = build_google_service('calendar', 'v3', credentials=creds)
-
-        # calendarList.list returns 100 entries per page by default and caps at
-        # 250, handing back a nextPageToken when there are more. Taking only
-        # the first page would silently hide calendars from the picker, and the
-        # user would have no way to tell the list was truncated.
-        entries = []
-        page_token = None
-        for _ in range(_CALENDAR_LIST_MAX_PAGES):
-            response = service.calendarList().list(
-                maxResults=250, pageToken=page_token).execute()
-            entries.extend(response.get('items', []))
-            page_token = response.get('nextPageToken')
-            if not page_token:
-                break
-        else:
-            # 2500 calendars in, something is wrong with the account or the
-            # token is looping; show what was collected rather than spin.
-            logger.warning(
-                'calendarList paging stopped at %d pages with more remaining',
-                _CALENDAR_LIST_MAX_PAGES)
-
-        calendars = [{
-            'id': entry.get('id'),
-            # The picker labels each row with summary and falls back to the id
-            # only in its own display, so send something either way.
-            'summary': entry.get('summary') or entry.get('id'),
-            'primary': bool(entry.get('primary', False)),
-        } for entry in entries if entry.get('id')]
-
-        # Primary first, then alphabetically: the list is usually short but the
-        # one the user wants is almost always their own calendar.
-        calendars.sort(key=lambda c: (not c['primary'], c['summary'].lower()))
-
-        return jsonify({'status': 'success', 'calendars': calendars})
-
-    except Exception as e:
-        logger.error('Error in list_calendar_calendars', exc_info=True)
-        return jsonify({'status': 'error',
-                        'message': 'An error occurred; see logs for details',
-                        'details': describe_exception(e)}), 500
-
-
 @api_v3.route('/plugins/assets/delete', methods=['POST'])
 def delete_plugin_asset():
     """Delete an asset file for a plugin"""
@@ -7814,7 +7635,7 @@ def connect_wifi():
     try:
         from src.wifi_manager import WiFiManager
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data:
             return jsonify({
                 'status': 'error',
@@ -7968,7 +7789,7 @@ def set_auto_enable_ap_mode():
     try:
         from src.wifi_manager import WiFiManager
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if data is None or 'auto_enable_ap_mode' not in data:
             return jsonify({
                 'status': 'error',
@@ -8097,7 +7918,7 @@ def delete_cache_file():
             from src.cache_manager import CacheManager
             api_v3.cache_manager = CacheManager()
 
-        data = request.get_json()
+        data = request.get_json(silent=True)
         if not data or 'key' not in data:
             return jsonify({'status': 'error', 'message': 'cache key is required'}), 400
 
@@ -8360,7 +8181,16 @@ def backup_restore():
         try:
             opts_dict = json.loads(options_raw)
         except json.JSONDecodeError:
-            opts_dict = {}
+            opts_dict = None
+        if not isinstance(opts_dict, dict):
+            # Every option defaults to True, so falling back to {} on a
+            # parse failure would silently perform a FULL restore —
+            # secrets and all — for a caller who asked for a narrow one
+            # and mis-serialized it. Refuse instead of guessing.
+            return jsonify({
+                'status': 'error',
+                'message': 'Invalid options: expected a JSON object',
+            }), 400
         options = RestoreOptions(
             restore_config=bool(opts_dict.get('restore_config', True)),
             restore_secrets=bool(opts_dict.get('restore_secrets', True)),

web_interface/static/v3/js/widgets/google-oauth.js

@@ -1,184 +0,0 @@
-/**
- * Google OAuth Widget
- *
- * Step 2 of the calendar plugin's setup, between uploading the OAuth client
- * file and picking calendars. Google will not let a headless device complete
- * consent on its own, so the flow is necessarily two calls with a human in
- * between:
- *
- *   1. POST /api/v3/plugins/calendar/authenticate with no body
- *      -> { auth_url } to open in a browser
- *   2. the browser lands on a loopback address that fails to load; its URL
- *      carries the authorization code. POST it back as redirect_url
- *      -> the server exchanges it and writes token.pickle
- *
- * The failed page in step 2 is expected and is worth saying out loud, because
- * it looks exactly like something went wrong.
- *
- * @module GoogleOAuthWidget
- */
-
-(function () {
-    'use strict';
-
-    if (typeof window.LEDMatrixWidgets === 'undefined') {
-        console.error('[GoogleOAuthWidget] LEDMatrixWidgets registry not found. Load registry.js first.');
-        return;
-    }
-
-    const ENDPOINT = '/api/v3/plugins/calendar/authenticate';
-
-    window.LEDMatrixWidgets.register('google-oauth', {
-        name: 'Google OAuth Widget',
-        version: '1.0.0',
-
-        /**
-         * @param {HTMLElement} container
-         * @param {Object} config  - schema config (unused)
-         * @param {*}      value   - unused; this widget stores nothing
-         * @param {Object} options - { fieldId, pluginId, name }
-         */
-        render: function (container, config, value, options) {
-            const fieldId = options.fieldId;
-
-            // Nothing is stored in config by this step -- the result is
-            // token.pickle on the device -- but the form still expects a field.
-            const hidden = document.createElement('input');
-            hidden.type = 'hidden';
-            hidden.id = fieldId + '_hidden';
-            hidden.name = options.name;
-            hidden.value = value || '';
-
-            const startBtn = document.createElement('button');
-            startBtn.type = 'button';
-            startBtn.className = 'px-3 py-1.5 text-sm rounded-md bg-blue-600 hover:bg-blue-700 text-white';
-            startBtn.innerHTML = '<i class="fas fa-key"></i> Connect Google Account';
-
-            const status = document.createElement('p');
-            status.className = 'text-xs text-gray-400 mt-2';
-
-            const step2 = document.createElement('div');
-            step2.className = 'mt-3 hidden';
-
-            const link = document.createElement('a');
-            link.target = '_blank';
-            link.rel = 'noopener noreferrer';
-            link.className = 'text-blue-400 underline text-sm break-all';
-            link.textContent = 'Open the Google consent screen';
-
-            // Deliberately loud. After consent the browser is redirected to a
-            // loopback address nothing is listening on, so it lands on a
-            // browser error page -- which reads as a failure at exactly the
-            // moment the user has to act on it. Said quietly in grey it gets
-            // missed, and the flow looks broken when it is working.
-            const hint = document.createElement('div');
-            hint.className =
-                'mt-3 p-3 rounded-md border border-amber-500/60 bg-amber-500/10';
-            hint.innerHTML =
-                '<p class="text-sm text-amber-300 font-semibold">'
-                + '<i class="fas fa-triangle-exclamation"></i> '
-                + 'The next page will fail to load. That is expected.</p>'
-                + '<p class="text-xs text-amber-200/90 mt-1">'
-                + 'After you approve access, Google sends your browser to '
-                + '<code>127.0.0.1</code>, where nothing is running \u2014 so you will see '
-                + '"This site can\u2019t be reached" or similar. Nothing has gone wrong. '
-                + 'Copy the <strong>entire address</strong> out of the address bar '
-                + '(it contains <code>?code=...</code>) and paste it in the box below.</p>';
-
-            const codeLabel = document.createElement('label');
-            codeLabel.className = 'block text-xs text-gray-300 mt-3';
-            codeLabel.textContent = 'Paste the address from that failed page here:';
-
-            const codeInput = document.createElement('input');
-            codeInput.type = 'text';
-            codeInput.placeholder = 'http://127.0.0.1/?code=...';
-            codeInput.className =
-                'mt-2 block w-full px-3 py-2 text-sm border border-gray-600 '
-                + 'rounded-md bg-gray-800 text-gray-100';
-
-            const finishBtn = document.createElement('button');
-            finishBtn.type = 'button';
-            finishBtn.className = 'mt-2 px-3 py-1.5 text-sm rounded-md bg-green-600 hover:bg-green-700 text-white';
-            finishBtn.innerHTML = '<i class="fas fa-check"></i> Finish Authentication';
-
-            function say(message, kind) {
-                status.textContent = message;
-                status.className = 'text-xs mt-2 ' + (
-                    kind === 'error' ? 'text-red-400'
-                        : kind === 'success' ? 'text-green-400'
-                            : 'text-gray-400');
-            }
-
-            function post(body) {
-                return fetch(ENDPOINT, {
-                    method: 'POST',
-                    headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify(body || {})
-                }).then(function (r) {
-                    return r.json().catch(function () {
-                        // A non-JSON body here means the request never reached
-                        // the handler -- worth saying so rather than "undefined".
-                        return { status: 'error', message: 'Server returned ' + r.status };
-                    });
-                });
-            }
-
-            startBtn.addEventListener('click', function () {
-                startBtn.disabled = true;
-                say('Requesting a consent link...');
-                post({}).then(function (data) {
-                    startBtn.disabled = false;
-                    if (data.status !== 'success' || !data.auth_url) {
-                        say(data.message || 'Could not start authentication.', 'error');
-                        return;
-                    }
-                    link.href = data.auth_url;
-                    step2.classList.remove('hidden');
-                    say(data.message || 'Open the link, approve, then paste the address back.');
-                }).catch(function (err) {
-                    startBtn.disabled = false;
-                    say('Request failed: ' + err.message, 'error');
-                });
-            });
-
-            finishBtn.addEventListener('click', function () {
-                const pasted = codeInput.value.trim();
-                if (!pasted) {
-                    say('Paste the address your browser was redirected to.', 'error');
-                    return;
-                }
-                finishBtn.disabled = true;
-                say('Exchanging the code with Google...');
-                post({ redirect_url: pasted }).then(function (data) {
-                    finishBtn.disabled = false;
-                    if (data.status !== 'success') {
-                        say(data.message || 'Authentication failed.', 'error');
-                        return;
-                    }
-                    say(data.message || 'Authenticated.', 'success');
-                    step2.classList.add('hidden');
-                    codeInput.value = '';
-                }).catch(function (err) {
-                    finishBtn.disabled = false;
-                    say('Request failed: ' + err.message, 'error');
-                });
-            });
-
-            step2.appendChild(link);
-            step2.appendChild(hint);
-            step2.appendChild(codeLabel);
-            step2.appendChild(codeInput);
-            step2.appendChild(finishBtn);
-
-            container.appendChild(hidden);
-            container.appendChild(startBtn);
-            container.appendChild(status);
-            container.appendChild(step2);
-        },
-
-        getValue: function (fieldId) {
-            const hidden = document.getElementById(fieldId + '_hidden');
-            return hidden ? hidden.value : '';
-        }
-    });
-})();

web_interface/templates/v3/base.html

@@ -987,7 +987,6 @@
     <script src="{{ url_for('static', filename='v3/js/widgets/custom-feeds.js') }}" defer></script>
     <script src="{{ url_for('static', filename='v3/js/widgets/array-table.js') }}" defer></script>
     <script src="{{ url_for('static', filename='v3/js/widgets/google-calendar-picker.js') }}" defer></script>
-    <script src="{{ url_for('static', filename='v3/js/widgets/google-oauth.js') }}" defer></script>
     <script src="{{ url_for('static', filename='v3/js/widgets/day-selector.js') }}" defer></script>
     <script src="{{ url_for('static', filename='v3/js/widgets/time-range.js') }}" defer></script>
     <script src="{{ url_for('static', filename='v3/js/widgets/time-picker.js') }}" defer></script>

web_interface/templates/v3/partials/display.html

@@ -117,6 +117,14 @@
                     </select>
                 </div>
 
+                <div class="form-group" id="setting-display-orientation" data-setting-key="display.hardware.orientation">
+                    <label for="orientation" class="block text-sm font-medium text-gray-700">Panel Orientation{{ ui.help_tip('Rotates the rendered image to match how the panel is physically mounted.\nUse "Upside Down" if you flipped the panel 180° to move the Raspberry Pi / wiring to a more convenient side.', 'Panel Orientation') }}</label>
+                    <select id="orientation" name="orientation" class="form-control">
+                        <option value="normal" {% if main_config.display.hardware.get('orientation', 'normal') == "normal" %}selected{% endif %}>Normal</option>
+                        <option value="180" {% if main_config.display.hardware.get('orientation', 'normal') == "180" %}selected{% endif %}>Upside Down (180°)</option>
+                    </select>
+                </div>
+
                 <div class="form-group" id="setting-display-led_rgb_sequence" data-setting-key="display.hardware.led_rgb_sequence">
                     <label for="led_rgb_sequence" class="block text-sm font-medium text-gray-700">LED RGB Sequence{{ ui.help_tip('Order the panel expects color channels in.\nChange this only if reds/greens/blues look swapped. Default: RGB.', 'LED RGB Sequence') }}</label>
                     <select id="led_rgb_sequence" name="led_rgb_sequence" class="form-control">

web_interface/templates/v3/partials/plugin_config.html

@@ -815,7 +815,7 @@
                     <i class="fas fa-info-circle mr-1"></i>
                     Changes in the file manager save immediately — no need to click Save Configuration.
                 </p>
-            {% elif str_widget in ['text-input', 'textarea', 'select-dropdown', 'toggle-switch', 'radio-group', 'date-picker', 'time-picker', 'slider', 'color-picker', 'email-input', 'url-input', 'password-input', 'font-selector', 'file-upload-single', 'plugin-file-manager', 'google-oauth'] %}
+            {% elif str_widget in ['text-input', 'textarea', 'select-dropdown', 'toggle-switch', 'radio-group', 'date-picker', 'time-picker', 'slider', 'color-picker', 'email-input', 'url-input', 'password-input', 'font-selector', 'file-upload-single', 'plugin-file-manager'] %}
                 {# Render widget container #}
                 <div id="{{ field_id }}_container" class="{{ str_widget }}-container"></div>
                 <script>