valw/docs/superpowers/specs/2026-10-02-valw-phase-4-zoom-design.md

# valw Phase 4: zoom mode (design)

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

## 1. Goal

A woomer-like magnifier: `valw zoom` freezes the focused output and lets
the user zoom towards the pointer, pan, and spotlight an area, then either
leave or capture what they see.

Success: zooming and panning stay smooth (60 fps) on the user's Intel HD
4000 at 1920×1080, pixels stay crisp, and `c` hands a crop to the usual
save → preview → clipboard flow.

### Out of scope

- Zoom on every output at once, smooth (linear) filtering, several
  captures from one zoom session.
- Vulkan or wgpu (the user asked for no Vulkan).

## 2. Decisions

| Question | Decision | Why |
|---|---|---|
| Renderer | OpenGL ES 3.0 through EGL (`khronos-egl`, `wayland-egl`, `glow`) | No Vulkan; a single textured triangle doesn't need wgpu. A spike on the user's HD 4000 (Mesa, crocus) got GLES 3.0, a compiling `#version 300 es` shader, `MAX_TEXTURE_SIZE` 16384 and 61 fps at 1920×1080 on a layer surface |
| Wayland backend | `wayland-backend` with `client_system` (libwayland-client) for the whole program | EGL and `wayland-egl` need the C `wl_display*` and `wl_proxy*`; the API valw uses doesn't change |
| Output | The focused output only | Simple, like woomer |
| Filtering | Nearest | Crisp pixels for inspection |
| `c` | Crops the visible area of the original frame (native pixels), runs the normal capture flow, exits | Zoomed region select; no upscaled pixels |
| Esc / `q` | Leave without saving, exit code 0 | Leaving is the normal end of zoom, not a cancelled capture |

## 3. Behaviour

Start, as for the other modes: load the config, take the capture lock,
wait `--delay`, hide the thumbnails, capture niri's focused output (with
the cursor if `--cursor`/`show_cursor`). Then a full-screen layer surface
(namespace `valw-zoom`, overlay layer, exclusive keyboard) on that output
shows the frozen frame at 1×.

| Input | Effect |
|---|---|
| Wheel | Zoom towards the pointer: the frame point under the pointer stays put. One notch = one `zoom.scroll_step` (default 1.15); touchpad scrolling: one step per 15 logical px. Range 1×–32× |
| Left drag | Pan, 1:1 with the pointer |
| `f` | Flashlight on/off: outside a circle around the pointer the image is dimmed to 25 % brightness |
| Ctrl + wheel | Flashlight radius × / ÷ `scroll_step` (default `zoom.flashlight_radius` = 180 logical px, range 20–2000) |
| `0` | Back to 1× (animated) |
| `c` | Capture the visible area (see 2) and exit |
| Esc, `q` | Exit, nothing saved |

- The view never leaves the image: at 1× it is exactly the frame, and a
  zoomed view is clamped to the frame's edges.
- Zoom and reset animate: the shown scale and position approach their
  targets exponentially (about 90 % in 120 ms) and snap when close. Pan is
  immediate. Frames are drawn on frame callbacks only while something
  changes; an idle view draws nothing.
- The cursor is the default pointer; while panning it is `grabbing`.

## 4. Structure

| File | Role |
|---|---|
| `src/zoom/view.rs` | Pure view math: `View { scale, origin }` (origin = the frame pixel at the top-left of the screen), `zoom_at`, `pan`, `reset`, `clamp`, the animation step, `visible_rect(frame size) -> PixelRect`, scroll → zoom factor, flashlight radius bounds |
| `src/zoom/gl.rs` | EGL display/context/window surface on the layer surface, the texture upload, one shader program (fullscreen triangle; fragment shader maps screen → frame pixels, `texelFetch`/nearest, swizzles BGRX, flashlight dimming) |
| `src/zoom/mod.rs` | `run(wl, output, frame, config) -> Result<Option<PixelRect>>`: surface, input routing, the draw loop; `Some(rect)` for `c`, `None` for Esc/`q` |
| `src/wayland.rs` | `State::zoom`; pointer, axis, key and modifier events go to it while it is open |
| `src/main.rs` | `Command::Zoom`, `Mode::Zoom`; `None` returns `Ok(())` before saving |
| `src/config.rs` | `[zoom] scroll_step = 1.15`, `flashlight_radius = 180` |
| `src/doctor.rs` | A line for EGL + an OpenGL ES 3 config (`warn`, not `fail`, when missing: only zoom needs it) |
| `nix/package.ulu.nix` | `LD_LIBRARY_PATH` suffix with libglvnd (`libEGL.so.1`); Mesa's drivers come from `/run/opengl-driver` on NixOS |

A missing EGL/GLES 3 makes `valw zoom` fail with a clear error and the
hint to run `valw doctor`; the other modes don't touch EGL.

## 5. Testing

Unit tests (`cargo nextest`) for `view.rs`:
- `zoom_at` keeps the frame point under the pointer fixed (several
  scales, pointer at a corner and the centre).
- Scale is clamped to 1–32; at 1× the origin is 0,0; a zoomed origin is
  clamped to the frame edges; `pan` respects the same clamp.
- The animation reaches the target and then reports "idle".
- `visible_rect` at 1× is the whole frame; at 4× with a known origin it
  is the expected rectangle, rounded outwards and inside the frame.
- Scroll → factor for wheel notches and touchpad pixels; flashlight radius
  bounds.
- Config: the `[zoom]` defaults and overrides; doctor: the EGL line's
  levels.

The headless sway check keeps covering screencopy and the overlay, now on
`client_system`. Zoom needs a GPU, so it is checked by hand: the Phase 4
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.