From 60e07feef401d9044db3a1c925cb9d1f6d20dac9 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 11 Nov 2026 23:46:02 -0300 Subject: 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 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- anim/src/regroup.zig | 348 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 348 insertions(+) create mode 100644 anim/src/regroup.zig (limited to 'anim/src/regroup.zig') diff --git a/anim/src/regroup.zig b/anim/src/regroup.zig new file mode 100644 index 0000000..431abd8 --- /dev/null +++ b/anim/src/regroup.zig @@ -0,0 +1,348 @@ +//! The introduction's dump (design/motion.md, "A scene: the introduction", +//! chapter I; "A word read"; mocks 29, 30, 37): the 128 bytes at the top of +//! the stack, where the stack panel will stand (the state column), and the +//! verbs that make words of them, each a clock the scene plays (frames, +//! linear): +//! +//! - `in`: the rows arrive, sixteen bytes a row, 18 f each, 12 f apart; no +//! ink, the addresses faint. +//! - `regroup` (design/README.md, 6. Verbs): sixteen a row to eight, the +//! return address walked (its offsets, `low byte`, `high byte`, its bytes +//! flying low byte first on nested arcs to its word's field, the gaps +//! closing, `zeros in front`), the other fifteen at a run. +//! - `framed`: three words that hold addresses framed as read, 30 f apart. +//! - `fold`: the rows out (6 f), the dump's tag to the shelf (18 f, `glide`); back. +//! - `ink` (6. Verbs): a word's digits to its region's ink, the walked one +//! framed with its bytes (its band in `segments` is the scene's echo); +//! the rest at a run, 2 f apart. +//! - `left`: the words to their field's left (24 f, `glide`); `chains`: +//! three chains grow (`extend`), 36 f apart. +//! +//! Every byte and word from the recording at its moment. +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 Recording = @import("Recording.zig"); +const theme = ui.theme; +const Rect = ui.Rect; +const t = theme.color.text; + +pub const words = 16; +const size = theme.size.mono.context; +const adv = ui.advance(size); +const pitch = theme.metric.context.row; + +/// Where it stands: the state column, its rows from `top`; the bytes 12 +/// after the address, 30 apart, 12 more after the eighth; the word's field +/// eight pairs wide, 48 after the bytes, its words ranged right. +pub const at = struct { + pub const column = theme.layout.state.x; + pub const address = column + 24; + pub const bytes = address + 12 * adv + 12; + pub const pair = theme.metric.bytes.pitch; + pub const middle = theme.metric.bytes.middle; + pub const field = bytes + 7 * pair + 24 + 48; + pub const field_end = field + 7 * pair + 24; + pub const top = 96; + /// The tie's bracket, left of the addresses. + pub const bracket = address - 12; +}; + +/// Bytes drawn 50% toward the page: what stays of where a word's bytes were. +fn dimmed() ui.Color { + return ui.mix(theme.color.page, t.primary, 0.5); +} + +fn clamp01(x: f32) f32 { + return std.math.clamp(x, 0, 1); +} + +fn glide(x: f32) f32 { + return theme.ease(.glide, clamp01(x)); +} + +pub const Words = struct { + rec: *const Recording, + at: u64, + in: anim.Value, + regroup: anim.Value, + framed: anim.Value, + fold: anim.Value, + /// 0 to 1: the rows' addresses take the stack's ink (the dump tied to its place). + placed: anim.Value, + ink: anim.Value, + left: anim.Value, + chains: anim.Value, + /// The word walked (the return address), the three framed and chained, top down. + walked: usize, + three: [3]usize, + /// 0 to 1: the rows glide to the stack panel's (chapter II): the panel's + /// left, its first row's top and that row's address; the bytes and the + /// chains' hops go in the first half, each address to the slot's + /// address, each word to where the slot's chain has it. + become: anim.Value, + panel: struct { x: f32 = 0, top: f32 = 0, first: u64 = 0 } = .{}, + + pub fn init(s: *anim.Frame, rec: *const Recording, moment: u64) Words { + const picked = pick(rec, moment); + return .{ .rec = rec, .at = moment, .in = s.value(-1), .regroup = s.value(-1), .framed = s.value(-1), .fold = s.value(0), .placed = s.value(0), .ink = s.value(-1), .left = s.value(-1), .chains = s.value(-1), .walked = picked.walked, .three = picked.three, .become = s.value(0) }; + } + + /// The return address the newest frame has, and the first word that + /// points into the heap, into the stack, and the return address, top down. + pub fn pick(rec: *const Recording, moment: u64) struct { walked: usize, three: [3]usize } { + const m = rec.moment(moment); + const rsp = rec.register(moment, "rsp"); + var walked: usize = 0; + if (m.regs(rec.tid) catch null) |regs| { + var slots: [words]zt.telescope.Slot = undefined; + if (zt.telescope.slots(m, ®s, rsp, &slots)) |found| { + for (found, 0..) |slot, i| if (slot.role == .return_address) { + walked = i; + break; + }; + } else |_| {} + } + const values = read(rec, moment); + var heap: ?usize = null; + var stack: ?usize = null; + for (values.words, 0..) |v, i| switch (rows.regionOf(m, v)) { + .heap => heap = heap orelse i, + .stack => stack = stack orelse i, + else => {}, + }; + var three = [3]usize{ heap orelse 0, stack orelse 1, walked }; + std.mem.sort(usize, &three, {}, std.sort.asc(usize)); + return .{ .walked = walked, .three = three }; + } + + pub const Bytes = struct { base: u64, bytes: [8 * words]u8, known: [8 * words]bool, words: [words]u64 }; + + pub fn read(rec: *const Recording, moment: u64) Bytes { + var out: Bytes = .{ .base = rec.register(moment, "rsp"), .bytes = undefined, .known = undefined, .words = undefined }; + rec.moment(moment).read(out.base, &out.bytes, &out.known) catch @memset(&out.known, false); + for (&out.words, 0..) |*w, i| w.* = std.mem.readInt(u64, out.bytes[i * 8 ..][0..8], .little); + return out; + } + + /// Word `i`'s row's top, its bytes' first x, and how much its address shows, at regroup clock `r`. + fn where(i: usize, r: f32) struct { y: f32, x: f32, address: f32 } { + const row: f32 = @floatFromInt(i / 2); + const half: f32 = @floatFromInt(i % 2); + const a = glide(r / 18); + const b = glide((r - 18) / 12); + const c = glide((r - 30) / 18); + return .{ + .y = at.top + pitch * (row + row * a + half * b), + .x = at.bytes + half * (8 * at.pair + at.middle) * (1 - c), + .address = if (half == 0) 1 else clamp01((r - 36) / 12), + }; + } + + /// The word's text: its hex without the zeros in front. + fn digits(u: ui.Ui, v: u64) []const u8 { + return u.print("{x}", .{v}); + } + + pub fn draw(w: *const Words, f: *sk.Frame, placed: anim.Placed) void { + const u: ui.Ui = .{ .f = f, .at = placed }; + const in = placed.value(w.in); + if (in < 0) return; + const was = @import("segments.zig").clipStage(f, placed); + defer @import("segments.zig").unclipStage(f, was); + const r = placed.value(w.regroup); + const fold = placed.value(w.fold); + const shown = 1 - clamp01(fold / 6); + w.tag(u, fold); + if (shown <= 0) return; + const v = u.faded(shown); + const data = read(w.rec, w.at); + const m = w.rec.moment(w.at); + // The header (mock 29), with the first row; gone as the dump is tied to its place. + const header = clamp01(in / 18) * (1 - placed.value(w.placed)); + if (header > 0) v.faded(header).text(.sans, theme.size.sans.micro, at.address, at.top - 12, "128 bytes, from where rsp points", t.faint); + + // The veil over every row but the walked one, while it is walked. + const veil = clamp01((r - 48) / 18) - clamp01((r - 270) / 18); + const address_ink = ui.mix(t.faint, theme.color.region.stack, placed.value(w.placed)); + const become = placed.value(w.become); + const g = glide(become); + for (0..words) |i| { + const p = where(i, r); + const arrive = clamp01((in - 12 * @as(f32, @floatFromInt(i / 2))) / 18); + if (arrive <= 0) continue; + const row = v.faded(arrive * (if (i == w.walked) 1 else 1 - theme.color.veil_alpha * veil)); + const slot: f32 = @floatFromInt(@as(i64, @bitCast(data.base + 8 * i -% w.panel.first)) >> 3); + const y = std.math.lerp(p.y, w.panel.top + pitch * slot, g); + const base = theme.baseline(y, pitch, size); + const ax = std.math.lerp(at.address, w.panel.x + theme.metric.slot.address, g); + if (p.address > 0) _ = row.faded(p.address).address(ax, base, data.base + 8 * i, .{ .ink = address_ink }); + w.drawBytes(row.faded(1 - clamp01(become * 2)), data, i, p.x, base, r, placed); + w.drawWord(row, m, data.words[i], i, y, r, placed); + } + if (r >= 0) w.walk(v, data, r); + // The three words framed as read, 30 f apart, each in over 6 f. + const framed = placed.value(w.framed); + if (framed >= 0) for (w.three, 0..) |i, k| { + const shows = clamp01((framed - 30 * @as(f32, @floatFromInt(k))) / 6); + if (shows > 0) v.read(w.wordRect(i, data.words[i], placed), shows); + }; + } + + /// Word `i`'s digits as they stand in the field (ranged right, or at its left). + fn wordRect(w: *const Words, i: usize, value: u64, placed: anim.Placed) Rect { + const n: f32 = @floatFromInt(ui.digits(value)); + const left = glide(placed.value(w.left) / 24); + const x = std.math.lerp(at.field_end - n * adv, at.field, left); + return .{ .x = x, .y = at.top + pitch * @as(f32, @floatFromInt(i)), .w = n * adv, .h = pitch }; + } + + fn drawBytes(w: *const Words, u: ui.Ui, data: Bytes, i: usize, x: f32, base: f32, r: f32, placed: anim.Placed) void { + // Its bytes dim as its word comes in (the run), or are left faint where they flew from. + const dim = if (i == w.walked) 0 else w.runIn(i, r); + for (0..8) |k| { + const bx = x + @as(f32, @floatFromInt(k)) * at.pair; + const b = i * 8 + k; + if (i == w.walked and r >= 108) { + // In flight or landed: a faint copy fades into its place from a third of its flight. + const copy = clamp01((r - 120 - 6 * @as(f32, @floatFromInt(k))) / 12); + if (copy > 0) u.faded(copy).text(.mono, size, bx, base, u.print("{x:0>2}", .{data.bytes[b]}), dimmed()); + continue; + } + const text = if (data.known[b]) u.print("{x:0>2}", .{data.bytes[b]}) else "??"; + u.text(.mono, size, bx, base, text, ui.mix(ui.rgb(t.primary), dimmed(), dim)); + } + // The walked word's bytes framed with its word as it takes its ink. + if (i == w.walked) { + const shows = w.walkedFrame(placed); + if (shows > 0) u.read(.{ .x = x, .y = base - 7.2 - pitch / 2, .w = 7 * at.pair + 2 * adv, .h = pitch }, shows); + } + } + + /// How far the run has brought word `i` in (its word in, its bytes dim): 8 f, rows 6 f apart. + fn runIn(w: *const Words, i: usize, r: f32) f32 { + const q: f32 = @floatFromInt(if (i > w.walked) i - 1 else i); + return clamp01((r - 288 - 6 * q) / 8); + } + + fn walkedFrame(w: *const Words, placed: anim.Placed) f32 { + const ink = placed.value(w.ink); + if (ink < 0) return 0; + return clamp01(ink / 6) * (1 - clamp01((ink - 72 - 2 * words - 12) / 18)); + } + + fn drawWord(w: *const Words, u: ui.Ui, m: Recording.Moment, value: u64, i: usize, y: f32, r: f32, placed: anim.Placed) void { + const shows = if (i == w.walked) @as(f32, if (r >= 240) 1 else 0) else w.runIn(i, r); + if (shows <= 0) return; + const v = u.faded(shows); + const kind = rows.regionOf(m, value); + // `ink`: the walked word first (12 f), the rest at a run, 2 f apart, rows top down. + const ink_clock = placed.value(w.ink); + const order: f32 = @floatFromInt(if (i == w.walked) 0 else 72 + 2 * (if (i > w.walked) i - 1 else i)); + const inked = if (ink_clock < 0) 0 else clamp01((ink_clock - order) / 12); + const ink = ui.mix(t.primary, rows.ink(kind), inked); + var rect = w.wordRect(i, value, placed); + const g = glide(placed.value(w.become)); + rect.y = y; + rect.x = std.math.lerp(rect.x, w.panel.x + theme.metric.slot.address + 12 * adv + theme.metric.context.arrow_w, g); + const base = theme.baseline(y, pitch, size); + // `extend`: three chains grow from their word, 36 f apart. + const chains = placed.value(w.chains); + const k = std.mem.indexOfScalar(usize, &w.three, i); + if (chains >= 0 and k != null and kind != .none) { + const since = (chains - 36 * @as(f32, @floatFromInt(k.?))) / 60; + if (since >= 0 and (kind == .code or kind == .rwx)) { + // A code address's chain is its name: it comes in as a hop does (6 f). + const end = v.address(rect.x, base, value, .{ .ink = ink, .rwx = kind == .rwx }); + var name_buf: [128]u8 = undefined; + if (m.string(value, &name_buf) catch null) |name| v.faded(clamp01(since * 10)).text(.mono, size, end + 10, base, ui.symbol(u, name), t.primary); + return; + } + if (since >= 0) { + _ = rows.chain(v, rect.x, y, m, value, theme.layout.state.x + theme.layout.state.w, .{ .extend = since, .hops = 1 - clamp01(placed.value(w.become) * 2) }); + return; + } + } + if (kind == .none) v.text(.mono, size, rect.x, base, digits(u, value), ink) else _ = v.address(rect.x, base, value, .{ .ink = ink, .rwx = kind == .rwx }); + const frame = if (i == w.walked) w.walkedFrame(placed) else 0; + if (frame > 0) v.read(rect, frame); + } + + /// The walked word, from its offsets to its sixteen digits (motion.md, "A word read"). + fn walk(w: *const Words, u: ui.Ui, data: Bytes, r: f32) void { + if (r < 66 or r >= 240) return; + const y = at.top + pitch * @as(f32, @floatFromInt(w.walked)); + const base = theme.baseline(y, pitch, size); + const value = data.words[w.walked]; + // Under the row, its offsets and labels on the page (the veiled rows under them give way). + // They go as the gaps close (192), not after: closed, their pairs are 24 apart and they would touch. + const labels = clamp01((r - 84) / 12) * (1 - clamp01((r - 192) / 12)); + const offsets = clamp01((r - 66) / 12) * (1 - clamp01((r - 192) / 12)); + const zeros_mark = clamp01((r - 204) / 12) * (1 - clamp01((r - 228) / 12)); + const under = @max(offsets, zeros_mark); + if (under > 0) u.faded(under).fill(.{ .x = at.bytes - 12, .y = y + pitch, .w = at.field_end - at.bytes + 24, .h = 2 * pitch + 6 }, theme.color.page); + const close = glide((r - 192) / 12); + for (0..8) |k| { + const kf: f32 = @floatFromInt(k); + const s = clamp01((r - 108 - 6 * kf) / 36); + const from = at.bytes + kf * at.pair; + const pair = 7 - kf; + const to = std.math.lerp(at.field + pair * at.pair, at.field_end - (8 - pair) * 2 * adv, close); + const long = to - from; + const high = std.math.clamp(long / 4, theme.time.flight.arc_min, theme.time.flight.arc_max); + const x = std.math.lerp(from, to, theme.ease(.glide, s)); + const lift = high * @sin(std.math.pi * s); + // The byte itself: bright and bold in the air (from 108 the walk draws it, not the row). + if (r >= 108) { + const air = s > 0 and s < 1; + const text = u.print("{x:0>2}", .{data.bytes[w.walked * 8 + k]}); + // In the air it carries its ground: over the veiled rows it reads alone. + if (air) u.fill(.{ .x = x - 3, .y = base - lift - 18, .w = 2 * adv + 6, .h = 24 }, theme.color.page); + // Each digit of a pair on its own: a zero in front of the word fades on its own. + for (0..2) |d| { + const lead = 2 * (7 - k) + d < 16 - ui.digits(value); + const fade: f32 = if (lead and r >= 228) 1 - clamp01((r - 228) / 12) else 1; + if (fade > 0) u.faded(fade).text(if (air) .mono_bold else .mono, size, x + @as(f32, @floatFromInt(d)) * adv, base - lift, text[d .. d + 1], if (air) t.bright else t.primary); + } + } + // Its offset under it, going with it. + const off = offsets * clamp01((r - 66 - 2 * kf) / 12); + if (off > 0 and s > 0 and s < 1) u.faded(off).fill(.{ .x = x - 3, .y = base + pitch - lift - 18, .w = 2 * adv + 6, .h = 24 }, theme.color.page); + if (off > 0) u.faded(off).text(.mono, size, x, base + pitch - lift, u.print("+{d}", .{k}), t.dim); + // `low byte` from its byte's left, `high byte` to its byte's right: under the bytes, never the addresses. + if (k == 0 or k == 7) if (labels > 0) { + const label = if (k == 0) "low byte" else "high byte"; + const lw = u.width(.sans, theme.size.sans.tag, label); + u.faded(labels).text(.sans, theme.size.sans.tag, if (k == 0) x else x + 2 * adv - lw, base + 2 * pitch + 2 - lift, label, t.dim); + }; + } + // The zeros in front, bracketed (motion.md: 204 to 228). + if (zeros_mark > 0) { + const lead: f32 = @floatFromInt(16 - ui.digits(value)); + const x0 = at.field_end - 16 * adv; + const v = u.faded(zeros_mark); + v.fill(.{ .x = x0, .y = y + pitch - 2, .w = lead * adv, .h = 2 }, t.dim); + v.fill(.{ .x = x0, .y = y + pitch - 8, .w = 2, .h = 6 }, t.dim); + v.fill(.{ .x = x0 + lead * adv - 2, .y = y + pitch - 8, .w = 2, .h = 6 }, t.dim); + v.text(.sans, theme.size.sans.tag, x0, base + pitch + 2, "zeros in front", t.dim); + } + } + + /// The dump folded to its tag on the shelf (mock 49's shelf, y 48): the + /// rows out over 6 f, the tag from over the rows to the shelf (18 f, `glide`). + fn tag(_: *const Words, u: ui.Ui, fold: f32) void { + if (fold <= 0) return; + const title = "the stack's 128 bytes"; + const p = glide((fold - 6) / 18); + const w = u.width(.sans_medium, theme.size.sans.tag, title) + 40; + const x = std.math.lerp(at.address - 8, theme.canvas.margin_x, p); + const y = std.math.lerp(at.top - 30, theme.canvas.stage.y, p); + const v = u.faded(clamp01(fold / 6)).moved(x, y); + v.fill(.{ .x = 0, .y = 0, .w = w, .h = theme.metric.context.tag }, theme.color.raised); + v.frame(.{ .x = 8, .y = 6, .w = 12, .h = 12 }, t.faint, theme.stroke.rule); + v.text(.sans_medium, theme.size.sans.tag, 28, theme.metric.context.tag - 6, title, t.dim); + } +}; -- cgit v1.3