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/array.zig | 189 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 anim/src/array.zig (limited to 'anim/src/array.zig') diff --git a/anim/src/array.zig b/anim/src/array.zig new file mode 100644 index 0000000..5d6b471 --- /dev/null +++ b/anim/src/array.zig @@ -0,0 +1,189 @@ +//! An array as cells: a variable the recording describes as `T name[N]`, +//! each element a cell with its index, the index variables that point into +//! it as tags, the cells a step compared framed as read, and a value a +//! step copied from one cell to another flying there on an arc, to land as +//! a write (a swap is two flights, one over and one under, the second a +//! little behind the first). +//! This is the idea drawn from memory: it changes a beat after the bytes do. +//! Reads `Moment.variables`, `Moment.read`, and the index of reads and writes. +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; +const fl = time.flight; + +/// How long a value flies, by how far: duration follows distance. +fn flightTime(units: f32) f32 { + return if (units <= 200) fl.near else if (units <= 400) fl.mid else fl.far; +} + +pub const Array = struct { + cursor: cursors.Cursor, + box: Rect, + /// The array's name in the program. + variable: []const u8, + /// Variables that index it, shown as tags in the cell they point at. + indices: []const []const u8 = &.{}, + focus: bool = false, + + /// The timetable of a step that swaps two neighbouring cells (give it + /// to `Cursor.step`): the line fires, the first value lifts and + /// flies, the second a little behind it; each lands with a strike; + /// then the hold, and the mark moves on. 2.1 s. + pub const swap: cursors.Plan = blk: { + const lands = time.fire + fl.lift + fl.near; + const advance = lands + fl.second + time.read_value; + break :blk .{ .at = .{ time.cascade, time.cascade, lands }, .advance = advance, .travel = time.step, .total = advance + time.step + time.rest }; + }; + + pub fn draw(g: *const Array, 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 v = rec.variable(f.scratch, moment, g.variable) orelse { + _ = u.panel(g.box.w, g.box.h, g.variable, .{ .focus = g.focus }); + return; + }; + const kind = rec.typeOf(f.scratch, v.type); + // Its declaration, and where it is: the address the context's pointers to it end in. + const body = u.panel(g.box.w, g.box.h, g.variable, .{ .focus = g.focus, .note = u.print("{s} at \u{2026}{x:0>4}", .{ objects.declare(f.scratch, rec, v), v.addr & 0xffff }) }); + // An array of numbers; anything else is read as 4-byte ones. + const elem: u64 = if (kind != null and kind.? == .array) kind.?.array.elem.size() orelse 4 else 4; + const signed = kind == null or kind.? != .array or kind.?.array.elem.* != .scalar or kind.?.array.elem.scalar.kind == .int; + const count: usize = @intCast(@min(v.size / elem, 32)); + if (count == 0) return; + + const room = body.w - 2 * theme.metric.panel.pad_x; + const hero = @as(f32, @floatFromInt(count)) * theme.metric.hero_cell[0] <= room; + // Beside the context there is less room: the cells are as wide as fit. + const compact = !hero and @as(f32, @floatFromInt(count)) * theme.metric.cell[0] > room; + const cell: [2]f32 = if (hero) theme.metric.hero_cell else if (compact) .{ @floor(room / @as(f32, @floatFromInt(count))), theme.metric.cell[1] } else theme.metric.cell; + const size: f32 = if (hero) theme.size.mono.hero else if (compact) theme.size.mono.data else theme.size.mono.value; + const left = (body.w - @as(f32, @floatFromInt(count)) * cell[0]) / 2; + const top = body.y + (body.h - cell[1]) / 2 - @as(f32, if (compact) 30 else 0); + const walking = now.walking(); + + // What moved: a cell written with what another cell held, which this step read. + const Flight = struct { from: usize, to: usize }; + var flights: std.ArrayList(Flight) = .empty; + const values = f.scratch.alloc(?i64, count) catch return; + const old = f.scratch.alloc(?i64, count) catch return; + for (values, old, 0..) |*value, *was, i| { + value.* = number(now.moment(), v.addr + i * elem, elem, signed); + was.* = number(now.before(), v.addr + i * elem, elem, signed); + } + if (now.plan.gait != .sprint and !now.resting()) for (0..count) |to| { + if (now.writeAge(v.addr + to * elem, elem) != 0 or values[to] == null) continue; + for (0..count) |from| { + if (from != to and old[from] == values[to] and now.wasRead(v.addr + from * elem, elem)) { + flights.append(f.scratch, .{ .from = from, .to = to }) catch {}; + break; + } + } + }; + + for (0..count) |i| { + const r: Rect = .{ .x = left + @as(f32, @floatFromInt(i)) * cell[0], .y = top, .w = cell[0] - 2, .h = cell[1] }; + const addr = v.addr + i * elem; + // The cell a value is flying to is struck when it lands: the second a little after the first. + const flown: ?usize = for (flights.items, 0..) |flight, k| { + if (flight.to == i) break k; + } else null; + const delay = if (flown) |k| @as(f32, @floatFromInt(k)) * fl.second else 0; + const pending = !now.landed(.idea, delay) and now.writeAge(addr, elem) == 0; + var heat = now.written(addr, elem, .idea, delay); + // The value on its way is the anticipation: no frame as well. + if (flown != null) heat.arm = 0; + const ink = u.written(r, heat, theme.color.raised); + // Staging: the compare is seen (framed as read) before anything moves. + if (now.wasRead(addr, elem) and now.writeAge(addr, elem) != 0) u.readMark(r, now.reading(.idea, 0)); + u.text(.mono, if (compact) theme.size.mono.context else theme.size.mono.small, r.x + @as(f32, if (compact) 6 else 14), r.y + @as(f32, if (compact) 24 else 34), u.print("{d}", .{i}), if (ink.face == .mono_bold) ink.ink else ui.rgb(t.faint)); + // Until its new value lands a cell keeps the old one, faint once + // the new is in the air: a copy does not erase. + const shown = if (pending) old[i] else values[i]; + const digits: Rect = .{ .x = r.x, .y = r.y + 18, .w = r.w, .h = r.h - 18 }; + const leaving = pending and flown != null and (!walking or now.since(.idea, delay) >= -(flightTime(cell[0]) + fl.lift)); + if (shown) |n| u.label(ink.face, size, digits, .center, u.print("{d}", .{n}), if (leaving) ui.rgb(t.faint) else ink.ink) else u.unknown(digits); + } + + // Index variables: tags that slide from cell to cell as the idea strikes. + for (g.indices, 0..) |name, nth| { + const iv = rec.variable(f.scratch, now.moment(), name) orelse continue; + const here = number(now.moment(), iv.addr, @min(iv.size, 8), true) orelse continue; + var x = left + (@as(f32, @floatFromInt(here)) + 1) * cell[0]; + if (number(now.before(), iv.addr, @min(iv.size, 8), true)) |was| { + x = std.math.lerp(left + (@as(f32, @floatFromInt(was)) + 1) * cell[0], x, cursors.standard(now.moving(.idea, 0, time.move))); + } + if (here < 0 or here >= count) continue; + // Under the tags of the indices before it that are in the same cell. + var slot: f32 = 0; + for (g.indices[0..nth]) |other| { + const ov = rec.variable(f.scratch, moment, other) orelse continue; + if (number(moment, ov.addr, @min(ov.size, 8), true) == here) slot += 1; + } + const w = u.width(.mono_bold, theme.size.mono.small, name) + 16; + // In a narrow cell the tags hang under it, not in it. + const tag: Rect = if (compact) .{ .x = x - cell[0] / 2 - w / 2, .y = top + cell[1] + 8 + slot * 38, .w = w, .h = 34 } else .{ .x = x - 2 - 10 - w, .y = top + 10 + slot * 38, .w = w, .h = 34 }; + u.fill(tag, t.ink); + u.label(.mono_bold, theme.size.mono.small, tag, .center, name, t.primary); + } + + // Values in flight, over everything: one over, the next under. + for (flights.items, 0..) |flight, k| { + const from = ui.Vec{ left + (@as(f32, @floatFromInt(flight.from)) + 0.5) * cell[0], top + cell[1] / 2 + 9 }; + const to = ui.Vec{ left + (@as(f32, @floatFromInt(flight.to)) + 0.5) * cell[0], top + cell[1] / 2 + 9 }; + const far = @abs(to[0] - from[0]); + const seconds = flightTime(far); + // Seconds until it lands. Anticipation: it lifts out of its + // cell before it goes, and is back to size as it comes down. + const left_to_go = -now.since(.idea, @as(f32, @floatFromInt(k)) * fl.second); + if (left_to_go <= 0) continue; + var along: f32 = undefined; + var lifted: f32 = undefined; + if (walking) { + if (left_to_go > seconds + fl.lift) continue; + along = 1 - std.math.clamp(left_to_go / seconds, 0, 1); + lifted = @min(std.math.clamp((seconds + fl.lift - left_to_go) / fl.lift, 0, 1), std.math.clamp(left_to_go / fl.lift, 0, 1)); + } else { + // At a run: the same arc, eased, in the step's first frames. + along = now.moving(.idea, 0, 0); + lifted = 0; + if (along >= 1) continue; + } + // Arcs: an idea moves on a curve, slow out of one cell and into the other, quickest over the top. + const eased = cursors.glide(along); + const rise = std.math.clamp(fl.arc * far, fl.arc_min, fl.arc_max) + cell[1] / 2; + const way: f32 = if (k % 2 == 0) -1 else 1; + const c = sk.math.mix(from, to, eased) + ui.Vec{ 0, way * rise * @sin(std.math.pi * eased) }; + const grown = std.math.lerp(1, fl.lift_scale, lifted); + const w = (if (compact) cell[0] + 4 else @max(theme.metric.flight_card[0], cell[0] * 0.6)) * grown; + const h = (if (compact) theme.metric.flight_card[1] - 8 else theme.metric.flight_card[1]) * grown; + const card: Rect = .{ .x = c[0] - w / 2, .y = c[1] - h / 2, .w = w, .h = h }; + u.fill(card, theme.color.page); + u.frame(card, t.bright, theme.stroke.line); + if (values[flight.to]) |n| u.label(.mono_bold, if (compact) theme.size.mono.value else theme.size.mono.flight, card, .center, u.print("{d}", .{n}), t.bright); + } + } +}; + +/// `bytes` at `addr` as a number, null where never recorded. +fn number(moment: Recording.Moment, addr: u64, bytes: u64, signed: bool) ?i64 { + const n: usize = @intCast(@min(bytes, 8)); + const raw = (Recording.word(moment, addr, n) catch return null) orelse return null; + if (!signed) return @bitCast(raw); + const shift: u6 = @intCast(64 - 8 * n); + return @as(i64, @bitCast(raw << shift)) >> shift; +} + +test "a swap of neighbours is 2.1 seconds" { + try std.testing.expectApproxEqAbs(@as(f32, 2.1), Array.swap.total, 1e-3); + try std.testing.expect(flightTime(168) == fl.near and flightTime(336) == fl.mid and flightTime(900) == fl.far); +} -- cgit v1.3