valw/docs/superpowers/specs/2026-10-03-valw-phase-6-toolbar-design.md

# valw Phase 6: the toolbar (design)

Date: 2026-10-03
Status: approved in brainstorming, pending written-spec review
Builds on: Phases 0–5 (on `main`); vision section 4.6

## 1. Goal

A Cmd+Shift+5-style bar: `valw toolbar` shows a floating bar at the
bottom of the focused output, the user picks a mode (and, if they like, a
timer, the cursor and the preview), and that mode runs as if started from
the command line.

Success: every mode starts from the bar with one click, the options are
remembered, and nothing of the bar or its countdown ends up in a shot.

### Out of scope

- A remembered region drawn on screen and a separate Capture button (the
  macOS "select, then capture" flow).
- Save-location choices; screen recording.

## 2. Decisions

| Question | Decision | Why |
|---|---|---|
| Flow | Clicking a mode starts it at once | Simple and fast |
| Options | Timer (None / 5 s / 10 s), Show cursor, Show preview | User choice |
| Rendering | A layer-shell surface drawn with tiny-skia and the editor's bundled font | Floats without niri rules; same stack as the overlay and preview; no new dependency |
| Memory | Last mode and options in `$XDG_STATE_HOME/valw/toolbar.toml` | The config may become a read-only home-manager file |

## 3. Behaviour

### 3.1 The bar

- A layer surface (namespace `valw-toolbar`, overlay layer, exclusive
  keyboard) covering niri's focused output. It is transparent except for
  the bar, which sits 24 logical px above the bottom edge, horizontally
  centred; covering the output is what lets a click beside the bar close
  it.
- Contents, left to right: **Screen**, **Window**, **Region**, a
  separator, **Zoom**, a separator, **Options ▾**. Labels in English,
  13 px, white; background `#1c1c1e` at 90 % opacity with 12 px corner
  radius; buttons 32 px tall with 12 px horizontal padding.
- The last used mode is highlighted (a lighter fill); the button under
  the pointer is highlighted more lightly.
- Drawn at the output's scale (buffer at physical size, viewporter to
  logical size), as the overlay does.

### 3.2 Options

**Options ▾** toggles a small menu above the bar, aligned to the button:

- Timer: None / 5 s / 10 s (one of three)
- Show cursor (check)
- Show preview (check)

Clicks in the menu change the option and keep the menu open. The options
apply only to captures started from the bar; the config is untouched.

### 3.3 Starting a mode

- A click on Screen, Window, Region or Zoom closes the bar (its surface is
  destroyed and the destruction flushed) and starts the mode with the
  options: Show cursor → `--cursor`; Show preview off → `--no-preview`.
- With a timer, a countdown pill (namespace `valw-countdown`, the same
  style, about 64 × 40 px, bottom-centred where the bar was) shows the
  seconds left, 5 → 1 (or 10 → 1), redrawn every second, and is destroyed
  before the mode starts so it is never captured. Esc during the
  countdown cancels (exit 3); the pill has exclusive keyboard focus.
- The chosen mode and options are saved before the mode starts.

### 3.4 Leaving

Esc, a click outside the bar and its menu, or the compositor closing the
surface: nothing is captured, exit code 3 (`Cancelled`), like Esc in
region mode.

### 3.5 Memory

`toolbar.toml` holds `mode` (`screen` | `window` | `region` | `zoom`),
`timer` (0, 5, 10), `cursor` and `preview` (booleans). Without a file the
defaults are: mode `region`, timer 0, `cursor = capture.show_cursor`,
`preview = preview.enabled` from the config. An unreadable or invalid file
logs a warning and uses the defaults; it is overwritten on the next save.

## 4. Structure

| File | Role |
|---|---|
| `src/toolbar/layout.rs` | Pure: button and menu rectangles from the measured label widths; `hit(point) -> Option<Target>` for the bar and the menu |
| `src/toolbar/state.rs` | `ToolbarState` load/save, defaults from the config |
| `src/toolbar/countdown.rs` | The countdown pill and its timing |
| `src/toolbar/mod.rs` | `run(wl, outputs, config) -> Result<Choice>`: the surface, drawing (tiny-skia + `editor::text`), input |
| `src/main.rs` | `Command::Toolbar`; the choice becomes `capture(mode, common)` |
| `src/wayland.rs` | Routing configure/pointer/keyboard/focus events to the toolbar |

## 5. Testing

Unit tests (`cargo nextest`):
- `layout`: buttons in order, non-overlapping, centred; hits on each
  button, the separators (none), outside (none); menu rows' hits.
- `state`: defaults from the config, save/load round trip, a broken file
  falls back to the defaults, unknown keys are ignored.
- `countdown`: the sequence of numbers for 5 and 10 s, and that 0 means
  no countdown.
- `main`: the CLI parses `toolbar`; a choice maps to the right mode and
  flags.

Manual checks go to the Phase 6 section of `docs/test-checklist.md`.

## 6. Definition of done

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