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/calls.zig | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 anim/src/calls.zig (limited to 'anim/src/calls.zig') diff --git a/anim/src/calls.zig b/anim/src/calls.zig new file mode 100644 index 0000000..af0893d --- /dev/null +++ b/anim/src/calls.zig @@ -0,0 +1,160 @@ +//! Calls as an idea, a lens on the stack: the tree of every call of one +//! function, which grows as the program runs (the frames themselves are +//! `context.Backtrace` and the stack's words). It reads the recording's +//! index of calls and returns, with what each was given and gave back, +//! and is the last level a step reaches: a node appears after the +//! registers that carried its argument have struck. +const std = @import("std"); +const sk = @import("sketch"); +const anim = @import("anim"); +const ui = @import("ui.zig"); +const cursors = @import("cursor.zig"); +const Cursor = cursors.Cursor; +const Recording = @import("Recording.zig"); +const theme = ui.theme; +const time = theme.time; +const Rect = ui.Rect; +const t = theme.color.text; + +/// A return's follow-through: its frame leaves the backtrace as the idea +/// strikes, and the tree's badge is struck this long after. +const badge_after = 0.20; + +pub const Tree = struct { + cursor: Cursor, + box: Rect, + /// The function whose calls are the tree. + function: []const u8, + focus: bool = false, + + pub fn draw(k: *const Tree, f: *sk.Frame, at: anim.Placed) void { + const u: ui.Ui = .{ .f = f, .at = at }; + const now = k.cursor.now(at); + const rec = k.cursor.rec; + const m = struct { + const radius = 18; + const level = 44; + const badge = 24; + }; + const body = u.panel(k.box.w, k.box.h, u.print("calls of {s}", .{k.function}), .{ .focus = k.focus, .note = "each call a node \u{00b7} its result on the shoulder \u{00b7} the frames are the stack's" }); + const nodes = layout(f.scratch, rec, k.function) catch return; + if (nodes.len == 0) return; + var leaves: f32 = 0; + for (nodes) |n| leaves = @max(leaves, n.x + 1); + const pitch = @min(4.5 * m.radius, (body.w - 2 * theme.metric.panel.pad_x - 2 * m.radius) / @max(leaves - 1, 1)); + const left = (body.w - (leaves - 1) * pitch) / 2; + const top = body.y + m.radius + 12; + var deepest_level: f32 = 1; + for (nodes) |n| deepest_level = @max(deepest_level, @as(f32, @floatFromInt(n.level))); + const level_h = @min(m.level, (body.h - 2 * m.radius - 24) / deepest_level); + // A call: its edge draws from the caller's node, then the node + // fades in, gold, and the caller's goes from gold to a waiting + // ring. A return: the badge is struck a little after the card's + // result, and the node goes from gold to done. + const since = now.since(.idea, 0); + const returned = now.walking() and rec.depths[now.stops[0]] < rec.depths[now.stops[1]]; + const moment = if (now.plan.gait == .sprint or since >= (if (returned) @as(f32, badge_after) else 0)) now.stops[0] else now.stops[1]; + const edge = cursors.standard(now.moving(.idea, time.quick, time.quick)); + const appears = now.moving(.idea, 0, time.snap); + + // Edges under nodes: the waiting path in vellum. + for (nodes) |n| { + const parent = n.parent orelse continue; + if (n.call.enter > now.stops[0]) continue; + const from = ui.Vec{ left + nodes[parent].x * pitch, top + @as(f32, @floatFromInt(nodes[parent].level)) * level_h }; + var to = ui.Vec{ left + n.x * pitch, top + @as(f32, @floatFromInt(n.level)) * level_h }; + if (n.call.enter > now.stops[1]) to = sk.math.mix(from, to, edge); + const live = n.call.active(moment); + u.line(from, to, if (live or n.call.enter > moment) ui.rgb(t.primary) else ui.rgb(theme.color.rule), if (live or n.call.enter > moment) theme.stroke.arrow else theme.stroke.line); + } + const deepest = deepestActive(nodes, moment); + for (nodes, 0..) |n, i| { + if (n.call.enter > moment) continue; + const c = ui.Vec{ left + n.x * pitch, top + @as(f32, @floatFromInt(n.level)) * level_h }; + const v = if (n.call.enter > now.stops[1]) u.faded(appears) else u; + if (deepest == i) { + v.disc(c, m.radius, ui.rgb(theme.mark(.current).solid), null, 0); + } else if (n.call.active(moment)) { + v.disc(c, m.radius - theme.stroke.arrow / 2, ui.rgb(theme.color.page), ui.rgb(t.primary), theme.stroke.arrow); + } else v.disc(c, m.radius, ui.rgb(theme.color.raised), null, 0); + } + // Then the words, so shapes and text each go in one run. + const size = theme.size.mono.context; + for (nodes, 0..) |n, i| { + if (n.call.enter > moment) continue; + const cx = left + n.x * pitch; + const cy = top + @as(f32, @floatFromInt(n.level)) * level_h; + const active = n.call.active(moment); + const words = if (n.call.arg) |arg| u.print("{d}", .{@as(i64, @bitCast(arg))}) else "?"; + const cell: Rect = .{ .x = cx - m.radius, .y = cy - m.radius, .w = 2 * m.radius, .h = 2 * m.radius }; + const v = if (n.call.enter > now.stops[1]) u.faded(appears) else u; + if (deepest == i) { + v.label(.mono_bold, size, cell, .center, words, theme.mark(.current).on_solid); + } else v.label(.mono, size, cell, .center, words, if (active) t.primary else t.dim); + if (active) continue; + // Done: what it returned, on its shoulder; struck as it lands. + const badge: Rect = .{ .x = cx + 10, .y = cy - m.radius - 12, .w = m.badge, .h = m.badge }; + const heat: ui.Heat = if (n.call.exit.? > now.stops[1]) now.heat(0, null, since - badge_after) else .none; + const ink = u.written(badge, heat, theme.color.page); + if (heat.level < 1) u.frame(badge, t.faint, theme.stroke.rule); + u.label(ink.face, size, badge, .center, u.print("{d}", .{@as(i64, @bitCast(n.call.result))}), if (heat.level >= 1) ink.ink else ui.rgb(t.primary)); + } + } +}; + +pub const Node = struct { + call: Recording.Call, + parent: ?usize, + level: u32, + /// In leaf slots: a leaf has a whole number, a parent sits over the + /// middle of its children. + x: f32, +}; + +fn deepestActive(nodes: []const Node, moment: u64) ?usize { + var best: ?usize = null; + for (nodes, 0..) |n, i| { + if (n.call.active(moment) and (best == null or n.level >= nodes[best.?].level)) best = i; + } + return best; +} + +/// Every call of `function`, placed as a tidy tree of the whole run, so a +/// node is where it will always be from the moment it appears. +pub fn layout(arena: std.mem.Allocator, rec: *const Recording, function: []const u8) ![]Node { + var nodes: std.ArrayList(Node) = .empty; + // Calls come in the order they were made: a parent before its children. + var index: std.AutoHashMapUnmanaged(u32, usize) = .empty; + for (rec.calls, 0..) |call, i| { + if (!std.mem.eql(u8, rec.name(call.function), function)) continue; + const parent: ?usize = if (call.parent) |p| index.get(p) else null; + try index.put(arena, @intCast(i), nodes.items.len); + try nodes.append(arena, .{ .call = call, .parent = parent, .level = if (parent) |p| nodes.items[p].level + 1 else 0, .x = -1 }); + } + // Leaves left to right in call order; then each parent over its children, + // deepest first (children come after their parent, so backwards). + const lo = try arena.alloc(f32, nodes.items.len); + const hi = try arena.alloc(f32, nodes.items.len); + @memset(lo, std.math.inf(f32)); + @memset(hi, -std.math.inf(f32)); + var next_leaf: f32 = 0; + for (nodes.items, 0..) |*n, i| { + const leaf = for (nodes.items[i + 1 ..]) |other| { + if (other.parent == i) break false; + } else true; + if (!leaf) continue; + n.x = next_leaf; + next_leaf += 1; + } + var i = nodes.items.len; + while (i > 0) { + i -= 1; + const n = &nodes.items[i]; + if (n.x < 0) n.x = (lo[i] + hi[i]) / 2; + if (n.parent) |p| { + lo[p] = @min(lo[p], n.x); + hi[p] = @max(hi[p], n.x); + } + } + return nodes.items; +} -- cgit v1.3