From 7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 14:48:26 -0300 Subject: canim: animations of recordings, as a debugger's whole context with a lens beside it A package of its own (anim/), on sketchbook's anim module and pardes's syntax. A scene opens a recording, takes a cursor into it, and declares blocks that read the moment the cursor is at: the state column (registers each followed as a pointer and inked by where it points, the stack telescope, the backtrace), the program column (the whole source, the disassembly in address order, and the scene's lens: a node-link list over a hexdump of its heap, array cells, a call tree, a syscall crossing), and ties between them. Motion is a step told as a sentence (the line fires, its effects cascade a level at a time, the mark moves on last), timed by what the step contains; walk, hurry and sprint pace a loop. Five scenes from real recordings of fib, a linked list, a sort and syscalls. First drafts, by the agent's own handover: the frame of the design's second revision, the hexdump lens and the ties; no disassembly annotations, no gallery, scenes not yet reviewed against the mocks. --- anim/src/ties.zig | 139 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 anim/src/ties.zig (limited to 'anim/src/ties.zig') diff --git a/anim/src/ties.zig b/anim/src/ties.zig new file mode 100644 index 0000000..426a667 --- /dev/null +++ b/anim/src/ties.zig @@ -0,0 +1,139 @@ +//! Ties: one pane is a view of another, and a line between them says so. +//! Any component can say where a thing of its own is on screen (`anchor`: +//! a register's row, a word of memory, a node, the source's current line, +//! the pc's row), and `Ties`, added last, draws the connections between +//! places in different panels, routed along the gutters and never across +//! a panel's text: +//! +//! - standing ties, declared by the scene (the source line and the +//! instruction it is at: the gold thread); +//! - the step's link: from the register a step has just struck to the +//! row or node whose address it now holds, in the ink of where it +//! points. It draws after the strike and goes as the marks advance; +//! - a word a step wrote and the node it is part of: the bytes are the +//! cause, the idea drawn from them the effect. +//! +//! A tie arrives, stays and leaves in the theme's time (`time.link`). +const std = @import("std"); +const sk = @import("sketch"); +const anim = @import("anim"); +const zt = @import("ztrace"); +const ui = @import("ui.zig"); +const cursors = @import("cursor.zig"); +const contexts = @import("context.zig"); +const Recording = @import("Recording.zig"); +const theme = ui.theme; +const time = theme.time; +const Rect = ui.Rect; + +/// A thing with a place on screen. +pub const Place = union(enum) { + /// A register's value, by its place in `Regs.names`. + register: usize, + /// The word of memory at this address, wherever it is shown. + word: u64, + /// The object at this address, as an idea. + node: u64, + /// The source's current line; the disassembly's. + source, + pc, + + fn key(p: Place) u64 { + return switch (p) { + .register => |i| 1 << 60 | @as(u64, i), + .word => |a| 2 << 60 | (a & (1 << 60) - 1), + .node => |a| 3 << 60 | (a & (1 << 60) - 1), + .source => 4 << 60, + .pc => 5 << 60, + }; + } +}; + +/// What this frame's components have said so far, in canvas pixels: left, top, right, bottom. +/// shortcut: one table for the process, emptied by `Ties.draw`; a scene with two players at once wants it on the frame. +var table: [256]struct { key: u64, box: [4]f32 } = undefined; +var said: usize = 0; + +/// `r` (in `u`'s units) is where `place` is, this frame. +pub fn anchor(u: ui.Ui, place: Place, r: Rect) void { + if (said == table.len) return; + const a = u.at.xf.apply(.{ r.x, r.y }); + const b = u.at.xf.apply(.{ r.x + r.w, r.y + r.h }); + table[said] = .{ .key = place.key(), .box = .{ a[0], a[1], b[0], b[1] } }; + said += 1; +} + +fn find(place: Place) ?[4]f32 { + for (table[0..said]) |entry| if (entry.key == place.key()) return entry.box; + return null; +} + +pub const Ties = struct { + cursor: cursors.Cursor, + box: Rect = theme.canvas.stage, + /// Ties that stand for the whole scene. + standing: []const [2]Place = &.{.{ .source, .pc }}, + + pub fn draw(g: *const Ties, f: *sk.Frame, at: anim.Placed) void { + defer said = 0; + const now = g.cursor.now(at); + const rec = g.cursor.rec; + // In canvas pixels, `k` of them a unit: anchors come from panels anywhere. + var raw: ui.Ui = .{ .f = f, .at = at }; + raw.at.xf = .identity; + const k = at.scale; + // The gutter between the two columns, and the margin left of the program's. + const gutter = at.xf.apply(.{ theme.layout.state.x - 16 - g.box.x, 0 })[0]; + const margin = at.xf.apply(.{ -12, 0 })[0]; + + for (g.standing) |tie| { + const a = find(tie[0]) orelse continue; + const b = find(tie[1]) orelse continue; + // The gold thread: two views of where execution is, joined down the margin. + const lane = @min(margin, @min(a[0], b[0]) - 6 * k); + raw.arrow(&.{ .{ a[0], (a[1] + a[3]) / 2 }, .{ lane, (a[1] + a[3]) / 2 }, .{ lane, (b[1] + b[3]) / 2 }, .{ b[0], (b[1] + b[3]) / 2 } }, theme.mark(.current).solid, .{ .width = theme.stroke.rule * k, .head = null }); + } + if (!now.walking()) return; + // The step's link: the first register it struck that now holds + // the address of something on screen. It draws once the strike + // is in, and goes as the marks advance. + const leaves = 1 - std.math.clamp((now.time - now.plan.advance) / time.link.out, 0, 1); + const regs = (now.moment().regs(rec.tid) catch null) orelse return; + for (zt.Regs.names, 0..) |name, index| { + if (now.registerAge(index) != 0 or std.mem.eql(u8, name, "rip") or std.mem.eql(u8, name, "rsp") or std.mem.eql(u8, name, "rbp")) continue; + const value = regs.named(name) orelse continue; + const from = find(.{ .register = index }) orelse continue; + const to = find(.{ .node = value }) orelse find(.{ .word = value & ~@as(u64, 7) }) orelse continue; + const drawn = cursors.standard(std.math.clamp((now.since(.cpu, 0) - time.strike.in) / time.link.in, 0, 1)); + const color = contexts.ink(contexts.regionOf(now.moment(), value)); + const y = (from[1] + from[3]) / 2; + const to_y = (to[1] + to[3]) / 2; + // Out of the panel's edge, along the gutter, to the side of what it lands on. + const edge = find(.{ .register = 1 << 20 }) orelse from; + const lands_at = if (to[2] < gutter) to[2] + 2 * k else to[0] - 2 * k; + raw.faded(leaves).arrow(&.{ .{ edge[0], y }, .{ gutter, y }, .{ gutter, to_y }, .{ lands_at, to_y } }, color, .{ .width = theme.stroke.line * k, .head = .{ 12 * k, 10 * k }, .progress = drawn }); + // What it lands on answers with a frame. + if (drawn >= 1) raw.faded(leaves).frame(.{ .x = to[0] - 2 * k, .y = to[1] - 2 * k, .w = to[2] - to[0] + 4 * k, .h = to[3] - to[1] + 4 * k }, color, theme.stroke.rule * k); + break; + } + // A word written and the node it is part of: the bytes, then the idea. + for (rec.written(now.stops[1], now.stops[0])) |span| { + const word = find(.{ .word = span.addr & ~@as(u64, 7) }) orelse continue; + const node = for (table[0..said]) |entry| { + // The node whose bytes hold the word: nodes are sixteen bytes here. + if (entry.key >> 60 == 3 and (span.addr & (1 << 60) - 1) -% (entry.key & (1 << 60) - 1) < 16) break entry.box; + } else continue; + const drawn = cursors.standard(std.math.clamp(now.since(.memory, 0) / time.cascade, 0, 1)); + const x = (word[0] + word[2]) / 2; + const node_x = (node[0] + node[2]) / 2; + const between = (node[3] + word[1]) / 2 + 18 * k; + raw.faded(leaves).arrow(&.{ .{ x, word[1] }, .{ x, between }, .{ node_x, between }, .{ node_x, node[3] + 2 * k } }, theme.mark(.write).solid, .{ .width = theme.stroke.line * k, .head = .{ 12 * k, 10 * k }, .progress = drawn }); + break; + } + } +}; + +test "places have keys of their own" { + try std.testing.expect((Place{ .word = 0x1000 }).key() != (Place{ .node = 0x1000 }).key()); + try std.testing.expect((Place{ .source = {} }).key() != (Place{ .pc = {} }).key()); +} -- cgit v1.3