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

* 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 (js/pages/display.js) 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.
Rebased onto main after the Display tab became an ES-module page (#771); the
hint moved from inline script into display.js, with a jsdom test.

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

* fix(scroll): count only agreeing windows toward the refresh shortfall; ignore a null planned rate

Review fixes on #759.

- A window the period estimate rejects (more than MAX_REFRESH_DROP faster
  than the adopted period) no longer counts toward the shortfall check, and
  it restarts the run. After a loaded start fixed a slow period, later
  windows at the real, faster rate were rejected yet still counted, so the
  warning could name the slow rate against a cap the panel was meeting. It
  now needs REFRESH_CHECK_WINDOWS consecutive windows that agree with the
  period.
- _panel_refresh_hz treats a stats file whose planned_refresh_hz key is
  present but null as no measurement. The emulator and the fallback canvas
  write it that way (DisplayManager never plans a refresh for them), and
  their frame rate says nothing about the cap. A file with no such key (an
  older display) keeps the old behaviour.

Three new tests fail on the previous code and pass now.

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

---------

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

test/test_frame_timing.py

@@ -807,3 +807,80 @@ def test_a_process_with_the_gc_monitor_exits_cleanly():
     assert proc.returncode == 0, proc.stderr
     assert "Exception ignored" not in proc.stderr
     assert "installed at exit: False" in proc.stdout
+
+
+SLOW = 1 / 110.0  # a panel that cannot reach a 120 Hz cap
+
+
+def _windows(recorder, n, interval, start=0.0):
+    for i in range(n):
+        _feed(recorder, [interval] * 200, start=start + 50.0 * i)
+        _aggregate(recorder)
+
+
+def _shortfall_warnings(caplog):
+    return [r for r in caplog.records
+            if r.name == "src.common.frame_timing" and "Limit Refresh Rate" in r.getMessage()]
+
+
+def test_a_panel_slower_than_its_cap_is_reported_once(tmp_path, caplog):
+    r = _recorder(tmp_path)
+    r.plan_refresh(120.0)
+    caplog.set_level("WARNING")
+    _windows(r, 3, SLOW)          # adopted on the 2nd window, checked on the 4th
+    assert _shortfall_warnings(caplog) == []
+    _windows(r, 3, SLOW, start=1000.0)
+    warnings = _shortfall_warnings(caplog)
+    assert len(warnings) == 1
+    assert "about 110 Hz" in warnings[0].getMessage()
+    assert "to 100 Hz" in warnings[0].getMessage()
+
+
+def test_a_panel_that_reaches_its_cap_is_not_reported(tmp_path, caplog):
+    r = _recorder(tmp_path)
+    r.plan_refresh(100.0)
+    caplog.set_level("WARNING")
+    _windows(r, 6, PERIOD)
+    assert _shortfall_warnings(caplog) == []
+
+
+def test_without_a_planned_rate_nothing_is_checked(tmp_path, caplog):
+    # The emulator and the fallback canvas: DisplayManager never calls
+    # plan_refresh(), since their frames are not paced by a panel.
+    r = _recorder(tmp_path)
+    caplog.set_level("WARNING")
+    _windows(r, 6, SLOW)
+    assert _shortfall_warnings(caplog) == []
+
+
+def test_the_snapshot_records_the_planned_rate(tmp_path):
+    r = _recorder(tmp_path)
+    assert r.snapshot()["planned_refresh_hz"] is None
+    r.plan_refresh(120.0)
+    assert r.snapshot()["planned_refresh_hz"] == 120.0
+
+
+def test_windows_the_period_rejected_do_not_count_toward_the_warning(tmp_path, caplog):
+    # A loaded start fixed 60 Hz (two windows agreed); the panel really runs at
+    # 100 Hz, but a window that much faster is ignored by the estimate, so the
+    # period stays 60 Hz. Warning "60 Hz is under your 100 Hz cap" would be wrong.
+    r = _recorder(tmp_path)
+    r.plan_refresh(100.0)
+    caplog.set_level("WARNING")
+    _windows(r, 2, 1 / 60.0)
+    assert abs(1.0 / r.refresh_period - 60.0) < 0.5
+    _windows(r, 6, PERIOD, start=1000.0)
+    assert abs(1.0 / r.refresh_period - 60.0) < 0.5   # still ignored
+    assert _shortfall_warnings(caplog) == []
+
+
+def test_one_disagreeing_window_restarts_the_run(tmp_path, caplog):
+    r = _recorder(tmp_path)
+    r.plan_refresh(120.0)
+    caplog.set_level("WARNING")
+    _windows(r, 3, SLOW)                               # two windows toward three
+    _windows(r, 1, 1 / 250.0, start=1000.0)            # far faster: rejected, resets
+    _windows(r, 1, SLOW, start=2000.0)
+    assert _shortfall_warnings(caplog) == []
+    _windows(r, 2, SLOW, start=3000.0)                 # three in a row now
+    assert len(_shortfall_warnings(caplog)) == 1