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/vegas_mode/render_pipeline.py

@@ -202,8 +202,25 @@ class RenderPipeline:
             # Update scroll position
             self.scroll_helper.update_scroll_position()
 
-            # Check if cycle is complete
-            if self.scroll_helper.is_scroll_complete():
+            # Determine if the cycle is done.
+            #
+            # scroll_helper considers a cycle complete only after
+            # total_distance_scrolled >= total_scroll_width + display_width.
+            # That extra display_width of travel causes a "wrap-around" phase
+            # where scroll_position resets to ~0 and the first plugin's content
+            # re-enters from the right — the user sees this 2-3 s window as
+            # "a plugin partially displaying before the next one starts."
+            #
+            # We end the cycle as soon as total_distance_scrolled reaches
+            # total_scroll_width (the wrap-around point), before any second-pass
+            # content becomes visible.  scroll_helper.is_scroll_complete() is
+            # kept as a fallback for edge-cases where that threshold is skipped.
+            at_wrap_point = (
+                not self._cycle_complete and
+                self.scroll_helper.total_distance_scrolled >= self.scroll_helper.total_scroll_width
+            )
+
+            if at_wrap_point or self.scroll_helper.is_scroll_complete():
                 if not self._cycle_complete:
                     self._cycle_complete = True
                     self.stats['scroll_cycles'] += 1
@@ -211,6 +228,20 @@ class RenderPipeline:
                         "Scroll cycle complete after %.1fs",
                         time.time() - self._cycle_start_time
                     )
+                    # Push blank immediately so the hardware never shows
+                    # post-wrap content while the coordinator recomposes.
+                    try:
+                        from PIL import Image as _Image
+                        blank = _Image.new('RGB', (self.display_width, self.display_height))
+                        self.display_manager.image = blank
+                        self.display_manager.update_display()
+                    except (ImportError, OSError, RuntimeError, ValueError, TypeError, MemoryError) as exc:
+                        logger.error(
+                            "Failed to push blank frame at cycle end "
+                            "(display=%dx%d): %s",
+                            self.display_width, self.display_height, exc
+                        )
+                return True  # Cycle done; coordinator starts new cycle next frame
 
             # Get visible portion
             visible_frame = self.scroll_helper.get_visible_portion()