summaryrefslogtreecommitdiff
path: root/anim/src/pair.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-11 23:46:02 -0300
committerGabriel Schneider <[email protected]>2026-11-12 01:40:04 -0300
commit60e07feef401d9044db3a1c925cb9d1f6d20dac9 (patch)
tree98957ba8425193f686c8e8692cd10a10f27dbf4b /anim/src/pair.zig
parent9c0696447dbc5cf37e56aee562c7ebba4f4d4e6b (diff)
downloadcomputeranim-60e07feef401d9044db3a1c925cb9d1f6d20dac9.tar.gz
computeranim-60e07feef401d9044db3a1c925cb9d1f6d20dac9.zip
canim: relations as one data-oriented subsystem; aim; the ASan pair; the introduction's chapters
From the user. Relations between panes are one subsystem: per-frame tables of places and values in struct-of-arrays, owned by the frame; the kinds one table of data; a resolver of pure passes (join, filter, priority, cut) unit-tested on hand-written tables. Ported kinds draw byte-identical frames; a synthetic map of 4000 places and 6000 values resolves in 0.56 ms against the old table's 5.7. aim, a word holding a code address tied to its row, is the first new kind, off unless a scene turns it on. The ASan pair: one overflow built plain and with ASan, recorded by instruction; the frame as bytes eight a row; the plain run goes on alone in the column, its return address aimed at main's row until the letters reach it; the fault at ret. The introduction's three chapters are built and tested, not yet exported. Annotations, rows and scrolls that changed in one frame now fade; captions stand twelve seconds at most. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'anim/src/pair.zig')
-rw-r--r--anim/src/pair.zig780
1 files changed, 780 insertions, 0 deletions
diff --git a/anim/src/pair.zig b/anim/src/pair.zig
new file mode 100644
index 0000000..0f9cfe0
--- /dev/null
+++ b/anim/src/pair.zig
@@ -0,0 +1,780 @@
+//! `pair` (design/README.md, "pair"): two runs of one program seen against
+//! each other, a split of the working frame. The shared source across both
+//! columns (the left run's mark on its number, the right run's ranged right),
+//! each run's disassembly, registers and frame on its side of the seam (the
+//! gutter, 944 to 976); a row one run has and the other has not (`only
+//! here`) a `dim` bar on its seam-side edge, a value that differs from its
+//! counterpart (`differs`) a `bright` one; one clock with both moments, one
+//! caption. Each side is a `Stage` of its own (`split`), so a panel of the
+//! context (`Disasm`, `Registers`, `Source`) draws there as anywhere, on its
+//! run's cursor; what the pair adds is here: the frame as bytes eight a row
+//! (`hexdump` `eight`: `Frame`), a stopped run's output (`Report`), the
+//! marks across the seam (`Marks`), the clock (`Clock`).
+const std = @import("std");
+const sk = @import("sketch");
+const anim = @import("anim");
+const zt = @import("ztrace");
+const ui = @import("ui.zig");
+const rows = @import("rows.zig");
+const cursors = @import("cursor.zig");
+const context = @import("context.zig");
+const ties = @import("ties.zig");
+const words = @import("words.zig");
+const Stage = @import("stage.zig").Stage;
+const Recording = @import("Recording.zig");
+const theme = ui.theme;
+const Rect = ui.Rect;
+const Split = theme.layout.Split;
+const t = theme.color.text;
+const m = theme.metric.context;
+const size = theme.size.mono.context;
+const adv = size * 3 / 5;
+
+pub const Side = enum { left, right };
+
+/// The pair's boxes on one side of the seam (`pair` in design/README.md):
+/// the source shared, five lines across both columns (48 to 200, the left
+/// side's; the right has none), then in each column the disassembly, nine
+/// rows (212 to 460), the registers, four (472 to 600), the frame, ten (612
+/// to 884). `stopped`: the right run once it has stopped, its disassembly
+/// down to the call that stopped it (five rows, to 364) and its output in
+/// `view` (six rows, 376 to 552), in place of its registers.
+pub fn split(side: Side, stopped: bool) Split {
+ const ph = theme.layout.panelH;
+ const gap = theme.canvas.row_gap;
+ const x: f32 = if (side == .left) theme.layout.program.x else theme.layout.state.x;
+ const w = theme.layout.program.w;
+ const top = theme.canvas.stage.y;
+ const none: Rect = .{ .x = x, .y = top, .w = w, .h = 0 };
+ const source: Rect = .{ .x = theme.canvas.stage.x, .y = top, .w = theme.canvas.stage.w, .h = if (side == .left) ph(5) else 0 };
+ const disasm: Rect = .{ .x = x, .y = top + ph(5) + gap, .w = w, .h = ph(if (stopped) 5 else 9) };
+ const registers: Rect = .{ .x = x, .y = top + ph(5) + ph(9) + 2 * gap, .w = w, .h = ph(4) };
+ const stack: Rect = .{ .x = x, .y = registers.y + registers.h + gap, .w = w, .h = ph(10) };
+ const view: Rect = if (stopped) .{ .x = x, .y = disasm.y + disasm.h + gap, .w = w, .h = ph(6) } else none;
+ return .{ .band = none, .view = view, .source = source, .disasm = disasm, .registers = registers, .stack = stack, .backtrace = none, .dump_rows = 0 };
+}
+
+test "the pair's boxes are the catalogue's" {
+ const l = split(.left, false);
+ try std.testing.expectEqual(@as(f32, 200), l.source.y + l.source.h);
+ try std.testing.expectEqual(@as(f32, 460), l.disasm.y + l.disasm.h);
+ try std.testing.expectEqual(@as(f32, 600), l.registers.y + l.registers.h);
+ try std.testing.expectEqual(@as(f32, 884), l.stack.y + l.stack.h);
+ const r = split(.right, true);
+ try std.testing.expectEqual(@as(f32, 364), r.disasm.y + r.disasm.h);
+ try std.testing.expectEqual(@as(f32, 552), r.view.y + r.view.h);
+ try std.testing.expectEqual(@as(f32, 976), r.stack.x);
+}
+
+/// A field of a frame, from the debug info and the call frame information
+/// (its locals, the saved rbp, the return address; an ASan fake frame's
+/// header, buffer and redzones), by address.
+pub const Field = struct {
+ at: u64,
+ len: u64,
+ name: []const u8,
+ reads: enum { number, pointer, text, bytes } = .number,
+ /// The moment it is the frame's from (the call pushes the return address,
+ /// the prologue the saved rbp and the locals): before it its bytes are
+ /// loose, and in the step that makes it its paper and reading fade in.
+ from: u64 = 0,
+};
+
+/// How much a thing that is the frame's from moment `from` shows now: none
+/// before, all after, and over the step that makes it, from memory's slot (12 f).
+fn live(now: cursors.Now, from: u64) f32 {
+ if (now.stops[0] < from) return 0;
+ if (now.stops[1] >= from or now.resting()) return 1;
+ return std.math.clamp(now.since(.memory, 0) / theme.time.quick, 0, 1);
+}
+
+/// `hexdump` `eight` (design/README.md): a stack frame as bytes, eight a
+/// row, so that a row is one word of the stack: rsp's and rbp's `row` pins
+/// at 12, the row's shadow byte at 62 (a run built with ASan), the address
+/// at 118, the bytes from 274 on a pitch of 30 (a field's on raised paper,
+/// what no field covers `loose`), the reading at 522 (the field's name in Go
+/// 18 dim, then what its bytes make), the frame's `call` span at 866. A byte
+/// the loop stores past `buf` keeps the string's ink in the field it lands
+/// in, whose reading says what the CPU will make of it. A store's byte is
+/// struck as in `bytes`; the field's reading crossfades from 6 f after it
+/// (12 f). Fixed rows: the pair scrolls each frame so that `buf` faces `buf`.
+pub const Frame = struct {
+ cursor: cursors.Cursor,
+ stage: *const Stage,
+ title: []const u8,
+ note: []const u8 = "",
+ /// Its rows, eight bytes each from `first`; then, under a rule, `more`
+ /// rows from `then` (ASan's real stack, far from its fake frame).
+ first: u64,
+ rows: usize,
+ then: u64 = 0,
+ more: usize = 0,
+ fields: []const Field,
+ /// Where the loop's letters begin: a byte from there on, up to the first
+ /// that is not one, is drawn in a string's ink whatever field holds it.
+ letters: u64 = 0,
+ letter: u8 = 'A',
+ /// Each row of the first stretch with its shadow byte beside it.
+ shadow: bool = false,
+ /// The frame's `call` span, from its first word to past its last, its
+ /// name, and the moment it is made.
+ span: [2]u64 = .{ 0, 0 },
+ span_from: u64 = 0,
+ /// In a box that holds more rows than it has (the column's): from this
+ /// word, as many rows as the box holds, and no second stretch; its rows
+ /// then the places a text is level with and a touch goes to (`ties`).
+ tall: u64 = 0,
+ name: []const u8 = "",
+ side: Side,
+ /// How much the first stretch shows (an ASan fake frame comes in as it is made).
+ shows: anim.Value,
+ /// How much the `differs` bars on rows `differ` show.
+ differs: anim.Value,
+ differ: []const u64 = &.{},
+
+ pub fn draw(frame: *const Frame, f: *sk.Frame, placed: anim.Placed) void {
+ const box = frame.stage.box(placed, .stack);
+ if (box.h < m.tag + m.row) return;
+ const fit = theme.layout.rowsIn(box.h);
+ var tall = frame.*;
+ const is_tall = frame.tall != 0 and fit > frame.rows + frame.more;
+ if (is_tall) {
+ tall.first = frame.tall;
+ tall.rows = fit;
+ tall.more = 0;
+ }
+ const fr = &tall;
+ const u = context.at(f, placed, box);
+ _ = u.panel(box.w, box.h, fr.title, .{ .note = fr.note });
+ context.clipBody(u, box);
+ defer u.unclip();
+ const now = fr.cursor.now(placed);
+ const top = m.tag + m.pad;
+ const shows = placed.value(fr.shows);
+ const passes = crossfade(now);
+ const n = fr.rows + fr.more;
+ for (0..n) |k| {
+ const second = k >= fr.rows;
+ const addr = fr.rowAddr(k);
+ const y = top + @as(f32, @floatFromInt(k)) * m.row;
+ const v = if (second) u else u.faded(shows);
+ if (is_tall) {
+ ties.anchor(u, .{ .row = addr }, .{ .x = 0, .y = y, .w = box.w, .h = m.row });
+ ties.anchor(u, .{ .word = addr }, .{ .x = eight.address, .y = y, .w = eight.first - eight.address, .h = m.row });
+ ties.anchor(u, .{ .slot_pin = addr }, .{ .x = theme.metric.slot.lane, .y = y, .w = theme.metric.slot.lane_end - theme.metric.slot.lane, .h = m.row });
+ // The word its eight bytes make, as shown: what an `aim` leaves from.
+ if (Recording.word(now.shownAt(addr, 8), addr, 8) catch null) |word| ties.show(u, word, .{ .x = eight.first, .y = y, .w = box.w - eight.first, .h = m.row }, .stack, addr, 0, box.w);
+ }
+ // A rule across between the two stretches: they are far apart.
+ if (second and k == fr.rows) u.fill(.{ .x = theme.stroke.rule, .y = y - 1, .w = box.w - 2 * theme.stroke.rule, .h = theme.stroke.rule }, theme.color.rule);
+ const lead = ui.shared(if (second) &.{ fr.then, fr.then + 8 * (fr.more -| 1) } else &.{ fr.first, fr.first + 8 * (fr.rows -| 1) });
+ // A row whose fields the step makes the frame's: its loose bytes going, its fields coming.
+ var q: f32 = 1;
+ for (fr.fields) |fl| if (fl.at < addr + 8 and fl.at + fl.len > addr) {
+ q = @min(q, live(now, fl.from));
+ };
+ for (passes.moments[0..passes.n], passes.shows[0..passes.n]) |moment, amount| {
+ if (q > 0) fr.row(v.faded(amount * q), now, moment, addr, y, lead, !second and fr.shadow, k, true);
+ if (q < 1) fr.row(v.faded(amount * (1 - q)), now, moment, addr, y, lead, !second and fr.shadow, k, false);
+ }
+ }
+ fr.pins(u, now, top);
+ if (fr.rowOf(fr.span[0])) |a| if (fr.rowOf(fr.span[1] - 8)) |b| {
+ rows.span(u.faded(live(now, fr.span_from)), box.w, top + @as(f32, @floatFromInt(a)) * m.row, top + @as(f32, @floatFromInt(b + 1)) * m.row, fr.name, true, false);
+ };
+ // `differs`: a bright bar on the seam-side edge of each row whose value its counterpart does not hold.
+ const bars = placed.value(fr.differs);
+ if (bars > 0) for (fr.differ) |addr| if (fr.rowOf(addr)) |k| {
+ const x: f32 = if (fr.side == .left) box.w - theme.stroke.rule - 4 else theme.stroke.rule;
+ u.faded(bars).fill(.{ .x = x, .y = top + @as(f32, @floatFromInt(k)) * m.row + 1, .w = 4, .h = m.row - 2 }, t.bright);
+ };
+ context.veiled(u, box, now.veil);
+ }
+
+ fn rowAddr(fr: *const Frame, k: usize) u64 {
+ return if (k >= fr.rows) fr.then + 8 * (k - fr.rows) else fr.first + 8 * k;
+ }
+
+ fn rowOf(fr: *const Frame, addr: u64) ?usize {
+ for (0..fr.rows + fr.more) |k| if (addr >= fr.rowAddr(k) and addr < fr.rowAddr(k) + 8) return k;
+ return null;
+ }
+
+ /// The field that holds byte `a`, if any.
+ fn fieldAt(fr: *const Frame, a: u64) ?Field {
+ for (fr.fields) |fl| if (a >= fl.at and a < fl.at + fl.len) return fl;
+ return null;
+ }
+
+ /// How many of the loop's letters stand from `letters` at `moment`.
+ fn lettered(fr: *const Frame, moment: Recording.Moment) u64 {
+ if (fr.letters == 0) return 0;
+ var buf: [64]u8 = undefined;
+ var known: [64]bool = undefined;
+ moment.read(fr.letters, &buf, &known) catch return 0;
+ var n: u64 = 0;
+ while (n < buf.len and known[n] and buf[n] == fr.letter) n += 1;
+ return n;
+ }
+
+ /// One row of eight bytes at `addr`, its values from `moment` (a write of
+ /// the step keeping its old bytes until its strike lands).
+ fn row(fr: *const Frame, u: ui.Ui, now: cursors.Now, moment: Recording.Moment, addr: u64, y: f32, lead: usize, shadowed: bool, k: usize, fielded: bool) void {
+ const b = eight;
+ const base = rows.baseline(y);
+ var values: [8]u8 = undefined;
+ var known: [8]bool = undefined;
+ moment.read(addr, &values, &known) catch return;
+ var was: [8]u8 = undefined;
+ var known_was: [8]bool = undefined;
+ now.before().read(addr, &was, &known_was) catch {
+ was = values;
+ known_was = known;
+ };
+ const letters_is = fr.lettered(moment);
+ const letters_was = fr.lettered(now.before());
+ if (shadowed) fr.shadowCell(u, now, moment, addr, y, k);
+ const region = rows.regionOf(moment, addr);
+ _ = u.address(b.address, base, addr, .{ .ink = ui.rgb(rows.ink(region)), .lead = lead });
+ // The runs: each field's part of the row, and the loose bytes between.
+ var j: u8 = 0;
+ var reading_x: f32 = b.reading;
+ while (j < 8) {
+ const here = addr + j;
+ const field = if (fielded) fr.fieldAt(here) else null;
+ var len: u8 = 1;
+ if (field) |fl| {
+ len = @intCast(@min(fl.at + fl.len - here, 8 - @as(u64, j)));
+ } else while (j + len < 8 and (!fielded or fr.fieldAt(here + len) == null)) len += 1;
+ const lo = j;
+ const hi = j + len;
+ // Until its strike lands (s+3) the run keeps its old bytes.
+ var shown = values;
+ var shown_known = known;
+ var letters_shown = letters_is;
+ if (now.struckAgo(here, len)) |ago| if (ago < theme.time.strike.in / 2.0) {
+ @memcpy(shown[lo..hi], was[lo..hi]);
+ @memcpy(shown_known[lo..hi], known_was[lo..hi]);
+ letters_shown = letters_was;
+ };
+ const heat = now.written(here, len, .memory, 0);
+ const changed = now.changedBytes(here, len);
+ var read: f32 = 0;
+ if (now.wasRead(here, len) and now.writeAge(here, len) != 0) read = now.reading(.memory, 0);
+ // Until this step's strike lands, the held corner stays on what the last write changed.
+ const held = if (now.struckAgo(here, len)) |ago| (if (ago < theme.time.strike.in / 2.0) changedBefore(now, here, len) else changed) else changed;
+ fr.bytes(u, y, addr, lo, hi, &shown, &shown_known, field, heat, changed, held, read, letters_shown, moment);
+ if (field) |fl| reading_x = fr.reading(u, now, y, reading_x, addr, lo, hi, fl, &values, &known, &was, &known_was, moment);
+ j = hi;
+ }
+ }
+
+ /// The bytes `lo .. hi` of the row at `addr`: paper for a field, the
+ /// strike's marks on the bytes the step changed, the digits in their ink.
+ fn bytes(fr: *const Frame, u: ui.Ui, y: f32, addr: u64, lo: u8, hi: u8, values: *const [8]u8, known: *const [8]bool, field: ?Field, h: ui.Heat, changed: ?[2]u8, held: ?[2]u8, read: f32, letters: u64, moment: Recording.Moment) void {
+ const base = rows.baseline(y);
+ const x0 = byteX(lo) - 4;
+ const x1 = byteX(hi - 1) + 28;
+ const r: Rect = .{ .x = x0, .y = y + 1, .w = x1 - x0, .h = m.row - 2 };
+ if (field != null) u.fill(r, theme.color.raised);
+ const c_lo: u8 = lo + if (changed) |c| c[0] else 0;
+ const c_hi: u8 = lo + if (changed) |c| c[1] else hi - lo - 1;
+ const s0 = byteX(c_lo) - 4;
+ const s1 = byteX(c_hi) + 28;
+ if (h.arm > 0) u.faded(h.arm).frame(.{ .x = s0 - 3, .y = y - 1, .w = s1 - s0 + 6, .h = m.row + 2 }, theme.mark(.write).solid, 2);
+ var solid_of: [8]f32 = @splat(0);
+ if (h.level >= 1 and h.solid > 0) for (c_lo..@as(usize, c_hi) + 1) |i| {
+ const solid = h.solid * std.math.clamp(h.in - @as(f32, @floatFromInt(i - c_lo)) / (60.0 * theme.time.strike.in), 0, 1);
+ solid_of[i] = solid;
+ if (solid <= 0) continue;
+ const bx0 = byteX(@intCast(i)) - 4 - if (i == c_lo) h.out else 0;
+ const bx1 = (if (i < c_hi) byteX(@intCast(i + 1)) - 4 else byteX(@intCast(i)) + 28) + if (i == c_hi) h.out else 0;
+ u.fill(.{ .x = bx0, .y = r.y - h.out, .w = bx1 - bx0, .h = r.h + 2 * h.out }, ui.mix(theme.color.raised, theme.color.struck, solid));
+ };
+ u.corner(byteX(lo + if (held) |c| c[0] else 0) - 4, y + 2, m.corner, h.level * h.corner);
+ if (read > 0) u.faded(read).frame(.{ .x = x0 - 3, .y = y - 1, .w = x1 - x0 + 6, .h = m.row + 2 }, theme.mark(.read).solid, 2);
+ // A pointer's bytes in the ink of where the whole word points; a number's primary; padding faint.
+ var word: u64 = 0;
+ if (field) |fl| if (fl.len == 8 and fl.reads == .pointer and fl.at >= addr and fl.at + 8 <= addr + 8) {
+ for (0..8) |i| word |= @as(u64, values[i]) << @intCast(8 * i);
+ };
+ const field_ink: u24 = if (field) |fl| switch (fl.reads) {
+ .pointer => rows.ink(rows.regionOf(moment, word)),
+ .text => theme.color.string,
+ .number => t.primary,
+ .bytes => t.primary,
+ } else t.dim;
+ var top: usize = lo;
+ for (lo..hi) |i| if (values[i] != 0) {
+ top = i;
+ };
+ for (lo..hi) |i| {
+ const x = byteX(@intCast(i));
+ if (!known[i]) {
+ u.fill(.{ .x = x + 5, .y = y + 11, .w = 4, .h = 4 }, t.faint);
+ u.fill(.{ .x = x + 15, .y = y + 11, .w = 4, .h = 4 }, t.faint);
+ continue;
+ }
+ const a = addr + i;
+ const letter = fr.letters != 0 and a >= fr.letters and a < fr.letters + letters;
+ const ink: u24 = if (letter) theme.color.string else field_ink;
+ const padding = field != null and field.?.reads != .text and !letter and i > top;
+ // Bright with the strike's paper, back to its ink as the paper cools (the face at the middle, where the colour moves fastest).
+ const c = ui.mix(if (padding) ui.mix(ink, theme.color.page, m.pad_alpha) else ui.rgb(ink), t.bright, solid_of[i]);
+ u.text(if (solid_of[i] >= 0.5) .mono_bold else .mono, size, x, base, u.print("{x:0>2}", .{values[i]}), c);
+ }
+ }
+
+ /// The reading of field `fl`'s part `lo .. hi` of the row at `addr`, from
+ /// `x`: its name, then what its bytes make; as the step's strike lands it
+ /// crossfades from what they made (6 f after, over 12 f). Returns where it ends.
+ fn reading(fr: *const Frame, u: ui.Ui, now: cursors.Now, y: f32, x: f32, addr: u64, lo: u8, hi: u8, fl: Field, values: *const [8]u8, known: *const [8]bool, was: *const [8]u8, known_was: *const [8]bool, moment: Recording.Moment) f32 {
+ _ = fr;
+ const whole = fl.at >= addr and fl.at + fl.len <= addr + 8;
+ const name = if (whole) fl.name else u.print("{s}[{d}..{d}]", .{ fl.name, addr + lo - fl.at, addr + hi - 1 - fl.at });
+ const micro = theme.size.sans.micro;
+ u.text(.sans, micro, x, rows.baseline(y) - 1, name, t.dim);
+ const vx = x + u.width(.sans, micro, name) + adv;
+ if (fl.reads == .bytes) return vx;
+ var q: f32 = 1;
+ if (now.struckAgo(addr + lo, hi - lo)) |ago| q = std.math.clamp((ago - 6.0 / 60.0) / theme.time.quick, 0, 1);
+ const same = std.mem.eql(u8, values[lo..hi], was[lo..hi]) and std.mem.eql(bool, known[lo..hi], known_was[lo..hi]);
+ if (same or q >= 1) return value(u.faded(1), vx, y, values[lo..hi], known[lo..hi], fl, moment);
+ const end_was = value(u.faded(1 - q), vx, y, was[lo..hi], known_was[lo..hi], fl, moment);
+ const end_is = value(u.faded(q), vx, y, values[lo..hi], known[lo..hi], fl, moment);
+ return @max(end_was, end_is);
+ }
+
+ /// What `bytes` (a field's, or its part on a row) make, read as `fl` says, at `x`.
+ fn value(u: ui.Ui, x: f32, y: f32, bytes_: []const u8, known: []const bool, fl: Field, moment: Recording.Moment) f32 {
+ if (std.mem.indexOfScalar(bool, known, false) != null) return x;
+ const base = rows.baseline(y);
+ var word: u64 = 0;
+ for (bytes_[0..@min(bytes_.len, 8)], 0..) |c, i| word |= @as(u64, c) << @intCast(8 * i);
+ switch (fl.reads) {
+ .bytes => return x,
+ .text => {
+ const text = quoted(u, bytes_);
+ u.text(.mono, size, x, base, text, theme.color.string);
+ return x + u.width(.mono, size, text);
+ },
+ .number => {
+ const bits: u6 = @intCast(64 - 8 * @as(u64, @min(bytes_.len, 8)));
+ const signed = @as(i64, @bitCast(word << bits)) >> bits;
+ const text = u.print("{d}", .{signed});
+ u.text(.mono, size, x, base, text, t.primary);
+ return x + u.width(.mono, size, text);
+ },
+ .pointer => {
+ // An address in its region's ink, and its name; once it is none, the number it is.
+ const region = rows.regionOf(moment, word);
+ if (region == .none) return u.value(x, base, word, false, .{});
+ // Its first hop, as a chain has it: a code address's name, a string's text.
+ const at = u.arrow(x, y + m.row / 2, .points);
+ return rows.chain(u, at, y, moment, word, eight.room, .{ .most = 1 }).end;
+ },
+ }
+ }
+
+ /// The row's shadow byte, at 62: its value (`f1` a frame's left
+ /// redzone, `f3` its right, `00` addressable) primary where it poisons,
+ /// faint where not; struck where the step wrote it, 2 f a row apart; framed
+ /// as read while a check loads it.
+ fn shadowCell(fr: *const Frame, u: ui.Ui, now: cursors.Now, moment: Recording.Moment, addr: u64, y: f32, k: usize) void {
+ _ = fr;
+ const sh = (zt.telescope.shadow(moment, addr) catch return) orelse return;
+ const delay = @as(f32, @floatFromInt(k)) * 2.0 / 60.0;
+ var shown = sh.value orelse return;
+ if (now.struckAgo(sh.addr, 1)) |ago| if (ago - delay < theme.time.strike.in / 2.0) {
+ if (zt.telescope.shadow(now.before(), addr) catch null) |old| shown = old.value orelse shown;
+ };
+ const cell: Rect = .{ .x = eight.shadow, .y = y, .w = 2 * adv, .h = m.row };
+ const h = now.written(sh.addr, 1, .memory, delay);
+ const ink = u.written(cell, h);
+ if (now.wasRead(sh.addr, 1)) u.read(cell, now.reading(.memory, 0));
+ const face: ui.Face = if (ink) |i| i.face else if (shown != 0) .mono_bold else .mono;
+ const c = if (ink) |i| i.ink else ui.rgb(if (shown != 0) t.primary else t.faint);
+ u.text(face, size, eight.shadow, rows.baseline(y), u.print("{x:0>2}", .{shown}), c);
+ }
+
+ /// rsp's and rbp's `row` pins, as the stack's: each at the row it points
+ /// into, travelling there with the step (as the stack's pins do, on
+ /// `glide`); one that leaves the rows fades.
+ fn pins(fr: *const Frame, u: ui.Ui, now: cursors.Now, top: f32) void {
+ const rec = fr.cursor.rec;
+ const names = [2][]const u8{ "rsp", "rbp" };
+ var ys: [2]?f32 = .{ null, null };
+ var shows: [2]f32 = .{ 0, 0 };
+ for (names, 0..) |name, k| {
+ const is = rec.register(now.stops[0], name);
+ const was = rec.register(now.stops[1], name);
+ const p = now.pinGone(k) orelse (if (now.resting()) 1 else std.math.clamp(now.since(.cpu, 0) / theme.time.tied.stack_pin, 0, 1));
+ const a = fr.rowOf(was);
+ const b = fr.rowOf(is);
+ const at = struct {
+ fn y(t0: f32, row_: usize) f32 {
+ return t0 + @as(f32, @floatFromInt(row_)) * m.row;
+ }
+ }.y;
+ if (a != null and b != null) {
+ ys[k] = std.math.lerp(at(top, a.?), at(top, b.?), cursors.glide(p));
+ shows[k] = 1;
+ } else if (b) |row_| {
+ ys[k] = at(top, row_);
+ shows[k] = p;
+ } else if (a) |row_| {
+ ys[k] = at(top, row_);
+ shows[k] = 1 - p;
+ }
+ }
+ const ink = theme.color.region.stack;
+ // rbp and rsp on one row: one pin, in pwndbg's order; a name joining or leaving it crossfades.
+ if (ys[0] != null and ys[1] != null and @abs(ys[0].? - ys[1].?) < 1) {
+ const both = @min(shows[0], shows[1]);
+ u.faded(both).pinRow(eight.pin, ys[0].?, &.{ "rbp", "rsp" }, ink);
+ const alone: usize = if (shows[0] > shows[1]) 0 else 1;
+ u.faded(@max(shows[0], shows[1]) - both).pinRow(eight.pin, ys[0].?, &.{names[alone]}, ink);
+ return;
+ }
+ for ([2]usize{ 1, 0 }) |k| if (ys[k]) |py| u.faded(shows[k]).pinRow(eight.pin, py, &.{names[k]}, ink);
+ }
+};
+
+/// Of `addr .. addr + len` (8 at most), the first and last byte (from
+/// `addr`) the newest write before this step changed: where its held corner is.
+fn changedBefore(now: cursors.Now, addr: u64, len: u64) ?[2]u8 {
+ const rec = now.rec;
+ for (1..now.stops.len - 1) |age| {
+ if (!Recording.touches(rec.written(now.stops[age + 1], now.stops[age]), addr, len)) continue;
+ var was: [8]u8 = undefined;
+ var is: [8]u8 = undefined;
+ var kw: [8]bool = undefined;
+ var ki: [8]bool = undefined;
+ const l: usize = @intCast(@min(len, 8));
+ rec.moment(now.stops[age + 1]).read(addr, was[0..l], kw[0..l]) catch return null;
+ rec.moment(now.stops[age]).read(addr, is[0..l], ki[0..l]) catch return null;
+ var out: ?[2]u8 = null;
+ for (0..l) |i| if (kw[i] and ki[i] and was[i] != is[i]) {
+ const first: u8 = if (out) |o| o[0] else @intCast(i);
+ out = .{ first, @intCast(i) };
+ };
+ return out;
+ }
+ return null;
+}
+
+/// `eight`'s columns (design/README.md, `hexdump`).
+const eight = struct {
+ const pin = 12;
+ const shadow = 62;
+ const address = 118;
+ const first = 274;
+ const pitch = 30;
+ const reading = 522;
+ /// Where a reading ends: before the span's name (`fill`) and its bracket.
+ const room = 820;
+};
+
+fn byteX(i: u8) f32 {
+ return eight.first + @as(f32, @floatFromInt(i)) * eight.pitch;
+}
+
+/// The memory a frame draws now, and how much each shows: at a run, what
+/// the step changed crossfades over 8 f, unmarked (`hexdump`'s own).
+const Passes = struct { moments: [2]Recording.Moment, shows: [2]f32, n: usize };
+fn crossfade(now: cursors.Now) Passes {
+ if (now.plan.gait == .run and !now.resting()) {
+ const q = std.math.clamp(now.since(.memory, 0) / theme.time.run_ease, 0, 1);
+ if (q > 0 and q < 1) return .{ .moments = .{ now.before(), now.moment() }, .shows = .{ 1 - q, q }, .n = 2 };
+ }
+ return .{ .moments = .{ now.shown(.memory), undefined }, .shows = .{ 1, 0 }, .n = 1 };
+}
+
+/// Bytes as C text, in quotes, to the first NUL.
+fn quoted(u: ui.Ui, bytes_: []const u8) []const u8 {
+ var out: std.ArrayList(u8) = .empty;
+ const a = u.f.scratch;
+ out.append(a, '"') catch return "";
+ for (bytes_) |c| {
+ if (c == 0) break;
+ if (std.ascii.isPrint(c) and c != '"' and c != '\\') out.append(a, c) catch {} else out.print(a, "\\x{x:0>2}", .{c}) catch {};
+ }
+ out.append(a, '"') catch {};
+ return out.items;
+}
+
+/// The address of ASan's shadow for `addr`'s granule: `(addr >> 3) + offset`, as the recording says it.
+pub fn shadowOffset(rec: *const Recording) ?u64 {
+ const sh = (zt.telescope.shadow(rec.moment(0), 0) catch return null) orelse return null;
+ return sh.addr;
+}
+
+/// A run's output as it wrote it (`write(2, …)`, from a recording that has
+/// its system calls), in place of its registers and its disassembly's lower
+/// rows once it has stopped (the stage's `view`): the lines the scene
+/// names (`lines`: each the first that holds the text), as written, cut at
+/// the panel's edge with `…`; the words the narration names framed bright,
+/// one after another as `framed` (0 to their count) goes.
+pub const Report = struct {
+ /// The recording of the run by system call.
+ rec: *const Recording,
+ stage: *const Stage,
+ title: []const u8,
+ lines: []const []const u8,
+ words: []const []const u8 = &.{},
+ framed: anim.Value,
+
+ /// What it wrote to fd 2, all of it.
+ pub fn stderr(rec: *const Recording, a: std.mem.Allocator) []const u8 {
+ var out: std.ArrayList(u8) = .empty;
+ for (rec.syscalls) |c| if (c.nr == 1 and c.args[0] == 2) out.appendSlice(a, c.text) catch {};
+ return out.items;
+ }
+
+ /// How it ended: the status it gave `exit_group`.
+ pub fn status(rec: *const Recording) ?u64 {
+ for (rec.syscalls) |c| if (c.nr == 231) return c.args[0];
+ return null;
+ }
+
+ pub fn draw(r: *const Report, f: *sk.Frame, placed: anim.Placed) void {
+ const box = r.stage.box(placed, .view);
+ if (box.h < m.tag + m.row) return;
+ const u = context.at(f, placed, box);
+ const exit = if (status(r.rec)) |st| u.print("its report, as written \u{00b7} exit {d}", .{st}) else "its report, as written";
+ _ = u.panel(box.w, box.h, r.title, .{ .note = exit });
+ context.clipBody(u, box);
+ defer u.unclip();
+ const all = stderr(r.rec, u.f.scratch);
+ const room = box.w - 2 * m.side;
+ const framed = placed.value(r.framed);
+ var k: usize = 0;
+ var word: usize = 0;
+ for (r.lines) |want| {
+ var it = std.mem.splitScalar(u8, all, '\n');
+ const line = while (it.next()) |l| {
+ if (std.mem.indexOf(u8, l, want) != null) break l;
+ } else continue;
+ const y = m.tag + m.pad + @as(f32, @floatFromInt(k)) * m.row;
+ const shown = rows.fitted(u, line, room);
+ u.text(.mono, size, m.side, rows.baseline(y), shown, t.primary);
+ // The words the narration names, framed bright where the line shows them whole.
+ for (r.words) |w| if (std.mem.indexOf(u8, line, w)) |at| {
+ defer word += 1;
+ const chars = std.unicode.utf8CountCodepoints(line[0..at]) catch at;
+ if (@as(f32, @floatFromInt(chars + w.len)) * adv > room - adv) continue;
+ const shows = std.math.clamp(framed - @as(f32, @floatFromInt(word)), 0, 1);
+ if (shows > 0) u.faded(shows).frame(.{ .x = m.side + @as(f32, @floatFromInt(chars)) * adv - 3, .y = y, .w = @as(f32, @floatFromInt(w.len)) * adv + 6, .h = m.row }, t.bright, theme.stroke.rule);
+ };
+ k += 1;
+ }
+ }
+};
+
+/// The pair's marks across the seam, over its panels: the right run's mark
+/// on the shared source (ranged right, a gold plaque pointing left, `asan`
+/// before it), the `only here` bars on the right run's rows that no row of
+/// the left faces, the two first rows that differ framed `attention` where
+/// they part, and a fault on the left run's row (`fault`: hazard bands round
+/// an ink plaque naming the signal; rip stays).
+pub const Marks = struct {
+ left: cursors.Cursor,
+ right: cursors.Cursor,
+ stages: [2]*const Stage,
+ /// The right run's name, by its mark on the source.
+ name: []const u8,
+ /// The right run's rows no row of the left faces.
+ only: []const u64,
+ /// The rows framed `attention` (the left's, the right's), and how much.
+ attend: [2]u64 = .{ 0, 0 },
+ attention: anim.Value,
+ /// How much the right run's marks show (it folds to the shelf while the left goes on alone).
+ right_shows: anim.Value,
+ /// The left run's fault: the moment its signal stops it, the row, its name.
+ fault: ?struct { at: u64, pc: u64, name: []const u8 } = null,
+
+ pub fn draw(mk: *const Marks, f: *sk.Frame, placed: anim.Placed) void {
+ mk.sourceMark(f, placed);
+ // `only here`: a dim bar on the seam-side (left) edge of the right run's rows.
+ const dbox = mk.stages[1].box(placed, .disasm);
+ const du = context.at(f, placed, dbox);
+ const rnow = mk.right.now(placed);
+ const right = placed.value(mk.right_shows);
+ context.clipBody(du, dbox);
+ const k = placed.scale;
+ const origin = du.at.xf.apply(.{ 0, 0 });
+ for (mk.only) |addr| if (ties.find(f, .{ .row = addr })) |r| {
+ const y = (r[1] - origin[1]) / k;
+ du.faded(right * (1 - 0.5 * rnow.veil)).fill(.{ .x = theme.stroke.rule, .y = y + 1, .w = 4, .h = m.row - 2 }, t.dim);
+ };
+ du.unclip();
+ const shows = placed.value(mk.attention);
+ if (shows > 0) for (mk.attend, 0..) |addr, side| if (ties.find(f, .{ .row = addr })) |r| {
+ const b = mk.stages[side].box(placed, .disasm);
+ const v = context.at(f, placed, b);
+ const o = v.at.xf.apply(.{ 0, 0 });
+ v.faded(shows).frame(.{ .x = 0, .y = (r[1] - o[1]) / k - 1, .w = b.w, .h = m.row + 2 }, theme.mark(.attention).solid, theme.stroke.rule);
+ };
+ if (mk.fault) |fault| mk.faultMark(f, placed, fault.at, fault.pc, fault.name);
+ }
+
+ /// The right run's mark on the shared source: its line's row, gliding with its advance.
+ fn sourceMark(mk: *const Marks, f: *sk.Frame, placed: anim.Placed) void {
+ const box = mk.stages[0].box(placed, .source);
+ if (box.h < m.tag + m.row) return;
+ const u = context.at(f, placed, box);
+ const lnow = mk.left.now(placed);
+ const rnow = mk.right.now(placed);
+ const lrec = mk.left.rec;
+ const rrec = mk.right.rec;
+ const fit: u32 = @intCast(theme.layout.rowsIn(box.h));
+ // The window, as the left's source has it (`Source`).
+ const going = lnow.advancing();
+ const windows = [2]f32{ @floatFromInt(lrec.shownFirst(fit, lrec.shown[lnow.marks[0]])), @floatFromInt(lrec.shownFirst(fit, lrec.shown[lnow.marks[1]])) };
+ const first = std.math.lerp(windows[0], windows[1], cursors.glide(going));
+ const at = [2]Recording.Shown{ rrec.shown[rnow.marks[0]], rrec.shown[rnow.marks[1]] };
+ if (at[1].line == 0) return;
+ const p = rnow.advancing();
+ var line: f32 = @floatFromInt(at[1].line);
+ var shows: f32 = 1;
+ if (at[0].line != at[1].line and p < 1 and at[0].line != 0) {
+ if (cursors.jumps(rrec, rnow.marks[0], rnow.marks[1])) {
+ // Into a call or out of one: out there, then in here.
+ line = @floatFromInt(if (p < 0.5) at[0].line else at[1].line);
+ shows = @abs(2 * p - 1);
+ } else line = std.math.lerp(@as(f32, @floatFromInt(at[0].line)), line, cursors.standard(p));
+ }
+ const y = m.tag + m.pad + (line - first) * m.row;
+ if (y < m.tag or y + m.row > box.h) return;
+ const gold = theme.mark(.current);
+ const w = theme.metric.plaque.pc;
+ const x = box.w - theme.stroke.rule - w;
+ const v = u.faded(shows * placed.value(mk.right_shows));
+ v.fill(.{ .x = x, .y = y, .w = w, .h = m.row }, gold.solid);
+ sk.draw.polygon(u.f, &.{ .{ x + 7, y + m.row / 2 }, .{ x + 17, y + 6 }, .{ x + 17, y + m.row - 6 } }, v.at.pen(.{ .fill = ui.rgb(gold.on_solid) }));
+ const micro = theme.size.sans.micro;
+ v.text(.sans_medium, micro, x - 10 - u.width(.sans_medium, micro, mk.name), rows.baseline(y) - 1, mk.name, t.dim);
+ }
+
+ /// `fault` on the row at `pc` in the left run's disassembly, from the
+ /// step that stops it at `at`: hazard bands round an ink plaque naming
+ /// the signal, in 12 f once the step has fired, at the row's right end.
+ fn faultMark(mk: *const Marks, f: *sk.Frame, placed: anim.Placed, at: u64, pc: u64, name: []const u8) void {
+ const now = mk.left.now(placed);
+ if (now.stops[0] < at) return;
+ const r = ties.find(f, .{ .row = pc }) orelse return;
+ var shows: f32 = 1;
+ if (now.stops[0] == at and !now.resting()) shows = std.math.clamp((now.time - theme.time.fire - theme.time.snap) / theme.time.quick, 0, 1);
+ if (shows <= 0) return;
+ const box = mk.stages[0].box(placed, .disasm);
+ const u = context.at(f, placed, box);
+ const o = u.at.xf.apply(.{ 0, 0 });
+ const y = (r[1] - o[1]) / placed.scale;
+ const band = theme.stroke.hazard;
+ const tw = u.width(.mono_bold, size, name);
+ const w = tw + 2 * 10 + 2 * band;
+ // Where its operands would be: `ret` has none, and its annotation goes on after it.
+ const x: f32 = theme.metric.insn.operands - band;
+ const v = u.faded(shows);
+ const outer: Rect = .{ .x = x, .y = y - 2, .w = w, .h = m.row + 4 };
+ // The bands: vermilion and ink at 45 degrees, 12 each, clipped to the plaque's frame.
+ v.fill(outer, t.ink);
+ v.clip(outer);
+ const fault = theme.mark(.fault).solid;
+ var bx: f32 = x - outer.h;
+ while (bx < x + w) : (bx += 2 * band) {
+ sk.draw.polygon(u.f, &.{ .{ bx, outer.y + outer.h }, .{ bx + band, outer.y + outer.h }, .{ bx + band + outer.h, outer.y }, .{ bx + outer.h, outer.y } }, v.at.pen(.{ .fill = ui.rgb(fault) }));
+ }
+ v.unclip();
+ const inner: Rect = .{ .x = x + band, .y = y + 1, .w = w - 2 * band, .h = m.row - 2 };
+ v.fill(inner, t.ink);
+ v.text(.mono_bold, size, inner.x + 10, rows.baseline(y), name, t.bright);
+ }
+};
+
+/// A run that has stopped, folded to one tag on the column's shelf (y 48,
+/// ranged right in the panes' column) while the other goes on alone: its
+/// panes' frame crossfading in at their boxes as they go (`fold` 0 to 1),
+/// then travelling to the tag (1 to 2, `glide`), the note coming as it lands;
+/// unfolding, the same backwards.
+pub const Shelf = struct {
+ stage: *const Stage,
+ title: []const u8,
+ note: []const u8,
+ fold: anim.Value,
+
+ pub fn draw(sh: *const Shelf, f: *sk.Frame, placed: anim.Placed) void {
+ const fold = placed.value(sh.fold);
+ if (fold <= 0) return;
+ const disasm = sh.stage.box(placed, .disasm);
+ const frame = sh.stage.box(placed, .stack);
+ const from: Rect = .{ .x = disasm.x, .y = disasm.y, .w = disasm.w, .h = frame.y + frame.h - disasm.y };
+ const u = context.at(f, placed, .{ .x = 0, .y = 0, .w = theme.canvas.width, .h = theme.canvas.height });
+ const sans = theme.size.sans;
+ const w = 28 + u.width(.sans_medium, sans.tag, sh.title) + 12 + u.width(.sans, sans.micro, sh.note) + 12;
+ const slot: Rect = .{ .x = theme.layout.program.x + theme.layout.program.w - w, .y = theme.canvas.stage.y, .w = w, .h = m.tag };
+ const on = theme.ease(.glide, std.math.clamp(fold - 1, 0, 1));
+ const r: Rect = .{ .x = std.math.lerp(from.x, slot.x, on), .y = std.math.lerp(from.y, slot.y, on), .w = std.math.lerp(from.w, slot.w, on), .h = std.math.lerp(from.h, slot.h, on) };
+ const v = u.moved(r.x, r.y).faded(std.math.clamp(fold, 0, 1));
+ _ = v.panel(r.w, r.h, sh.title, .{});
+ const shows = std.math.clamp((on - 0.75) * 4, 0, 1);
+ if (shows > 0) v.faded(shows).text(.sans, sans.micro, 28 + v.width(.sans_medium, sans.tag, sh.title) + 12, m.tag - 6, sh.note, t.faint);
+ }
+};
+
+/// The pair's clock: one rule, gold along it as far as the left run has
+/// come (its steps are the pair's), still while a step plays, the step's
+/// piece fading in once its mark has landed (`words.Clock`); under its right
+/// end the turn and each run's moment.
+pub const Clock = struct {
+ left: cursors.Cursor,
+ right: cursors.Cursor,
+ names: [2][]const u8,
+ /// The loop's counter, where the left run keeps it (0: none), from the moment it counts.
+ counter: u64 = 0,
+ counting: u64 = 0,
+ /// The left run's stage: in the column (`Stage.column`) the clock is under the text column alone.
+ stage: ?*const Stage = null,
+ box: Rect = .{ .x = theme.canvas.stage.x, .y = theme.canvas.clock_y - 12, .w = theme.canvas.stage.w, .h = 24 },
+
+ pub fn draw(k: *const Clock, f: *sk.Frame, at: anim.Placed) void {
+ const u = words.fixed(f, at, 0);
+ const c = theme.canvas;
+ const now = k.left.now(at);
+ const rnow = k.right.now(at);
+ var stage = c.stage;
+ const in_column = if (k.stage) |st| at.value(st.column) else 0;
+ stage.x = std.math.lerp(c.stage.x, theme.layout.state.x, theme.ease(.glide, in_column));
+ stage.w = c.stage.x + c.stage.w - stage.x;
+ u.fill(.{ .x = stage.x, .y = c.clock_y - 1, .w = stage.w, .h = theme.stroke.rule }, theme.color.rule);
+ const gold = theme.mark(.current).solid;
+ const place = struct {
+ fn of(n: cursors.Now, moment: u64) f32 {
+ return std.math.clamp(@as(f32, @floatFromInt(moment -| n.way[0])) / @as(f32, @floatFromInt(@max(n.way[1] -| n.way[0], 1))), 0, 1);
+ }
+ }.of;
+ if (now.plan.gait == .sprint or now.resting()) {
+ u.fill(.{ .x = stage.x, .y = c.clock_y - 2, .w = stage.w * now.place, .h = 4 }, gold);
+ } else {
+ const landed = now.plan.advance + now.plan.travel;
+ const fade = std.math.clamp((now.time - landed) / @as(f32, if (now.plan.gait == .run) theme.time.run_ease else theme.time.quick), 0, 1);
+ const from = place(now, now.stops[1]);
+ const to = place(now, now.stops[0]);
+ u.fill(.{ .x = stage.x, .y = c.clock_y - 2, .w = stage.w * from, .h = 4 }, gold);
+ if (fade > 0) u.fill(.{ .x = stage.x + stage.w * from, .y = c.clock_y - 2, .w = stage.w * (to - from), .h = 4 }, ui.mix(theme.color.page, gold, fade));
+ }
+ // Each count changes as its run's step lands, never in the middle of a step.
+ const counts = [2]u64{ counted(now), counted(rnow) };
+ var text = u.print("{s} moment {d} \u{00b7} {s} moment {d}", .{ k.names[0], counts[0] -| now.way[0], k.names[1], counts[1] -| rnow.way[0] });
+ if (k.counter != 0 and counts[0] >= k.counting) if (Recording.word(k.left.rec.moment(counts[0]), k.counter, 4) catch null) |i| {
+ const turn: i32 = @bitCast(@as(u32, @truncate(i)));
+ if (turn >= 0 and turn <= 64) text = u.print("i {d} \u{00b7} {s}", .{ turn, text });
+ };
+ u.text(.mono, size, stage.x + stage.w - u.width(.mono, size, text), c.clock_y + 28, text, t.faint);
+ }
+
+ fn counted(n: cursors.Now) u64 {
+ if (n.resting() or n.plan.gait == .sprint) return n.marked();
+ return if (n.time >= n.plan.advance + n.plan.travel) n.stops[0] else n.stops[1];
+ }
+};