lightbar/TOOD.md

# Lightbar implementation checklist

This file tracks the implementation of the agreed native, low-CPU Sway panel.
The first target is Ubuntu 26.04 with Sway 1.11. The core bar ships before the
StatusNotifier tray.

## 1. Project and configuration

- [ ] Rename the project and source folder to Lightbar, migrate the installed
      configuration, and verify the running build and tests.
- [ ] Initialize Git and push the reviewed source to the Lightbar repository;
      verify that the remote branch matches the local commit.
- [x] Rename the package, executable, configuration, documentation, and source
      folder to Lightbar; migrate the installation and verify the running build.
- [x] Create a locked Rust application named `lightbar`.
- [x] Add CLI support for Sway's `-b <bar-id>`, `--config`, `check-config`,
      `doctor`, and `--version`.
- [x] Define strict, documented TOML models for the bar, layout, modules,
      actions, custom commands, and theme.
- [x] Load `$XDG_CONFIG_HOME/lightbar/config.toml` and its relative theme file.
- [x] Validate module references, colors, dimensions, durations, formats, and
      command limits before starting the UI.
- [x] Watch configuration and theme files; reload atomically and keep the last
      valid state after an invalid edit.
- [x] Filter and coalesce configuration filesystem events so reads and unrelated
      files cannot trigger reload loops.
- [ ] Add rate-limited structured logging and useful exit codes.
- [x] Add `doctor` checks for configuration, fonts, Sway/Wayland environment,
      D-Bus services, hardware, and optional helper applications.

## 2. Native Wayland shell and rendering

- [x] Connect through `WAYLAND_SOCKET` when Sway launches the bar and through
      the normal Wayland environment during development.
- [x] Create a top layer-shell surface with a 24 logical-pixel exclusive zone
      for every active output.
- [ ] Handle output creation/removal, integer and fractional scaling, surface
      configure events, and graceful compositor shutdown.
- [x] Implement reusable shared-memory buffers and compositor-frame-throttled
      drawing without a free-running render loop.
- [x] Render backgrounds, borders, state colors, and shaped system-font text.
- [x] Implement left/center/right layout, width measurement, clipping, and
      stable pointer hit boxes.
- [x] Handle hover, left/middle/right click, scrolling, and keyboard focus only
      while a popup needs it.
- [x] Implement one clamped `xdg_popup` per seat with dismissal, buttons,
      sliders, scrolling, and calendar/menu layouts.

## 3. Core data model and modules

- [x] Define a common module state/event/action interface with dirty-state
      comparison so unchanged data cannot trigger redraws.
- [ ] Use bounded latest-value channels and coalesce bursts into one frame.
- [x] Implement Sway IPC framing, initialization, persistent request and event
      connections, commands, output-local workspaces, binding mode, and
      scratchpad discovery.
- [x] Preserve the last workspace list and focused selection across recoverable
      Sway IPC disconnects instead of replacing it with an empty snapshot.
- [x] Implement a navigable scratchpad window popover and reveal/move actions.
- [x] Implement an exact-boundary clock and navigable calendar popover.
- [ ] Implement NetworkManager status and detail through D-Bus, with an
      `nm-connection-editor` launcher for advanced management.
- [ ] Implement UPower battery status and detail through D-Bus.
- [x] Implement PulseAudio/PipeWire-Pulse volume events, mute/volume controls,
      and a `pavucontrol` launcher.
- [x] Extend audio with current default output and microphone names, independent
      volume/mute controls, and default-device selection in the popup.
- [x] Verify audio event synchronization, missing/disconnected devices, control
      routing, and popup keyboard interaction with regression tests.
      Verified with 37 automated tests, a read-only comparison with live
      PipeWire/WirePlumber, and an isolated Sway session using simulated devices.
- [x] Install the updated audio build, validate the installed configuration,
      and verify that the running bar uses the installed binary.
- [x] Implement sysfs/logind backlight discovery and adjustment.
- [x] Implement configurable `hwmon` temperature discovery and sparse polling.
- [x] Auto-detect current hardware names while retaining explicit overrides.
- [x] Hide or mark an unavailable optional module without crashing the bar.

## 4. Custom command modules

- [x] Support interval commands and long-running newline streams.
- [x] Accept plain text or JSON objects containing `text`, `tooltip`, `state`,
      and `visible`.
- [x] Enforce argument-array execution by default, explicit shell opt-in,
      two-second default timeouts, 64 KiB limits, and child cleanup.
- [x] Preserve the last good value as stale after transient failures and use
      bounded exponential restart backoff.
- [x] Interrupt and reap monitored children during reload without holding child
      locks across blocking waits.
- [x] Support typed built-in, Sway, executable, and explicit-shell actions for
      clicks and scroll directions.

## 5. StatusNotifier tray (second milestone)

- [x] Reuse an existing `org.kde.StatusNotifierWatcher`, or own and implement
      it when no watcher exists.
- [x] Register a StatusNotifierHost and track item registration, property
      changes, and duplicate notifications.
- [x] Remove owned-watcher registrations immediately when their D-Bus name
      disappears, and never render ownerless or unreadable items as fallback
      circles.
- [x] Validate and render item-provided ARGB pixmaps.
- [ ] Resolve icon-name-only items from installed XDG icon themes; do not bundle
      a vector icon set.
- [x] Implement activation, secondary activation, context menus, and scrolling.
- [ ] Implement DBusMenu layout, updates, nested menus, separators, toggles,
      enabled/visible state, and activation in native popups.
- [ ] Reject malformed/oversized pixmaps, cap menu depth and item count,
      isolate broken items, and rate-limit event floods.

## 6. Tests, profiling, and rollout

- [x] Unit-test config validation, duration/color parsing, format expansion,
      hit testing, Sway frames/filtering, custom output, sysfs selection, and
      hostile tray pixmaps.
- [ ] Add focused tests for state transitions, retries, popup placement, output
      scoping, and rendering cache eviction.
- [ ] Test modules through fake Sway streams, D-Bus services, audio events,
      sysfs trees, and hostile custom processes.
- [ ] Add rendering snapshots for multiple scales, Unicode, missing glyphs,
      urgent states, and narrow outputs.
- [ ] Run end-to-end tests in a nested headless Sway session.
- [ ] Add adversarial tray tests for malformed pixmaps/menus, duplicate items,
      disappearing services, and signal floods.
- [ ] Compare Waybar with/without tray against Lightbar core/with tray in repeated
      idle and interaction runs.
- [ ] Complete an eight-hour soak with flat memory and no sustained CPU spin
      after disconnects, reloads, event storms, or malformed input.
- [x] Provide a current-layout example using UbuntuMono Nerd Font, while
      warning and falling back to Noto Sans when it is absent.
- [x] Document development dependencies, release build, user installation,
      Sway configuration, validation, profiling, and one-line Waybar rollback.
- [x] Generate a per-user Sway include fragment so shared configurations do not
      hardcode usernames or depend on the graphical session's `PATH`.
- [ ] Install as `~/.local/bin/lightbar`, preserve the existing Waybar files, and
      switch only `swaybar_command` after all release checks pass.