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>

web_interface/static/v3/js/pages/display.js

@@ -92,6 +92,45 @@ function refreshScrollSpeedHint(root, ctx) {
     }, HINT_DELAY_MS);
 }
 
+// ── the refresh-cap hint ─────────────────────────────────────────────────────
+// Scroll speeds are worked out against the cap, so a panel that cannot reach
+// it runs every scroll slow. The display has measured a cap it can hold.
+function showRefreshRateHint(root, ctx) {
+    const hint = root.querySelector('#limit_refresh_rate_hz_hint');
+    const input = root.querySelector('#limit_refresh_rate_hz');
+    if (!hint || !input) return;
+    const doc = root.ownerDocument;
+    const win = doc.defaultView;
+    ctx.api.get('/api/v3/config/refresh-rate', { signal: ctx.signal })
+        .then(function(body) {
+            const s = body.status === 'success' && body.data.shortfall;
+            hint.textContent = '';
+            if (!s) return;
+            hint.appendChild(doc.createTextNode(
+                'This panel refreshes at about ' + Math.round(s.measured_hz) +
+                ' Hz, below this ' + Math.round(s.planned_hz) + ' Hz cap, so scrolls run about ' +
+                s.slow_percent + '% slower than set.' + (s.suggested_cap_hz ? ' ' : '')));
+            if (!s.suggested_cap_hz) return;
+            const btn = doc.createElement('button');
+            btn.type = 'button';
+            btn.className = 'underline font-medium';
+            btn.textContent = 'Use ' + s.suggested_cap_hz + ' Hz';
+            btn.addEventListener('click', function() {
+                input.value = s.suggested_cap_hz;
+                input.dispatchEvent(new win.Event('input', { bubbles: true }));
+                input.dispatchEvent(new win.Event('change', { bubbles: true }));
+                hint.textContent = 'Save, then restart the display, to apply ' +
+                    s.suggested_cap_hz + ' Hz.';
+            });
+            hint.appendChild(btn);
+            hint.appendChild(doc.createTextNode(', a cap it can hold.'));
+        })
+        .catch(function(error) {
+            if (quiet(error) || error.body) return;
+            hint.textContent = '';
+        });
+}
+
 function renderScrollSpeedHint(root, hint, slider, a) {
     const doc = root.ownerDocument;
     const win = doc.defaultView;
@@ -303,6 +342,7 @@ export function init(root, ctx) {
     // when it already is), then every 5 s while it stays there.
     ctx.visibility.every(SYNC_POLL_MS, function() { pollSyncStatus(root, ctx); });
 
+    showRefreshRateHint(root, ctx);
     startPluginOrder(root, ctx);
     active = ctx;
 }