repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): plan initial bar shell

30d758f0c04ef53db28f566b2038455cebec3a2c

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (2)

docs/super/plans/2026-06-17-quickshell-hypr-companions-phase-2a-bar-shell.md

Added
new file mode 100644
1 +# Quickshell Hypr Companions Phase 2A Bar Shell Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Add a hidden-by-default Quickshell top bar shell with Nugu styling, workspace buttons, and clock, without replacing Ironbar.
7 +**Architecture:** This is the first subplan of Roadmap Phase 2. It wires a per-monitor `Bar` into the existing Phase 1 `Scope`, controlled by IPC (`showBar`/`hideBar`/`toggleBar`) so it can be tested safely beside the current desktop. The bar uses Quickshell's Hyprland service for workspace active/occupied state and `SystemClock` for time.
9 +**Tech Stack:** Quickshell 0.3.0, QML/QtQuick, `Quickshell.Hyprland`, `SystemClock`, Nugu Theme service from Phase 1.
11 +**Roadmap:** [`docs/super/roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md`](../roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md)
13 +**Architecture Spec:** [`docs/super/specs/2026-06-17-quickshell-hypr-companions-architecture.md`](../specs/2026-06-17-quickshell-hypr-companions-architecture.md)
15 +**Parity Checklist:** [`docs/super/inventory/2026-06-17-quickshell-parity-checklist.md`](../inventory/2026-06-17-quickshell-parity-checklist.md)
17 +**Phase:** Phase 2A: Bar shell, workspaces, clock
19 +---
21 +## Scope Boundary
23 +This plan intentionally implements only the safe first slice of Ironbar parity:
25 +- Top bar shell, hidden by default.
26 +- Nugu bar styling: height, padding, font, background, accent bottom border, hover/active/muted colors.
27 +- Workspace labels/actions for `1..5,9`.
28 +- Clock text `%H:%M`.
29 +- IPC to show/hide/toggle the bar for tests.
31 +Out of scope for this subplan:
33 +- Retiring or stopping Ironbar persistently.
34 +- Mako/notifications, tray, clipboard, bind mode, MPRIS, WiFi, Bluetooth, CPU, volume, brightness, battery, inhibit, power popup.
35 +- Hypr bind migration.
37 +Phase boundary: after this plan, Ironbar and Mako remain active. Quickshell can show a partial bar only on demand for visual and workspace testing.
39 +## File Structure
41 +Create:
43 +- `quickshell/nugu/Bar.qml` — per-monitor top bar shell and section layout.
44 +- `quickshell/nugu/BarButton.qml` — shared compact Nugu button primitive.
45 +- `quickshell/nugu/WorkspaceWidget.qml` — workspace row with labels, active/occupied/muted state, click-to-focus.
46 +- `quickshell/nugu/ClockWidget.qml` — center `%H:%M` clock.
48 +Modify:
50 +- `quickshell/nugu/shell.qml` — add `barVisible` state, IPC methods, per-monitor `Variants`.
51 +- `quickshell/nugu/README.md` — document Phase 2A IPC and safe test flow.
53 +Do not modify:
55 +- `hypr/modules/*`.
56 +- `ironbar/*`.
57 +- `mako/*`.
58 +- service manifests.
60 +## Task 1: Add bar primitives
62 +**Files:**
64 +- Create: `quickshell/nugu/BarButton.qml`
66 +- [ ] **Step 1: Write `BarButton.qml`**
68 +Create this file exactly:
70 +```qml
71 +import QtQuick
73 +Item {
74 + id: root
76 + required property QtObject theme
77 + property string text: ""
78 + property bool active: false
79 + property bool muted: false
80 + property string tooltip: ""
82 + signal activated()
84 + implicitWidth: label.implicitWidth + 14
85 + implicitHeight: 22
87 + Rectangle {
88 + anchors.fill: parent
89 + radius: 7
90 + color: root.active ? root.theme.ui.focus : (mouse.containsMouse ? root.theme.ui.accent : "transparent")
91 + }
93 + Text {
94 + id: label
95 + anchors.centerIn: parent
96 + text: root.text
97 + color: root.active || mouse.containsMouse
98 + ? root.theme.content.backdrop
99 + : (root.muted ? root.theme.ui.minor : root.theme.ui.normal)
100 + font.family: "IBM Plex Mono"
101 + font.pixelSize: 12
102 + font.bold: root.active
103 + font.features: { "tnum": 1 }
106 + MouseArea {
107 + id: mouse
108 + anchors.fill: parent
109 + hoverEnabled: true
110 + acceptedButtons: Qt.LeftButton
111 + onClicked: root.activated()
114 +```
116 +- [ ] **Step 2: Run direct parse check expecting failure until shell wires files**
118 +Run:
120 +```bash
121 +timeout 3s qs -p quickshell/nugu/shell.qml >/tmp/nugu-qs-2a-primitive.out 2>/tmp/nugu-qs-2a-primitive.err; code=$?; printf 'exit=%s\n' "$code"; sed -n '1,120p' /tmp/nugu-qs-2a-primitive.err
122 +```
124 +Expected: same result as Phase 1 (`124` and no QML errors) because the new file is not imported yet.
126 +## Task 2: Add workspace widget
128 +**Files:**
130 +- Create: `quickshell/nugu/WorkspaceWidget.qml`
132 +- [ ] **Step 1: Write `WorkspaceWidget.qml`**
134 +Create this file exactly:
136 +```qml
137 +import QtQuick
138 +import QtQuick.Layouts
139 +import Quickshell.Hyprland
140 +import "."
142 +RowLayout {
143 + id: root
145 + required property QtObject theme
147 + spacing: 4
149 + property var workspaces: [
150 + { "id": 1, "label": "1 󰖟" },
151 + { "id": 2, "label": "2 󰅨" },
152 + { "id": 3, "label": "3 󰆍" },
153 + { "id": 4, "label": "4 󰭹" },
154 + { "id": 5, "label": "5 󰎆" },
155 + { "id": 9, "label": "9 󰉋" }
158 + function workspaceObject(id: int): var {
159 + return Hyprland.workspaces.values.find(workspace => workspace.id === id) || null
162 + function active(id: int): bool {
163 + return Hyprland.focusedWorkspace !== null && Hyprland.focusedWorkspace.id === id
166 + function occupied(id: int): bool {
167 + const workspace = workspaceObject(id)
168 + return workspace !== null && workspace.toplevels !== null && workspace.toplevels.values.length > 0
171 + Repeater {
172 + model: root.workspaces
174 + BarButton {
175 + required property var modelData
177 + theme: root.theme
178 + text: modelData.label
179 + active: root.active(modelData.id)
180 + muted: !root.active(modelData.id) && !root.occupied(modelData.id)
181 + tooltip: `workspace ${modelData.id}`
182 + onActivated: {
183 + const workspace = root.workspaceObject(modelData.id)
184 + if (workspace !== null) {
185 + workspace.activate()
186 + } else {
187 + Hyprland.dispatch(`workspace ${modelData.id}`)
193 +```
195 +- [ ] **Step 2: Record API provenance in verification notes**
197 +Add this sentence to the eventual verification record for this phase:
199 +```markdown
200 +Workspace implementation uses Quickshell v0.3.0 `Hyprland.workspaces.values`, `Hyprland.focusedWorkspace`, `HyprlandWorkspace.toplevels.values`, and `HyprlandWorkspace.activate()` as documented in local Phase 2A planning.
201 +```
203 +## Task 3: Add clock widget
205 +**Files:**
207 +- Create: `quickshell/nugu/ClockWidget.qml`
209 +- [ ] **Step 1: Write `ClockWidget.qml`**
211 +Create this file exactly:
213 +```qml
214 +import QtQuick
215 +import Quickshell
216 +import "."
218 +BarButton {
219 + id: root
221 + required property QtObject theme
223 + text: Qt.formatTime(clock.date, "HH:mm")
224 + active: false
225 + muted: false
227 + SystemClock {
228 + id: clock
229 + precision: SystemClock.Minutes
232 +```
234 +- [ ] **Step 2: Note Phase 2C calendar dependency**
236 +Do not add a calendar popup in this task. The Phase 2C plan owns popups and full clock/calendar parity.
238 +## Task 4: Add top bar shell
240 +**Files:**
242 +- Create: `quickshell/nugu/Bar.qml`
244 +- [ ] **Step 1: Write `Bar.qml`**
246 +Create this file exactly:
248 +```qml
249 +import QtQuick
250 +import QtQuick.Layouts
251 +import Quickshell
252 +import "."
254 +PanelWindow {
255 + id: root
257 + required property QtObject theme
258 + property bool shown: false
260 + visible: shown
261 + anchors { top: true; left: true; right: true }
262 + implicitHeight: 30
263 + color: "transparent"
265 + Rectangle {
266 + anchors.fill: parent
267 + color: `${root.theme.ui.backdrop}ee`
270 + Rectangle {
271 + anchors.left: parent.left
272 + anchors.right: parent.right
273 + anchors.bottom: parent.bottom
274 + height: 2
275 + color: root.theme.ui.accent
278 + RowLayout {
279 + anchors.fill: parent
280 + anchors.leftMargin: 20
281 + anchors.rightMargin: 20
282 + anchors.topMargin: 0
283 + anchors.bottomMargin: 2
284 + spacing: 8
286 + RowLayout {
287 + Layout.fillWidth: true
288 + Layout.alignment: Qt.AlignVCenter
289 + spacing: 10
291 + WorkspaceWidget { theme: root.theme }
294 + RowLayout {
295 + Layout.alignment: Qt.AlignCenter
296 + spacing: 8
298 + ClockWidget { theme: root.theme }
301 + RowLayout {
302 + Layout.fillWidth: true
303 + Layout.alignment: Qt.AlignVCenter | Qt.AlignRight
304 + spacing: 8
308 +```
310 +- [ ] **Step 2: Check that bar remains unreachable until shell wiring**
312 +Run:
314 +```bash
315 +timeout 3s qs -p quickshell/nugu/shell.qml >/tmp/nugu-qs-2a-bar-unwired.out 2>/tmp/nugu-qs-2a-bar-unwired.err; code=$?; printf 'exit=%s\n' "$code"; sed -n '1,160p' /tmp/nugu-qs-2a-bar-unwired.err
316 +```
318 +Expected: exit `124`, no QML parse/type errors.
320 +## Task 5: Wire bar into shell IPC
322 +**Files:**
324 +- Modify: `quickshell/nugu/shell.qml`
326 +- [ ] **Step 1: Replace `shell.qml` with bar-aware root**
328 +Replace the whole file with this content:
330 +```qml
331 +import QtQuick
332 +import Quickshell
333 +import Quickshell.Io
334 +import "."
336 +Scope {
337 + id: root
339 + property bool diagnosticsVisible: false
340 + property bool barVisible: false
342 + Theme { id: theme }
344 + IpcHandler {
345 + target: "nugu"
347 + function showDiagnostics(): void { root.diagnosticsVisible = true }
348 + function hideDiagnostics(): void { root.diagnosticsVisible = false }
349 + function toggleDiagnostics(): void { root.diagnosticsVisible = !root.diagnosticsVisible }
351 + function showBar(): void { root.barVisible = true }
352 + function hideBar(): void { root.barVisible = false }
353 + function toggleBar(): void { root.barVisible = !root.barVisible }
355 + function reloadTheme(): void { theme.reload() }
356 + function setThemeMode(mode: string): void { theme.setMode(mode) }
359 + Variants {
360 + model: Quickshell.screens
361 + delegate: Component {
362 + Bar {
363 + required property var modelData
365 + screen: modelData
366 + theme: theme
367 + shown: root.barVisible
372 + Diagnostics {
373 + visible: root.diagnosticsVisible
374 + theme: theme
377 +```
379 +- [ ] **Step 2: Validate direct parse/start**
381 +Run:
383 +```bash
384 +timeout 3s qs -p quickshell/nugu/shell.qml >/tmp/nugu-qs-2a-wired.out 2>/tmp/nugu-qs-2a-wired.err; code=$?; printf 'exit=%s\n' "$code"; sed -n '1,200p' /tmp/nugu-qs-2a-wired.err
385 +```
387 +Expected:
389 +- Exit `124` from timeout.
390 +- No QML parse/type errors.
391 +- No errors about `SystemClock.Minutes`, `Hyprland.workspaces.values`, or missing `BarButton` type.
393 +## Task 6: Validate live IPC without retiring Ironbar
395 +**Files:**
397 +- No tracked changes.
399 +- [ ] **Step 1: Start temporary named config**
401 +Run from repo root after Phase 1 link exists, or create the same symlink used by Phase 1:
403 +```bash
404 +mkdir -p ~/.config/quickshell
405 +ln -sfn "$PWD/quickshell/nugu" ~/.config/quickshell/nugu
406 +QS_NO_RELOAD_POPUP=1 qs -c nugu >/tmp/nugu-qs-2a-ipc.out 2>/tmp/nugu-qs-2a-ipc.err &
407 +printf '%s\n' $! >/tmp/nugu-qs-2a-ipc.pid
408 +sleep 1
409 +sed -n '1,160p' /tmp/nugu-qs-2a-ipc.err
410 +```
412 +Expected: no QML parse/type errors. This does not use systemd and does not disable Ironbar.
414 +- [ ] **Step 2: Show bar**
416 +Run:
418 +```bash
419 +qs -c nugu ipc call nugu showBar
420 +sleep 1
421 +```
423 +Expected: Quickshell bar appears. Ironbar may still be visible; this is a temporary overlap test, not final visual approval.
425 +- [ ] **Step 3: Test workspace clicks visually**
427 +Manually click workspace buttons `1`, `2`, `3`, `4`, `5`, `9`.
429 +Expected:
431 +- Hyprland switches to clicked workspace.
432 +- Active workspace highlight changes immediately.
433 +- Empty workspaces are muted.
434 +- Occupied workspaces are normal foreground.
436 +- [ ] **Step 4: Test clock and theme switching**
438 +Run:
440 +```bash
441 +qs -c nugu ipc call nugu setThemeMode light
442 +sleep 1
443 +qs -c nugu ipc call nugu setThemeMode dark
444 +sleep 1
445 +```
447 +Expected:
449 +- Bar colors change with Nugu mode.
450 +- Clock remains visible and formatted `HH:mm`.
452 +- [ ] **Step 5: Hide bar**
454 +Run:
456 +```bash
457 +qs -c nugu ipc call nugu hideBar
458 +```
460 +Expected: Quickshell bar disappears; Ironbar remains live.
462 +- [ ] **Step 6: Stop temporary Quickshell**
464 +Run:
466 +```bash
467 +kill "$(cat /tmp/nugu-qs-2a-ipc.pid)"
468 +rm -f /tmp/nugu-qs-2a-ipc.pid
469 +ps -eo pid,pcpu,rss,comm,args | grep -E 'qs -c nugu|quickshell' | grep -v grep || true
470 +```
472 +Expected: no temporary `qs -c nugu` process remains.
474 +## Task 7: Update README and verification record
476 +**Files:**
478 +- Modify: `quickshell/nugu/README.md`
479 +- Create: `docs/super/inventory/2026-06-17-quickshell-phase-2a-verification.md`
481 +- [ ] **Step 1: Append Phase 2A README section**
483 +Append this to `quickshell/nugu/README.md`:
485 +```markdown
487 +## Phase 2A bar IPC
489 +The bar is hidden by default while Ironbar remains the live bar.
491 +```sh
492 +qs -c nugu ipc call nugu showBar
493 +qs -c nugu ipc call nugu hideBar
494 +qs -c nugu ipc call nugu toggleBar
495 +```
497 +Phase 2A only covers bar shell, workspaces, and clock. Full Ironbar parity requires later Phase 2B/2C plans.
498 +```
500 +- [ ] **Step 2: Write verification record**
502 +Run:
504 +```bash
505 +mkdir -p docs/super/inventory
507 + printf '# Quickshell Phase 2A Verification — 2026-06-17\n\n'
508 + printf '## Commands\n\n'
509 + printf -- '- `timeout 3s qs -p quickshell/nugu/shell.qml`\n'
510 + printf -- '- `qs -c nugu ipc call nugu showBar`\n'
511 + printf -- '- `qs -c nugu ipc call nugu setThemeMode light`\n'
512 + printf -- '- `qs -c nugu ipc call nugu setThemeMode dark`\n'
513 + printf -- '- `qs -c nugu ipc call nugu hideBar`\n\n'
514 + printf '## Parse stderr\n\n```text\n'
515 + sed -n '1,200p' /tmp/nugu-qs-2a-wired.err 2>/dev/null || true
516 + printf '\n```\n\n'
517 + printf '## IPC stderr\n\n```text\n'
518 + sed -n '1,200p' /tmp/nugu-qs-2a-ipc.err 2>/dev/null || true
519 + printf '\n```\n\n'
520 + printf '## Manual observations\n\n'
521 + printf -- '- Bar appeared after showBar: recorded during execution.\n'
522 + printf -- '- Workspace buttons 1/2/3/4/5/9 switched Hypr workspaces: recorded during execution.\n'
523 + printf -- '- Workspace active/occupied/muted colors updated: recorded during execution.\n'
524 + printf -- '- Clock displayed HH:mm: recorded during execution.\n'
525 + printf -- '- Dark/light IPC changed bar colors: recorded during execution.\n'
526 + printf -- '- Ironbar remained live and was not retired.\n'
527 + printf -- '- Workspace implementation uses Quickshell v0.3.0 `Hyprland.workspaces.values`, `Hyprland.focusedWorkspace`, `HyprlandWorkspace.toplevels.values`, and `HyprlandWorkspace.activate()`.\n'
528 +} > docs/super/inventory/2026-06-17-quickshell-phase-2a-verification.md
529 +```
531 +- [ ] **Step 3: Confirm old services still run**
533 +Run:
535 +```bash
536 +systemctl --user --no-pager --plain is-active ironbar.service ironbar-workspaces.service mako.service
537 +```
539 +Expected: all three are still active.
541 +## Task 8: Commit Phase 2A
543 +**Files:**
545 +- Add/modify all files from prior tasks.
547 +- [ ] **Step 1: Check status**
549 +Run:
551 +```bash
552 +git status --short
553 +```
555 +Expected: only intended Phase 2A files plus pre-existing unrelated dirty work.
557 +- [ ] **Step 2: Commit**
559 +Run:
561 +```bash
562 +git add quickshell/nugu/Bar.qml quickshell/nugu/BarButton.qml quickshell/nugu/WorkspaceWidget.qml quickshell/nugu/ClockWidget.qml quickshell/nugu/shell.qml quickshell/nugu/README.md docs/super/inventory/2026-06-17-quickshell-phase-2a-verification.md
563 +git commit -m "feat(quickshell): add initial nugu bar shell"
564 +```
566 +## Task 9: Phase boundary check
568 +**Files:**
570 +- No tracked changes unless verification found a bug.
572 +- [ ] **Step 1: Non-mutating final checks**
574 +Run:
576 +```bash
577 +hyprctl configerrors
578 +systemctl --user --no-pager --plain is-active ironbar.service mako.service
579 +ps -eo pid,pcpu,rss,comm,args | grep -E 'ironbar|mako|workspaces-watch|qs -c nugu|quickshell' | grep -v grep || true
580 +```
582 +Expected:
584 +- `hyprctl configerrors` empty.
585 +- Ironbar and Mako active.
586 +- No stray temporary `qs -c nugu` process unless explicitly left running for user review.
588 +- [ ] **Step 2: Report next subplan**
590 +Report:
592 +```text
593 +Phase 2A adds hidden Quickshell bar shell/workspaces/clock only. Ironbar remains live. Next plan: Phase 2B status/service widgets.
594 +```
596 +Do not start Phase 2B implementation in the same execution pass.
598 +## Plan validation note
600 +Before implementation, the planned Phase 2A QML files were copied with Phase 1 `Theme.qml` and `hypr/generated/nugu.json` to a temporary `/tmp/pi-exp.qs-phase2a.*` directory and run with:
602 +```bash
603 +timeout 3s qs -p /tmp/pi-exp.qs-phase2a.*/quickshell/nugu/shell.qml
604 +```
606 +Observed result on 2026-06-17: exit `124` from `timeout`, empty stderr, temp directory deleted. This supports the planned bar/workspace/clock QML parse/start shape on local Quickshell `0.3.0`.

docs/super/roadmaps/2026-06-17-quickshell-hypr-companions-roadmap.md

Modified
115 115 **Context notes:** This phase can end with Ironbar still running. Retirement happens in Phase 5 after final visual/interaction approval.
117 +**Detailed execution split:** Phase 2 is too large for one safe task-level plan. Keep the Phase 2 outcome unchanged, but write and execute it as:
119 +- Phase 2A: bar shell, shared bar primitives, workspace widget, clock widget, safe show/hide IPC.
120 +- Phase 2B: status/service widgets for MPRIS, WiFi, Bluetooth, CPU, volume, brightness, battery.
121 +- Phase 2C: tray, clipboard entry point, bind mode, notification bridge, inhibit, power popup, full dark/light visual comparison.
123 +Ironbar remains live and enabled through all Phase 2 subplans. No retirement happens until Phase 5.
117 125 ## Phase 3: Quickshell Notification Daemon Replacing Mako
119 127 **Outcome:** Quickshell owns notifications with Mako-equivalent placement, style, actions, grouping/overflow, history, restore, dismiss-all, and dark/light colors.