valw/docs/superpowers/specs/2026-10-02-valw-phase-3-window-mode-design.md

# valw Phase 3: window mode (design)

Date: 2026-10-02
Status: approved in brainstorming, pending written-spec review
Builds on: Phase 0+1 (region/screen), Phase 2 (preview), drag-out (all on `main`)

## 1. Goal

Capture a single window the macOS way: `valw window` lets the user click a
window and saves exactly that window; in region mode, Space (before
dragging) switches to window mode, like the camera icon on macOS.

Success: any window (tiled or floating, partly covered or not) can be
captured with a click, and the shot then goes through the same save,
clipboard, preview and drag-out flow as every other capture.

### Out of scope (later polish phase)

- The size indicator (`640 × 480`) next to the cursor.
- Shift / Alt / Space modifiers while dragging a region.
- The window shadow option.
- A blue highlight on the window under the pointer (see 2).

## 2. Decisions

| Question | Decision | Why |
|---|---|---|
| Who picks the window | niri (`Request::PickWindow`) | niri 26.04's IPC reports positions only for floating windows (`tile_pos_in_workspace_view` is `None` for tiled ones), so valw can't hit-test or highlight tiled windows itself |
| Who renders it | niri (`Action::ScreenshotWindow` with an explicit `path`) | Exact window pixels even when covered, rounded corners and transparency kept, correct scale |
| How valw gets the pixels | niri writes a temporary PNG; valw waits for the `ScreenshotCaptured` event, decodes the file and deletes it | One path for every target (`--output`, `-`, `--clipboard-only`); the rest of the pipeline stays unchanged |
| Highlight | None; niri's pick cursor is the feedback | Not possible for tiled windows (see above) |

## 3. Flow of `valw window`

1. As today: load the config, take the capture lock, wait `--delay`, hide
   the thumbnails (`HideGuard`).
2. `niri::pick_window()` sends `Request::PickWindow`; niri changes the
   cursor and replies after the click. `None` (Esc) → `Cancelled`.
3. Open a second niri socket with `Request::EventStream` **before**
   asking for the screenshot, so the event can't be missed.
4. Send `Action::ScreenshotWindow { id: Some(id), write_to_disk: true,
   show_pointer: cursor, path: Some(tmp) }`, where `tmp` is
   `$XDG_RUNTIME_DIR/valw-window-<pid>.png` (absolute, as niri requires).
5. Read events until `Event::ScreenshotCaptured { path: Some(p) }` with
   `p == tmp`. A reader thread sends events over a channel; the main side
   waits at most 5 s, then fails with "niri did not deliver the window
   screenshot". `ScreenshotCaptured { path: None }` or another path is
   ignored (niri also reports other screenshots on the same stream).
6. Decode `tmp` into an `RgbaImage` and delete it (also on every error
   after step 4, through a drop guard).
7. The preview's output: the output of the window's workspace (from
   `Request::Workspaces`); if that is unknown, niri's focused output, as
   in screen mode.
8. Continue with the existing `save` → preview → clipboard steps, exactly
   as for a region shot.

Side effects owned by niri, accepted: niri sets the clipboard itself and
shows its own "Screenshot captured" notification (niri's `dbus` build).
valw then sets the clipboard again with the same image (when configured),
so the end state is unchanged. The notification's image may be gone,
since valw deletes the temporary file.

## 4. Space in region mode

- The overlay's keyboard handler: Space while no drag is in progress
  ends the overlay with the outcome "switch to window mode". Space during
  a drag does nothing (reserved for "move the selection" in the polish
  phase).
- `region::select` returns `enum Choice { Region(usize, PixelRect), Window }`
  instead of `Picked`.
- `main`: `Window` drops the frozen frames and the Wayland connection and
  runs steps 2–8 of section 3 in the same process (lock, delay and hidden
  thumbnails carry over; the delay is not applied twice).

## 5. Code layout

| File | Change |
|---|---|
| `src/niri.rs` | `pick_window()`, `screenshot_window(id, path, cursor)`, `wait_for_capture(...)`, `output_of(window, workspaces)`, `is_our_capture(event, path)` |
| `src/window.rs` (new) | steps 2–7: temporary path + drop guard, decode, returns `(RgbaImage, output name)` |
| `src/main.rs` | `Command::Window`, `Mode::Window`, `Choice::Window` from region |
| `src/region.rs` | `Choice`; `Overlay::switch_to_window()` (no-op while dragging) |
| `src/wayland.rs` | Space in `press_key` calls `switch_to_window` |
| `src/doctor.rs` | nothing new (the niri version check already covers the IPC) |

## 6. Testing

Unit tests (`cargo nextest`):
- `niri::is_our_capture`: our path → true; `None`, another path → false.
- `niri::output_of`: window on a workspace with an output → that name;
  no workspace, unknown workspace, workspace without output → `None`.
- `region`: Space before a press → `Window`; Space while dragging →
  nothing.
- `window`: the temporary file is removed when the guard drops.

Manual checks are appended to `docs/test-checklist.md` (tiled, floating,
covered, HiDPI/other monitor, Esc during the pick, `--cursor`, Space from
region mode, `--clipboard-only`, `-o -`).

## 7. Definition of done

`cargo clippy -- -D warnings`, `cargo fmt --check`, `cargo nextest run`
and `nix flake check` pass; the checklist section is written.