# ztrace GUI A native, live Linux x86-64 debugger using **ztrace** for process control and recordings and **canim / Sketchbook** for rendering. Continue, pause, instruction step and source step operate on the running process. Each stop records a snapshot; browsing that history does not rewind execution. There is no gdb subprocess, browser frontend, or continuous instruction trace. ```sh cd gui zig build -Doptimize=ReleaseFast zig build test -Doptimize=ReleaseFast zig build run -Doptimize=ReleaseFast -- --fresh ``` Use the repository's Zig toolchain and existing sibling `sketchbook` and `pardes` checkouts (Sketchbook `d307463` or newer for native profiling and upload fixes). Keep the installed `ztrace` beside `ztrace-gui`. ## Controls Colon opens the debugger command bar; backtick opens the renderer console. ```text launch /absolute/path/to/program arguments break main continue restart break *0x12345678 clear 1 interrupt stepi nextline goto code 0x12345678 goto stack 0x12345678 goto memory 0x12345678 source-map /remote/build/source /local/source symbols /tmp/current-jit-object.o origin 0x12345678 lens 0x12345678 memory-format 8 hex ``` `break` accepts function, file:line and `*address` forms. `origin` retains the recorded source location of an originating JS instruction during a native transition. `source-map` resolves the longest matching directory prefix in the shared symbol library, both for live control and offline GUI source loading. Relative prefixes resolve against the debugger's working directory. | Keys | Action | | --- | --- | | `s`, `n` | Instruction / next source line (enters calls) | | `c`, `Esc` or `Ctrl-c` | Continue / pause | | `Shift-r` | Restart the launched program at entry | | `Ctrl-+` / `Ctrl-=` / `Ctrl--`, `Ctrl-0` | Font scale in 10% steps, 60–200%; reset | | `j` / `k`, `Ctrl-d` / `Ctrl-u`, `gg` / `G` | Scroll, half page, segment start / end | | `PageUp` / `PageDown` | Scroll the stacked page | | `h` / `l`, `Shift-h` / `Shift-l` | Source horizontal scroll / pane horizontal scroll | | `Tab`, `Ctrl-w h/j/k/l` | Focus pane | | `Ctrl-o` / `Ctrl-i`, Mouse4 / Mouse5 | Pane address history | | `[` / `]`, `Shift-f` | Recorded stop history / latest live stop | | `f` | Follow current live address in focused pane | | `p` | Search mapping names, addresses and permissions for the active pane | | `t`, `d` | Control-flow graph / unobserved opacity (25%, 50%, 75%, 100%) | | `v`, `m`, `a` | Source, minimap, operand annotations | | `b`, `z`, `?`, `:` | Break at PC, lens, help, command bar | Wide windows keep code beside registers and memory beside stack. Smaller windows stack these panes; wheel over a header/gutter or use PageUp/PageDown to reach them. Font scaling changes drawing scale, geometry, visible rows and pointer hit regions; it never changes the native window dimensions or backing size. Every new execution stop reveals PC and its source group. Nearby scrolling settles in 200 ms using elapsed time, including when the frame rate changes. Manual scrolling lasts until the next stop; an explicit address jump stays pinned until Follow is enabled. Stack, memory and disassembly navigation span the **entire selected mapping**. The thin right minimap rail maps its full address range. The adjacent content minimap compresses source-only gaps and unknown memory rows. `p` selects any mapping from the selected recording moment and adds the jump to that pane's history. At a live stop, navigation fetches only a bounded window (128 instructions or 2 KiB), without resuming the target or changing RIP. Historical views use recorded bytes only: uncaptured data remains unknown. Arbitrary x86 address jumps start decoding at the requested byte; instruction boundaries are only certain when supplied by recorded code, symbols or a known entry point. Click an address to open a connected lens. Further pointers keep their ancestors; a different pointer in a parent replaces its descendants. Each close button closes that lens and its children. Cycles, unreadable addresses and uncaptured historical bytes are labeled. Executable mappings open disassembly lenses. Wheel over a lens body to browse its segment; the original focus area stays bright while surrounding rows dim. Shift-wheel, headers and gaps scroll the lens chain. Right-click sends stack addresses to the stack pane and every other address to memory. Matching addresses get staggered background highlights: the selected occurrence appears first, followed by its peers. Lens ancestry keeps its connectors. Stack offsets use the same hover/click behavior as their storage addresses. Disassembly brackets also link simple 64-bit base/index/scale/displacement addresses, including `lea`, using the selected stop's registers only at its PC. RIP-relative and absolute addresses work on other rows too. Future/past register values, segment overrides and 32-bit addressing are not inferred. Truncated brackets have no hidden hit target. These links work in executable lenses too. Address values in the right-hand register hints use the same hover and mouse actions, at the displayed register width. Ordinary scalar hints stay inactive. Memory's two header controls choose 8/16/32/64-bit groups and hexadecimal, unsigned, signed or floating-point values (little endian). `memory-format SIZE FORMAT` sets byte sizes 1/2/4/8 and `hex`, `unsigned`, `signed` or `float` directly; floats require 4 or 8 bytes. Unknown bytes stay unknown; these controls only change rendering. Recognized pointer fields are clickable across all their bytes, including 8-bit view: left-click opens a lens; right-click opens stack or memory. Wide values remain reachable with Shift-h/l. Hex bytes have no persistent group background; hover and access highlights remain. Lenses keep an opaque reading surface, with a native GPU backdrop shader for edge refraction, subtle color separation and a cyan rim. A canvas-sized texture and one reusable lens snapshot are independent of font zoom and lens count. Non-GPU rendering keeps an opaque fallback. `set glass false` in the renderer console disables the effect. The graph uses recorded basic blocks and shared graph layout. It is scoped to captured code, not a complete static analysis of an entire executable. Gold marks PC; recent observed PCs are bright. Branch-target annotation is a prediction from the current flags. Dimming means **unobserved**, not proof an instruction was skipped: Continue does not record all intermediate execution. ## Natural V8 deoptimization Use the existing debug build on `chaincli-box`; see [results and provenance](bench/RESULTS.md). The local runtime, matching source and split DWARF now live in the ignored `.ws/v8-debug/` cache, which survives reboot. `targets/jit.js` warms `jitWork` with one object shape, then supplies another. It uses no optimization intrinsics, traps, engine patches or tier-disabling flags. ```sh # From the repository root, after building gui/: python3 gui/bench/steps.py --d8 .ws/v8-debug/runtime/d8 \ --source .ws/v8-debug/source --out /tmp/ztrace-natural-bench python3 gui/test/inspection.py --d8 .ws/v8-debug/runtime/d8 --source .ws/v8-debug/source ``` The harness waits for natural TurboFan code, imports the matching V8 GDB JIT ELF, stops at its wrong-map guard exit, verifies the originating return address at `v8::internal::Deoptimizer::New`, continues to `v8::internal::Runtime_NotifyDeoptimized`, and identifies the actual fallback by stepping into its dispatch handler. This revision resumed Ignition; another build may resume a different tier. The harness fails instead of relabeling it. For the interactive session, run from `gui/targets` with the script basename (V8 embeds that name in its JIT ELF dump filename): ```text launch ../../.ws/v8-debug/runtime/d8 --trace-opt --trace-deopt --trace-deopt-verbose --print-opt-code --print-opt-code-filter=jitWork --gdbjit --gdbjit-dump --gdbjit-dump-filter=jitWork jit.js break main continue clear 1 source-map ../../src ../../.ws/v8-debug/source/src break v8::internal::Deoptimizer::New break v8::internal::Runtime_NotifyDeoptimized continue ``` Ignore unrelated outer-loop deoptimizations. Use the printed `jitWork` TurboFan block containing the `wrong map` relocation to locate the generated exit and its guard. Import the dumped ELF whose executable section covers that exact code address using `symbols PATH` (multiple compilations produce multiple objects). Break at the exit, inspect the guard's code, set `origin GUARD_ADDRESS`, and continue to Deoptimizer::New. Its x86-64 `rdx` must equal that exit's recorded return PC. The guard maps to JS property access line 3; the shared exit stub's own line table can instead name the return statement. Addresses change each run. The harness in `bench/control.py` is the executable version of these checks. The toolbar's circular arrow, `Shift-r`, or `restart` relaunches the same executable and arguments, including after exit. It stops at entry with fresh breakpoints and JIT symbols; source-prefix mappings and display preferences are retained. Old recordings remain on disk, while pinned addresses, lenses and histories reset because addresses may change in the new process. ## Recording and boundaries `open PATH.ztrace` opens history without launching a target. Live recordings stay at `/tmp/ztrace-gui-PID-TIMESTAMP.ztrace` after closing. Closing the GUI terminates its launched target. Target stdin is `/dev/null`; stdout/stderr go to GUI stderr. Launch arguments are whitespace-separated, without shell quoting. A single controller thread owns ptrace; a mailbox services commands while the process runs. Stop replies follow recording flush; drawing reads committed snapshots without blocking on ptrace. Mappings refresh at each stop, including new non-code mappings. Inspection commits metadata/bytes without executing. `capture_ns` measures stop capture and flush separately from total command time. One launched process and selected stopped thread are supported. There is no attach UI, thread picker, expression evaluator or reverse execution. JIT ELF imports are explicit; breakpoints do not relocate when generated code moves. Retrieved split DWARF artifacts are available, but complete split-DWARF C++ local variable inspection is not implemented. The canvas has keyboard controls but still lacks a native accessibility tree for debugger rows. Native restart/zoom regression (requires a display): ```sh python3 gui/test/restart.py --native ``` This checks the actual SDL window dimensions across zoom levels, in addition to the headless checks included in `zig build test`. ## Frame profiling Tracy is optional and shared with Sketchbook. A normal build has no Tracy client. To measure native scrolling, lenses and live stepping: ```sh cd gui zig build -Doptimize=ReleaseFast -Dtracy=/absolute/path/to/tracy cd .. python3 gui/bench/frames.py --tracy /absolute/path/to/tracy --out /tmp/ztrace-frames # Repeat with --size 1440x900 or --size 800x700 --zoom 200. ``` The checkout needs `build-capture/tracy-capture` and `build-csvexport/tracy-csvexport`. The harness writes a reproducible input script, `.tracy` capture, event CSV and percentile summary. It excludes the first two seconds from warm interaction statistics. Host frame/presentation times include VSync and driver waits; GUI `draw` measures construction of drawing commands. Source loading and debugger transition capture have separate measurements in [the benchmark results](bench/RESULTS.md). Rebuild without `-Dtracy` for ordinary use.