fix(vegas): eliminate plugin re-appearance at scroll cycle boundaries (#327)

* fix(vegas): eliminate plugin re-appearance at scroll cycle boundaries

The Vegas scroll image is wider than the display. scroll_helper marks a
cycle complete only after total_distance_scrolled >= total_scroll_width +
display_width, meaning it keeps scrolling for an extra display_width of
pixels after all content has exited left. During that extra travel the
scroll_position wraps back to ~0 and the first plugin re-enters from the
right - visible for ~2-3 seconds as a plugin partially displaying before
the next one starts.

render_pipeline.render_frame(): end the cycle the moment
total_distance_scrolled >= total_scroll_width (the natural wrap point),
before any second-pass content becomes visible. Push a blank frame
immediately on detection so hardware never shows a frozen content
snapshot while start_new_cycle() recomposes (~100 ms).

display_manager.py: add capture_mode() context manager. When active,
update_display() and the canvas clear in clear() skip the hardware
write, preventing plugins that call update_display() internally from
flashing on the matrix during off-screen content capture inside
start_new_cycle().

plugin_adapter.py: wrap all plugin.display() calls in
_capture_display_content() and _trigger_scroll_content_generation()
with capture_mode() so the fallback capture path never produces
hardware output.

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

* fix(vegas): tighten exception handling in clear() and blank-frame push

display_manager.clear(): replace bare except/pass on the three hardware
Clear() calls with (RuntimeError, OSError) and a logger.error() so
failures are visible in logs rather than silently swallowed.  Still
non-fatal — the PIL image buffer is already black before these calls,
so the next update_display() will push clean content regardless.

render_pipeline.render_frame(): replace broad except/pass in the
blank-frame push with (ImportError, ValueError, TypeError, MemoryError)
and a logger.error() that includes display dimensions for context.
update_display() already handles its own hardware errors internally.

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

* fix(vegas): catch OSError and RuntimeError in blank-frame push

Image.new() can raise OSError in some PIL environments and hardware
libraries may surface RuntimeError on I/O failures.  Add both to the
exception tuple alongside the existing ImportError/ValueError/TypeError/
MemoryError so no boundary failure escapes the local handler.

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

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

src/display_manager.py

@@ -3,6 +3,7 @@ if os.getenv("EMULATOR", "false") == "true":
     from RGBMatrixEmulator import RGBMatrix, RGBMatrixOptions
 else:
     from rgbmatrix import RGBMatrix, RGBMatrixOptions
+from contextlib import contextmanager
 from PIL import Image, ImageDraw, ImageFont
 import time
 from typing import Dict, Any, List, Tuple
@@ -28,6 +29,8 @@ class DisplayManager:
         self.config = config or {}
         self._force_fallback = force_fallback
         self._suppress_test_pattern = suppress_test_pattern
+        # When True, update_display() and clear() skip hardware writes (used during off-screen content capture)
+        self._capture_mode_active = False
         # Snapshot settings for web preview integration (service writes, web reads)
         self._snapshot_path = "/tmp/led_matrix_preview.png"
         self._snapshot_min_interval_sec = 0.2  # max ~5 fps
@@ -255,6 +258,22 @@ class DisplayManager:
         except Exception as e:
             logger.error(f"Error drawing test pattern: {e}", exc_info=True)
 
+    @contextmanager
+    def capture_mode(self):
+        """Suppress hardware output during off-screen content capture.
+
+        Plugins call update_display() as part of their normal display() flow.
+        When fetching content for Vegas mode the render loop is still running,
+        so any incidental hardware write causes a visible flash on the matrix.
+        Entering this context prevents those writes without affecting the PIL
+        image buffer, which the adapter reads to extract content.
+        """
+        self._capture_mode_active = True
+        try:
+            yield
+        finally:
+            self._capture_mode_active = False
+
     def update_display(self):
         """Update the display using double buffering with proper sync."""
         try:
@@ -264,10 +283,13 @@ class DisplayManager:
                 # Still write a snapshot so the web UI can preview
                 self._write_snapshot_if_due()
                 return
-                
-            # Copy the current image to the offscreen canvas   
+
+            if self._capture_mode_active:
+                return  # Skip hardware write — content is being captured off-screen
+
+            # Copy the current image to the offscreen canvas
             self.offscreen_canvas.SetImage(self.image)
-            
+
             # Swap buffers immediately
             self.matrix.SwapOnVSync(self.offscreen_canvas)
             
@@ -304,21 +326,23 @@ class DisplayManager:
             # Create a new black image
             self.image = Image.new('RGB', (self.matrix.width, self.matrix.height))
             self.draw = ImageDraw.Draw(self.image)
-            
-            # Clear both canvases and the underlying matrix to ensure no artifacts
-            try:
-                self.offscreen_canvas.Clear()
-            except Exception:
-                pass
-            try:
-                self.current_canvas.Clear()
-            except Exception:
-                pass
-            try:
-                # Extra safety: clear the matrix front buffer as well
-                self.matrix.Clear()
-            except Exception:
-                pass
+
+            if not self._capture_mode_active:
+                # Clear both canvases and the underlying matrix to ensure no artifacts.
+                # Failures are non-fatal — the image buffer is already black above, so
+                # the next update_display() call will push clean content regardless.
+                try:
+                    self.offscreen_canvas.Clear()
+                except (RuntimeError, OSError) as e:
+                    logger.error("Failed to clear offscreen canvas: %s", e)
+                try:
+                    self.current_canvas.Clear()
+                except (RuntimeError, OSError) as e:
+                    logger.error("Failed to clear current canvas: %s", e)
+                try:
+                    self.matrix.Clear()
+                except (RuntimeError, OSError) as e:
+                    logger.error("Failed to clear matrix front buffer: %s", e)
             
             # Note: We do NOT call update_display() here to avoid black flashes.
             # The caller should call update_display() after drawing new content.