docs: spanning region spec

docs/superpowers/specs/2026-10-04-valw-spanning-region-design.md

@@ -0,0 +1,76 @@
+# valw: a region across monitors (design)
+
+Date: 2026-10-04
+Status: approved in brainstorming (transparent gaps), pending written-spec review
+Builds on: region mode (`src/region.rs`, `src/selection.rs`), capture (`src/main.rs`, `src/frame.rs`)
+
+## 1. Goal
+
+`valw region` today keeps a selection on the output where the drag
+started and clips it there. Let a drag carry on onto other outputs: each
+output shows its part of the selection, and the shot is one image of the
+whole rectangle, stitched from every output it covers.
+
+The user's layout: LVDS-1 1366×768 at (0, 0), HDMI-A-1 1920×1080 at
+(−277, −1080), both scale 1, so a box dragged from the laptop up onto the
+monitor is the main case.
+
+## 2. Behaviour
+
+- The selection lives in global logical coordinates (it already does);
+  Shift, Alt and Space keep working across outputs.
+- While dragging, every output whose area the rectangle touches shows its
+  part of it (bright inside, dimmed outside); the others stay fully dimmed.
+  Wayland keeps a drag's pointer events on the surface where it started,
+  with positions beyond its edges, so the global position is still
+  `start output origin + event position`.
+- The `W × H` label shows the size of the whole shot, next to the pointer,
+  on the output the pointer is over (found from the global position; when
+  it is over no output, on the nearest one).
+- On release:
+  - inside one output: exactly as today (`Choice::Region(output, rect)`,
+    opaque, the same pixels);
+  - across outputs: one image the size of the whole rectangle in physical
+    pixels at the largest scale among the outputs it covers; each output's
+    part is cropped from its frozen frame and placed at its offset
+    (resampled when that output's scale is smaller); areas that no output
+    covers are transparent (alpha 0). Everything else (sound, clipboard,
+    file, preview) as for any shot; the preview appears on the output the
+    pointer was over at release.
+- A drag smaller than the click threshold (`MIN_PIXELS`) in the whole
+  rectangle is still a click.
+
+## 3. Structure
+
+| File | Role |
+|---|---|
+| `src/selection.rs` | `span(a, b, outputs) -> Option<Span>`: the rectangle's parts per output (output index, its `PixelRect`, where it goes and at what size in the stitched image) and the image size; `locate(point, outputs)`: the output a global point is over (or the nearest) |
+| `src/stitch.rs` (new) | `stitch(frames, span) -> RgbaImage`: transparent canvas, each part's crop pasted (resized when needed) |
+| `src/region.rs` | every surface draws its part (`selection_on` no longer anchor-only), redraw only surfaces whose part changed; label on the pointer's output with the whole size; release returns `Choice::Region` for one output or `Choice::Span(Span, preview_output)` |
+| `src/main.rs` | `Choice::Span` → `stitch`, source = the preview output |
+
+## 4. Testing
+
+Unit tests (`cargo nextest`):
+- `span`: a rectangle inside one output → one part equal to today's `clip`;
+  the user's layout, a box from the laptop up onto the monitor → two
+  parts, their places, the image size; a box partly over no output → the
+  image is the whole box; mixed scales (1 and 2) → the image at scale 2,
+  the scale-1 part placed and sized ×2; nothing under `MIN_PIXELS` → None.
+- `locate`: a point on each output, in the gap (nearest output).
+- `stitch`: pixels land at the right offsets, gaps are alpha 0, covered
+  pixels alpha 255, a scaled part is resized to its target size.
+- region: the surface where the drag did not start draws its part; the
+  release decision (one output → `Region`, two → `Span`) as a pure function
+  of the corners and the outputs.
+
+Manual checks (a section in `docs/test-checklist.md`): drag from the laptop
+up onto the monitor and back, Shift/Alt/Space across the edge, the label on
+the right output with the whole size, the stitched PNG (gaps transparent,
+seams exact), preview on the release output, single-output shots unchanged.
+
+## 5. Definition of done
+
+`cargo clippy -- -D warnings`, `cargo fmt --check`, `cargo nextest run` and
+`nix flake check` pass; checklist updated; copland lock updated after the
+user's approval.