added .deb build target + systemd unit + updated readme

Reviewed-on: #2

.gitea/workflows/release.yml

@@ -64,31 +64,31 @@ jobs:
           VERSION: ${{ steps.get_version.outputs.VERSION }}
           TAG: ${{ steps.get_version.outputs.TAG }}
         run: |
-          PKG="fluxo-rs_${VERSION}_amd64"
+          PKG="fluxo_${VERSION}_amd64"
 
           mkdir -p "${PKG}/DEBIAN"
           mkdir -p "${PKG}/usr/bin"
 
-          cp target/release/fluxo-rs "${PKG}/usr/bin/"
+          cp target/release/fluxo "${PKG}/usr/bin/"
-          strip "${PKG}/usr/bin/fluxo-rs"
+          strip "${PKG}/usr/bin/fluxo"
 
           printf '%s\n' \
-            "Package: fluxo-rs" \
+            "Package: fluxo" \
             "Version: ${VERSION}" \
             "Section: utils" \
             "Priority: optional" \
             "Architecture: amd64" \
-            "Maintainer: fluxo-rs contributors" \
+            "Maintainer: fluxo contributors" \
             "Description: High-performance daemon/client for Waybar custom modules" \
-            " fluxo-rs is a compiled Rust daemon that polls system metrics and" \
+            " fluxo is a compiled Rust daemon that polls system metrics and" \
             " serves formatted JSON output to Waybar custom modules over a Unix" \
             " domain socket. Replaces shell scripts with a single binary." \
             > "${PKG}/DEBIAN/control"
 
           dpkg-deb --build "${PKG}"
 
-          mv "${PKG}.deb" "fluxo-rs-${TAG}-amd64.deb"
+          mv "${PKG}.deb" "fluxo-${TAG}-amd64.deb"
-          echo "Built: fluxo-rs-${TAG}-amd64.deb"
+          echo "Built: fluxo-${TAG}-amd64.deb"
 
       - name: Create Release and Upload Assets
         if: steps.check_release.outputs.EXISTS == 'false'
@@ -101,8 +101,8 @@ jobs:
             Commit: ${{ github.sha }}
             Branch: ${{ github.ref_name }}
           files: |
-            fluxo-rs-${{ steps.get_version.outputs.TAG }}-amd64.deb
+            fluxo-${{ steps.get_version.outputs.TAG }}-amd64.deb
-            target/release/fluxo-rs
+            target/release/fluxo
           draft: false
           prerelease: false
         env:

Cargo.lock

@@ -111,17 +111,6 @@ dependencies = [
  "slab",
 ]
 
-[[package]]
-name = "async-fs"
-version = "2.2.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8034a681df4aed8b8edbd7fbe472401ecf009251c8b40556b304567052e294c5"
-dependencies = [
- "async-lock",
- "blocking",
- "futures-lite",
-]
-
 [[package]]
 name = "async-io"
 version = "2.6.0"
@@ -239,15 +228,6 @@ version = "2.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "843867be96c8daad0d758b57df9392b6d8d271134fce549de6ce169ff98a92af"
 
-[[package]]
-name = "block-buffer"
-version = "0.10.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
-dependencies = [
- "generic-array",
-]
-
 [[package]]
 name = "block2"
 version = "0.6.2"
@@ -378,31 +358,12 @@ dependencies = [
  "crossbeam-utils",
 ]
 
-[[package]]
-name = "cpufeatures"
-version = "0.2.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "crossbeam-utils"
 version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
-[[package]]
-name = "crypto-common"
-version = "0.1.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
-dependencies = [
- "generic-array",
- "typenum",
-]
-
 [[package]]
 name = "ctrlc"
 version = "3.5.2"
@@ -504,16 +465,6 @@ dependencies = [
  "tokio",
 ]
 
-[[package]]
-name = "digest"
-version = "0.10.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
-dependencies = [
- "block-buffer",
- "crypto-common",
-]
-
 [[package]]
 name = "dispatch2"
 version = "0.3.1"
@@ -621,13 +572,14 @@ checksum = "1d674e81391d1e1ab681a28d99df07927c6d4aa5b027d7da16ba32d1d21ecd99"
 
 [[package]]
 name = "fluxo-rs"
-version = "0.3.3"
+version = "0.5.4"
 dependencies = [
  "anyhow",
  "bluer",
  "clap",
  "ctrlc",
  "futures",
+ "libc",
  "libpulse-binding",
  "maestro",
  "nix 0.31.2",
@@ -768,27 +720,6 @@ dependencies = [
  "slab",
 ]
 
-[[package]]
-name = "generic-array"
-version = "0.14.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
-dependencies = [
- "typenum",
- "version_check",
-]
-
-[[package]]
-name = "getrandom"
-version = "0.2.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
-dependencies = [
- "cfg-if",
- "libc",
- "wasi",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.4.2"
@@ -1071,7 +1002,6 @@ dependencies = [
  "cfg-if",
  "cfg_aliases",
  "libc",
- "memoffset",
 ]
 
 [[package]]
@@ -1304,15 +1234,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "ppv-lite86"
-version = "0.2.21"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
-dependencies = [
- "zerocopy",
-]
-
 [[package]]
 name = "prettyplease"
 version = "0.2.37"
@@ -1407,36 +1328,6 @@ version = "6.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"
 
-[[package]]
-name = "rand"
-version = "0.8.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
-dependencies = [
- "libc",
- "rand_chacha",
- "rand_core",
-]
-
-[[package]]
-name = "rand_chacha"
-version = "0.3.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
-dependencies = [
- "ppv-lite86",
- "rand_core",
-]
-
-[[package]]
-name = "rand_core"
-version = "0.6.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
-dependencies = [
- "getrandom 0.2.17",
-]
-
 [[package]]
 name = "regex"
 version = "1.12.3"
@@ -1563,17 +1454,6 @@ dependencies = [
  "serde_core",
 ]
 
-[[package]]
-name = "sha1"
-version = "0.10.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
-dependencies = [
- "cfg-if",
- "cpufeatures",
- "digest",
-]
-
 [[package]]
 name = "sharded-slab"
 version = "0.1.7"
@@ -1615,12 +1495,6 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
-[[package]]
-name = "static_assertions"
-version = "1.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
-
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -1692,7 +1566,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"
 dependencies = [
  "fastrand",
- "getrandom 0.4.2",
+ "getrandom",
  "once_cell",
  "rustix",
  "windows-sys 0.61.2",
@@ -1791,7 +1665,7 @@ dependencies = [
  "toml_datetime",
  "toml_parser",
  "toml_writer",
- "winnow",
+ "winnow 1.0.1",
 ]
 
 [[package]]
@@ -1805,14 +1679,14 @@ dependencies = [
 
 [[package]]
 name = "toml_edit"
-version = "0.25.8+spec-1.1.0"
+version = "0.25.10+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "16bff38f1d86c47f9ff0647e6838d7bb362522bdf44006c7068c2b1e606f1f3c"
+checksum = "a82418ca169e235e6c399a84e395ab6debeb3bc90edc959bf0f48647c6a32d1b"
 dependencies = [
  "indexmap",
  "toml_datetime",
  "toml_parser",
- "winnow",
+ "winnow 1.0.1",
 ]
 
 [[package]]
@@ -1821,7 +1695,7 @@ version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2abe9b86193656635d2411dc43050282ca48aa31c2451210f4202550afb7526"
 dependencies = [
- "winnow",
+ "winnow 1.0.1",
 ]
 
 [[package]]
@@ -1891,12 +1765,6 @@ dependencies = [
  "tracing-log",
 ]
 
-[[package]]
-name = "typenum"
-version = "1.19.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
-
 [[package]]
 name = "uds_windows"
 version = "1.2.1"
@@ -1932,8 +1800,9 @@ version = "1.23.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5ac8b6f42ead25368cf5b098aeb3dc8a1a2c05a3eee8a9a1a68c640edbfc79d9"
 dependencies = [
- "getrandom 0.4.2",
+ "getrandom",
  "js-sys",
+ "serde_core",
  "wasm-bindgen",
 ]
 
@@ -1943,12 +1812,6 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
-[[package]]
-name = "version_check"
-version = "0.9.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
-
 [[package]]
 name = "walkdir"
 version = "2.5.0"
@@ -2194,15 +2057,6 @@ dependencies = [
  "windows-link",
 ]
 
-[[package]]
-name = "windows-sys"
-version = "0.52.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
-dependencies = [
- "windows-targets 0.52.6",
-]
-
 [[package]]
 name = "windows-sys"
 version = "0.59.0"
@@ -2368,6 +2222,15 @@ version = "0.53.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
 
+[[package]]
+name = "winnow"
+version = "0.7.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "winnow"
 version = "1.0.1"
@@ -2465,25 +2328,14 @@ dependencies = [
  "wasmparser",
 ]
 
-[[package]]
-name = "xdg-home"
-version = "1.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ec1cdab258fb55c0da61328dc52c8764709b249011b2cad0454c72f0bf10a1f6"
-dependencies = [
- "libc",
- "windows-sys 0.59.0",
-]
-
 [[package]]
 name = "zbus"
-version = "4.4.0"
+version = "5.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bb97012beadd29e654708a0fdb4c84bc046f537aecfde2c3ee0a9e4b4d48c725"
+checksum = "ca82f95dbd3943a40a53cfded6c2d0a2ca26192011846a1810c4256ef92c60bc"
 dependencies = [
  "async-broadcast",
  "async-executor",
- "async-fs",
  "async-io",
  "async-lock",
  "async-process",
@@ -2494,20 +2346,18 @@ dependencies = [
  "enumflags2",
  "event-listener",
  "futures-core",
- "futures-sink",
+ "futures-lite",
- "futures-util",
  "hex",
- "nix 0.29.0",
+ "libc",
  "ordered-stream",
- "rand",
+ "rustix",
  "serde",
  "serde_repr",
- "sha1",
- "static_assertions",
  "tracing",
  "uds_windows",
- "windows-sys 0.52.0",
+ "uuid",
- "xdg-home",
+ "windows-sys 0.61.2",
+ "winnow 0.7.15",
  "zbus_macros",
  "zbus_names",
  "zvariant",
@@ -2515,48 +2365,30 @@ dependencies = [
 
 [[package]]
 name = "zbus_macros"
-version = "4.4.0"
+version = "5.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "267db9407081e90bbfa46d841d3cbc60f59c0351838c4bc65199ecd79ab1983e"
+checksum = "897e79616e84aac4b2c46e9132a4f63b93105d54fe8c0e8f6bffc21fa8d49222"
 dependencies = [
  "proc-macro-crate",
  "proc-macro2",
  "quote",
  "syn",
+ "zbus_names",
+ "zvariant",
  "zvariant_utils",
 ]
 
 [[package]]
 name = "zbus_names"
-version = "3.0.0"
+version = "4.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4b9b1fef7d021261cc16cba64c351d291b715febe0fa10dc3a443ac5a5022e6c"
+checksum = "ffd8af6d5b78619bab301ff3c560a5bd22426150253db278f164d6cf3b72c50f"
 dependencies = [
  "serde",
- "static_assertions",
+ "winnow 0.7.15",
  "zvariant",
 ]
 
-[[package]]
-name = "zerocopy"
-version = "0.8.48"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eed437bf9d6692032087e337407a86f04cd8d6a16a37199ed57949d415bd68e9"
-dependencies = [
- "zerocopy-derive",
-]
-
-[[package]]
-name = "zerocopy-derive"
-version = "0.8.48"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "70e3cd084b1788766f53af483dd21f93881ff30d7320490ec3ef7526d203bad4"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
-]
-
 [[package]]
 name = "zmij"
 version = "1.0.21"
@@ -2565,22 +2397,23 @@ checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
 
 [[package]]
 name = "zvariant"
-version = "4.2.0"
+version = "5.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2084290ab9a1c471c38fc524945837734fbf124487e105daec2bb57fd48c81fe"
+checksum = "5708299b21903bbe348e94729f22c49c55d04720a004aa350f1f9c122fd2540b"
 dependencies = [
  "endi",
  "enumflags2",
  "serde",
- "static_assertions",
+ "winnow 0.7.15",
  "zvariant_derive",
+ "zvariant_utils",
 ]
 
 [[package]]
 name = "zvariant_derive"
-version = "4.2.0"
+version = "5.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "73e2ba546bda683a90652bac4a279bc146adad1386f25379cf73200d2002c449"
+checksum = "5b59b012ebe9c46656f9cc08d8da8b4c726510aef12559da3e5f1bf72780752c"
 dependencies = [
  "proc-macro-crate",
  "proc-macro2",
@@ -2591,11 +2424,13 @@ dependencies = [
 
 [[package]]
 name = "zvariant_utils"
-version = "2.1.0"
+version = "3.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c51bcff7cc3dbb5055396bcf774748c3dab426b4b8659046963523cee4808340"
+checksum = "f75c23a64ef8f40f13a6989991e643554d9bef1d682a281160cf0c1bc389c5e9"
 dependencies = [
  "proc-macro2",
  "quote",
+ "serde",
  "syn",
+ "winnow 0.7.15",
 ]

Cargo.toml

@@ -1,12 +1,25 @@
 [package]
 name = "fluxo-rs"
-version = "0.3.3"
+version = "0.5.4"
 edition = "2024"
 
+[[bin]]
+name = "fluxo"
+path = "src/main.rs"
+
+[features]
+default = ["mod-audio", "mod-bt", "mod-network", "mod-hardware", "mod-dbus"]
+mod-audio = ["dep:libpulse-binding"]
+mod-bt = ["dep:bluer", "dep:maestro"]
+mod-network = ["dep:nix"]
+mod-hardware = []
+mod-dbus = ["dep:zbus", "dep:futures"]
+
 [dependencies]
 anyhow = "1.0.102"
 clap = { version = "4.6.0", features = ["derive"] }
 ctrlc = "3"
+libc = "0.2"
 regex = "1.12"
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.149"
@@ -15,16 +28,30 @@ thiserror = "2.0"
 toml = "1.1.2"
 tracing = "0.1.44"
 tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
-maestro = { git = "https://github.com/qzed/pbpctrl", package = "maestro" }
+tokio = { version = "1", features = ["rt", "rt-multi-thread", "sync", "time", "macros", "signal", "process", "io-util", "net"] }
-bluer = { version = "0.17", features = ["bluetoothd", "rfcomm", "id"] }
-tokio = { version = "1", features = ["rt", "rt-multi-thread", "sync", "time", "macros", "signal", "process"] }
 tokio-util = { version = "0.7", features = ["codec", "time"] }
-futures = "0.3"
-libpulse-binding = "2.30"
-nix = { version = "0.31", features = ["net"] }
 notify = "8.2.0"
-zbus = "4"
+
+# Optional module dependencies
+maestro = { git = "https://github.com/qzed/pbpctrl", package = "maestro", optional = true }
+bluer = { version = "0.17", features = ["bluetoothd", "rfcomm", "id"], optional = true }
+futures = { version = "0.3", optional = true }
+libpulse-binding = { version = "2.30", optional = true }
+nix = { version = "0.31", features = ["net"], optional = true }
+zbus = { version = "5", optional = true }
 
 [dev-dependencies]
-
 tempfile = "3"
+
+[package.metadata.deb]
+maintainer = "Nils Pukropp"
+copyright = "2024-2026 Nils Pukropp"
+depends = "$auto"
+section = "utils"
+priority = "optional"
+assets = [
+    ["target/release/fluxo", "usr/bin/", "755"],
+    ["dist/fluxo.service", "usr/lib/systemd/user/", "644"],
+    ["README.md", "usr/share/doc/fluxo/", "644"],
+    ["example.config.toml", "usr/share/doc/fluxo/", "644"],
+]

README.md

@@ -1,18 +1,16 @@
-# fluxo-rs
+# fluxo
 
-fluxo-rs is a high-performance system metrics daemon and client designed specifically for Waybar. It replaces standard shell scripts with a compiled Rust binary that collects data via a background polling loop and serves it over a Unix socket.
+`fluxo` is a high-performance system metrics daemon and client designed specifically for Waybar. It entirely replaces standard shell scripts with a compiled Rust binary that collects data via a background polling loop and serves it over a Unix socket. 
+
+With its **100% Native, Content-Based Event-Driven Architecture**, it consumes effectively 0% CPU while idle and signals Waybar to redraw *only* when the rendered UI text or icons physically change.
 
 ## Key Features
 
-- **Asynchronous Architecture**: Built on **Tokio**, the daemon handles concurrent IPC requests and background tasks with zero latency and minimal CPU overhead.
+- **100% Native Architecture**: Zero shell-outs or subprocesses. Uses `bluer` for Bluetooth, `libpulse-binding` for audio, `zbus` for MPRIS/DND, and `notify` for backlight.
-- **Native Library Integrations**: 
+- **Content-Based Event Signaling**: `fluxo` evaluates your custom configuration formats internally. It only sends a `SIGRTMIN+X` signal to Waybar if the resulting string or CSS class has actually changed, eliminating pointless re-renders from raw polling fluctuations.
-    - **Audio**: Direct `libpulse` integration for event-driven, instant volume and device updates.
+- **Zero-Latency Interactions**: Direct library bindings mean that when you change your volume or connect a Bluetooth device via the CLI, the daemon updates instantly.
-    - **Bluetooth**: Native `bluer` integration for robust device monitoring.
+- **Circuit Breaker (Failsafe)**: Automatically detects failing modules and enters a "Cool down" state, preventing resource waste and log spam. Fallback caching keeps your bar looking clean even during brief failures.
-    - **Pixel Buds Pro**: Custom native RPC implementation for real-time battery and ANC control.
+- **Multi-threaded Polling**: Decoupled Tokio subsystem threads ensure that a hang in one system (e.g., a slow GPU probe) never freezes your Waybar.
-    - **Network**: Native `nix` and `/proc` inspection for high-speed interface monitoring.
-    - **Hyprland**: Direct IPC Unix socket communication for gamemode and animation status.
-- **Circuit Breaker (Failsafe)**: Automatically detects failing modules and enters a "Cool down" state to prevent resource waste and log spam.
-- **Multi-threaded Polling**: Decoupled subsystem threads ensure that a hang in one system (e.g., a slow GPU probe) never freezes your entire bar.
 
 ## Modules
 
@@ -24,43 +22,116 @@ fluxo-rs is a high-performance system metrics daemon and client designed specifi
 | `sys` | System load and uptime | `{uptime}`, `{load1}`, `{load5}`, `{load15}`, `{procs}` |
 | `disk` | Disk usage | `{mount}`, `{used}`, `{total}` |
 | `pool` | Btrfs aggregate storage | `{used}`, `{total}` |
+| `gpu` | GPU usage & thermals | `{usage}`, `{vram_used}`, `{vram_total}`, `{temp}` |
 | `vol` | Audio output (sink) | `{name}`, `{volume}`, `{icon}` |
 | `mic` | Audio input (source) | `{name}`, `{volume}`, `{icon}` |
 | `bt` | Bluetooth status & plugins | `{alias}`, `{mac}`, `{left}`, `{right}`, `{anc}` |
 | `power` | Battery and AC status | `{percentage}`, `{icon}` |
-| `game` | Hyprland status | active/inactive icons |
+| `game` | Hyprland Gamemode status | active/inactive strings |
+| `mpris` | Media Player status | `{artist}`, `{title}`, `{album}`, `{status_icon}` |
+| `backlight` | Display Brightness | `{percentage}`, `{icon}` |
+| `kbd` | Keyboard Layout | `{layout}` |
+| `dnd` | Do Not Disturb (SwayNC) | active/inactive strings |
+
+## Installation
+
+### From Source
+
+```bash
+cargo build --release
+cp target/release/fluxo ~/.cargo/bin/
+```
+
+### Debian/Ubuntu (.deb)
+
+```bash
+cargo install cargo-deb
+cargo deb
+sudo dpkg -i target/debian/fluxo-rs_*.deb
+```
+
+The `.deb` package installs the binary to `/usr/bin/fluxo`, the systemd user service to `/usr/lib/systemd/user/fluxo.service`, and documentation to `/usr/share/doc/fluxo/`.
 
 ## Setup
 
-1. **Build**: `cargo build --release`
+1. **Configure**: Create `~/.config/fluxo/config.toml` (see `example.config.toml`). Ensure you map your `[signals]`.
-2. **Configure**: Create `~/.config/fluxo/config.toml` (see `example.config.toml`).
+2. **Start the daemon** via systemd (recommended) or manually:
-3. **Daemon**: Start `fluxo-rs daemon`. It's recommended to run this as a systemd user service.
+
+### systemd (recommended)
+
+If installed from the `.deb`, the service file is already in place. For manual installs:
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp dist/fluxo.service ~/.config/systemd/user/
+```
+
+If your binary is not at `~/.cargo/bin/fluxo`, edit the `ExecStart=` path in the service file.
+
+Then enable and start:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now fluxo
+```
+
+Check status:
+
+```bash
+systemctl --user status fluxo
+journalctl --user -u fluxo -f
+```
+
+### Manual
+
+```bash
+fluxo daemon
+```
 
 ## Waybar Configuration
 
-To achieve zero-latency updates, use **Waybar Signals**:
+To achieve zero-latency updates and zero-polling CPU usage, set `interval: 0` on your modules and rely entirely on **Waybar Signals** mapped in your `config.toml`:
 
 ```jsonc
-"custom/audio": {
+"custom/volume": {
     "exec": "fluxo vol",
     "return-type": "json",
-    "interval": 5,
+    "interval": 0,
-    "signal": 8,
+    "signal": 8, // Must match the value in config.toml [signals]
-    "on-click": "fluxo audio cycle sink && pkill -RTMIN+8 waybar"
+    "on-click": "fluxo vol mute",
+    "on-scroll-up": "fluxo vol up 1",
+    "on-scroll-down": "fluxo vol down 1",
+    "on-click-right": "fluxo vol cycle"
 },
-"custom/bluetooth": {
+"custom/bluetooth-audio": {
-    "exec": "fluxo bt",
+    "format": "{}",
     "return-type": "json",
-    "interval": 5,
+    "exec": "fluxo bt",
+    "on-click": "fluxo bt menu",
+    "on-click-right": "fluxo bt cycle_mode",
     "signal": 9,
-    "on-click": "fluxo bt menu && pkill -RTMIN+9 waybar",
+    "interval": 0,
-    "on-click-right": "fluxo bt cycle_mode && pkill -RTMIN+9 waybar"
+    "tooltip": true
 }
 ```
 
 ## Debugging
 
-Start the daemon with `RUST_LOG=debug` to see detailed logs of library interactions and circuit breaker status:
+Use `--loglevel` to control log verbosity (trace, debug, info, warn, error):
+
 ```bash
-RUST_LOG=debug fluxo-rs daemon
+fluxo daemon --loglevel debug
+```
+
+Or via the `RUST_LOG` environment variable:
+
+```bash
+RUST_LOG=debug fluxo daemon
+```
+
+For module help and available arguments:
+
+```bash
+fluxo help          # overview of all modules
+fluxo help vol      # detailed help for a specific module
 ```

example.config.toml

@@ -1,46 +1,116 @@
 # Fluxo configuration example
+# Place this at ~/.config/fluxo/config.toml
+
+# Note: All tokens support standard alignment, padding, and precision specifiers dynamically.
+# For example, you can change {rx:>5.2} to {rx:<8.1} or {used} to {used:^4.0} directly here.
 
 [general]
+# command used for interactive menus (e.g., bluetooth device selection)
+# $FLUXO_PROMPT is securely injected to prevent shell escaping issues
 menu_command = "fuzzel --dmenu --prompt \"$FLUXO_PROMPT\""
+# For Wofi use: menu_command = "wofi --show dmenu --prompt \"$FLUXO_PROMPT\""
+
+# Map modules to specific Waybar signals for zero-latency, event-driven UI updates.
+# These MUST match the `signal` configuration in your waybar config.jsonc
+[signals]
+network = 1
+cpu = 2
+memory = 3
+gpu = 4
+sys = 5
+disk = 6
+game = 7
+audio = 8
+bt = 9
+power = 10
+keyboard = 11
+mpris = 12
+backlight = 13
+dnd = 14
 
 [network]
-format = "{interface} ({ip}):  {rx:>5.2} MB/s   {tx:>5.2} MB/s"
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {interface}, {ip}, {rx}, {tx}
+format = "{interface} ({ip}):  {rx:^4.1} MB/s   {tx:^4.1} MB/s"
 
 [cpu]
-format = "CPU: {usage:>4.1}% {temp:>4.1}C"
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {usage}, {temp}, {model}
+format = "CPU: {usage:^4.1}% {temp:^4.1}C"
 
 [memory]
-format = "{used:>5.2}/{total:>5.2}GB"
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {used}, {total}
+format = "MEM: {used:^4.1}/{total:^4.1}GB"
 
 [gpu]
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {usage}, {vram_used}, {vram_total}, {temp}
 format_amd = "AMD: {usage:>3.0}% {vram_used:>4.1}/{vram_total:>4.1}GB {temp:>4.1}C"
 format_intel = "iGPU: {usage:>3.0}%"
 format_nvidia = "NV: {usage:>3.0}% {vram_used:>4.1}/{vram_total:>4.1}GB {temp:>4.1}C"
 
 [sys]
-format = "UP: {uptime} | LOAD: {load1:>4.2} {load5:>4.2} {load15:>4.2}"
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {uptime}, {load1}, {load5}, {load15}, {procs}
+format = "UP: {uptime} LOAD: {load1:^3.1} "
 
 [disk]
-format = "{mount} {used:>5.1}/{total:>5.1}G"
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {mount}, {used}, {total}
+format = "{mount} {used:^3.0}/{total:^3.0}G"
 
 [pool]
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {used}, {total}
 format = "{used:>4.0}G / {total:>4.0}G"
 
 [power]
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {percentage}, {icon}
 format = "{percentage:>3}%  {icon}"
 
-[bt]
-format_connected = "{alias} 󰂰"
-format_plugin = "{alias} [{left}|{right}] {anc} 󰂰"
-format_disconnected = "󰂯"
-format_disabled = "󰂲 Off"
-
 [audio]
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {name}, {volume}, {icon}
 format_sink_unmuted = "{name} {volume:>3}% {icon}"
 format_sink_muted = "{name} {icon}"
 format_source_unmuted = "{name} {volume:>3}% {icon}"
 format_source_muted = "{name} {icon}"
 
+[bt]
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {alias}, {mac}, {left}, {right}, {anc}
+format_plugin = "{alias} [{left}|{right}] {anc} 󰂰"
+format_connected = "󰂰 {alias}"
+format_disconnected = "󰂯 Disconnected"
+format_disabled = "󰂲 Off"
+
 [game]
+# enabled = false  # set to false to disable this module at runtime
 format_active = "<span size='large'>󰊖</span>"
 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}"
+
+[backlight]
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {percentage}, {icon}
+format = "{percentage:>3}% {icon}"
+
+[keyboard]
+# enabled = false  # set to false to disable this module at runtime
+# tokens: {layout}
+format = "{layout}"
+
+[dnd]
+# enabled = false  # set to false to disable this module at runtime
+format_dnd = "<span size='large'>󰂛</span>"
+format_normal = "<span size='large'>󰂚</span>"

src/bt_menu.rs

@@ -0,0 +1,135 @@
+//! Bluetooth interactive menu (client-side).
+//!
+//! Runs entirely in the client process because it needs to spawn the user's
+//! menu command (rofi/dmenu/wofi) — the daemon has no business opening GUI
+//! windows. Communicates with the daemon via IPC to fetch device lists and
+//! dispatch connect/disconnect/mode commands.
+
+/// Format strings used both when *building* menu items and when *parsing*
+/// the user's selection back. Keeping them together prevents drift.
+mod fmt {
+    /// Connected device with a plugin mode: `"<alias>: Mode: <mode> [<mac>]"`.
+    pub const MODE_INFIX: &str = ": Mode: ";
+    /// Disconnect action: `"Disconnect <alias> [<mac>]"`.
+    pub const DISCONNECT_PREFIX: &str = "Disconnect ";
+    /// Visual separator before paired-but-not-connected devices.
+    pub const CONNECT_HEADER: &str = "--- Connect Device ---";
+}
+
+/// Extract a MAC address enclosed in `[…]` at the end of a string.
+fn parse_mac_from_brackets(s: &str) -> Option<&str> {
+    let start = s.rfind('[')?;
+    let end = s.rfind(']')?;
+    if end > start + 1 {
+        Some(&s[start + 1..end])
+    } else {
+        None
+    }
+}
+
+/// Extract a MAC address enclosed in `(…)` at the end of a string.
+fn parse_mac_from_parens(s: &str) -> Option<&str> {
+    let start = s.rfind('(')?;
+    let end = s.rfind(')')?;
+    if end > start + 1 {
+        Some(&s[start + 1..end])
+    } else {
+        None
+    }
+}
+
+/// Parse a mode selection line: `"<alias>: Mode: <mode> [<mac>]"`.
+/// Returns `(mode, mac)`.
+fn parse_mode_selection(s: &str) -> Option<(&str, &str)> {
+    let mac = parse_mac_from_brackets(s)?;
+    let mode_start = s.find(fmt::MODE_INFIX)?;
+    let mode_begin = mode_start + fmt::MODE_INFIX.len();
+    let bracket_start = s.rfind('[')?;
+    if bracket_start > mode_begin {
+        let mode = s[mode_begin..bracket_start].trim_end();
+        Some((mode, mac))
+    } else {
+        None
+    }
+}
+
+/// Run the interactive Bluetooth device menu.
+///
+/// Fetches connected/paired devices from the daemon, presents them in the
+/// user's configured menu command, and dispatches the selected action back
+/// to the daemon.
+pub fn run_bt_menu() {
+    let config = crate::config::load_config(None);
+    let mut items = Vec::new();
+
+    let mut connected: Vec<(String, String)> = Vec::new();
+    let mut paired: Vec<(String, String)> = Vec::new();
+
+    // Fetch the device list from the daemon.
+    if let Ok(json_str) = crate::ipc::request_data("bt", &["menu_data"])
+        && let Ok(val) = serde_json::from_str::<serde_json::Value>(&json_str)
+        && let Some(text) = val.get("text").and_then(|t| t.as_str())
+    {
+        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()));
+            }
+        }
+    }
+
+    // Build menu items for connected devices (modes + disconnect).
+    for (alias, mac) in &connected {
+        if let Ok(json_str) = crate::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!("{}{}{} [{}]", alias, fmt::MODE_INFIX, mode, mac));
+            }
+        }
+        items.push(format!("{}{} [{}]", fmt::DISCONNECT_PREFIX, alias, mac));
+    }
+
+    // Paired-but-not-connected devices go below a separator.
+    if !paired.is_empty() {
+        items.push(fmt::CONNECT_HEADER.to_string());
+        for (alias, mac) in &paired {
+            items.push(format!("{} ({})", alias, mac));
+        }
+    }
+
+    if items.is_empty() {
+        tracing::info!("No Bluetooth options found.");
+        return;
+    }
+
+    let Ok(selected) = crate::utils::show_menu("BT Menu: ", &items, &config.general.menu_command)
+    else {
+        return;
+    };
+
+    if let Some((mode, mac)) = parse_mode_selection(&selected) {
+        crate::output::print_waybar_response(crate::ipc::request_data(
+            "bt",
+            &["set_mode", mode, mac],
+        ));
+    } else if selected.starts_with(fmt::DISCONNECT_PREFIX) {
+        if let Some(mac) = parse_mac_from_brackets(&selected) {
+            crate::output::print_waybar_response(crate::ipc::request_data(
+                "bt",
+                &["disconnect", mac],
+            ));
+        }
+    } else if selected == fmt::CONNECT_HEADER {
+        // Section header — no action.
+    } else if let Some(mac) = parse_mac_from_parens(&selected) {
+        crate::output::print_waybar_response(crate::ipc::request_data("bt", &["connect", mac]));
+    }
+}

src/client.rs

@@ -0,0 +1,44 @@
+//! Client-side module command dispatch.
+//!
+//! Resolves CLI aliases (e.g. `mic` → audio source), delegates to
+//! special-case handlers (BT menu), and falls through to the standard
+//! IPC → daemon → Waybar JSON path for everything else.
+
+/// Resolve client-side module aliases that prepend implicit arguments.
+///
+/// `vol` maps to the audio sink, `mic` maps to the audio source — both
+/// dispatch to the `"vol"` module on the daemon with a `"sink"` or
+/// `"source"` prefix argument.
+fn resolve_alias(module: &str, args: &[String]) -> (String, Vec<String>) {
+    match module {
+        "vol" => {
+            let mut a = vec!["sink".to_string()];
+            a.extend(args.iter().cloned());
+            ("vol".to_string(), a)
+        }
+        "mic" => {
+            let mut a = vec!["source".to_string()];
+            a.extend(args.iter().cloned());
+            ("vol".to_string(), a)
+        }
+        _ => (module.to_string(), args.to_vec()),
+    }
+}
+
+/// Entry point for all `fluxo <module> [args...]` invocations.
+///
+/// Handles the BT menu special case client-side, resolves aliases, and
+/// sends the request to the daemon via IPC.
+pub fn run_module_command(module: &str, args: &[String]) {
+    // Bluetooth menu runs client-side because it spawns the user's menu
+    // command (rofi/dmenu/wofi) — the daemon must not open GUI windows.
+    #[cfg(feature = "mod-bt")]
+    if module == "bt" && args.first().map(|s| s.as_str()) == Some("menu") {
+        crate::bt_menu::run_bt_menu();
+        return;
+    }
+
+    let (actual_module, actual_args) = resolve_alias(module, args);
+    let args_ref: Vec<&str> = actual_args.iter().map(|s| s.as_str()).collect();
+    crate::output::print_waybar_response(crate::ipc::request_data(&actual_module, &args_ref));
+}

src/config.rs

@@ -1,50 +1,73 @@
-use regex::Regex;
+//! 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 std::sync::LazyLock;
 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)]
     pub general: GeneralConfig,
     #[serde(default)]
     pub signals: SignalsConfig,
+    #[cfg(feature = "mod-network")]
     #[serde(default)]
     pub network: NetworkConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub cpu: CpuConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub memory: MemoryConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub gpu: GpuConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub sys: SysConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub disk: DiskConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub pool: PoolConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub power: PowerConfig,
+    #[cfg(feature = "mod-audio")]
     #[serde(default)]
     pub audio: AudioConfig,
+    #[cfg(feature = "mod-bt")]
     #[serde(default)]
     pub bt: BtConfig,
+    #[cfg(feature = "mod-hardware")]
     #[serde(default)]
     pub game: GameConfig,
+    #[cfg(feature = "mod-dbus")]
     #[serde(default)]
     pub mpris: MprisConfig,
+    #[cfg(feature = "mod-dbus")]
     #[serde(default)]
     pub backlight: BacklightConfig,
+    #[cfg(feature = "mod-dbus")]
     #[serde(default)]
     pub keyboard: KeyboardConfig,
+    #[cfg(feature = "mod-dbus")]
     #[serde(default)]
     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,
 }
 
@@ -56,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 {
@@ -76,47 +102,62 @@ 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")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for NetworkConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "{interface} ({ip}):  {rx:>5.2} MB/s   {tx:>5.2} MB/s".to_string(),
         }
     }
 }
 
+/// CPU module config. `format` tokens: `usage`, `temp`.
 #[derive(Deserialize, Clone)]
 pub struct CpuConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for CpuConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "CPU: {usage:>4.1}% {temp:>4.1}C".to_string(),
         }
     }
 }
 
+/// Memory module config. `format` tokens: `used`, `total` (gigabytes).
 #[derive(Deserialize, Clone)]
 pub struct MemoryConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for MemoryConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "{used:>5.2}/{total:>5.2}GB".to_string(),
         }
     }
 }
 
+/// GPU module config with per-vendor format strings.
 #[derive(Deserialize, Clone)]
 pub struct GpuConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format_amd: String,
     pub format_intel: String,
     pub format_nvidia: String,
@@ -125,6 +166,7 @@ pub struct GpuConfig {
 impl Default for GpuConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format_amd: "AMD: {usage:>3.0}% {vram_used:>4.1}/{vram_total:>4.1}GB {temp:>4.1}C"
                 .to_string(),
             format_intel: "iGPU: {usage:>3.0}%".to_string(),
@@ -134,60 +176,79 @@ impl Default for GpuConfig {
     }
 }
 
+/// Sys module config. `format` tokens: `uptime`, `load1`, `load5`, `load15`, `procs`.
 #[derive(Deserialize, Clone)]
 pub struct SysConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for SysConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "UP: {uptime} | LOAD: {load1:>4.2} {load5:>4.2} {load15:>4.2}".to_string(),
         }
     }
 }
 
+/// Disk module config. `format` tokens: `mount`, `used`, `total`.
 #[derive(Deserialize, Clone)]
 pub struct DiskConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for DiskConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "{mount} {used:>5.1}/{total:>5.1}G".to_string(),
         }
     }
 }
 
+/// Btrfs pool module config. `format` tokens: `used`, `total`.
 #[derive(Deserialize, Clone)]
 pub struct PoolConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for PoolConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "{used:>4.0}G / {total:>4.0}G".to_string(),
         }
     }
 }
 
+/// Battery/power module config. `format` tokens: `percentage`, `icon`.
 #[derive(Deserialize, Clone)]
 pub struct PowerConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for PowerConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "{percentage:>3}%  {icon}".to_string(),
         }
     }
 }
 
+/// Audio module config, one format per (sink|source) × (muted|unmuted) state.
 #[derive(Deserialize, Clone)]
 pub struct AudioConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format_sink_unmuted: String,
     pub format_sink_muted: String,
     pub format_source_unmuted: String,
@@ -197,6 +258,7 @@ pub struct AudioConfig {
 impl Default for AudioConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format_sink_unmuted: "{name} {volume:>3}% {icon}".to_string(),
             format_sink_muted: "{name} {icon}".to_string(),
             format_source_unmuted: "{name} {volume:>3}% {icon}".to_string(),
@@ -205,8 +267,12 @@ 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")]
+    pub enabled: bool,
     pub format_connected: String,
     pub format_plugin: String,
     pub format_disconnected: String,
@@ -216,6 +282,7 @@ pub struct BtConfig {
 impl Default for BtConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format_connected: "{alias} 󰂰".to_string(),
             format_plugin: "{alias} [{left}|{right}] {anc} 󰂰".to_string(),
             format_disconnected: "󰂯".to_string(),
@@ -224,8 +291,11 @@ impl Default for BtConfig {
     }
 }
 
+/// Gamemode indicator config (active/inactive glyphs).
 #[derive(Deserialize, Clone)]
 pub struct GameConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format_active: String,
     pub format_inactive: String,
 }
@@ -233,71 +303,110 @@ pub struct GameConfig {
 impl Default for GameConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format_active: "<span size='large'>󰊖</span>".to_string(),
             format_inactive: "<span size='large'></span>".to_string(),
         }
     }
 }
 
+/// 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 {
     fn default() -> Self {
         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")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for BacklightConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "{percentage:>3}% {icon}".to_string(),
         }
     }
 }
 
+/// Keyboard layout module config. `format` tokens: `layout`.
 #[derive(Deserialize, Clone)]
 pub struct KeyboardConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format: String,
 }
 
 impl Default for KeyboardConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format: "{layout}".to_string(),
         }
     }
 }
 
+/// Do-Not-Disturb indicator config (dnd/normal glyphs).
 #[derive(Deserialize, Clone)]
 pub struct DndConfig {
+    #[serde(default = "default_true")]
+    pub enabled: bool,
     pub format_dnd: String,
     pub format_normal: String,
 }
 
+fn default_true() -> bool {
+    true
+}
+
 impl Default for DndConfig {
     fn default() -> Self {
         Self {
+            enabled: true,
             format_dnd: "<span size='large'>󰂛</span>".to_string(),
             format_normal: "<span size='large'>󰂚</span>".to_string(),
         }
     }
 }
 
-static TOKEN_RE: LazyLock<Regex> =
-    LazyLock::new(|| Regex::new(r"\{([a-zA-Z0-9_]+)(?::([<>\^])?(\d+)?(?:\.(\d+))?)?\}").unwrap());
-
 fn extract_tokens(format_str: &str) -> Vec<String> {
-    TOKEN_RE
+    crate::utils::TOKEN_RE
         .captures_iter(format_str)
         .map(|cap| cap[1].to_string())
         .collect()
@@ -315,12 +424,43 @@ fn validate_format(label: &str, format_str: &str, known_tokens: &[&str]) {
 }
 
 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 {
+        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(
             "network",
             &self.network.format,
             &["interface", "ip", "rx", "tx"],
         );
+        #[cfg(feature = "mod-hardware")]
+        {
             validate_format("cpu", &self.cpu.format, &["usage", "temp"]);
             validate_format("memory", &self.memory.format, &["used", "total"]);
             validate_format(
@@ -342,6 +482,9 @@ impl Config {
             validate_format("disk", &self.disk.format, &["mount", "used", "total"]);
             validate_format("pool", &self.pool.format, &["used", "total"]);
             validate_format("power", &self.power.format, &["percentage", "icon"]);
+        }
+        #[cfg(feature = "mod-audio")]
+        {
             validate_format(
                 "audio.sink_unmuted",
                 &self.audio.format_sink_unmuted,
@@ -362,12 +505,18 @@ impl Config {
                 &self.audio.format_source_muted,
                 &["name", "icon"],
             );
+        }
+        #[cfg(feature = "mod-bt")]
+        {
             validate_format("bt.connected", &self.bt.format_connected, &["alias"]);
             validate_format(
                 "bt.plugin",
                 &self.bt.format_plugin,
                 &["alias", "left", "right", "anc", "mac"],
             );
+        }
+        #[cfg(feature = "mod-dbus")]
+        {
             validate_format(
                 "mpris",
                 &self.mpris.format,
@@ -376,10 +525,12 @@ impl Config {
             validate_format("backlight", &self.backlight.format, &["percentage", "icon"]);
             validate_format("keyboard", &self.keyboard.format, &["layout"]);
         }
+    }
 }
 
-pub fn load_config(custom_path: Option<PathBuf>) -> Config {
+/// Resolve the default config path: `$XDG_CONFIG_HOME/fluxo/config.toml`
-    let config_path = custom_path.unwrap_or_else(|| {
+/// (or `~/.config/fluxo/config.toml`).
+pub fn default_config_path() -> PathBuf {
     let config_dir = std::env::var("XDG_CONFIG_HOME")
         .map(PathBuf::from)
         .unwrap_or_else(|_| {
@@ -387,7 +538,12 @@ pub fn load_config(custom_path: Option<PathBuf>) -> Config {
             PathBuf::from(home).join(".config")
         });
     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);
 
     if let Ok(content) = fs::read_to_string(&config_path) {
         match toml::from_str::<Config>(&content) {

src/daemon.rs

@@ -1,14 +1,35 @@
+//! 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::error::FluxoError;
 use crate::ipc::socket_path;
-use crate::modules::WaybarModule;
+#[cfg(feature = "mod-audio")]
 use crate::modules::audio::AudioDaemon;
+#[cfg(feature = "mod-dbus")]
 use crate::modules::backlight::BacklightDaemon;
+#[cfg(feature = "mod-bt")]
 use crate::modules::bt::BtDaemon;
+#[cfg(feature = "mod-dbus")]
 use crate::modules::dnd::DndDaemon;
+#[cfg(feature = "mod-hardware")]
 use crate::modules::hardware::HardwareDaemon;
+#[cfg(feature = "mod-dbus")]
 use crate::modules::keyboard::KeyboardDaemon;
+#[cfg(feature = "mod-dbus")]
 use crate::modules::mpris::MprisDaemon;
+#[cfg(feature = "mod-network")]
 use crate::modules::network::NetworkDaemon;
 use crate::signaler::WaybarSignaler;
 use crate::state::AppReceivers;
@@ -21,9 +42,77 @@ use std::sync::Arc;
 use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
 use tokio::net::UnixListener;
 use tokio::sync::{RwLock, mpsc, watch};
-use tokio::time::{Duration, Instant, sleep};
+use tokio::time::{Duration, sleep};
 use tokio_util::sync::CancellationToken;
-use tracing::{debug, error, info, warn};
+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,
@@ -37,17 +126,14 @@ impl Drop for SocketGuard {
 }
 
 fn get_config_path(custom_path: Option<PathBuf>) -> PathBuf {
-    custom_path.unwrap_or_else(|| {
+    custom_path.unwrap_or_else(crate::config::default_config_path)
-        let config_dir = std::env::var("XDG_CONFIG_HOME")
-            .map(PathBuf::from)
-            .unwrap_or_else(|_| {
-                let home = std::env::var("HOME").unwrap_or_else(|_| String::from("/"));
-                PathBuf::from(home).join(".config")
-            });
-        config_dir.join("fluxo/config.toml")
-    })
 }
 
+/// 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();
 
@@ -56,37 +142,77 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
         fs::remove_file(&sock_path)?;
     }
 
+    #[cfg(feature = "mod-network")]
     let (net_tx, net_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-hardware")]
     let (cpu_tx, cpu_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-hardware")]
     let (mem_tx, mem_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-hardware")]
     let (sys_tx, sys_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-hardware")]
     let (gpu_tx, gpu_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-hardware")]
     let (disks_tx, disks_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-bt")]
     let (bt_tx, bt_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-audio")]
     let (audio_tx, audio_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-dbus")]
     let (mpris_tx, mpris_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-dbus")]
     let (backlight_tx, backlight_rx) = watch::channel(Default::default());
+    #[cfg(feature = "mod-dbus")]
     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);
 
     let receivers = AppReceivers {
+        #[cfg(feature = "mod-network")]
         network: net_rx,
+        #[cfg(feature = "mod-hardware")]
         cpu: cpu_rx,
+        #[cfg(feature = "mod-hardware")]
         memory: mem_rx,
+        #[cfg(feature = "mod-hardware")]
         sys: sys_rx,
+        #[cfg(feature = "mod-hardware")]
         gpu: gpu_rx,
+        #[cfg(feature = "mod-hardware")]
         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")]
         mpris: mpris_rx,
+        #[cfg(feature = "mod-dbus")]
         backlight: backlight_rx,
+        #[cfg(feature = "mod-dbus")]
         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,
+        #[cfg(feature = "mod-audio")]
         audio_cmd_tx,
     };
 
@@ -95,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 {
@@ -106,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)
+    #[cfg(feature = "mod-network")]
-    let watcher_config = Arc::clone(&config);
+    if config.read().await.network.enabled {
-    let watcher_path = resolved_config_path.clone();
+        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(
@@ -133,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;
@@ -142,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_config = Arc::clone(&config);
+    let hup_path = resolved_path.to_path_buf();
-    let hup_path = resolved_config_path.clone();
     tokio::spawn(async move {
         use tokio::signal::unix::{SignalKind, signal};
         let mut stream = signal(SignalKind::hangup()).unwrap();
@@ -154,120 +410,24 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
             reload_config(&hup_config, Some(hup_path.clone())).await;
         }
     });
+}
 
-    // 1. Network Task
+/// Accept loop for the client Unix socket.
-    let token = cancel_token.clone();
+///
-    let net_health = Arc::clone(&health);
+/// Each client request spawns a short-lived task that reads one line, looks
-    tokio::spawn(async move {
+/// up the module via [`crate::registry::dispatch`], and writes the JSON
-        info!("Starting Network polling task");
+/// response back. Broken-pipe errors are logged at `debug` — they just mean
-        let mut daemon = NetworkDaemon::new();
+/// the client timed out before we responded.
-        loop {
+async fn run_ipc_loop(
-            if !is_in_backoff("net", &net_health).await {
+    listener: UnixListener,
-                let res = daemon.poll(&net_tx).await;
+    receivers: AppReceivers,
-                handle_poll_result("net", res, &net_health).await;
+    config: Arc<RwLock<Config>>,
-            }
+    config_path: Option<PathBuf>,
-            tokio::select! {
+    cancel_token: CancellationToken,
-                _ = token.cancelled() => break,
+) -> Result<()> {
-                _ = sleep(Duration::from_secs(1)) => {}
-            }
-        }
-        info!("Network task shut down.");
-    });
-
-    // 2. Fast Hardware Task (CPU, Mem, Load)
-    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 !is_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)
-    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 !is_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
-    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 !is_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)
-    let audio_daemon = AudioDaemon::new();
-    audio_daemon.start(&audio_tx, audio_cmd_rx);
-
-    // 5.1 Backlight Thread (Event driven)
-    let backlight_daemon = BacklightDaemon::new();
-    backlight_daemon.start(backlight_tx);
-
-    // 5.2 Keyboard Thread (Event driven)
-    let keyboard_daemon = KeyboardDaemon::new();
-    keyboard_daemon.start(keyboard_tx);
-
-    // 5.3 DND Thread (Event driven)
-    let dnd_daemon = DndDaemon::new();
-    dnd_daemon.start(dnd_tx);
-
-    // 5.4 MPRIS Thread
-    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);
-
     loop {
         tokio::select! {
-            _ = cancel_token.cancelled() => {
+            _ = cancel_token.cancelled() => break,
-                break;
-            }
             res = listener.accept() => {
                 match res {
                     Ok((mut stream, _)) => {
@@ -324,59 +484,7 @@ pub async fn run_daemon(config_path: Option<PathBuf>) -> Result<()> {
     Ok(())
 }
 
-async fn handle_poll_result(
+/// Re-read the configuration file and swap it into the shared lock.
-    module_name: &str,
-    result: crate::error::Result<()>,
-    health_lock: &Arc<RwLock<HashMap<String, crate::state::ModuleHealth>>>,
-) {
-    let mut lock = health_lock.write().await;
-    let health = lock.entry(module_name.to_string()).or_default();
-
-    match result {
-        Ok(_) => {
-            if health.consecutive_failures > 0 {
-                info!(
-                    module = module_name,
-                    "Module recovered after {} failures", health.consecutive_failures
-                );
-            }
-            health.consecutive_failures = 0;
-            health.backoff_until = None;
-        }
-        Err(e) => {
-            health.consecutive_failures += 1;
-            health.last_failure = Some(Instant::now());
-
-            if !e.is_transient() {
-                // Fatal errors trigger immediate long backoff
-                health.backoff_until = Some(Instant::now() + Duration::from_secs(60));
-                error!(module = module_name, error = %e, "Fatal module error, entering long cooldown");
-            } else if health.consecutive_failures >= 3 {
-                // Exponential backoff for transient errors: 30s, 60s, 120s...
-                let backoff_secs = 30 * (2u64.pow(health.consecutive_failures.saturating_sub(3)));
-                let backoff_secs = backoff_secs.min(3600); // Cap at 1 hour
-                health.backoff_until = Some(Instant::now() + Duration::from_secs(backoff_secs));
-                warn!(module = module_name, error = %e, backoff = backoff_secs, "Repeated transient failures, entering backoff");
-            } else {
-                debug!(module = module_name, error = %e, "Transient module failure (attempt {})", health.consecutive_failures);
-            }
-        }
-    }
-}
-
-async fn is_in_backoff(
-    module_name: &str,
-    health_lock: &Arc<RwLock<HashMap<String, crate::state::ModuleHealth>>>,
-) -> bool {
-    let lock = health_lock.read().await;
-    if let Some(health) = lock.get(module_name)
-        && let Some(until) = health.backoff_until
-    {
-        return Instant::now() < until;
-    }
-    false
-}
-
 pub async fn reload_config(config_lock: &Arc<RwLock<Config>>, path: Option<PathBuf>) {
     info!("Reloading configuration...");
     let new_config = crate::config::load_config(path);
@@ -385,79 +493,20 @@ 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,
     config: &Config,
 ) -> Option<String> {
-    let result = match module_name {
+    let args = crate::registry::signaler_default_args(module_name);
-        "net" | "network" => {
+    crate::registry::dispatch(module_name, config, state, args)
-            crate::modules::network::NetworkModule
-                .run(config, state, &[])
         .await
-        }
+        .ok()
-        "cpu" => crate::modules::cpu::CpuModule.run(config, state, &[]).await,
+        .and_then(|out| serde_json::to_string(&out).ok())
-        "mem" | "memory" => {
-            crate::modules::memory::MemoryModule
-                .run(config, state, &[])
-                .await
-        }
-        "disk" => {
-            crate::modules::disk::DiskModule
-                .run(config, state, &["/"])
-                .await
-        }
-        "pool" | "btrfs" => {
-            crate::modules::btrfs::BtrfsModule
-                .run(config, state, &["btrfs"])
-                .await
-        }
-        "vol" | "audio" => {
-            crate::modules::audio::AudioModule
-                .run(config, state, &["sink", "show"])
-                .await
-        }
-        "mic" => {
-            crate::modules::audio::AudioModule
-                .run(config, state, &["source", "show"])
-                .await
-        }
-        "gpu" => crate::modules::gpu::GpuModule.run(config, state, &[]).await,
-        "sys" => crate::modules::sys::SysModule.run(config, state, &[]).await,
-        "bt" | "bluetooth" => {
-            crate::modules::bt::BtModule
-                .run(config, state, &["show"])
-                .await
-        }
-        "power" => {
-            crate::modules::power::PowerModule
-                .run(config, state, &[])
-                .await
-        }
-        "game" => {
-            crate::modules::game::GameModule
-                .run(config, state, &[])
-                .await
-        }
-        "backlight" => {
-            crate::modules::backlight::BacklightModule
-                .run(config, state, &[])
-                .await
-        }
-        "kbd" | "keyboard" => {
-            crate::modules::keyboard::KeyboardModule
-                .run(config, state, &[])
-                .await
-        }
-        "dnd" => crate::modules::dnd::DndModule.run(config, state, &[]).await,
-        "mpris" => {
-            crate::modules::mpris::MprisModule
-                .run(config, state, &[])
-                .await
-        }
-        _ => return None,
-    };
-    result.ok().and_then(|out| serde_json::to_string(&out).ok())
 }
 
 async fn handle_request(
@@ -466,160 +515,23 @@ async fn handle_request(
     state: &AppReceivers,
     config_lock: &Arc<RwLock<Config>>,
 ) -> String {
-    // 1. Check Circuit Breaker status
+    let (is_in_backoff, cached_output) = crate::health::check_backoff(module_name, state).await;
-    let (is_in_backoff, cached_output) = {
-        let lock = state.health.read().await;
-        if let Some(health) = lock.get(module_name) {
-            let in_backoff = if let Some(until) = health.backoff_until {
-                Instant::now() < until
-            } else {
-                false
-            };
-            (in_backoff, health.last_successful_output.clone())
-        } else {
-            (false, None)
-        }
-    };
 
     if is_in_backoff {
-        if let Some(mut cached) = cached_output {
+        return crate::health::backoff_response(module_name, cached_output);
-            // Add a "warning" class to indicate stale data
-            let class = cached.class.unwrap_or_default();
-            cached.class = Some(format!("{} warning", class).trim().to_string());
-            return serde_json::to_string(&cached).unwrap_or_else(|_| "{}".to_string());
-        }
-        return format!(
-            "{{\"text\":\"\u{200B}Cooling down ({})\u{200B}\",\"class\":\"error\"}}",
-            module_name
-        );
     }
 
     let config = config_lock.read().await;
+    let result = crate::registry::dispatch(module_name, &config, state, args).await;
 
-    let result = match module_name {
+    crate::health::update_health(module_name, &result, state).await;
-        "net" | "network" => {
-            crate::modules::network::NetworkModule
-                .run(&config, state, args)
-                .await
-        }
-        "cpu" => {
-            crate::modules::cpu::CpuModule
-                .run(&config, state, args)
-                .await
-        }
-        "mem" | "memory" => {
-            crate::modules::memory::MemoryModule
-                .run(&config, state, args)
-                .await
-        }
-        "disk" => {
-            crate::modules::disk::DiskModule
-                .run(&config, state, args)
-                .await
-        }
-        "pool" | "btrfs" => {
-            crate::modules::btrfs::BtrfsModule
-                .run(&config, state, args)
-                .await
-        }
-        "vol" | "audio" => {
-            crate::modules::audio::AudioModule
-                .run(&config, state, args)
-                .await
-        }
-        "mic" => {
-            crate::modules::audio::AudioModule
-                .run(&config, state, args)
-                .await
-        }
-        "gpu" => {
-            crate::modules::gpu::GpuModule
-                .run(&config, state, args)
-                .await
-        }
-        "sys" => {
-            crate::modules::sys::SysModule
-                .run(&config, state, args)
-                .await
-        }
-        "bt" | "bluetooth" => crate::modules::bt::BtModule.run(&config, state, args).await,
-        "power" => {
-            crate::modules::power::PowerModule
-                .run(&config, state, args)
-                .await
-        }
-        "game" => {
-            crate::modules::game::GameModule
-                .run(&config, state, args)
-                .await
-        }
-        "backlight" => {
-            crate::modules::backlight::BacklightModule
-                .run(&config, state, args)
-                .await
-        }
-        "kbd" | "keyboard" => {
-            crate::modules::keyboard::KeyboardModule
-                .run(&config, state, args)
-                .await
-        }
-        "dnd" => {
-            crate::modules::dnd::DndModule
-                .run(&config, state, args)
-                .await
-        }
-        "mpris" => {
-            crate::modules::mpris::MprisModule
-                .run(&config, state, args)
-                .await
-        }
-        _ => {
-            warn!("Received request for unknown module: '{}'", module_name);
-            Err(FluxoError::Ipc(format!("Unknown module: {}", module_name)))
-        }
-    };
-
-    // 2. Update Health and Cache based on result
-    {
-        let mut lock = state.health.write().await;
-        let health = lock.entry(module_name.to_string()).or_default();
-        match &result {
-            Ok(output) => {
-                health.consecutive_failures = 0;
-                health.backoff_until = None;
-                health.last_successful_output = Some(output.clone());
-            }
-            Err(e) => {
-                health.consecutive_failures += 1;
-                health.last_failure = Some(Instant::now());
-                if health.consecutive_failures >= 3 {
-                    // Backoff for 30 seconds after 3 failures
-                    health.backoff_until = Some(Instant::now() + Duration::from_secs(30));
-                    warn!(module = module_name, error = %e, "Module entered backoff state due to repeated failures");
-                }
-            }
-        }
-    }
 
     match result {
         Ok(output) => serde_json::to_string(&output).unwrap_or_else(|_| "{}".to_string()),
-        Err(e) => {
+        Err(crate::error::FluxoError::Disabled(_)) => {
-            // If we have a cached output, return it as fallback even on immediate error
+            serde_json::to_string(&crate::output::WaybarOutput::disabled())
-            if let Some(mut cached) = cached_output {
+                .unwrap_or_else(|_| "{}".to_string())
-                let class = cached.class.unwrap_or_default();
-                cached.class = Some(format!("{} warning", class).trim().to_string());
-                return serde_json::to_string(&cached).unwrap_or_else(|_| "{}".to_string());
-            }
-
-            let error_msg = e.to_string();
-            error!(module = module_name, error = %error_msg, "Module execution failed");
-            let err_out = crate::output::WaybarOutput {
-                text: "\u{200B}Error\u{200B}".to_string(),
-                tooltip: Some(error_msg),
-                class: Some("error".to_string()),
-                percentage: None,
-            };
-            serde_json::to_string(&err_out).unwrap_or_else(|_| "{}".to_string())
         }
+        Err(e) => crate::health::error_response(module_name, &e, cached_output),
     }
 }

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 {
@@ -33,11 +39,17 @@ pub enum FluxoError {
     #[error("Serialization error: {0}")]
     Serialization(#[from] serde_json::Error),
 
+    #[error("Module disabled: {0}")]
+    Disabled(String),
+
     #[error("Other error: {0}")]
     Other(#[from] anyhow::Error),
 }
 
 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,
@@ -51,4 +63,5 @@ impl FluxoError {
     }
 }
 
+/// Crate-wide `Result` alias using [`FluxoError`].
 pub type Result<T> = std::result::Result<T, FluxoError>;

src/health.rs

@@ -0,0 +1,144 @@
+//! 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;
+use std::sync::Arc;
+use tokio::sync::RwLock;
+use tokio::time::{Duration, Instant};
+use tracing::{debug, error, info, warn};
+
+/// Check if a module is in backoff (used by request handler).
+pub async fn check_backoff(
+    module_name: &str,
+    state: &AppReceivers,
+) -> (bool, Option<WaybarOutput>) {
+    let lock = state.health.read().await;
+    if let Some(health) = lock.get(module_name) {
+        let in_backoff = health
+            .backoff_until
+            .is_some_and(|until| Instant::now() < until);
+        (in_backoff, health.last_successful_output.clone())
+    } else {
+        (false, None)
+    }
+}
+
+/// Update health after a request dispatch (used by request handler).
+pub async fn update_health(
+    module_name: &str,
+    result: &Result<WaybarOutput, crate::error::FluxoError>,
+    state: &AppReceivers,
+) {
+    let mut lock = state.health.write().await;
+    let health = lock.entry(module_name.to_string()).or_default();
+    match result {
+        Ok(output) => {
+            health.consecutive_failures = 0;
+            health.backoff_until = None;
+            health.last_successful_output = Some(output.clone());
+        }
+        Err(crate::error::FluxoError::Disabled(_)) => {}
+        Err(e) => {
+            health.consecutive_failures += 1;
+            health.last_failure = Some(Instant::now());
+            if health.consecutive_failures >= 3 {
+                health.backoff_until = Some(Instant::now() + Duration::from_secs(30));
+                warn!(module = module_name, error = %e, "Module entered backoff state due to repeated failures");
+            }
+        }
+    }
+}
+
+/// Check if a polling daemon module is in backoff.
+pub async fn is_poll_in_backoff(
+    module_name: &str,
+    health_lock: &Arc<RwLock<HashMap<String, ModuleHealth>>>,
+) -> bool {
+    let lock = health_lock.read().await;
+    if let Some(health) = lock.get(module_name)
+        && let Some(until) = health.backoff_until
+    {
+        return Instant::now() < until;
+    }
+    false
+}
+
+/// Update health after a polling daemon result.
+pub async fn handle_poll_result(
+    module_name: &str,
+    result: crate::error::Result<()>,
+    health_lock: &Arc<RwLock<HashMap<String, ModuleHealth>>>,
+) {
+    let mut lock = health_lock.write().await;
+    let health = lock.entry(module_name.to_string()).or_default();
+
+    match result {
+        Ok(_) => {
+            if health.consecutive_failures > 0 {
+                info!(
+                    module = module_name,
+                    "Module recovered after {} failures", health.consecutive_failures
+                );
+            }
+            health.consecutive_failures = 0;
+            health.backoff_until = None;
+        }
+        Err(e) => {
+            health.consecutive_failures += 1;
+            health.last_failure = Some(Instant::now());
+
+            if !e.is_transient() {
+                health.backoff_until = Some(Instant::now() + Duration::from_secs(60));
+                error!(module = module_name, error = %e, "Fatal module error, entering long cooldown");
+            } else if health.consecutive_failures >= 3 {
+                let backoff_secs = 30 * (2u64.pow(health.consecutive_failures.saturating_sub(3)));
+                let backoff_secs = backoff_secs.min(3600);
+                health.backoff_until = Some(Instant::now() + Duration::from_secs(backoff_secs));
+                warn!(module = module_name, error = %e, backoff = backoff_secs, "Repeated transient failures, entering backoff");
+            } else {
+                debug!(module = module_name, error = %e, "Transient module failure (attempt {})", health.consecutive_failures);
+            }
+        }
+    }
+}
+
+/// 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();
+        cached.class = Some(format!("{} warning", class).trim().to_string());
+        return serde_json::to_string(&cached).unwrap_or_else(|_| "{}".to_string());
+    }
+    let zws = crate::output::ZERO_WIDTH_SPACE;
+    format!("{{\"text\":\"{zws}Cooling down ({module_name}){zws}\",\"class\":\"error\"}}")
+}
+
+/// 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,
+    cached: Option<WaybarOutput>,
+) -> String {
+    if let Some(mut cached) = cached {
+        let class = cached.class.unwrap_or_default();
+        cached.class = Some(format!("{} warning", class).trim().to_string());
+        return serde_json::to_string(&cached).unwrap_or_else(|_| "{}".to_string());
+    }
+
+    let error_msg = e.to_string();
+    error!(module = module_name, error = %error_msg, "Module execution failed");
+    let err_out = WaybarOutput::error(&error_msg);
+    serde_json::to_string(&err_out).unwrap_or_else(|_| "{}".to_string())
+}

src/help.rs

@@ -0,0 +1,499 @@
+//! Human-readable help output for all available modules.
+//!
+//! `fluxo help` prints an overview of every module with its aliases, arguments,
+//! and format tokens. `fluxo help <module>` shows the detailed page for a
+//! single module.
+
+/// Module help descriptor used to build the help output.
+struct ModuleHelp {
+    /// Primary display name.
+    name: &'static str,
+    /// CLI aliases that dispatch to this module.
+    aliases: &'static [&'static str],
+    /// Cargo feature gate required at compile time.
+    feature: &'static str,
+    /// One-line summary of what the module does.
+    summary: &'static str,
+    /// Argument synopsis in `[arg]` notation.
+    args_synopsis: &'static str,
+    /// Detailed argument descriptions.
+    args_detail: &'static [(&'static str, &'static str)],
+    /// Format tokens available in `config.toml`.
+    tokens: &'static [(&'static str, &'static str)],
+    /// Concrete usage examples.
+    examples: &'static [(&'static str, &'static str)],
+}
+
+/// All module descriptors, ordered by category.
+const MODULES: &[ModuleHelp] = &[
+    // ── Hardware ─────────────────────────────────────────────────────
+    ModuleHelp {
+        name: "cpu",
+        aliases: &["cpu"],
+        feature: "mod-hardware",
+        summary: "CPU usage percentage and temperature.",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("usage", "CPU usage as a percentage (0.0 - 100.0)"),
+            ("temp", "CPU temperature in degrees Celsius"),
+        ],
+        examples: &[("fluxo cpu", "Show current CPU usage and temperature")],
+    },
+    ModuleHelp {
+        name: "memory",
+        aliases: &["mem", "memory"],
+        feature: "mod-hardware",
+        summary: "RAM usage in gigabytes with usage classification.",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("used", "Used memory in GB"),
+            ("total", "Total memory in GB"),
+        ],
+        examples: &[("fluxo mem", "Show current RAM usage")],
+    },
+    ModuleHelp {
+        name: "sys",
+        aliases: &["sys"],
+        feature: "mod-hardware",
+        summary: "Uptime, load averages, and process count.",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("uptime", "Human-readable uptime (e.g. \"2d 5h\")"),
+            ("load1", "1-minute load average"),
+            ("load5", "5-minute load average"),
+            ("load15", "15-minute load average"),
+            ("procs", "Number of running processes"),
+        ],
+        examples: &[("fluxo sys", "Show system uptime and load")],
+    },
+    ModuleHelp {
+        name: "gpu",
+        aliases: &["gpu"],
+        feature: "mod-hardware",
+        summary: "GPU usage, VRAM, and temperature (AMD/NVIDIA/Intel).",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("usage", "GPU utilisation percentage"),
+            ("vram_used", "Used VRAM in GB (AMD/NVIDIA)"),
+            ("vram_total", "Total VRAM in GB (AMD/NVIDIA)"),
+            ("temp", "GPU temperature in Celsius (AMD/NVIDIA)"),
+            ("freq", "GPU frequency in MHz (Intel)"),
+        ],
+        examples: &[("fluxo gpu", "Show GPU stats for the detected vendor")],
+    },
+    ModuleHelp {
+        name: "disk",
+        aliases: &["disk"],
+        feature: "mod-hardware",
+        summary: "Filesystem usage for a given mount point.",
+        args_synopsis: "[mountpoint]",
+        args_detail: &[(
+            "mountpoint",
+            "Path to the mount point to display (default: \"/\")",
+        )],
+        tokens: &[
+            ("mount", "The mount point path"),
+            ("used", "Used space in GB"),
+            ("total", "Total space in GB"),
+        ],
+        examples: &[
+            ("fluxo disk", "Show usage of the root filesystem (/)"),
+            ("fluxo disk /home", "Show usage of /home"),
+        ],
+    },
+    ModuleHelp {
+        name: "pool",
+        aliases: &["pool", "btrfs"],
+        feature: "mod-hardware",
+        summary: "Aggregated Btrfs pool usage across all btrfs mounts.",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("used", "Total used space in GB across all btrfs mounts"),
+            ("total", "Total capacity in GB across all btrfs mounts"),
+        ],
+        examples: &[
+            ("fluxo pool", "Show combined Btrfs pool usage"),
+            ("fluxo btrfs", "Same as above (alias)"),
+        ],
+    },
+    ModuleHelp {
+        name: "power",
+        aliases: &["power"],
+        feature: "mod-hardware",
+        summary: "Battery percentage and charge state from sysfs.",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("percentage", "Battery level (0 - 100)"),
+            ("icon", "State icon (varies by charge level and AC status)"),
+        ],
+        examples: &[("fluxo power", "Show battery status")],
+    },
+    ModuleHelp {
+        name: "game",
+        aliases: &["game"],
+        feature: "mod-hardware",
+        summary: "Gamemode indicator (Hyprland animation state).",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[],
+        examples: &[("fluxo game", "Show whether gamemode is active")],
+    },
+    // ── Network ──────────────────────────────────────────────────────
+    ModuleHelp {
+        name: "network",
+        aliases: &["net", "network"],
+        feature: "mod-network",
+        summary: "Primary network interface, IP, and transfer rates.",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("interface", "Active interface name (e.g. \"wlan0\")"),
+            ("ip", "IPv4 address of the active interface"),
+            ("rx", "Receive rate in MB/s"),
+            ("tx", "Transmit rate in MB/s"),
+        ],
+        examples: &[("fluxo net", "Show network status and throughput")],
+    },
+    // ── Audio ────────────────────────────────────────────────────────
+    ModuleHelp {
+        name: "vol (sink)",
+        aliases: &["vol"],
+        feature: "mod-audio",
+        summary: "PulseAudio/PipeWire output (sink) volume and controls.",
+        args_synopsis: "[show|up|down|mute|cycle] [step]",
+        args_detail: &[
+            (
+                "show",
+                "Display current sink volume and mute state (default)",
+            ),
+            ("up", "Increase volume by <step> percent (default: 5)"),
+            ("down", "Decrease volume by <step> percent (default: 5)"),
+            ("mute", "Toggle mute on the default sink"),
+            ("cycle", "Switch to the next available output device"),
+            ("step", "Volume change increment in percent (default: 5)"),
+        ],
+        tokens: &[
+            ("name", "Device description (truncated to 20 chars)"),
+            ("icon", "Volume-level icon (changes with volume/mute)"),
+            ("volume", "Current volume percentage (0 - 150)"),
+        ],
+        examples: &[
+            ("fluxo vol", "Show current sink volume"),
+            ("fluxo vol up", "Increase volume by 5%"),
+            ("fluxo vol up 10", "Increase volume by 10%"),
+            ("fluxo vol down 2", "Decrease volume by 2%"),
+            ("fluxo vol mute", "Toggle sink mute"),
+            ("fluxo vol cycle", "Switch to next output device"),
+        ],
+    },
+    ModuleHelp {
+        name: "mic (source)",
+        aliases: &["mic"],
+        feature: "mod-audio",
+        summary: "PulseAudio/PipeWire input (source/microphone) controls.",
+        args_synopsis: "[show|up|down|mute|cycle] [step]",
+        args_detail: &[
+            (
+                "show",
+                "Display current source volume and mute state (default)",
+            ),
+            ("up", "Increase mic volume by <step> percent (default: 5)"),
+            ("down", "Decrease mic volume by <step> percent (default: 5)"),
+            ("mute", "Toggle mute on the default source"),
+            ("cycle", "Switch to the next available input device"),
+            ("step", "Volume change increment in percent (default: 5)"),
+        ],
+        tokens: &[
+            ("name", "Device description (truncated to 20 chars)"),
+            ("icon", "Microphone icon (changes with mute state)"),
+            ("volume", "Current volume percentage (0 - 150)"),
+        ],
+        examples: &[
+            ("fluxo mic", "Show current microphone volume"),
+            ("fluxo mic mute", "Toggle microphone mute"),
+            ("fluxo mic up 10", "Increase mic volume by 10%"),
+        ],
+    },
+    // ── Bluetooth ────────────────────────────────────────────────────
+    ModuleHelp {
+        name: "bluetooth",
+        aliases: &["bt", "bluetooth"],
+        feature: "mod-bt",
+        summary: "Bluetooth device status, connection management, and plugin modes.",
+        args_synopsis: "[show|connect|disconnect|cycle|menu|get_modes|set_mode|cycle_mode] [args...]",
+        args_detail: &[
+            ("show", "Display the active device's status (default)"),
+            (
+                "connect <mac>",
+                "Connect to the device with the given MAC address",
+            ),
+            (
+                "disconnect [mac]",
+                "Disconnect the active device, or a specific MAC",
+            ),
+            (
+                "cycle",
+                "Cycle through connected devices (multi-device setups)",
+            ),
+            (
+                "menu",
+                "Open an interactive device picker (client-side, uses menu_command)",
+            ),
+            (
+                "get_modes [mac]",
+                "List available plugin modes (e.g. ANC modes for Pixel Buds)",
+            ),
+            (
+                "set_mode <mode> [mac]",
+                "Set a plugin mode on the active or specified device",
+            ),
+            ("cycle_mode [mac]", "Advance to the next plugin mode"),
+        ],
+        tokens: &[
+            ("alias", "Device display name (e.g. \"Pixel Buds Pro\")"),
+            ("mac", "Device MAC address"),
+            ("left", "Left earbud battery (plugin, e.g. \"85%\")"),
+            ("right", "Right earbud battery (plugin, e.g. \"90%\")"),
+            (
+                "anc",
+                "ANC mode label (plugin, e.g. \"ANC\", \"Aware\", \"Off\")",
+            ),
+        ],
+        examples: &[
+            ("fluxo bt", "Show the active BT device"),
+            (
+                "fluxo bt connect AA:BB:CC:DD:EE:FF",
+                "Connect to a specific device",
+            ),
+            ("fluxo bt disconnect", "Disconnect the active device"),
+            ("fluxo bt menu", "Open the interactive BT device menu"),
+            ("fluxo bt cycle_mode", "Toggle ANC mode on Pixel Buds"),
+            ("fluxo bt set_mode aware", "Set ANC to aware mode"),
+        ],
+    },
+    // ── D-Bus ────────────────────────────────────────────────────────
+    ModuleHelp {
+        name: "mpris",
+        aliases: &["mpris"],
+        feature: "mod-dbus",
+        summary: "MPRIS media player status (artist, title, playback state).",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("artist", "Current track artist"),
+            ("title", "Current track title"),
+            ("album", "Current track album"),
+            ("status_icon", "Playback icon (play/pause/stop glyph)"),
+        ],
+        examples: &[("fluxo mpris", "Show current media player status")],
+    },
+    ModuleHelp {
+        name: "backlight",
+        aliases: &["backlight"],
+        feature: "mod-dbus",
+        summary: "Screen brightness percentage (inotify-driven).",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[
+            ("percentage", "Current brightness level (0 - 100)"),
+            ("icon", "Brightness bucket icon"),
+        ],
+        examples: &[("fluxo backlight", "Show current screen brightness")],
+    },
+    ModuleHelp {
+        name: "keyboard",
+        aliases: &["kbd", "keyboard"],
+        feature: "mod-dbus",
+        summary: "Active keyboard layout (Hyprland event-driven).",
+        args_synopsis: "",
+        args_detail: &[],
+        tokens: &[(
+            "layout",
+            "Active keyboard layout name (e.g. \"English (US)\")",
+        )],
+        examples: &[("fluxo kbd", "Show the current keyboard layout")],
+    },
+    ModuleHelp {
+        name: "dnd",
+        aliases: &["dnd"],
+        feature: "mod-dbus",
+        summary: "Do-Not-Disturb toggle (SwayNC signal-driven / Dunst polling).",
+        args_synopsis: "[show|toggle]",
+        args_detail: &[
+            ("show", "Display the current DND state (default)"),
+            ("toggle", "Toggle DND on/off via the notification daemon"),
+        ],
+        tokens: &[],
+        examples: &[
+            ("fluxo dnd", "Show current DND state"),
+            ("fluxo dnd toggle", "Toggle Do-Not-Disturb"),
+        ],
+    },
+];
+
+/// Print help for all modules or a single module by name.
+pub fn print_help(module: Option<&str>) {
+    if let Some(name) = module {
+        let found = MODULES.iter().find(|m| {
+            m.aliases.iter().any(|a| a.eq_ignore_ascii_case(name))
+                || m.name.eq_ignore_ascii_case(name)
+        });
+
+        match found {
+            Some(m) => print_module_detail(m),
+            None => {
+                eprintln!("Unknown module: \"{}\"\n", name);
+                eprintln!("Run `fluxo help` to see all available modules.");
+                std::process::exit(1);
+            }
+        }
+    } else {
+        print_overview();
+    }
+}
+
+fn print_overview() {
+    println!("\x1b[1;36mfluxo\x1b[0m — high-performance daemon/client for Waybar custom modules\n");
+
+    println!("\x1b[1mUSAGE:\x1b[0m");
+    println!("    fluxo daemon [--config <path>]    Start the background daemon");
+    println!("    fluxo reload                      Hot-reload the daemon config");
+    println!("    fluxo <module> [args...]           Query or control a module");
+    println!("    fluxo help [module]                Show this help or module details\n");
+
+    println!("\x1b[1mCONFIGURATION:\x1b[0m");
+    println!("    Config file:  $XDG_CONFIG_HOME/fluxo/config.toml");
+    println!("    Format tokens in config strings use {{token}} syntax.");
+    println!("    Run `fluxo help <module>` to see available tokens.\n");
+
+    let categories: &[(&str, &[&str])] = &[
+        (
+            "Hardware",
+            &[
+                "cpu", "memory", "sys", "gpu", "disk", "pool", "power", "game",
+            ],
+        ),
+        ("Network", &["network"]),
+        ("Audio", &["vol (sink)", "mic (source)"]),
+        ("Bluetooth", &["bluetooth"]),
+        ("D-Bus", &["mpris", "backlight", "keyboard", "dnd"]),
+    ];
+
+    println!("\x1b[1mMODULES:\x1b[0m\n");
+
+    for (category, names) in categories {
+        println!(
+            "  \x1b[1;33m{}\x1b[0m  ({})",
+            category,
+            feature_for_category(category)
+        );
+        for module_name in *names {
+            if let Some(m) = MODULES.iter().find(|m| m.name == *module_name) {
+                let aliases = m.aliases.join(", ");
+                println!("    \x1b[1;32m{:<18}\x1b[0m {}", aliases, m.summary,);
+                if !m.args_synopsis.is_empty() {
+                    println!("    {:<18} args: {}", "", m.args_synopsis,);
+                }
+            }
+        }
+        println!();
+    }
+
+    println!("\x1b[1mEXAMPLES:\x1b[0m\n");
+    println!("    fluxo daemon                Start the daemon");
+    println!("    fluxo cpu                   Show CPU usage and temperature");
+    println!("    fluxo vol up 10             Increase volume by 10%");
+    println!("    fluxo bt menu               Open Bluetooth device picker");
+    println!("    fluxo dnd toggle            Toggle Do-Not-Disturb");
+    println!("    fluxo help vol              Show detailed help for the volume module");
+    println!();
+    println!("For detailed module info: \x1b[1mfluxo help <module>\x1b[0m");
+}
+
+fn print_module_detail(m: &ModuleHelp) {
+    println!("\x1b[1;36mfluxo {}\x1b[0m — {}\n", m.name, m.summary);
+
+    // Aliases
+    if m.aliases.len() > 1
+        || m.aliases.first() != Some(&m.name.split_whitespace().next().unwrap_or(m.name))
+    {
+        println!("\x1b[1mALIASES:\x1b[0m  {}", m.aliases.join(", "));
+        println!();
+    }
+
+    // Feature gate
+    println!("\x1b[1mFEATURE:\x1b[0m  {}", m.feature);
+    println!();
+
+    // Usage
+    println!("\x1b[1mUSAGE:\x1b[0m");
+    let primary = m.aliases.first().unwrap_or(&m.name);
+    if m.args_synopsis.is_empty() {
+        println!("    fluxo {}", primary);
+    } else {
+        println!("    fluxo {} {}", primary, m.args_synopsis);
+    }
+    println!();
+
+    // Arguments
+    if !m.args_detail.is_empty() {
+        println!("\x1b[1mARGUMENTS:\x1b[0m\n");
+        let max_name = m
+            .args_detail
+            .iter()
+            .map(|(n, _)| n.len())
+            .max()
+            .unwrap_or(0);
+        for (name, desc) in m.args_detail {
+            println!(
+                "    \x1b[32m{:<width$}\x1b[0m    {}",
+                name,
+                desc,
+                width = max_name
+            );
+        }
+        println!();
+    }
+
+    // Format tokens
+    if !m.tokens.is_empty() {
+        println!("\x1b[1mFORMAT TOKENS:\x1b[0m  (for use in config.toml format strings)\n");
+        let max_token = m.tokens.iter().map(|(t, _)| t.len()).max().unwrap_or(0);
+        for (token, desc) in m.tokens {
+            let padded = format!("{{{}}}", token);
+            println!(
+                "    \x1b[33m{:<width$}\x1b[0m  {}",
+                padded,
+                desc,
+                width = max_token + 2 // +2 for the braces
+            );
+        }
+        println!();
+    }
+
+    // Examples
+    if !m.examples.is_empty() {
+        println!("\x1b[1mEXAMPLES:\x1b[0m\n");
+        for (cmd, desc) in m.examples {
+            println!("    \x1b[1m$\x1b[0m {:<34}  # {}", cmd, desc);
+        }
+        println!();
+    }
+}
+
+fn feature_for_category(category: &str) -> &'static str {
+    match category {
+        "Hardware" => "mod-hardware",
+        "Network" => "mod-network",
+        "Audio" => "mod-audio",
+        "Bluetooth" => "mod-bt",
+        "D-Bus" => "mod-dbus",
+        _ => "default",
+    }
+}

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,26 +1,78 @@
+//! `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;
+#[cfg(feature = "mod-bt")]
+mod bt_menu;
+mod client;
 mod config;
 mod daemon;
 mod error;
+mod health;
+mod help;
 mod ipc;
 mod modules;
 mod output;
+mod registry;
 mod signaler;
 mod state;
 mod utils;
 
-use clap::{Parser, Subcommand};
+use clap::{Parser, Subcommand, ValueEnum};
 use std::path::PathBuf;
 use std::process;
 use tracing::{error, info};
 use tracing_subscriber::{EnvFilter, fmt, prelude::*};
 
+#[derive(Clone, ValueEnum)]
+enum LogLevel {
+    Trace,
+    Debug,
+    Info,
+    Warn,
+    Error,
+}
+
+impl From<LogLevel> for tracing::Level {
+    fn from(level: LogLevel) -> Self {
+        match level {
+            LogLevel::Trace => tracing::Level::TRACE,
+            LogLevel::Debug => tracing::Level::DEBUG,
+            LogLevel::Info => tracing::Level::INFO,
+            LogLevel::Warn => tracing::Level::WARN,
+            LogLevel::Error => tracing::Level::ERROR,
+        }
+    }
+}
+
 #[derive(Parser)]
 #[command(name = "fluxo")]
 #[command(about = "A high-performance daemon/client for Waybar custom modules", long_about = None)]
+#[command(disable_help_subcommand = true, disable_help_flag = true)]
 struct Cli {
     #[command(subcommand)]
     command: Option<Commands>,
 
+    /// Print help information
+    #[arg(short, long, global = true)]
+    help: bool,
+
+    /// Set the log level (trace, debug, info, warn, error)
+    #[arg(long, global = true, value_enum)]
+    loglevel: Option<LogLevel>,
+
     /// Module name to query or interact with
     module: Option<String>,
 
@@ -39,15 +91,35 @@ enum Commands {
     },
     /// Reload the daemon configuration
     Reload,
+    /// Show detailed help for all modules or a specific module
+    Help {
+        /// Optional module name to show detailed help for
+        module: Option<String>,
+    },
 }
 
 fn main() {
+    let cli = Cli::parse();
+
+    // Explicit --loglevel takes priority, then RUST_LOG env var, then a
+    // sensible default: INFO for the daemon, WARN for client commands.
+    let default_level = if let Some(level) = &cli.loglevel {
+        tracing::Level::from(level.clone())
+    } else if matches!(&cli.command, Some(Commands::Daemon { .. })) {
+        tracing::Level::INFO
+    } else {
+        tracing::Level::WARN
+    };
+
     tracing_subscriber::registry()
         .with(fmt::layer().with_target(false).pretty())
-        .with(EnvFilter::from_default_env().add_directive(tracing::Level::INFO.into()))
+        .with(EnvFilter::from_default_env().add_directive(default_level.into()))
         .init();
 
-    let cli = Cli::parse();
+    if cli.help {
+        help::print_help(None);
+        return;
+    }
 
     if let Some(command) = &cli.command {
         match command {
@@ -70,117 +142,16 @@ fn main() {
                     process::exit(1);
                 }
             },
+            Commands::Help { module } => {
+                help::print_help(module.as_deref());
+            }
         }
         return;
     }
 
     if let Some(module) = &cli.module {
-        // Special case for client-side Bluetooth menu which requires UI
+        client::run_module_command(module, &cli.args);
-        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());
-
-            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())
-            {
-                for line in devices_str.lines() {
-                    if !line.is_empty() {
-                        items.push(line.to_string());
-                    }
-                }
-            }
-
-            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"]));
-                    } else if selected == "--- Connect Device ---" {
-                        // Do nothing
-                    } else if let Some(mac_start) = selected.rfind('(')
-                        && let Some(mac_end) = selected.rfind(')')
-                    {
-                        let mac = &selected[mac_start + 1..mac_end];
-                        handle_ipc_response(ipc::request_data("bt", &["connect", mac]));
-                    }
-                }
     } else {
-                info!("No Bluetooth options found.");
+        help::print_help(None);
-            }
-            return;
-        }
-
-        // Generic module dispatch
-        // To handle module-specific default targets like "vol up" -> "vol sink up" or "mic up" -> "vol source up"
-        // Wait, `daemon.rs` `evaluate_module_for_signaler` defaults `vol` to `sink show`.
-        // If we map `mic` to `["vol", "source"]` in `main.rs` instead of keeping `mic` in daemon:
-        let (actual_module, actual_args) = if module == "vol" {
-            let mut new_args = vec!["sink".to_string()];
-            new_args.extend(cli.args.clone());
-            ("vol".to_string(), new_args)
-        } else if module == "mic" {
-            let mut new_args = vec!["source".to_string()];
-            new_args.extend(cli.args.clone());
-            ("vol".to_string(), new_args)
-        } else {
-            (module.clone(), cli.args.clone())
-        };
-
-        let args_ref: Vec<&str> = actual_args.iter().map(|s| s.as_str()).collect();
-        handle_ipc_response(ipc::request_data(&actual_module, &args_ref));
-    } else {
-        println!("Please specify a module or command. See --help.");
-        process::exit(1);
-    }
-}
-
-fn handle_ipc_response(response: anyhow::Result<String>) {
-    match response {
-        Ok(json_str) => match serde_json::from_str::<serde_json::Value>(&json_str) {
-            Ok(mut val) => {
-                if let Some(text) = val.get_mut("text").and_then(|t| t.as_str()) {
-                    let processed_text = if text.contains('<') {
-                        text.to_string()
-                    } else {
-                        text.replace(' ', "\u{2007}")
-                    };
-
-                    let fixed_text = format!("\u{200B}{}\u{200B}", processed_text);
-                    val["text"] = serde_json::Value::String(fixed_text);
-                }
-                println!("{}", serde_json::to_string(&val).unwrap());
-            }
-            Err(_) => println!("{}", json_str),
-        },
-        Err(e) => {
-            let err_out = output::WaybarOutput {
-                text: format!("\u{200B}Daemon offline ({})\u{200B}", e),
-                tooltip: Some(e.to_string()),
-                class: Some("error".to_string()),
-                percentage: None,
-            };
-            println!("{}", serde_json::to_string(&err_out).unwrap());
-            process::exit(1);
-        }
     }
 }

src/modules/audio.rs

@@ -1,17 +1,26 @@
+//! PulseAudio/PipeWire sink + source indicator with live event subscription.
+//!
+//! The daemon runs on its own OS thread because libpulse's threaded mainloop
+//! must drive callbacks inside its own lock scope. Volume/mute changes are
+//! routed back via an async [`mpsc`] channel — the module handlers [`run`]s
+//! only push commands; the thread performs the actual libpulse calls.
+
 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;
 
+/// Commands the module handler sends to the audio daemon thread.
 pub enum AudioCommand {
     ChangeVolume {
         is_sink: bool,
@@ -26,13 +35,17 @@ pub enum AudioCommand {
     },
 }
 
+/// Long-lived daemon driving libpulse's threaded mainloop.
 pub struct AudioDaemon;
 
 impl AudioDaemon {
+    /// Construct a new (stateless) daemon.
     pub fn new() -> Self {
         Self
     }
 
+    /// Spawn the audio thread, subscribe to sink/source/server events, and
+    /// start consuming [`AudioCommand`]s.
     pub fn start(
         &self,
         state_tx: &watch::Sender<AudioState>,
@@ -45,7 +58,7 @@ impl AudioDaemon {
                 ThreadedMainloop::new().expect("Failed to create pulse threaded mainloop");
 
             let mut context =
-                Context::new(&mainloop, "fluxo-rs").expect("Failed to create pulse context");
+                Context::new(&mainloop, "fluxo").expect("Failed to create pulse context");
 
             context
                 .connect(None, ContextFlag::NOFLAGS, None)
@@ -55,7 +68,6 @@ impl AudioDaemon {
 
             mainloop.lock();
 
-            // Wait for context to be ready
             loop {
                 match context.get_state() {
                     libpulse_binding::context::State::Ready => break,
@@ -73,10 +85,8 @@ impl AudioDaemon {
                 }
             }
 
-            // Initial fetch
             let _ = fetch_audio_data_sync(&mut context, &state_tx);
 
-            // Subscribe to events
             let interest =
                 InterestMaskSet::SINK | InterestMaskSet::SOURCE | InterestMaskSet::SERVER;
             context.subscribe(interest, |_| {});
@@ -195,7 +205,6 @@ impl AudioDaemon {
 
                 mainloop.lock();
 
-                // Fetch data and update available sinks/sources
                 let _ = fetch_audio_data_sync(&mut context, &state_tx);
 
                 mainloop.unlock();
@@ -206,13 +215,12 @@ impl AudioDaemon {
 
 use std::time::Duration;
 
+/// Trigger async libpulse introspection: server defaults + sink/source lists.
+/// Callbacks publish onto `state_tx` as results land.
 fn fetch_audio_data_sync(
     context: &mut Context,
     state_tx: &watch::Sender<AudioState>,
 ) -> Result<()> {
-    // We fetch all sinks and sources, and also server info to know defaults.
-    // The order doesn't strictly matter as long as we update correctly.
-
     let tx_server = state_tx.clone();
     context.introspect().get_server_info(move |info| {
         let mut current = tx_server.borrow().clone();
@@ -229,92 +237,131 @@ fn fetch_audio_data_sync(
         let _ = tx_server.send(current);
     });
 
-    let tx_sink = state_tx.clone();
+    fetch_sinks(context, state_tx);
-    context.introspect().get_sink_info_list(move |res| {
+    fetch_sources(context, state_tx);
-        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 => {}
-        }
-    });
 
     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)
+}
+
+/// Write `info` into `target` only when `item_name` matches the currently
+/// selected default device — other sinks/sources are ignored here.
+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;
+    }
+}
+
+/// Dispatch `get_sink_info_list` and collect names into `available_sinks`.
+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 => {}
+        }
+    });
+}
+
+/// Dispatch `get_source_info_list` and collect names (skipping `.monitor`
+/// virtual sources) into `available_sources`.
+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 => {}
+        }
+    });
+}
+
+/// Renders sink/source + dispatches volume/mute/cycle commands.
+/// Args: `[sink|source] [show|up|down|mute|cycle] [step]`.
 pub struct AudioModule;
 
 impl WaybarModule for AudioModule {
@@ -331,19 +378,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 {
@@ -380,7 +427,6 @@ impl AudioModule {
         };
 
         if name.is_empty() {
-            // Fallback if daemon hasn't populated state yet
             return Ok(WaybarOutput {
                 text: "Audio Loading...".to_string(),
                 ..Default::default()

src/modules/backlight.rs

@@ -1,3 +1,7 @@
+//! Screen backlight indicator, driven by `inotify` on
+//! `/sys/class/backlight/*/actual_brightness`. Falls back to a 5 s poll loop
+//! to catch any missed events.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
@@ -11,6 +15,7 @@ use std::time::Duration;
 use tokio::sync::watch;
 use tracing::{error, info};
 
+/// Renders the brightness percentage with a vendor-agnostic icon bucket.
 pub struct BacklightModule;
 
 impl WaybarModule for BacklightModule {
@@ -47,13 +52,16 @@ impl WaybarModule for BacklightModule {
     }
 }
 
+/// Background `inotify` watcher thread for the sysfs backlight file.
 pub struct BacklightDaemon;
 
 impl BacklightDaemon {
+    /// Construct a new (stateless) daemon.
     pub fn new() -> Self {
         Self
     }
 
+    /// Spawn an OS thread that publishes brightness changes onto `tx`.
     pub fn start(&self, tx: watch::Sender<BacklightState>) {
         std::thread::spawn(move || {
             let base_dir = PathBuf::from("/sys/class/backlight");
@@ -105,12 +113,10 @@ impl BacklightDaemon {
                 }
             };
 
-            // Initial poll
             let _ = tx.send(BacklightState {
                 percentage: get_percentage(),
             });
 
-            // Set up notify watcher
             let (ev_tx, ev_rx) = mpsc::channel();
             let mut watcher = RecommendedWatcher::new(
                 move |res: notify::Result<Event>| {
@@ -130,9 +136,8 @@ impl BacklightDaemon {
             }
 
             loop {
-                // Block until an event occurs or a timeout to catch missed events
                 if ev_rx.recv_timeout(Duration::from_secs(5)).is_ok() {
-                    // Debounce rapid events
+                    // Debounce bursts from scroll-driven brightness changes.
                     std::thread::sleep(Duration::from_millis(50));
                     while ev_rx.try_recv().is_ok() {}
 
@@ -140,7 +145,7 @@ impl BacklightDaemon {
                         percentage: get_percentage(),
                     });
                 } else {
-                    // Timeout hit, poll just in case
+                    // Timeout reached — resync in case an event was missed.
                     let current = get_percentage();
                     if tx.borrow().percentage != current {
                         let _ = tx.send(BacklightState {

src/modules/bt/buds.rs

@@ -1,3 +1,6 @@
+//! Per-device BT plugin trait + PixelBuds Pro implementation on top of the
+//! Maestro GATT connection.
+
 use crate::config::Config;
 use crate::error::{FluxoError, Result as FluxoResult};
 use crate::modules::bt::maestro::BudsCommand;
@@ -5,29 +8,38 @@ use crate::state::AppReceivers;
 use crate::utils::TokenValue;
 use futures::future::BoxFuture;
 
+/// A device-specific adapter that can enrich [`BtState`](crate::state::BtState)
+/// with extra metadata and expose control actions (modes).
 pub trait BtPlugin: Send + Sync {
+    /// Plugin identifier used for logging.
     fn name(&self) -> &str;
+    /// Return true if this plugin handles a device with `alias`/`mac`.
     fn can_handle(&self, alias: &str, mac: &str) -> bool;
+    /// Return `(token_name, value)` pairs merged into the rendered template.
     fn get_data(
         &self,
         config: &Config,
         state: &AppReceivers,
         mac: &str,
     ) -> BoxFuture<'static, FluxoResult<Vec<(String, TokenValue)>>>;
+    /// List of mode identifiers the plugin can switch between.
     fn get_modes(
         &self,
         mac: &str,
         state: &AppReceivers,
     ) -> BoxFuture<'static, FluxoResult<Vec<String>>>;
+    /// Switch device to `mode` (must be one returned by `get_modes`).
     fn set_mode(
         &self,
         mode: &str,
         mac: &str,
         state: &AppReceivers,
     ) -> BoxFuture<'static, FluxoResult<()>>;
+    /// Advance to the next mode in the list (wraps around).
     fn cycle_mode(&self, mac: &str, state: &AppReceivers) -> BoxFuture<'static, FluxoResult<()>>;
 }
 
+/// Google Pixel Buds Pro plugin. Reads battery + ANC state via Maestro GATT.
 pub struct PixelBudsPlugin;
 
 impl BtPlugin for PixelBudsPlugin {

src/modules/bt/maestro.rs

@@ -1,3 +1,11 @@
+//! Google Maestro (PixelBuds GATT) integration.
+//!
+//! Each connected device gets its own [`buds_task`] running on a dedicated
+//! single-threaded runtime. The task opens an RFCOMM channel, speaks the
+//! Maestro protocol to read battery + ANC state, and listens for settings
+//! changes. External callers interact via [`MaestroManager::send_command`]
+//! and [`MaestroManager::get_status`].
+
 use crate::state::AppReceivers;
 use anyhow::{Context, Result};
 use futures::StreamExt;
@@ -7,12 +15,12 @@ use std::time::{Duration, Instant};
 use tokio::sync::mpsc;
 use tracing::{debug, error, info, warn};
 
-// Maestro imports
 use maestro::protocol::codec::Codec;
 use maestro::pwrpc::client::Client;
 use maestro::service::MaestroService;
 use maestro::service::settings::{self, SettingValue};
 
+/// Cached per-device snapshot returned to BT plugin consumers.
 #[derive(Clone, Default)]
 pub struct BudsStatus {
     pub left_battery: Option<u8>,
@@ -24,28 +32,35 @@ pub struct BudsStatus {
     pub error: Option<String>,
 }
 
+/// Command that can be issued against a connected buds device.
 pub enum BudsCommand {
+    /// Set the ANC mode: `active`, `aware`, or `off`.
     SetAnc(String),
 }
 
+/// Messages sent to the [`MaestroManager`] control thread.
 pub enum ManagerCommand {
+    /// Ensure a [`buds_task`] is running for `mac`; spawn if absent.
     EnsureTask(String),
+    /// Forward a [`BudsCommand`] to the task for `mac`.
     SendCommand(String, BudsCommand),
 }
 
+/// Owns all buds-task lifetimes and a shared status cache.
 pub struct MaestroManager {
     statuses: Arc<Mutex<HashMap<String, BudsStatus>>>,
     management_tx: mpsc::UnboundedSender<ManagerCommand>,
 }
 
 impl MaestroManager {
+    /// Spawn the management thread + runtime and return a handle.
     pub fn new(state: AppReceivers) -> Self {
         let (tx, mut rx) = mpsc::unbounded_channel::<ManagerCommand>();
         let statuses = Arc::new(Mutex::new(HashMap::new()));
         let statuses_clone = Arc::clone(&statuses);
         let state_clone = state.clone();
 
-        // Start dedicated BT management thread
+        // Dedicated thread — bluer uses per-thread local tasks.
         std::thread::spawn(move || {
             let rt = tokio::runtime::Builder::new_current_thread()
                 .enable_all()
@@ -85,7 +100,7 @@ impl MaestroManager {
                             }
                         }
                         _ = tokio::time::sleep(Duration::from_millis(100)) => {
-                            // Cleanup dropped tasks if needed
+                            // Wake tick: future hook for task-lifecycle cleanup.
                         }
                     }
                 }
@@ -98,17 +113,20 @@ impl MaestroManager {
         }
     }
 
+    /// Return the cached [`BudsStatus`] for `mac` (default if absent).
     pub fn get_status(&self, mac: &str) -> BudsStatus {
         let statuses = self.statuses.lock().unwrap();
         statuses.get(mac).cloned().unwrap_or_default()
     }
 
+    /// Request that a buds task be running for `mac`. Idempotent.
     pub fn ensure_task(&self, mac: &str) {
         let _ = self
             .management_tx
             .send(ManagerCommand::EnsureTask(mac.to_string()));
     }
 
+    /// Ensure a task exists and forward `cmd` to it.
     pub fn send_command(&self, mac: &str, cmd: BudsCommand) -> Result<()> {
         self.ensure_task(mac);
         let _ = self
@@ -118,6 +136,8 @@ impl MaestroManager {
     }
 }
 
+/// Per-device async task: opens RFCOMM, runs the Maestro codec, mirrors
+/// battery/ANC state into the shared status map, and consumes commands.
 async fn buds_task(
     mac: &str,
     statuses: Arc<Mutex<HashMap<String, BudsStatus>>>,
@@ -150,7 +170,7 @@ async fn buds_task(
             break;
         }
 
-        // Connect to Maestro RFCOMM service
+        // Maestro historically listens on channel 1 or 2 — probe both.
         let mut stream = None;
         for channel in [1, 2] {
             let socket = match bluer::rfcomm::Socket::new() {
@@ -190,13 +210,11 @@ async fn buds_task(
 
         info!("Connected Maestro RFCOMM to {} on channel", mac);
 
-        // Initialize Maestro communication stack
         let codec = Codec::new();
         let stream = codec.wrap(stream);
         let mut client = Client::new(stream);
         let handle = client.handle();
 
-        // Resolve Maestro channel
         let channel = match maestro::protocol::utils::resolve_channel(&mut client).await {
             Ok(c) => c,
             Err(e) => {
@@ -213,7 +231,7 @@ async fn buds_task(
 
         let mut service = MaestroService::new(handle, channel);
 
-        // Update health
+        // Successful connect — clear health backoff for bt.buds.
         {
             let mut lock = state.health.write().await;
             let health = lock.entry("bt.buds".to_string()).or_default();
@@ -221,7 +239,6 @@ async fn buds_task(
             health.backoff_until = None;
         }
 
-        // Query initial ANC state
         if let Ok(val) = service
             .read_setting_var(settings::SettingId::CurrentAncrState)
             .await
@@ -337,6 +354,7 @@ async fn buds_task(
     Ok(())
 }
 
+/// String ("active"/"aware"/"off") → Maestro enum; unknown falls back to `Off`.
 fn mode_to_anc_state(mode: &str) -> settings::AncState {
     match mode {
         "active" => settings::AncState::Active,
@@ -346,6 +364,7 @@ fn mode_to_anc_state(mode: &str) -> settings::AncState {
     }
 }
 
+/// Inverse of [`mode_to_anc_state`] for status readout.
 pub fn anc_state_to_string(state: &settings::AncState) -> String {
     match state {
         settings::AncState::Active => "active".to_string(),
@@ -357,6 +376,7 @@ pub fn anc_state_to_string(state: &settings::AncState) -> String {
 
 static MAESTRO: OnceLock<MaestroManager> = OnceLock::new();
 
+/// Lazily initialise the process-wide [`MaestroManager`] and return a reference.
 pub fn get_maestro(state: &AppReceivers) -> &MaestroManager {
     MAESTRO.get_or_init(|| MaestroManager::new(state.clone()))
 }

src/modules/bt/mod.rs

@@ -1,3 +1,11 @@
+//! Bluetooth indicator + control (BlueZ via `bluer`).
+//!
+//! Core loop: filter paired+connected audio-sink devices, enrich them via
+//! per-device [`BtPlugin`]s (currently PixelBuds via the Maestro GATT
+//! protocol), and publish the result as [`BtState`]. The module handler
+//! exposes `connect`, `disconnect`, `cycle`, `menu_data`, `get_modes`,
+//! `set_mode`, `cycle_mode` actions for the Waybar menu.
+
 pub mod buds;
 pub mod maestro;
 
@@ -5,7 +13,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;
@@ -14,15 +22,18 @@ use tracing::{error, warn};
 
 use self::buds::{BtPlugin, PixelBudsPlugin};
 
+/// Background poller that syncs connected BlueZ devices into [`BtState`].
 pub struct BtDaemon {
     session: Option<bluer::Session>,
 }
 
 impl BtDaemon {
+    /// Construct a new daemon. The BlueZ session is lazily created on first poll.
     pub fn new() -> Self {
         Self { session: None }
     }
 
+    /// Poll wrapper that logs + swallows errors so the outer loop keeps running.
     pub async fn poll(
         &mut self,
         tx: &watch::Sender<BtState>,
@@ -47,32 +58,35 @@ impl BtDaemon {
         let adapter = session.default_adapter().await?;
         let adapter_powered = adapter.is_powered().await.unwrap_or(false);
 
-        let mut bt_state = BtState {
+        let mut connected_devices = Vec::new();
-            adapter_powered,
-            ..Default::default()
-        };
 
         if adapter_powered {
-            let devices = adapter.device_addresses().await?;
+            let mut addresses = adapter.device_addresses().await?;
-            for addr in devices {
+            addresses.sort();
+            let audio_sink_uuid = bluer::Uuid::from_u128(0x0000110b_0000_1000_8000_00805f9b34fb);
+
+            for addr in addresses {
                 let device = adapter.device(addr)?;
-                if device.is_connected().await.unwrap_or(false) {
+                if !device.is_connected().await.unwrap_or(false) {
+                    continue;
+                }
                 let uuids = device.uuids().await?.unwrap_or_default();
-                    let audio_sink_uuid =
+                if !uuids.contains(&audio_sink_uuid) {
-                        bluer::Uuid::from_u128(0x0000110b_0000_1000_8000_00805f9b34fb);
+                    continue;
-                    if uuids.contains(&audio_sink_uuid) {
+                }
-                        bt_state.connected = true;
+
-                        bt_state.device_address = addr.to_string();
+                let mut dev_info = BtDeviceInfo {
-                        bt_state.device_alias =
+                    device_address: addr.to_string(),
-                            device.alias().await.unwrap_or_else(|_| addr.to_string());
+                    device_alias: device.alias().await.unwrap_or_else(|_| addr.to_string()),
-                        bt_state.battery_percentage =
+                    battery_percentage: device.battery_percentage().await.unwrap_or(None),
-                            device.battery_percentage().await.unwrap_or(None);
+                    plugin_data: vec![],
+                };
 
                 for p in PLUGINS.iter() {
-                            if p.can_handle(&bt_state.device_alias, &bt_state.device_address) {
+                    if p.can_handle(&dev_info.device_alias, &dev_info.device_address) {
-                                match p.get_data(config, state, &bt_state.device_address).await {
+                        match p.get_data(config, state, &dev_info.device_address).await {
                             Ok(data) => {
-                                        bt_state.plugin_data = data
+                                dev_info.plugin_data = data
                                     .into_iter()
                                     .map(|(k, v)| {
                                         let val_str = match v {
@@ -86,7 +100,7 @@ impl BtDaemon {
                             }
                             Err(e) => {
                                 warn!("Plugin {} failed for {}: {}", p.name(), addr, e);
-                                        bt_state
+                                dev_info
                                     .plugin_data
                                     .push(("plugin_error".to_string(), e.to_string()));
                             }
@@ -94,13 +108,14 @@ impl BtDaemon {
                         break;
                     }
                 }
-                        break;
+                connected_devices.push(dev_info);
-                    }
-                }
             }
         }
 
-        let _ = tx.send(bt_state);
+        let _ = tx.send(BtState {
+            adapter_powered,
+            devices: connected_devices,
+        });
 
         Ok(())
     }
@@ -109,10 +124,10 @@ impl BtDaemon {
 static PLUGINS: LazyLock<Vec<Box<dyn BtPlugin>>> =
     LazyLock::new(|| vec![Box::new(PixelBudsPlugin)]);
 
+/// After a user-initiated connect/disconnect, schedule a staircase of
+/// forced polls so the UI catches up even if BlueZ is slow to settle.
 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 +135,27 @@ 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)
+}
+
+/// Renders the current BT status + handles control actions.
 pub struct BtModule;
 
 impl WaybarModule for BtModule {
@@ -129,12 +165,10 @@ impl WaybarModule for BtModule {
         state: &AppReceivers,
         args: &[&str],
     ) -> FluxoResult<WaybarOutput> {
-        let action = args.first().cloned().unwrap_or("show").to_string();
+        let action = args.first().cloned().unwrap_or("show");
-        let args = args.iter().map(|s| s.to_string()).collect::<Vec<_>>();
-
         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,74 +182,120 @@ impl WaybarModule for BtModule {
                 }
                 return Ok(WaybarOutput::default());
             }
-            "disconnect" if bt_state.connected => {
+            "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) = bt_state.device_address.parse::<bluer::Address>()
+                        && let Ok(addr) = mac.parse::<bluer::Address>()
                         && let Ok(device) = adapter.device(addr)
                     {
                         let _ = device.disconnect().await;
                     }
                     trigger_robust_poll(state.clone());
+                }
+                return Ok(WaybarOutput::default());
+            }
+            "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 devs = Vec::new();
+                let mut lines = Vec::new();
+
+                for dev in &bt_state.devices {
+                    lines.push(format!(
+                        "CONNECTED:{}|{}",
+                        dev.device_alias, dev.device_address
+                    ));
+                }
+
+                // Also surface paired-but-not-connected devices for the menu.
                 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());
-                            devs.push(format!("{} ({})", alias, addr));
+                            lines.push(format!("PAIRED:{}|{}", alias, addr_str));
                         }
                     }
                 }
+
                 return Ok(WaybarOutput {
-                    text: devs.join("\n"),
+                    text: lines.join("\n"),
                     ..Default::default()
                 });
             }
-            "cycle_mode" if bt_state.connected => {
+            "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.cycle_mode(&bt_state.device_address, state).await?;
+                        let modes = p.get_modes(&mac, 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![]
-                };
                         return Ok(WaybarOutput {
                             text: modes.join("\n"),
                             ..Default::default()
                         });
                     }
-            "set_mode" if bt_state.connected => {
+                }
+                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(&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?;
+                            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" => {}
             _ => {}
         }
 
@@ -228,22 +308,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 +344,9 @@ impl WaybarModule for BtModule {
             let text = format_template(format, &tokens);
             let tooltip = format!(
                 "{} | MAC: {}\nBattery: {}",
-                bt_state.device_alias,
+                dev.device_alias,
-                bt_state.device_address,
+                dev.device_address,
-                bt_state
+                dev.battery_percentage
-                    .battery_percentage
                     .map(|b| format!("{}%", b))
                     .unwrap_or_else(|| "N/A".to_string())
             );
@@ -275,7 +355,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/btrfs.rs

@@ -1,10 +1,15 @@
+//! Btrfs pool renderer: sums usage across all btrfs-typed mounts seen in the
+//! `disks` watch channel. Dispatch-only (no dedicated poll task).
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
 use crate::state::AppReceivers;
-use crate::utils::{TokenValue, format_template};
+use crate::utils::{TokenValue, classify_usage, format_template};
 
+/// Aggregates used/total across every mount whose filesystem name contains
+/// `btrfs`. Emits `No BTRFS` when none are present.
 pub struct BtrfsModule;
 
 impl WaybarModule for BtrfsModule {
@@ -44,13 +49,7 @@ impl WaybarModule for BtrfsModule {
         let size_gb = total_size / 1024.0 / 1024.0 / 1024.0;
         let percentage = (total_used / total_size) * 100.0;
 
-        let class = if percentage > 95.0 {
+        let class = classify_usage(percentage, 80.0, 95.0);
-            "max"
-        } else if percentage > 80.0 {
-            "high"
-        } else {
-            "normal"
-        };
 
         let text = format_template(
             &config.pool.format,

src/modules/cpu.rs

@@ -1,10 +1,13 @@
+//! CPU usage + temperature renderer. Reads from the `cpu` watch channel.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
 use crate::state::AppReceivers;
-use crate::utils::{TokenValue, format_template};
+use crate::utils::{TokenValue, classify_usage, format_template};
 
+/// Renders CPU usage/temp using [`CpuConfig::format`](crate::config::CpuConfig).
 pub struct CpuModule;
 
 impl WaybarModule for CpuModule {
@@ -27,13 +30,7 @@ impl WaybarModule for CpuModule {
             ],
         );
 
-        let class = if usage > 95.0 {
+        let class = classify_usage(usage, 75.0, 95.0);
-            "max"
-        } else if usage > 75.0 {
-            "high"
-        } else {
-            "normal"
-        };
 
         Ok(WaybarOutput {
             text,

src/modules/disk.rs

@@ -1,10 +1,14 @@
+//! Filesystem usage renderer. Args: `[mountpoint]` (default `/`).
+
 use crate::config::Config;
 use crate::error::{FluxoError, Result};
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
 use crate::state::AppReceivers;
-use crate::utils::{TokenValue, format_template};
+use crate::utils::{TokenValue, classify_usage, format_template};
 
+/// Renders used/total for a given mount point. Returns [`FluxoError::Module`]
+/// if the mount point isn't present in the current disk snapshot.
 pub struct DiskModule;
 
 impl WaybarModule for DiskModule {
@@ -41,13 +45,7 @@ impl WaybarModule for DiskModule {
                     0.0
                 };
 
-                let class = if percentage > 95.0 {
+                let class = classify_usage(percentage, 80.0, 95.0);
-                    "max"
-                } else if percentage > 80.0 {
-                    "high"
-                } else {
-                    "normal"
-                };
 
                 let text = format_template(
                     &config.disk.format,
@@ -121,7 +119,7 @@ mod tests {
 
     #[tokio::test]
     async fn test_disk_not_found() {
-        let state = mock_state(AppState::default());
+        let state = state_with_disk("/", 100, 50);
         let config = Config::default();
         let result = DiskModule
             .run(&config, &state.receivers, &["/nonexistent"])

src/modules/dnd.rs

@@ -1,3 +1,9 @@
+//! Do-Not-Disturb toggle + status for SwayNC or Dunst.
+//!
+//! SwayNC exposes a `dnd` property on its `org.erikreider.swaync.control`
+//! interface that fires PropertiesChanged signals, so we subscribe. Dunst has
+//! no change signal for its `paused` property, so we fall back to a 2 s poll.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
@@ -5,18 +11,81 @@ 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};
 
+/// Renders + toggles DND state. Args: `["show"]` (default) or `["toggle"]`.
 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,
         config: &Config,
         state: &AppReceivers,
-        _args: &[&str],
+        args: &[&str],
     ) -> Result<WaybarOutput> {
+        let action = args.first().unwrap_or(&"show");
+
+        if *action == "toggle" {
+            let connection =
+                Connection::session()
+                    .await
+                    .map_err(|e| crate::error::FluxoError::Module {
+                        module: "dnd",
+                        message: format!("DBus connection failed: {}", e),
+                    })?;
+
+            if let Ok(proxy) = SwayncControlProxy::new(&connection).await
+                && let Ok(is_dnd) = proxy.dnd().await
+            {
+                let _ = proxy.set_dnd(!is_dnd).await;
+                return Ok(WaybarOutput::default());
+            }
+
+            if let Ok(is_paused) = dunst_get_paused(&connection).await {
+                let _ = dunst_set_paused(&connection, !is_paused).await;
+                return Ok(WaybarOutput::default());
+            }
+
+            return Err(crate::error::FluxoError::Module {
+                module: "dnd",
+                message: "No supported notification daemon found to toggle".to_string(),
+            });
+        }
+
         let is_dnd = state.dnd.borrow().is_dnd;
 
         if is_dnd {
@@ -37,6 +106,8 @@ impl WaybarModule for DndModule {
     }
 }
 
+/// Background watcher that keeps [`DndState`] in sync with the active
+/// notification daemon (SwayNC via signals, Dunst via polling).
 pub struct DndDaemon;
 
 #[proxy(
@@ -47,13 +118,17 @@ pub struct DndDaemon;
 trait SwayncControl {
     #[zbus(property)]
     fn dnd(&self) -> zbus::Result<bool>;
+    #[zbus(property)]
+    fn set_dnd(&self, value: bool) -> zbus::Result<()>;
 }
 
 impl DndDaemon {
+    /// Construct a new (stateless) daemon.
     pub fn new() -> Self {
         Self
     }
 
+    /// Spawn a supervised listen loop that reconnects with a 5 s backoff.
     pub fn start(&self, tx: watch::Sender<DndState>) {
         tokio::spawn(async move {
             loop {
@@ -70,16 +145,12 @@ impl DndDaemon {
 
         info!("Connected to D-Bus for DND monitoring");
 
-        // Try SwayNC first
+        if let Ok(proxy) = SwayncControlProxy::new(&connection).await
-        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");
-            // Get initial state
-            if let Ok(is_dnd) = proxy.dnd().await {
             let _ = tx.send(DndState { is_dnd });
-            }
 
-            // Monitor properties changed
             if let Ok(props_proxy) = PropertiesProxy::builder(&connection)
                 .destination("org.erikreider.swaync.control")?
                 .path("/org/erikreider/swaync/control")?
@@ -97,8 +168,42 @@ impl DndDaemon {
                     }
                 }
             }
+
+            return Err(anyhow::anyhow!("SwayNC DND stream ended"));
         }
 
-        Err(anyhow::anyhow!("DND stream ended or daemon not found"))
+        // Dunst: raw D-Bus call avoids zbus proxy typing quirks with its
+        // non-standard `org.dunstproject.cmd0` interface.
+        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 });
+
+                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!(
+            "No supported notification daemon found (tried SwayNC, Dunst)"
+        ))
     }
 }

src/modules/game.rs

@@ -1,3 +1,6 @@
+//! Gamemode indicator. Queries Hyprland's animation setting over its IPC
+//! socket; animations disabled => gamemode active. Dispatch-only.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
@@ -6,6 +9,7 @@ use crate::state::AppReceivers;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio::net::UnixStream;
 
+/// Renders a glyph depending on whether Hyprland animations are disabled.
 pub struct GameModule;
 
 impl WaybarModule for GameModule {
@@ -38,6 +42,7 @@ impl WaybarModule for GameModule {
     }
 }
 
+/// Send `cmd` to Hyprland's `.socket.sock` and return the response body.
 async fn hyprland_ipc(cmd: &str) -> Result<String> {
     let path = crate::utils::get_hyprland_socket(".socket.sock")?;
 

src/modules/gpu.rs

@@ -1,10 +1,14 @@
+//! GPU renderer. Picks a vendor-specific format string (AMD/Intel/NVIDIA) and
+//! reads from the `gpu` watch channel.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
 use crate::state::AppReceivers;
-use crate::utils::{TokenValue, format_template};
+use crate::utils::{TokenValue, classify_usage, format_template};
 
+/// Renders GPU usage / VRAM / temp using the per-vendor format from config.
 pub struct GpuModule;
 
 impl WaybarModule for GpuModule {
@@ -36,13 +40,7 @@ impl WaybarModule for GpuModule {
             });
         }
 
-        let class = if usage > 95.0 {
+        let class = classify_usage(usage, 75.0, 95.0);
-            "max"
-        } else if usage > 75.0 {
-            "high"
-        } else {
-            "normal"
-        };
 
         let format_str = match vendor.as_str() {
             "Intel" => &config.gpu.format_intel,

src/modules/hardware.rs

@@ -1,7 +1,16 @@
+//! Unified CPU/memory/sys/GPU/disk poller.
+//!
+//! CPU/memory/sys are sampled every fast tick (1 s). GPU polls every 5th fast
+//! tick via [`poll_slow`], and disks every 10th (they rarely change). GPU
+//! vendor is detected once by probing nvidia-smi / `/sys/class/drm/*`, then
+//! cached so subsequent polls take the fast path.
+
 use crate::state::{CpuState, DiskInfo, GpuState, MemoryState, SysState};
 use sysinfo::{Components, Disks, System};
 use tokio::sync::watch;
 
+/// Long-lived hardware sampler. Holds the `sysinfo::System` handle so
+/// successive refreshes can diff against prior samples.
 pub struct HardwareDaemon {
     sys: System,
     components: Components,
@@ -11,6 +20,7 @@ pub struct HardwareDaemon {
 }
 
 impl HardwareDaemon {
+    /// Build a new daemon with an initial `sysinfo` snapshot.
     pub fn new() -> Self {
         let mut sys = System::new();
         sys.refresh_cpu_usage();
@@ -21,10 +31,13 @@ impl HardwareDaemon {
             components,
             gpu_vendor: None,
             gpu_poll_counter: 0,
-            disk_poll_counter: 9, // Start at 9 to poll on the first tick
+            // Start at 9 so (counter + 1) % 10 == 0 on the first tick.
+            disk_poll_counter: 9,
         }
     }
 
+    /// Fast path: refresh CPU usage, memory, temperatures, load avg, uptime.
+    /// Called every daemon tick.
     pub async fn poll_fast(
         &mut self,
         cpu_tx: &watch::Sender<CpuState>,
@@ -96,12 +109,13 @@ impl HardwareDaemon {
         let _ = sys_tx.send(sys);
     }
 
+    /// Slow path: GPU every 5 ticks, disks every 10 ticks. Each sub-poll
+    /// runs off the hot loop before any state is published.
     pub async fn poll_slow(
         &mut self,
         gpu_tx: &watch::Sender<GpuState>,
         disks_tx: &watch::Sender<Vec<DiskInfo>>,
     ) {
-        // 1. Gather GPU data outside of lock
         let mut gpu_state = crate::state::GpuState::default();
         self.gpu_poll_counter = (self.gpu_poll_counter + 1) % 5;
         let should_poll_gpu = self.gpu_poll_counter == 0;
@@ -109,7 +123,6 @@ impl HardwareDaemon {
             self.poll_gpu(&mut gpu_state).await;
         }
 
-        // 2. Gather Disk data outside of lock
         let mut disks_data = None;
         self.disk_poll_counter = (self.disk_poll_counter + 1) % 10;
         if self.disk_poll_counter == 0 {
@@ -130,7 +143,6 @@ impl HardwareDaemon {
             );
         }
 
-        // 3. Apply to state
         if should_poll_gpu {
             let _ = gpu_tx.send(gpu_state);
         }
@@ -140,19 +152,55 @@ impl HardwareDaemon {
         }
     }
 
+    /// Dispatch to the cached vendor's probe, or run detection on first call.
     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())
+        match self.gpu_vendor.as_deref() {
-            && let Ok(output) = tokio::process::Command::new("nvidia-smi")
+            Some("NVIDIA") => {
+                Self::poll_nvidia(gpu).await;
+            }
+            Some("AMD") => {
+                Self::poll_amd(gpu);
+            }
+            Some("Intel") => {
+                Self::poll_intel(gpu);
+            }
+            _ => {
+                // First run — probe each vendor and cache the first hit.
+                Self::poll_nvidia(gpu).await;
+                if gpu.active {
+                    self.gpu_vendor = Some("NVIDIA".to_string());
+                    return;
+                }
+                Self::poll_amd(gpu);
+                if gpu.active {
+                    self.gpu_vendor = Some("AMD".to_string());
+                    return;
+                }
+                Self::poll_intel(gpu);
+                if gpu.active {
+                    self.gpu_vendor = Some("Intel".to_string());
+                }
+            }
+        }
+    }
+
+    /// Shell out to `nvidia-smi --query-gpu=...` for utilization/VRAM/temp.
+    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
-            && output.status.success()
+        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();
@@ -164,42 +212,31 @@ impl HardwareDaemon {
                 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();
-                    self.gpu_vendor = Some("NVIDIA".to_string());
-                    return;
             }
         }
     }
 
-        if self.gpu_vendor.as_deref() == Some("AMD")
+    /// Read amdgpu sysfs entries under `/sys/class/drm/card*/device`.
-            || self.gpu_vendor.as_deref() == Some("Intel")
+    fn poll_amd(gpu: &mut crate::state::GpuState) {
-            || self.gpu_vendor.is_none()
-        {
         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;
+            };
 
-                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) =
+            if let Ok(mem_used) = std::fs::read_to_string(format!("{}/mem_info_vram_used", base)) {
-                        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;
-                        gpu.vram_used = mem_used.trim().parse::<f64>().unwrap_or(0.0)
-                            / 1024.0
-                            / 1024.0
-                            / 1024.0;
             }
-                    if let Ok(mem_total) =
+            if let Ok(mem_total) = std::fs::read_to_string(format!("{}/mem_info_vram_total", base))
-                        std::fs::read_to_string(format!("{}/mem_info_vram_total", base))
             {
-                        gpu.vram_total = mem_total.trim().parse::<f64>().unwrap_or(0.0)
+                gpu.vram_total =
-                            / 1024.0
+                    mem_total.trim().parse::<f64>().unwrap_or(0.0) / 1024.0 / 1024.0 / 1024.0;
-                            / 1024.0
-                            / 1024.0;
             }
 
             if let Ok(entries) = std::fs::read_dir(format!("{}/hwmon", base)) {
@@ -212,18 +249,18 @@ impl HardwareDaemon {
                 }
             }
             gpu.model = "AMD GPU".to_string();
-                    self.gpu_vendor = Some("AMD".to_string());
             return;
         }
+    }
 
-                if self.gpu_vendor.as_deref() == Some("Intel") || self.gpu_vendor.is_none() {
+    /// Read i915/xe sysfs `gt_cur_freq_mhz`; approximate "usage" as
-                    let freq_path =
+    /// current/max frequency since Intel has no direct utilization counter.
-                        if std::path::Path::new(&format!("{}/gt_cur_freq_mhz", base)).exists() {
+    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!(
+            } else if std::path::Path::new(&format!("/sys/class/drm/card{}/gt_cur_freq_mhz", i))
-                            "/sys/class/drm/card{}/gt_cur_freq_mhz",
-                            i
-                        ))
                 .exists()
             {
                 Some(format!("/sys/class/drm/card{}/gt_cur_freq_mhz", i))
@@ -254,11 +291,8 @@ impl HardwareDaemon {
                 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;
             }
         }
     }
-        }
-    }
 }

src/modules/keyboard.rs

@@ -1,3 +1,7 @@
+//! Keyboard layout indicator backed by Hyprland's event socket
+//! (`.socket2.sock`). Also seeds the initial layout by shelling out to
+//! `hyprctl devices -j` once at startup.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
@@ -10,6 +14,7 @@ use tokio::net::UnixStream;
 use tokio::sync::watch;
 use tracing::{error, info};
 
+/// Renders the current keyboard layout from [`KeyboardState`].
 pub struct KeyboardModule;
 
 impl WaybarModule for KeyboardModule {
@@ -44,19 +49,22 @@ impl WaybarModule for KeyboardModule {
     }
 }
 
+/// Background watcher that subscribes to `activelayout>>` events emitted by
+/// Hyprland's event socket.
 pub struct KeyboardDaemon;
 
 impl KeyboardDaemon {
+    /// Construct a new (stateless) daemon.
     pub fn new() -> Self {
         Self
     }
 
+    /// Spawn a supervised listen loop that reconnects with a 5 s backoff.
     pub fn start(&self, tx: watch::Sender<KeyboardState>) {
         tokio::spawn(async move {
             loop {
                 if let Err(e) = Self::listen_loop(&tx).await {
                     error!("Keyboard layout listener error: {}", e);
-                    // Fallback to waiting before reconnecting to prevent tight loop
                     tokio::time::sleep(tokio::time::Duration::from_secs(5)).await;
                 }
             }
@@ -71,7 +79,6 @@ impl KeyboardDaemon {
         let reader = BufReader::new(stream);
         let mut lines = reader.lines();
 
-        // Fetch initial layout natively via hyprctl
         if let Ok(output) = tokio::process::Command::new("hyprctl")
             .args(["devices", "-j"])
             .output()
@@ -80,7 +87,8 @@ impl KeyboardDaemon {
             && let Some(keyboards) = json.get("keyboards").and_then(|v| v.as_array())
             && let Some(main_kb) = keyboards.last()
         {
-            // The last active one is usually the main one
+            // `keyboards.last()` is the most recently registered device,
+            // which is typically the main one for single-keyboard setups.
             if let Some(layout) = main_kb.get("active_keymap").and_then(|v| v.as_str()) {
                 let _ = tx.send(KeyboardState {
                     layout: layout.to_string(),
@@ -89,8 +97,8 @@ impl KeyboardDaemon {
         }
 
         while let Ok(Some(line)) = lines.next_line().await {
+            // Event payload: `keyboard_name,layout_name`.
             if let Some(payload) = line.strip_prefix("activelayout>>") {
-                // payload format: keyboard_name,layout_name
                 let parts: Vec<&str> = payload.splitn(2, ',').collect();
                 if parts.len() == 2 {
                     let layout = parts[1].to_string();

src/modules/memory.rs

@@ -1,10 +1,13 @@
+//! RAM usage renderer. Reads from the `memory` watch channel.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
 use crate::output::WaybarOutput;
 use crate::state::AppReceivers;
-use crate::utils::{TokenValue, format_template};
+use crate::utils::{TokenValue, classify_usage, format_template};
 
+/// Renders used/total GB with usage classification for Waybar CSS.
 pub struct MemoryModule;
 
 impl WaybarModule for MemoryModule {
@@ -33,13 +36,7 @@ impl WaybarModule for MemoryModule {
             ],
         );
 
-        let class = if ratio > 95.0 {
+        let class = classify_usage(ratio, 75.0, 95.0);
-            "max"
-        } else if ratio > 75.0 {
-            "high"
-        } else {
-            "normal"
-        };
 
         Ok(WaybarOutput {
             text,

src/modules/mod.rs

@@ -1,18 +1,48 @@
+//! 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")]
 pub mod backlight;
+#[cfg(feature = "mod-bt")]
 pub mod bt;
+#[cfg(feature = "mod-hardware")]
 pub mod btrfs;
+#[cfg(feature = "mod-hardware")]
 pub mod cpu;
+#[cfg(feature = "mod-hardware")]
 pub mod disk;
+#[cfg(feature = "mod-dbus")]
 pub mod dnd;
+#[cfg(feature = "mod-hardware")]
 pub mod game;
+#[cfg(feature = "mod-hardware")]
 pub mod gpu;
+#[cfg(feature = "mod-hardware")]
 pub mod hardware;
+#[cfg(feature = "mod-dbus")]
 pub mod keyboard;
+#[cfg(feature = "mod-hardware")]
 pub mod memory;
+#[cfg(feature = "mod-dbus")]
 pub mod mpris;
+#[cfg(feature = "mod-network")]
 pub mod network;
+#[cfg(feature = "mod-hardware")]
 pub mod power;
+#[cfg(feature = "mod-hardware")]
 pub mod sys;
 
 use crate::config::Config;
@@ -20,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

@@ -1,13 +1,79 @@
+//! MPRIS media player indicator.
+//!
+//! Subscribes to `PlaybackStatus` and `Metadata` property-changed streams on
+//! the first `org.mpris.MediaPlayer2.*` name that appears on the session bus,
+//! so the indicator is truly signal-driven (no 2 s polling). A 10 s heartbeat
+//! verifies the player is still there. Optional marquee scrolling is driven
+//! by [`mpris_scroll_ticker`] from [`crate::daemon`].
+
 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};
 
+/// Render the user's format string + derive the Waybar CSS class from state.
+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)
+}
+
+/// Return a cyclic `max_len`-wide window over `full_text + separator`.
+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()
+}
+
+/// Truncate `text` to `max_len` chars, appending `...` when cut.
+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)
+}
+
+/// Renders the current player state, applying scroll/truncate per config.
 pub struct MprisModule;
 
 impl WaybarModule for MprisModule {
@@ -28,32 +94,26 @@ impl WaybarModule for MprisModule {
             });
         }
 
-        let status_icon = if mpris.is_playing {
+        let (full_text, class) = format_mpris_text(&config.mpris.format, &mpris);
-            "󰏤"
-        } else if mpris.is_paused {
-            "󰐊"
-        } else {
-            "󰓛"
-        };
 
-        let class = if mpris.is_playing {
+        let text = if config.mpris.scroll {
-            "playing"
+            if let Some(max_len) = config.mpris.max_length {
-        } else if mpris.is_paused {
+                let scroll = state.mpris_scroll.read().await;
-            "paused"
+                apply_scroll_window(
+                    &full_text,
+                    max_len,
+                    scroll.offset,
+                    &config.mpris.scroll_separator,
+                )
             } else {
-            "stopped"
+                full_text.clone()
+            }
+        } else if let Some(max_len) = config.mpris.max_length {
+            truncate_with_ellipsis(&full_text, max_len)
+        } else {
+            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 +123,59 @@ impl WaybarModule for MprisModule {
     }
 }
 
+/// Drive the marquee animation: advance the offset every `scroll_speed` ms
+/// while a track is playing, and emit a fresh generation on `tick_tx` so the
+/// mpris signaler arm fires. Resets offset when the track changes.
+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 — sleep until the next player state change.
+        if mpris_rx.changed().await.is_err() {
+            break;
+        }
+    }
+}
+
+/// Background watcher that discovers the active MPRIS player and mirrors
+/// its `PlaybackStatus` + `Metadata` properties into [`MprisState`].
 pub struct MprisDaemon;
 
 #[proxy(
@@ -89,10 +202,12 @@ trait MprisPlayer {
 }
 
 impl MprisDaemon {
+    /// Construct a new (stateless) daemon.
     pub fn new() -> Self {
         Self
     }
 
+    /// Spawn a supervised listen loop with a 5 s reconnect backoff.
     pub fn start(&self, tx: watch::Sender<MprisState>) {
         tokio::spawn(async move {
             loop {
@@ -105,40 +220,99 @@ 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");
 
-        // Simple poll loop for MPRIS since players can come and go, and tracking dynamically
-        // with pure signals across multiple dynamically spawned DBus names is complex.
-        // A robust hybrid approach: poll every 2s for active players, and update state.
-
         let dbus_proxy = DBusProxy::new(&connection).await?;
 
         loop {
             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 {
+            let Some(player_name) = active_player else {
-                if name.starts_with("org.mpris.MediaPlayer2.") {
+                send_stopped_if_changed(tx);
-                    active_player = Some(name);
+                tokio::time::sleep(Duration::from_secs(5)).await;
-                    break; // Just grab the first active player for now
+                continue;
-                }
+            };
-            }
 
-            if let Some(player_name) = active_player {
+            let player_proxy = match MprisPlayerProxy::builder(&connection)
-                if let Ok(player_proxy) = MprisPlayerProxy::builder(&connection)
                 .destination(player_name.clone())?
                 .build()
                 .await
             {
-                    let status = player_proxy.playback_status().await.unwrap_or_default();
+                Ok(p) => p,
-                    let metadata = player_proxy.metadata().await.unwrap_or_default();
+                Err(_) => {
+                    tokio::time::sleep(Duration::from_secs(2)).await;
+                    continue;
+                }
+            };
+
+            update_from_player(&player_proxy, tx).await;
+
+            let mut status_stream = player_proxy.receive_playback_status_changed().await;
+            let mut metadata_stream = player_proxy.receive_metadata_changed().await;
+
+            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: re-check that the player name is still owned.
+                        let current = dbus_proxy.list_names().await.unwrap_or_default();
+                        if !current.iter().any(|n| n == &player_name) {
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+/// Fetch `PlaybackStatus` + `Metadata` and publish only when they differ
+/// from the previous [`MprisState`] (to avoid spurious watch wake-ups).
+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,
+        });
+    }
+}
+
+/// Extract `xesam:artist` (string or array), `xesam:title`, `xesam: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();
@@ -167,27 +341,12 @@ impl MprisDaemon {
         album = a.to_string();
     }
 
-                    // Only send if changed
+    (artist, title, album)
-                    let current = tx.borrow();
+}
-                    if current.is_playing != is_playing
+
-                        || current.is_paused != is_paused
+/// Publish a cleared/stopped [`MprisState`] if the current state isn't already
-                        || current.is_stopped != is_stopped
+/// that. Called when no player is on the bus.
-                        || current.title != title
+fn send_stopped_if_changed(tx: &watch::Sender<MprisState>) {
-                        || 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);
@@ -200,9 +359,4 @@ impl MprisDaemon {
             album: String::new(),
         });
     }
-            }
-
-            tokio::time::sleep(tokio::time::Duration::from_secs(2)).await;
-        }
-    }
 }

src/modules/network.rs

@@ -1,3 +1,10 @@
+//! Primary-interface throughput renderer + polling daemon.
+//!
+//! The daemon picks the interface with the longest-prefix default route (see
+//! [`get_primary_interface`]) and computes rx/tx rates as byte-count deltas
+//! between successive polls. Well-known VPN interface prefixes get a lock
+//! glyph prepended to the rendered text.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
@@ -9,8 +16,10 @@ use std::fs;
 use std::time::{SystemTime, UNIX_EPOCH};
 use tokio::sync::watch;
 
+/// Renders interface / IP / rx / tx for the detected primary route.
 pub struct NetworkModule;
 
+/// Background poller that tracks byte counters across ticks to derive rates.
 pub struct NetworkDaemon {
     last_time: u64,
     last_rx_bytes: u64,
@@ -22,6 +31,7 @@ pub struct NetworkDaemon {
 type PollResult = crate::error::Result<(String, Option<String>, Option<(u64, u64)>)>;
 
 impl NetworkDaemon {
+    /// Build a fresh daemon with no prior byte-count samples.
     pub fn new() -> Self {
         Self {
             last_time: 0,
@@ -32,6 +42,9 @@ impl NetworkDaemon {
         }
     }
 
+    /// Detect the primary interface, read `/sys/class/net/*/statistics`, and
+    /// publish a new [`NetworkState`] onto `state_tx`. Interface/byte reads
+    /// run via [`tokio::task::spawn_blocking`] so the runtime isn't starved.
     pub async fn poll(
         &mut self,
         state_tx: &watch::Sender<NetworkState>,
@@ -56,7 +69,6 @@ impl NetworkDaemon {
         } else {
             self.cached_interface = None;
             self.cached_ip = None;
-            // Provide a default state for "No connection"
             let mut network = state_tx.borrow().clone();
             network.interface.clear();
             network.ip.clear();
@@ -71,7 +83,6 @@ impl NetworkDaemon {
         let interface = if let Some(ref interface) = self.cached_interface {
             interface.clone()
         } else {
-            // No interface detected
             let mut network = state_tx.borrow().clone();
             network.interface.clear();
             network.ip.clear();
@@ -107,7 +118,7 @@ impl NetworkDaemon {
                 network.ip = self.cached_ip.clone().unwrap_or_default();
                 let _ = state_tx.send(network);
             } else {
-                // First poll: no speed data yet, but update interface/ip
+                // First poll has no prior sample — publish iface/ip only.
                 let mut network = state_tx.borrow().clone();
                 network.interface = interface.clone();
                 network.ip = self.cached_ip.clone().unwrap_or_default();
@@ -118,7 +129,6 @@ impl NetworkDaemon {
             self.last_rx_bytes = rx_bytes_now;
             self.last_tx_bytes = tx_bytes_now;
         } else {
-            // Read failed, might be down
             self.cached_interface = None;
             return Err(crate::error::FluxoError::Network(format!(
                 "Failed to read bytes for {}",
@@ -182,6 +192,8 @@ impl WaybarModule for NetworkModule {
     }
 }
 
+/// Parse `/proc/net/route` to find the default-route interface. When several
+/// defaults exist, prefer the one with the longest netmask, then lowest metric.
 fn get_primary_interface() -> Result<String> {
     let content = std::fs::read_to_string("/proc/net/route")?;
 
@@ -200,7 +212,6 @@ fn get_primary_interface() -> Result<String> {
         }
     }
 
-    // Sort by mask descending (longest prefix match first), then by metric ascending
     defaults.sort_by(|a, b| b.0.cmp(&a.0).then(a.1.cmp(&b.1)));
     if let Some((_, _, dev)) = defaults.first() {
         Ok(dev.clone())
@@ -209,6 +220,7 @@ fn get_primary_interface() -> Result<String> {
     }
 }
 
+/// First IPv4 address for `interface`, via `getifaddrs`. `None` if absent.
 fn get_ip_address(interface: &str) -> Option<String> {
     let addrs = getifaddrs().ok()?;
     for ifaddr in addrs {
@@ -222,6 +234,7 @@ fn get_ip_address(interface: &str) -> Option<String> {
     None
 }
 
+/// Read `(rx_bytes, tx_bytes)` counters from sysfs for `interface`.
 fn get_bytes(interface: &str) -> Result<(u64, u64)> {
     let rx_path = format!("/sys/class/net/{}/statistics/rx_bytes", interface);
     let tx_path = format!("/sys/class/net/{}/statistics/tx_bytes", interface);

src/modules/power.rs

@@ -1,3 +1,6 @@
+//! Battery/AC indicator via `/sys/class/power_supply`. Dispatch-only - reads
+//! sysfs on demand rather than polling into a watch channel.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
@@ -6,6 +9,7 @@ use crate::state::AppReceivers;
 use crate::utils::{TokenValue, format_template};
 use std::fs;
 
+/// Renders battery percentage + charge state (critical/warning/bat/charging/ac).
 pub struct PowerModule;
 
 impl WaybarModule for PowerModule {
@@ -18,7 +22,6 @@ impl WaybarModule for PowerModule {
         let critical_threshold = 15;
         let warning_threshold = 50;
 
-        // Find the first battery
         let mut battery_path = None;
         if let Ok(entries) = fs::read_dir("/sys/class/power_supply") {
             for entry in entries.flatten() {
@@ -30,7 +33,6 @@ impl WaybarModule for PowerModule {
             }
         }
 
-        // Check AC status
         let mut ac_online = false;
         if let Ok(entries) = fs::read_dir("/sys/class/power_supply") {
             for entry in entries.flatten() {

src/modules/sys.rs

@@ -1,3 +1,5 @@
+//! Uptime + load average renderer. Reads from the `sys` watch channel.
+
 use crate::config::Config;
 use crate::error::Result;
 use crate::modules::WaybarModule;
@@ -5,6 +7,7 @@ use crate::output::WaybarOutput;
 use crate::state::AppReceivers;
 use crate::utils::{TokenValue, format_template};
 
+/// Renders uptime and load averages with a detailed tooltip.
 pub struct SysModule;
 
 impl WaybarModule for SysModule {

src/output.rs

@@ -1,16 +1,101 @@
+//! JSON payload returned to Waybar custom modules, plus client-side
+//! output formatting utilities.
+
 use serde::{Deserialize, Serialize};
 
+/// Waybar renders in a proportional font — replacing normal spaces with
+/// figure-spaces (U+2007) keeps column widths stable across updates.
+pub const FIGURE_SPACE: char = '\u{2007}';
+
+/// Zero-width space used as cosmetic padding around module text so Waybar
+/// doesn't clip leading/trailing glyphs.
+pub const ZERO_WIDTH_SPACE: char = '\u{200B}';
+
+/// 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>,
 }
 
+impl WaybarOutput {
+    /// A blank output for disabled modules.
+    pub fn disabled() -> Self {
+        Self {
+            text: String::new(),
+            tooltip: Some("Module disabled".to_string()),
+            class: Some("disabled".to_string()),
+            percentage: None,
+        }
+    }
+
+    /// A user-visible error with tooltip detail.
+    pub fn error(message: &str) -> Self {
+        Self {
+            text: format!("{}Error{}", ZERO_WIDTH_SPACE, ZERO_WIDTH_SPACE),
+            tooltip: Some(message.to_string()),
+            class: Some("error".to_string()),
+            percentage: None,
+        }
+    }
+}
+
+/// Apply Waybar font-stabilisation to a text string.
+///
+/// Replaces normal spaces with figure-spaces (unless the string contains
+/// markup), and wraps in zero-width spaces for cosmetic padding.
+pub fn stabilize_text(text: &str) -> String {
+    let processed = if text.contains('<') {
+        text.to_string()
+    } else {
+        text.replace(' ', &FIGURE_SPACE.to_string())
+    };
+    format!("{}{}{}", ZERO_WIDTH_SPACE, processed, ZERO_WIDTH_SPACE)
+}
+
+/// Process an IPC response and print Waybar-compatible JSON to stdout.
+///
+/// On IPC failure, prints a "Daemon offline" error output and exits
+/// non-zero so Waybar surfaces the problem visually.
+pub fn print_waybar_response(response: anyhow::Result<String>) {
+    match response {
+        Ok(json_str) => match serde_json::from_str::<serde_json::Value>(&json_str) {
+            Ok(mut val) => {
+                if let Some(text) = val.get("text").and_then(|t| t.as_str()) {
+                    val["text"] = serde_json::Value::String(stabilize_text(text));
+                }
+                println!("{}", serde_json::to_string(&val).unwrap());
+            }
+            Err(_) => println!("{}", json_str),
+        },
+        Err(e) => {
+            let err_out = WaybarOutput {
+                text: format!(
+                    "{}Daemon offline ({}){}",
+                    ZERO_WIDTH_SPACE, e, ZERO_WIDTH_SPACE
+                ),
+                tooltip: Some(e.to_string()),
+                class: Some("error".to_string()),
+                percentage: None,
+            };
+            println!("{}", serde_json::to_string(&err_out).unwrap());
+            std::process::exit(1);
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/registry.rs

@@ -0,0 +1,85 @@
+//! 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;
+use crate::state::AppReceivers;
+
+#[allow(unused_imports)]
+use crate::modules::WaybarModule;
+
+/// 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 = $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))),
+            }
+        }
+
+        /// 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"],
+                _ => &[],
+            }
+        }
+    };
+}
+
+for_each_watched_module!(gen_dispatch);

src/signaler.rs

@@ -1,8 +1,13 @@
+//! 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 nix::libc;
-use nix::sys::signal::{Signal, kill};
-use nix::unistd::Pid;
 use std::collections::HashMap;
 use std::sync::Arc;
 use sysinfo::{ProcessesToUpdate, System};
@@ -10,13 +15,18 @@ 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<Pid>,
+    cached_pid: Option<i32>,
     sys: System,
     last_signal_sent: HashMap<i32, Instant>,
 }
 
 impl WaybarSignaler {
+    /// Create a new signaler with no cached PID.
     pub fn new() -> Self {
         Self {
             cached_pid: None,
@@ -25,11 +35,11 @@ impl WaybarSignaler {
         }
     }
 
-    fn find_waybar_pid(&mut self) -> Option<Pid> {
+    fn find_waybar_pid(&mut self) -> Option<i32> {
         self.sys.refresh_processes(ProcessesToUpdate::All, true);
         for (pid, process) in self.sys.processes() {
             if process.name() == "waybar" {
-                return Some(Pid::from_raw(pid.as_u32() as i32));
+                return Some(pid.as_u32() as i32);
             }
         }
         None
@@ -44,7 +54,7 @@ impl WaybarSignaler {
 
         let mut valid_pid = false;
         if let Some(pid) = self.cached_pid
-            && kill(pid, None).is_ok()
+            && unsafe { libc::kill(pid, 0) } == 0
         {
             valid_pid = true;
         }
@@ -54,33 +64,33 @@ impl WaybarSignaler {
         }
 
         if let Some(pid) = self.cached_pid {
-            let rt_sig = match Signal::try_from(libc::SIGRTMIN() + signal_num) {
+            let sig = libc::SIGRTMIN() + signal_num;
-                Ok(sig) => sig,
+            if unsafe { libc::kill(pid, sig) } == 0 {
-                Err(_) => {
-                    unsafe {
-                        if libc::kill(pid.as_raw(), libc::SIGRTMIN() + signal_num) == 0 {
-                            debug!("Sent raw SIGRTMIN+{} to waybar (PID: {})", signal_num, pid);
-                            self.last_signal_sent.insert(signal_num, Instant::now());
-                        } else {
-                            warn!("Failed to send raw SIGRTMIN+{} to waybar", signal_num);
-                        }
-                    }
-                    return;
-                }
-            };
-
-            if let Err(e) = kill(pid, rt_sig) {
-                warn!("Failed to signal waybar: {}", e);
-                self.cached_pid = None;
-            } else {
                 debug!("Sent SIGRTMIN+{} to waybar (PID: {})", signal_num, pid);
                 self.last_signal_sent.insert(signal_num, Instant::now());
+            } else {
+                warn!("Failed to send SIGRTMIN+{} to waybar", signal_num);
+                self.cached_pid = None;
             }
         } else {
             debug!("Waybar process not found, skipping signal.");
         }
     }
+}
 
+/// 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();
 
@@ -107,50 +117,47 @@ impl WaybarSignaler {
                         };
                     }
 
+                    // 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 = receivers.network.changed(), if signals.network.is_some() => {
+                        $(
-                    if res.is_ok() { check_and_signal!("net", signals.network); }
+                            res = $field, if signals.$signal.is_some() => {
-                }
-                res = receivers.cpu.changed(), if signals.cpu.is_some() => {
-                    if res.is_ok() { check_and_signal!("cpu", signals.cpu); }
-                }
-                res = receivers.memory.changed(), if signals.memory.is_some() => {
-                    if res.is_ok() { check_and_signal!("mem", signals.memory); }
-                }
-                res = receivers.sys.changed(), if signals.sys.is_some() => {
-                    if res.is_ok() { check_and_signal!("sys", signals.sys); }
-                }
-                res = receivers.gpu.changed(), if signals.gpu.is_some() => {
-                    if res.is_ok() { check_and_signal!("gpu", signals.gpu); }
-                }
-                res = receivers.disks.changed(), if signals.disk.is_some() => {
-                    if res.is_ok() { check_and_signal!("disk", signals.disk); }
-                }
-                res = receivers.bluetooth.changed(), if signals.bt.is_some() => {
-                    if res.is_ok() { check_and_signal!("bt", signals.bt); }
-                }
-                res = receivers.audio.changed(), if signals.audio.is_some() => {
                                 if res.is_ok() {
-                        check_and_signal!("vol", signals.audio);
+                                    $(check_and_signal!($sig_name, signals.$signal);)+
-                        check_and_signal!("mic", signals.audio);
                                 }
                             }
-                res = receivers.backlight.changed(), if signals.backlight.is_some() => {
+                        )*
-                    if res.is_ok() { check_and_signal!("backlight", signals.backlight); }
+
-                }
+                        // MPRIS scroll tick (separate from mpris data changes)
-                res = receivers.keyboard.changed(), if signals.keyboard.is_some() => {
+                        res = mpris_scroll_tick, if signals.mpris.is_some() => {
-                    if res.is_ok() { check_and_signal!("keyboard", signals.keyboard); }
+                            if res.is_ok()
-                }
+                                && let Some(sig) = signals.mpris { self.send_signal(sig); }
-                res = receivers.dnd.changed(), if signals.dnd.is_some() => {
-                    if res.is_ok() { check_and_signal!("dnd", signals.dnd); }
-                }
-                res = receivers.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
+                            // heartbeat: re-read signals config on each iteration
                         }
                     }
                 }
             }
+        }
+    };
 }
+
+for_each_watched_module!(gen_signaler_run);

src/state.rs

@@ -1,28 +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)]
+/// Generates the [`AppReceivers`] struct, with one `watch::Receiver` field
-pub struct AppReceivers {
+/// per watched module (cfg-gated by feature flag).
-    pub network: watch::Receiver<NetworkState>,
+macro_rules! gen_app_receivers {
-    pub cpu: watch::Receiver<CpuState>,
+    ($( { $feature:literal, $field:ident, $state:ty, [$($name:literal),+], [$($sig_name:literal),+], $module:path, $signal:ident, [$($default_arg:literal),*], $config:ident } )*) => {
-    pub memory: watch::Receiver<MemoryState>,
+        /// Bundle of every watch-channel receiver and control-channel handle.
-    pub sys: watch::Receiver<SysState>,
+        ///
-    pub gpu: watch::Receiver<GpuState>,
+        /// Cloned into each IPC request handler and each module daemon so that
-    pub disks: watch::Receiver<Vec<DiskInfo>>,
+        /// they can snapshot state without locking. Per-module receivers are
-    pub bluetooth: watch::Receiver<BtState>,
+        /// generated from [`for_each_watched_module!`]; the remaining fields
-    pub audio: watch::Receiver<AudioState>,
+        /// (`health`, `bt_cycle`, `audio_cmd_tx`, `mpris_scroll_*`) are shared
-    pub mpris: watch::Receiver<MprisState>,
+        /// control state.
-    pub backlight: watch::Receiver<BacklightState>,
+        #[derive(Clone)]
-    pub keyboard: watch::Receiver<KeyboardState>,
+        pub struct AppReceivers {
-    pub dnd: watch::Receiver<DndState>,
+            $(
+                #[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,
@@ -31,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,
@@ -48,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 struct BtDeviceInfo {
-    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 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,
@@ -75,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,
@@ -83,6 +120,7 @@ pub struct NetworkState {
     pub ip: String,
 }
 
+/// CPU utilisation and temperature.
 #[derive(Clone)]
 pub struct CpuState {
     pub usage: f64,
@@ -100,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,
@@ -115,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,
@@ -140,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,
@@ -165,88 +219,166 @@ 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,
-    // Keep senders alive so receivers don't return Closed errors
+    #[cfg(feature = "mod-network")]
     _net_tx: watch::Sender<NetworkState>,
+    #[cfg(feature = "mod-hardware")]
     _cpu_tx: watch::Sender<CpuState>,
+    #[cfg(feature = "mod-hardware")]
     _mem_tx: watch::Sender<MemoryState>,
+    #[cfg(feature = "mod-hardware")]
     _sys_tx: watch::Sender<SysState>,
+    #[cfg(feature = "mod-hardware")]
     _gpu_tx: watch::Sender<GpuState>,
+    #[cfg(feature = "mod-hardware")]
     _disks_tx: watch::Sender<Vec<DiskInfo>>,
+    #[cfg(feature = "mod-bt")]
     _bt_tx: watch::Sender<BtState>,
+    #[cfg(feature = "mod-audio")]
     _audio_tx: watch::Sender<AudioState>,
+    #[cfg(feature = "mod-dbus")]
     _mpris_tx: watch::Sender<MprisState>,
+    #[cfg(feature = "mod-dbus")]
     _backlight_tx: watch::Sender<BacklightState>,
+    #[cfg(feature = "mod-dbus")]
     _keyboard_tx: watch::Sender<KeyboardState>,
+    #[cfg(feature = "mod-dbus")]
     _dnd_tx: watch::Sender<DndState>,
 }
 
+/// Plain-data counterpart of [`AppReceivers`] used to seed a [`MockState`].
 #[cfg(test)]
 #[derive(Default, Clone)]
 pub struct AppState {
+    #[cfg(feature = "mod-network")]
     pub network: NetworkState,
+    #[cfg(feature = "mod-hardware")]
     pub cpu: CpuState,
+    #[cfg(feature = "mod-hardware")]
     pub memory: MemoryState,
+    #[cfg(feature = "mod-hardware")]
     pub sys: SysState,
+    #[cfg(feature = "mod-hardware")]
     pub gpu: GpuState,
+    #[cfg(feature = "mod-hardware")]
     pub disks: Vec<DiskInfo>,
+    #[cfg(feature = "mod-bt")]
     pub bluetooth: BtState,
+    #[cfg(feature = "mod-audio")]
     pub audio: AudioState,
+    #[cfg(feature = "mod-dbus")]
     pub mpris: MprisState,
+    #[cfg(feature = "mod-dbus")]
     pub backlight: BacklightState,
+    #[cfg(feature = "mod-dbus")]
     pub keyboard: KeyboardState,
+    #[cfg(feature = "mod-dbus")]
     pub dnd: DndState,
     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")]
     let (net_tx, net_rx) = watch::channel(state.network);
+    #[cfg(feature = "mod-hardware")]
     let (cpu_tx, cpu_rx) = watch::channel(state.cpu);
+    #[cfg(feature = "mod-hardware")]
     let (mem_tx, mem_rx) = watch::channel(state.memory);
+    #[cfg(feature = "mod-hardware")]
     let (sys_tx, sys_rx) = watch::channel(state.sys);
+    #[cfg(feature = "mod-hardware")]
     let (gpu_tx, gpu_rx) = watch::channel(state.gpu);
+    #[cfg(feature = "mod-hardware")]
     let (disks_tx, disks_rx) = watch::channel(state.disks);
+    #[cfg(feature = "mod-bt")]
     let (bt_tx, bt_rx) = watch::channel(state.bluetooth);
+    #[cfg(feature = "mod-audio")]
     let (audio_tx, audio_rx) = watch::channel(state.audio);
+    #[cfg(feature = "mod-dbus")]
     let (mpris_tx, mpris_rx) = watch::channel(state.mpris);
+    #[cfg(feature = "mod-dbus")]
     let (backlight_tx, backlight_rx) = watch::channel(state.backlight);
+    #[cfg(feature = "mod-dbus")]
     let (keyboard_tx, keyboard_rx) = watch::channel(state.keyboard);
+    #[cfg(feature = "mod-dbus")]
     let (dnd_tx, dnd_rx) = watch::channel(state.dnd);
+    #[cfg(feature = "mod-bt")]
     let (bt_force_tx, _) = mpsc::channel(1);
+    #[cfg(feature = "mod-audio")]
     let (audio_cmd_tx, _) = mpsc::channel(1);
 
     MockState {
         receivers: AppReceivers {
+            #[cfg(feature = "mod-network")]
             network: net_rx,
+            #[cfg(feature = "mod-hardware")]
             cpu: cpu_rx,
+            #[cfg(feature = "mod-hardware")]
             memory: mem_rx,
+            #[cfg(feature = "mod-hardware")]
             sys: sys_rx,
+            #[cfg(feature = "mod-hardware")]
             gpu: gpu_rx,
+            #[cfg(feature = "mod-hardware")]
             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")]
             mpris: mpris_rx,
+            #[cfg(feature = "mod-dbus")]
             backlight: backlight_rx,
+            #[cfg(feature = "mod-dbus")]
             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,
+            #[cfg(feature = "mod-audio")]
             audio_cmd_tx,
         },
+        #[cfg(feature = "mod-network")]
         _net_tx: net_tx,
+        #[cfg(feature = "mod-hardware")]
         _cpu_tx: cpu_tx,
+        #[cfg(feature = "mod-hardware")]
         _mem_tx: mem_tx,
+        #[cfg(feature = "mod-hardware")]
         _sys_tx: sys_tx,
+        #[cfg(feature = "mod-hardware")]
         _gpu_tx: gpu_tx,
+        #[cfg(feature = "mod-hardware")]
         _disks_tx: disks_tx,
+        #[cfg(feature = "mod-bt")]
         _bt_tx: bt_tx,
+        #[cfg(feature = "mod-audio")]
         _audio_tx: audio_tx,
+        #[cfg(feature = "mod-dbus")]
         _mpris_tx: mpris_tx,
+        #[cfg(feature = "mod-dbus")]
         _backlight_tx: backlight_tx,
+        #[cfg(feature = "mod-dbus")]
         _keyboard_tx: keyboard_tx,
+        #[cfg(feature = "mod-dbus")]
         _dnd_tx: dnd_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,21 +80,39 @@ 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"
+    } else if value > high {
+        "high"
+    } else {
+        "normal"
+    }
+}
+
+/// 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>,
 {
-    static RE: LazyLock<Regex> = LazyLock::new(|| {
+    TOKEN_RE
-        Regex::new(r"\{([a-zA-Z0-9_]+)(?::([<>\^])?(\d+)?(?:\.(\d+))?)?\}").unwrap()
+        .replace_all(template, |caps: &regex::Captures| {
-    });
-
-    RE.replace_all(template, |caps: &regex::Captures| {
             let name = &caps[1];
             if let Some((_, val)) = values.iter().find(|(k, _)| k.as_ref() == name) {
                 let align = caps.get(2).map(|m| m.as_str()).unwrap_or(">");