# ztrace GUI A separate native application using **ztrace** for control and recordings and **canim / Sketchbook** for the view. The libraries stay where they are. It launches a real Linux x86-64 process, stops at breakpoints, steps, and browses recorded machine state. No gdb subprocess or browser frontend. The fixed view uses the animation library's instruction cells, operand values, flag marks, pointer colors, telescope chains, stack roles and frame spans. The current-instruction marker moves between rows; changed registers and stack words strike in vermilion, cool, then retain a corner marker. Those changes are computed from adjacent recorded moments. Build with the same Zig toolchain as the rest of computeranim; the sibling `sketchbook` and `pardes` checkouts are the existing renderer dependencies: ```sh cd gui zig build -Doptimize=ReleaseFast zig build test -Doptimize=ReleaseFast zig build run -Doptimize=ReleaseFast -- --fresh ``` The build installs `ztrace` alongside `ztrace-gui`; keep the two together. Backtick opens the renderer's console: ```text launch /absolute/path/to/program arguments break main continue break *0x12345678 clear 1 signal 0 interrupt stepi nextline ``` `break` accepts the library's function, file:line and `*address` forms. Its reply includes the breakpoint ID. F5 toggles continue/pause, F10 steps one instruction, F11 steps to another source line (one instruction when source is unavailable). The corresponding buttons work with the mouse. Left/right browse recorded moments; End returns to the latest stop. Browsing history does not rewind the process. Continuing returns the view to live state. Source stepping can stay in a loop on one source line; F5 interrupts it. The renderer already uses `pause` and `step` for its own timeline. The debugger's console names are `interrupt` and `nextline` to keep those separate. Do not use renderer playback to replay debugger commands. Without a launched target, `open /path/to/file.ztrace` views an existing recording. Live recordings remain at `/tmp/ztrace-gui-PID-TIMESTAMP.ztrace` after closing. Closing the GUI terminates the target it launched. Target stdin is `/dev/null`; its stdout and stderr go to the GUI's stderr. There is no terminal emulation. ## How it fits The GUI starts `ztrace serve RECORDING -- PROGRAM [ARGS]` with private pipes. A single controller thread owns every ptrace operation. A `std.Io.concurrent` reader feeds a bounded `std.Io.Queue`; `Debugger.on_wait` services that mailbox while the target runs. `Debugger.interrupt` requests SIGSTOP and suppresses its redelivery. Idle waits use `std.Io.sleep`, while fast steps briefly poll. Existing synchronous debugger callers retain their blocking wait. Replies are small newline-delimited JSON values (`src/trace/control.zig`). A `std.Io` task in the GUI reads replies into one mutex-protected latest snapshot. The draw loop never waits for ptrace. Each completed command flushes the existing recorder before publishing its stop; the GUI reopens that committed snapshot and queries `Trace.moment`. File I/O, subprocesses, queues, tasks, locks and timing use `std.Io`. Raw Linux calls remain at the ptrace/signal and descriptor boundaries. New executable mappings are refreshed when a stop's PC is previously unknown, so code produced by a JIT is recorded without tracing every syscall. Entering code without source lines clears the previous source location in the recording. The GUI uses bounded moment queries rather than indexing an entire animation recording. It draws the existing canim components without requiring an animation timeline. ## Debug V8 Build V8 on `chaincli-box`, using the `v8-remote-build` skill. Copy d8 together with its shared libraries, data/snapshots and build flags to the workstation. See [the measured run](bench/RESULTS.md) for the exact revision and limitations. For the deterministic JIT fixture: ```sh ./zig-out/bin/ztrace-gui --fresh \ --console 'launch /tmp/computeranim-v8-debug-remote/d8 --allow-natives-syntax --no-concurrent-recompilation --no-maglev --print-opt-code --print-opt-code-filter=jitWork /absolute/path/to/computeranim/gui/targets/jit.js' \ --console continue 2>/tmp/ztrace-jit.log ``` `%SystemBreak()` first stops in V8's native runtime after optimizing `jitWork`. Find the address of `addl r8,r11` in its printed TurboFan loop body. In the GUI console, enter `signal 0`, `break *ADDRESS`, then `continue`. This second stop is a software breakpoint inside the generated JavaScript code, not the runtime trap. F10 steps through that machine code. Addresses change on each launch. The benchmark checks both RIP and that it belongs to an anonymous executable map. ```sh # From the repository root, after building gui/: python3 gui/bench/steps.py --d8 /tmp/computeranim-v8-debug-remote/d8 ``` The script builds a small C control, tests the JIT breakpoint, steps each target 1,000 times with identical capture settings, and writes recordings, target logs and `results.json` under `/tmp/ztrace-step-bench`. `capture` includes ptrace, register/stack/telescope/disassembly capture and recording flush; `roundtrip` also includes pipe transport and the Python driver. Neither measures display presentation latency. First-break timing includes target startup and initial symbol work. Debugger builds use ReleaseFast; target builds remain Debug. ## First-pass boundaries Fixed layout, one launched target, selected stopped thread, address/function breakpoints, and machine-state history. There is no attach UI, thread picker, expression evaluator, reverse execution or JavaScript source-map integration. Launch arguments are whitespace-separated (no shell quoting). V8 JIT names/code movement are not registered automatically: this fixture obtains the address from V8's own disassembly and stops before using it. Breakpoints are not relocated if V8 moves or discards generated code. Split DWARF files and V8 source must be retrieved separately for full C++ local inspection. The current renderer is a canvas with keyboard controls; it does not yet expose debugger rows through a native accessibility tree.