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/cursor.zig | 638 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 638 insertions(+) create mode 100644 anim/src/cursor.zig (limited to 'anim/src/cursor.zig') diff --git a/anim/src/cursor.zig b/anim/src/cursor.zig new file mode 100644 index 0000000..2ca8a97 --- /dev/null +++ b/anim/src/cursor.zig @@ -0,0 +1,638 @@ +//! The cursor: where in the recording the picture is, as numbers on the +//! scene's timeline. It moves in steps, each from one moment straight to a +//! later one (the next instruction, the next source line, the line after a +//! call returns, the next syscall: `Recording.Stop`), and remembers the +//! last few places it stopped. +//! +//! A step is a sentence (design/motion.md): the line about to run fires; +//! what it did lands a level at a time, the CPU, then memory, then the idea +//! drawn from them, each armed and then struck; it is held to be read; and +//! last the current mark moves on. The cursor writes that timetable (a +//! `Plan`) for each step from what the step changed, so a walk has the +//! program's rhythm and not a clock's, and every component reads it +//! (`Cursor.now`) with no state of its own. +const std = @import("std"); +const anim = @import("anim"); +const zt = @import("ztrace"); +const Recording = @import("Recording.zig"); +const ui = @import("ui.zig"); +const theme = ui.theme; +const time = theme.time; + +/// A mark lasts this many steps, then one more to leave in. +const history = time.strike.ember_steps + 2; + +/// Slow in and slow out, for things with weight: a value in flight, a +/// layout, a colour cooling. Quickest at the middle. +pub fn glide(t: f32) f32 { + return theme.ease(.glide, t); +} + +/// For things that answer the program (the mark, cards, tags, an arrow +/// growing): off promptly, a long settle. +pub fn standard(t: f32) f32 { + return theme.ease(.standard, t); +} + +/// The levels a step's effects land on, in the order they are caused. +pub const Level = enum(u2) { cpu, memory, idea }; + +/// What is on screen for the cursor to time a step by. A level the scene +/// does not show gives up its place in the cascade. +pub const Levels = struct { + cpu: bool = true, + memory: bool = true, + /// The idea drawn from them, when one is shown: the calls (cards, a + /// tree), or the data (nodes, an array's cells). + idea: enum { none, calls, data } = .none, + /// Follow-through: seconds the data's view goes on moving after its + /// strike (an arrow redrawn, a tag sliding), before the hold begins. + follow: f32 = 0, + /// Where a step fires: on the source line, or (a scene that steps by + /// instruction) on the pc's row of the disassembly. One place: two + /// views of the same thing start together, and only one of them pulses. + fire: enum { source, disasm } = .source, + /// How many lines the source panel shows (the split's): a step that + /// takes the program out of its window has the window's glide to wait for. + source_rows: u32 = 12, +}; + +/// How a step is drawn. Walk: everything, as a sentence. Run: the mark and +/// structures eased, values as embers. Sprint: structures grow, embers. +pub const Gait = enum(u2) { walk, run, sprint }; + +/// A step's timetable, in seconds from its first frame. +pub const Plan = struct { + gait: Gait = .walk, + /// When each level strikes (`Level` is the index). + at: [3]f32 = @splat(time.cascade), + /// When the mark sets off for the next line, and how long it takes. + advance: f32 = time.fire, + travel: f32 = time.step, + /// The whole step: the advance, then a rest in which the next line is read. + total: f32 = time.fire + time.step + time.rest, + + /// Once the pattern is known: the levels a stagger apart from the + /// first frame, the mark after them, in `seconds`. + pub fn running(seconds: f32) Plan { + return .{ .gait = .run, .at = .{ 0, time.stagger, 2 * time.stagger }, .advance = time.run_ease, .travel = time.run_ease, .total = seconds }; + } + + pub fn sprinting(seconds: f32) Plan { + return .{ .gait = .sprint, .at = @splat(0), .advance = 0, .travel = 0, .total = seconds }; + } +}; + +/// Registers whose change is no value to read: where execution is, and the flags. +const quiet: u32 = blk: { + var mask: u32 = 0; + for (zt.Regs.names, 0..) |name, i| { + if (std.mem.eql(u8, name, "rip") or std.mem.eql(u8, name, "eflags")) mask |= 1 << i; + } + break :blk mask; +}; + +pub const Cursor = struct { + rec: *Recording, + /// Where it is (or is arriving), where it came from, and before that. + stops: [history]anim.Value, + /// 0 to 1 through the step it is taking; 1 at rest. + phase: anim.Value, + /// The step's `Plan`, a value a field. + plan: [7]anim.Value, + /// The moment the current mark was on, and the one it is on (or going to). + marks: [2]anim.Value, + /// 1 while steps are hurried (the head counts them), and while what + /// cannot be read at that pace is veiled. + hurried: anim.Value, + veil: anim.Value, + /// Steps taken. + count: anim.Value, + /// The levels the scene shows: set before the first step. + levels: Levels = .{}, + /// The scene's whole way, for the head's progress line and counter (`journey`). + first: u64, + last: u64, + of: u32 = 0, + + /// A cursor at rest at moment `start`. + pub fn init(s: *anim.Frame, rec: *Recording, start: u64) Cursor { + const here: f32 = @floatFromInt(start); + const plan: Plan = .{}; + var c: Cursor = .{ + .rec = rec, + .stops = undefined, + .phase = s.value(1), + .plan = .{ s.value(0), s.value(plan.at[0]), s.value(plan.at[1]), s.value(plan.at[2]), s.value(plan.advance), s.value(plan.travel), s.value(plan.total) }, + .marks = .{ s.value(here), s.value(here) }, + .hurried = s.value(0), + .veil = s.value(0), + .count = s.value(0), + .first = start, + .last = start, + }; + // shortcut: an f32 holds whole moments up to 16 million; a longer recording needs two values a stop. + for (&c.stops) |*stop| stop.* = s.value(here); + return c; + } + + /// Where the timeline has taken the cursor so far: for scene code that + /// finds the next place from the last. + pub fn moment(c: Cursor, s: *const anim.Frame) u64 { + return @intFromFloat(settled(s, c.stops[0])); + } + + /// Tells the cursor how far the scene will take it, in steps of `by`: + /// what the head's progress line and step counter are measured against. + pub fn journey(c: *Cursor, by: Recording.Stop, until: u64) void { + c.last = until; + c.of = c.steps(by, c.first, until); + } + + /// How many steps of `by` from `from` to `until`. + pub fn steps(c: Cursor, by: Recording.Stop, from: u64, until: u64) u32 { + var n: u32 = 0; + var here = from; + while (here < until) : (n += 1) here = @min(c.rec.next(by, here), until); + return n; + } + + /// One step, straight to moment `to`, drawn as `plan` says and played + /// in `seconds` (a plan played in less than its `total` is the same + /// sentence said faster). + pub fn step(c: Cursor, s: *anim.Frame, to: u64, plan: Plan, seconds: f32) void { + const from = c.moment(s); + var set: [history + 11]anim.Animation = undefined; + for (1..history) |i| set[i] = c.stops[i].to(settled(s, c.stops[i - 1])); + set[0] = c.stops[0].to(@floatFromInt(to)); + for (c.plan, [_]f32{ @floatFromInt(@intFromEnum(plan.gait)), plan.at[0], plan.at[1], plan.at[2], plan.advance, plan.travel, plan.total }, history..) |value, is, n| set[n] = value.to(is); + // At a sprint the mark is seen only where a phrase ends. + const was = settled(s, c.marks[1]); + set[history + 7] = c.marks[0].to(was); + set[history + 8] = c.marks[1].to(if (plan.gait == .sprint and !c.phraseEnds(from, to)) was else @floatFromInt(to)); + set[history + 9] = c.phase.to(0); + set[history + 10] = c.count.to(settled(s, c.count) + 1); + s.play(set, .{ .seconds = 0 }); + s.play(.{c.phase.to(1)}, .{ .seconds = seconds, .ease = anim.ease.linear }); + } + + /// Steps of `by` up to moment `until`, each shown in full and as long + /// as what it changed takes to read (`reading`), with a beat's rest + /// where a phrase ends. For the first time anything happens, and + /// whatever the narration names. + pub fn walk(c: Cursor, s: *anim.Frame, by: Recording.Stop, until: u64) void { + var here = c.moment(s); + while (here < until) { + const next = @min(c.rec.next(by, here), until); + const plan = c.reading(here, next); + c.step(s, next, plan, plan.total); + if (c.phraseEnds(here, next)) s.wait(time.phrase_rest); + here = next; + } + } + + /// Timing: the timetable a walked step from `from` to `to` deserves. + /// Fire; a slot of the cascade for each level it touched; the idea's + /// follow-through; a hold as long as the values take to read; the + /// advance; a rest. A line and no more comes to 0.8 s, one value to + /// 1.5, a register and memory to 2.0, a call through three levels 2.5. + pub fn reading(c: Cursor, from: u64, to: u64) Plan { + const rec = c.rec; + const regs: f32 = @floatFromInt(@popCount(rec.registersChanged(from, to) & ~quiet)); + const wrote: f32 = @floatFromInt(rec.written(from, to).len); + const touched = wrote > 0 or rec.read(from, to).len > 0; + const deeper = rec.depths[to] > rec.depths[from]; + const back = rec.depths[to] < rec.depths[from]; + const levels = [3]bool{ + c.levels.cpu and regs > 0, + c.levels.memory and touched, + switch (c.levels.idea) { + .none => false, + .calls => deeper or back, + .data => touched, + }, + }; + var plan: Plan = .{ .travel = c.travel(from, to) }; + var slot: f32 = 0; + for (levels, &plan.at) |is, *strikes| { + if (is) slot += time.cascade; + strikes.* = @max(slot, time.cascade); + } + if (slot > 0) { + // What there is to read: a level's worth each. (In the whole + // context a line changes more registers than anyone reads; + // the hold is for the one the scene is about.) + var values: f32 = 0; + for (levels) |is| values += @floatFromInt(@intFromBool(is)); + // A card leaves after its result is read; an arrow lands after its word strikes. + const follow: f32 = if (!levels[2]) 0 else switch (c.levels.idea) { + .none => 0, + .calls => if (back) time.returning else time.snap, + .data => c.levels.follow, + }; + plan.advance = slot + follow + @min(time.read_value + time.read_more * (values - 1), time.read_most); + } + plan.total = plan.advance + plan.travel + time.rest; + return plan; + } + + /// How long the mark takes to the next line: a slide by how far, or a + /// jump (out, then in) into or out of a call, or further than a few rows. + fn travel(c: Cursor, from: u64, to: u64) f32 { + const rec = c.rec; + // The source's window moves with it: by whole lines, and never a cut. + if (rec.viewFirst(c.levels.source_rows, rec.own[from]) != rec.viewFirst(c.levels.source_rows, rec.own[to])) return time.move; + if (jumps(rec, from, to)) return 2 * time.current_jump; + const rows: f32 = @floatFromInt(@max(rec.own[from], rec.own[to]) - @min(rec.own[from], rec.own[to])); + return @min(time.step + time.step_per_row * @max(rows - 1, 0), time.step_max); + } + + /// A phrase ends where a call returns, or a loop comes round again. + pub fn phraseEnds(c: Cursor, from: u64, to: u64) bool { + const rec = c.rec; + return rec.depths[to] < rec.depths[from] or (rec.depths[to] == rec.depths[from] and rec.own[to] < rec.own[from]); + } + + pub const Hurry = struct { + /// Seconds a step, once up to speed: `time.run`, or `time.sprint`. + pace: f32 = time.run, + /// What the pace was before, and is to be after. + from: f32 = time.walk, + to: f32 = time.walk, + /// Veil what cannot be read at that pace (null: at a sprint). + veil: ?bool = null, + /// Lift the veil and rest a beat afterwards: not when another + /// stretch at another pace follows at once. + settle: bool = true, + }; + + /// Pacing: steps of `by` up to `until`, hurried, for a pattern already + /// seen in full. A change of pace is never a switch: each step is + /// `time.ramp` of the one before on the way down from `from`, and on + /// the way back up to `to`, and then the picture is still for a beat. + /// A step with time enough is still a whole sentence, said faster; + /// shorter, it is a run (the mark and structures eased, values as + /// embers), with a short rest where a phrase ends; shorter still, a + /// sprint. The head counts the steps while it lasts. + pub fn hurry(c: Cursor, s: *anim.Frame, by: Recording.Stop, until: u64, options: Hurry) void { + var here = c.moment(s); + const n: f32 = @floatFromInt(c.steps(by, here, until)); + if (n == 0) return; + // Anticipation: the veil and the counter come with the first shortened step. + const veiled = options.veil orelse (options.pace < time.run); + const start = s.cursor; + s.play(.{ c.hurried.to(1), c.veil.to(if (veiled) 1 else 0) }, .{ .seconds = time.veil, .ease = anim.ease.linear }); + s.cursor = start; + var k: f32 = 0; + while (here < until) : (k += 1) { + const next = @min(c.rec.next(by, here), until); + const natural = c.reading(here, next); + const down = options.from * std.math.pow(f32, time.ramp, k + 1); + const up = options.to * std.math.pow(f32, time.ramp, n - k); + // Whole frames, at 30 a second as at 60. + const seconds = @round(@min(natural.total, @max(options.pace, @min(down, up))) * 30) / 30; + const plan: Plan = if (seconds >= time.walk_least) natural else if (seconds > 1.5 * time.sprint) .running(seconds) else .sprinting(seconds); + c.step(s, next, plan, seconds); + if (plan.gait != .sprint and c.phraseEnds(here, next)) s.wait(time.phrase_rest_running); + here = next; + } + if (!options.settle) return; + s.play(.{ c.hurried.to(0), c.veil.to(0) }, .{ .seconds = time.veil, .ease = anim.ease.linear }); + s.wait(time.beat); + } + + /// There at once, with nothing struck: a cut. + pub fn jump(c: Cursor, s: *anim.Frame, to: u64) void { + var all: [history + 3]anim.Animation = undefined; + for (c.stops, 0..) |stop_value, i| all[i] = stop_value.to(@floatFromInt(to)); + all[history] = c.phase.to(1); + all[history + 1] = c.marks[0].to(@floatFromInt(to)); + all[history + 2] = c.marks[1].to(@floatFromInt(to)); + s.play(all, .{ .seconds = 0 }); + } + + /// For a component, while it draws. + pub fn now(c: Cursor, placed: anim.Placed) Now { + const rec = c.rec; + var n: Now = .{ + .rec = rec, + .stops = undefined, + .time = std.math.inf(f32), + .plan = .{ + .gait = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(placed.value(c.plan[0])), 0, 2)))), + .at = .{ placed.value(c.plan[1]), placed.value(c.plan[2]), placed.value(c.plan[3]) }, + .advance = placed.value(c.plan[4]), + .travel = placed.value(c.plan[5]), + .total = placed.value(c.plan[6]), + }, + .marks = .{ whole(rec, placed.value(c.marks[0])), whole(rec, placed.value(c.marks[1])) }, + .hurried = placed.value(c.hurried), + .veil = placed.value(c.veil), + .count = @intFromFloat(@max(placed.value(c.count), 0)), + .of = c.of, + .place = 0, + .fired = c.levels.fire, + .way = .{ c.first, c.last }, + }; + for (&n.stops, c.stops) |*stop_at, v| stop_at.* = whole(rec, placed.value(v)); + const phase = placed.value(c.phase); + if (phase < 1) n.time = phase * n.plan.total; + if (c.last > c.first) { + // Linear: time itself. + const here = std.math.lerp(@as(f32, @floatFromInt(n.stops[1])), @as(f32, @floatFromInt(n.stops[0])), std.math.clamp(phase, 0, 1)); + n.place = std.math.clamp((here - @as(f32, @floatFromInt(c.first))) / @as(f32, @floatFromInt(c.last - c.first)), 0, 1); + } + return n; + } +}; + +fn whole(rec: *const Recording, value: f32) u64 { + return @min(@as(u64, @intFromFloat(@max(value, 0))), rec.end()); +} + +fn settled(s: *const anim.Frame, v: anim.Value) f32 { + return s.values.items[@backingInt(v)].settled; +} + +/// Whether the mark jumps from the line of moment `from` to that of `to` +/// (fades out there and in here) and does not slide: a call is not a +/// journey across the lines between. +pub fn jumps(rec: *const Recording, from: u64, to: u64) bool { + const rows = @max(rec.own[from], rec.own[to]) - @min(rec.own[from], rec.own[to]); + return rec.depths[from] != rec.depths[to] or rows > time.current_jump_rows; +} + +/// The cursor at one instant. +pub const Now = struct { + rec: *const Recording, + /// `stops[0]` is the moment shown, `stops[1]` where the step came + /// from: the step is every moment after it up to the one shown. + stops: [history]u64, + /// Seconds into the step's plan; infinite at rest. + time: f32, + plan: Plan, + /// The moment whose line the current mark is leaving, and the one it goes to. + marks: [2]u64, + /// 0 to 1: steps are hurried; what cannot be read is veiled. + hurried: f32, + veil: f32, + /// Steps taken, of how many in the scene (0: not told). + count: u32, + of: u32, + /// 0 to 1 along the scene's way through the recording. + place: f32, + /// Where the scene's steps fire (`Levels.fire`). + fired: @FieldType(Levels, "fire") = .source, + /// The scene's way through the recording: its first moment and its last. + way: [2]u64 = .{ 0, 0 }, + + /// The program's state as shown. + pub fn moment(n: Now) Recording.Moment { + return n.rec.moment(n.stops[0]); + } + + /// Its state before this step. + pub fn before(n: Now) Recording.Moment { + return n.rec.moment(n.stops[1]); + } + + pub fn resting(n: Now) bool { + return std.math.isInf(n.time); + } + + /// A step shown in full: fire, arm, strike, hold. + pub fn walking(n: Now) bool { + return n.plan.gait == .walk and !n.resting(); + } + + /// Seconds since `level` struck, for the one of several that strikes + /// `delay` after the first: negative before, infinite at rest. + pub fn since(n: Now, level: Level, delay: f32) f32 { + return n.time - n.plan.at[@intFromEnum(level)] - delay; + } + + /// Whether `level`'s changes show yet: until then a component draws + /// the state before the step. The digits change as the fill comes in. + pub fn landed(n: Now, level: Level, delay: f32) bool { + return n.since(level, delay) >= time.strike.in / 2.0; + } + + /// The state to draw for `level`. + pub fn shown(n: Now, level: Level) Recording.Moment { + return if (n.landed(level, 0)) n.moment() else n.before(); + } + + /// The moment to ask the recording's index about, for `level`. + pub fn stop(n: Now, level: Level) u64 { + return if (n.landed(level, 0)) n.stops[0] else n.stops[1]; + } + + /// How far (0 to 1, to be eased) a thing has got that moves as `level` + /// strikes: it sets off `lead` seconds before the strike and takes + /// `seconds`. At a run it sets off with its level and takes + /// `time.run_ease`; at a sprint, and at rest, it is there. + pub fn moving(n: Now, level: Level, lead: f32, seconds: f32) f32 { + return switch (n.plan.gait) { + .walk => std.math.clamp((n.since(level, 0) + lead) / seconds, 0, 1), + .run => std.math.clamp(n.since(level, 0) / time.run_ease, 0, 1), + .sprint => 1, + }; + } + + /// The fire: how far out (in units) the edges of the mark's plaque + /// are, on the line about to run. The step's first beat, alone. + pub fn fire(n: Now) f32 { + return if (n.walking() and n.time < time.fire) theme.pulse(n.time / time.fire) else 0; + } + + /// The same for the view the scene fires in, 0 for the other. + pub fn fires(n: Now, in: @FieldType(Levels, "fire")) f32 { + return if (n.fired == in) n.fire() else 0; + } + + /// 0 to 1 (to be eased) through the mark's move to the next line: the + /// step's follow-through, and the next step's anticipation. + pub fn advancing(n: Now) f32 { + return n.advancingAfter(0); + } + + /// The same for another view of where execution is (the pc's row, the + /// value of rip), which follows the source's mark `delay` seconds + /// behind: three panels do not start on one frame. + pub fn advancingAfter(n: Now, delay: f32) f32 { + if (n.resting() or n.plan.travel <= 0) return 1; + return std.math.clamp((n.time - n.plan.advance - delay) / @max(n.plan.travel - delay, 1.0 / 60.0), 0, 1); + } + + /// The moment the current mark stands for: the step's own line until + /// the mark has left it. + pub fn marked(n: Now) u64 { + return if (n.advancing() >= 0.5) n.marks[1] else n.marks[0]; + } + + /// How many steps ago (0: in this one) the bytes `addr .. addr + size` + /// last changed; null when longer ago than a mark lasts. + pub fn writeAge(n: Now, addr: u64, size: u64) ?u64 { + return n.writeAgeFrom(addr, size, 0); + } + + /// The same, not counting the `skip` newest steps. + fn writeAgeFrom(n: Now, addr: u64, size: u64, skip: usize) ?u64 { + for (skip..history - 1) |age| { + if (Recording.touches(n.rec.written(n.stops[age + 1], n.stops[age]), addr, size)) return age; + } + return null; + } + + /// The same for a register, by its place in `Regs.names`. + pub fn registerAge(n: Now, reg: usize) ?u64 { + return n.registerAgeFrom(reg, 0); + } + + fn registerAgeFrom(n: Now, reg: usize, skip: usize) ?u64 { + for (skip..history - 1) |age| { + if (n.rec.registersChanged(n.stops[age + 1], n.stops[age]) >> @intCast(reg) & 1 != 0) return age; + } + return null; + } + + /// Whether this step read any of `addr .. addr + size`. + pub fn wasRead(n: Now, addr: u64, size: u64) bool { + return Recording.touches(n.rec.read(n.stops[1], n.stops[0]), addr, size); + } + + /// How far into the run of bytes this step wrote `addr` is: bytes of + /// one write strike a frame apart, low address first. + pub fn writeOffset(n: Now, addr: u64) u64 { + for (n.rec.written(n.stops[1], n.stops[0])) |span| { + if (addr >= span.addr and addr < span.addr + span.len) return addr - span.addr; + } + return 0; + } + + /// What a step `age` steps ago left on a thing it wrote: an ember for + /// three steps, leaving in the one after. + fn left(n: Now, age: ?u64) ui.Heat { + const s = time.strike; + const a = age orelse return .none; + if (a == 0 or a > s.ember_steps) return .none; + if (a < s.ember_steps) return .ember; + // Linear: a fade. Gone by the time this step is over. + return .{ .level = 1 - std.math.clamp(n.time / s.out, 0, 1) }; + } + + /// The mark of a thing last changed `age` steps ago (`older`: not + /// counting this step), whose strike came `since_strike` seconds ago. + /// Anticipation: armed first, a frame round the old value. Then the + /// strike: the fill comes in (never in one frame) with a pulse of its + /// edges, the one exaggeration there is. Held solid while the line + /// that did it is still gold; cooled as the mark leaves. + pub fn heat(n: Now, age: ?u64, older: ?u64, since_strike: f32) ui.Heat { + const s = time.strike; + if (age != 0) return n.left(age); + const was = n.left(older); + switch (n.plan.gait) { + // Faster than a strike can be seen: embers only. + .sprint => return .ember, + .run => return if (was.level >= 1 or n.resting()) .ember else .{ .level = std.math.clamp(since_strike / time.snap, 0, 1) }, + .walk => {}, + } + if (n.resting()) return .ember; + if (since_strike < 0) { + var armed = was; + if (since_strike >= -s.arm) armed.arm = std.math.clamp((since_strike + s.arm) / time.stagger, 0, 1); + return armed; + } + return .{ + .level = 1, + .solid = 1 - glide(std.math.clamp((n.time - n.plan.advance) / s.cool, 0, 1)), + .in = std.math.clamp(since_strike / s.in, 0, 1), + .from = if (was.level >= 1) .ember else .nothing, + .out = if (since_strike < s.pulse) theme.pulse(since_strike / s.pulse) else 0, + }; + } + + /// The mark of the bytes `addr .. addr + size`, which strike with + /// `level`, `delay` seconds after its first. + pub fn written(n: Now, addr: u64, size: u64, level: Level, delay: f32) ui.Heat { + return n.heat(n.writeAge(addr, size), n.writeAgeFrom(addr, size, 1), n.since(level, delay)); + } + + /// The mark of a register: the CPU's level. + pub fn register(n: Now, reg: usize, delay: f32) ui.Heat { + return n.heat(n.registerAge(reg), n.registerAgeFrom(reg, 1), n.since(.cpu, delay)); + } + + /// How much (0 to 1) the frame round a thing this step read shows: in + /// with its level, never armed or pulsed, held while the line is + /// gold, and out as the mark leaves, gone before the next line fires. + pub fn reading(n: Now, level: Level, delay: f32) f32 { + return switch (n.plan.gait) { + .walk => n.held(n.plan.at[@intFromEnum(level)] + delay), + .run => if (n.resting()) 0 else @min(std.math.clamp(n.since(level, 0) / time.stagger, 0, 1), std.math.clamp((n.plan.total - n.time) / time.snap, 0, 1)), + .sprint => 0, + }; + } + + /// The same for a frame that comes in `from` seconds into a walked step. + pub fn held(n: Now, from: f32) f32 { + const r = time.read; + if (!n.walking()) return 0; + return @min(std.math.clamp((n.time - from) / r.in, 0, 1), 1 - std.math.clamp((n.time - n.plan.advance) / r.out, 0, 1)); + } +}; + +fn instant(seconds: f32, plan: Plan) Now { + return .{ .rec = undefined, .stops = undefined, .time = seconds, .plan = plan, .marks = undefined, .hurried = 0, .veil = 0, .count = 0, .of = 0, .place = 0 }; +} + +test "a write is armed, strikes, holds, cools with the advance, and leaves after three steps" { + const s = time.strike; + const expect = std.testing.expect; + const expectEqual = std.testing.expectEqual; + // One register written: struck at 0.30, the mark leaves at 0.90. + const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .total = 1.50 }; + // Armed: a frame, and no fill yet. + var h = instant(0.20, plan).heat(0, null, 0.20 - 0.30); + try expect(h.arm == 1 and h.level == 0); + // Not before its arm. + try expectEqual(ui.Heat.none, instant(0.05, plan).heat(0, null, 0.05 - 0.30)); + // Struck: the fill half in, the edges out. + h = instant(0.35, plan).heat(0, null, 0.05); + try expect(h.level == 1 and h.solid == 1 and @abs(h.in - 0.5) < 1e-3 and h.out > 2 and h.arm == 0); + // Held solid until the mark leaves, then cooled, halfway at the middle. + h = instant(0.89, plan).heat(0, null, 0.59); + try expect(h.solid == 1 and h.in == 1 and h.out == 0); + h = instant(0.90 + s.cool / 2.0, plan).heat(0, null, 0.8); + try std.testing.expectApproxEqAbs(@as(f32, 0.5), h.solid, 1e-3); + // At rest, and for the steps after: the ember; then it goes. + const rest = instant(std.math.inf(f32), plan); + try expectEqual(ui.Heat.ember, rest.heat(0, null, std.math.inf(f32))); + try expectEqual(ui.Heat.ember, rest.heat(2, 2, 0)); + try expectEqual(ui.Heat.none, rest.heat(4, 4, 0)); + try expectEqual(ui.Heat.none, rest.heat(null, null, 0)); + try std.testing.expectApproxEqAbs(@as(f32, 0.5), instant(s.out / 2.0, plan).heat(s.ember_steps, s.ember_steps, 0).level, 1e-3); + // Struck again over its ember: armed with the ember still under it. + h = instant(0.20, plan).heat(0, 1, -0.10); + try expect(h.level == 1 and h.arm == 1 and h.solid == 0); + // Running: an ember and no more. Sprinting: the same, at once. + try expect(instant(0.2, Plan.running(0.3)).heat(0, null, 0.2).solid == 0); + try expectEqual(ui.Heat.ember, instant(0.01, Plan.sprinting(0.05)).heat(0, null, 0.01)); +} + +test "what a step read is framed while its line is gold" { + const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .total = 1.50 }; + try std.testing.expectEqual(@as(f32, 0), instant(0.2, plan).reading(.memory, 0)); + try std.testing.expectEqual(@as(f32, 1), instant(0.6, plan).reading(.memory, 0)); + try std.testing.expectEqual(@as(f32, 0), instant(0.9 + time.read.out, plan).reading(.memory, 0)); + try std.testing.expectEqual(@as(f32, 0), instant(std.math.inf(f32), plan).reading(.memory, 0)); +} + +test "the mark fires first and moves last" { + const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .travel = 0.20, .total = 1.50 }; + try std.testing.expect(instant(0.10, plan).fire() > 3.9); + try std.testing.expectEqual(@as(f32, 0), instant(0.30, plan).fire()); + try std.testing.expectEqual(@as(f32, 0), instant(0.89, plan).advancing()); + try std.testing.expectEqual(@as(f32, 1), instant(1.10, plan).advancing()); + try std.testing.expectEqual(@as(f32, 1), instant(std.math.inf(f32), plan).advancing()); +} -- cgit v1.3