Debugger chrome: dock workspace, registers + pause/step, engine-equivalence + render-decode/mouse oracles (#53 slice 3, first artifact)

[InauguralPhysicist]

First artifact of #53 (fleet UI ladder rung 5, slice 3): a dock-workspace debugger chrome around the LCD — registers panel + pause/step — with the oracle set the issue prescribes. Disassembly/breakpoints and tile/VRAM/OAM viewers remain on #53.

What ships

• --debug opens the chrome (dock #848 from EigenScript main; dev-binary decoupled — see CI note): center = live LCD canvas, west = registers code_view + Pause/Run, Step-instr, Step-frame buttons. p/s/f keyboard equivalents; joypad keys still play the game while running. --break-cycle N auto-pauses at the first frame boundary ≥ N.
• src/debug.eigs — the engine side, headless-safe: debug_step_instr (the non-inlined, readable form of the hot-loop bodies), the canonical state dump (CYC/regs/FLAGS/IE IF/LCDC STAT LY DIV TIMA TMA TAC ROM + SERLEN/MEMSUM over all mutable memory), --dump-state, and --engine debug on the headless CLI.
• run_frame(cpu, mem) lifted out of the gfx loop (twin markers moved intact) — plain gfx mode and the chrome's RUN state now drive the identical inlined hot loop, once per 70224 T-cycles.

Oracles (all green)

1. Engine equivalence (tests/run_debug_equivalence.sh, in CI, runs on any pin): hot engine vs debug engine full-dump byte-diff at 500K cycles — identical including the memory hash — plus Blargg 06.gb driven entirely through the debug engine → Passed (~3s).
2. Chrome ≡ core: the chrome's pause dump at CYC=421368 byte-equals headless --cycles 421368 --dump-state (a frame boundary is an instruction boundary, so the bound reproduces exactly).
3. Render-decode (tests/run_debug_ui_oracle.sh): glyph atlas built from real rendered output (tests/atlas_app.eigs, never a golden image); the registers panel is decoded back out of window screenshots and byte-diffed against the core's stdout dump — 11/11 lines identical at every checkpoint.
4. Mouse oracle, real pointer via xdotool through the real flow: hover → click Step (CYC advances exactly one instruction, panel re-decodes identical), click-away on the LCD is inert, Run → Pause round-trip re-decodes identical.
5. Planted render fault: --plant-render-fault corrupts the panel while the dump stays truthful — caught.
6. Suites: check_twins, all unit tests, input-script smoke, Blargg instr/mem/interrupt timing suite, cpu_instrs aggregate, gfx smoke — green.
7. Canary (500K cpu_instrs, n=5 interleaved pairs, same binary, this box): branch median 1.146 MHz vs master 1.075 MHz — no regression; ~6% faster. Consistent with the L1i-bound canary profile: the big cold gfx block left module top-level for a function body, shrinking the main bytecode chunk. Reported as observed; not a tuned claim.

The mouse oracle caught its own first bug on first run: xdotool getwindowgeometry reports the frame origin under a reparenting WM, so every click landed one titlebar-height low (Step hit Frame). Fixed with xwininfo client coords, plus per-dump reason asserts so a mis-aimed click can never pass by coincidence. A second real find: app_loop runs the toolkit focus path and the app key handler, so space on a clicked (focused) button double-fired — pause moved to p and the controls drop focus after acting.

CI / pin note

Dock landed upstream after the v0.37.0 cut, so the chrome is dev-binary-only until the next release wave. tests/run_debug_ui_oracle.sh is self-arming: on the current pin the dock probe SKIPs it loudly; once the pin carries dock, every missing tool or display becomes a hard FAIL so the oracle cannot be silently dropped. The equivalence gate needs no lib/ui and runs in CI now. The devcontainer gains the X tooling (xdotool, x11-apps, x11-utils, python3-pil) so bump day needs no further change.

Part of #53 — does not close it.

🤖 Generated with Claude Code