fps: Cap the headline by asking the platform what the panel runs at

[huacnlee]

Summary

Follow-up to #2954. MAX FPS was capped by a refresh rate inferred from the gaps between presents. That inference cannot work: those gaps are whole multiples of the panel's period, so they bound it from below and never from above — 41.7ms is six refreshes at 144Hz and one at 24Hz, and nothing in the timing distinguishes them.

Four estimators, four wrong readings on real windows, the last three found in longbridge-lite:

Estimator	Read	Should have been
Shortest gap ever seen	169	144 — a compositor catch-up is not a refresh
Densest group of gaps	149	144 — bucketing truncates the distribution it measures
Densest group of gaps	75	~137 — the densest thing a demand-drawing window does is idle
Fastest sustained run	24	~116 — the application's own timer fired every 41.7ms
Frame budget until established	60	~167 — a ceiling under the truth hides the figure entirely

A steady 41.7ms application tick is indistinguishable from a 24Hz panel. No tuning gets past that.

Changes

The guessing is gone, and the platform is asked instead. GPUI hands out the platform's own display handle through DisplayId, and the HUD takes it from there:

• macOS — CGDisplayCopyDisplayMode on the CGDirectDisplayID
• Windows — EnumDisplaySettingsW on the monitor's device name
• Wayland — object ids are per-connection and mean nothing across one, so the outputs are enumerated again and matched to GPUI's displays by the identity it derives from their names
• X11 and everything else — no query, so no cap

A panel that reports no fixed rate — which is what ProMotion honestly is through CoreGraphics — is read as no cap. Where nobody will say, the reading is left uncapped rather than held to a guess.

The answer is re-asked when the window moves to another display, and not otherwise: it is a property of the panel, and on some platforms asking is a round trip.

The warm-up stays. Frames from before the HUD was mounted, and the cold ones right after it, are dropped rather than measured, so a window that just opened still reads healthy.

Verified

On Wayland against two panels, with a temporary probe:

output 1492e027-… -> 143.998 Hz     (compositor: 143.999)
output 09e7b298-… -> 59.997 Hz      (compositor: 59.997)
window on the first  -> 143.998 Hz

and the HUD on that window, FRAME 4.3ms — 232 uncapped — reading MAX 144, from the moment it opened and with no interaction.

Not verified on hardware: the macOS and Windows queries could not be compiled here, let alone run. The Wayland path and everything above it is measured.

Test plan

• macOS: MAX stops at the panel's rate on an external display; a built-in ProMotion panel reads uncapped
• Windows: MAX stops at the panel's rate
• Drag the window between two monitors of different rates: MAX follows
• A window with a regular timer (quote ticks, a clock) is not capped by its own cadence
• A window that just opened still reads DROP 0.0% and a green P95

AI Assistance

🤖 Code and docs generated by Claude Code; the wrong readings were caught by the author on real windows. Verified locally on Linux/Wayland with 144Hz and 60Hz panels; cargo test -p gpui-fps (28) passes, clippy --deny warnings clean. The macOS and Windows queries are unverified — they cannot be built on this machine.

🤖 Generated with Claude Code

https://claude.ai/code/session_01USSMRpQ5W58YP3UKUCzrri