Module overlay_watchdog 

Render-readiness watchdog for the break overlay (#196, #226).

super::overlay::fire_break shows an always_on_top overlay window, grabs focus, and pauses media before the overlay’s webview has rendered anything. If that webview never paints — its content process crashes (macOS / WKWebView, #196) or the surface is never realised (Linux, #226) — the break is invisible but active: media paused, focus grabbed, the screen covered, and no UI to dismiss it. The desktop is frozen until the app is force-quit.

This guards against that regardless of why rendering failed. Each overlay break arms a monotonically increasing epoch; the overlay frontend acks once it has rendered the break (any successful IPC from the overlay proves the webview is alive and executing). A watchdog task captures the armed epoch and, after a grace period, tears the break down iff that epoch is still current and unacked — i.e. nothing ever rendered.

Structs

OverlayAck

Two monotonic counters tracking whether the overlay reported in for the most recently fired break. armed advances on every fired break; acked is raised to the latest armed value when the overlay renders. A captured epoch is “stranded” when it is still the armed break and acked never caught up to it.

Constants

RENDER_GRACE_SECS

Grace period before a never-rendered overlay is torn down. Comfortably above a healthy cold mount — React boot, the overlay’s get_settings / get_current_break IPC round-trips, and first paint all land well under a second even on a loaded machine — so a slow-but-live overlay is never killed, yet short enough that a genuine freeze self-clears quickly.

Statics

OVERLAY_ACK

Process-wide instance: armed by super::overlay::fire_break, acked by the notify_overlay_rendered command, read by the watchdog task. A global (like crate::media’s pause state) so the synchronous, scheduler-free fire_break can arm it without threading a handle through every caller.