repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(nuguland): orientation implementation plan

b63ddfa182ae4e08da8587173882e27325d08d99

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Changed files (1)

docs/superpowers/plans/2026-06-28-nuguland-orientation.md

Added
new file mode 100644
1 +# Nuguland Orientation Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Let the nuguland bar and all its widgets render in either a horizontal (top edge, default) or a vertical (left edge) orientation, with abbreviated labels and a stacked clock in vertical mode.
7 +**Architecture:** A single `orientation` string on `shell.qml` is injected into the Bar (visual layout) and the SurfaceManager (popout geometry), threaded through the existing `setPopoutScreen` channel. No singleton — consistent with the project's inject-via-shell DI. OSD/toast surfaces are untouched (they anchor top-right, independent of the bar).
9 +**Tech Stack:** Quickshell / QML (Qt6), niri compositor keybinds (KDL), systemd user service.
11 +## Global Constraints
13 +- No `pragma Singleton`; inject required properties via `shell.qml`; never re-declare inherited required props. (`nuguland-di-no-singleton`)
14 +- `stateJson()` / per-handler IPC JSON is a contract — additive changes only, never refactor existing serialization away. (`nuguland-statejson-is-ipc-contract`)
15 +- Sizes and positions are content-driven, never hardcoded magic numbers — vertical bar thickness derives from widest chip content.
16 +- No automated QML test runner exists. Verification = pure-function selftests exposed over IPC + live restart + journal grep + geometry reads (`registeredAnchors`, `popoutState`). (`qs-ipc-bracket-arg-spread`)
17 +- IPC target for the main handler is `nuguland`; call pattern: `qs ipc -c nuguland call nuguland <fn> <args>`.
18 +- After deleting/renaming QML symbols, clear `~/.cache/quickshell/qmlcache` or stale TypeErrors appear. (`quickshell-qmlcache-stale-symbols`)
19 +- Two commits total: one at the end of Phase 1 (Task 4), one at the end of Phase 2 (Task 6). Tasks within a phase accumulate uncommitted.
21 +**Restart + verify loop (used in every task's verification):**
22 +```bash
23 +rm -rf ~/.cache/quickshell/qmlcache
24 +systemctl --user restart quickshell
25 +sleep 2
26 +journalctl --user -u quickshell -n 60 --no-pager | grep -iE "error|warning|typeerror" || echo "clean"
27 +```
29 +---
31 +## File Structure
33 +- `quickshell/nuguland/shell.qml` — `orientation` property, `setOrientation` IPC, `registeredAnchors`/`popoutState` read IPCs, `abbreviateSelfTest` IPC, inject `orientation` into Bar.
34 +- `quickshell/nuguland/Bar.qml` — `orientation`/`vertical` props, `abbreviate()`, anchor + thickness switch, vertical workspace column (idx-only pills), GridLayout widgets zone, vertical stacked clock chip with overlap guard.
35 +- `quickshell/nuguland/SurfaceManager.qml` — `orientation` property, left-bar popout geometry in `popupWindowAnchorRect`/`popupCardFrame`/`popoutWidth`/`heightBudget`/`clampedTarget`/`popoutState`, `setPopoutScreen` gains orientation arg.
36 +- `quickshell/nuguland/PopoutHost.qml` — input-region origin, surface dims, slide direction orientation-aware.
37 +- `niri/cfg/keybinds.kdl` — orientation toggle keybind.
39 +---
41 +# Phase 1 — bar visual
43 +## Task 1: Orientation flag, IPC, keybind, verification scaffolding
45 +**Files:**
46 +- Modify: `quickshell/nuguland/shell.qml` (add property + IPC functions in the `target: "nuguland"` handler, after `niriSelfTest` at line ~604)
47 +- Modify: `niri/cfg/keybinds.kdl`
49 +**Interfaces:**
50 +- Produces: `shell.orientation` (string `"horizontal"`|`"vertical"`); IPC `setOrientation(mode) -> string` (accepts `"horizontal"`|`"vertical"`|`"toggle"`, returns resulting orientation); IPC `registeredAnchors() -> string` (JSON); IPC `popoutState() -> string` (JSON); these read-IPCs are consumed by later tasks' verification.
52 +- [ ] **Step 1: Add the orientation property to ShellRoot**
54 +In `shell.qml`, after the `primaryScreenName` block (line 24), add:
55 +```qml
56 + // Bar orientation: "horizontal" (top edge, default) or "vertical" (left
57 + // edge). Injected into the Bar and the SurfaceManager so layout and popout
58 + // geometry share one source of truth.
59 + property string orientation: "horizontal"
60 +```
62 +- [ ] **Step 2: Add IPC functions**
64 +In the `IpcHandler` whose `target: "nuguland"` (the block starting line 593), after `niriSelfTest()` (ends line 604), add:
65 +```qml
66 + function setOrientation(mode: string) : string {
67 + const want = String(mode);
68 + if (want === "toggle")
69 + shell.orientation = shell.orientation === "vertical" ? "horizontal" : "vertical";
70 + else if (want === "horizontal" || want === "vertical")
71 + shell.orientation = want;
73 + return shell.orientation;
74 + }
76 + function registeredAnchors() : string {
77 + return surfaceManager.registeredAnchors();
78 + }
80 + function popoutState() : string {
81 + return surfaceManager.popoutState();
82 + }
83 +```
85 +- [ ] **Step 3: Add the niri toggle keybind**
87 +In `niri/cfg/keybinds.kdl`, inside the `binds {` block (after the `Mod+Space` launcher bind, around line 17), add:
88 +```kdl
89 + Mod+Shift+O hotkey-overlay-title="Nuguland: toggle bar orientation" {
90 + spawn "uwsm" "app" "-s" "session-graphical.slice" "--" "qs" "ipc" "-c" "nuguland" "call" "nuguland" "setOrientation" "toggle"
91 + }
92 +```
94 +- [ ] **Step 4: Restart and verify IPC**
96 +```bash
97 +rm -rf ~/.cache/quickshell/qmlcache
98 +systemctl --user restart quickshell
99 +sleep 2
100 +journalctl --user -u quickshell -n 60 --no-pager | grep -iE "error|typeerror" || echo "clean"
101 +qs ipc -c nuguland call nuguland setOrientation vertical
102 +qs ipc -c nuguland call nuguland setOrientation toggle
103 +qs ipc -c nuguland call nuguland setOrientation horizontal
104 +qs ipc -c nuguland call nuguland registeredAnchors
105 +```
106 +Expected: journal `clean`; calls return `vertical`, then `horizontal`, then `horizontal`; `registeredAnchors` returns a JSON object. No visual change yet (Bar ignores orientation until Task 3).
108 +- [ ] **Step 5: Reload niri config and test keybind**
110 +```bash
111 +niri msg action load-config-file 2>/dev/null || true
112 +```
113 +Press `Mod+Shift+O`, then:
114 +```bash
115 +qs ipc -c nuguland call nuguland setOrientation toggle
116 +```
117 +Expected: the call returns whichever value is now current (confirms the keybind flipped it). No commit (accumulates into Phase 1).
119 +---
121 +## Task 2: abbreviate() pure function + selftest
123 +**Files:**
124 +- Modify: `quickshell/nuguland/Bar.qml` (add function after `chipLabel`, line ~57)
125 +- Modify: `quickshell/nuguland/shell.qml` (add `abbreviateSelfTest` IPC)
127 +**Interfaces:**
128 +- Consumes: nothing.
129 +- Produces: `Bar.abbreviate(text) -> string`; IPC `abbreviateSelfTest() -> string` returning `{"pass": bool, "failures": [...]}`.
131 +The rule (user-authored): drop the vowels `a e i o u`, then truncate to 3 chars; if the vowel-dropped result is shorter than 3, use the first 3 chars of the original.
133 +- [ ] **Step 1: Implement abbreviate() in Bar.qml**
135 +After `chipLabel()` closes (line 57), add:
136 +```qml
137 + // Vertical-mode label shortener (user rule): drop vowels, truncate to 3;
138 + // if the vowel-dropped result is under 3 chars, fall back to the first 3
139 + // of the original. Pure — gate-tested via abbreviateSelfTest IPC.
140 + function abbreviate(text) {
141 + const s = String(text);
142 + const stripped = s.replace(/[aeiou]/gi, "");
143 + return (stripped.length >= 3 ? stripped : s).slice(0, 3);
146 + function abbreviateSelfTest() {
147 + const cases = {
148 + "notify": "ntf",
149 + "code": "cod",
150 + "media": "med",
151 + "system": "sys",
152 + "audio": "aud",
153 + "power": "pwr",
154 + "idle": "idl",
155 + "tray": "try"
156 + };
157 + const failures = [];
158 + for (const key in cases) {
159 + const got = root.abbreviate(key);
160 + if (got !== cases[key])
161 + failures.push(`${key}: expected ${cases[key]}, got ${got}`);
163 + return {
164 + "pass": failures.length === 0,
165 + "failures": failures
166 + };
168 +```
170 +- [ ] **Step 2: Expose the selftest over IPC**
172 +In `shell.qml`, the `target: "nuguland"` handler, add after `popoutState()` (from Task 1):
173 +```qml
174 + function abbreviateSelfTest() : string {
175 + return JSON.stringify(bar.abbreviateSelfTest());
177 +```
178 +This requires a stable handle to the Bar instance. The Bar lives inside a `Variants` delegate (line 482) and has no `id`. Add `barRef` plumbing: in the Bar delegate (line 482), add a line `Component.onCompleted: shell.activeBar = this` is fragile across screens; instead expose the function on a shared object. **Simpler:** move `abbreviate`/`abbreviateSelfTest` to a tiny shared component.
180 +Create `quickshell/nuguland/Format.qml`:
181 +```qml
182 +pragma ComponentBehavior: Bound
183 +import QtQuick
185 +QtObject {
186 + function abbreviate(text) {
187 + const s = String(text);
188 + const stripped = s.replace(/[aeiou]/gi, "");
189 + return (stripped.length >= 3 ? stripped : s).slice(0, 3);
192 + function abbreviateSelfTest() {
193 + const cases = {
194 + "notify": "ntf", "code": "cod", "media": "med", "system": "sys",
195 + "audio": "aud", "power": "pwr", "idle": "idl", "tray": "try"
196 + };
197 + const failures = [];
198 + for (const key in cases) {
199 + const got = abbreviate(key);
200 + if (got !== cases[key])
201 + failures.push(`${key}: expected ${cases[key]}, got ${got}`);
203 + return { "pass": failures.length === 0, "failures": failures };
206 +```
208 +In `shell.qml`, instantiate it near `Theme` (line 26):
209 +```qml
210 + Format { id: format }
211 +```
212 +Replace the Bar.qml `abbreviate`/`abbreviateSelfTest` additions from Step 1 with an injected reference: in Bar.qml add `required property QtObject formatService` to the property block (after `usageService`, line 27), and use `root.formatService.abbreviate(...)`. Inject it in the Bar delegate (shell.qml line 506 area): `formatService: format`.
214 +The `shell.qml` IPC becomes:
215 +```qml
216 + function abbreviateSelfTest() : string {
217 + return JSON.stringify(format.abbreviateSelfTest());
219 +```
221 +- [ ] **Step 3: Restart and verify selftest**
223 +```bash
224 +rm -rf ~/.cache/quickshell/qmlcache
225 +systemctl --user restart quickshell
226 +sleep 2
227 +qs ipc -c nuguland call nuguland abbreviateSelfTest
228 +```
229 +Expected: `{"pass":true,"failures":[]}`. No commit.
231 +---
233 +## Task 3: Bar orientation-aware layout (anchors, thickness, zones, vertical pills)
235 +**Files:**
236 +- Modify: `quickshell/nuguland/Bar.qml`
238 +**Interfaces:**
239 +- Consumes: `root.orientation` (injected), `root.formatService.abbreviate()`.
240 +- Produces: a Bar that anchors left+vertical with content-driven `implicitWidth` when vertical; widgets stack; workspace pills render idx-only.
242 +- [ ] **Step 1: Add orientation props and inject from shell**
244 +In Bar.qml property block (after line 27 `usageService`), add:
245 +```qml
246 + required property string orientation
247 + readonly property bool vertical: orientation === "vertical"
248 +```
249 +In `shell.qml` Bar delegate (line 482 block), add: `orientation: shell.orientation`.
251 +- [ ] **Step 2: Switch root anchors and thickness**
253 +Replace the root sizing/anchors (lines 127-142) with:
254 +```qml
255 + screen: root.screen
256 + // horizontal: width spans (left+right anchored), implicitHeight sets bar
257 + // height. vertical: height spans (top+bottom anchored), implicitWidth sets
258 + // bar thickness from the widest chip content (never a magic constant).
259 + implicitHeight: 34
260 + implicitWidth: root.vertical ? Math.max(46, barContent.childrenRect.width + 12) : root.width
261 + color: "transparent"
262 + WlrLayershell.namespace: "nuguland-bar"
263 + WlrLayershell.layer: WlrLayer.Top
264 + WlrLayershell.keyboardFocus: WlrKeyboardFocus.None
265 + Component.onCompleted: Qt.callLater(root.refreshSurfaceGeometry)
266 + onSurfacesChanged: Qt.callLater(root.refreshSurfaceGeometry)
267 + onWidthChanged: root.refreshSurfaceGeometry()
268 + onHeightChanged: root.refreshSurfaceGeometry()
270 + anchors {
271 + top: true
272 + left: true
273 + right: !root.vertical
274 + bottom: root.vertical
276 +```
278 +- [ ] **Step 3: Pass orientation + thickness to SurfaceManager**
280 +Replace `refreshSurfaceGeometry()` (lines 121-125) with:
281 +```qml
282 + function refreshSurfaceGeometry() {
283 + if (root.surfaces) {
284 + const thickness = Math.round(root.vertical ? root.width : root.height);
285 + root.surfaces.setPopoutScreen(Math.round(root.screen ? root.screen.width : root.width), Math.round(root.screen ? root.screen.height : root.height), thickness, root.orientation);
288 +```
289 +(SurfaceManager's `setPopoutScreen` gains the 4th arg in Task 5; passing it now is harmless — extra args are ignored until then.)
291 +- [ ] **Step 4: Give the content Rectangle an id and make the edge line orientation-aware**
293 +Change line 144 `Rectangle {` (the `anchors.fill: parent` content container) to `Rectangle { id: barContent`. Replace the accent edge-line Rectangle (lines 148-154) with:
294 +```qml
295 + // accent edge: bottom hairline (horizontal) / right hairline (vertical)
296 + Rectangle {
297 + anchors.left: parent.left
298 + anchors.bottom: parent.bottom
299 + anchors.right: root.vertical ? undefined : parent.right
300 + anchors.top: root.vertical ? parent.top : undefined
301 + width: root.vertical ? 1 : undefined
302 + height: root.vertical ? undefined : 1
303 + color: root.theme ? root.theme.withAlpha(root.theme.ui.accent, 0.55) : "transparent"
305 +```
307 +- [ ] **Step 5: Make the workspace strip orientation-aware (idx-only vertical pills)**
309 +Replace the workspace `Row { id: workspaceStrip ... }` (lines 176-279) with a version that swaps flow and pin axis. Replace the `Row` header (lines 176-186) with:
310 +```qml
311 + // workspace strip: left zone (horizontal) above the clock / top zone
312 + // (vertical) above the clock. GridLayout unifies row/column flow.
313 + GridLayout {
314 + id: workspaceStrip
316 + flow: root.vertical ? GridLayout.TopToBottom : GridLayout.LeftToRight
317 + anchors.left: parent.left
318 + anchors.top: root.vertical ? parent.top : undefined
319 + anchors.leftMargin: root.vertical ? 0 : 10
320 + anchors.topMargin: root.vertical ? 10 : 0
321 + anchors.right: root.vertical ? parent.right : clockChip.left
322 + anchors.rightMargin: root.vertical ? 0 : 12
323 + anchors.bottom: root.vertical ? clockStack.top : undefined
324 + anchors.bottomMargin: root.vertical ? 10 : 0
325 + anchors.verticalCenter: root.vertical ? undefined : parent.verticalCenter
326 + anchors.horizontalCenter: root.vertical ? parent.horizontalCenter : undefined
327 + rowSpacing: 8
328 + columnSpacing: 8
329 + clip: true
330 +```
331 +The closing of this element stays the matched `}` at line 279. **Important:** the inner `Repeater`/`Item`/`Rectangle` tree (lines 188-277) is kept verbatim EXCEPT the workspace label, which becomes idx-only in vertical. Change `workspaceLabel` (line 233) to:
332 +```qml
333 + readonly property string workspaceLabel: root.vertical ? String(pillWrap.modelData.idx || pillWrap.modelData.id || "?") : `${pillWrap.modelData.idx || pillWrap.modelData.id || "?"}${pillWrap.modelData.name ? ` ${pillWrap.modelData.name}` : ""}`.toLowerCase()
334 +```
335 +And the group wrapper `Item` (line 195) and pill wrapper need `Layout` hints so GridLayout places them — add to `groupItem` (after line 201 `height: 26`): `Layout.alignment: Qt.AlignCenter`. (The nested pill `Row` inside the tray is unaffected — pills within one output's tray always flow horizontally; only the per-output trays stack.)
337 +- [ ] **Step 6: Make the widgets zone orientation-aware**
339 +Replace the widgets `RowLayout { id: widgetsRow ... }` (lines 284-304) with:
340 +```qml
341 + // widgets zone: right edge (horizontal) / bottom edge (vertical).
342 + GridLayout {
343 + id: widgetsRow
345 + flow: root.vertical ? GridLayout.TopToBottom : GridLayout.LeftToRight
346 + anchors.right: root.vertical ? undefined : parent.right
347 + anchors.rightMargin: root.vertical ? 0 : 10
348 + anchors.bottom: root.vertical ? parent.bottom : undefined
349 + anchors.bottomMargin: root.vertical ? 10 : 0
350 + anchors.horizontalCenter: root.vertical ? parent.horizontalCenter : undefined
351 + anchors.verticalCenter: root.vertical ? undefined : parent.verticalCenter
352 + rowSpacing: 4
353 + columnSpacing: 4
355 + Repeater {
356 + model: root.usageService ? root.usageService.layoutOrder : []
358 + delegate: BarChip {
359 + required property var modelData
361 + popoutName: modelData
362 + label: root.vertical ? root.formatService.abbreviate(root.chipLabel(modelData)) : root.chipLabel(modelData)
366 +```
368 +- [ ] **Step 7: Restart and verify stacked geometry**
370 +```bash
371 +rm -rf ~/.cache/quickshell/qmlcache
372 +systemctl --user restart quickshell
373 +sleep 2
374 +journalctl --user -u quickshell -n 80 --no-pager | grep -iE "error|typeerror" || echo "clean"
375 +qs ipc -c nuguland call nuguland setOrientation vertical
376 +sleep 1
377 +qs ipc -c nuguland call nuguland registeredAnchors
378 +```
379 +Expected: journal `clean`; in vertical, the widget chips in `registeredAnchors` share a near-constant `x` and increasing `y` (stacked), and each width is small (abbreviated 3-char labels). Toggle back to horizontal and confirm chips return to a shared `y`, increasing `x`. No commit.
381 +---
383 +## Task 4: Vertical stacked clock + overlap guard (Phase 1 commit)
385 +**Files:**
386 +- Modify: `quickshell/nuguland/Bar.qml`
388 +**Interfaces:**
389 +- Consumes: `root.chipLabel("clock")` (returns `"HH:MM"`), `root.vertical`.
390 +- Produces: a `clockStack` element registered under anchor name `"clock"`; existing `clockChip` hidden in vertical.
392 +- [ ] **Step 1: Gate the horizontal clock chip on horizontal mode**
394 +In the `BarChip { id: clockChip ... }` (line 158), add after `popoutName: "clock"` (line 161):
395 +```qml
396 + visible: !root.vertical
397 +```
399 +- [ ] **Step 2: Add the vertical stacked clock element**
401 +Immediately after the `clockChip` block closes (line 171), add:
402 +```qml
403 + // Vertical clock: HH over a thin accent rule over MM. The rule is a
404 + // Rectangle (geometry, not a glyph) so it always renders. Pinned at
405 + // bar centre on the y-axis, nudged up if the widgets need the room —
406 + // the y-axis twin of the horizontal clock's overlap guard.
407 + Rectangle {
408 + id: clockStack
410 + readonly property bool selected: root.surfaces && root.surfaces.popoutName === "clock"
411 + readonly property var clockParts: String(root.chipLabel("clock")).split(":")
412 + readonly property string hh: clockStack.clockParts[0] || "--"
413 + readonly property string mm: clockStack.clockParts[1] || "--"
415 + visible: root.vertical
416 + width: Math.max(34, stackColumn.implicitWidth + 12)
417 + height: stackColumn.implicitHeight + 12
418 + radius: 9
419 + anchors.horizontalCenter: parent.horizontalCenter
420 + y: Math.min(parent.height / 2 - height / 2, widgetsRow.y - height - 12)
421 + color: !root.theme ? "transparent" : (selected ? root.theme.ui.focus : root.theme.withAlpha(root.theme.ui.minor, 0.1))
422 + clip: true
423 + Component.onCompleted: Qt.callLater(() => root.registerAnchor("clock", clockStack))
424 + onXChanged: root.registerAnchor("clock", clockStack)
425 + onYChanged: root.registerAnchor("clock", clockStack)
426 + onWidthChanged: root.registerAnchor("clock", clockStack)
427 + onHeightChanged: root.registerAnchor("clock", clockStack)
429 + Column {
430 + id: stackColumn
432 + anchors.centerIn: parent
433 + spacing: 3
435 + NuguText {
436 + anchors.horizontalCenter: parent.horizontalCenter
437 + theme: root.theme
438 + variant: "meta"
439 + text: clockStack.hh
440 + color: !root.theme ? "transparent" : (clockStack.selected ? root.theme.content.backdrop : root.theme.content.normal)
443 + Rectangle {
444 + anchors.horizontalCenter: parent.horizontalCenter
445 + width: 16
446 + height: 2
447 + radius: 1
448 + color: root.theme ? root.theme.ui.accent : "transparent"
451 + NuguText {
452 + anchors.horizontalCenter: parent.horizontalCenter
453 + theme: root.theme
454 + variant: "meta"
455 + text: clockStack.mm
456 + color: !root.theme ? "transparent" : (clockStack.selected ? root.theme.content.backdrop : root.theme.content.normal)
460 + StateLayer {
461 + theme: root.theme
462 + checked: clockStack.selected
463 + onEntered: {
464 + if (root.surfaces)
465 + root.surfaces.hoverRegisteredPopout("clock");
467 + onActivated: {
468 + if (root.surfaces)
469 + root.activatePopout("clock");
473 +```
475 +- [ ] **Step 3: Restart and verify clock geometry + no overlap**
477 +```bash
478 +rm -rf ~/.cache/quickshell/qmlcache
479 +systemctl --user restart quickshell
480 +sleep 2
481 +journalctl --user -u quickshell -n 80 --no-pager | grep -iE "error|typeerror" || echo "clean"
482 +qs ipc -c nuguland call nuguland setOrientation vertical
483 +sleep 1
484 +qs ipc -c nuguland call nuguland registeredAnchors
485 +```
486 +Expected: journal `clean`. In `registeredAnchors`, the `clock` rect's `[y, y+height]` span does not intersect any widget rect's y-span, and its `x` is centered in the bar thickness. Ask the user to confirm the stacked `HH / line / MM` reads legibly.
488 +- [ ] **Step 4: Commit Phase 1**
490 +```bash
491 +git add quickshell/nuguland/shell.qml quickshell/nuguland/Bar.qml quickshell/nuguland/Format.qml niri/cfg/keybinds.kdl
492 +git commit -m "feat(nuguland): vertical bar layout — orientation flag, abbreviated labels, stacked clock
494 +Phase 1 of vertical/horizontal orientation. Bar anchors left with
495 +content-driven thickness in vertical mode; widgets stack top-to-bottom
496 +with vowel-dropped labels; workspace pills render idx-only; the clock
497 +stacks HH/MM around a thin accent rule with a y-axis overlap guard.
498 +Popout geometry still assumes a top bar (Phase 2).
500 +Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
501 +```
503 +---
505 +# Phase 2 — popout geometry
507 +## Task 5: SurfaceManager left-bar popout geometry
509 +**Files:**
510 +- Modify: `quickshell/nuguland/SurfaceManager.qml`
512 +**Interfaces:**
513 +- Consumes: 4th arg to `setPopoutScreen(width, height, barThickness, orientation)` (Bar already passes it from Task 3).
514 +- Produces: `orientation` property; `popupWindowAnchorRect`/`popupCardFrame`/`popoutWidth`/`heightBudget`/`clampedTarget`/`popoutState` emit left-edge geometry when vertical.
516 +- [ ] **Step 1: Add orientation property + readonly helper**
518 +After `property int barHeight: 34` (line 21), add:
519 +```qml
520 + property string orientation: "horizontal"
521 + readonly property bool vertical: orientation === "vertical"
522 +```
524 +- [ ] **Step 2: Accept orientation in setPopoutScreen**
526 +Replace `setPopoutScreen` (lines 229-234) with:
527 +```qml
528 + function setPopoutScreen(width, height, topBarThickness, orient) {
529 + screenWidth = Math.max(0, Number(width));
530 + screenHeight = Math.max(0, Number(height));
531 + barHeight = Math.max(1, Number(topBarThickness || barHeight));
532 + if (orient === "horizontal" || orient === "vertical")
533 + orientation = orient;
535 + return popoutState();
537 +```
539 +- [ ] **Step 3: Make the size budget swap axes in vertical**
541 +In `popoutWidth()` (lines 48-53), the popout width is bounded by the screen width minus the bar in vertical. Replace lines 48-53:
542 +```qml
543 + function popoutWidth() {
544 + const along = vertical ? Math.max(0, screenWidth - barHeight) : screenWidth;
545 + if (along <= 0)
546 + return 844;
548 + return Math.max(520, Math.min(920, Math.round(along / goldenRatio)));
550 +```
551 +In `heightBudget()` (lines 55-58), the constrained cross-axis is height minus bar in horizontal, full height in vertical. Replace:
552 +```qml
553 + function heightBudget(wanted) {
554 + const reserve = vertical ? 48 : barHeight + 48;
555 + const maxHeight = screenHeight > 0 ? Math.max(260, screenHeight - reserve) : 680;
556 + return Math.min(maxHeight, Math.max(220, Number(wanted)));
558 +```
560 +- [ ] **Step 4: Anchor the popup window beside the bar**
562 +Replace `popupWindowAnchorRect()` (lines 126-133):
563 +```qml
564 + function popupWindowAnchorRect() {
565 + if (vertical)
566 + return {
567 + "x": Math.max(1, Math.round(barHeight)),
568 + "y": 0,
569 + "width": 1,
570 + "height": screenHeight > 0 ? screenHeight : popoutContentSize(popoutName).height
571 + };
573 + return {
574 + "x": 0,
575 + "y": Math.max(1, Math.round(barHeight)),
576 + "width": screenWidth > 0 ? screenWidth : popoutContentSize(popoutName).width,
577 + "height": 1
578 + };
580 +```
582 +- [ ] **Step 5: Slide the card rightward from the left bar**
584 +Replace `popupCardFrame()` (lines 135-150):
585 +```qml
586 + function popupCardFrame(progress) {
587 + const t = Math.max(0, Math.min(1, Number(progress)));
588 + const contentSize = popoutContentSize(popoutName);
589 + if (vertical) {
590 + const surfaceHeight = screenHeight > 0 ? screenHeight : contentSize.height;
591 + return {
592 + "source": "left-bar-slide-fade",
593 + "progress": t,
594 + "currentRect": {
595 + "x": Math.round(barHeight - 18 + 26 * t),
596 + "y": Math.max(8, Math.round((surfaceHeight - contentSize.height) / 2) + 8),
597 + "width": Math.max(1, Math.round(contentSize.width - 16)),
598 + "height": Math.max(1, Math.round(contentSize.height - 16))
599 + },
600 + "opacity": t
601 + };
603 + const surfaceWidth = screenWidth > 0 ? screenWidth : contentSize.width;
604 + return {
605 + "source": "simple-center-slide-fade",
606 + "progress": t,
607 + "currentRect": {
608 + "x": Math.max(8, Math.round((surfaceWidth - contentSize.width) / 2) + 8),
609 + "y": Math.round(barHeight - 18 + 26 * t),
610 + "width": Math.max(1, Math.round(contentSize.width - 16)),
611 + "height": Math.max(1, Math.round(contentSize.height - 16))
612 + },
613 + "opacity": t
614 + };
616 +```
618 +- [ ] **Step 6: Clamp on the cross-axis in vertical**
620 +`clampedTarget` (lines 236-257) clamps x against screen width. In vertical the free axis is y against screen height. Replace:
621 +```qml
622 + function clampedTarget(origin, contentSize) {
623 + const edges = [];
624 + if (vertical) {
625 + let y = Math.round(origin.y - contentSize.height / 2);
626 + if (y < 0) {
627 + y = 0;
628 + edges.push("top");
630 + if (screenHeight > 0 && y + contentSize.height > screenHeight) {
631 + y = Math.max(0, screenHeight - contentSize.height);
632 + edges.length = 0;
633 + edges.push("bottom");
635 + return {
636 + "rect": { "x": Math.max(0, Math.round(barHeight)), "y": y, "width": contentSize.width, "height": contentSize.height },
637 + "edges": edges
638 + };
640 + let x = Math.round(origin.x - contentSize.width / 2);
641 + if (x < 0) {
642 + x = 0;
643 + edges.push("left");
645 + if (screenWidth > 0 && x + contentSize.width > screenWidth) {
646 + x = Math.max(0, screenWidth - contentSize.width);
647 + edges.length = 0;
648 + edges.push("right");
650 + return {
651 + "rect": { "x": x, "y": origin.y, "width": contentSize.width, "height": contentSize.height },
652 + "edges": edges
653 + };
655 +```
657 +- [ ] **Step 7: Make the origin and transition direction orientation-aware**
659 +In `popoutState()` (lines 337-374), replace the `origin` computation (lines 339-342) and the `transition.direction` (line 369). Replace `origin`:
660 +```qml
661 + const origin = vertical ? {
662 + "x": Math.round(popoutAnchor.x + popoutAnchor.width),
663 + "y": Math.round(popoutAnchor.y + popoutAnchor.height / 2)
664 + } : {
665 + "x": Math.round(popoutAnchor.x + popoutAnchor.width / 2),
666 + "y": Math.round(popoutAnchor.y + popoutAnchor.height)
667 + };
668 +```
669 +Replace the `transition` block's `direction` (line 369):
670 +```qml
671 + "direction": vertical ? (popoutClosing ? "left-out" : "right-in") : (popoutClosing ? "up-out" : "down-in"),
672 +```
674 +- [ ] **Step 8: Restart and verify popout geometry**
676 +```bash
677 +rm -rf ~/.cache/quickshell/qmlcache
678 +systemctl --user restart quickshell
679 +sleep 2
680 +journalctl --user -u quickshell -n 80 --no-pager | grep -iE "error|typeerror" || echo "clean"
681 +qs ipc -c nuguland call nuguland setOrientation vertical
682 +sleep 1
683 +qs ipc -c nuguland call nuguland openClock
684 +sleep 1
685 +qs ipc -c nuguland call nuguland popoutState
686 +```
687 +Expected: journal `clean`; `popoutState` JSON shows `popupCardFrame.currentRect.x ≈ barThickness` (not `y ≈ barHeight`), `popupAnchorRect.x ≈ barThickness` with full-height `height`, and `transition.direction` `"right-in"`. The card body still renders by `currentRect` (driven here); the host hit-region is fixed in Task 6. No commit.
689 +---
691 +## Task 6: PopoutHost input region + surface dims + slide (Phase 2 commit)
693 +**Files:**
694 +- Modify: `quickshell/nuguland/PopoutHost.qml`
696 +**Interfaces:**
697 +- Consumes: `surfaces.orientation` (alias `vertical`), `surfaces.barHeight` (bar thickness), `surfaces.popupCardFrame`/`currentRect` (already drives the card).
698 +- Produces: an input region and surface dimensions that match a left bar in vertical mode.
700 +- [ ] **Step 1: Add a vertical helper and fix surface dimensions**
702 +After `readonly property int surfaceHeight: ...` (line 49), add:
703 +```qml
704 + readonly property bool vertical: surfaces && surfaces.orientation === "vertical"
705 +```
706 +Replace `surfaceWidth`/`surfaceHeight` (lines 48-49) so the bar is subtracted on the correct axis:
707 +```qml
708 + readonly property int surfaceWidth: surfaces && surfaces.screenWidth > 0 ? (root.vertical ? Math.max(1, surfaces.screenWidth - surfaces.barHeight) : surfaces.screenWidth) : contentSize.width
709 + readonly property int surfaceHeight: surfaces && surfaces.screenHeight > 0 ? (root.vertical ? surfaces.screenHeight : Math.max(1, surfaces.screenHeight - surfaces.barHeight)) : contentSize.height
710 +```
711 +(Note: `root.vertical` is declared after these lines; QML property bindings resolve lazily by id, so forward reference is fine. If the linter complains, move the `vertical` declaration above line 48.)
713 +- [ ] **Step 2: Move the input region origin beside the bar**
715 +Replace the `popoutInputRegion` Item (lines 117-124):
716 +```qml
717 + Item {
718 + id: popoutInputRegion
720 + x: root.vertical && root.surfaces ? root.surfaces.barHeight : 0
721 + y: root.vertical || !root.surfaces ? 0 : root.surfaces.barHeight
722 + width: Math.max(1, parent.width - x)
723 + height: Math.max(1, parent.height - y)
725 +```
727 +- [ ] **Step 3: Restart and verify dismiss region + open direction**
729 +```bash
730 +rm -rf ~/.cache/quickshell/qmlcache
731 +systemctl --user restart quickshell
732 +sleep 2
733 +journalctl --user -u quickshell -n 80 --no-pager | grep -iE "error|typeerror" || echo "clean"
734 +qs ipc -c nuguland call nuguland setOrientation vertical
735 +sleep 1
736 +qs ipc -c nuguland call nuguland openClock
737 +```
738 +Expected: journal `clean`. Ask the user to confirm: in vertical, the popout opens to the RIGHT of the left bar (not under the top edge), slides in rightward, and clicking in the empty area to the right of the card dismisses it while clicking the bar does not. Then toggle to horizontal and confirm popouts still open below the top bar as before (regression check).
740 +- [ ] **Step 4: Commit Phase 2**
742 +```bash
743 +git add quickshell/nuguland/SurfaceManager.qml quickshell/nuguland/PopoutHost.qml
744 +git commit -m "feat(nuguland): vertical popout geometry — open beside the left bar
746 +Phase 2 of vertical/horizontal orientation. SurfaceManager emits
747 +left-edge popout geometry in vertical mode (anchor at bar thickness,
748 +full screen height, slide rightward, clamp on the y-axis); PopoutHost
749 +moves its input/dismiss region beside the bar. OSD/toast untouched
750 +(top-right, bar-independent).
752 +Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
753 +```
755 +---
757 +## Self-Review
759 +**Spec coverage:**
760 +- Orientation flag + IPC toggle → Task 1 ✓
761 +- niri keybind (user's test request) → Task 1 ✓
762 +- Content-driven vertical thickness → Task 3 Step 2 ✓
763 +- Widgets stack top-to-bottom → Task 3 Step 6 ✓
764 +- Vowel-drop abbreviate (user rule) + selftest → Task 2 ✓
765 +- Workspace pills idx-only in vertical → Task 3 Step 5 ✓
766 +- Stacked clock with thin-line separator → Task 4 ✓
767 +- Vertical clock overlap guard (y-axis twin) → Task 4 Step 2 ✓
768 +- SurfaceManager left-bar geometry → Task 5 ✓
769 +- PopoutHost input region + slide → Task 6 ✓
770 +- OSD/toast untouched → not modified in any task ✓
771 +- Two commits, one per phase → Task 4 Step 4, Task 6 Step 4 ✓
773 +**Type/name consistency:** `setOrientation`, `abbreviate`, `abbreviateSelfTest`, `registeredAnchors`, `popoutState`, `orientation`, `vertical`, `barContent`, `clockStack`, `widgetsRow`, `workspaceStrip`, `formatService`, `format` used consistently across tasks. `setPopoutScreen` 4-arg signature: Bar passes it (Task 3 Step 3), SurfaceManager accepts it (Task 5 Step 2) — extra arg ignored in between (safe).
775 +**Open risk flagged for review:** Task 2 introduces `Format.qml` rather than a Bar method, because the IPC handler needs a stable handle and the Bar has no id (it is a `Variants` delegate). This keeps `abbreviate` testable without per-screen Bar plumbing. If the reviewer prefers the function on the Bar, the IPC would need a `Variants`-safe Bar reference — more code for the same result.