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

• Move the source checkout to the requested parent folder and verify Git metadata and project discovery from the new location.
• 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.
• Create a locked Rust application named lightbar.
• Add CLI support for Sway's -b <bar-id>, --config, check-config, doctor, and --version.
• Define strict, documented TOML models for the bar, layout, modules, actions, custom commands, and theme.
• Load $XDG_CONFIG_HOME/lightbar/config.toml and its relative theme file.
• Validate module references, colors, dimensions, durations, formats, and command limits before starting the UI.
• Watch configuration and theme files; reload atomically and keep the last valid state after an invalid edit.
• Filter and coalesce configuration filesystem events so reads and unrelated files cannot trigger reload loops.
• Add rate-limited structured logging and useful exit codes.
• Add doctor checks for configuration, fonts, Sway/Wayland environment, D-Bus services, hardware, and optional helper applications.

2. Native Wayland shell and rendering

• Connect through WAYLAND_SOCKET when Sway launches the bar and through the normal Wayland environment during development.
• 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.
• Implement reusable shared-memory buffers and compositor-frame-throttled drawing without a free-running render loop.
• Render backgrounds, borders, state colors, and shaped system-font text.
• Implement left/center/right layout, width measurement, clipping, and stable pointer hit boxes.
• Handle hover, left/middle/right click, scrolling, and keyboard focus only while a popup needs it.
• Implement one clamped xdg_popup per seat with dismissal, buttons, sliders, scrolling, and calendar/menu layouts.

3. Core data model and modules

• 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.
• Implement Sway IPC framing, initialization, persistent request and event connections, commands, output-local workspaces, binding mode, and scratchpad discovery.
• Preserve the last workspace list and focused selection across recoverable Sway IPC disconnects instead of replacing it with an empty snapshot.
• Implement a navigable scratchpad window popover and reveal/move actions.
• 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.
• Add a keyboard-accessible network popup for LAN, Wi-Fi scans and connections, WWAN profiles, and actual IPv4/IPv6 default connections.
• Set internet preference through saved NetworkManager route metrics, preserve VPN routing, and report authorization or activation failures.
• Verify network controls with isolated services and popup tests, document supported connection types, and validate the installed build. Verified with 54 automated tests, a read-only comparison with live NetworkManager, and native popup controls in an isolated Sway session.
• Implement UPower battery status and detail through D-Bus.
• Implement PulseAudio/PipeWire-Pulse volume events, mute/volume controls, and a pavucontrol launcher.
• Extend audio with current default output and microphone names, independent volume/mute controls, and default-device selection in the popup.
• 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.
• Install the updated audio build, validate the installed configuration, and verify that the running bar uses the installed binary.
• Implement sysfs/logind backlight discovery and adjustment.
• Implement configurable hwmon temperature discovery and sparse polling.
• Auto-detect current hardware names while retaining explicit overrides.
• Hide or mark an unavailable optional module without crashing the bar.

4. Custom command modules

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

5. StatusNotifier tray (second milestone)

• Reuse an existing org.kde.StatusNotifierWatcher, or own and implement it when no watcher exists.
• Register a StatusNotifierHost and track item registration, property changes, and duplicate notifications.
• Remove owned-watcher registrations immediately when their D-Bus name disappears, and never render ownerless or unreadable items as fallback circles.
• Validate and render item-provided ARGB pixmaps.
• Resolve icon-name-only items from installed XDG icon themes; do not bundle a vector icon set.
• 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

• 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.
• Provide a current-layout example using UbuntuMono Nerd Font, while warning and falling back to Noto Sans when it is absent.
• Document development dependencies, release build, user installation, Sway configuration, validation, profiling, and one-line Waybar rollback.
• 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.