summaryrefslogtreecommitdiff
path: root/anim/src/nodes.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 14:48:26 -0300
committerGabriel Schneider <[email protected]>2026-11-10 15:14:31 -0300
commit7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb (patch)
treea6add92cd4dcbbf4c31cd1ce989d99b190258353 /anim/src/nodes.zig
parented46c51fe127377eb1fde8dee83da984e0f61860 (diff)
downloadcomputeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.tar.gz
computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.zip
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.
Diffstat (limited to 'anim/src/nodes.zig')
-rw-r--r--anim/src/nodes.zig273
1 files changed, 273 insertions, 0 deletions
diff --git a/anim/src/nodes.zig b/anim/src/nodes.zig
new file mode 100644
index 0000000..1326837
--- /dev/null
+++ b/anim/src/nodes.zig
@@ -0,0 +1,273 @@
+//! Data structures as nodes and arrows: the structs the program's pointers
+//! reach from a root variable (`objects.reach`: no offsets are given by
+//! hand, the recording's type descriptions say which fields are pointers
+//! and which is the value). A node's place is its allocation's (the order
+//! it was made in), so nodes stay where they are while pointers change: a
+//! list reversing is its arrows turning round. Variables that point at a
+//! node are tags under it, tracked ones in their pigment, and slide from
+//! node to node as they change; one that holds NULL waits at the row's
+//! end. A node whose memory was freed is hollow and dashed.
+//! This is the idea drawn from memory: it changes a beat after the bytes do.
+//! Reads `Moment.variables`, `Moment.read`, `Moment.allocation`.
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const ui = @import("ui.zig");
+const cursors = @import("cursor.zig");
+const Recording = @import("Recording.zig");
+const objects = @import("objects.zig");
+const theme = ui.theme;
+const time = theme.time;
+const Rect = ui.Rect;
+const t = theme.color.text;
+/// A node of a lens beside the context.
+const size = struct {
+ const w = 116;
+ const h = 44;
+ const pointer_w = 44;
+};
+
+pub const Nodes = struct {
+ cursor: cursors.Cursor,
+ box: Rect,
+ title: []const u8 = "the list",
+ note: []const u8 = "what the code means",
+ /// The variable the structure hangs from.
+ root: []const u8,
+ /// Variables each with a pigment (by its place here): the same list a
+ /// memory grid of them is given.
+ track: []const []const u8 = &.{},
+ /// How nodes are placed: in a row (a list), or a row for each distance
+ /// from the root (a tree, a graph). Either way a node's column is its own.
+ arrange: enum { row, levels } = .row,
+ focus: bool = false,
+
+ pub fn draw(g: *const Nodes, f: *sk.Frame, at: anim.Placed) void {
+ const u: ui.Ui = .{ .f = f, .at = at };
+ const now = g.cursor.now(at);
+ const rec = g.cursor.rec;
+ const moment = now.shown(.idea);
+ const body = u.panel(g.box.w, g.box.h, g.title, .{ .focus = g.focus, .note = g.note });
+ const things = objects.reach(f.scratch, rec, moment, null);
+ const before = objects.reach(f.scratch, rec, now.before(), null);
+ if (things.len == 0) {
+ const root = rec.variable(f.scratch, moment, g.root);
+ const empty = root != null and (Recording.word(moment, root.?.addr, 8) catch null) == 0;
+ return u.text(.sans, theme.size.sans.note, theme.metric.panel.pad_x, body.y + 52, if (empty) u.print("empty: {s} is NULL", .{g.root}) else "nothing yet", t.faint);
+ }
+
+ // Columns: one for every node the program will ever make, so no
+ // node moves when another comes or goes. And one more, where a
+ // variable that holds NULL waits.
+ var slots: usize = 0;
+ for (rec.allocations) |a| slots += @intFromBool(a.size == things[0].type.record.size);
+ slots = @max(slots, 1);
+ const count: f32 = @floatFromInt(slots);
+ const park_w = 76;
+ // As a lens beside the context a node is 116 by 44; a gap for an arrow.
+ const node_w = @min(size.w, @floor((body.w - 2 * 20 - park_w) / count) - 28);
+ const gap = @min(56, (body.w - 2 * 20 - park_w - count * node_w) / count);
+ const left: f32 = 24;
+ const row_y = body.y + 36;
+ const park: ui.Vec = .{ left + count * (node_w + gap), row_y - 12 };
+
+ const places = f.scratch.alloc(Rect, things.len) catch return;
+ for (things, places, 0..) |o, *place, i| {
+ const level: f32 = if (g.arrange == .levels) @floatFromInt(distance(f.scratch, rec, moment, things, g.root, i)) else 0;
+ place.* = .{ .x = left + @as(f32, @floatFromInt(o.slot orelse i)) * (node_w + gap), .y = if (g.arrange == .levels) body.y + 40 + level * (size.h + 56) else row_y, .w = node_w, .h = size.h };
+ @import("ties.zig").anchor(u, .{ .node = o.addr }, place.*);
+ // Where it is in the heap, under it: the address the registers' chains to it show, in heap's ink.
+ _ = u.value(place.x, place.y + place.h + 20, o.addr, true, .{ .ink = ui.rgb(theme.color.region.heap) });
+ }
+
+ // Arrows under the nodes they leave.
+ const since = now.since(.idea, 0);
+ var lane: f32 = 0;
+ for (things, places) |o, place| for (o.type.record.fields) |field| {
+ if (field.type != .pointer) continue;
+ const from_addr = o.addr + field.offset;
+ const start = ui.Vec{ place.x + place.w - pointerW(place.w) / 2, place.y + size.h / 2 };
+ const new = if (Recording.word(now.moment(), from_addr, 8) catch null) |target| placeOf(things, places, target) else null;
+ const old = if (Recording.word(now.before(), from_addr, 8) catch null) |target| placeOf(things, places, target) else null;
+ const fresh = now.writeAge(from_addr, 8) == 0;
+ lane += 1;
+ const purple = theme.color.region.heap;
+ if (!fresh or !now.walking()) {
+ // As it stands; at a run a new arrow still grows to its node.
+ if (if (now.landed(.idea, 0)) new else old) |to| u.arrow(route(u, start, place, to, lane), purple, .{ .progress = if (fresh) cursors.standard(now.moving(.idea, 0, time.redirect.head)) else 1 });
+ continue;
+ }
+ // A pointer rewritten, a beat after its word in memory.
+ // Anticipation: as the square is armed the old arrow goes
+ // dashed and faint. Follow-through: the square strikes, the
+ // new arrow grows to the node it now points at, and that
+ // node answers with a bright frame. The old one lingers.
+ const armed = since >= -time.strike.arm;
+ if (old) |to| {
+ const ghost = if (armed) u.faded(1 - std.math.clamp((since - time.redirect.ghost_hold) / time.redirect.ghost_out, 0, 1)) else u;
+ ghost.arrow(route(u, start, place, to, 0), if (armed) ui.rgb(t.faint) else ui.rgb(purple), .{ .dashed = armed, .head = if (armed) null else theme.stroke.head, .width = if (armed) theme.stroke.line else theme.stroke.arrow });
+ }
+ if (new) |to| {
+ u.arrow(route(u, start, place, to, lane), purple, .{ .progress = cursors.standard(std.math.clamp((since - time.snap) / time.redirect.head, 0, 1)) });
+ const landed = since - time.snap - time.redirect.head;
+ const out = theme.metric.pointer_frame_outset;
+ if (landed >= 0 and landed < time.redirect.landing) u.faded(1 - landed / time.redirect.landing).frame(.{ .x = to.x - out, .y = to.y - out, .w = to.w + 2 * out, .h = to.h + 2 * out }, theme.mark(.attention).solid, theme.stroke.line);
+ }
+ };
+
+ for (things, places) |o, place| {
+ const new = for (before) |b| {
+ if (b.addr == o.addr) break false;
+ } else true;
+ // What begins fades in; it does not pop.
+ g.node(if (new) u.faded(now.moving(.idea, 0, time.quick)) else u, now, o, place);
+ }
+ g.tags(u, now, things, places, park);
+ }
+
+ fn node(g: *const Nodes, u: ui.Ui, now: cursors.Now, o: objects.Object, r: Rect) void {
+ _ = g;
+ const moment = now.shown(.idea);
+ const value_w = r.w - pointerW(r.w);
+ const value: Rect = .{ .x = r.x, .y = r.y, .w = value_w, .h = r.h };
+ const pointer: Rect = .{ .x = r.x + value_w, .y = r.y, .w = pointerW(r.w), .h = r.h };
+ if (o.freed) {
+ // Handed back: its bytes are still there, and nobody owns them.
+ u.dashedFrame(r, theme.mark(.freed).solid, theme.stroke.line);
+ } else {
+ // A node is its own colour whoever points at it: pigment is for the names.
+ u.fill(value, theme.color.raised);
+ u.fill(pointer, ui.mix(theme.color.raised, theme.color.page, 0.45));
+ u.fill(.{ .x = pointer.x, .y = r.y, .w = theme.stroke.rule, .h = r.h }, theme.color.page);
+ }
+ if (o.valueField()) |field| {
+ const bytes: usize = @intCast(@min(8, field.type.size() orelse 8));
+ var ink: ui.Ink = .{};
+ if (!o.freed) ink = u.written(value, now.written(o.addr + field.offset, bytes, .idea, 0), null);
+ if (Recording.word(moment, o.addr + field.offset, bytes) catch null) |n| {
+ const shift: u6 = @intCast(64 - 8 * bytes);
+ const signed = @as(i64, @bitCast(n << shift)) >> shift;
+ u.label(ink.face, theme.size.mono.small, value, .center, u.print("{d}", .{signed}), if (o.freed) ui.rgb(t.faint) else ink.ink);
+ } else u.unknown(value);
+ }
+ // The first pointer field: the square its arrow leaves from, or a slash for null.
+ for (o.type.record.fields) |field| {
+ if (field.type != .pointer) continue;
+ const held = Recording.word(moment, o.addr + field.offset, 8) catch null;
+ // On the solid of a strike the square is ink, like digits.
+ const struck = !o.freed and u.written(pointer, now.written(o.addr + field.offset, 8, .idea, 0), null).face == .mono_bold;
+ if (held == null) {
+ u.unknown(pointer);
+ } else if (held.? == 0) {
+ u.line(.{ pointer.x + 12, pointer.y + pointer.h - 10 }, .{ pointer.x + pointer.w - 12, pointer.y + 10 }, if (struck) t.ink else t.dim, theme.stroke.line);
+ } else u.fill(.{ .x = pointer.x + pointer.w / 2 - 7, .y = pointer.y + pointer.h / 2 - 7, .w = 14, .h = 14 }, if (struck) t.ink else theme.color.region.heap);
+ break;
+ }
+ }
+
+ /// The names: the root and the tracked variables, each a tag under
+ /// the node it points at, or at the row's end when it holds NULL.
+ /// What persists slides: a tag goes to its new place as the idea
+ /// strikes, and fades only where it has nowhere to come from.
+ fn tags(g: *const Nodes, u: ui.Ui, now: cursors.Now, things: []const objects.Object, places: []const Rect, park: ui.Vec) void {
+ const rec = g.cursor.rec;
+ const small = theme.size.mono.context;
+ const h = 22;
+ const states = [2]Recording.Moment{ now.before(), now.moment() };
+ const count = 1 + g.track.len;
+ // In each state, where each name points: an address, 0 for NULL, null for nowhere to draw.
+ const held = u.f.scratch.alloc([2]?u64, count) catch return;
+ var parked = false;
+ for (0..count) |i| for (states, 0..) |state, k| {
+ held[i][k] = null;
+ const v = rec.variable(u.f.scratch, state, if (i == 0) g.root else g.track[i - 1]) orelse continue;
+ if (!rec.assigned(v, state.index)) continue;
+ const to = (Recording.word(state, v.addr, 8) catch null) orelse continue;
+ if (to == 0 or placeOf(things, places, to) != null) held[i][k] = to;
+ if (to == 0) parked = true;
+ };
+ if (parked) u.text(.mono, small, park[0], park[1] + 16, "NULL", t.faint);
+ const p = cursors.glide(now.moving(.idea, 0, time.move));
+ for (0..count) |i| {
+ const name = if (i == 0) g.root else g.track[i - 1];
+ var at_place: [2]?ui.Vec = .{ null, null };
+ for (&at_place, 0..) |*place, k| {
+ const to = held[i][k] orelse continue;
+ // Under the names already at the same place.
+ var above: f32 = 0;
+ for (0..i) |other| above += @floatFromInt(@intFromBool(held[other][k] == to));
+ // Beside the names already at the same place: under the node's address, or at the row's end.
+ var width: f32 = 0;
+ for (0..i) |other| if (held[other][k] == to) {
+ width += u.width(.mono, small, if (other == 0) g.root else g.track[other - 1]) + 16 + 4;
+ };
+ place.* = if (to == 0) .{ park[0], park[1] + 24 + above * (h + 2) } else if (placeOf(things, places, to)) |r| .{ r.x + width, r.y + r.h + 28 } else null;
+ }
+ const xy = if (at_place[0] != null and at_place[1] != null) sk.math.mix(at_place[0].?, at_place[1].?, p) else at_place[1] orelse at_place[0] orelse continue;
+ const v = if (at_place[0] == null) u.faded(p) else if (at_place[1] == null) u.faded(1 - p) else u;
+ const tag: Rect = .{ .x = xy[0], .y = xy[1], .w = u.width(.mono, small, name) + 16, .h = h };
+ if (i > 0) v.fill(tag, theme.color.pigment[(i - 1) % theme.color.pigment.len]) else v.frame(tag, t.faint, theme.stroke.rule);
+ v.label(.mono, small, tag, .center, name, t.primary);
+ }
+ }
+};
+
+/// The pointer's square, of a node `w` wide.
+fn pointerW(w: f32) f32 {
+ return @min(size.pointer_w, @round(w * 0.4));
+}
+
+fn placeOf(things: []const objects.Object, places: []const Rect, addr: u64) ?Rect {
+ for (things, places) |o, place| if (o.addr == addr) return place;
+ return null;
+}
+
+/// From the pointer square at `start` (in the node at `from`) to the left
+/// edge of the node at `to`: straight to the neighbour on the right, else
+/// up and over, in a lane of its own.
+fn route(u: ui.Ui, start: ui.Vec, from: Rect, to: Rect, lane: f32) []const ui.Vec {
+ const enter = ui.Vec{ to.x - 2, to.y + to.h / 2 };
+ const out = u.f.scratch.alloc(ui.Vec, 5) catch return &.{};
+ if (@abs(to.y - from.y) < 1 and to.x > from.x and to.x - (from.x + from.w) < 100) {
+ out[0] = start;
+ out[1] = enter;
+ return out[0..2];
+ }
+ // Over the top when going back, under when going on past a neighbour.
+ const over = to.x < from.x or @abs(to.y - from.y) > 1;
+ const y = if (over) @min(from.y, to.y) - 12 - @mod(lane, 2) * 8 else @max(from.y + from.h, to.y + to.h) + 64 + @mod(lane, 2) * theme.stroke.lane_pitch;
+ out[0] = .{ start[0], if (over) from.y else from.y + from.h };
+ out[1] = .{ start[0], y };
+ out[2] = .{ to.x - 26, y };
+ out[3] = .{ to.x - 26, enter[1] };
+ out[4] = enter;
+ return out;
+}
+
+/// How many pointers from the root variable to `things[i]`, at least.
+fn distance(scratch: std.mem.Allocator, rec: *const Recording, moment: Recording.Moment, things: []const objects.Object, root: []const u8, i: usize) usize {
+ const dist = scratch.alloc(usize, things.len) catch return 0;
+ @memset(dist, things.len);
+ if (rec.variable(scratch, moment, root)) |v| if (Recording.word(moment, v.addr, 8) catch null) |first| {
+ for (things, 0..) |o, k| if (o.addr == first) {
+ dist[k] = 0;
+ };
+ };
+ // Few nodes: relax until nothing changes.
+ var changed = true;
+ while (changed) {
+ changed = false;
+ for (things, 0..) |o, k| {
+ if (dist[k] == things.len) continue;
+ for (o.type.record.fields) |field| {
+ if (field.type != .pointer) continue;
+ const target = (Recording.word(moment, o.addr + field.offset, 8) catch null) orelse continue;
+ for (things, 0..) |other, j| if (other.addr == target and dist[j] > dist[k] + 1) {
+ dist[j] = dist[k] + 1;
+ changed = true;
+ };
+ }
+ }
+ }
+ return if (dist[i] == things.len) 0 else dist[i];
+}