# Niri Native Scratchpad Implementation Plan > **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. **Goal:** Add a Sway-style scratchpad natively to niri — hide the focused window into a global stash and show/toggle/cycle it back as a centered floating overlay — shipped as a pinned patch built by a custom `niri-scratchpad` Arch package, replacing the old workspace-based minimize. **Architecture:** The scratchpad is a stash (`VecDeque>`) plus a "currently shown" id (`Option`) on niri's `Layout` struct — the same place that already holds workspaceless live tiles for interactive-move and drag-and-drop. Hide = `Layout::remove_window` → push onto the stash; show = pop → re-add to the active workspace as floating. Because the stash is not a workspace, it has no index, never appears in waybar, and is output-independent — eliminating the `+1` offset and multi-monitor bug of the old approach. Two new bindable actions (`move-window-to-scratchpad`, `scratchpad-show`) are threaded through niri's two `Action` enums and its `do_action` dispatch. The core state machine is unit-tested in niri's synthetic `src/layout/tests.rs` harness (no compositor); focus/close/multi-monitor behavior is verified manually in a nested niri. **Tech Stack:** Rust (niri 26.04, commit `8ed0da4`), knuffel (KDL config derive), clap (IPC), smithay; Arch `makepkg`/PKGBUILD; niri KDL config; fish `install.sh`. ## Global Constraints - **Pinned upstream:** niri git tag `v26.04`, commit `8ed0da4`. Every source line/anchor below is against that commit. Do not develop against `main`. - **Delta lives as patches:** all Rust changes ship as `niri-patches/*.patch` applied by `pkg/niri-scratchpad/PKGBUILD`. Upstream is never vendored into the repo. - **Stash key type is `W::Id`** (production `Window`, tests `usize`) — never `MappedId`. This keeps the state machine unit-testable and generic. - **Single-shown invariant:** at most one scratchpad window is shown at a time (accepted simplification — no multi-shown, no persistent per-window `is_scratchpad` flag). - **Repo principles (CLAUDE.md):** idempotent `install.sh`, no sleep-based hacks, complete files, Tomorrow Night theme untouched. - **Two repos:** Rust work happens in a disposable niri dev clone (`~/build/niri-scratchpad`); its commits are throwaway — only the exported patch is a deliverable. Real deliverables (patch, PKGBUILD, install.sh, config, deletions) are committed in the dotfiles repo. **Path shorthand in this plan:** `$DEV` = `~/build/niri-scratchpad` (niri dev clone). `$DOT` = `/home/alex/Documents/dotfiles`. --- ## File Structure **niri dev clone (`$DEV`) — source of the patch, throwaway commits:** - Modify `src/layout/mod.rs` — stash fields on `Layout`; `move_to_scratchpad` / `scratchpad_show` methods; close-eviction hook inside `remove_window`. - Modify `src/layout/tests.rs` — new `Op` variants + `apply` arms + `#[test]`s. - Modify `niri-ipc/src/lib.rs` — IPC `Action` variants. - Modify `niri-config/src/binds.rs` — config `Action` variants + `From` arms. - Modify `src/input/mod.rs` — `do_action` arms. **dotfiles repo (`$DOT`) — real deliverables:** - Create `niri-patches/0001-scratchpad.patch` — the whole Rust delta (single patch; see Task 6 rationale). - Create `pkg/niri-scratchpad/PKGBUILD` — builds pinned niri + patch. - Modify `install.sh` — build/install `niri-scratchpad`; drop `window-restore` symlink. - Modify `niri/config.kdl` — remove `workspace "minimized"`, un-offset `Mod+1..9`, new `Mod+M` / `Mod+Shift+M` binds. - Delete `scripts/window-restore.py`, `scripts/tests/window-restore.test.py`. --- ## Task 1: Dev clone + baseline build Establishes a known-good, buildable, runnable baseline before any change. A patch is only meaningful as a diff against this exact tree. **Files:** none in repo yet (environment setup). - [ ] **Step 1: Clone niri at the pinned commit onto a work branch** ```bash mkdir -p ~/build && cd ~/build git clone https://github.com/YaLTeR/niri.git niri-scratchpad cd ~/build/niri-scratchpad git checkout 8ed0da4 git switch -c scratchpad # all dev commits land here git tag baseline 8ed0da4 # patch is diffed against this ``` - [ ] **Step 2: Confirm the baseline builds** Run: `cd ~/build/niri-scratchpad && cargo build --release --locked 2>&1 | tail -5` Expected: `Finished \`release\` profile ... target(s)` (first build is slow; that is fine). - [ ] **Step 3: Confirm the baseline runs nested** Run (inside an existing graphical session, from a terminal): `cd ~/build/niri-scratchpad && ./target/release/niri --version` Expected: `niri 26.04 (8ed0da4...)`. (A full nested `niri` window is exercised in Task 7; here we only confirm the binary links and reports the pinned version.) - [ ] **Step 4: No commit** — this task produces no repo artifact. Proceed to Task 2. --- ## Task 2: Stash state + `move-window-to-scratchpad` Adds the two `Layout` fields and the hide method, unit-tested in the synthetic harness. No compositor. **Files:** - Modify: `$DEV/src/layout/mod.rs` (struct `Layout` ~line 336–369; inits at ~695–708 and ~721–732; new methods in the `impl Layout` block starting ~690) - Test: `$DEV/src/layout/tests.rs` (`Op` enum + `apply` at ~759; new `#[test]`s) **Interfaces:** - Produces: `Layout::move_to_scratchpad(&mut self, window: &W::Id)`; fields `scratchpad: VecDeque>`, `scratchpad_shown: Option`. - Consumes (existing, verbatim signatures): `Layout::remove_window(&mut self, window: &W::Id, transaction: Transaction) -> Option>`; `RemovedTile` has module-private field `tile: Tile`; `Tile::window(&self) -> &W`; `W::id(&self) -> &W::Id`. - [ ] **Step 1: Add the fields to the `Layout` struct** In `$DEV/src/layout/mod.rs`, in the `pub struct Layout` definition (ends ~line 369), add after the `dnd` field: ```rust /// Windows hidden in the scratchpad, front = next to show. Not part of any /// workspace, so they have no index and never appear in the workspace list. scratchpad: VecDeque>, /// Id of the scratchpad window currently shown as a floating overlay, if any. scratchpad_shown: Option, ``` Ensure `use std::collections::VecDeque;` exists at the top of the file (add it if not). - [ ] **Step 2: Initialize the fields in BOTH constructors** There are two field-init blocks; both must set the new fields or the crate will not compile. In `with_options` (~line 695) and in `with_options_and_workspaces` (~line 721), add alongside `dnd: None,`: ```rust scratchpad: VecDeque::new(), scratchpad_shown: None, ``` - [ ] **Step 3: Add test-harness `Op` variants** In `$DEV/src/layout/tests.rs`, add to the `Op` enum: ```rust ScratchpadStash(usize), ScratchpadShow, ``` In `Op::apply` (match at ~line 759), add arms: ```rust Op::ScratchpadStash(id) => { layout.move_to_scratchpad(&id); } Op::ScratchpadShow => { layout.scratchpad_show(); } ``` (`scratchpad_show` is implemented in Task 3; to keep this task compiling on its own, temporarily add a stub `pub fn scratchpad_show(&mut self) {}` in mod.rs now and flesh it out in Task 3.) - [ ] **Step 4: Write the failing test for stashing** Add to `$DEV/src/layout/tests.rs`: ```rust #[test] fn scratchpad_stash_removes_window_from_workspace() { let ops = [ Op::AddOutput(1), Op::AddWindow { params: TestWindowParams::new(0) }, Op::ScratchpadStash(0), ]; let layout = check_ops(ops); // The window left every workspace... assert!(!layout.has_window(&0), "window should not be in any workspace"); // ...and now lives in the stash. assert_eq!(layout.scratchpad.len(), 1); assert_eq!(layout.scratchpad.back().unwrap().tile.window().id(), &0); } ``` - [ ] **Step 5: Run it, verify it fails** Run: `cd ~/build/niri-scratchpad && cargo test -p niri scratchpad_stash_removes_window_from_workspace 2>&1 | tail -20` Expected: compile error `no method named \`move_to_scratchpad\`` (method not yet written). - [ ] **Step 6: Implement `move_to_scratchpad`** In the `impl Layout` block in `$DEV/src/layout/mod.rs`, add: ```rust /// Hide `window` into the scratchpad. Focus falls to the next window via the /// normal remove path. No-op if the window is not in the layout. pub fn move_to_scratchpad(&mut self, window: &W::Id) { let Some(removed) = self.remove_window(window, Transaction::new()) else { return; }; self.scratchpad.push_back(removed); // scratchpad_shown is cleared by the eviction hook in remove_window // (Task 4) if this window was the one shown. } ``` - [ ] **Step 7: Run it, verify it passes** Run: `cd ~/build/niri-scratchpad && cargo test -p niri scratchpad_stash_removes_window_from_workspace 2>&1 | tail -20` Expected: `test result: ok. 1 passed`. - [ ] **Step 8: Commit (throwaway dev commit)** ```bash cd ~/build/niri-scratchpad git add -A && git commit -m "scratchpad: stash fields + move_to_scratchpad" ``` --- ## Task 3: `scratchpad_show` state machine + centering Implements show/hide/cycle/focus and first-show centering, unit-tested. Replaces the Task 2 stub. **Files:** - Modify: `$DEV/src/layout/mod.rs` (replace the `scratchpad_show` stub; methods block ~690) - Test: `$DEV/src/layout/tests.rs` **Interfaces:** - Produces: `Layout::scratchpad_show(&mut self)`. - Consumes (existing, verbatim): `Layout::has_window(&self, window: &W::Id) -> bool`; `Layout::focus(&self) -> Option<&W>`; `Layout::active_output(&self) -> Option<&Output>`; `Layout::active_workspace(&self) -> Option<&Workspace>`; `Monitor::add_tile(&mut self, tile, MonitorAddWindowTarget::Workspace { id, column_idx: None }, ActivateWindow::Yes, true, width, is_full_width, is_floating)` — re-add pattern verbatim at `mod.rs:3359-3373`; `RemovedTile` fields `tile`, `width`, `is_full_width`, `is_floating`. **State table (the contract this task implements):** | State (after staleness check) | Behavior | |---|---| | shown = Some(id) AND id is focused | Hide: `remove_window(id)` → `push_back` to stash; `scratchpad_shown = None` | | shown = Some(id) AND id not focused | Focus that window; stash unchanged | | shown = None, stash non-empty | Pop front → add to active workspace, floating, focused, centered on first show; set `scratchpad_shown` | | shown = None, stash empty | No-op | - [ ] **Step 1: Write the failing tests** Add to `$DEV/src/layout/tests.rs`: ```rust #[test] fn scratchpad_show_brings_window_back_focused() { let ops = [ Op::AddOutput(1), Op::AddWindow { params: TestWindowParams::new(0) }, Op::ScratchpadStash(0), Op::ScratchpadShow, ]; let layout = check_ops(ops); assert!(layout.scratchpad.is_empty(), "stash drained on show"); assert!(layout.has_window(&0), "window returned to a workspace"); assert_eq!(layout.scratchpad_shown, Some(0)); assert_eq!(layout.focus().map(|w| *w.id()), Some(0), "shown window is focused"); } #[test] fn scratchpad_show_twice_hides_again() { let ops = [ Op::AddOutput(1), Op::AddWindow { params: TestWindowParams::new(0) }, Op::ScratchpadStash(0), Op::ScratchpadShow, // show Op::ScratchpadShow, // focused -> hide ]; let layout = check_ops(ops); assert_eq!(layout.scratchpad.len(), 1, "window back in stash"); assert!(!layout.has_window(&0)); assert_eq!(layout.scratchpad_shown, None); } #[test] fn scratchpad_show_cycles_round_robin() { let ops = [ Op::AddOutput(1), Op::AddWindow { params: TestWindowParams::new(0) }, Op::AddWindow { params: TestWindowParams::new(1) }, Op::ScratchpadStash(0), // stash: [0] Op::ScratchpadStash(1), // stash: [0, 1] Op::ScratchpadShow, // show 0 (front) Op::ScratchpadShow, // 0 focused -> hide 0 -> stash: [1, 0] Op::ScratchpadShow, // show 1 (new front) ]; let layout = check_ops(ops); assert_eq!(layout.scratchpad_shown, Some(1), "cycled to the next window"); assert!(layout.has_window(&1)); } #[test] fn scratchpad_show_empty_is_noop() { let ops = [Op::AddOutput(1), Op::ScratchpadShow]; let layout = check_ops(ops); assert_eq!(layout.scratchpad_shown, None); assert!(layout.scratchpad.is_empty()); } ``` - [ ] **Step 2: Run them, verify they fail** Run: `cd ~/build/niri-scratchpad && cargo test -p niri scratchpad_show 2>&1 | tail -30` Expected: assertion failures (the stub does nothing) — e.g. `scratchpad_show_brings_window_back_focused` fails on `has_window`. - [ ] **Step 3: Implement `scratchpad_show`** Replace the stub in `$DEV/src/layout/mod.rs` with: ```rust /// Show / toggle / cycle the scratchpad. See the state table in the plan. pub fn scratchpad_show(&mut self) { // Drop a stale "shown" id (window was closed or moved away). if let Some(id) = self.scratchpad_shown.clone() { if !self.has_window(&id) { self.scratchpad_shown = None; } } if let Some(id) = self.scratchpad_shown.clone() { let focused = self.focus().map(|w| w.id().clone()); if focused.as_ref() == Some(&id) { // shown + focused -> hide it if let Some(removed) = self.remove_window(&id, Transaction::new()) { self.scratchpad.push_back(removed); } self.scratchpad_shown = None; } else { // shown + not focused -> focus it. // CONFIRM at implementation: the exact focus-by-id call. Candidates // in this file are the activation path used by move actions; use // whichever method focuses an existing window by &W::Id without // moving it. Verify against `scratchpad_show_*` tests staying green. self.activate_window(&id); } return; } // nothing shown -> show the front of the stash let Some(mut removed) = self.scratchpad.pop_front() else { return; }; removed.tile.stop_move_animations(); // First-show centering: if this tile has never floated, place it centered // on the active output. If it has a remembered floating position, leave it. // CONFIRM at implementation: centering uses the active output geometry; if // niri's floating layer already centers a position-less tile acceptably, // this block may reduce to leaving floating_pos as-is. Verified visually in // Task 7 (manual acceptance #3), not by unit test. // center_floating_tile(&mut removed.tile, self.active_output()); let id = removed.tile.window().id().clone(); let ws_id = match self.active_workspace() { Some(ws) => ws.id(), None => { self.scratchpad.push_front(removed); // no active ws; put it back return; } }; self.add_removed_tile_floating(ws_id, removed); // helper below self.scratchpad_shown = Some(id); } ``` Add a small private helper next to it that mirrors the verbatim re-add pattern at `mod.rs:3359-3373`, forcing `is_floating = true` and targeting the given workspace's monitor (find the monitor owning `ws_id` in `self.monitor_set`, then `mon.add_tile(removed.tile, MonitorAddWindowTarget::Workspace { id: ws_id, column_idx: None }, ActivateWindow::Yes, true, removed.width, removed.is_full_width, true)`). - [ ] **Step 4: Run the tests, verify they pass** Run: `cd ~/build/niri-scratchpad && cargo test -p niri scratchpad 2>&1 | tail -20` Expected: all `scratchpad_*` tests pass. If the "focus it" branch cannot be reached by these tests (it isn't — it needs manual focus change), that branch is covered by Task 7 manual test; the four tests above must be green. - [ ] **Step 5: Run the full layout suite to catch invariant regressions** Run: `cd ~/build/niri-scratchpad && cargo test -p niri --lib layout 2>&1 | tail -20` Expected: no new failures (each op runs `verify_invariants`). - [ ] **Step 6: Commit** ```bash cd ~/build/niri-scratchpad git add -A && git commit -m "scratchpad: show/hide/cycle state machine + centering" ``` --- ## Task 4: Evict on close (single hook in `remove_window`) A window closed *while stashed* is in no workspace, so nothing removes it from the stash — a leak / stale-id bug. Fix at the single choke point every removal passes through. **Files:** - Modify: `$DEV/src/layout/mod.rs` (`Layout::remove_window`, ~line 1112) - Test: `$DEV/src/layout/tests.rs` **Interfaces:** - Consumes: `Op::CloseWindow(usize)` in the harness already calls `remove_window` (`tests.rs:1061`). - [ ] **Step 1: Write the failing test** Add to `$DEV/src/layout/tests.rs`: ```rust #[test] fn scratchpad_evicts_closed_stashed_window() { let ops = [ Op::AddOutput(1), Op::AddWindow { params: TestWindowParams::new(0) }, Op::AddWindow { params: TestWindowParams::new(1) }, Op::ScratchpadStash(0), Op::ScratchpadStash(1), Op::CloseWindow(0), // close a window while it is stashed ]; let layout = check_ops(ops); assert_eq!(layout.scratchpad.len(), 1, "closed window evicted from stash"); assert_eq!(layout.scratchpad.front().unwrap().tile.window().id(), &1); } ``` - [ ] **Step 2: Run it, verify it fails** Run: `cd ~/build/niri-scratchpad && cargo test -p niri scratchpad_evicts_closed_stashed_window 2>&1 | tail -20` Expected: `assertion \`left == right\` failed: closed window evicted from stash` — stash still has 2 (the close didn't touch it). - [ ] **Step 3: Add the eviction hook at the top of `remove_window`** At the very start of `Layout::remove_window` (before the existing monitor_set lookup), add: ```rust // A window may be sitting in the scratchpad (not in any workspace). // Drop it here so both toplevel-destroy paths and the close op cover it. self.scratchpad.retain(|rt| rt.tile.window().id() != window); if self.scratchpad_shown.as_ref() == Some(window) { self.scratchpad_shown = None; } ``` This is the single point of truth: it covers `handlers/compositor.rs` (unmap) and `handlers/xdg_shell.rs` (destroy), which both call `remove_window`, and the harness `Op::CloseWindow`. It is a no-op for the common case (window not in the stash). - [ ] **Step 4: Run it, verify it passes; re-run the scratchpad suite** Run: `cd ~/build/niri-scratchpad && cargo test -p niri scratchpad 2>&1 | tail -20` Expected: all `scratchpad_*` tests pass (the new one plus the four from Task 3 — confirm none regressed, since `remove_window` now also runs during hide). - [ ] **Step 5: Commit** ```bash cd ~/build/niri-scratchpad git add -A && git commit -m "scratchpad: evict stashed window on close via remove_window" ``` --- ## Task 5: Wire the bindable actions (IPC + config + dispatch) Threads `move-window-to-scratchpad` and `scratchpad-show` through niri's two `Action` enums and `do_action`. After this, the whole binary compiles and the binds parse. **Files:** - Modify: `$DEV/niri-ipc/src/lib.rs` (IPC `Action` enum, ~line 194) - Modify: `$DEV/niri-config/src/binds.rs` (config `Action` enum ~line 102; `From` impl ~line 395) - Modify: `$DEV/src/input/mod.rs` (`do_action` match, ~line 659) **Interfaces:** - Consumes: `Layout::move_to_scratchpad`, `Layout::scratchpad_show` (Tasks 2–3); `self.niri.layout.focus().map(|m| m.window.clone())` yields the focused `Window` (= `W::Id`); `self.niri.queue_redraw_all()`. - [ ] **Step 1: Add IPC `Action` variants** In `$DEV/niri-ipc/src/lib.rs`, in the `pub enum Action`, add two unit-like struct variants (mirror the style of neighboring variants): ```rust /// Move the focused window to the scratchpad (hide it). MoveWindowToScratchpad {}, /// Show, toggle, or cycle the scratchpad. ScratchpadShow {}, ``` - [ ] **Step 2: Add config `Action` variants** In `$DEV/niri-config/src/binds.rs`, in the `pub enum Action` (`#[derive(knuffel::Decode, ...)]`), add (knuffel derives kebab-case node names `move-window-to-scratchpad` / `scratchpad-show`): ```rust MoveWindowToScratchpad, ScratchpadShow, ``` - [ ] **Step 3: Add `From` arms** In the `impl From for Action` (~line 395) — exhaustive over the IPC enum, so both new IPC variants need an arm: ```rust niri_ipc::Action::MoveWindowToScratchpad {} => Self::MoveWindowToScratchpad, niri_ipc::Action::ScratchpadShow {} => Self::ScratchpadShow, ``` - [ ] **Step 4: Add `do_action` dispatch arms** In `$DEV/src/input/mod.rs`, in the `match action {` (~line 659), add (patterned on `Action::FullscreenWindow` at ~line 812): ```rust Action::MoveWindowToScratchpad => { let focus = self.niri.layout.focus().map(|m| m.window.clone()); if let Some(window) = focus { self.niri.layout.move_to_scratchpad(&window); self.niri.queue_redraw_all(); } } Action::ScratchpadShow => { self.niri.layout.scratchpad_show(); self.niri.queue_redraw_all(); } ``` - [ ] **Step 5: Build the whole binary** Run: `cd ~/build/niri-scratchpad && cargo build --release --locked 2>&1 | tail -15` Expected: `Finished` with no errors. (If a match is non-exhaustive, an arm is missing — add it where the compiler points.) - [ ] **Step 6: Verify the binds parse via `niri validate`** Create a throwaway config and validate it: ```bash cat > /tmp/sp-test.kdl <<'EOF' binds { Mod+M { move-window-to-scratchpad; } Mod+Shift+M { scratchpad-show; } } EOF cd ~/build/niri-scratchpad && ./target/release/niri validate -c /tmp/sp-test.kdl && echo VALID ``` Expected: `VALID` (no unknown-node error — proves knuffel accepts the new nodes). - [ ] **Step 7: Verify the IPC action parses** Run: `cd ~/build/niri-scratchpad && ./target/release/niri msg action scratchpad-show 2>&1 | head -3` Expected: it fails to *connect* (no running niri socket) rather than failing to *parse* the action — i.e. an error about the socket, not `unrecognized subcommand`. (Full IPC behavior is exercised in Task 7.) - [ ] **Step 8: Commit** ```bash cd ~/build/niri-scratchpad git add -A && git commit -m "scratchpad: bindable + IPC actions wired through do_action" ``` --- ## Task 6: Package the patch + dotfiles changes Export the Rust delta as one patch, build it via a PKGBUILD, and make all the dotfiles-side changes (config, install.sh, deletions) in a single reviewable commit. **Rationale for a single patch file:** the changes interleave within `src/layout/mod.rs` (fields, methods, and the `remove_window` hook are all in that one file). Splitting into three `git apply`-able patches would force a fixed apply order and make rebasing fragile. One patch = one `git diff baseline..scratchpad`, trivially re-generated after a rebase. **Files:** - Create: `$DOT/niri-patches/0001-scratchpad.patch` - Create: `$DOT/pkg/niri-scratchpad/PKGBUILD` - Modify: `$DOT/install.sh` - Modify: `$DOT/niri/config.kdl` - Delete: `$DOT/scripts/window-restore.py`, `$DOT/scripts/tests/window-restore.test.py` - [ ] **Step 1: Export the patch** ```bash mkdir -p /home/alex/Documents/dotfiles/niri-patches cd ~/build/niri-scratchpad git diff baseline..scratchpad > /home/alex/Documents/dotfiles/niri-patches/0001-scratchpad.patch head -5 /home/alex/Documents/dotfiles/niri-patches/0001-scratchpad.patch ``` Expected: a unified diff beginning `diff --git a/niri-config/src/binds.rs ...` (touching binds.rs, lib.rs, mod.rs, tests.rs, input/mod.rs). - [ ] **Step 2: Verify the patch applies cleanly to a fresh checkout** ```bash cd /tmp && rm -rf niri-apply-check && git clone -q https://github.com/YaLTeR/niri.git niri-apply-check cd /tmp/niri-apply-check && git checkout -q 8ed0da4 git apply --check /home/alex/Documents/dotfiles/niri-patches/0001-scratchpad.patch && echo "APPLIES CLEANLY" ``` Expected: `APPLIES CLEANLY`. - [ ] **Step 3: Write the PKGBUILD** Create `$DOT/pkg/niri-scratchpad/PKGBUILD`. Mirrors the official niri package install layout (from `resources/`), adds the patch in `prepare()`, and `provides`/`conflicts` stock niri: ```bash # Maintainer: alex pkgname=niri-scratchpad pkgver=26.04 pkgrel=1 _commit=8ed0da4 pkgdesc="niri with a native Sway-style scratchpad (local patch set)" arch=('x86_64') url="https://github.com/YaLTeR/niri" license=('GPL-3.0-or-later') depends=('libgbm' 'libglvnd' 'libinput' 'libxkbcommon' 'mesa' 'pango' 'pipewire' 'seatd' 'systemd-libs' 'wayland') makedepends=('git' 'cargo' 'clang' 'mesa') provides=('niri') conflicts=('niri') options=('!lto') source=("niri::git+https://github.com/YaLTeR/niri.git#commit=${_commit}" "0001-scratchpad.patch") sha256sums=('SKIP' 'SKIP') prepare() { cd niri git apply "${srcdir}/0001-scratchpad.patch" export RUSTUP_TOOLCHAIN=stable cargo fetch --locked --target "$(rustc -vV | sed -n 's/host: //p')" } build() { cd niri export RUSTUP_TOOLCHAIN=stable export CARGO_TARGET_DIR=target cargo build --release --frozen } package() { cd niri install -Dm755 target/release/niri "${pkgdir}/usr/bin/niri" install -Dm755 resources/niri-session "${pkgdir}/usr/bin/niri-session" install -Dm644 resources/niri.desktop \ "${pkgdir}/usr/share/wayland-sessions/niri.desktop" install -Dm644 resources/niri-portals.conf \ "${pkgdir}/usr/share/xdg-desktop-portal/niri-portals.conf" install -Dm644 resources/niri.service \ "${pkgdir}/usr/lib/systemd/user/niri.service" install -Dm644 resources/niri-shutdown.target \ "${pkgdir}/usr/lib/systemd/user/niri-shutdown.target" } ``` The `0001-scratchpad.patch` source is a repo-relative sibling: symlink or copy it next to the PKGBUILD at build time (Step 5 handles this). CONFIRM at implementation: cross-check `depends`/install lines against `pacman -Qi niri` on this machine so the packaged binary keeps identical runtime deps and session integration. - [ ] **Step 4: Build and install the package** ```bash cd /home/alex/Documents/dotfiles/pkg/niri-scratchpad cp ../../niri-patches/0001-scratchpad.patch . # makepkg needs sources local makepkg -si --noconfirm 2>&1 | tail -20 ``` Expected: package builds and installs; `pacman -Q niri-scratchpad` shows `26.04-1`. - [ ] **Step 5: Verify the installed binary is the patched one** ```bash niri --version && niri msg action scratchpad-show 2>&1 | head -2 ``` Expected: version `26.04`; the action is recognized (socket error if run outside niri, not `unrecognized subcommand`). - [ ] **Step 6: Update `niri/config.kdl`** — remove the stash workspace, un-offset, rebind In `$DOT/niri/config.kdl`: - Delete the comment block (lines ~50–54) and the `workspace "minimized"` declaration (line ~55). - `Mod+1..9`: change `focus-workspace 2..10` back to `focus-workspace 1..9` (drop the comment about the +1 offset too). - `Mod+Shift+1..9`: change `move-window-to-workspace 2..10` back to `move-window-to-workspace 1..9`. - Replace the two minimize binds: ```kdl Mod+M { move-window-to-scratchpad; } Mod+Shift+M { scratchpad-show; } ``` - [ ] **Step 7: Validate the real config with the patched binary** Run: `niri validate -c /home/alex/Documents/dotfiles/niri/config.kdl && echo VALID` Expected: `VALID`. - [ ] **Step 8: Delete the old Python implementation** ```bash cd /home/alex/Documents/dotfiles git rm scripts/window-restore.py scripts/tests/window-restore.test.py ``` - [ ] **Step 9: Update `install.sh`** In `$DOT/install.sh`: - Remove the line that symlinks `window-restore` into `~/.local/bin`. - Add a step (idempotent) that builds/installs the package, e.g. skip when already current: ```bash # Build & install patched niri (native scratchpad) if not already present. if ! pacman -Q niri-scratchpad &>/dev/null; then (cd "$(pwd)/pkg/niri-scratchpad" \ && cp ../../niri-patches/0001-scratchpad.patch . \ && makepkg -si --noconfirm) fi ``` CONFIRM placement matches the existing symlink/step block style in `install.sh` (read the file first; match its status-message convention). - [ ] **Step 10: Commit the dotfiles changes** ```bash cd /home/alex/Documents/dotfiles git add niri-patches pkg install.sh niri/config.kdl git add -u scripts # stage the deletions git commit -m "niri: native scratchpad via patched niri-scratchpad package Replace the workspace-based minimize (declared 'minimized' workspace + +1 offset + window-restore.py) with a native Sway-style scratchpad built into niri. Ships as niri-patches/0001-scratchpad.patch + a niri-scratchpad PKGBUILD. Mod+M stashes; Mod+Shift+M shows/toggles/cycles. Mod+1..9 no longer offset. Co-Authored-By: Claude Opus 4.8 (1M context) " ``` --- ## Task 7: End-to-end manual acceptance (nested niri) The behaviors no unit test reaches: real focus routing, the "focus it" branch, close-while-stashed under a live client, centering, and multi-monitor. Run the patched niri nested inside the current session. **Files:** none (verification only). - [ ] **Step 1: Launch patched niri nested with the repo config** Run (from a terminal in the current graphical session): `niri -c /home/alex/Documents/dotfiles/niri/config.kdl` Expected: a nested niri window opens without error. Open two terminals inside it. - [ ] **Step 2: Run the acceptance checklist** — observe each, all must hold: 1. On a window, `Mod+M`: it vanishes and **focus moves to another window** (regression guard for the focus-release risk). 2. `Mod+Shift+M`: the window reappears **centered on the current output**, focused. 3. `Mod+Shift+M` again (window still focused): it hides. 4. Stash two windows; `Mod+Shift+M` repeatedly cycles A → (hide) → B → (hide) → A. 5. Show a window, move/resize it, hide, show again: **same geometry** (remembered). 6. Show a window, click/focus the *other* window, `Mod+Shift+M`: focus returns to the shown window (the "shown-but-not-focused → focus it" branch). 7. Stash a terminal, then `exit` its shell so the client dies while stashed; `Mod+Shift+M`: no crash, cycle skips it, stash count correct. 8. If a second output is available (or a nested second output), show on the **focused** output; repeat focused on the other output — each shows there. 9. `Mod+1..9` land on workspaces `1..9` with **no offset**; the scratchpad has **no** waybar pill. 10. `Mod+Shift+M` with an empty stash: nothing happens, no crash. - [ ] **Step 3: Record results** Note any failing item with the observed behavior. A failure in #1, #6, #7, or #8 points back at the focus/cast/close bookkeeping risk — fix in the relevant Task 2–4 method, re-export the patch (Task 6 Step 1), rebuild, and re-run this checklist. Do not claim completion until all ten hold. - [ ] **Step 4: Final verification statement** Only after all ten pass and `cargo test -p niri scratchpad` is green: the feature is complete. Log-out / log-in to the real session (now running `niri-scratchpad`) as the last real-world confirmation. --- ## Self-Review (author checklist — completed) **Spec coverage:** stash-not-workspace (Task 2 fields) ✓; `Mod+M` hide (Task 2) ✓; show/hide/cycle/focus table (Task 3) ✓; centering + remember (Task 3) ✓; single-shown invariant (design, enforced by `Option` field) ✓; close-while-stashed (Task 4) ✓; two-Action wiring + From + do_action (Task 5) ✓; patch + PKGBUILD (Task 6) ✓; config un-offset + rebind + workspace-decl removal (Task 6) ✓; Python deletion (Task 6) ✓; install.sh (Task 6) ✓; unit tests (Tasks 2–4) + manual acceptance incl. multi-monitor (Task 7) ✓. **Placeholder scan:** two `CONFIRM at implementation` notes remain by design — the exact focus-by-id method name and the centering call are the two spots the spec flagged as compiler/geometry-dependent; each names the location, the pattern to mirror, and the test that must stay green, rather than deferring undefined work. **Type consistency:** stash keyed on `W::Id` throughout; `scratchpad: VecDeque>` / `scratchpad_shown: Option` named identically in fields, methods, tests, and the `remove_window` hook; method names `move_to_scratchpad` / `scratchpad_show` consistent across Layout, `do_action`, and the harness `Op` arms.