missing docs

Cargo.lock

@@ -572,7 +572,7 @@ checksum = "1d674e81391d1e1ab681a28d99df07927c6d4aa5b027d7da16ba32d1d21ecd99"
 
 [[package]]
 name = "fluxo-rs"
-version = "0.4.2"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "bluer",

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fluxo-rs"
-version = "0.4.2"
+version = "0.5.1"
 edition = "2024"
 
 [features]

example.config.toml

@@ -93,6 +93,10 @@ format_inactive = "<span size='large'></span>"
 
 [mpris]
 # enabled = false  # set to false to disable this module at runtime
+# max_length = 30          # truncate text beyond this character length (adds '...')
+# scroll = true            # enable marquee scroll animation (requires max_length)
+# scroll_speed = 500       # ms between scroll steps (only while playing)
+# scroll_separator = " /// "  # separator shown between loops when scrolling
 # tokens: {artist}, {title}, {album}, {status_icon}
 format = "{status_icon} {artist} - {title}"
 

src/config.rs

@@ -1,8 +1,16 @@
+//! Configuration loading + top-level `Config` struct.
+//!
+//! Every module section `#[derive(Deserialize)]`s its own struct with `serde`
+//! defaults, so missing TOML sections/fields simply fall back to baked-in
+//! values. The live `Config` is held behind an `Arc<RwLock<_>>` by the daemon
+//! and replaced atomically on reload (see [`crate::daemon::reload_config`]).
+
 use serde::Deserialize;
 use std::fs;
 use std::path::PathBuf;
 use tracing::{debug, info, warn};
 
+/// Top-level parsed `config.toml`. Each field corresponds to a `[section]`.
 #[derive(Deserialize, Default, Clone)]
 pub struct Config {
     #[serde(default)]
@@ -56,8 +64,10 @@ pub struct Config {
     pub dnd: DndConfig,
 }
 
+/// Process-wide settings that aren't tied to a single module.
 #[derive(Deserialize, Clone)]
 pub struct GeneralConfig {
+    /// Shell command spawned by [`crate::utils::show_menu`] for interactive pickers.
     pub menu_command: String,
 }
 
@@ -69,6 +79,9 @@ impl Default for GeneralConfig {
     }
 }
 
+/// Which Waybar `SIGRTMIN+N` signal each module should trigger, if any.
+///
+/// `None` disables signalling for that module entirely.
 #[allow(dead_code)]
 #[derive(Deserialize, Default, Clone)]
 pub struct SignalsConfig {
@@ -89,6 +102,7 @@ pub struct SignalsConfig {
     pub dnd: Option<i32>,
 }
 
+/// Network module config. `format` tokens: `interface`, `ip`, `rx`, `tx`.
 #[derive(Deserialize, Clone)]
 pub struct NetworkConfig {
     #[serde(default = "default_true")]
@@ -105,6 +119,7 @@ impl Default for NetworkConfig {
     }
 }
 
+/// CPU module config. `format` tokens: `usage`, `temp`.
 #[derive(Deserialize, Clone)]
 pub struct CpuConfig {
     #[serde(default = "default_true")]
@@ -121,6 +136,7 @@ impl Default for CpuConfig {
     }
 }
 
+/// Memory module config. `format` tokens: `used`, `total` (gigabytes).
 #[derive(Deserialize, Clone)]
 pub struct MemoryConfig {
     #[serde(default = "default_true")]
@@ -137,6 +153,7 @@ impl Default for MemoryConfig {
     }
 }
 
+/// GPU module config with per-vendor format strings.
 #[derive(Deserialize, Clone)]
 pub struct GpuConfig {
     #[serde(default = "default_true")]
@@ -159,6 +176,7 @@ impl Default for GpuConfig {
     }
 }
 
+/// Sys module config. `format` tokens: `uptime`, `load1`, `load5`, `load15`, `procs`.
 #[derive(Deserialize, Clone)]
 pub struct SysConfig {
     #[serde(default = "default_true")]
@@ -175,6 +193,7 @@ impl Default for SysConfig {
     }
 }
 
+/// Disk module config. `format` tokens: `mount`, `used`, `total`.
 #[derive(Deserialize, Clone)]
 pub struct DiskConfig {
     #[serde(default = "default_true")]
@@ -191,6 +210,7 @@ impl Default for DiskConfig {
     }
 }
 
+/// Btrfs pool module config. `format` tokens: `used`, `total`.
 #[derive(Deserialize, Clone)]
 pub struct PoolConfig {
     #[serde(default = "default_true")]
@@ -207,6 +227,7 @@ impl Default for PoolConfig {
     }
 }
 
+/// Battery/power module config. `format` tokens: `percentage`, `icon`.
 #[derive(Deserialize, Clone)]
 pub struct PowerConfig {
     #[serde(default = "default_true")]
@@ -223,6 +244,7 @@ impl Default for PowerConfig {
     }
 }
 
+/// Audio module config, one format per (sink|source) × (muted|unmuted) state.
 #[derive(Deserialize, Clone)]
 pub struct AudioConfig {
     #[serde(default = "default_true")]
@@ -245,6 +267,8 @@ impl Default for AudioConfig {
     }
 }
 
+/// Bluetooth module config. Plugin line tokens: `alias`, `left`, `right`,
+/// `anc`, `mac`. Plain connect line tokens: `alias`.
 #[derive(Deserialize, Clone)]
 pub struct BtConfig {
     #[serde(default = "default_true")]
@@ -267,6 +291,7 @@ impl Default for BtConfig {
     }
 }
 
+/// Gamemode indicator config (active/inactive glyphs).
 #[derive(Deserialize, Clone)]
 pub struct GameConfig {
     #[serde(default = "default_true")]
@@ -285,11 +310,29 @@ impl Default for GameConfig {
     }
 }
 
+/// MPRIS module config. `format` tokens: `artist`, `title`, `album`,
+/// `status_icon`. Optional marquee scrolling when `scroll = true`.
 #[derive(Deserialize, Clone)]
 pub struct MprisConfig {
     #[serde(default = "default_true")]
     pub enabled: bool,
     pub format: String,
+    #[serde(default)]
+    pub max_length: Option<usize>,
+    #[serde(default)]
+    pub scroll: bool,
+    #[serde(default = "default_scroll_speed")]
+    pub scroll_speed: u64,
+    #[serde(default = "default_scroll_separator")]
+    pub scroll_separator: String,
+}
+
+fn default_scroll_speed() -> u64 {
+    500
+}
+
+fn default_scroll_separator() -> String {
+    " /// ".to_string()
 }
 
 impl Default for MprisConfig {
@@ -297,10 +340,15 @@ impl Default for MprisConfig {
         Self {
             enabled: true,
             format: "{status_icon} {artist} - {title}".to_string(),
+            max_length: None,
+            scroll: false,
+            scroll_speed: 500,
+            scroll_separator: " /// ".to_string(),
         }
     }
 }
 
+/// Backlight module config. `format` tokens: `percentage`, `icon`.
 #[derive(Deserialize, Clone)]
 pub struct BacklightConfig {
     #[serde(default = "default_true")]
@@ -317,6 +365,7 @@ impl Default for BacklightConfig {
     }
 }
 
+/// Keyboard layout module config. `format` tokens: `layout`.
 #[derive(Deserialize, Clone)]
 pub struct KeyboardConfig {
     #[serde(default = "default_true")]
@@ -333,6 +382,7 @@ impl Default for KeyboardConfig {
     }
 }
 
+/// Do-Not-Disturb indicator config (dnd/normal glyphs).
 #[derive(Deserialize, Clone)]
 pub struct DndConfig {
     #[serde(default = "default_true")]
@@ -377,41 +427,31 @@ impl Config {
     /// Check if a module is enabled in the configuration.
     /// Returns false if the module is explicitly disabled; true if enabled or unknown.
     pub fn is_module_enabled(&self, module_name: &str) -> bool {
-        match module_name {
-            #[cfg(feature = "mod-network")]
-            "net" | "network" => self.network.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "cpu" => self.cpu.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "mem" | "memory" => self.memory.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "gpu" => self.gpu.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "sys" => self.sys.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "disk" => self.disk.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "pool" | "btrfs" => self.pool.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "power" => self.power.enabled,
-            #[cfg(feature = "mod-hardware")]
-            "game" => self.game.enabled,
-            #[cfg(feature = "mod-audio")]
-            "vol" | "audio" | "mic" => self.audio.enabled,
-            #[cfg(feature = "mod-bt")]
-            "bt" | "bluetooth" => self.bt.enabled,
-            #[cfg(feature = "mod-dbus")]
-            "mpris" => self.mpris.enabled,
-            #[cfg(feature = "mod-dbus")]
-            "backlight" => self.backlight.enabled,
-            #[cfg(feature = "mod-dbus")]
-            "kbd" | "keyboard" => self.keyboard.enabled,
-            #[cfg(feature = "mod-dbus")]
-            "dnd" => self.dnd.enabled,
-            _ => true,
+        macro_rules! gen_enabled_match {
+            ($( { $feature:literal, $field:ident, $state:ty, [$($name:literal),+], [$($sig_name:literal),+], $module:path, $signal:ident, [$($default_arg:literal),*], $config:ident } )*) => {
+                match module_name {
+                    $(
+                        #[cfg(feature = $feature)]
+                        $($name)|+ => self.$config.enabled,
+                    )*
+                    // Dispatch-only modules (no watch channel)
+                    #[cfg(feature = "mod-audio")]
+                    "mic" => self.audio.enabled,
+                    #[cfg(feature = "mod-hardware")]
+                    "pool" | "btrfs" => self.pool.enabled,
+                    #[cfg(feature = "mod-hardware")]
+                    "power" => self.power.enabled,
+                    #[cfg(feature = "mod-hardware")]
+                    "game" => self.game.enabled,
+                    _ => true,
+                }
+            };
         }
+        for_each_watched_module!(gen_enabled_match)
     }
 
+    /// Warn-log any `{token}` placeholders used in format strings that the
+    /// corresponding module does not know how to fill in.
     pub fn validate(&self) {
         #[cfg(feature = "mod-network")]
         validate_format(
@@ -488,6 +528,8 @@ impl Config {
     }
 }
 
+/// Resolve the default config path: `$XDG_CONFIG_HOME/fluxo/config.toml`
+/// (or `~/.config/fluxo/config.toml`).
 pub fn default_config_path() -> PathBuf {
     let config_dir = std::env::var("XDG_CONFIG_HOME")
         .map(PathBuf::from)
@@ -498,6 +540,8 @@ pub fn default_config_path() -> PathBuf {
     config_dir.join("fluxo/config.toml")
 }
 
+/// Load and validate the config, falling back to [`Config::default`] when
+/// the file is missing or malformed. Never panics.
 pub fn load_config(custom_path: Option<PathBuf>) -> Config {
     let config_path = custom_path.unwrap_or_else(default_config_path);
 

src/daemon.rs

@@ -1,3 +1,18 @@
+//! Daemon entry point: orchestrates polling tasks, signal handling, config
+//! hot-reloading, and the IPC server.
+//!
+//! Layout of [`run_daemon`]:
+//!
+//! 1. **Channels** — `watch::channel()` pairs for every module that pushes
+//!    state from a background task.
+//! 2. **Polling / event tasks** — one per module; each writes into its sender,
+//!    the signaler and request handlers read from the matching receiver.
+//! 3. **Config watchers** — filesystem notifier + `SIGHUP` handler refresh the
+//!    [`Config`] in place so modules see updates immediately.
+//! 4. **Signaler** — watches all state receivers and pokes Waybar.
+//! 5. **IPC loop** — `UnixListener` accepting client requests; each connection
+//!    dispatches to [`crate::registry::dispatch`] and returns JSON.
+
 use crate::config::Config;
 use crate::ipc::socket_path;
 #[cfg(feature = "mod-audio")]
@@ -31,6 +46,74 @@ use tokio::time::{Duration, sleep};
 use tokio_util::sync::CancellationToken;
 use tracing::{debug, error, info};
 
+/// Spawn a health-tracked polling loop.
+///
+/// Each iteration: skip if in backoff, else await `$poll_expr` and feed the
+/// `Result` to [`crate::health::handle_poll_result`]. The loop breaks when
+/// `$token` is cancelled.
+macro_rules! spawn_poll_loop {
+    ($name:expr, $interval:expr, $health:expr, $token:expr, $poll_expr:expr) => {
+        tokio::spawn(async move {
+            info!(concat!("Starting ", $name, " polling task"));
+            loop {
+                if !crate::health::is_poll_in_backoff($name, &$health).await {
+                    let res: crate::error::Result<()> = $poll_expr.await;
+                    crate::health::handle_poll_result($name, res, &$health).await;
+                }
+                tokio::select! {
+                    _ = $token.cancelled() => break,
+                    _ = sleep($interval) => {}
+                }
+            }
+            info!(concat!($name, " task shut down."));
+        })
+    };
+}
+
+/// Spawn a health-tracked polling loop with an extra trigger channel.
+///
+/// Identical to [`spawn_poll_loop`] but `$trigger` can wake the loop early —
+/// used by the Bluetooth daemon when a client forces an immediate refresh.
+macro_rules! spawn_poll_loop_triggered {
+    ($name:expr, $interval:expr, $health:expr, $token:expr, $trigger:expr, $poll_expr:expr) => {
+        tokio::spawn(async move {
+            info!(concat!("Starting ", $name, " polling task"));
+            loop {
+                if !crate::health::is_poll_in_backoff($name, &$health).await {
+                    let res: crate::error::Result<()> = $poll_expr.await;
+                    crate::health::handle_poll_result($name, res, &$health).await;
+                }
+                tokio::select! {
+                    _ = $token.cancelled() => break,
+                    _ = $trigger.recv() => {},
+                    _ = sleep($interval) => {}
+                }
+            }
+            info!(concat!($name, " task shut down."));
+        })
+    };
+}
+
+/// Spawn a polling loop with no health tracking.
+///
+/// Used for internal daemons (hardware fast/slow) whose poll functions are
+/// infallible and whose failures don't drive client-visible backoff.
+macro_rules! spawn_poll_loop_simple {
+    ($name:expr, $interval:expr, $token:expr, $poll_expr:expr) => {
+        tokio::spawn(async move {
+            info!(concat!("Starting ", $name, " polling task"));
+            loop {
+                $poll_expr.await;
+                tokio::select! {
+                    _ = $token.cancelled() => break,
+                    _ = sleep($interval) => {}
+                }
+            }
+            info!(concat!($name, " task shut down."));
+        })
+    };
+}
+
 struct SocketGuard {
     path: String,
 }
@@ -46,6 +129,11 @@ fn get_config_path(custom_path: Option<PathBuf>) -> PathBuf {
     custom_path.unwrap_or_else(crate::config::default_config_path)
 }
 
+/// Run the daemon to completion.
+///
+/// Sets up the socket, spawns all enabled module tasks, hooks up config
+/// hot-reloading, and finally enters the IPC accept loop. Returns only on
+/// a fatal error or `Ctrl+C`.
 pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
     let sock_path = socket_path();
 
@@ -78,9 +166,15 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
     let (keyboard_tx, keyboard_rx) = watch::channel(Default::default());
     #[cfg(feature = "mod-dbus")]
     let (dnd_tx, dnd_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-dbus")]
+    let mpris_scroll = Arc::new(RwLock::new(crate::state::MprisScrollState::default()));
+    #[cfg(feature = "mod-dbus")]
+    let (mpris_scroll_tick_tx, mpris_scroll_tick_rx) = watch::channel(0u64);
     let health = Arc::new(RwLock::new(HashMap::new()));
     #[cfg(feature = "mod-bt")]
     let (bt_force_tx, mut bt_force_rx) = mpsc::channel(1);
+    #[cfg(feature = "mod-bt")]
+    let bt_cycle = Arc::new(RwLock::new(0usize));
     #[cfg(feature = "mod-audio")]
     let (audio_cmd_tx, audio_cmd_rx) = mpsc::channel(8);
 
@@ -99,6 +193,8 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
         disks: disks_rx,
         #[cfg(feature = "mod-bt")]
         bluetooth: bt_rx,
+        #[cfg(feature = "mod-bt")]
+        bt_cycle,
         #[cfg(feature = "mod-audio")]
         audio: audio_rx,
         #[cfg(feature = "mod-dbus")]
@@ -109,6 +205,10 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
         keyboard: keyboard_rx,
         #[cfg(feature = "mod-dbus")]
         dnd: dnd_rx,
+        #[cfg(feature = "mod-dbus")]
+        mpris_scroll: Arc::clone(&mpris_scroll),
+        #[cfg(feature = "mod-dbus")]
+        mpris_scroll_tick: mpris_scroll_tick_rx,
         health: Arc::clone(&health),
         #[cfg(feature = "mod-bt")]
         bt_force_poll: bt_force_tx,
@@ -121,7 +221,8 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
         path: sock_path.clone(),
     };
 
-    // Signal handling for graceful shutdown
+    // Ctrl+C triggers a graceful shutdown by cancelling this token; every
+    // spawned polling task checks it in its `select!`.
     let cancel_token = CancellationToken::new();
     let token_clone = cancel_token.clone();
     tokio::spawn(async move {
@@ -132,10 +233,140 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
 
     let resolved_config_path = get_config_path(config_path.clone());
     let config = Arc::new(RwLock::new(crate::config::load_config(config_path.clone())));
+    spawn_config_watchers(&config, &resolved_config_path);
 
-    // 0. Config Watcher (Hot Reload)
-    let watcher_config = Arc::clone(&config);
-    let watcher_path = resolved_config_path.clone();
+    #[cfg(feature = "mod-network")]
+    if config.read().await.network.enabled {
+        let mut daemon = NetworkDaemon::new();
+        let token = cancel_token.clone();
+        let h = Arc::clone(&health);
+        spawn_poll_loop!(
+            "net",
+            Duration::from_secs(1),
+            h,
+            token,
+            daemon.poll(&net_tx)
+        );
+    }
+
+    // Fast-cycle hardware (cpu/mem/load) polled at 1 Hz.
+    #[cfg(feature = "mod-hardware")]
+    {
+        let cfg = config.read().await;
+        let fast_enabled = cfg.cpu.enabled || cfg.memory.enabled || cfg.sys.enabled;
+        drop(cfg);
+        if fast_enabled {
+            let mut daemon = HardwareDaemon::new();
+            let token = cancel_token.clone();
+            spawn_poll_loop_simple!(
+                "fast_hw",
+                Duration::from_secs(1),
+                token,
+                daemon.poll_fast(&cpu_tx, &mem_tx, &sys_tx)
+            );
+        }
+    }
+
+    // Slow-cycle hardware (gpu/disks) polled every 5 s — expensive to sample.
+    #[cfg(feature = "mod-hardware")]
+    {
+        let cfg = config.read().await;
+        let slow_enabled = cfg.gpu.enabled || cfg.disk.enabled;
+        drop(cfg);
+        if slow_enabled {
+            let mut daemon = HardwareDaemon::new();
+            let token = cancel_token.clone();
+            spawn_poll_loop_simple!(
+                "slow_hw",
+                Duration::from_secs(5),
+                token,
+                daemon.poll_slow(&gpu_tx, &disks_tx)
+            );
+        }
+    }
+
+    #[cfg(feature = "mod-bt")]
+    if config.read().await.bt.enabled {
+        let mut daemon = BtDaemon::new();
+        let token = cancel_token.clone();
+        let h = Arc::clone(&health);
+        let poll_config = Arc::clone(&config);
+        let poll_receivers = receivers.clone();
+        spawn_poll_loop_triggered!("bt", Duration::from_secs(2), h, token, bt_force_rx, async {
+            let config = poll_config.read().await;
+            daemon.poll(&bt_tx, &poll_receivers, &config).await;
+            Ok(())
+        });
+    }
+
+    // Event-driven subsystems — these spawn their own threads internally and
+    // push into their watch sender as events arrive (no polling loop).
+    #[cfg(feature = "mod-audio")]
+    if config.read().await.audio.enabled {
+        let audio_daemon = AudioDaemon::new();
+        audio_daemon.start(&audio_tx, audio_cmd_rx);
+    }
+
+    #[cfg(feature = "mod-dbus")]
+    if config.read().await.backlight.enabled {
+        let backlight_daemon = BacklightDaemon::new();
+        backlight_daemon.start(backlight_tx);
+    }
+
+    #[cfg(feature = "mod-dbus")]
+    if config.read().await.keyboard.enabled {
+        let keyboard_daemon = KeyboardDaemon::new();
+        keyboard_daemon.start(keyboard_tx);
+    }
+
+    #[cfg(feature = "mod-dbus")]
+    if config.read().await.dnd.enabled {
+        let dnd_daemon = DndDaemon::new();
+        dnd_daemon.start(dnd_tx);
+    }
+
+    #[cfg(feature = "mod-dbus")]
+    if config.read().await.mpris.enabled {
+        let mpris_daemon = MprisDaemon::new();
+        mpris_daemon.start(mpris_tx);
+
+        // Ticks the scroll offset forward for the marquee animation.
+        let scroll_config = Arc::clone(&config);
+        let scroll_rx = receivers.mpris.clone();
+        let scroll_state = Arc::clone(&mpris_scroll);
+        tokio::spawn(async move {
+            crate::modules::mpris::mpris_scroll_ticker(
+                scroll_config,
+                scroll_rx,
+                scroll_state,
+                mpris_scroll_tick_tx,
+            )
+            .await;
+        });
+    }
+
+    let signaler = WaybarSignaler::new();
+    let sig_config = Arc::clone(&config);
+    let sig_receivers = receivers.clone();
+    tokio::spawn(async move {
+        info!("Starting Waybar Signaler task");
+        signaler.run(sig_config, sig_receivers).await;
+    });
+
+    info!("Fluxo daemon successfully bound to socket: {}", sock_path);
+    run_ipc_loop(listener, receivers, config, config_path, cancel_token).await
+}
+
+/// Spawn background tasks that hot-reload the daemon's [`Config`].
+///
+/// Installs a `notify`-based filesystem watcher on the config file's parent
+/// directory, plus a `SIGHUP` handler — either triggers a reload of the
+/// shared `Arc<RwLock<Config>>`.
+fn spawn_config_watchers(config: &Arc<RwLock<Config>>, resolved_path: &std::path::Path) {
+    // `notify` recursively tracks the parent dir so atomic-write editors
+    // (which rename a new file into place) still get picked up.
+    let watcher_config = Arc::clone(config);
+    let watcher_path = resolved_path.to_path_buf();
     tokio::spawn(async move {
         let (ev_tx, mut ev_rx) = mpsc::channel(1);
         let mut watcher = RecommendedWatcher::new(
@@ -159,7 +390,7 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
         loop {
             tokio::select! {
                 _ = ev_rx.recv() => {
-                    // Debounce reloads
+                    // Coalesce rapid editor writes into one reload.
                     sleep(Duration::from_millis(100)).await;
                     while ev_rx.try_recv().is_ok() {}
                     reload_config(&watcher_config, Some(watcher_path.clone())).await;
@@ -168,9 +399,8 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
         }
     });
 
-    // 0.1 SIGHUP Handler
-    let hup_config = Arc::clone(&config);
-    let hup_path = resolved_config_path.clone();
+    let hup_config = Arc::clone(config);
+    let hup_path = resolved_path.to_path_buf();
     tokio::spawn(async move {
         use tokio::signal::unix::{SignalKind, signal};
         let mut stream = signal(SignalKind::hangup()).unwrap();
@@ -180,157 +410,24 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
             reload_config(&hup_config, Some(hup_path.clone())).await;
         }
     });
+}
 
-    // 1. Network Task
-    #[cfg(feature = "mod-network")]
-    if config.read().await.network.enabled {
-        let token = cancel_token.clone();
-        let net_health = Arc::clone(&health);
-        tokio::spawn(async move {
-            info!("Starting Network polling task");
-            let mut daemon = NetworkDaemon::new();
-            loop {
-                if !crate::health::is_poll_in_backoff("net", &net_health).await {
-                    let res = daemon.poll(&net_tx).await;
-                    crate::health::handle_poll_result("net", res, &net_health).await;
-                }
-                tokio::select! {
-                    _ = token.cancelled() => break,
-                    _ = sleep(Duration::from_secs(1)) => {}
-                }
-            }
-            info!("Network task shut down.");
-        });
-    }
-
-    // 2. Fast Hardware Task (CPU, Mem, Load)
-    #[cfg(feature = "mod-hardware")]
-    {
-        let cfg = config.read().await;
-        let fast_enabled = cfg.cpu.enabled || cfg.memory.enabled || cfg.sys.enabled;
-        drop(cfg);
-        if fast_enabled {
-            let token = cancel_token.clone();
-            let hw_health = Arc::clone(&health);
-            tokio::spawn(async move {
-                info!("Starting Fast Hardware polling task");
-                let mut daemon = HardwareDaemon::new();
-                loop {
-                    if !crate::health::is_poll_in_backoff("cpu", &hw_health).await {
-                        daemon.poll_fast(&cpu_tx, &mem_tx, &sys_tx).await;
-                    }
-                    tokio::select! {
-                        _ = token.cancelled() => break,
-                        _ = sleep(Duration::from_secs(1)) => {}
-                    }
-                }
-                info!("Fast Hardware task shut down.");
-            });
-        }
-    }
-
-    // 3. Slow Hardware Task (GPU, Disks)
-    #[cfg(feature = "mod-hardware")]
-    {
-        let cfg = config.read().await;
-        let slow_enabled = cfg.gpu.enabled || cfg.disk.enabled;
-        drop(cfg);
-        if slow_enabled {
-            let token = cancel_token.clone();
-            let slow_health = Arc::clone(&health);
-            tokio::spawn(async move {
-                info!("Starting Slow Hardware polling task");
-                let mut daemon = HardwareDaemon::new();
-                loop {
-                    if !crate::health::is_poll_in_backoff("gpu", &slow_health).await {
-                        daemon.poll_slow(&gpu_tx, &disks_tx).await;
-                    }
-                    tokio::select! {
-                        _ = token.cancelled() => break,
-                        _ = sleep(Duration::from_secs(5)) => {}
-                    }
-                }
-                info!("Slow Hardware task shut down.");
-            });
-        }
-    }
-
-    // 4. Bluetooth Task
-    #[cfg(feature = "mod-bt")]
-    if config.read().await.bt.enabled {
-        let token = cancel_token.clone();
-        let bt_health = Arc::clone(&health);
-        let poll_config = Arc::clone(&config);
-        let poll_receivers = receivers.clone();
-        tokio::spawn(async move {
-            info!("Starting Bluetooth polling task");
-            let mut daemon = BtDaemon::new();
-            loop {
-                if !crate::health::is_poll_in_backoff("bt", &bt_health).await {
-                    let config = poll_config.read().await;
-                    daemon.poll(&bt_tx, &poll_receivers, &config).await;
-                }
-                tokio::select! {
-                    _ = token.cancelled() => break,
-                    _ = bt_force_rx.recv() => {},
-                    _ = sleep(Duration::from_secs(2)) => {}
-                }
-            }
-            info!("Bluetooth task shut down.");
-        });
-    }
-
-    // 5. Audio Thread (Event driven)
-    #[cfg(feature = "mod-audio")]
-    if config.read().await.audio.enabled {
-        let audio_daemon = AudioDaemon::new();
-        audio_daemon.start(&audio_tx, audio_cmd_rx);
-    }
-
-    // 5.1 Backlight Thread (Event driven)
-    #[cfg(feature = "mod-dbus")]
-    if config.read().await.backlight.enabled {
-        let backlight_daemon = BacklightDaemon::new();
-        backlight_daemon.start(backlight_tx);
-    }
-
-    // 5.2 Keyboard Thread (Event driven)
-    #[cfg(feature = "mod-dbus")]
-    if config.read().await.keyboard.enabled {
-        let keyboard_daemon = KeyboardDaemon::new();
-        keyboard_daemon.start(keyboard_tx);
-    }
-
-    // 5.3 DND Thread (Event driven)
-    #[cfg(feature = "mod-dbus")]
-    if config.read().await.dnd.enabled {
-        let dnd_daemon = DndDaemon::new();
-        dnd_daemon.start(dnd_tx);
-    }
-
-    // 5.4 MPRIS Thread
-    #[cfg(feature = "mod-dbus")]
-    if config.read().await.mpris.enabled {
-        let mpris_daemon = MprisDaemon::new();
-        mpris_daemon.start(mpris_tx);
-    }
-
-    // 6. Waybar Signaler Task
-    let signaler = WaybarSignaler::new();
-    let sig_config = Arc::clone(&config);
-    let sig_receivers = receivers.clone();
-    tokio::spawn(async move {
-        info!("Starting Waybar Signaler task");
-        signaler.run(sig_config, sig_receivers).await;
-    });
-
-    info!("Fluxo daemon successfully bound to socket: {}", sock_path);
-
+/// Accept loop for the client Unix socket.
+///
+/// Each client request spawns a short-lived task that reads one line, looks
+/// up the module via [`crate::registry::dispatch`], and writes the JSON
+/// response back. Broken-pipe errors are logged at `debug` — they just mean
+/// the client timed out before we responded.
+async fn run_ipc_loop(
+    listener: UnixListener,
+    receivers: AppReceivers,
+    config: Arc<RwLock<Config>>,
+    config_path: Option<PathBuf>,
+    cancel_token: CancellationToken,
+) -> Result<()> {
     loop {
         tokio::select! {
-            _ = cancel_token.cancelled() => {
-                break;
-            }
+            _ = cancel_token.cancelled() => break,
             res = listener.accept() => {
                 match res {
                     Ok((mut stream, _)) => {
@@ -387,6 +484,7 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
     Ok(())
 }
 
+/// Re-read the configuration file and swap it into the shared lock.
 pub async fn reload_config(config_lock: &Arc<RwLock<Config>>, path: Option<PathBuf>) {
     info!("Reloading configuration...");
     let new_config = crate::config::load_config(path);
@@ -395,6 +493,10 @@ pub async fn reload_config(config_lock: &Arc<RwLock<Config>>, path: Option<PathB
     info!("Configuration reloaded successfully.");
 }
 
+/// Evaluate a module with its signaler-default args and return the JSON body.
+///
+/// Used by the [`crate::signaler`] to decide whether the module's output has
+/// actually changed before sending Waybar a signal.
 pub async fn evaluate_module_for_signaler(
     module_name: &str,
     state: &AppReceivers,

src/error.rs

@@ -1,5 +1,11 @@
+//! Error types used across the crate.
+
 use thiserror::Error;
 
+/// Canonical error type for all fluxo subsystems.
+///
+/// Errors are categorised so that [`FluxoError::is_transient`] can distinguish
+/// temporary runtime failures (retried with backoff) from permanent ones.
 #[derive(Error, Debug)]
 #[allow(dead_code)]
 pub enum FluxoError {
@@ -41,6 +47,9 @@ pub enum FluxoError {
 }
 
 impl FluxoError {
+    /// Returns `true` for errors that represent likely-transient failures
+    /// (IO, external systems, hardware) and should trigger exponential backoff
+    /// rather than permanent cooldown.
     pub fn is_transient(&self) -> bool {
         matches!(
             self,
@@ -54,4 +63,5 @@ impl FluxoError {
     }
 }
 
+/// Crate-wide `Result` alias using [`FluxoError`].
 pub type Result<T> = std::result::Result<T, FluxoError>;

src/health.rs

@@ -1,3 +1,10 @@
+//! Per-module health tracking and exponential backoff.
+//!
+//! Both the IPC request handler (for on-demand module evaluation) and the
+//! background polling loops consult this module. Transient errors increment a
+//! failure counter that grows the cooldown window; permanent errors trigger an
+//! immediate long cooldown.
+
 use crate::output::WaybarOutput;
 use crate::state::{AppReceivers, ModuleHealth};
 use std::collections::HashMap;
@@ -101,6 +108,10 @@ pub async fn handle_poll_result(
     }
 }
 
+/// Serialise a response to return while a module is cooling down.
+///
+/// If a cached successful output exists, it is returned with a `warning` CSS
+/// class appended; otherwise a generic "Cooling down" placeholder is emitted.
 pub fn backoff_response(module_name: &str, cached: Option<WaybarOutput>) -> String {
     if let Some(mut cached) = cached {
         let class = cached.class.unwrap_or_default();
@@ -113,6 +124,10 @@ pub fn backoff_response(module_name: &str, cached: Option<WaybarOutput>) -> Stri
     )
 }
 
+/// Serialise a fallback response for a module that errored this request.
+///
+/// Prefers showing the last successful cached output (with a `warning` class)
+/// over a bare error text, to keep the bar visually stable.
 pub fn error_response(
     module_name: &str,
     e: &crate::error::FluxoError,

src/ipc.rs

@@ -1,8 +1,16 @@
+//! Client/daemon Unix socket IPC.
+//!
+//! Requests are newline-terminated `module arg1 arg2...` lines; responses are
+//! the daemon's JSON payload written until EOF.
+
 use std::io::{Read, Write};
 use std::os::unix::net::UnixStream;
 use std::time::Duration;
 use tracing::debug;
 
+/// Returns the path to the daemon's Unix socket.
+///
+/// Prefers `$XDG_RUNTIME_DIR/fluxo.sock`, falling back to `/tmp/fluxo.sock`.
 pub fn socket_path() -> String {
     if let Ok(dir) = std::env::var("XDG_RUNTIME_DIR") {
         format!("{}/fluxo.sock", dir)
@@ -11,13 +19,15 @@ pub fn socket_path() -> String {
     }
 }
 
+/// Send a module invocation to the daemon and return its response body.
+///
+/// Blocks for up to 5 seconds waiting for the daemon to reply.
 pub fn request_data(module: &str, args: &[&str]) -> anyhow::Result<String> {
     let sock = socket_path();
     debug!(module, ?args, "Connecting to daemon socket: {}", sock);
     let mut stream = UnixStream::connect(&sock)?;
     stream.set_read_timeout(Some(Duration::from_secs(5)))?;
 
-    // Send module and args
     let mut request = module.to_string();
     for arg in args {
         request.push(' ');

src/macros.rs

@@ -0,0 +1,43 @@
+//! Central declarative macro that registers every watched module.
+//!
+//! Every piece of per-module boilerplate (AppReceivers field, IPC dispatch arm,
+//! signaler future binding, signaler select arm, config enabled-lookup, default
+//! signaler args) is generated from this single table. Adding a new module is
+//! a one-line edit here plus writing the module file itself.
+
+/// Central module registry. Defines all modules with watch channels in one place.
+///
+/// Invoke with a callback macro name. The callback receives repeated entries of the form:
+///   { $feature:literal, $field:ident, $state:ty, [$($name:literal),+], [$($sig_name:literal),+], $module:path, $signal:ident, [$($default_arg:literal),*], $config:ident }
+///
+/// Fields:
+///   - feature:       Cargo feature gate (e.g., "mod-network")
+///   - field:         AppReceivers field name (e.g., network)
+///   - state:         State type for the watch channel (e.g., NetworkState)
+///   - names:         CLI name aliases for dispatch (e.g., ["net", "network"])
+///   - signaler_names: Waybar module names to signal when the channel fires
+///     (usually [first dispatch name], but audio signals ["vol", "mic"])
+///   - module:        Module struct implementing WaybarModule (e.g., network::NetworkModule)
+///   - signal:        SignalsConfig field name (e.g., network)
+///   - default_args:  Default args for signaler evaluation
+///   - config:        Config section field name (e.g., network)
+///
+/// Modules without watch channels (power, game, pool/btrfs) are handled manually.
+macro_rules! for_each_watched_module {
+    ($m:ident) => {
+        $m! {
+            { "mod-network",  network,   crate::state::NetworkState,       ["net", "network"],  ["net"],        crate::modules::network::NetworkModule,     network,   [],               network   }
+            { "mod-hardware", cpu,       crate::state::CpuState,           ["cpu"],             ["cpu"],        crate::modules::cpu::CpuModule,             cpu,       [],               cpu       }
+            { "mod-hardware", memory,    crate::state::MemoryState,        ["mem", "memory"],   ["mem"],        crate::modules::memory::MemoryModule,       memory,    [],               memory    }
+            { "mod-hardware", sys,       crate::state::SysState,           ["sys"],             ["sys"],        crate::modules::sys::SysModule,             sys,       [],               sys       }
+            { "mod-hardware", gpu,       crate::state::GpuState,           ["gpu"],             ["gpu"],        crate::modules::gpu::GpuModule,             gpu,       [],               gpu       }
+            { "mod-hardware", disks,     Vec<crate::state::DiskInfo>,      ["disk"],            ["disk"],       crate::modules::disk::DiskModule,           disk,      ["/"],            disk      }
+            { "mod-bt",       bluetooth, crate::state::BtState,            ["bt", "bluetooth"], ["bt"],         crate::modules::bt::BtModule,               bt,        ["show"],         bt        }
+            { "mod-audio",    audio,     crate::state::AudioState,         ["vol", "audio"],    ["vol", "mic"], crate::modules::audio::AudioModule,         audio,     ["sink", "show"], audio     }
+            { "mod-dbus",     mpris,     crate::state::MprisState,         ["mpris"],           ["mpris"],      crate::modules::mpris::MprisModule,         mpris,     [],               mpris     }
+            { "mod-dbus",     backlight, crate::state::BacklightState,     ["backlight"],       ["backlight"],  crate::modules::backlight::BacklightModule, backlight, [],               backlight }
+            { "mod-dbus",     keyboard,  crate::state::KeyboardState,      ["kbd", "keyboard"], ["kbd"],        crate::modules::keyboard::KeyboardModule,   keyboard,  [],               keyboard  }
+            { "mod-dbus",     dnd,       crate::state::DndState,           ["dnd"],             ["dnd"],        crate::modules::dnd::DndModule,             dnd,       [],               dnd       }
+        }
+    };
+}

src/main.rs

@@ -1,3 +1,19 @@
+//! `fluxo` — high-performance daemon/client for Waybar custom modules.
+//!
+//! The binary has two faces:
+//! * `fluxo daemon` — starts a long-lived process that polls system state
+//!   (network, cpu, audio, bluetooth, …) on background tasks and exposes the
+//!   results over a Unix socket. It also sends `SIGRTMIN+N` signals to Waybar
+//!   when module output changes, so the bar refreshes instantly.
+//! * `fluxo <module> [args]` — a tiny client that asks the daemon to evaluate
+//!   a single module and prints the Waybar-compatible JSON to stdout.
+//!
+//! Modules are feature-gated at compile time (`mod-audio`, `mod-bt`, `mod-dbus`,
+//! `mod-hardware`, `mod-network`) and registered centrally via the
+//! [`for_each_watched_module!`] macro in [`mod@macros`].
+
+#[macro_use]
+mod macros;
 mod config;
 mod daemon;
 mod error;
@@ -77,49 +93,83 @@ fn main() {
     }
 
     if let Some(module) = &cli.module {
-        // Special case for client-side Bluetooth menu which requires UI
+        // Bluetooth menu is handled client-side: it needs access to the user's
+        // menu command (rofi/dmenu/wofi) which the daemon has no business spawning.
         #[cfg(feature = "mod-bt")]
         if module == "bt" && cli.args.first().map(|s| s.as_str()) == Some("menu") {
             let config = config::load_config(None);
             let mut items = Vec::new();
 
-            if let Ok(json_str) = ipc::request_data("bt", &["get_modes"])
-                && let Ok(val) = serde_json::from_str::<serde_json::Value>(&json_str)
-                && let Some(modes_str) = val.get("text").and_then(|t| t.as_str())
-                && !modes_str.is_empty()
-            {
-                for mode in modes_str.lines() {
-                    items.push(format!("Mode: {}", mode));
-                }
-            }
-
-            if !items.is_empty() {
-                items.push("Disconnect".to_string());
-            }
-
-            items.push("--- Connect Device ---".to_string());
+            // Ask the daemon for the device list; tuples are (alias, mac).
+            let mut connected: Vec<(String, String)> = Vec::new();
+            let mut paired: Vec<(String, String)> = Vec::new();
 
             if let Ok(json_str) = ipc::request_data("bt", &["menu_data"])
                 && let Ok(val) = serde_json::from_str::<serde_json::Value>(&json_str)
-                && let Some(devices_str) = val.get("text").and_then(|t| t.as_str())
+                && let Some(text) = val.get("text").and_then(|t| t.as_str())
             {
-                for line in devices_str.lines() {
-                    if !line.is_empty() {
-                        items.push(line.to_string());
+                for line in text.lines() {
+                    if let Some(rest) = line.strip_prefix("CONNECTED:")
+                        && let Some((alias, mac)) = rest.split_once('|')
+                    {
+                        connected.push((alias.to_string(), mac.to_string()));
+                    } else if let Some(rest) = line.strip_prefix("PAIRED:")
+                        && let Some((alias, mac)) = rest.split_once('|')
+                    {
+                        paired.push((alias.to_string(), mac.to_string()));
                     }
                 }
             }
 
+            for (alias, mac) in &connected {
+                if let Ok(json_str) = ipc::request_data("bt", &["get_modes", mac])
+                    && let Ok(val) = serde_json::from_str::<serde_json::Value>(&json_str)
+                    && let Some(modes_str) = val.get("text").and_then(|t| t.as_str())
+                    && !modes_str.is_empty()
+                {
+                    for mode in modes_str.lines() {
+                        items.push(format!("{}: Mode: {} [{}]", alias, mode, mac));
+                    }
+                }
+                items.push(format!("Disconnect {} [{}]", alias, mac));
+            }
+
+            if !paired.is_empty() {
+                items.push("--- Connect Device ---".to_string());
+                for (alias, mac) in &paired {
+                    items.push(format!("{} ({})", alias, mac));
+                }
+            }
+
             if !items.is_empty() {
                 if let Ok(selected) =
                     utils::show_menu("BT Menu: ", &items, &config.general.menu_command)
                 {
-                    if let Some(mode) = selected.strip_prefix("Mode: ") {
-                        handle_ipc_response(ipc::request_data("bt", &["set_mode", mode]));
-                    } else if selected == "Disconnect" {
-                        handle_ipc_response(ipc::request_data("bt", &["disconnect"]));
+                    if selected.contains(": Mode: ") {
+                        // Parse "<alias>: Mode: <mode> [<MAC>]".
+                        if let Some(bracket_start) = selected.rfind('[')
+                            && let Some(bracket_end) = selected.rfind(']')
+                        {
+                            let mac = &selected[bracket_start + 1..bracket_end];
+                            if let Some(mode_start) = selected.find(": Mode: ") {
+                                let mode =
+                                    &selected[mode_start + ": Mode: ".len()..bracket_start - 1];
+                                handle_ipc_response(ipc::request_data(
+                                    "bt",
+                                    &["set_mode", mode, mac],
+                                ));
+                            }
+                        }
+                    } else if selected.starts_with("Disconnect ") {
+                        // Parse "Disconnect <alias> [<MAC>]".
+                        if let Some(bracket_start) = selected.rfind('[')
+                            && let Some(bracket_end) = selected.rfind(']')
+                        {
+                            let mac = &selected[bracket_start + 1..bracket_end];
+                            handle_ipc_response(ipc::request_data("bt", &["disconnect", mac]));
+                        }
                     } else if selected == "--- Connect Device ---" {
-                        // Do nothing
+                        // section header
                     } else if let Some(mac_start) = selected.rfind('(')
                         && let Some(mac_end) = selected.rfind(')')
                     {
@@ -133,8 +183,8 @@ fn main() {
             return;
         }
 
-        // Generic module dispatch
-        // Translate module-specific shorthand targets
+        // `vol` and `mic` both dispatch to the audio module; we just prepend
+        // the "sink" / "source" argument so the server picks the right device.
         let (actual_module, actual_args) = if module == "vol" {
             let mut new_args = vec!["sink".to_string()];
             new_args.extend(cli.args.clone());
@@ -155,6 +205,13 @@ fn main() {
     }
 }
 
+/// Post-process the daemon's response for direct output to Waybar.
+///
+/// Normal spaces are replaced with figure-spaces (U+2007) so Waybar's
+/// proportional font does not jitter between updates, and the text is wrapped
+/// in zero-width spaces (U+200B) as a cosmetic padding trick. Markup strings
+/// (containing `<`) pass through untouched. On IPC failure an `error` output
+/// is emitted and the client exits non-zero.
 fn handle_ipc_response(response: anyhow::Result<String>) {
     match response {
         Ok(json_str) => match serde_json::from_str::<serde_json::Value>(&json_str) {

src/modules/audio.rs

@@ -2,13 +2,14 @@ use crate::config::Config;
 use crate::error::{FluxoError, Result};
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
-use crate::state::{AppReceivers, AudioState};
+use crate::state::{AppReceivers, AudioDeviceInfo, AudioState};
 use crate::utils::{TokenValue, format_template};
 use libpulse_binding::callbacks::ListResult;
 use libpulse_binding::context::subscribe::{Facility, InterestMaskSet};
 use libpulse_binding::context::{Context, FlagSet as ContextFlag};
 use libpulse_binding::mainloop::threaded::Mainloop as ThreadedMainloop;
 use libpulse_binding::volume::Volume;
+use std::sync::Arc;
 use tokio::sync::{mpsc, watch};
 use tracing::error;
 
@@ -229,92 +230,124 @@ fn fetch_audio_data_sync(
         let _ = tx_server.send(current);
     });
 
-    let tx_sink = state_tx.clone();
-    context.introspect().get_sink_info_list(move |res| {
-        let mut current = tx_sink.borrow().clone();
-        match res {
-            ListResult::Item(item) => {
-                if let Some(name) = item.name.as_ref() {
-                    let name_str = name.to_string();
-                    if !current.available_sinks.contains(&name_str) {
-                        current.available_sinks.push(name_str);
-                    }
-                }
-
-                let is_default = item
-                    .name
-                    .as_ref()
-                    .map(|s| s.as_ref() == current.sink.name)
-                    .unwrap_or(false);
-                if is_default {
-                    current.sink.description = item
-                        .description
-                        .as_ref()
-                        .map(|s| s.to_string())
-                        .unwrap_or_default();
-                    current.sink.volume = ((item.volume.avg().0 as f64 / Volume::NORMAL.0 as f64)
-                        * 100.0)
-                        .round() as u8;
-                    current.sink.muted = item.mute;
-                    current.sink.channels = item.volume.len();
-                }
-                let _ = tx_sink.send(current);
-            }
-            ListResult::End => {
-                // Clear the list on End so it rebuilds fresh next time
-                current.available_sinks.clear();
-                let _ = tx_sink.send(current);
-            }
-            ListResult::Error => {}
-        }
-    });
-
-    let tx_source = state_tx.clone();
-    context.introspect().get_source_info_list(move |res| {
-        let mut current = tx_source.borrow().clone();
-        match res {
-            ListResult::Item(item) => {
-                if let Some(name) = item.name.as_ref() {
-                    let name_str = name.to_string();
-                    // PulseAudio includes monitor sources, ignore them if we want to
-                    if !name_str.contains(".monitor")
-                        && !current.available_sources.contains(&name_str)
-                    {
-                        current.available_sources.push(name_str);
-                    }
-                }
-
-                let is_default = item
-                    .name
-                    .as_ref()
-                    .map(|s| s.as_ref() == current.source.name)
-                    .unwrap_or(false);
-                if is_default {
-                    current.source.description = item
-                        .description
-                        .as_ref()
-                        .map(|s| s.to_string())
-                        .unwrap_or_default();
-                    current.source.volume = ((item.volume.avg().0 as f64 / Volume::NORMAL.0 as f64)
-                        * 100.0)
-                        .round() as u8;
-                    current.source.muted = item.mute;
-                    current.source.channels = item.volume.len();
-                }
-                let _ = tx_source.send(current);
-            }
-            ListResult::End => {
-                // Clear the list on End so it rebuilds fresh next time
-                current.available_sources.clear();
-                let _ = tx_source.send(current);
-            }
-            ListResult::Error => {}
-        }
-    });
+    fetch_sinks(context, state_tx);
+    fetch_sources(context, state_tx);
 
     Ok(())
 }
 
+/// Shared bookkeeping for a device list fetch.
+struct PendingList {
+    names: Arc<std::sync::Mutex<Vec<String>>>,
+}
+
+impl PendingList {
+    fn new() -> Self {
+        Self {
+            names: Arc::new(std::sync::Mutex::new(Vec::new())),
+        }
+    }
+
+    fn push(&self, name: String) {
+        self.names.lock().unwrap().push(name);
+    }
+
+    fn drain(&self) -> Vec<String> {
+        self.names.lock().unwrap().drain(..).collect()
+    }
+}
+
+/// Extract common device info from a pulse item's volume/mute/description fields.
+fn device_info_from(
+    description: Option<&str>,
+    volume: &libpulse_binding::volume::ChannelVolumes,
+    muted: bool,
+) -> (String, u8, bool, u8) {
+    let desc = description.unwrap_or_default().to_string();
+    let vol = ((volume.avg().0 as f64 / Volume::NORMAL.0 as f64) * 100.0).round() as u8;
+    let channels = volume.len();
+    (desc, vol, muted, channels)
+}
+
+fn apply_device_info(target: &mut AudioDeviceInfo, item_name: &str, info: (String, u8, bool, u8)) {
+    if item_name == target.name {
+        target.description = info.0;
+        target.volume = info.1;
+        target.muted = info.2;
+        target.channels = info.3;
+    }
+}
+
+fn fetch_sinks(context: &mut Context, state_tx: &watch::Sender<AudioState>) {
+    let tx = state_tx.clone();
+    let pending = PendingList::new();
+    let pending_cb = PendingList {
+        names: Arc::clone(&pending.names),
+    };
+    context.introspect().get_sink_info_list(move |res| {
+        let mut current = tx.borrow().clone();
+        match res {
+            ListResult::Item(item) => {
+                let name_str = item
+                    .name
+                    .as_ref()
+                    .map(|s| s.to_string())
+                    .unwrap_or_default();
+                if !name_str.is_empty() {
+                    pending_cb.push(name_str.clone());
+                }
+                let info = device_info_from(
+                    item.description.as_ref().map(|s| s.as_ref()),
+                    &item.volume,
+                    item.mute,
+                );
+                apply_device_info(&mut current.sink, &name_str, info);
+                let _ = tx.send(current);
+            }
+            ListResult::End => {
+                current.available_sinks = pending_cb.drain();
+                let _ = tx.send(current);
+            }
+            ListResult::Error => {}
+        }
+    });
+}
+
+fn fetch_sources(context: &mut Context, state_tx: &watch::Sender<AudioState>) {
+    let tx = state_tx.clone();
+    let pending = PendingList::new();
+    let pending_cb = PendingList {
+        names: Arc::clone(&pending.names),
+    };
+    context.introspect().get_source_info_list(move |res| {
+        let mut current = tx.borrow().clone();
+        match res {
+            ListResult::Item(item) => {
+                let name_str = item
+                    .name
+                    .as_ref()
+                    .map(|s| s.to_string())
+                    .unwrap_or_default();
+                if !name_str.is_empty() && !name_str.contains(".monitor") {
+                    pending_cb.push(name_str.clone());
+                }
+                let info = device_info_from(
+                    item.description.as_ref().map(|s| s.as_ref()),
+                    &item.volume,
+                    item.mute,
+                );
+                apply_device_info(&mut current.source, &name_str, info);
+                let _ = tx.send(current);
+            }
+            ListResult::End => {
+                current.available_sources = pending_cb.drain();
+                let _ = tx.send(current);
+            }
+            ListResult::Error => {}
+        }
+    });
+}
+
 pub struct AudioModule;
 
 impl WaybarModule for AudioModule {
@@ -331,19 +364,19 @@ impl WaybarModule for AudioModule {
         match *action {
             "up" => {
                 self.change_volume(state, target_type, step, true).await?;
-                Ok(WaybarOutput::default())
+                self.get_status(config, state, target_type).await
             }
             "down" => {
                 self.change_volume(state, target_type, step, false).await?;
-                Ok(WaybarOutput::default())
+                self.get_status(config, state, target_type).await
             }
             "mute" => {
                 self.toggle_mute(state, target_type).await?;
-                Ok(WaybarOutput::default())
+                self.get_status(config, state, target_type).await
             }
             "cycle" => {
                 self.cycle_device(state, target_type).await?;
-                Ok(WaybarOutput::default())
+                self.get_status(config, state, target_type).await
             }
             "show" => self.get_status(config, state, target_type).await,
             other => Err(FluxoError::Module {

src/modules/bt/mod.rs

@@ -5,7 +5,7 @@ use crate::config::Config;
 use crate::error::Result as FluxoResult;
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
-use crate::state::{AppReceivers, BtState};
+use crate::state::{AppReceivers, BtDeviceInfo, BtState};
 use crate::utils::{TokenValue, format_template};
 use anyhow::Result;
 use std::sync::LazyLock;
@@ -47,60 +47,64 @@ impl BtDaemon {
         let adapter = session.default_adapter().await?;
         let adapter_powered = adapter.is_powered().await.unwrap_or(false);
 
-        let mut bt_state = BtState {
-            adapter_powered,
-            ..Default::default()
-        };
+        let mut connected_devices = Vec::new();
 
         if adapter_powered {
-            let devices = adapter.device_addresses().await?;
-            for addr in devices {
-                let device = adapter.device(addr)?;
-                if device.is_connected().await.unwrap_or(false) {
-                    let uuids = device.uuids().await?.unwrap_or_default();
-                    let audio_sink_uuid =
-                        bluer::Uuid::from_u128(0x0000110b_0000_1000_8000_00805f9b34fb);
-                    if uuids.contains(&audio_sink_uuid) {
-                        bt_state.connected = true;
-                        bt_state.device_address = addr.to_string();
-                        bt_state.device_alias =
-                            device.alias().await.unwrap_or_else(|_| addr.to_string());
-                        bt_state.battery_percentage =
-                            device.battery_percentage().await.unwrap_or(None);
+            let mut addresses = adapter.device_addresses().await?;
+            addresses.sort();
+            let audio_sink_uuid = bluer::Uuid::from_u128(0x0000110b_0000_1000_8000_00805f9b34fb);
 
-                        for p in PLUGINS.iter() {
-                            if p.can_handle(&bt_state.device_alias, &bt_state.device_address) {
-                                match p.get_data(config, state, &bt_state.device_address).await {
-                                    Ok(data) => {
-                                        bt_state.plugin_data = data
-                                            .into_iter()
-                                            .map(|(k, v)| {
-                                                let val_str = match v {
-                                                    TokenValue::String(s) => s,
-                                                    TokenValue::Int(i) => i.to_string(),
-                                                    TokenValue::Float(f) => format!("{:.1}", f),
-                                                };
-                                                (k, val_str)
-                                            })
-                                            .collect();
-                                    }
-                                    Err(e) => {
-                                        warn!("Plugin {} failed for {}: {}", p.name(), addr, e);
-                                        bt_state
-                                            .plugin_data
-                                            .push(("plugin_error".to_string(), e.to_string()));
-                                    }
-                                }
-                                break;
+            for addr in addresses {
+                let device = adapter.device(addr)?;
+                if !device.is_connected().await.unwrap_or(false) {
+                    continue;
+                }
+                let uuids = device.uuids().await?.unwrap_or_default();
+                if !uuids.contains(&audio_sink_uuid) {
+                    continue;
+                }
+
+                let mut dev_info = BtDeviceInfo {
+                    device_address: addr.to_string(),
+                    device_alias: device.alias().await.unwrap_or_else(|_| addr.to_string()),
+                    battery_percentage: device.battery_percentage().await.unwrap_or(None),
+                    plugin_data: vec![],
+                };
+
+                for p in PLUGINS.iter() {
+                    if p.can_handle(&dev_info.device_alias, &dev_info.device_address) {
+                        match p.get_data(config, state, &dev_info.device_address).await {
+                            Ok(data) => {
+                                dev_info.plugin_data = data
+                                    .into_iter()
+                                    .map(|(k, v)| {
+                                        let val_str = match v {
+                                            TokenValue::String(s) => s,
+                                            TokenValue::Int(i) => i.to_string(),
+                                            TokenValue::Float(f) => format!("{:.1}", f),
+                                        };
+                                        (k, val_str)
+                                    })
+                                    .collect();
+                            }
+                            Err(e) => {
+                                warn!("Plugin {} failed for {}: {}", p.name(), addr, e);
+                                dev_info
+                                    .plugin_data
+                                    .push(("plugin_error".to_string(), e.to_string()));
                             }
                         }
                         break;
                     }
                 }
+                connected_devices.push(dev_info);
             }
         }
 
-        let _ = tx.send(bt_state);
+        let _ = tx.send(BtState {
+            adapter_powered,
+            devices: connected_devices,
+        });
 
         Ok(())
     }
@@ -111,8 +115,6 @@ static PLUGINS: LazyLock<Vec<Box<dyn BtPlugin>>> =
 
 fn trigger_robust_poll(state: AppReceivers) {
     tokio::spawn(async move {
-        // Poll immediately and then a few times over the next few seconds
-        // to catch slow state changes in bluez or plugins.
         for delay in [200, 500, 1000, 2000, 3000] {
             tokio::time::sleep(std::time::Duration::from_millis(delay)).await;
             let _ = state.bt_force_poll.try_send(());
@@ -120,6 +122,26 @@ fn trigger_robust_poll(state: AppReceivers) {
     });
 }
 
+/// Resolve a target MAC: use explicit arg if given, otherwise fall back to the active device.
+async fn resolve_target_mac(
+    bt_state: &BtState,
+    state: &AppReceivers,
+    explicit_mac: Option<&str>,
+) -> Option<String> {
+    if let Some(mac) = explicit_mac {
+        return Some(mac.to_string());
+    }
+    let idx = *state.bt_cycle.read().await;
+    bt_state
+        .active_device(idx)
+        .map(|d| d.device_address.clone())
+}
+
+/// Find a device in the current state by MAC.
+fn find_device<'a>(bt_state: &'a BtState, mac: &str) -> Option<&'a BtDeviceInfo> {
+    bt_state.devices.iter().find(|d| d.device_address == mac)
+}
+
 pub struct BtModule;
 
 impl WaybarModule for BtModule {
@@ -129,12 +151,10 @@ impl WaybarModule for BtModule {
         state: &AppReceivers,
         args: &[&str],
     ) -> FluxoResult<WaybarOutput> {
-        let action = args.first().cloned().unwrap_or("show").to_string();
-        let args = args.iter().map(|s| s.to_string()).collect::<Vec<_>>();
-
+        let action = args.first().cloned().unwrap_or("show");
         let bt_state = state.bluetooth.borrow().clone();
 
-        match action.as_str() {
+        match action {
             "connect" => {
                 if let Some(mac) = args.get(1) {
                     if let Ok(session) = bluer::Session::new().await
@@ -148,77 +168,125 @@ impl WaybarModule for BtModule {
                 }
                 return Ok(WaybarOutput::default());
             }
-            "disconnect" if bt_state.connected => {
-                if let Ok(session) = bluer::Session::new().await
-                    && let Ok(adapter) = session.default_adapter().await
-                    && let Ok(addr) = bt_state.device_address.parse::<bluer::Address>()
-                    && let Ok(device) = adapter.device(addr)
-                {
-                    let _ = device.disconnect().await;
-                }
-                trigger_robust_poll(state.clone());
-                return Ok(WaybarOutput::default());
-            }
-            "menu_data" => {
-                let mut devs = Vec::new();
-                if let Ok(session) = bluer::Session::new().await
-                    && let Ok(adapter) = session.default_adapter().await
-                    && let Ok(addresses) = adapter.device_addresses().await
-                {
-                    for addr in addresses {
-                        if let Ok(device) = adapter.device(addr)
-                            && device.is_paired().await.unwrap_or(false)
-                        {
-                            let alias = device.alias().await.unwrap_or_else(|_| addr.to_string());
-                            devs.push(format!("{} ({})", alias, addr));
-                        }
+            "disconnect" => {
+                let target_mac = resolve_target_mac(&bt_state, state, args.get(1).copied()).await;
+                if let Some(mac) = target_mac {
+                    if let Ok(session) = bluer::Session::new().await
+                        && let Ok(adapter) = session.default_adapter().await
+                        && let Ok(addr) = mac.parse::<bluer::Address>()
+                        && let Ok(device) = adapter.device(addr)
+                    {
+                        let _ = device.disconnect().await;
                     }
-                }
-                return Ok(WaybarOutput {
-                    text: devs.join("\n"),
-                    ..Default::default()
-                });
-            }
-            "cycle_mode" if bt_state.connected => {
-                let plugin = PLUGINS
-                    .iter()
-                    .find(|p| p.can_handle(&bt_state.device_alias, &bt_state.device_address));
-                if let Some(p) = plugin {
-                    p.cycle_mode(&bt_state.device_address, state).await?;
                     trigger_robust_poll(state.clone());
                 }
                 return Ok(WaybarOutput::default());
             }
-            "get_modes" if bt_state.connected => {
-                let plugin = PLUGINS
-                    .iter()
-                    .find(|p| p.can_handle(&bt_state.device_alias, &bt_state.device_address));
-                let modes = if let Some(p) = plugin {
-                    p.get_modes(&bt_state.device_address, state).await?
-                } else {
-                    vec![]
-                };
+            "cycle" => {
+                let count = bt_state.devices.len();
+                if count > 1 {
+                    let mut idx = state.bt_cycle.write().await;
+                    *idx = (*idx + 1) % count;
+                }
+                let _ = state.bt_force_poll.try_send(());
+                return Ok(WaybarOutput::default());
+            }
+            "menu_data" => {
+                let mut lines = Vec::new();
+
+                // Connected devices
+                for dev in &bt_state.devices {
+                    lines.push(format!(
+                        "CONNECTED:{}|{}",
+                        dev.device_alias, dev.device_address
+                    ));
+                }
+
+                // Paired-but-not-connected devices
+                if let Ok(session) = bluer::Session::new().await
+                    && let Ok(adapter) = session.default_adapter().await
+                    && let Ok(addresses) = adapter.device_addresses().await
+                {
+                    let connected_macs: std::collections::HashSet<&str> = bt_state
+                        .devices
+                        .iter()
+                        .map(|d| d.device_address.as_str())
+                        .collect();
+
+                    for addr in addresses {
+                        let addr_str = addr.to_string();
+                        if connected_macs.contains(addr_str.as_str()) {
+                            continue;
+                        }
+                        if let Ok(device) = adapter.device(addr)
+                            && device.is_paired().await.unwrap_or(false)
+                        {
+                            let alias = device.alias().await.unwrap_or_else(|_| addr.to_string());
+                            lines.push(format!("PAIRED:{}|{}", alias, addr_str));
+                        }
+                    }
+                }
+
                 return Ok(WaybarOutput {
-                    text: modes.join("\n"),
+                    text: lines.join("\n"),
                     ..Default::default()
                 });
             }
-            "set_mode" if bt_state.connected => {
-                if let Some(mode) = args.get(1) {
+            "get_modes" => {
+                let target_mac = resolve_target_mac(&bt_state, state, args.get(1).copied()).await;
+                if let Some(mac) = target_mac
+                    && let Some(dev) = find_device(&bt_state, &mac)
+                {
                     let plugin = PLUGINS
                         .iter()
-                        .find(|p| p.can_handle(&bt_state.device_alias, &bt_state.device_address));
+                        .find(|p| p.can_handle(&dev.device_alias, &dev.device_address));
                     if let Some(p) = plugin {
-                        p.set_mode(mode, &bt_state.device_address, state).await?;
+                        let modes = p.get_modes(&mac, state).await?;
+                        return Ok(WaybarOutput {
+                            text: modes.join("\n"),
+                            ..Default::default()
+                        });
+                    }
+                }
+                return Ok(WaybarOutput::default());
+            }
+            "set_mode" => {
+                if let Some(mode) = args.get(1) {
+                    let target_mac =
+                        resolve_target_mac(&bt_state, state, args.get(2).copied()).await;
+                    if let Some(mac) = target_mac
+                        && let Some(dev) = find_device(&bt_state, &mac)
+                    {
+                        let plugin = PLUGINS
+                            .iter()
+                            .find(|p| p.can_handle(&dev.device_alias, &dev.device_address));
+                        if let Some(p) = plugin {
+                            p.set_mode(mode, &mac, state).await?;
+                            trigger_robust_poll(state.clone());
+                        }
+                    }
+                }
+                return Ok(WaybarOutput::default());
+            }
+            "cycle_mode" => {
+                let target_mac = resolve_target_mac(&bt_state, state, args.get(1).copied()).await;
+                if let Some(mac) = target_mac
+                    && let Some(dev) = find_device(&bt_state, &mac)
+                {
+                    let plugin = PLUGINS
+                        .iter()
+                        .find(|p| p.can_handle(&dev.device_alias, &dev.device_address));
+                    if let Some(p) = plugin {
+                        p.cycle_mode(&mac, state).await?;
                         trigger_robust_poll(state.clone());
                     }
                 }
                 return Ok(WaybarOutput::default());
             }
-            "show" => {}
             _ => {}
         }
 
+        // "show" and fallthrough
         if !bt_state.adapter_powered {
             return Ok(WaybarOutput {
                 text: config.bt.format_disabled.clone(),
@@ -228,22 +296,23 @@ impl WaybarModule for BtModule {
             });
         }
 
-        if bt_state.connected {
+        let cycle_idx = *state.bt_cycle.read().await;
+        if let Some(dev) = bt_state.active_device(cycle_idx) {
             let mut tokens: Vec<(String, TokenValue)> = vec![
                 (
                     "alias".to_string(),
-                    TokenValue::String(bt_state.device_alias.clone()),
+                    TokenValue::String(dev.device_alias.clone()),
                 ),
                 (
                     "mac".to_string(),
-                    TokenValue::String(bt_state.device_address.clone()),
+                    TokenValue::String(dev.device_address.clone()),
                 ),
             ];
 
             let mut class = vec!["connected".to_string()];
             let mut has_plugin = false;
 
-            for (k, v) in &bt_state.plugin_data {
+            for (k, v) in &dev.plugin_data {
                 if k == "plugin_class" {
                     class.push(v.clone());
                     has_plugin = true;
@@ -263,10 +332,9 @@ impl WaybarModule for BtModule {
             let text = format_template(format, &tokens);
             let tooltip = format!(
                 "{} | MAC: {}\nBattery: {}",
-                bt_state.device_alias,
-                bt_state.device_address,
-                bt_state
-                    .battery_percentage
+                dev.device_alias,
+                dev.device_address,
+                dev.battery_percentage
                     .map(|b| format!("{}%", b))
                     .unwrap_or_else(|| "N/A".to_string())
             );
@@ -275,7 +343,7 @@ impl WaybarModule for BtModule {
                 text,
                 tooltip: Some(tooltip),
                 class: Some(class.join(" ")),
-                percentage: bt_state.battery_percentage,
+                percentage: dev.battery_percentage,
             })
         } else {
             Ok(WaybarOutput {

src/modules/dnd.rs

@@ -5,11 +5,44 @@ use crate::output::WaybarOutput;
 use crate::state::{AppReceivers, DndState};
 use futures::StreamExt;
 use tokio::sync::watch;
+use tokio::time::Duration;
 use tracing::{debug, error, info};
-use zbus::{Connection, fdo::PropertiesProxy, proxy};
+use zbus::proxy;
+use zbus::zvariant::OwnedValue;
+use zbus::{Connection, fdo::PropertiesProxy};
 
 pub struct DndModule;
 
+/// Read dunst's `paused` property via raw D-Bus call.
+async fn dunst_get_paused(connection: &Connection) -> anyhow::Result<bool> {
+    let reply = connection
+        .call_method(
+            Some("org.freedesktop.Notifications"),
+            "/org/freedesktop/Notifications",
+            Some("org.freedesktop.DBus.Properties"),
+            "Get",
+            &("org.dunstproject.cmd0", "paused"),
+        )
+        .await?;
+    let value: OwnedValue = reply.body().deserialize()?;
+    Ok(bool::try_from(&*value)?)
+}
+
+/// Set dunst's `paused` property via raw D-Bus call.
+async fn dunst_set_paused(connection: &Connection, paused: bool) -> anyhow::Result<()> {
+    let value = zbus::zvariant::Value::from(paused);
+    connection
+        .call_method(
+            Some("org.freedesktop.Notifications"),
+            "/org/freedesktop/Notifications",
+            Some("org.freedesktop.DBus.Properties"),
+            "Set",
+            &("org.dunstproject.cmd0", "paused", value),
+        )
+        .await?;
+    Ok(())
+}
+
 impl WaybarModule for DndModule {
     async fn run(
         &self,
@@ -28,7 +61,7 @@ impl WaybarModule for DndModule {
                         message: format!("DBus connection failed: {}", e),
                     })?;
 
-            // Try toggling SwayNC
+            // Try SwayNC
             if let Ok(proxy) = SwayncControlProxy::new(&connection).await
                 && let Ok(is_dnd) = proxy.dnd().await
             {
@@ -36,11 +69,9 @@ impl WaybarModule for DndModule {
                 return Ok(WaybarOutput::default());
             }
 
-            // Try toggling Dunst
-            if let Ok(proxy) = DunstControlProxy::new(&connection).await
-                && let Ok(is_paused) = proxy.paused().await
-            {
-                let _ = proxy.set_paused(!is_paused).await;
+            // Try Dunst via raw D-Bus
+            if let Ok(is_paused) = dunst_get_paused(&connection).await {
+                let _ = dunst_set_paused(&connection, !is_paused).await;
                 return Ok(WaybarOutput::default());
             }
 
@@ -84,18 +115,6 @@ trait SwayncControl {
     fn set_dnd(&self, value: bool) -> zbus::Result<()>;
 }
 
-#[proxy(
-    interface = "org.dunstproject.cmd0",
-    default_service = "org.freedesktop.Notifications",
-    default_path = "/org/freedesktop/Notifications"
-)]
-trait DunstControl {
-    #[zbus(property)]
-    fn paused(&self) -> zbus::Result<bool>;
-    #[zbus(property)]
-    fn set_paused(&self, value: bool) -> zbus::Result<()>;
-}
-
 impl DndDaemon {
     pub fn new() -> Self {
         Self
@@ -117,11 +136,11 @@ impl DndDaemon {
 
         info!("Connected to D-Bus for DND monitoring");
 
-        // Try SwayNC
+        // Try SwayNC first (signal-based)
         if let Ok(proxy) = SwayncControlProxy::new(&connection).await
             && let Ok(is_dnd) = proxy.dnd().await
         {
-            debug!("Found SwayNC, using it for DND state.");
+            debug!("Found SwayNC, using signal-based DND monitoring");
             let _ = tx.send(DndState { is_dnd });
 
             if let Ok(props_proxy) = PropertiesProxy::builder(&connection)
@@ -141,34 +160,41 @@ impl DndDaemon {
                     }
                 }
             }
+
+            return Err(anyhow::anyhow!("SwayNC DND stream ended"));
         }
 
-        // Try Dunst
-        if let Ok(proxy) = DunstControlProxy::new(&connection).await
-            && let Ok(is_dnd) = proxy.paused().await
-        {
-            debug!("Found Dunst, using it for DND state.");
-            let _ = tx.send(DndState { is_dnd });
+        // Try Dunst via raw D-Bus calls (bypasses zbus proxy issues)
+        match dunst_get_paused(&connection).await {
+            Ok(is_paused) => {
+                info!("Found Dunst, using polling-based DND monitoring");
+                let _ = tx.send(DndState { is_dnd: is_paused });
 
-            if let Ok(props_proxy) = PropertiesProxy::builder(&connection)
-                .destination("org.freedesktop.Notifications")?
-                .path("/org/freedesktop/Notifications")?
-                .build()
-                .await
-            {
-                let mut stream = props_proxy.receive_properties_changed().await?;
-                while let Some(signal) = stream.next().await {
-                    let args = signal.args()?;
-                    if args.interface_name == "org.dunstproject.cmd0"
-                        && let Some(val) = args.changed_properties.get("paused")
-                        && let Ok(is_dnd) = bool::try_from(val)
-                    {
-                        let _ = tx.send(DndState { is_dnd });
+                loop {
+                    tokio::time::sleep(Duration::from_secs(2)).await;
+                    match dunst_get_paused(&connection).await {
+                        Ok(is_paused) => {
+                            let current = tx.borrow().is_dnd;
+                            if current != is_paused {
+                                let _ = tx.send(DndState { is_dnd: is_paused });
+                            }
+                        }
+                        Err(e) => {
+                            debug!("Dunst paused() poll failed: {}", e);
+                            break;
+                        }
                     }
                 }
+
+                return Err(anyhow::anyhow!("Dunst connection lost"));
+            }
+            Err(e) => {
+                info!("Dunst not available: {}", e);
             }
         }
 
-        Err(anyhow::anyhow!("DND stream ended or daemon not found"))
+        Err(anyhow::anyhow!(
+            "No supported notification daemon found (tried SwayNC, Dunst)"
+        ))
     }
 }

src/modules/hardware.rs

@@ -143,122 +143,139 @@ impl HardwareDaemon {
     async fn poll_gpu(&mut self, gpu: &mut crate::state::GpuState) {
         gpu.active = false;
 
-        if (self.gpu_vendor.as_deref() == Some("NVIDIA") || self.gpu_vendor.is_none())
-            && let Ok(output) = tokio::process::Command::new("nvidia-smi")
-                .args([
-                    "--query-gpu=utilization.gpu,memory.used,memory.total,temperature.gpu,name",
-                    "--format=csv,noheader,nounits",
-                ])
-                .output()
-                .await
-            && output.status.success()
-        {
-            let stdout = String::from_utf8_lossy(&output.stdout);
-            if let Some(line) = stdout.lines().next() {
-                let parts: Vec<&str> = line.split(',').collect();
-                if parts.len() >= 5 {
-                    gpu.active = true;
-                    gpu.vendor = "NVIDIA".to_string();
-                    gpu.usage = parts[0].trim().parse().unwrap_or(0.0);
-                    gpu.vram_used = parts[1].trim().parse::<f64>().unwrap_or(0.0) / 1024.0;
-                    gpu.vram_total = parts[2].trim().parse::<f64>().unwrap_or(0.0) / 1024.0;
-                    gpu.temp = parts[3].trim().parse().unwrap_or(0.0);
-                    gpu.model = parts[4].trim().to_string();
+        match self.gpu_vendor.as_deref() {
+            Some("NVIDIA") => {
+                Self::poll_nvidia(gpu).await;
+            }
+            Some("AMD") => {
+                Self::poll_amd(gpu);
+            }
+            Some("Intel") => {
+                Self::poll_intel(gpu);
+            }
+            _ => {
+                // Detection pass: try each vendor, cache the first that responds.
+                Self::poll_nvidia(gpu).await;
+                if gpu.active {
                     self.gpu_vendor = Some("NVIDIA".to_string());
                     return;
                 }
-            }
-        }
-
-        if self.gpu_vendor.as_deref() == Some("AMD")
-            || self.gpu_vendor.as_deref() == Some("Intel")
-            || self.gpu_vendor.is_none()
-        {
-            for i in 0..=3 {
-                let base = format!("/sys/class/drm/card{}/device", i);
-
-                if (self.gpu_vendor.as_deref() == Some("AMD") || self.gpu_vendor.is_none())
-                    && let Ok(usage_str) =
-                        std::fs::read_to_string(format!("{}/gpu_busy_percent", base))
-                {
-                    gpu.active = true;
-                    gpu.vendor = "AMD".to_string();
-                    gpu.usage = usage_str.trim().parse().unwrap_or(0.0);
-
-                    if let Ok(mem_used) =
-                        std::fs::read_to_string(format!("{}/mem_info_vram_used", base))
-                    {
-                        gpu.vram_used = mem_used.trim().parse::<f64>().unwrap_or(0.0)
-                            / 1024.0
-                            / 1024.0
-                            / 1024.0;
-                    }
-                    if let Ok(mem_total) =
-                        std::fs::read_to_string(format!("{}/mem_info_vram_total", base))
-                    {
-                        gpu.vram_total = mem_total.trim().parse::<f64>().unwrap_or(0.0)
-                            / 1024.0
-                            / 1024.0
-                            / 1024.0;
-                    }
-
-                    if let Ok(entries) = std::fs::read_dir(format!("{}/hwmon", base)) {
-                        for entry in entries.flatten() {
-                            let temp_path = entry.path().join("temp1_input");
-                            if let Ok(temp_str) = std::fs::read_to_string(temp_path) {
-                                gpu.temp = temp_str.trim().parse::<f64>().unwrap_or(0.0) / 1000.0;
-                                break;
-                            }
-                        }
-                    }
-                    gpu.model = "AMD GPU".to_string();
+                Self::poll_amd(gpu);
+                if gpu.active {
                     self.gpu_vendor = Some("AMD".to_string());
                     return;
                 }
-
-                if self.gpu_vendor.as_deref() == Some("Intel") || self.gpu_vendor.is_none() {
-                    let freq_path =
-                        if std::path::Path::new(&format!("{}/gt_cur_freq_mhz", base)).exists() {
-                            Some(format!("{}/gt_cur_freq_mhz", base))
-                        } else if std::path::Path::new(&format!(
-                            "/sys/class/drm/card{}/gt_cur_freq_mhz",
-                            i
-                        ))
-                        .exists()
-                        {
-                            Some(format!("/sys/class/drm/card{}/gt_cur_freq_mhz", i))
-                        } else {
-                            None
-                        };
-
-                    if let Some(path) = freq_path
-                        && let Ok(freq_str) = std::fs::read_to_string(&path)
-                    {
-                        gpu.active = true;
-                        gpu.vendor = "Intel".to_string();
-
-                        let cur_freq = freq_str.trim().parse::<f64>().unwrap_or(0.0);
-                        let mut max_freq = 0.0;
-
-                        let max_path = path.replace("gt_cur_freq_mhz", "gt_max_freq_mhz");
-                        if let Ok(max_str) = std::fs::read_to_string(max_path) {
-                            max_freq = max_str.trim().parse::<f64>().unwrap_or(0.0);
-                        }
-
-                        gpu.usage = if max_freq > 0.0 {
-                            (cur_freq / max_freq) * 100.0
-                        } else {
-                            0.0
-                        };
-                        gpu.temp = 0.0;
-                        gpu.vram_used = 0.0;
-                        gpu.vram_total = 0.0;
-                        gpu.model = format!("Intel iGPU ({}MHz)", cur_freq);
-                        self.gpu_vendor = Some("Intel".to_string());
-                        return;
-                    }
+                Self::poll_intel(gpu);
+                if gpu.active {
+                    self.gpu_vendor = Some("Intel".to_string());
                 }
             }
         }
     }
+
+    async fn poll_nvidia(gpu: &mut crate::state::GpuState) {
+        let Ok(output) = tokio::process::Command::new("nvidia-smi")
+            .args([
+                "--query-gpu=utilization.gpu,memory.used,memory.total,temperature.gpu,name",
+                "--format=csv,noheader,nounits",
+            ])
+            .output()
+            .await
+        else {
+            return;
+        };
+        if !output.status.success() {
+            return;
+        }
+        let stdout = String::from_utf8_lossy(&output.stdout);
+        if let Some(line) = stdout.lines().next() {
+            let parts: Vec<&str> = line.split(',').collect();
+            if parts.len() >= 5 {
+                gpu.active = true;
+                gpu.vendor = "NVIDIA".to_string();
+                gpu.usage = parts[0].trim().parse().unwrap_or(0.0);
+                gpu.vram_used = parts[1].trim().parse::<f64>().unwrap_or(0.0) / 1024.0;
+                gpu.vram_total = parts[2].trim().parse::<f64>().unwrap_or(0.0) / 1024.0;
+                gpu.temp = parts[3].trim().parse().unwrap_or(0.0);
+                gpu.model = parts[4].trim().to_string();
+            }
+        }
+    }
+
+    fn poll_amd(gpu: &mut crate::state::GpuState) {
+        for i in 0..=3 {
+            let base = format!("/sys/class/drm/card{}/device", i);
+            let Ok(usage_str) = std::fs::read_to_string(format!("{}/gpu_busy_percent", base))
+            else {
+                continue;
+            };
+
+            gpu.active = true;
+            gpu.vendor = "AMD".to_string();
+            gpu.usage = usage_str.trim().parse().unwrap_or(0.0);
+
+            if let Ok(mem_used) = std::fs::read_to_string(format!("{}/mem_info_vram_used", base)) {
+                gpu.vram_used =
+                    mem_used.trim().parse::<f64>().unwrap_or(0.0) / 1024.0 / 1024.0 / 1024.0;
+            }
+            if let Ok(mem_total) = std::fs::read_to_string(format!("{}/mem_info_vram_total", base))
+            {
+                gpu.vram_total =
+                    mem_total.trim().parse::<f64>().unwrap_or(0.0) / 1024.0 / 1024.0 / 1024.0;
+            }
+
+            if let Ok(entries) = std::fs::read_dir(format!("{}/hwmon", base)) {
+                for entry in entries.flatten() {
+                    let temp_path = entry.path().join("temp1_input");
+                    if let Ok(temp_str) = std::fs::read_to_string(temp_path) {
+                        gpu.temp = temp_str.trim().parse::<f64>().unwrap_or(0.0) / 1000.0;
+                        break;
+                    }
+                }
+            }
+            gpu.model = "AMD GPU".to_string();
+            return;
+        }
+    }
+
+    fn poll_intel(gpu: &mut crate::state::GpuState) {
+        for i in 0..=3 {
+            let base = format!("/sys/class/drm/card{}/device", i);
+            let freq_path = if std::path::Path::new(&format!("{}/gt_cur_freq_mhz", base)).exists() {
+                Some(format!("{}/gt_cur_freq_mhz", base))
+            } else if std::path::Path::new(&format!("/sys/class/drm/card{}/gt_cur_freq_mhz", i))
+                .exists()
+            {
+                Some(format!("/sys/class/drm/card{}/gt_cur_freq_mhz", i))
+            } else {
+                None
+            };
+
+            if let Some(path) = freq_path
+                && let Ok(freq_str) = std::fs::read_to_string(&path)
+            {
+                gpu.active = true;
+                gpu.vendor = "Intel".to_string();
+
+                let cur_freq = freq_str.trim().parse::<f64>().unwrap_or(0.0);
+                let mut max_freq = 0.0;
+
+                let max_path = path.replace("gt_cur_freq_mhz", "gt_max_freq_mhz");
+                if let Ok(max_str) = std::fs::read_to_string(max_path) {
+                    max_freq = max_str.trim().parse::<f64>().unwrap_or(0.0);
+                }
+
+                gpu.usage = if max_freq > 0.0 {
+                    (cur_freq / max_freq) * 100.0
+                } else {
+                    0.0
+                };
+                gpu.temp = 0.0;
+                gpu.vram_used = 0.0;
+                gpu.vram_total = 0.0;
+                gpu.model = format!("Intel iGPU ({}MHz)", cur_freq);
+                return;
+            }
+        }
+    }
 }

src/modules/mod.rs

@@ -1,3 +1,17 @@
+//! Waybar module implementations.
+//!
+//! Each submodule exposes a [`WaybarModule`] type (CPU, network, audio, …)
+//! and is feature-gated by a `mod-<kind>` flag. The [`WaybarModule`] trait is
+//! what [`crate::registry::dispatch`] uses to evaluate a module on demand.
+//!
+//! Modules come in two flavours:
+//!
+//! * **Watched** — the daemon spawns a background polling/event task that
+//!   pushes state into a `watch::Receiver`, which the module reads lock-free
+//!   (network, cpu, audio, bluetooth, …).
+//! * **Dispatch-only** — evaluated on demand only, without a watch channel
+//!   (power, game, btrfs).
+
 #[cfg(feature = "mod-audio")]
 pub mod audio;
 #[cfg(feature = "mod-dbus")]
@@ -36,7 +50,14 @@ use crate::error::Result as FluxoResult;
 use crate::output::WaybarOutput;
 use crate::state::AppReceivers;
 
+/// Common interface implemented by every Waybar module.
+///
+/// Given the current daemon config, the shared state receivers, and any
+/// caller-supplied arguments, a module produces a single [`WaybarOutput`].
+/// Implementations must be cheap to evaluate — they are invoked on every
+/// client request and on every signaler state change.
 pub trait WaybarModule {
+    /// Evaluate the module and return its rendered output.
     fn run(
         &self,
         config: &Config,

src/modules/mpris.rs

@@ -2,12 +2,66 @@ use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
-use crate::state::{AppReceivers, MprisState};
+use crate::state::{AppReceivers, MprisScrollState, MprisState};
 use crate::utils::{TokenValue, format_template};
-use tokio::sync::watch;
+use std::sync::Arc;
+use tokio::sync::{RwLock, watch};
+use tokio::time::Duration;
 use tracing::{debug, info};
 use zbus::{Connection, proxy};
 
+fn format_mpris_text(format: &str, mpris: &MprisState) -> (String, &'static str) {
+    let status_icon = if mpris.is_playing {
+        "󰏤"
+    } else if mpris.is_paused {
+        "󰐊"
+    } else {
+        "󰓛"
+    };
+
+    let class = if mpris.is_playing {
+        "playing"
+    } else if mpris.is_paused {
+        "paused"
+    } else {
+        "stopped"
+    };
+
+    let text = format_template(
+        format,
+        &[
+            ("artist", TokenValue::String(mpris.artist.clone())),
+            ("title", TokenValue::String(mpris.title.clone())),
+            ("album", TokenValue::String(mpris.album.clone())),
+            ("status_icon", TokenValue::String(status_icon.to_string())),
+        ],
+    );
+
+    (text, class)
+}
+
+fn apply_scroll_window(full_text: &str, max_len: usize, offset: usize, separator: &str) -> String {
+    let char_count = full_text.chars().count();
+    let total_len = char_count + separator.chars().count();
+    let offset = offset % total_len;
+    full_text
+        .chars()
+        .chain(separator.chars())
+        .cycle()
+        .skip(offset)
+        .take(max_len)
+        .collect()
+}
+
+fn truncate_with_ellipsis(text: &str, max_len: usize) -> String {
+    let char_count = text.chars().count();
+    if char_count <= max_len {
+        return text.to_string();
+    }
+    let truncated: String = text.chars().take(max_len.saturating_sub(3)).collect();
+    format!("{}...", truncated)
+}
+
 pub struct MprisModule;
 
 impl WaybarModule for MprisModule {
@@ -28,32 +82,26 @@ impl WaybarModule for MprisModule {
             });
         }
 
-        let status_icon = if mpris.is_playing {
-            "󰏤"
-        } else if mpris.is_paused {
-            "󰐊"
-        } else {
-            "󰓛"
-        };
+        let (full_text, class) = format_mpris_text(&config.mpris.format, &mpris);
 
-        let class = if mpris.is_playing {
-            "playing"
-        } else if mpris.is_paused {
-            "paused"
+        let text = if config.mpris.scroll {
+            if let Some(max_len) = config.mpris.max_length {
+                let scroll = state.mpris_scroll.read().await;
+                apply_scroll_window(
+                    &full_text,
+                    max_len,
+                    scroll.offset,
+                    &config.mpris.scroll_separator,
+                )
+            } else {
+                full_text.clone()
+            }
+        } else if let Some(max_len) = config.mpris.max_length {
+            truncate_with_ellipsis(&full_text, max_len)
         } else {
-            "stopped"
+            full_text.clone()
         };
 
-        let text = format_template(
-            &config.mpris.format,
-            &[
-                ("artist", TokenValue::String(mpris.artist.clone())),
-                ("title", TokenValue::String(mpris.title.clone())),
-                ("album", TokenValue::String(mpris.album.clone())),
-                ("status_icon", TokenValue::String(status_icon.to_string())),
-            ],
-        );
-
         Ok(WaybarOutput {
             text,
             tooltip: Some(format!("{} - {}", mpris.artist, mpris.title)),
@@ -63,6 +111,54 @@ impl WaybarModule for MprisModule {
     }
 }
 
+pub async fn mpris_scroll_ticker(
+    config: Arc<RwLock<Config>>,
+    mut mpris_rx: watch::Receiver<MprisState>,
+    scroll_state: Arc<RwLock<MprisScrollState>>,
+    tick_tx: watch::Sender<u64>,
+) {
+    let mut generation: u64 = 0;
+    let mut last_track_key = String::new();
+
+    loop {
+        let mpris = mpris_rx.borrow_and_update().clone();
+        let cfg = config.read().await;
+        let scroll_enabled = cfg.mpris.scroll;
+        let has_max_length = cfg.mpris.max_length.is_some();
+        let scroll_speed = cfg.mpris.scroll_speed;
+        let format_str = cfg.mpris.format.clone();
+        drop(cfg);
+
+        let (full_text, _) = format_mpris_text(&format_str, &mpris);
+        let track_key = format!("{}|{}|{}", mpris.artist, mpris.title, mpris.album);
+
+        if track_key != last_track_key {
+            let mut state = scroll_state.write().await;
+            state.offset = 0;
+            state.full_text = full_text.clone();
+            last_track_key = track_key;
+            generation += 1;
+            let _ = tick_tx.send(generation);
+        }
+
+        if scroll_enabled && has_max_length && mpris.is_playing {
+            tokio::time::sleep(Duration::from_millis(scroll_speed)).await;
+            let mut state = scroll_state.write().await;
+            state.offset += 1;
+            state.full_text = full_text;
+            drop(state);
+            generation += 1;
+            let _ = tick_tx.send(generation);
+            continue;
+        }
+
+        // Not scrolling — wait for next state change
+        if mpris_rx.changed().await.is_err() {
+            break;
+        }
+    }
+}
+
 pub struct MprisDaemon;
 
 #[proxy(
@@ -105,103 +201,141 @@ impl MprisDaemon {
     }
 
     async fn listen_loop(tx: &watch::Sender<MprisState>) -> anyhow::Result<()> {
+        use futures::StreamExt;
+
         let connection = Connection::session().await?;
-
         info!("Connected to D-Bus for MPRIS monitoring");
 
-        // Periodically poll for the active player and update the MPRIS state.
-        // This avoids complex dynamic signal tracking across ephemeral player instances.
-
         let dbus_proxy = DBusProxy::new(&connection).await?;
 
         loop {
+            // Discovery pass: find an active MPRIS player.
             let names = dbus_proxy.list_names().await?;
-            let mut active_player = None;
+            let active_player = names
+                .into_iter()
+                .find(|n| n.starts_with("org.mpris.MediaPlayer2."));
 
-            for name in names {
-                if name.starts_with("org.mpris.MediaPlayer2.") {
-                    active_player = Some(name);
-                    break; // Just grab the first active player for now
+            let Some(player_name) = active_player else {
+                send_stopped_if_changed(tx);
+                // No player — wait and re-discover.
+                tokio::time::sleep(Duration::from_secs(5)).await;
+                continue;
+            };
+
+            let player_proxy = match MprisPlayerProxy::builder(&connection)
+                .destination(player_name.clone())?
+                .build()
+                .await
+            {
+                Ok(p) => p,
+                Err(_) => {
+                    tokio::time::sleep(Duration::from_secs(2)).await;
+                    continue;
                 }
-            }
+            };
 
-            if let Some(player_name) = active_player {
-                if let Ok(player_proxy) = MprisPlayerProxy::builder(&connection)
-                    .destination(player_name.clone())?
-                    .build()
-                    .await
-                {
-                    let status = player_proxy.playback_status().await.unwrap_or_default();
-                    let metadata = player_proxy.metadata().await.unwrap_or_default();
+            // Initial fetch and then signal-driven updates via PropertiesChanged.
+            update_from_player(&player_proxy, tx).await;
 
-                    let is_playing = status == "Playing";
-                    let is_paused = status == "Paused";
-                    let is_stopped = status == "Stopped";
+            let mut status_stream = player_proxy.receive_playback_status_changed().await;
+            let mut metadata_stream = player_proxy.receive_metadata_changed().await;
 
-                    let mut artist = String::new();
-                    let mut title = String::new();
-                    let mut album = String::new();
-
-                    if let Some(v) = metadata.get("xesam:artist") {
-                        if let Ok(arr) = zbus::zvariant::Array::try_from(v) {
-                            let mut artists = Vec::new();
-                            for i in 0..arr.len() {
-                                if let Ok(Some(s)) = arr.get::<&str>(i) {
-                                    artists.push(s.to_string());
-                                }
-                            }
-                            artist = artists.join(", ");
-                        } else if let Ok(a) = <&str>::try_from(v) {
-                            artist = a.to_string();
+            loop {
+                tokio::select! {
+                    Some(_) = status_stream.next() => {
+                        update_from_player(&player_proxy, tx).await;
+                    }
+                    Some(_) = metadata_stream.next() => {
+                        update_from_player(&player_proxy, tx).await;
+                    }
+                    _ = tokio::time::sleep(Duration::from_secs(10)) => {
+                        // Heartbeat: verify the player is still on the bus.
+                        let current = dbus_proxy.list_names().await.unwrap_or_default();
+                        if !current.iter().any(|n| n == &player_name) {
+                            break;
                         }
                     }
-                    if let Some(v) = metadata.get("xesam:title")
-                        && let Ok(t) = <&str>::try_from(v)
-                    {
-                        title = t.to_string();
-                    }
-                    if let Some(v) = metadata.get("xesam:album")
-                        && let Ok(a) = <&str>::try_from(v)
-                    {
-                        album = a.to_string();
-                    }
-
-                    // Only send if changed
-                    let current = tx.borrow();
-                    if current.is_playing != is_playing
-                        || current.is_paused != is_paused
-                        || current.is_stopped != is_stopped
-                        || current.title != title
-                        || current.artist != artist
-                        || current.album != album
-                    {
-                        drop(current); // Drop borrow before send
-                        let _ = tx.send(MprisState {
-                            is_playing,
-                            is_paused,
-                            is_stopped,
-                            artist,
-                            title,
-                            album,
-                        });
-                    }
-                }
-            } else {
-                let current = tx.borrow();
-                if !current.is_stopped || !current.title.is_empty() {
-                    drop(current);
-                    let _ = tx.send(MprisState {
-                        is_playing: false,
-                        is_paused: false,
-                        is_stopped: true,
-                        artist: String::new(),
-                        title: String::new(),
-                        album: String::new(),
-                    });
                 }
             }
-
-            tokio::time::sleep(tokio::time::Duration::from_secs(2)).await;
         }
     }
 }
+
+async fn update_from_player(player: &MprisPlayerProxy<'_>, tx: &watch::Sender<MprisState>) {
+    let status = player.playback_status().await.unwrap_or_default();
+    let metadata = player.metadata().await.unwrap_or_default();
+
+    let is_playing = status == "Playing";
+    let is_paused = status == "Paused";
+    let is_stopped = status == "Stopped";
+
+    let (artist, title, album) = parse_metadata(&metadata);
+
+    let current = tx.borrow();
+    if current.is_playing != is_playing
+        || current.is_paused != is_paused
+        || current.is_stopped != is_stopped
+        || current.title != title
+        || current.artist != artist
+        || current.album != album
+    {
+        drop(current);
+        let _ = tx.send(MprisState {
+            is_playing,
+            is_paused,
+            is_stopped,
+            artist,
+            title,
+            album,
+        });
+    }
+}
+
+fn parse_metadata(
+    metadata: &std::collections::HashMap<String, zbus::zvariant::Value<'_>>,
+) -> (String, String, String) {
+    let mut artist = String::new();
+    let mut title = String::new();
+    let mut album = String::new();
+
+    if let Some(v) = metadata.get("xesam:artist") {
+        if let Ok(arr) = zbus::zvariant::Array::try_from(v) {
+            let mut artists = Vec::new();
+            for i in 0..arr.len() {
+                if let Ok(Some(s)) = arr.get::<&str>(i) {
+                    artists.push(s.to_string());
+                }
+            }
+            artist = artists.join(", ");
+        } else if let Ok(a) = <&str>::try_from(v) {
+            artist = a.to_string();
+        }
+    }
+    if let Some(v) = metadata.get("xesam:title")
+        && let Ok(t) = <&str>::try_from(v)
+    {
+        title = t.to_string();
+    }
+    if let Some(v) = metadata.get("xesam:album")
+        && let Ok(a) = <&str>::try_from(v)
+    {
+        album = a.to_string();
+    }
+
+    (artist, title, album)
+}
+
+fn send_stopped_if_changed(tx: &watch::Sender<MprisState>) {
+    let current = tx.borrow();
+    if !current.is_stopped || !current.title.is_empty() {
+        drop(current);
+        let _ = tx.send(MprisState {
+            is_playing: false,
+            is_paused: false,
+            is_stopped: true,
+            artist: String::new(),
+            title: String::new(),
+            album: String::new(),
+        });
+    }
+}

src/output.rs

@@ -1,12 +1,22 @@
+//! JSON payload returned to Waybar custom modules.
+
 use serde::{Deserialize, Serialize};
 
+/// A Waybar custom module return value.
+///
+/// Serialises to the schema Waybar's `return-type: json` expects — the
+/// optional fields are omitted from the output when unset.
 #[derive(Serialize, Deserialize, Clone, Debug, Default)]
 pub struct WaybarOutput {
+    /// Primary text shown in the bar.
     pub text: String,
+    /// Tooltip text shown on hover.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub tooltip: Option<String>,
+    /// CSS class applied to the module (for styling).
     #[serde(skip_serializing_if = "Option::is_none")]
     pub class: Option<String>,
+    /// Optional 0-100 value usable by bar progress indicators.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub percentage: Option<u8>,
 }

src/registry.rs

@@ -1,3 +1,11 @@
+//! Central module dispatch: name → [`WaybarModule::run`] lookup.
+//!
+//! The `dispatch` function is called by the IPC request handler with a module
+//! name (e.g. `"cpu"`, `"vol"`) and returns the rendered [`WaybarOutput`]. All
+//! per-module match arms are generated by [`for_each_watched_module!`];
+//! dispatch-only modules without a watch channel (power/game/btrfs) are
+//! listed manually.
+
 use crate::config::Config;
 use crate::error::{FluxoError, Result as FluxoResult};
 use crate::output::WaybarOutput;
@@ -6,120 +14,72 @@ use crate::state::AppReceivers;
 #[allow(unused_imports)]
 use crate::modules::WaybarModule;
 
-pub async fn dispatch(
-    module_name: &str,
-    #[allow(unused)] config: &Config,
-    #[allow(unused)] state: &AppReceivers,
-    #[allow(unused)] args: &[&str],
-) -> FluxoResult<WaybarOutput> {
-    if !config.is_module_enabled(module_name) {
-        return Err(FluxoError::Disabled(module_name.to_string()));
-    }
+/// Expands the module registry into a single [`dispatch`] match and a
+/// [`signaler_default_args`] lookup.
+macro_rules! gen_dispatch {
+    ($( { $feature:literal, $field:ident, $state:ty, [$($name:literal),+], [$($sig_name:literal),+], $module:path, $signal:ident, [$($default_arg:literal),*], $config:ident } )*) => {
+        /// Look up a module by name and render its [`WaybarOutput`].
+        ///
+        /// Returns [`FluxoError::Disabled`] when the module is disabled in
+        /// config, and [`FluxoError::Ipc`] when the name is unknown.
+        pub async fn dispatch(
+            module_name: &str,
+            #[allow(unused)] config: &Config,
+            #[allow(unused)] state: &AppReceivers,
+            #[allow(unused)] args: &[&str],
+        ) -> FluxoResult<WaybarOutput> {
+            if !config.is_module_enabled(module_name) {
+                return Err(FluxoError::Disabled(module_name.to_string()));
+            }
 
-    match module_name {
-        #[cfg(feature = "mod-network")]
-        "net" | "network" => {
-            crate::modules::network::NetworkModule
-                .run(config, state, args)
-                .await
+            match module_name {
+                $(
+                    #[cfg(feature = $feature)]
+                    $($name)|+ => {
+                        $module.run(config, state, args).await
+                    }
+                )*
+
+                // Dispatch-only modules (no watch channel)
+                #[cfg(feature = "mod-audio")]
+                "mic" => {
+                    crate::modules::audio::AudioModule
+                        .run(config, state, args)
+                        .await
+                }
+                #[cfg(feature = "mod-hardware")]
+                "power" => {
+                    crate::modules::power::PowerModule
+                        .run(config, state, args)
+                        .await
+                }
+                #[cfg(feature = "mod-hardware")]
+                "game" => {
+                    crate::modules::game::GameModule
+                        .run(config, state, args)
+                        .await
+                }
+                #[cfg(feature = "mod-hardware")]
+                "pool" | "btrfs" => {
+                    crate::modules::btrfs::BtrfsModule
+                        .run(config, state, args)
+                        .await
+                }
+                _ => Err(FluxoError::Ipc(format!("Unknown module: {}", module_name))),
+            }
         }
-        #[cfg(feature = "mod-hardware")]
-        "cpu" => {
-            crate::modules::cpu::CpuModule
-                .run(config, state, args)
-                .await
+
+        /// Returns the default args used by the signaler when evaluating a module.
+        pub fn signaler_default_args(module_name: &str) -> &'static [&'static str] {
+            match module_name {
+                $(
+                    $($name)|+ => &[$($default_arg),*],
+                )*
+                "mic" => &["source", "show"],
+                _ => &[],
+            }
         }
-        #[cfg(feature = "mod-hardware")]
-        "mem" | "memory" => {
-            crate::modules::memory::MemoryModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-hardware")]
-        "disk" => {
-            crate::modules::disk::DiskModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-hardware")]
-        "pool" | "btrfs" => {
-            crate::modules::btrfs::BtrfsModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-audio")]
-        "vol" | "audio" => {
-            crate::modules::audio::AudioModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-audio")]
-        "mic" => {
-            crate::modules::audio::AudioModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-hardware")]
-        "gpu" => {
-            crate::modules::gpu::GpuModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-hardware")]
-        "sys" => {
-            crate::modules::sys::SysModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-bt")]
-        "bt" | "bluetooth" => crate::modules::bt::BtModule.run(config, state, args).await,
-        #[cfg(feature = "mod-hardware")]
-        "power" => {
-            crate::modules::power::PowerModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-hardware")]
-        "game" => {
-            crate::modules::game::GameModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-dbus")]
-        "backlight" => {
-            crate::modules::backlight::BacklightModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-dbus")]
-        "kbd" | "keyboard" => {
-            crate::modules::keyboard::KeyboardModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-dbus")]
-        "dnd" => {
-            crate::modules::dnd::DndModule
-                .run(config, state, args)
-                .await
-        }
-        #[cfg(feature = "mod-dbus")]
-        "mpris" => {
-            crate::modules::mpris::MprisModule
-                .run(config, state, args)
-                .await
-        }
-        _ => Err(FluxoError::Ipc(format!("Unknown module: {}", module_name))),
-    }
+    };
 }
 
-/// Returns the default args used by the signaler when evaluating a module.
-pub fn signaler_default_args(module_name: &str) -> &'static [&'static str] {
-    match module_name {
-        "disk" => &["/"],
-        "vol" | "audio" => &["sink", "show"],
-        "mic" => &["source", "show"],
-        "bt" | "bluetooth" => &["show"],
-        _ => &[],
-    }
-}
+for_each_watched_module!(gen_dispatch);

src/signaler.rs

@@ -1,3 +1,11 @@
+//! Waybar signalling: watch state channels, send `SIGRTMIN+N` on changes.
+//!
+//! Waybar's custom modules use `signal = N` to rerun their command when they
+//! receive `SIGRTMIN+N`. This task subscribes to every watched module's
+//! `watch::Receiver`, evaluates the module when its channel fires, and only
+//! signals Waybar when the rendered output actually changed. A 50 ms per-signal
+//! debounce prevents storms during rapid state churn.
+
 use crate::config::Config;
 use crate::state::AppReceivers;
 use std::collections::HashMap;
@@ -7,6 +15,10 @@ use tokio::sync::RwLock;
 use tokio::time::{Duration, Instant, sleep};
 use tracing::{debug, warn};
 
+/// Sends real-time signals to the Waybar process.
+///
+/// Resolves Waybar's PID lazily and caches it — the PID is invalidated on
+/// signal failure (e.g. Waybar was restarted) and rediscovered via `sysinfo`.
 pub struct WaybarSignaler {
     cached_pid: Option<i32>,
     sys: System,
@@ -14,6 +26,7 @@ pub struct WaybarSignaler {
 }
 
 impl WaybarSignaler {
+    /// Create a new signaler with no cached PID.
     pub fn new() -> Self {
         Self {
             cached_pid: None,
@@ -63,162 +76,88 @@ impl WaybarSignaler {
             debug!("Waybar process not found, skipping signal.");
         }
     }
+}
 
-    pub async fn run(mut self, config_lock: Arc<RwLock<Config>>, mut receivers: AppReceivers) {
-        let mut last_outputs: HashMap<&'static str, String> = HashMap::new();
+/// Generates [`WaybarSignaler::run`] from the central module registry.
+///
+/// For each watched module we emit:
+/// * a cfg-gated `watch::Receiver::changed()` future (or `pending::<()>` when
+///   the feature is disabled, so the `tokio::select!` arm compiles uniformly),
+/// * a `select!` arm that re-evaluates the module and signals Waybar once per
+///   changed output.
+macro_rules! gen_signaler_run {
+    ($( { $feature:literal, $field:ident, $state:ty, [$($name:literal),+], [$($sig_name:literal),+], $module:path, $signal:ident, [$($default_arg:literal),*], $config:ident } )*) => {
+        impl WaybarSignaler {
+            /// Run the signaler event loop forever.
+            ///
+            /// Consumes `self`; intended to be spawned as a long-lived task.
+            pub async fn run(mut self, config_lock: Arc<RwLock<Config>>, mut receivers: AppReceivers) {
+                let mut last_outputs: HashMap<&'static str, String> = HashMap::new();
 
-        loop {
-            let signals = config_lock.read().await.signals.clone();
+                loop {
+                    let signals = config_lock.read().await.signals.clone();
 
-            macro_rules! check_and_signal {
-                ($module_name:expr, $signal_opt:expr) => {
-                    if let Some(sig) = $signal_opt {
-                        let config = config_lock.read().await;
-                        if let Some(out) = crate::daemon::evaluate_module_for_signaler(
-                            $module_name,
-                            &receivers,
-                            &config,
-                        )
-                        .await
-                        {
-                            if last_outputs.get($module_name) != Some(&out) {
-                                last_outputs.insert($module_name, out);
-                                self.send_signal(sig);
+                    macro_rules! check_and_signal {
+                        ($module_name:expr, $signal_opt:expr) => {
+                            if let Some(sig) = $signal_opt {
+                                let config = config_lock.read().await;
+                                if let Some(out) = crate::daemon::evaluate_module_for_signaler(
+                                    $module_name,
+                                    &receivers,
+                                    &config,
+                                )
+                                .await
+                                {
+                                    if last_outputs.get($module_name) != Some(&out) {
+                                        last_outputs.insert($module_name, out);
+                                        self.send_signal(sig);
+                                    }
+                                }
                             }
+                        };
+                    }
+
+                    // Generate cfg-gated futures for each watched module
+                    $(
+                        #[cfg(not(feature = $feature))]
+                        let $field = std::future::pending::<
+                            std::result::Result<(), tokio::sync::watch::error::RecvError>,
+                        >();
+                        #[cfg(feature = $feature)]
+                        let $field = receivers.$field.changed();
+                    )*
+
+                    // MPRIS scroll tick (special case — not a watched module)
+                    #[cfg(not(feature = "mod-dbus"))]
+                    let mpris_scroll_tick = std::future::pending::<
+                        std::result::Result<(), tokio::sync::watch::error::RecvError>,
+                    >();
+                    #[cfg(feature = "mod-dbus")]
+                    let mpris_scroll_tick = receivers.mpris_scroll_tick.changed();
+
+                    tokio::select! {
+                        $(
+                            res = $field, if signals.$signal.is_some() => {
+                                if res.is_ok() {
+                                    $(check_and_signal!($sig_name, signals.$signal);)+
+                                }
+                            }
+                        )*
+
+                        // MPRIS scroll tick (separate from mpris data changes)
+                        res = mpris_scroll_tick, if signals.mpris.is_some() => {
+                            if res.is_ok()
+                                && let Some(sig) = signals.mpris { self.send_signal(sig); }
+                        }
+
+                        _ = sleep(Duration::from_secs(5)) => {
+                            // heartbeat: re-read signals config on each iteration
                         }
                     }
-                };
-            }
-
-            // For disabled features, create futures that never resolve
-            #[cfg(not(feature = "mod-network"))]
-            let net_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-network")]
-            let net_changed = receivers.network.changed();
-
-            #[cfg(not(feature = "mod-hardware"))]
-            let cpu_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-hardware")]
-            let cpu_changed = receivers.cpu.changed();
-
-            #[cfg(not(feature = "mod-hardware"))]
-            let mem_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-hardware")]
-            let mem_changed = receivers.memory.changed();
-
-            #[cfg(not(feature = "mod-hardware"))]
-            let sys_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-hardware")]
-            let sys_changed = receivers.sys.changed();
-
-            #[cfg(not(feature = "mod-hardware"))]
-            let gpu_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-hardware")]
-            let gpu_changed = receivers.gpu.changed();
-
-            #[cfg(not(feature = "mod-hardware"))]
-            let disks_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-hardware")]
-            let disks_changed = receivers.disks.changed();
-
-            #[cfg(not(feature = "mod-bt"))]
-            let bt_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-bt")]
-            let bt_changed = receivers.bluetooth.changed();
-
-            #[cfg(not(feature = "mod-audio"))]
-            let audio_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-audio")]
-            let audio_changed = receivers.audio.changed();
-
-            #[cfg(not(feature = "mod-dbus"))]
-            let backlight_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-dbus")]
-            let backlight_changed = receivers.backlight.changed();
-
-            #[cfg(not(feature = "mod-dbus"))]
-            let keyboard_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-dbus")]
-            let keyboard_changed = receivers.keyboard.changed();
-
-            #[cfg(not(feature = "mod-dbus"))]
-            let dnd_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-dbus")]
-            let dnd_changed = receivers.dnd.changed();
-
-            #[cfg(not(feature = "mod-dbus"))]
-            let mpris_changed = std::future::pending::<
-                std::result::Result<(), tokio::sync::watch::error::RecvError>,
-            >();
-            #[cfg(feature = "mod-dbus")]
-            let mpris_changed = receivers.mpris.changed();
-
-            tokio::select! {
-                res = net_changed, if signals.network.is_some() => {
-                    if res.is_ok() { check_and_signal!("net", signals.network); }
-                }
-                res = cpu_changed, if signals.cpu.is_some() => {
-                    if res.is_ok() { check_and_signal!("cpu", signals.cpu); }
-                }
-                res = mem_changed, if signals.memory.is_some() => {
-                    if res.is_ok() { check_and_signal!("mem", signals.memory); }
-                }
-                res = sys_changed, if signals.sys.is_some() => {
-                    if res.is_ok() { check_and_signal!("sys", signals.sys); }
-                }
-                res = gpu_changed, if signals.gpu.is_some() => {
-                    if res.is_ok() { check_and_signal!("gpu", signals.gpu); }
-                }
-                res = disks_changed, if signals.disk.is_some() => {
-                    if res.is_ok() { check_and_signal!("disk", signals.disk); }
-                }
-                res = bt_changed, if signals.bt.is_some() => {
-                    if res.is_ok() { check_and_signal!("bt", signals.bt); }
-                }
-                res = audio_changed, if signals.audio.is_some() => {
-                    if res.is_ok() {
-                        check_and_signal!("vol", signals.audio);
-                        check_and_signal!("mic", signals.audio);
-                    }
-                }
-                res = backlight_changed, if signals.backlight.is_some() => {
-                    if res.is_ok() { check_and_signal!("backlight", signals.backlight); }
-                }
-                res = keyboard_changed, if signals.keyboard.is_some() => {
-                    if res.is_ok() { check_and_signal!("keyboard", signals.keyboard); }
-                }
-                res = dnd_changed, if signals.dnd.is_some() => {
-                    if res.is_ok() { check_and_signal!("dnd", signals.dnd); }
-                }
-                res = mpris_changed, if signals.mpris.is_some() => {
-                    if res.is_ok() { check_and_signal!("mpris", signals.mpris); }
-                }
-                _ = sleep(Duration::from_secs(5)) => {
-                    // loop and refresh config
                 }
             }
         }
-    }
+    };
 }
+
+for_each_watched_module!(gen_signaler_run);

src/state.rs

@@ -1,42 +1,50 @@
+//! Shared state types exchanged between daemon tasks and modules.
+//!
+//! Every "watched" module has a `watch::Receiver<StateType>` held by
+//! [`AppReceivers`]; background tasks write into the paired sender. Readers
+//! (the request handler, the signaler) take a cheap snapshot via
+//! `Receiver::borrow()` and render their output from it.
+
 use crate::output::WaybarOutput;
 use std::collections::HashMap;
 use std::sync::Arc;
 use tokio::sync::{RwLock, mpsc, watch};
 use tokio::time::Instant;
 
-#[derive(Clone)]
-pub struct AppReceivers {
-    #[cfg(feature = "mod-network")]
-    pub network: watch::Receiver<NetworkState>,
-    #[cfg(feature = "mod-hardware")]
-    pub cpu: watch::Receiver<CpuState>,
-    #[cfg(feature = "mod-hardware")]
-    pub memory: watch::Receiver<MemoryState>,
-    #[cfg(feature = "mod-hardware")]
-    pub sys: watch::Receiver<SysState>,
-    #[cfg(feature = "mod-hardware")]
-    pub gpu: watch::Receiver<GpuState>,
-    #[cfg(feature = "mod-hardware")]
-    pub disks: watch::Receiver<Vec<DiskInfo>>,
-    #[cfg(feature = "mod-bt")]
-    pub bluetooth: watch::Receiver<BtState>,
-    #[cfg(feature = "mod-audio")]
-    pub audio: watch::Receiver<AudioState>,
-    #[cfg(feature = "mod-dbus")]
-    pub mpris: watch::Receiver<MprisState>,
-    #[cfg(feature = "mod-dbus")]
-    pub backlight: watch::Receiver<BacklightState>,
-    #[cfg(feature = "mod-dbus")]
-    pub keyboard: watch::Receiver<KeyboardState>,
-    #[cfg(feature = "mod-dbus")]
-    pub dnd: watch::Receiver<DndState>,
-    pub health: Arc<RwLock<HashMap<String, ModuleHealth>>>,
-    #[cfg(feature = "mod-bt")]
-    pub bt_force_poll: mpsc::Sender<()>,
-    #[cfg(feature = "mod-audio")]
-    pub audio_cmd_tx: mpsc::Sender<crate::modules::audio::AudioCommand>,
+/// Generates the [`AppReceivers`] struct, with one `watch::Receiver` field
+/// per watched module (cfg-gated by feature flag).
+macro_rules! gen_app_receivers {
+    ($( { $feature:literal, $field:ident, $state:ty, [$($name:literal),+], [$($sig_name:literal),+], $module:path, $signal:ident, [$($default_arg:literal),*], $config:ident } )*) => {
+        /// Bundle of every watch-channel receiver and control-channel handle.
+        ///
+        /// Cloned into each IPC request handler and each module daemon so that
+        /// they can snapshot state without locking. Per-module receivers are
+        /// generated from [`for_each_watched_module!`]; the remaining fields
+        /// (`health`, `bt_cycle`, `audio_cmd_tx`, `mpris_scroll_*`) are shared
+        /// control state.
+        #[derive(Clone)]
+        pub struct AppReceivers {
+            $(
+                #[cfg(feature = $feature)]
+                pub $field: watch::Receiver<$state>,
+            )*
+            #[cfg(feature = "mod-bt")]
+            pub bt_cycle: Arc<RwLock<usize>>,
+            #[cfg(feature = "mod-dbus")]
+            pub mpris_scroll: Arc<RwLock<MprisScrollState>>,
+            #[cfg(feature = "mod-dbus")]
+            pub mpris_scroll_tick: watch::Receiver<u64>,
+            pub health: Arc<RwLock<HashMap<String, ModuleHealth>>>,
+            #[cfg(feature = "mod-bt")]
+            pub bt_force_poll: mpsc::Sender<()>,
+            #[cfg(feature = "mod-audio")]
+            pub audio_cmd_tx: mpsc::Sender<crate::modules::audio::AudioCommand>,
+        }
+    };
 }
+for_each_watched_module!(gen_app_receivers);
 
+/// Runtime health statistics used for backoff decisions.
 #[derive(Clone, Default)]
 pub struct ModuleHealth {
     pub consecutive_failures: u32,
@@ -45,14 +53,16 @@ pub struct ModuleHealth {
     pub last_successful_output: Option<WaybarOutput>,
 }
 
+/// Current default audio sink + source plus all available devices.
 #[derive(Default, Clone)]
 pub struct AudioState {
     pub sink: AudioDeviceInfo,
-    pub source: AudioSourceInfo,
+    pub source: AudioDeviceInfo,
     pub available_sinks: Vec<String>,
     pub available_sources: Vec<String>,
 }
 
+/// Metadata for one PulseAudio sink or source.
 #[derive(Default, Clone)]
 pub struct AudioDeviceInfo {
     pub name: String,
@@ -62,25 +72,37 @@ pub struct AudioDeviceInfo {
     pub channels: u8,
 }
 
+/// A single BlueZ device, optionally annotated by a plugin (buds, maestro…).
 #[derive(Default, Clone)]
-pub struct AudioSourceInfo {
-    pub name: String,
-    pub description: String,
-    pub volume: u8,
-    pub muted: bool,
-    pub channels: u8,
-}
-
-#[derive(Default, Clone)]
-pub struct BtState {
-    pub connected: bool,
-    pub adapter_powered: bool,
+pub struct BtDeviceInfo {
     pub device_alias: String,
     pub device_address: String,
     pub battery_percentage: Option<u8>,
     pub plugin_data: Vec<(String, String)>,
 }
 
+/// Snapshot of the Bluetooth adapter plus every tracked device.
+#[derive(Default, Clone)]
+pub struct BtState {
+    pub adapter_powered: bool,
+    pub devices: Vec<BtDeviceInfo>,
+}
+
+impl BtState {
+    /// Return the device the client is currently cycled to, if any.
+    ///
+    /// The `index` is taken modulo `devices.len()` so cycling past the end
+    /// wraps around naturally.
+    pub fn active_device(&self, index: usize) -> Option<&BtDeviceInfo> {
+        if self.devices.is_empty() {
+            None
+        } else {
+            Some(&self.devices[index % self.devices.len()])
+        }
+    }
+}
+
+/// Per-mountpoint disk usage.
 #[derive(Default, Clone)]
 pub struct DiskInfo {
     pub mount_point: String,
@@ -89,6 +111,7 @@ pub struct DiskInfo {
     pub available_bytes: u64,
 }
 
+/// Throughput and identity of the active network interface.
 #[derive(Default, Clone)]
 pub struct NetworkState {
     pub rx_mbps: f64,
@@ -97,6 +120,7 @@ pub struct NetworkState {
     pub ip: String,
 }
 
+/// CPU utilisation and temperature.
 #[derive(Clone)]
 pub struct CpuState {
     pub usage: f64,
@@ -114,12 +138,14 @@ impl Default for CpuState {
     }
 }
 
+/// RAM usage in gigabytes.
 #[derive(Default, Clone)]
 pub struct MemoryState {
     pub used_gb: f64,
     pub total_gb: f64,
 }
 
+/// Load averages, uptime, and process count.
 #[derive(Default, Clone)]
 pub struct SysState {
     pub load_1: f64,
@@ -129,6 +155,9 @@ pub struct SysState {
     pub process_count: usize,
 }
 
+/// GPU snapshot (vendor-agnostic).
+///
+/// `active` is `false` until detection finds a supported GPU.
 #[derive(Clone)]
 pub struct GpuState {
     pub active: bool,
@@ -154,21 +183,32 @@ impl Default for GpuState {
     }
 }
 
+/// Do-Not-Disturb toggle state.
 #[derive(Default, Clone)]
 pub struct DndState {
     pub is_dnd: bool,
 }
 
+/// Currently active keyboard layout.
 #[derive(Default, Clone)]
 pub struct KeyboardState {
     pub layout: String,
 }
 
+/// Display backlight brightness as a 0-100 percentage.
 #[derive(Default, Clone)]
 pub struct BacklightState {
     pub percentage: u8,
 }
 
+/// Marquee scroll position for the MPRIS module.
+#[derive(Default, Clone)]
+pub struct MprisScrollState {
+    pub offset: usize,
+    pub full_text: String,
+}
+
+/// Currently playing media metadata from an MPRIS player.
 #[derive(Default, Clone)]
 pub struct MprisState {
     pub is_playing: bool,
@@ -179,6 +219,10 @@ pub struct MprisState {
     pub album: String,
 }
 
+/// Test harness holding a synthetic [`AppReceivers`] plus its senders.
+///
+/// The senders are kept alive via `_*_tx` fields so test code can drive the
+/// watch channels without them being dropped.
 #[cfg(test)]
 pub struct MockState {
     pub receivers: AppReceivers,
@@ -208,6 +252,7 @@ pub struct MockState {
     _dnd_tx: watch::Sender<DndState>,
 }
 
+/// Plain-data counterpart of [`AppReceivers`] used to seed a [`MockState`].
 #[cfg(test)]
 #[derive(Default, Clone)]
 pub struct AppState {
@@ -238,6 +283,7 @@ pub struct AppState {
     pub health: HashMap<String, ModuleHealth>,
 }
 
+/// Build a [`MockState`] from a plain [`AppState`] snapshot for unit tests.
 #[cfg(test)]
 pub fn mock_state(state: AppState) -> MockState {
     #[cfg(feature = "mod-network")]
@@ -285,6 +331,8 @@ pub fn mock_state(state: AppState) -> MockState {
             disks: disks_rx,
             #[cfg(feature = "mod-bt")]
             bluetooth: bt_rx,
+            #[cfg(feature = "mod-bt")]
+            bt_cycle: Arc::new(RwLock::new(0usize)),
             #[cfg(feature = "mod-audio")]
             audio: audio_rx,
             #[cfg(feature = "mod-dbus")]
@@ -295,6 +343,13 @@ pub fn mock_state(state: AppState) -> MockState {
             keyboard: keyboard_rx,
             #[cfg(feature = "mod-dbus")]
             dnd: dnd_rx,
+            #[cfg(feature = "mod-dbus")]
+            mpris_scroll: Arc::new(RwLock::new(MprisScrollState::default())),
+            #[cfg(feature = "mod-dbus")]
+            mpris_scroll_tick: {
+                let (_, rx) = watch::channel(0u64);
+                rx
+            },
             health: Arc::new(RwLock::new(state.health)),
             #[cfg(feature = "mod-bt")]
             bt_force_poll: bt_force_tx,

src/utils.rs

@@ -1,23 +1,31 @@
+//! Shared helpers: menu spawning, Hyprland socket lookup, and template formatting.
+
 use anyhow::{Context, Result};
 use std::io::Write;
 use std::process::{Command, Stdio};
 
+/// Pipe `items` into an external menu program (rofi/dmenu/wofi) and return
+/// the user's selection.
+///
+/// The prompt is exposed to the command as `$FLUXO_PROMPT` (preferred) and
+/// as a legacy `{prompt}` placeholder that is substituted in the shell string.
 pub fn show_menu(prompt: &str, items: &[String], menu_cmd: &str) -> Result<String> {
-    // Backward compatibility for {prompt}, but environment variable is safer
     let cmd_str = menu_cmd.replace("{prompt}", prompt);
     let mut child = Command::new("sh")
         .arg("-c")
         .arg(&cmd_str)
-        .env("FLUXO_PROMPT", prompt) // Safer shell injection
+        .env("FLUXO_PROMPT", prompt)
         .stdin(Stdio::piped())
         .stdout(Stdio::piped())
-        .stderr(Stdio::null()) // Suppress GTK/Wayland warnings from tools like wofi
+        // Suppress GTK/Wayland noise from tools like wofi.
+        .stderr(Stdio::null())
         .spawn()
         .context("Failed to spawn menu command")?;
 
     if let Some(mut stdin) = child.stdin.take() {
         let mut input = items.join("\n");
-        input.push('\n'); // Ensure trailing newline for wofi/rofi
+        // Trailing newline is required by wofi/rofi.
+        input.push('\n');
         stdin
             .write_all(input.as_bytes())
             .context("Failed to write to menu stdin")?;
@@ -37,11 +45,14 @@ pub fn show_menu(prompt: &str, items: &[String], menu_cmd: &str) -> Result<Strin
     Ok(selected)
 }
 
+/// Resolve the path to a Hyprland IPC socket for the current session.
+///
+/// Looks under `$XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/` first,
+/// then falls back to `/tmp/hypr/...` for older Hyprland builds.
 pub fn get_hyprland_socket(socket_name: &str) -> Result<std::path::PathBuf> {
     let signature = std::env::var("HYPRLAND_INSTANCE_SIGNATURE")
         .context("HYPRLAND_INSTANCE_SIGNATURE not set")?;
 
-    // Try XDG_RUNTIME_DIR first (usually /run/user/1000)
     if let Ok(runtime_dir) = std::env::var("XDG_RUNTIME_DIR") {
         let path = std::path::PathBuf::from(runtime_dir)
             .join("hypr")
@@ -52,7 +63,6 @@ pub fn get_hyprland_socket(socket_name: &str) -> Result<std::path::PathBuf> {
         }
     }
 
-    // Fallback to /tmp
     let path = std::path::PathBuf::from("/tmp/hypr")
         .join(&signature)
         .join(socket_name);
@@ -70,6 +80,7 @@ pub fn get_hyprland_socket(socket_name: &str) -> Result<std::path::PathBuf> {
 use regex::Regex;
 use std::sync::LazyLock;
 
+/// Bucket `value` into `"normal"`, `"high"`, or `"max"` for CSS class output.
 pub fn classify_usage(value: f64, high: f64, max: f64) -> &'static str {
     if value > max {
         "max"
@@ -80,15 +91,22 @@ pub fn classify_usage(value: f64, high: f64, max: f64) -> &'static str {
     }
 }
 
+/// A typed value supplied to [`format_template`] — chosen at call site so
+/// formatting handles precision and alignment correctly per type.
 pub enum TokenValue {
     Float(f64),
     Int(i64),
     String(String),
 }
 
+/// Token grammar: `{name}`, `{name:>5}`, `{name:<8.2}`, `{name:^6}`, etc.
 pub static TOKEN_RE: LazyLock<Regex> =
     LazyLock::new(|| Regex::new(r"\{([a-zA-Z0-9_]+)(?::([<>\^])?(\d+)?(?:\.(\d+))?)?\}").unwrap());
 
+/// Substitute `{name[:align[width[.precision]]]}` tokens in a template string.
+///
+/// Unknown tokens are left verbatim. Width/alignment/precision follow Rust's
+/// `std::fmt` semantics (`<` left, `^` center, `>` right).
 pub fn format_template<K>(template: &str, values: &[(K, TokenValue)]) -> String
 where
     K: AsRef<str>,