repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): add parity validation checklist

45e2ed4358bfb0d529ab149bf64c053c4ba4b063

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/inventory/2026-06-17-quickshell-parity-checklist.md

Added
new file mode 100644
1 +# Quickshell Hypr Companion Parity Checklist — 2026-06-17
3 +Purpose: executable acceptance checklist for proving Quickshell parity before retiring Ironbar, Mako, Hyprlauncher/Hyprshutdown usage, or Hypr `hyprctl notify` helpers.
5 +Baseline: [`2026-06-17-quickshell-hypr-companion-baseline.md`](2026-06-17-quickshell-hypr-companion-baseline.md)
6 +Architecture: [`../specs/2026-06-17-quickshell-hypr-companions-architecture.md`](../specs/2026-06-17-quickshell-hypr-companions-architecture.md)
8 +## Rules
10 +- Do not mark a row PASS from code inspection alone.
11 +- Do not retire old apps unless all rows in the relevant section PASS with old app stopped where applicable.
12 +- Screenshots need both dark and light mode unless the row is nonvisual.
13 +- If a row cannot be automated, record the manual observation and why automation is not available.
14 +- Destructive poweroff/reboot tests must use confirmation UI or dry-run only unless the user explicitly approves real execution.
16 +## Baseline snapshot commands
18 +Run before testing a replacement:
20 +```sh
21 +git status --short
22 +qs --version
23 +hyprctl version
24 +hyprctl monitors -j
25 +hyprctl configerrors
26 +systemctl --user --no-pager --plain status ironbar.service ironbar-workspaces.service mako.service cliphist.service wl-clip-persist.service
27 +ps -eo pid,pcpu,rss,comm,args | grep -E 'ironbar|mako|workspaces-watch|hyprlauncher|hyprshutdown|qs|quickshell' | grep -v grep || true
28 +```
30 +Expected baseline before migration:
32 +- Existing unrelated dirty work may exist and must be preserved.
33 +- `hyprctl configerrors` empty.
34 +- Ironbar/Mako services active until their specific retirement tests.
35 +- Quickshell may be active only after Phase 1.
37 +## Phase 1 foundation acceptance
39 +| Check | Command/action | PASS condition |
40 +| --- | --- | --- |
41 +| Direct parse/start | `timeout 3s qs -p quickshell/nugu/shell.qml` | Exit `124`; stderr has no QML parse/type errors. |
42 +| Service syntax | `systemd-analyze --user verify hypr/systemd/quickshell.service` | Exit `0`, no output. |
43 +| Named config IPC | `qs -c nugu ipc call nugu showDiagnostics` | Diagnostics panel appears without replacing Ironbar/Mako. |
44 +| Theme light | `qs -c nugu ipc call nugu setThemeMode light` | Diagnostics colors switch to light Nugu palette. |
45 +| Theme dark | `qs -c nugu ipc call nugu setThemeMode dark` | Diagnostics colors switch to dark Nugu palette. |
46 +| Hide diagnostics | `qs -c nugu ipc call nugu hideDiagnostics` | Diagnostics panel disappears. |
47 +| Old services untouched | `systemctl --user is-active ironbar.service mako.service` | Both still active unless user explicitly approved otherwise. |
49 +## Bar parity acceptance
51 +Run with Ironbar still available for rollback. Capture old/new screenshots with the same workspace and apps if possible.
53 +### Visual shell
55 +| Check | Command/action | PASS condition |
56 +| --- | --- | --- |
57 +| Top bar placement | Start Quickshell bar on `LVDS-1`. | Bar anchored top, full width, reserves space. |
58 +| Height | Screenshot or geometry inspection. | Visual height matches Ironbar `30px`. |
59 +| Padding | Screenshot compare. | Left/right content aligns like Ironbar `20px` padded bar. |
60 +| Border | Screenshot compare. | Bottom border is `2px` Nugu `ui.accent`. |
61 +| Font | Visual inspect. | Bar/status text uses `IBM Plex Mono`. |
62 +| Dark mode | Set Nugu dark, screenshot. | Colors match semantic Ironbar dark variables. |
63 +| Light mode | Set Nugu light, screenshot. | Colors remain readable and match semantic Nugu variables. |
64 +| Hover/active colors | Hover/click buttons. | Hover uses `ui.accent` over `content.backdrop`; active uses documented active color. |
66 +### Workspace widget
68 +| Check | Command/action | PASS condition |
69 +| --- | --- | --- |
70 +| Labels | Inspect bar. | Shows `1 󰖟`, `2 󰅨`, `3 󰆍`, `4 󰭹`, `5 󰎆`, `9 󰉋`. |
71 +| Active highlight | `hyprctl dispatch workspace 1`, repeat for `2..5`. | Active workspace changes immediately and uses `ui.important_global` equivalent. |
72 +| Occupied state | Open a window on a workspace, switch away. | Occupied but inactive workspace uses normal fg. |
73 +| Empty state | Use an empty workspace. | Empty workspace uses muted color. |
74 +| Click focus | Click each workspace button. | Hypr focuses clicked workspace. |
75 +| No watcher | `ps -eo args | grep workspaces-watch.py` after retirement test. | No Python watcher when Ironbar retired. |
77 +### Clipboard entry point
79 +| Check | Command/action | PASS condition |
80 +| --- | --- | --- |
81 +| Open picker | Click clipboard widget or call Quickshell IPC. | Picker opens and is styled with Nugu. |
82 +| List recent text | Copy several text snippets. | Picker shows recent history, max 5 in compact context where applicable. |
83 +| Truncation | Copy text longer than 30 chars. | Display truncates end around current Ironbar behavior. |
84 +| Select item | Choose older item. | Item is decoded and written to clipboard via `wl-copy`; paste returns selected item. |
85 +| Empty state | Clear/test empty history if safe. | Empty state is visible and non-crashing. |
87 +### Bind mode
89 +| Check | Command/action | PASS condition |
90 +| --- | --- | --- |
91 +| Normal state | Inspect bar during normal operation. | Hidden/empty if no bind mode active, matching Ironbar behavior. |
92 +| Mode state | Trigger a Hypr bind mode if one exists. | Bar shows mode name, truncated at 20 if needed. |
94 +### Music/MPRIS
96 +| Check | Command/action | PASS condition |
97 +| --- | --- | --- |
98 +| Idle | No MPRIS player. | Widget hidden/empty cleanly; no log spam loop. |
99 +| Playing | Start an MPRIS player. | Center shows `{title} / {artist}`, truncates around 42 chars. |
100 +| Metadata update | Change track. | Text updates without restart. |
101 +| Controls unaffected | Use media keys/OSD phase if present. | MPRIS state remains correct. |
103 +### Clock/calendar
105 +| Check | Command/action | PASS condition |
106 +| --- | --- | --- |
107 +| Time text | Inspect center. | Shows `%H:%M`, bold/accent like Ironbar. |
108 +| Minute update | Wait minute boundary. | Time updates. |
109 +| Calendar popup | Click clock. | Popup opens and is readable. |
110 +| Calendar dark/light | Toggle mode. | Calendar colors remain readable in both modes. |
112 +### Notification status bridge/native
114 +| Check | Command/action | PASS condition |
115 +| --- | --- | --- |
116 +| No notifications | Clear notifications. | Shows `󰂚` or final chosen equivalent. |
117 +| Count | Send notifications. | Shows `󰂞 N` or final chosen equivalent. |
118 +| Restore | Left click. | Restores last notification while Mako bridge is active or native equivalent after Phase 3. |
119 +| Dismiss all | Right click. | Dismisses all visible notifications. |
120 +| No shell poll after native | Inspect implementation/processes. | Phase 3 native path has no `mako-status.sh` polling. |
122 +### WiFi
124 +| Check | Command/action | PASS condition |
125 +| --- | --- | --- |
126 +| Connected state | Normal connected iwd state. | Shows `󰖩`. |
127 +| Disconnected state | Safe disconnect/test or mock adapter in dev plan. | Shows `󰖪 off`. |
128 +| Left click | Click widget. | Opens `impala` via existing terminal policy. |
129 +| Middle click | Middle click widget. | Opens `impala`. |
130 +| No NetworkManager dependency | Inspect deps/commands. | Uses iwd/process adapter; does not require NetworkManager. |
132 +### Bluetooth
134 +| Check | Command/action | PASS condition |
135 +| --- | --- | --- |
136 +| Not found/disabled/enabled | Toggle adapter only if safe. | Icons match current behavior: empty/`󰂲`/`󰂯`. |
137 +| Connected | Connect paired device if available. | Shows `󰂱`; battery percent if available. |
138 +| Left click | Click widget. | Opens `bluetui`. |
139 +| Middle click | Middle click widget. | Opens `bluetui`. |
140 +| No ugly popup | Click behavior. | Does not show the old unwanted GTK Bluetooth popup. |
142 +### Tray
144 +| Check | Command/action | PASS condition |
145 +| --- | --- | --- |
146 +| Icons | Start normal tray apps. | Existing tray icons render at about `14px`. |
147 +| Menus | Open tray item menu. | Menu opens and is readable/clickable. |
148 +| Passive/attention state | Observe available tray items. | Passive dims/attention visible if service exposes state. |
150 +### CPU/system monitor
152 +| Check | Command/action | PASS condition |
153 +| --- | --- | --- |
154 +| Display | Inspect bar. | Shows ` N%`. |
155 +| Update interval | Watch for >2s. | Value updates around 2s cadence, not per-frame. |
156 +| Left/middle click | Click widget. | Opens `btm` via existing terminal policy. |
158 +### Volume
160 +| Check | Command/action | PASS condition |
161 +| --- | --- | --- |
162 +| Display | Inspect bar. | Shows current sink volume/mute state. |
163 +| Scroll up | Scroll over widget. | Volume increases by about 2%, max 100/1.0 unless current overdrive policy says otherwise. |
164 +| Scroll down | Scroll over widget. | Volume decreases by about 2%. |
165 +| Right click | Right click widget. | Toggles mute. |
166 +| Middle click | Middle click widget. | Opens `wiremix`. |
167 +| Pipewire state | Change volume externally with `wpctl`. | Widget updates without restart. |
169 +### Brightness
171 +| Check | Command/action | PASS condition |
172 +| --- | --- | --- |
173 +| Display | Inspect bar. | Shows `󰃠 N%`. |
174 +| Scroll up/down | Scroll over widget. | Backlight changes similarly to Ironbar. |
175 +| External update | `brightnessctl` if safe. | Widget updates. |
176 +| Device | Inspect implementation. | Uses X230 `intel_backlight` or robust detected backlight. |
178 +### Battery
180 +| Check | Command/action | PASS condition |
181 +| --- | --- | --- |
182 +| Display | Inspect X230. | Shows `󰁹 N%`. |
183 +| Hidden desktop case | If no battery environment is available. | Hidden when no `BAT*`, matching Ironbar `show_if`. |
184 +| Warning | Simulate or inspect threshold logic. | <=20% warning color. |
185 +| Critical | Simulate or inspect threshold logic. | <=5% and discharging uses critical icon/color. |
186 +| Click | Left/middle click. | Opens current battery/upower terminal or native equivalent. |
188 +### Inhibit
190 +| Check | Command/action | PASS condition |
191 +| --- | --- | --- |
192 +| Initial | Inspect widget. | Shows off state `󰛊 inf` or matching default duration. |
193 +| Toggle | Left click. | Shows on state `󰅶 {duration}` and inhibits idle. |
194 +| Cycle | Right click repeatedly. | Cycles `30m`, `1h`, `2h`, `inf`. |
195 +| Timeout | Let short duration expire if implemented. | Inhibit turns off after duration. |
197 +### Power menu
199 +| Check | Command/action | PASS condition |
200 +| --- | --- | --- |
201 +| Open | Click `󰐥`. | Popup opens, styled with Nugu. |
202 +| Uptime | Inspect popup. | Shows uptime line equivalent to `up ...`. |
203 +| Lock | Click lock. | Runs `hyprlock` or dry-run in safe test; no crash. |
204 +| Sleep | Use only with approval or dry-run. | Runs lock+suspend path when approved. |
205 +| Logout | Dry-run or confirmation. | Equivalent to `hyprshutdown` logout semantics. |
206 +| Poweroff/reboot | Confirmation only unless explicitly approved. | No accidental destructive action. |
208 +## Notification daemon parity acceptance
210 +Before native test:
212 +```sh
213 +systemctl --user stop mako.service
214 +```
216 +Rollback:
218 +```sh
219 +systemctl --user restart mako.service
220 +```
222 +| Check | Command/action | PASS condition |
223 +| --- | --- | --- |
224 +| DBus ownership | Stop Mako, start Quickshell notifications, run `notify-send hello body`. | Quickshell receives and displays notification. |
225 +| Placement | Send normal notification. | Top-right overlay, width 360, height <=160, margin/outer-margin visually match. |
226 +| Typography | Visual inspect. | `IBM Plex Sans 10`, summary bold, body readable. |
227 +| Icon | `notify-send -i dialog-information hello body`. | Icon shown max 48px with rounded corners. |
228 +| Normal timeout | Send normal notification. | Expires after about 6500ms. |
229 +| Low timeout | `notify-send -u low hello body`. | Expires after about 2500ms. |
230 +| Critical timeout | `notify-send -u critical hello body`. | Persists until dismissed. |
231 +| Max visible | Send 6 notifications. | 4 visible max, overflow indicator shown. |
232 +| History cap | Send >80 in controlled test. | History does not grow unbounded; cap 80. |
233 +| Left click | Send notification with default action. | Invokes default action. |
234 +| Middle click | Send grouped notifications. | Dismisses group. |
235 +| Right click | Send notification. | Dismisses notification. |
236 +| Actions | Send action notification via a test tool. | Action buttons invoke correct actions. |
237 +| Markup | Send markup body. | Markup renders safely. |
238 +| Error regex | Summary contains `Error`/`Failed`/`Crash`. | Error color/border. |
239 +| Warning regex | Summary contains `Warn`/`Warning`. | Warning color/border. |
240 +| Info regex | Summary contains `Info`/`Notice`. | Info color/border. |
241 +| Restore IPC | Call `qs -c nugu ipc call nugu restoreNotification`. | Last/history notification restored. |
242 +| Dismiss IPC | Call `qs -c nugu ipc call nugu dismissNotifications`. | Visible notifications dismissed. |
244 +## Launcher/clipboard/power/OSD parity acceptance
246 +| Check | Command/action | PASS condition |
247 +| --- | --- | --- |
248 +| Launcher bind | Press `SUPER+Space`. | Quickshell launcher opens, not Hyprlauncher. |
249 +| Search app | Type app name. | Matching desktop entries filter live. |
250 +| Launch app | Select app. | App launches and launcher closes. |
251 +| Escape | Press Escape. | Launcher closes without side effects. |
252 +| Clipboard bind | Press `SUPER+V`. | Quickshell clipboard picker opens. |
253 +| Clipboard select | Select old clip. | Clipboard contains selected decoded value. |
254 +| Power bind | Press `CTRL+ALT+Delete`. | Quickshell power/logout surface opens; no immediate destructive action. |
255 +| Volume keys | Press XF86 volume up/down/mute. | Volume changes and Quickshell OSD appears. |
256 +| Mic mute | Press mic mute key if available. | Mic mute toggles and OSD appears. |
257 +| Brightness keys | Press XF86 brightness up/down. | Brightness changes and OSD appears. |
258 +| Media keys | Press play/next/prev. | MPRIS action fires and OSD/status appears. |
259 +| Lock bind | Press `SUPER+ALT+L`. | Quickshell status appears, then existing lock path works. |
260 +| Reload bind | Press `SUPER+SHIFT+R`. | Hypr reloads; Quickshell status appears. |
261 +| Screenshot region | Press `Print`. | Region capture still works; Quickshell status appears. |
262 +| Screenshot annotate | Press `SUPER+Print`. | Satty annotation path still works; status appears. |
263 +| Color pick | Press `SUPER+SHIFT+Print`. | Color is copied; status appears. |
265 +## Dark/light acceptance
267 +| Check | Command/action | PASS condition |
268 +| --- | --- | --- |
269 +| Dark switch | Run Nugu switcher to dark. | Hypr, Quickshell bar, popups, notifications, launcher, OSD all dark. |
270 +| Light switch | Run Nugu switcher to light. | Same surfaces light and readable. |
271 +| Auto mode | Enable/watch current auto behavior. | Quickshell follows mode change without requiring Ironbar/Mako restart. |
272 +| GTK scheme | `gsettings get org.gnome.desktop.interface color-scheme`. | Matches `prefer-dark`/`prefer-light`. |
273 +| Contrast | Use `pastel` or visual check on critical pairs. | Small text fg/bg pairs meet target contrast or are consciously adjusted. |
275 +## Retirement acceptance
277 +Run only after all relevant parity rows pass.
279 +| Candidate | Stop command | PASS condition before disabling in dotfiles |
280 +| --- | --- | --- |
281 +| Ironbar | `systemctl --user stop ironbar.service ironbar-workspaces.service` | Quickshell bar covers all bar rows; no missing interaction. |
282 +| Mako | `systemctl --user stop mako.service` | Quickshell owns notifications and covers all notification rows. |
283 +| Hyprlauncher usage | Remove/replace binds in test branch. | `grep -R hyprlauncher hypr ironbar quickshell` finds no live-path usage except docs/history. |
284 +| Hyprshutdown usage | Replace with Quickshell power IPC. | `grep -R hyprshutdown hypr ironbar quickshell` finds no live-path usage except docs/history. |
285 +| Hyprtoolkit config | Remove after no Hyprtoolkit apps remain. | No remaining live bindings/apps consume `hyprtoolkit.conf`. |
286 +| `hyprctl notify` helpers | Replace OSD/status. | `grep -R 'hyprctl notify' hypr quickshell` finds no live helper use. |
288 +## Final resource comparison
290 +Collect after old services stopped and Quickshell settled for at least 60s:
292 +```sh
293 +ps -eo pid,pcpu,rss,comm,args | grep -E 'ironbar|mako|workspaces-watch|hyprlauncher|hyprshutdown|qs|quickshell' | grep -v grep || true
294 +systemctl --user --no-pager --plain status quickshell.service
295 +systemctl --user --no-pager --plain status ironbar.service ironbar-workspaces.service mako.service || true
296 +```
298 +PASS condition:
300 +- Old retired services inactive/disabled as intended.
301 +- Quickshell service active.
302 +- Process count is lower for companion UI.
303 +- CPU/log spam is not worse than baseline.
304 +- RSS is lower than old combined steady-state or any increase is explicitly justified by replaced functionality.