perf(render): park the render loop while nothing consumes frames

crates/hypercolor-app/tests/packaging_tests.rs

@@ -1804,6 +1804,37 @@ fn pawnio_lookups_see_the_64_bit_install_from_any_powershell() {
     }
 }
 
+/// The daemon exits nonzero when its render thread cannot recover in
+/// process. Every launcher that runs it as a service must restart it on
+/// that exit, not only on a crash: systemd on failure, and the Windows
+/// service manager only once the failure flag extends its recovery actions
+/// to non-crash failures.
+#[test]
+fn daemon_service_launchers_restart_a_daemon_that_exits_with_an_error() {
+    for (name, unit) in [
+        ("hypercolor.service", SYSTEMD_USER_UNIT),
+        ("hypercolor.service.system", SYSTEMD_PACKAGED_USER_UNIT),
+    ] {
+        assert!(
+            unit.lines().any(|line| line.trim() == "Restart=on-failure"),
+            "{name} must restart the daemon after an error exit"
+        );
+    }
+    let code: Vec<&str> = INSTALL_WINDOWS_SERVICE_PS1
+        .lines()
+        .filter(|line| !line.trim_start().starts_with('#'))
+        .collect();
+    for step in [
+        "sc.exe failure $ServiceName reset= 86400 actions= restart/",
+        "sc.exe failureflag $ServiceName 1",
+    ] {
+        assert!(
+            code.iter().any(|line| line.contains(step)),
+            "the daemon service installer is missing {step}"
+        );
+    }
+}
+
 /// `Start-Service` and `Stop-Service` wait without a bound while a service
 /// is pending, which would hang the installer. The broker installer bounds
 /// every wait, checks the broker stayed up, and on failure prints the

crates/hypercolor-cli/src/commands/status.rs

@@ -361,7 +361,12 @@ fn status_table_lines(data: &SystemStatus, p: &Painter) -> Vec<String> {
     let fps_pct = ratio_percent(fps_ratio);
     let bar = render_fps_bar(fps_ratio, 24, p);
     let fps_display = format!("{actual_fps:>4.1} {} {target_fps}", p.muted("/"));
-    let health_word = format_fps_health(fps_pct, p);
+    // A parked loop reports zero FPS by design, not as a failing rate.
+    let health_word = if render_loop.output_demand.parked {
+        p.muted("parked")
+    } else {
+        format_fps_health(fps_pct, p)
+    };
 
     lines.push(format!(
         "  {}   {}  {bar}  {health_word}",
@@ -381,6 +386,13 @@ fn status_table_lines(data: &SystemStatus, p: &Painter) -> Vec<String> {
         p.muted(&format!("{} frames", format_count(total_frames))),
         p.muted(""),
     ));
+    if render_loop.output_demand.parked {
+        lines.push(format!(
+            "  {}   {}",
+            p.muted(&pad("", 10)),
+            p.muted("parked: nothing consumes frames, so nothing renders until a device, preview, or capture appears"),
+        ));
+    }
 
     // ── Frame budget ────────────────────────────────────────────────
     if let Some(latest_frame) = &data.latest_frame {
@@ -611,8 +623,8 @@ mod tests {
     use hypercolor_types::api::system::{
         LatestFrameStatus, MacosCapabilityOwner, MacosDaemonHandoverPhase,
         MacosDaemonOwnerConflictStatus, MacosDaemonOwnerRecoveryRequiredStatus,
-        MacosDaemonOwnershipStatus, PreviewRuntimeStatus, RenderLoopStatus, RenderSurfaceStatus,
-        ServerInfo, SystemResource, SystemStatus,
+        MacosDaemonOwnershipStatus, PreviewRuntimeStatus, RenderLoopStatus,
+        RenderOutputDemandStatus, RenderSurfaceStatus, ServerInfo, SystemResource, SystemStatus,
     };
     use serde_json::json;
 
@@ -958,6 +970,50 @@ mod tests {
         assert_eq!(format_count(1_234_567), "1,234,567");
     }
 
+    #[test]
+    fn status_lines_explain_a_parked_render_loop() {
+        let painter = Painter::plain();
+        let parked = SystemStatus {
+            render_loop: RenderLoopStatus {
+                state: "running".to_owned(),
+                target_fps: 60,
+                output_demand: RenderOutputDemandStatus {
+                    parked: true,
+                    idle_reason: Some("no_output_consumers".to_owned()),
+                    ..RenderOutputDemandStatus::default()
+                },
+                ..RenderLoopStatus::default()
+            },
+            ..SystemStatus::default()
+        };
+        let rendering = SystemStatus {
+            render_loop: RenderLoopStatus {
+                state: "running".to_owned(),
+                target_fps: 60,
+                ..RenderLoopStatus::default()
+            },
+            ..SystemStatus::default()
+        };
+
+        let parked_lines = status_table_lines(&parked, &painter).join("\n");
+        let rendering_lines = status_table_lines(&rendering, &painter).join("\n");
+
+        assert!(parked_lines.contains("parked: nothing consumes frames"));
+        assert!(!rendering_lines.contains("parked"));
+
+        // Zero FPS reads as a failing rate only while the loop renders.
+        let fps_line = |lines: &str| {
+            lines
+                .lines()
+                .find(|line| line.contains("/ 60"))
+                .map(str::to_owned)
+                .expect("status should print the render rate")
+        };
+        assert!(fps_line(&parked_lines).ends_with("parked"));
+        assert!(!fps_line(&parked_lines).contains("0%"));
+        assert!(fps_line(&rendering_lines).ends_with("0%"));
+    }
+
     #[test]
     fn status_lines_include_core_fields() {
         let data = SystemStatus {

crates/hypercolor-core/src/bus/demand.rs

@@ -0,0 +1,113 @@
+//! Output-demand signalling for the latest-value bus lanes.
+//!
+//! A producer that publishes onto watch lanes can stop producing while
+//! nothing consumes its output, but watch channels never announce a new
+//! subscriber. [`OutputDemandSignal`] closes that gap: every lane
+//! subscription, every [`OutputDemandHold`], and every discrete event
+//! published on the bus notifies it, so an idle producer can sleep on the
+//! signal and re-evaluate the moment a consumer appears or observable state
+//! changes, instead of polling for either.
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering, fence};
+
+use tokio::sync::Notify;
+use tokio::sync::futures::Notified;
+
+/// Wake signal for producers that idle while nothing consumes their output.
+///
+/// Every event publication notifies it, so notification skips the waiter
+/// list entirely unless a producer has armed a wait.
+#[derive(Debug, Default)]
+pub struct OutputDemandSignal {
+    epoch: AtomicU64,
+    holds: AtomicUsize,
+    armed: AtomicUsize,
+    notify: Notify,
+}
+
+impl OutputDemandSignal {
+    /// Monotonic count of notifications, for observing that one happened.
+    #[must_use]
+    pub fn epoch(&self) -> u64 {
+        self.epoch.load(Ordering::Acquire)
+    }
+
+    /// Number of live [`OutputDemandHold`]s.
+    #[must_use]
+    pub fn hold_count(&self) -> usize {
+        self.holds.load(Ordering::Acquire)
+    }
+
+    /// Arm a wait. Notifications reach waiters only while at least one
+    /// [`ArmedOutputDemand`] lives, so arm before re-checking demand.
+    pub fn arm(&self) -> ArmedOutputDemand<'_> {
+        self.armed.fetch_add(1, Ordering::SeqCst);
+        // Orders the arm before every demand read the waiter makes next.
+        fence(Ordering::SeqCst);
+        ArmedOutputDemand { signal: self }
+    }
+
+    /// Wake every current waiter.
+    pub fn notify(&self) {
+        self.epoch.fetch_add(1, Ordering::AcqRel);
+        // The state change that prompted this call (a new receiver, a hold,
+        // an event) may use weaker orderings, so a full fence orders it
+        // before the armed check. Paired with the fence in `arm`, either
+        // this load sees the waiter and wakes it, or the waiter's demand
+        // read sees the state change.
+        fence(Ordering::SeqCst);
+        if self.armed.load(Ordering::SeqCst) > 0 {
+            self.notify.notify_waiters();
+        }
+    }
+
+    pub(super) fn acquire_hold(self: &Arc<Self>) -> OutputDemandHold {
+        self.holds.fetch_add(1, Ordering::AcqRel);
+        self.notify();
+        OutputDemandHold {
+            signal: Arc::clone(self),
+        }
+    }
+}
+
+/// An armed wait on an [`OutputDemandSignal`].
+#[derive(Debug)]
+pub struct ArmedOutputDemand<'a> {
+    signal: &'a OutputDemandSignal,
+}
+
+impl ArmedOutputDemand<'_> {
+    /// Future that resolves on the next notification.
+    ///
+    /// Pin it and call [`Notified::enable`] before re-checking demand: a
+    /// notification that lands between the check and the await then still
+    /// wakes the waiter.
+    pub fn notified(&self) -> Notified<'_> {
+        self.signal.notify.notified()
+    }
+}
+
+impl Drop for ArmedOutputDemand<'_> {
+    fn drop(&mut self) {
+        self.signal.armed.fetch_sub(1, Ordering::SeqCst);
+    }
+}
+
+/// Keeps output demand registered for consumers that read the bus without
+/// holding a lane receiver, such as a borrow of a per-zone sender.
+///
+/// Dropping the hold withdraws the demand. Release needs no notification:
+/// a producer only loses demand on its own next evaluation.
+#[derive(Debug)]
+#[must_use = "dropping the hold withdraws the output demand it registers"]
+pub struct OutputDemandHold {
+    signal: Arc<OutputDemandSignal>,
+}
+
+impl Drop for OutputDemandHold {
+    fn drop(&mut self) {
+        let previous = self.signal.holds.fetch_sub(1, Ordering::AcqRel);
+        debug_assert!(previous > 0, "output demand hold underflow");
+    }
+}