valw/docs/superpowers/specs/2026-10-03-valw-phase-5b-editor-design.md

# valw Phase 5b: editor text, pixelate, numbers, crop (design)

Date: 2026-10-03
Status: approved in brainstorming, pending written-spec review
Builds on: Phase 5a (`valw edit`), `docs/superpowers/specs/2026-10-02-valw-phase-5a-editor-design.md`

## 1. Goal

Finish the editor's tool set from vision 4.5: text, hiding sensitive
parts, numbered markers and crop, with the same guarantee as 5a: the
saved PNG is what the canvas shows.

### Out of scope

- Editing, moving or selecting finished shapes (text included).
- Blur (pixelate only), font choice, text background boxes.

## 2. Decisions

| Question | Decision | Why |
|---|---|---|
| Text editing | Place and type; Enter or a click elsewhere finishes; no re-editing (undo instead) | No selection model yet |
| Text look | Bold, chosen colour, thin dark outline; S/M/L = 16/24/36 px | Readable on any background |
| Font | DejaVu Sans Bold, vendored in `assets/fonts/` with its licence | Turkish glyphs, permissive licence, works without system fonts |
| Text rendering | Glyph outlines from `ab_glyph`, filled and stroked by tiny-skia | One renderer for canvas and export |
| Hiding | Pixelate only | Can't be undone by deblurring |
| Crop | Drag, adjust edges, Enter applies, Esc cancels; an undoable history step | User choice |

## 3. Behaviour

New tools, after the 5a ones in the toolbar: **Text (T), Pixelate (B),
Number (N), Crop (C)**. Ctrl+C stays Copy.

### 3.1 Text

- A click on the image starts a text at that point (its top-left).
  Typing inserts characters, Backspace deletes, Shift+Enter starts a new
  line, Enter or a press anywhere else finishes it. Esc while typing
  drops the text (and does not trigger the close flow).
- An empty text is discarded. While typing, the single-letter tool keys
  and Ctrl+Z/Ctrl+Y act on the text box only as text (letters) or not at
  all (Ctrl shortcuts are ignored until the text finishes).
- Look: the glyphs filled in the chosen colour over an outline in near
  black (`#1c1c1e` at 80 % opacity) of width `size / 8`, so it reads on
  light and dark backgrounds. White text gets the same dark outline.
- Size from the width control: S 16, M 24, L 36 px (image pixels); line
  height 1.2 × size; kerning from the font.
- A caret (a thin line after the last glyph) blinks while typing; it is
  never exported.

### 3.2 Pixelate

- Drag a rectangle (Shift: square). On release the area turns into
  blocks of S 8, M 12, L 20 px, aligned to the rectangle's top-left; each
  block takes the average colour (alpha included) of what is under it at
  that point in the history, so earlier shapes are pixelated too. Edge
  blocks are partial.
- A click (under 2 px) is discarded.

### 3.3 Numbers

- A click places a filled circle in the chosen colour with a white bold
  number centred in it. Diameter S 24, M 32, L 44 px; the number's size
  is 0.55 × diameter.
- The number is 1 + the count of numbers already in the document, so
  undo makes the next number reuse the freed one.

### 3.4 Crop

- Drag a rectangle: the outside darkens (50 % black over the canvas), the
  inside stays clear, with a 1 px white border. Dragging within 8 screen
  px of an edge or corner moves that edge (corners move two); the cursor
  shows the resize direction.
- Enter applies it, Esc cancels it (Esc then does not start the close
  flow). Switching tools cancels it.
- An applied crop is one history step: undo restores the previous view.
  The canvas shows only the cropped area, fitted as in 5a. Shapes keep
  their original image coordinates; drawing is clamped to the crop.
- A later crop happens inside the current one.
- Export: everything is drawn on the full image, then the last crop's
  rectangle is cut out. "Unsaved" compares the history including crops.

## 4. Structure

| File | Change |
|---|---|
| `assets/fonts/DejaVuSans-Bold.ttf`, `assets/fonts/LICENSE-DejaVu` | The vendored font |
| `src/editor/text.rs` (new) | The embedded font, layout (lines, advances, kerning), glyph outlines → tiny-skia paths, text width/height |
| `src/editor/shape.rs` | `Tool::{Text, Pixelate, Number, Crop}`; `Shape` gains the text payload; geometry for numbers |
| `src/editor/doc.rs` | History entries become `Item::{Shape(Shape), Crop(PixelRect)}`; `crop()`; next number |
| `src/editor/export.rs` | Text, pixelation, number glyphs; final crop |
| `src/editor/view.rs` | Fitting the crop rectangle instead of the whole image |
| `src/editor/mod.rs` | Text input, crop handles and keys, toolbar entries |

Dependency: `ab_glyph`.

## 5. Testing

Unit tests (`cargo nextest`):
- `text`: line breaking on `\n`, width grows with characters, kerning
  applied, Turkish letters (`ğüşıöçİ`) have glyphs, an empty string has no
  size.
- `export`: text pixels inside the glyph box use the colour; the outline
  darkens the edge; pixelation makes each block uniform with the block's
  average; a pixelate after a red line pixelates the line; a number draws
  a filled circle with white in its centre; a crop sets the output size
  and offset.
- `doc`: numbers count only `Number` shapes and follow undo; crops are
  undoable and nest; dirty includes crops.
- `view`: fitting a crop rectangle; screen ↔ image round trip with a
  crop.
- `mod`: the crop edge hit-test (edges, corners, inside, outside).

Manual checks go to the Phase 5b 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.