App Verifier

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.