valw/docs/superpowers/specs/2026-10-02-valw-phase-5a-editor-design.md

valw Phase 5a: the built-in editor, basics (design)

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

1. Goal

Replace Satty with valw's own editor for everyday markup: click a preview thumbnail, draw arrows, boxes and highlights, save or copy, done. Phase 5b adds text, blur/pixelate, numbered markers and crop on top of this.

Success: the user can mark up a screenshot as fast as in macOS Markup, and what is saved is pixel-for-pixel what the canvas shows (at the image's own resolution).

Out of scope (5b or later)

• Text, blur/pixelate, numbered markers, crop (5b).
• Selecting, moving or editing a drawn shape; filled shapes; zoom inside the editor; a custom colour picker.

2. Decisions

Question	Decision	Why
Split	5a basics now, 5b afterwards, each with its own spec and plan	The editor is the largest phase; 5a is already usable on its own
Toolkit	eframe/egui with the glow backend (OpenGL ES through EGL), no Vulkan, no wgpu	Ready-made buttons, shortcuts and (for 5b) text input; a normal Wayland window
Process	valw edit <file>, its own process	Same as Satty today; the preview host stays small
Look	macOS Markup: one slim toolbar on top, the image large below	User choice
Ctrl+S	Overwrite the file; Ctrl+Shift+S saves a copy next to it	Like macOS; the preview already points at that file
Rendering	Shapes become shared geometry (polylines, polygons) in image pixels; egui draws it on screen, tiny-skia draws it for export	One geometry, two painters: the export matches the screen

3. Behaviour

3.1 Window

valw edit <file> opens a window titled <file name> — valw, app id valw-editor (for niri window rules). The image is fitted into the area below the toolbar, centred, never upscaled beyond 100 %. A file that can't be read is an error on stderr and exit code 1, before any window appears.

3.2 Toolbar (left to right)

Group	Items
Tools	Arrow, Rectangle, Ellipse, Line, Pen, Highlighter
Colour	red #ff3b30 (default), orange #ff9500, yellow #ffcc00, green #34c759, blue #007aff, black, white
Width	S 2 px, M 4 px (default), L 8 px (image pixels)
History	Undo, Redo (disabled when there is nothing to do)
Output	Copy, Save

The active tool, colour and width are highlighted. Default tool: Arrow.

3.3 Drawing

• Press, drag, release on the image creates one shape from the press point to the release point (Pen and Highlighter: every point on the way). A press outside the image does nothing; a drag that leaves the image is clamped to its edges.
• A shape whose drag is shorter than 2 image px (a click) is discarded, except for Pen, which keeps a dot.
• Shift while dragging: Line and Arrow snap to 45° steps; Rectangle and Ellipse become a square and a circle.
• Arrow: a line with a filled triangular head at the release point; the head grows with the width (length max(12, 4 × width), 30° half-angle).
• Rectangle and Ellipse: outlines only.
• Highlighter: the chosen colour at 40 % opacity, width × 4, round caps; drawn over everything below it.
• Width is in image pixels, so a 4 px arrow is 4 px in the saved file.

3.4 Keys

Key	Effect
A, R, O, L, P, H	Arrow, Rectangle, Ellipse (O), Line, Pen, Highlighter
Ctrl+Z	Undo
Ctrl+Shift+Z, Ctrl+Y	Redo
Ctrl+C	Copy the edited image to the clipboard
Ctrl+S	Save over the file
Ctrl+Shift+S	Save a copy: <stem> edited.png next to it (unique_path if taken)
Esc	Close; with unsaved changes the first Esc shows a bar "Unsaved changes — Esc to discard, Ctrl+S to save", the second closes

Closing the window (compositor close) with unsaved changes behaves like the first Esc: the bar appears and the window stays.

3.5 Undo

The document is the base image plus a list of shapes. Every finished shape pushes onto the list and clears the redo stack; undo moves the last shape to the redo stack, redo moves it back. Saving does not clear history. "Unsaved" means the shape list differs from what was last saved.

3.6 Save and copy

Export composites the shapes onto the base image at its full resolution with tiny-skia (anti-aliased), then encodes PNG with the existing output::encode_png.

• Save: output::write_atomic over the file; the window stays open.
• Save a copy: as above to the edited path; the window stays open.
• Copy: the existing clipboard path (output::copy_to_clipboard, which forks a server); the window stays open.
• Each prints a short status in the toolbar ("Saved", "Copied") for 2 s; a failure shows its message there instead and is logged.

3.7 Opening from the preview

The preview host reads [editor] backend when a thumbnail is clicked: "builtin" (default) runs valw edit <file> (the running executable), "satty" keeps today's Satty command. Unknown values are a config error.

4. Structure

File	Role
src/editor/mod.rs	run(path): load, start eframe, the App (toolbar, canvas, keys, status bar)
src/editor/doc.rs	Doc (base image, shapes, redo stack, saved marker): add / undo / redo / dirty
src/editor/shape.rs	Tool, Shape, Style; constraints (Shift), shape → Geometry (polylines and polygons in image px)
src/editor/export.rs	Geometry → pixels with tiny-skia; edited_path
src/editor/view.rs	Fit the image into the canvas: image ↔ screen transforms
src/config.rs	[editor] backend = "builtin" | "satty"
src/host.rs	open_editor picks the backend
src/main.rs	Command::Edit { file }
nix/package.ulu.nix	LD_LIBRARY_PATH gains wayland and libxkbcommon (winit loads them at run time)

Dependencies: eframe (default features off; glow, wayland, default_fonts), tiny-skia.

5. Testing

Unit tests (cargo nextest):

• shape: Shift snapping (angles, square, circle); the arrow head's size and direction; highlighter width and alpha; a click is discarded but a Pen dot is kept.
• doc: add / undo / redo order, redo cleared by a new shape, dirty after edits and clean after save, undo past a save makes it dirty.
• export: a red 4 px line on a white image has red pixels on the line and untouched pixels away from it; a highlighter over a known colour blends at 40 %; the output keeps the image size.
• view: fitting (never above 100 %, centred) and the round trip image → screen → image.
• edited_path: a.png → a edited.png, unique when taken.
• Config: [editor] backend default and the unknown-value error; the preview host's backend choice.

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