verify

Apps here render via the kitty graphics protocol, so they can be verified

without a real terminal. Every verification is recorded: the harness in

tools/verify-recorder/ captures every frame the app emits, overlays your

inputs (click ripples, caption bar), encodes a video, and generates a summary

page. Do not hand-roll one-off pty scripts that only dump PNGs.

Writing a verification

Write a driver script (in /tmp is fine) using the checked-in package:

import sys
sys.path.insert(0, "<repo>/tools/verify-recorder")
from driver import Driver
from recorder import Recorder

rec = Recorder("wheel-pan", title="Wheel pan keeps cursor anchored")
d = Driver(["<repo>/engine/target/debug/typing"], rec,
           cols=120, rows=32, xpixel=1200, ypixel=800)

d.pump(3.0)                                  # pump between actions so frames arrive
rec.check("app painted", d.frame_size is not None, f"{d.frame_size}")
w, h = d.frame_size                          # REAL framebuffer size — always use this

d.text("hello", "type into editor")          # every input takes a description
d.click(w // 2, h // 3, "select the note")   # mouse coords are pixels (1016 mode)
d.wheel(w // 2, h // 2, down=True, n=3, description="scroll content")
d.pump(1.0)
rec.check("scroll redrew", len(rec.frames) > 40, f"{len(rec.frames)} frames")
rec.still("after-scroll")                    # named snapshot for the summary page

d.stop("ctrl+c")                             # or "ctrl+q" depending on the app
rec.finish()                                 # composites markers, encodes mp4, writes summary

• Driver spawns the argv in a pty (TERM=xterm-kitty, TIOCSWINSZ with pixel

dims, answers the \x1b[?1016$p mouse probe), decodes kitty a=T,f=32,o=z

frames, and feeds them to the recorder. Node apps: spawn

["npx", "tsx", "src/main.tsx", ...] with cwd= the package dir (tsx

resolves tsconfig from cwd; a wrong cwd silently drops jsx config).

• Input methods: key("enter"/"esc"/"ctrl+q"/"super+shift+z"), text,

click, press/drag/release (a drag needs all three — click sends

press+release together), move, wheel. Descriptions become the video

caption bar and the summary timeline — write what the step is testing.

• rec.check(name, ok, detail) for every assertion; rec.still(name) to pin

the current frame into the summary.

• Give checks real assertions (frame deltas, decoded pixel colors via

recorder.png_read(rec.frames[-1]["path"])) — the summary shows pass/fail.

Ending a verification (required)

rec.finish() prints the run dir and summary path. **Always end by opening

the summary in a split:**

pixel open file:///tmp/verify-runs/<name>-<stamp>/summary.html

That page is the deliverable: what was tested (clickable timeline that seeks

the video), the checks table, the stills, and the video of the whole run.

Watch out for FAIL rows before declaring the verification passed.

Gotchas

• The engine rounds the window down to the cell grid, so the framebuffer can

be narrower than the requested winsize. Take coordinates from

d.frame_size, never from the requested pixels, or clicks land ~5% off.

• Keep pumping after quit (d.stop does) or the exit is never observed.
• Escape must be kitty CSI-u (d.key("esc") handles it); a bare \x1b makes

the app swallow the next escape sequence as literal text.

• If a press lands on a node without handlers, the engine dispatches the click

at the release position — a missed drag can silently click something else.

• Hover state only updates on move events; end interactions with a move if

the screenshot should show hover styling.

• Apps taking a file path argv need an ABSOLUTE path (their cwd is the

package dir).

• Run artifacts live in /tmp/verify-runs/<name>-<stamp>/: frames/,

events.jsonl, run.json, verification.mp4, summary.html.