feat(scroll): report a panel that cannot reach its refresh cap, and suggest one it can hold

Scroll speeds are solved against display.hardware.limit_refresh_rate_hz,
which is only a ceiling. A panel that cannot reach it still moves whole
pixels per frame, but every scroll runs slow by the shortfall and the
"smooth" ladder is the cap's, not the panel's. A user rig (Pi 4, 2x128x64,
adafruit-hat-pwm, pwm_bits 9, gpio_slowdown 5) measured 107.6-113.1 Hz under
a 120 Hz cap: 60 px/s ran at 55, and nothing said why.

- scroll_config: refresh_shortfall() (more than 3% under the planned rate),
  holdable_cap() (a multiple of 10, 5% under the measurement, since the
  measurement is the fast end of an uncapped panel's drift), and
  describe_refresh_shortfall().
- FrameTimingRecorder.plan_refresh(): once the measured period has held for
  three trusted windows, a shortfall is logged once as a warning naming the
  cap to use. DisplayManager calls it only for a real panel, not the
  emulator or the fallback canvas. The stats file records
  planned_refresh_hz (additive).
- GET /api/v3/config/refresh-rate, plus a hint under the Display tab's
  Limit Refresh Rate field with a button that fills in the suggested cap.
- _panel_refresh_hz (behind the Vegas slider's advice) ignores a measurement
  written under a different cap, so a changed cap stops being advised from
  the old rate before the display restarts.

Verified on ledpi with a temporary 200 Hz cap: the warning logged about a
minute after the restart ("about 132 Hz ... Set Limit Refresh Rate to
120 Hz"), the endpoint returned the same shortfall, and the Display tab
showed the hint; its button filled in 120. ledpi was restored afterwards.

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

test/test_scroll_config.py

@@ -21,6 +21,7 @@ from src.common.scroll_config import (  # noqa: E402
     refresh_hz_from_config,
     resolve,
 )
+from src.common import scroll_config  # noqa: E402
 
 
 class FakeHelper:
@@ -504,3 +505,46 @@ class TestSpeedAdvice:
         got = solve_crisp(50, 125.74)
         assert got.steppiness == "smooth"
         assert got.pixels_per_frame == 1
+
+
+class TestRefreshShortfall:
+    """A panel that cannot reach its cap runs every scroll slow."""
+
+    def test_the_ledmatrix_rig_is_told_to_cap_at_100(self):
+        # Pi 4, 2x128x64 on adafruit-hat-pwm under a 120 Hz cap: measured
+        # 107.6-113.1 Hz, and frame_timing reports the fast end.
+        s = scroll_config.refresh_shortfall(113.1, 120)
+        assert s == {"measured_hz": 113.1, "planned_hz": 120.0,
+                     "suggested_cap_hz": 100, "slow_percent": 6}
+
+    def test_a_panel_that_holds_its_cap_is_fine(self):
+        assert scroll_config.refresh_shortfall(99.95, 100) is None
+        assert scroll_config.refresh_shortfall(97.5, 100) is None
+
+    def test_a_panel_that_beats_its_cap_is_fine(self):
+        assert scroll_config.refresh_shortfall(125.7, 120) is None
+
+    def test_nothing_measured_says_nothing(self):
+        assert scroll_config.refresh_shortfall(None, 120) is None
+        assert scroll_config.refresh_shortfall(0, 120) is None
+        assert scroll_config.refresh_shortfall("fast", 120) is None
+
+    def test_the_suggestion_leaves_headroom_under_the_measurement(self):
+        assert scroll_config.holdable_cap(113.1) == 100
+        assert scroll_config.holdable_cap(95.0) == 90
+        # 5% under 105 is 99.75: 100 would sit inside the panel's drift.
+        assert scroll_config.holdable_cap(105.0) == 90
+        assert scroll_config.holdable_cap(9.0) is None
+        assert scroll_config.holdable_cap(None) is None
+
+    def test_the_log_line_names_the_cap_to_use(self):
+        text = scroll_config.describe_refresh_shortfall(
+            scroll_config.refresh_shortfall(113.1, 120))
+        assert "about 113 Hz" in text and "120 Hz" in text
+        assert "6% slower" in text
+        assert "Set Limit Refresh Rate to 100 Hz" in text
+
+    def test_no_suggestion_for_a_panel_too_slow_for_any_cap(self):
+        text = scroll_config.describe_refresh_shortfall(
+            scroll_config.refresh_shortfall(9.0, 100))
+        assert "Set Limit Refresh Rate" not in text