# 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, dense view uses the animation library's source syntax colors, aligned instruction cells, operand values, flag marks, pointer colors, telescope chains, stack roles, frame spans, byte rows, and minimap strokes. Source runs line up with their machine instructions; the gold thread connects the active run to the PC. Changed registers, stack words and bytes strike, cool, and retain a corner mark. Click an address for an animated memory lens; right-click to follow its meaning. 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. Colon opens the debugger command bar; 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 goto memory 0x12345678 ``` `break` accepts the library's function, file:line and `*address` forms. Its reply includes the breakpoint ID. The icon buttons have hover labels and keys; pane headers hold history, follow, minimap and interpretation controls. | Keys | Action | | --- | --- | | `s`, `n` | One instruction / next source line (enters calls) | | `c`, `Esc` or `Ctrl-c` | Continue / pause | | `j` / `k`, `Ctrl-d` / `Ctrl-u`, `gg` / `G` | Smooth scroll, half page, first / last row | | `h` / `l` | Inspect long source lines horizontally | | `Ctrl-w h/j/k/l`, `Tab` | Focus a pane | | `Ctrl-o` / `Ctrl-i`, Mouse4 / Mouse5 | Back / forward in the hovered or focused pane | | `[` / `]`, `Shift-f` | Recorded stop history / latest live stop | | `f` | Follow the live address in the focused pane | | `v`, `m`, `a` | Source columns, minimap, operand annotations | | `b`, `z`, `?`, `:` | Break at PC, address lens, help, command line | Scrolling accepts fractional wheel deltas. Click or drag the actual-content minimap to move its viewport. Each pane's bounded jump history remembers address and scroll, and a new jump discards its forward branch. Browsing recorded state never rewinds the process. Continuing returns the moment selection to live. Source stepping may stay in a loop on one source line; pause with Esc / Ctrl-c. A right-click follows executable memory (including RWX) into disassembly, stack memory or a pointer-bearing word into the telescope, and other memory into the hex view. Unknown bytes stay unknown. At a live stop this requests a bounded read-only capture; it never writes RIP or resumes the target. `goto code|stack|memory ADDRESS` selects a specific view. The first pass bounds views to 256 decoded instructions, 128 stack slots, and 128 hex rows; jump to another address to inspect further. A lens shows five real rows and follows further pointers when clicked. 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. `s` 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. ### JavaScript source beside JIT code V8 can emit GDB JIT ELF objects containing actual line tables. Run the fixture from its directory, using its **basename** (V8's dump filename embeds the script name and cannot contain directory separators): ```text launch /tmp/computeranim-v8-debug-remote/d8 --allow-natives-syntax --no-concurrent-recompilation --no-maglev --gdbjit --gdbjit-dump --gdbjit-dump-filter=jitWork --print-opt-code --print-opt-code-filter=jitWork jit.js ``` After reaching the generated-code breakpoint, import the emitted object: ```text symbols /tmp/elfdumpjitWork jit.js:3:170.o ``` Use the actual emitted filename. The shared debugger validates its executable sections against the stopped target and reuses the ELF/DWARF reader; inline DWARF strings do not require `.debug_str`. The import is committed as an inspection moment without moving the target. Source files are loaded with `std.Io` and cached with owned syntax data. Missing source is explicitly labeled. This is an explicit import of the current JIT object, not a watcher of the GDB JIT registration protocol. Import a fresh object after code regeneration; it must belong to the current process. No fabricated JS-to-instruction mapping is used. Split native V8 `.dwo` files are still needed for complete C++ debug info. Read-only capture and JIT source integration checks: ```sh python3 gui/test/inspection.py --d8 /tmp/computeranim-v8-debug-remote/d8 python3 gui/bench/steps.py --d8 /tmp/computeranim-v8-debug-remote/d8 --jit-source --out /tmp/ztrace-step-bench-source ```