macOS: coalesce libmpv frame notifications before entering the Qt event queue

[tcconnally]

Problem

On the 16 GB Apple M5, the macOS libmpv render path drives sustained CPU and GUI pressure during an 8-cell wall. MpvGLWidget._on_mpv_frame() currently records and emits a queued Qt signal for each libmpv update callback, while paintGL() invokes the native render API. We need to measure and bound that queue explicitly.

Evidence

• Software 8-cell run 20260828_161931: 1,191 main-loop stalls over about 3,000 active seconds, 32 cache-starvation freezes, and 206,131 VO frame-drop events.
• Hardware trial 20260828_172945: about 118,000 render calls in 600 seconds; the Hyperwall process averaged 2.14 CPU cores in powermetrics.
• Corrected normalized total render CPU was about 0.8275 core-equivalents for software versus 0.8313 for hardware, so a decoder toggle is not a demonstrated render-CPU fix.

Scope

• Add a thread-safe one-pending-update gate per MpvGLWidget.
• Preserve newest-frame semantics without unbounded queued GUI work.
• Count callbacks, coalesced callbacks, queued notifications, paints, renders, and errors.
• Preserve the libmpv callback trampoline through teardown.

Acceptance criteria

• Tests cover callback bursts, callback/GUI races, shutdown gating, and newest-frame handling.
• A 60-120 second M5 profile shows bounded queued notifications.
• No render-context teardown regression or increase in maximum paint gap.
• The full repository test suite passes.

[tcconnally]

Implemented in PR #81, merged as 300e14c. The macOS frame-update path now coalesces callbacks before Qt dispatch and exports queue/paint/render counters. The remaining acceptance item is a physical M5 profile confirming bounded notifications and paint-gap behavior.

[tcconnally]

Native acceptance update

Current main is 4475e0ff8f9207f28f92f0067d9d0ba8b739094d. The frame-pump implementation is present in merged PR #81, but native acceptance is still incomplete. This session is running on Linux without a macOS display, native sample, or powermetrics; there is no configured Mac target or current Emby checkout/config here. Historical 8-cell artifacts are not current evidence and fail the current analyzer because power/sleep evidence and required media gates are missing.

Still required: a fixed-corpus 60-120 second M5 run at 1, 2, 4, 6, and 8 cells with frame callbacks, coalesced callbacks, queued notifications, paints, renders, paint gaps, loop lag, native stacks, thermal/GPU/process telemetry, exact commit, and teardown evidence. This issue remains open.

[tcconnally]

Post-merge status: main is now b94be1ce3d86f06841ff458e3708d66efacd4ef1 after PR #84. PR #84 changed only the #79 capacity-evaluator contract; it produced no Mac/native measurements and does not change the open native blockers for this issue. The issue remains open.

[tcconnally]

Native pilot update on main 74a4118c6c194c4f07a666c6ffb3112218137829: the 8-cell run 20260905T114942Z/profile-8-native captured frame-pump and render telemetry, but it is not a pass. The run used the full 856-item library for about 120 seconds, p95 loop lag was 81.6 ms, one active stall exceeded 100 ms, and paint gaps reached about 1970 ms. No fixed-corpus acceptance result yet. Issue remains open.

[tcconnally]

Native pilot update for run 20260905T165329Z/profile-8-docked-clamshell-fixed on commit 2ce6de1c66ce7f4217249c59fa710268c47bc2bc. The docked-clamshell power gate passed: AC, sleep assertions, and external-display evidence were complete. The 8-cell pilot ran about 119.812 seconds with the full 801-item library, not a fixed corpus. Frame-pump/render telemetry and native captures were complete; p95 loop lag was 114.5 ms, 126 stalls were at least 100 ms, and maximum paint gap was 1947.874084 ms. This validates the evidence path but does not satisfy #75 acceptance. The issue remains open pending fixed-corpus 60-120 second profiling evidence.

[tcconnally]

Fixed-corpus frame-pump summary on commit 074258ddb6b1b2e3e1e8bd5cbe09742310c5d99b.

Manifest: 0c1b04d2739bd0a151768b2f781644b505e440ad7a4e44562b52ce367895be5e; all phases used 67 Favorites with the initial soak filter.

Callbacks / queued updates / coalesced callbacks:

• 1 cell: 6995 / 6995 / 0
• 2 cells: 12650 / 12649 / 5
• 4 cells: 13693 / 13690 / 5
• 6 cells: 23371 / 23364 / 9
• 8 cells: 17027 / 16999 / 43

Ignored callbacks were zero in every phase, and queued updates never exceeded callbacks. The frame-pump coalescing behavior is present. Maximum paint gaps were 288.666916 ms, 502.145292 ms, 2066.382125 ms, 1694.7345 ms, and 2557.391 ms for 1/2/4/6/8 cells respectively. The high-cell render-gap criterion is not satisfied, so this issue remains open.

[tcconnally]

Current closeout boundary — main a858488152f1e57453c7ad98ad9c620a69dda407

No new native measurement was produced by the #78 harness publication. The fixed-corpus matrix still demonstrates bounded queued notifications, but maximum paint gaps remain 288.666916 / 502.145292 / 2066.382125 / 1694.7345 / 2557.391 ms at 1/2/4/6/8 cells. The render-gap acceptance criterion is therefore not satisfied. The target Mac is unreachable from the current Linux host, so the issue remains open without a fabricated pass.