Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ADR-0003: Text inspection as the primary debugging interface

Status: accepted

Context. A screenshot costs a model ~450–1600 tokens and requires “vision” to understand what is where. And exact sizes and the causes of a layout cannot be extracted from a picture.

Decision. A deterministic headless runtime and an action language (tree, tap, type, why, state, lint, expect). Mutating actions print a diff of the semantic tree. Tests (.vtest) and MCP use the same language. A bundled font makes layout identical on every machine.

Consequences. + a screen ≈ 100 tokens, an action ≈ 30; reproducible bugs and tests without an emulator. − the headless render is not pixel-identical to the platform; the final visual check happens on a device (plan: the same protocol over a WebSocket to the device).