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):**
23 +rm -rf ~/.cache/quickshell/qmlcache
24 +systemctl --user restart quickshell
26 +journalctl --user -u quickshell -n 60 --no-pager
| grep -iE
"error|warning|typeerror" || echo "clean" 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.
41 +#
Phase 1 — bar visual 43 +##
Task 1: Orientation flag, IPC, keybind, verification scaffolding 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`
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:
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"
62 +- [ ] **Step 2: Add IPC functions**
64 +In the `IpcHandler` whose `target: "nuguland"` (the block starting line 593), after `niriSelfTest()` (ends line 604), add:
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;
76 + function registeredAnchors() : string {
77 + return surfaceManager.registeredAnchors();
80 + function popoutState() : string {
81 + return surfaceManager.popoutState();
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:
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"
94 +- [ ] **Step 4: Restart and verify IPC**
97 +rm -rf ~/.cache/quickshell/qmlcache
98 +systemctl --user restart quickshell
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
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**
111 +niri msg action load-config-file
2>/dev/null
|| true
113 +Press `Mod+Shift+O`, then:
115 +qs ipc -c nuguland call nuguland setOrientation toggle
117 +Expected: the call returns whichever value is now current (confirms the keybind flipped it). No commit (accumulates into Phase 1).
121 +##
Task 2: abbreviate() pure function + selftest 124 +- Modify: `quickshell/nuguland/Bar.qml` (add function after `chipLabel`, line ~57)
125 +- Modify: `quickshell/nuguland/shell.qml` (add `abbreviateSelfTest` IPC)
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:
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() {
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}`);
164 + "pass": failures.length === 0,
165 + "failures": failures
170 +- [ ] **Step 2: Expose the selftest over IPC**
172 +In `shell.qml`, the `target: "nuguland"` handler, add after `popoutState()` (from Task 1):
174 + function abbreviateSelfTest() : string {
175 + return JSON.stringify(bar.abbreviateSelfTest());
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`:
182 +pragma ComponentBehavior: Bound
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() {
194 + "notify": "ntf", "code": "cod", "media": "med", "system": "sys",
195 + "audio": "aud", "power": "pwr", "idle": "idl", "tray": "try"
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 };
208 +In `shell.qml`, instantiate it near `Theme` (line 26):
210 + Format { id: format }
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:
216 + function abbreviateSelfTest() : string {
217 + return JSON.stringify(format.abbreviateSelfTest());
221 +- [ ] **Step 3: Restart and verify selftest**
224 +rm -rf ~/.cache/quickshell/qmlcache
225 +systemctl --user restart quickshell
227 +qs ipc -c nuguland call nuguland abbreviateSelfTest
229 +Expected: `{"pass":true,"failures":[]}`. No commit.
233 +##
Task 3: Bar orientation-aware layout (anchors, thickness, zones, vertical pills) 236 +- Modify: `quickshell/nuguland/Bar.qml`
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:
246 + required property string orientation
247 + readonly property bool vertical: orientation === "vertical"
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:
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).
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()
273 + right: !root.vertical
274 + bottom: root.vertical
278 +- [ ] **Step 3: Pass orientation + thickness to SurfaceManager**
280 +Replace `refreshSurfaceGeometry()` (lines 121-125) with:
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);
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:
295 + // accent edge: bottom hairline (horizontal) / right hairline (vertical)
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"
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:
311 + // workspace strip: left zone (horizontal) above the clock / top zone
312 + // (vertical) above the clock. GridLayout unifies row/column flow.
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
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:
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()
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:
341 + // widgets zone: right edge (horizontal) / bottom edge (vertical).
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
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)
368 +- [ ] **Step 7: Restart and verify stacked geometry**
371 +rm -rf ~/.cache/quickshell/qmlcache
372 +systemctl --user restart quickshell
374 +journalctl --user -u quickshell -n 80 --no-pager
| grep -iE
"error|typeerror" || echo "clean" 375 +qs ipc -c nuguland call nuguland setOrientation vertical
377 +qs ipc -c nuguland call nuguland registeredAnchors
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.
383 +##
Task 4: Vertical stacked clock + overlap guard (Phase 1 commit) 386 +- Modify: `quickshell/nuguland/Bar.qml`
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):
396 + visible: !root.vertical
399 +- [ ] **Step 2: Add the vertical stacked clock element**
401 +Immediately after the `clockChip` block closes (line 171), add:
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.
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
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))
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)
432 + anchors.centerIn: parent
436 + anchors.horizontalCenter: parent.horizontalCenter
439 + text: clockStack.hh
440 + color: !root.theme ? "transparent" : (clockStack.selected ? root.theme.content.backdrop : root.theme.content.normal)
444 + anchors.horizontalCenter: parent.horizontalCenter
448 + color: root.theme ? root.theme.ui.accent : "transparent"
452 + anchors.horizontalCenter: parent.horizontalCenter
455 + text: clockStack.mm
456 + color: !root.theme ? "transparent" : (clockStack.selected ? root.theme.content.backdrop : root.theme.content.normal)
462 + checked: clockStack.selected
465 + root.surfaces.hoverRegisteredPopout("clock");
469 + root.activatePopout("clock");
475 +- [ ] **Step 3: Restart and verify clock geometry + no overlap**
478 +rm -rf ~/.cache/quickshell/qmlcache
479 +systemctl --user restart quickshell
481 +journalctl --user -u quickshell -n 80 --no-pager
| grep -iE
"error|typeerror" || echo "clean" 482 +qs ipc -c nuguland call nuguland setOrientation vertical
484 +qs ipc -c nuguland call nuguland registeredAnchors
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**
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>" 505 +#
Phase 2 — popout geometry 507 +##
Task 5: SurfaceManager left-bar popout geometry 510 +- Modify: `quickshell/nuguland/SurfaceManager.qml`
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:
520 + property string orientation: "horizontal"
521 + readonly property bool vertical: orientation === "vertical"
524 +- [ ] **Step 2: Accept orientation in setPopoutScreen**
526 +Replace `setPopoutScreen` (lines 229-234) with:
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();
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:
543 + function popoutWidth() {
544 + const along = vertical ? Math.max(0, screenWidth - barHeight) : screenWidth;
548 + return Math.max(520, Math.min(920, Math.round(along / goldenRatio)));
551 +In `heightBudget()` (lines 55-58), the constrained cross-axis is height minus bar in horizontal, full height in vertical. Replace:
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)));
560 +- [ ] **Step 4: Anchor the popup window beside the bar**
562 +Replace `popupWindowAnchorRect()` (lines 126-133):
564 + function popupWindowAnchorRect() {
567 + "x": Math.max(1, Math.round(barHeight)),
570 + "height": screenHeight > 0 ? screenHeight : popoutContentSize(popoutName).height
575 + "y": Math.max(1, Math.round(barHeight)),
576 + "width": screenWidth > 0 ? screenWidth : popoutContentSize(popoutName).width,
582 +- [ ] **Step 5: Slide the card rightward from the left bar**
584 +Replace `popupCardFrame()` (lines 135-150):
586 + function popupCardFrame(progress) {
587 + const t = Math.max(0, Math.min(1, Number(progress)));
588 + const contentSize = popoutContentSize(popoutName);
590 + const surfaceHeight = screenHeight > 0 ? screenHeight : contentSize.height;
592 + "source": "left-bar-slide-fade",
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))
603 + const surfaceWidth = screenWidth > 0 ? screenWidth : contentSize.width;
605 + "source": "simple-center-slide-fade",
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))
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:
622 + function clampedTarget(origin, contentSize) {
625 + let y = Math.round(origin.y - contentSize.height / 2);
630 + if (screenHeight > 0 && y + contentSize.height > screenHeight) {
631 + y = Math.max(0, screenHeight - contentSize.height);
633 + edges.push("bottom");
636 + "rect": { "x": Math.max(0, Math.round(barHeight)), "y": y, "width": contentSize.width, "height": contentSize.height },
640 + let x = Math.round(origin.x - contentSize.width / 2);
643 + edges.push("left");
645 + if (screenWidth > 0 && x + contentSize.width > screenWidth) {
646 + x = Math.max(0, screenWidth - contentSize.width);
648 + edges.push("right");
651 + "rect": { "x": x, "y": origin.y, "width": contentSize.width, "height": contentSize.height },
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`:
661 + const origin = vertical ? {
662 + "x": Math.round(popoutAnchor.x + popoutAnchor.width),
663 + "y": Math.round(popoutAnchor.y + popoutAnchor.height / 2)
665 + "x": Math.round(popoutAnchor.x + popoutAnchor.width / 2),
666 + "y": Math.round(popoutAnchor.y + popoutAnchor.height)
669 +Replace the `transition` block's `direction` (line 369):
671 + "direction": vertical ? (popoutClosing ? "left-out" : "right-in") : (popoutClosing ? "up-out" : "down-in"),
674 +- [ ] **Step 8: Restart and verify popout geometry**
677 +rm -rf ~/.cache/quickshell/qmlcache
678 +systemctl --user restart quickshell
680 +journalctl --user -u quickshell -n 80 --no-pager
| grep -iE
"error|typeerror" || echo "clean" 681 +qs ipc -c nuguland call nuguland setOrientation vertical
683 +qs ipc -c nuguland call nuguland openClock
685 +qs ipc -c nuguland call nuguland popoutState
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.
691 +##
Task 6: PopoutHost input region + surface dims + slide (Phase 2 commit) 694 +- Modify: `quickshell/nuguland/PopoutHost.qml`
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:
704 + readonly property bool vertical: surfaces && surfaces.orientation === "vertical"
706 +Replace `surfaceWidth`/`surfaceHeight` (lines 48-49) so the bar is subtracted on the correct axis:
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
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):
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)
727 +- [ ] **Step 3: Restart and verify dismiss region + open direction**
730 +rm -rf ~/.cache/quickshell/qmlcache
731 +systemctl --user restart quickshell
733 +journalctl --user -u quickshell -n 80 --no-pager
| grep -iE
"error|typeerror" || echo "clean" 734 +qs ipc -c nuguland call nuguland setOrientation vertical
736 +qs ipc -c nuguland call nuguland openClock
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**
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>" 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.