valw/docs/superpowers/specs/2026-10-03-valw-polish-design.md

# valw polish phase (design)

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

## 1. Goal

Three finishing touches, in this order:

- **P1** Region selection: a size label next to the pointer and macOS's
  Shift / Alt / Space modifiers while dragging.
- **P2** An optional soft shadow around window shots.
- **P3** The combo shutter sound: escalating with quick successive shots,
  ending in an endlessly rising loop.

### Out of scope

The deferred minors in `docs/test-checklist.md` (they wait for the end
test pass). Nothing binds to Caps Lock (the user maps it to Ctrl).

## 2. P1: Region selection

### 2.1 Size label

While a selection is being dragged, a label shows its size in physical
pixels, `W × H` (the same numbers the saved PNG will have), in white
13 px text on a rounded `#1c1c1e` pill at 90 % opacity, 6 px padding.
It sits 16 logical px right of and below the pointer; if it would leave
the output it moves to the other side of the pointer (left and/or above).
It is drawn only on the output where the drag happens, and disappears
with the drag.

### 2.2 Modifiers while dragging

The selection is computed from the press point `a`, the pointer `p` and
the modifiers, as a pure function in `selection.rs`:

| Held | Effect |
|---|---|
| none | rectangle from `a` to `p` |
| Shift | only one dimension follows the pointer: the one that changes more in the first motion after Shift goes down; the other stays as it was when Shift was pressed. Releasing Shift returns to the plain rectangle |
| Alt (Option) | `a` is the centre: the rectangle spans `a ± (p − a)` |
| Space (held) | the whole rectangle moves with the pointer, keeping its size; on release the far corner follows the pointer again from where it is |

Shift and Alt combine (one dimension, from the centre). Space before a
drag still switches to window mode (Phase 3); Space during a drag now
moves the selection. Releasing the mouse button finishes the selection
with whatever modifiers are held.

The overlay learns the modifier state from the keyboard (SCTK
`update_modifiers`) and Space press/release events.

## 3. P2: Window shadow

`[capture] window_shadow = false` (default off). When on, a window shot
(Phase 3, from `valw window`, Space in region mode, or the toolbar) gets
a shadow before it is saved:

- The image is padded by 40 px on every side (transparent).
- The shadow is the window's own alpha (so it follows rounded corners),
  black at 50 % opacity, blurred with a radius of 20 px (three box blur
  passes approximating a Gaussian), offset 12 px down.
- The window is drawn over it unchanged.

The preview, clipboard and file all get the shadowed image (it has
alpha; Phase 3's preview already handles that).

## 4. P3: The combo sound

### 4.1 The sounds

All sounds are synthesised in code (no samples): 16-bit mono PCM at
44 100 Hz, written as WAV.

- **The shutter** (~150 ms): a short filtered noise click (5 ms attack,
  fast decay) followed after 60 ms by a second, softer and longer
  "shk" (noise through a gentle band-pass, 80 ms decay).
- **Shots 1–5**: the shutter played faster and higher: speed
  1.00, 1.12, 1.25, 1.40, 1.60 (resampled; shorter and brighter).
- **Shot 6**: the shutter at speed 1.80 followed by a Shepard-tone
  glide rising half an octave over 400 ms.
- **Shot 7**: the same shutter, then the glide continuing over the next
  half octave, so that its end equals the start of shot 6's glide.
- From then on shots alternate 6, 7, 6, 7…, which sounds like an endless
  rise. The Shepard tone is a sum of octave-spaced partials under a
  fixed bell-shaped loudness curve over log-frequency, so a whole-octave
  shift sounds identical.

### 4.2 The combo

- A shot's number is 1 + the previous one's, if the previous shot was
  less than `combo_reset_secs` ago (default 5); otherwise 1. After 7 it
  goes back to 6.
- The state (last number, last time) is a small file in
  `$XDG_RUNTIME_DIR` (`valw-combo`), so separate `valw` runs share it.
  A missing or unreadable file means number 1.

### 4.3 Playing

- The sound plays right after the screen was captured (before saving),
  for every mode that produces a shot (screen, `--all` once, region,
  window, zoom's `c`). Cancelled captures play nothing.
- The seven WAVs are written once to `$XDG_RUNTIME_DIR/valw-sound/`
  (regenerated if missing) and played by spawning `pw-play` (PipeWire)
  detached, with the volume from the config; valw doesn't wait for it.
  `pw-play` comes with the Nix package's `PATH`. If it can't be started,
  a warning is logged once per run and the capture goes on.

### 4.4 Settings

```toml
[sound]
enabled = true
volume = 0.6          # 0.0–1.0
combo_reset_secs = 5  # 1–60
```

The toolbar's Options menu gains **Play sound** (a check, remembered in
`toolbar.toml`, default from `sound.enabled`), which wins over the config
for captures started from the bar, like Show cursor.

## 5. Structure

| File | Change |
|---|---|
| `src/selection.rs` | modifier-aware selection: `Mods`, the Shift axis lock, centre and move |
| `src/region.rs` | modifiers, Space during a drag, the size label |
| `src/render.rs` | blending a small premultiplied label into the overlay buffer |
| `src/wayland.rs` | `update_modifiers` and Space release to the overlay |
| `src/shadow.rs` (new) | `add_shadow(&RgbaImage) -> RgbaImage` |
| `src/window.rs` / `src/main.rs` | apply the shadow when configured; play the sound after capture |
| `src/sound/` (new) | `synth.rs` (shutter, speed-up, Shepard glide, WAV), `combo.rs` (numbering and state file), `mod.rs` (cache + `pw-play`) |
| `src/config.rs` | `capture.window_shadow`, `[sound]` |
| `src/toolbar/*` | the Play sound option |
| `nix/package.ulu.nix` | `pipewire` on the wrapper's `PATH` |

## 6. Testing

Unit tests (`cargo nextest`):
- `selection`: plain, Shift locking each axis, Alt from the centre, Shift
  + Alt, Space moving and then resizing again, clipping to the output.
- the size label's placement near each edge and its text.
- `shadow`: output size, the shadow below the window (alpha > 0 under,
  ~0 far away), the window's own pixels unchanged, rounded corners
  followed.
- `synth`: lengths per speed, no clipping, the WAV header; the Shepard
  glide's end matching its start an octave apart (6's start = 7's end).
- `combo`: numbering 1…7 then 6, 7, 6; reset after the gap; a broken
  state file.
- config defaults and bounds; the toolbar's sound option.

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

## 7. Definition of done

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