feat(perf): time every presented frame, and a soak script to judge a rig

Each scroller already logs its own stats line, but in different formats,
per source, and Vegas logs a healthy window only at DEBUG. None of it
answers the question a release has to answer on each rig: over a long
run, how often did a moving frame reach the panel late?

Every frame reaches the panel through DisplayManager.update_display, so
it is timed there once, whoever drew it: the blit (SetImage), the vsync
wait, and the interval since the previous frame. The render thread only
appends a tuple. A worker thread aggregates cumulative counters and
histograms and rewrites /dev/shm/ledmatrix_frame_stats.json every 10s
(RAM, so no SD wear).

A frame due after `hold` refreshes that lands one or more refreshes
later is "late": the panel repeated the previous frame, a visible hitch.
Gaps of 250ms+ inside a scroll are "freezes" (recomposes, handovers,
blocking calls), counted separately so one handover does not read as 40
missed refreshes. Static frames, the first frame of a scroll and gaps
between scrolls are not timed. The refresh period is estimated from the
frames themselves.

scripts/frame_soak.py runs next to the service as any user, diffs two
snapshots over a run (default 10 minutes), optionally keeps the web
preview's viewer marker fresh, and exits non-zero above 0.1% late
frames. It also reports whether the loaded rgbmatrix binding releases
the GIL. Documented under "Soaking a rig" in docs/SCROLL_PERFORMANCE.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/display_manager.py

@@ -52,6 +52,7 @@ import zlib
 import freetype
 
 from src.common import snapshot_policy
+from src.common.frame_timing import FrameTimingRecorder
 from src.deprecation import deprecated
 from src.common.permission_utils import (
     ensure_directory_permissions,
@@ -232,6 +233,10 @@ class DisplayManager:
         # See src/common/scroll_config.py and scripts/scroll_speeds.py.
         self._frame_hold = 1
 
+        # Timing of every presented frame, whoever drew it, for
+        # scripts/frame_soak.py. See src/common/frame_timing.py.
+        self.frame_timing = FrameTimingRecorder(info=self._frame_timing_info())
+
         self._scrolling_state = {
             'is_scrolling': False,
             'last_scroll_activity': 0,
@@ -808,15 +813,21 @@ class DisplayManager:
 
                 # Copy the current image to the offscreen canvas. In double-sided
                 # mode the logical screen is first tiled across the full chain.
+                blit_started = time.perf_counter()
                 if self._double_sided is not None:
                     self.offscreen_canvas.SetImage(self._composite_double_sided())
                 else:
                     self.offscreen_canvas.SetImage(self.image)
+                blit_done = time.perf_counter()
 
                 # Swap buffers immediately. framerate_fraction holds the frame
                 # for N refreshes; SwapOnVSync blocks for all of them, which is
                 # what paces the render loop to the chosen frame rate.
                 self.matrix.SwapOnVSync(self.offscreen_canvas, self._frame_hold)
+                presented_at = time.perf_counter()
+                self.frame_timing.record(
+                    blit_done - blit_started, presented_at - blit_done,
+                    self._frame_hold, self.is_currently_scrolling(), presented_at)
 
                 # Swap our canvas references
                 self.offscreen_canvas, self.current_canvas = self.current_canvas, self.offscreen_canvas
@@ -1448,6 +1459,18 @@ class DisplayManager:
             value = 0.0
         return value if value > 0 else 100.0
 
+    def _frame_timing_info(self) -> Dict[str, Any]:
+        """What the frame-timing stats were measured on, for the soak report."""
+        display = self.config.get('display') or {}
+        hardware = display.get('hardware') or {}
+        runtime = display.get('runtime') or {}
+        info = {key: hardware.get(key) for key in (
+            'rows', 'cols', 'chain_length', 'parallel', 'pwm_bits',
+            'hardware_mapping', 'limit_refresh_rate_hz', 'pixel_mapper_config')}
+        info['gpio_slowdown'] = runtime.get('gpio_slowdown')
+        info['emulator'] = os.environ.get('EMULATOR', 'false') == 'true'
+        return info
+
     def set_frame_hold(self, refreshes: int) -> None:
         """Hold each pushed frame for this many panel refreshes (>=1).