summaryrefslogtreecommitdiff
path: root/anim/README.md
blob: c6e55bc4a0020b195136c1bf764b05b151b51677 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
# canim

Animations of how a program ran, from a `ztrace` recording, on sketchbook's
`anim` (live scenes). The frame is a debugger's whole context, as pwndbg
shows it, with one lens over it; the names, sizes and colours of everything
in it are the design language's catalogue (`../design/README.md`), and how
it moves is `../design/motion.md`. Code and design share one set of names:
a block of the catalogue is a function or a component of the same name here.

```sh
zig build record                         # the recordings, into zig-out/recordings
zig build sources                        # fetch the library sources their lines name (the only step that uses the network)
zig build run -Dscene=fib                # a scene in a window, hot reload (zig build lib --watch)
zig build export -Dscene=fib -- DIR --fps 60 --size 1920x1080    # frames as PNGs (or - for raw RGBA)
zig build videos -Doptimize=ReleaseFast  # every scene: out/NAME-1080.mp4 and out/NAME-2160.mp4 (x264, 60 fps, aq-mode=0)
zig build test                           # unit tests, each scene run headless, and the gallery against its pictures
zig build gallery                        # the gallery's pictures drawn anew into test/gallery
zig build bench                          # what a recording costs a frame
zig build bench -- NAME BY [FUNCTION]    # a recording's steps (BY: moment, line, over), with what each changed
python3 tools/chart.py chart out/fib-1080.mp4 --out out/motion/fib   # the designer's timing chart and checks (POP, CROWD, METRONOME, CAPTION, AIR)
CANIM_MAP=1 zig build export -Dscene=fib -- DIR --size 3840x2160 # every frame the scene's map filling it, as `list` opens on it: a map at 1:1
```

Needs what sketchbook and ztrace need, and `setarch`, `clang` (the pass
plugin), `ffmpeg` (videos), python with numpy and Pillow (charts), `curl`
(`zig build sources` alone). The
`sqlite` scene also needs SQLite's amalgamation (`-Dsqlite=DIR`, the
directory of `sqlite3.c` and `sqlite3.h`; by default
`~/05-genizah/sqlite/sqlite-amalgamation-3500400`) and `objdump`; where
the directory is not there the scene is not made, and the rest builds
and tests as before.
Dependencies are by path (`..` is ztrace, `../../sketchbook`,
`../../02-pardes-code`); `zig-pkg` is a symlink to pardes's.

## A scene

```zig
const anim = @import("anim");
const canim = @import("canim");
const recordings = @import("recordings");

pub const background = canim.background;
pub const scene = anim.Live(frame, struct {});

fn frame(s: *anim.Frame) void {
    const rec = canim.open(recordings.steps);              // a recording the build made and embedded
    var at = canim.cursor(s, rec, rec.lineMoment(10, rec.call("main", 0).enter));
    at.levels = .{ .idea = .calls, .source_rows = 10 };    // what a step is timed by
    at.journey(.line, rec.call("fib", 0).exit.?);          // the clock's whole way
    // The stage: the band (the lens) over the program column and the state column.
    const ctx = canim.context(s, at, .{ .split = canim.layout.split.subject });
    const tree = canim.callTree(s, .{ .cursor = at, .stage = ctx.stage, .function = "fib" });
    const joins = ctx.ties(s);                             // thread, link, projection; add it last
    var says: canim.Narrator = .{};

    canim.establish(s, .{ ctx.clock, ctx.registers, ctx.stack, ctx.source, ctx.disasm, tree, joins });
    says.line(s, "`fib` calls itself.");                   // old caption out, a gap, new one in, then stillness
    at.walk(s, .line, rec.lineMoment(6, rec.call("fib", 0).enter));   // each step in full, timed by its content
    at.hurry(s, .line, rec.call("fib", 4).enter, .{});     // a run: ramps in and out, counted on the clock
    ctx.stage.relayout(s, canim.layout.split.none);        // a change of split, 48 f
    s.wait(canim.theme.time.before_cut);
}
```

`frame` runs every frame and builds the whole timeline each time; a
component is an `anim` object (`fadeIn`, `fadeOut`) that draws the program's
state at the cursor, at the box its `Stage` gives it now.

**The cursor** (`src/cursor.zig`) moves in steps from one moment straight to
a later one (`Recording.Stop`: `.moment`, `.line`, `.over`, `.call`,
`.syscall`). For each step it writes a timetable, a `Plan`: the cascade.
The line fires (12 f); each level the step touched strikes 18 f after the one
before (after the last of its registers, which strike 6 f apart), in the order CPU, memory, idea (a level the scene does not show, or
the step did not touch, or touched nothing drawn, gives up its slot; a
drawing made of bytes strikes when the projection from them arrives, 24 f
after them, and its write 12 f later still; a call's node when the
projection from its return address does, 36 f after); the writes of one step strike 6 f apart (those that take a
place: not a stack frame the step has already left, a callee's words under rsp), each keeping its old value through
its arm until its own strike lands (s+3: `Now.struckAgo`, `shownAt`; what the kernel fills, once the last byte of the
word lands); a register's chain reads memory as the panels show it: from the bytes' strike its later hops fade
out (3 f), and 4 f after they land they are followed again (`extend`, `Now.following`); a hold to read; the
mark advances last; a rest. `walk` plays steps in full, `hurry` ramps the
pace down and up again (each step 0.6 of the one before) to a run (0.30 s a
step: nothing struck, no held corner, no arc, a dump's values crossfading
over 8 f; the arcs fade back in as it ends) or a sprint, `step` takes an explicit `Plan` (`Array.swap`,
`syscalls.step`), and `continue` goes to a stop far from this one (a
breakpoint): the line it leaves fires, the registers it changed strike in
a wave 2 f apart in pwndbg's order (fill 6 f, no arm, no pulse), then
memory and the idea, a 36 f hold, the mark out and in (6 f each, the
source fading through first if far), a 24 f rest. Components read it
through `Cursor.now(at)`; each pane's minimap (its strip) reads the same
values 6 f behind and five more mirrors a frame apart, with the panes'
windows as they were as long ago (`Cursor.lags`, `time.minimap_lag`,
`time.minimap_fade`: its drawings are averaged), so nothing on it starts
on a primary onset's frame and nothing on it moves a pixel in one.

## The scenes

| Scene | Shows | Split, lens | Recording |
| --- | --- | --- | --- |
| `title` | the series (six programs, named) and the legend of the marks the scenes use | a card | |
| `fib` | recursion: each call a frame and a node | `subject`, `calls` | `steps` |
| `list` | a list reversed: each `next` turned; it opens on the map and dives into the frame; after the first load the pointer loaded opens in a loupe, and the `next` in it one deeper | `subject`, `nodes` | `list` |
| `sort` | insertion sort as its blocks: one trip of the inner loop walked a block at a time (each block's rows a cascade onto its last, then `leave` along the edge it takes: the compare's chips framed, the edge drawn gold, the mark along it, the target's count struck; `turn` up the inner loop's lane), the next trip at a run, the long middle a sprint on the map (`surface`, the gold going block to block, the counts growing, `dive`), the last value's trip walked again, the way out run | `blocks` (`graph.Blocks`; the disassembly its view over the state column, the source alone in the program column); on the map the graph with its rows (`Context.Options.graph`) | `sort` |
| `syscalls` | glibc's `hello`, by instruction from main: `open` followed down (main's call ringed, the PLT's stub passed, libc's wrapper run to its last three instructions and those walked, its source beside it where the build has it (open64.c, and sysdep-cancel.h where the pc is in what that header's macro made; `zig build sources`), the kernel's window at the floor with the call in C's form and `returns`, and back up), then `read`, `close`, `write` stepped over, each in three parts: the instructions before the call a cascade onto the call row, the crossing from that row with the kernel's window opening under it (the rows after it making room), the stores after it 18 f after rax | `beside`, `syscalls` (the calls so far, as strace writes them); the disassembly a `descent` (`Context.Options.descent`) | `hello` |
| `musl` | the same `hello` built by Zig against musl, static: `open` followed down with no PLT and no GOT, the source panel following the pc through musl's own files (open.c, `__syscall_cp.c`, the one line of `syscall_arch.h` that is the `syscall`), the kernel's window, and back up to `main` | `beside`, `syscalls`; the disassembly a `descent` | `musl` |
| `heap` | glibc's malloc under a list of three: three pushes, two pops, a push, told by motion.md's storyboard (nine captions; pushes 2 and 3 at a run; each `free` and the `malloc` that takes the head back walked; what the storyboard does not narrate runs: the calls into push and pop with their prologues, the returns to main but the one under the second free's long caption); the chunks by fields (`size`, `protected`, `key`), the program's list over the tcache's free list with its `bin` (a chunk in neither list drawn in the program's row, unarrowed), the tcache in a loupe over the stack, its stem down the gutter from its chunk's row, opened in each step that changes the tcache and closed at its advance | `subject`, the scene's own drawing (`nodes` in two rows) and view, both on its map too | `heap` |
| `zoom` | one line of C as its instructions, the call's bytes | `none`, the camera at x1.16 on the instructions and the stack in one view, cause and effect (the stack's window set before the move and held); the map's drawing the calls of `fib` (`Map.drawing`) | `steps` |
| `sqlite` | a row's way to disk in SQLite: from `sqlite3_step` to `sqlite3BtreeInsert` (three continues, the row's struct on the stack), the commit's `unixWrite` nine calls under `main`, `pwrite64` of page 2 into the kernel, and the page read as a B-tree leaf | `subject`, `backtrace` (`Context.Options.backtrace`), then `syscalls`; its view a `hexdump.Dump`; as the caption names them, rdi's `BtCursor` opened in a loupe, then rsi linked to its row in the view (`Context.tiesWith`); the page's fields named a group at a time, 2 s apart; the backtrace lens drawn on its map | `sqlite` |
| `gallery` | every block in its states, a page or a state each 3 s; at 21 s the `blocks` lens (at rest, `leave` mid-way, `turn` landing, libc's `open` folded), at 24 s the graph with its rows as the map draws it, at half size (sort's panned to its loop; `open` at its `syscall`, the blocks not reached folded) | all three, `blocks` | `gallery`, and for the graph pages `test/gallery/sort.ztrace` and `hello.ztrace` |

## The blocks

The catalogue's layers, and where each block is. Every block is drawn in
every state the code has in the `gallery` scene.

| Layer | Block | Where | Notes |
| --- | --- | --- | --- |
| 0 tokens | grid, colour, type, the splits | `src/theme.zig` | per "Token changes" (`metric.calls`, `time.pin`, `time.continue_wave`, `time.relayout_fade` there; the insn's character counts gone); JetBrains Mono NL (`.code*` faces) for all mono, Medium under 30 |
| 1 atom | `address` (`lead`, `name`, `rwx`), `value` (and `Ui.typed`: `fd`, `bool`, `char`), `arrow` (`points`, `holds`, `more`), `mark`s, `plaque` (`chip`), `pin` (`row`, `under`; and at a view's row's end, `Ui.pinEnd`), `bracket` (`quiet`, `tie`, `thread`), `tag` | `src/ui.zig` (`Ui.address`, `.value`, `.arrow`, `.written`, `.corner`, `.read`, `.cellWritten`, `.cellRead`, `.current`, `.trail`, `.unknown`, `.chip`, `.pinRow`, `.pinUnder`, `.bracket`, `.panel`) | marks as mock 15's column B: `current` the white wash (`color.wash`) and the gold plaque; `struck` the softened paper (`color.struck`) with bold bright digits; `held` a turned corner (9; 12 on a lens's cell), in over the cool's last 6 f (`Heat.corner`, `time.strike.corner`); `armed`, `read` |
| | `byte` | `src/rows.zig` `bytes` | `number`, `pointer`, `text` (a string's ink), `loose` (a byte of no field: the allocator's, padding, past what a dump is of), `unread`; `pad`; `bytesAt` moves the bytes right of a long (stack) address, by the dump's widest; a write's arm, strike and held corner cover the bytes whose value changed, first to last (`Run.changed`, `Now.changedBytes`), struck a byte a frame from the low address (what a read fills, 2 f apart); until its strike lands (s+3) a run keeps its old bytes and their reading, through the arm, read by its old field where the step retypes it (`hexdump.keepOld`, `Fields.was`) |
| 2 row | `chain`, `reg` (and `rip` with the flags), `slot`, `line`, `bytes`, `call` (`span`, `callRow`) | `src/rows.zig` | `chain` follows `zt.telescope.chase`; cut at its far end, `more`; a register's reads memory as the panels show it, the step's bytes from their strike (s+3): its later hops fade out from the strike and are followed again 4 f after the bytes land (`Now.following`, `Marks.hops`). `slot`: pins from 16, the offset from rsp ranged right to 172, the address at 184, the chain, its role ranged right where the room ends (48 sooner in a pane: its strip), from `zt.telescope.slots` (`saved rbx`, a local's name in primary, `n, high half` for a narrower local in the word's top four bytes, `argc`, `argv[0]`, `argv end`, `envp end`, `auxv`; nothing for a return address or `.none`). `bytes`: the bracket at 24, the address at 34, the bytes 12 after it and at 132 at least |
| | `arc` | `src/rows.zig` (`Arcs`), `src/hexdump.zig` (`pointerArcs`) | a pointer to a row of its own panel: lanes at 4, 10, 16 in a dump or a loupe, 4 and 10 on the stack; longest outermost, a chain in one lane; standing at 60% toward the page, full in the step that writes or reads it and always in a loupe; rewritten: the old dashed with the arm, fading from 6 f after the strike as the new draws (12 f), quieting with the cool; a lane change glides while the arc that causes it draws or fades (`Arcs.assign`, with and without the arcs on their way); a stub to the rule for a target in the region past the window, only in its step; a saved rbp's only in its step, going with its advance (18 f); a dump withholds the arcs an open loupe carries |
| | `insn` | `src/disasm.zig` | columns at 2, 31, 40, 134, 180, 264, 564 (540 in a pane, whose strip takes 48 of the row; `map.content`); size words dropped from every operand, a `width` of byte cells (`metric.width`) after the `]` where no register outside the brackets has the access's size and the mnemonic does not fix it; `nop` and `endbr64` faint; a PLT target named (`401070 open@plt`); the annotation from 564 or a character after the operands, then the operands give way, never inside `[]`; `current`, `ran` (every instruction of the last three steps), `ahead`, `outside`, `waiting`, `pass`; the jump lane from the jump just before the pc's moment. The row's detail, every value the recording's at that moment: a compare's two values and the flags it leaves as chips (those the conditional after it reads; CF ZF SF OF when none); a conditional's `taken`/`not taken · reads` and its flags, `→ target` when it leaves the window, and while it runs the setting row's chips and rip's framed as read (an echo); `lea`'s `= value`; a call through memory or a register `→ target name · read from open@got, 403fd8` (out of room the slot goes, then the digits); a call through a PLT stub by the function it reaches (`the resolver` while its slot is lazy); `fs:[0x28]` as the stack's canary (`canary` where the row has no room); a `rep`'s count and step; `syscall` with its name and number, its arguments under it by register, typed (`-100 AT_FDCWD`, `O_RDONLY`), the rows they hang over giving up their own annotation; a call that has run in C's form with its result (`read(3, …) = 15`: out of room the arguments go from the right, the result stays); a memory access narrower than a word read at its width (`rows.narrow`: `7fffffffecc4 ◂ 15`) |
| | `descent` | `src/descent.zig` (`Descent`, `step`) | the disassembly a call deep: the root's window on top (main), each callee's under the row that called it (that row `waiting`, ringed, its annotation the call in C's form), a PLT stub gone through kept as its `jmp`, `pass`; a head row over each window (the name at 40, Go Medium 18; what it is ranged right: `libc.so.6 · open64.c` (the file of its function's entry, where the build has the source), `libc.so.6 · no source`, `the PLT · its jmp reads open@got, 403fd8`, `the PLT, jumped through`); the call lane at x 14; the nearest caller takes the rows the deepest does not use, all above its call row (one row after it, the return row, the callee's head directly under that), and where its function starts first the rest go back to the deepest window; three code windows at most, the rest one `more` row; each window's addresses its own width; the tag the deepest function and its module (`open · libc.so.6`); at a `syscall` (and the stop after it) the floor's three rows are the kernel's: in a crossing the lane down from the plaque (3, vellum), the window filling down, `the kernel` and `openat, system call 257`, the call in C's form, `returns` struck, `rcx, r11: clobbered`, the answer climbing the lane (24 f, `glide`), the window drawing back at the advance. A crossing stepped over opens the same window under the call row, past the arguments hanging under it, the rows after them making room (18 f) and closing up with the window. Every row keyed (an address, a head), so a step is the rows both stops have gliding and the rest leaving or arriving on its verb's timetable, in two moves, never at once: `descend` (2.9 s: the given-up rows fade 66–78, the kept ones glide 78–96, ring 84–96, lane 96–114, head 108–120, rows 114–138), on through a stub's `jmp` (2.2 s), `ascend` (2.5 s: the window closes 48–72, lane back 72–84, the kept rows glide 84–102, the given-up ones fade in 102–114), `cross` (`syscalls.step`); a row whose state the verb changes (the call row to `waiting` with its hanging arguments, a jmp to `pass`, a waiting call taking its result) crossfades; with it the source's line `waiting` where the pc is in code without source (ringed, the tag `main waits at line 6 · the pc is in libc's open`, crossfading over the 12 f before the advance, as a stack span's name does) and the thread waiting (primary, 2); where the build has the library's source the panel goes on with the pc into it. Its strip is the deepest window's function's linear column (a `Disasm` drawn for the strip alone, `Map.In.strips`), that window framed on it; going down or up it fades through as the mark lands (`map.through`) |
| 3 panel | `registers`, `stack`, `backtrace` | `src/context.zig` | rip's value crossfading over the advance, a flag set or cleared over the 6 f it lands in (`rows.RipWas`); the backtrace newest at the bottom, `#0` last, the oldest dropped from the top (`newest at the bottom · 2 more above`), as a panel, the calls lens's view, the backtrace lens and on the map, all one block (`backtraceRows`: frames leave, slide and arrive; what a kept row says that changes, its depth, its pc's offset, its line, and the tag's count, crossfades, 12 f before the advance); the stack's window on `[rsp, rbp+16)` keeping the touched word in view, its tag the first and last word shown (`rsp+20 to rsp+48`), a word's role and offset, and the tag, crossfading (12 f from memory's strike) where the step changes them, rsp and rbp's pins travelling 18 f after rsp's strike (`time.pin`, keeping their place among the names they leave and join), at rest only where the register points; a window that moves farther than its own height (six or eight slots) fades out and in round memory's strike (12 f each; at a run half its step each), and what it brings, and what changed before it, is plain; while rows slide they keep their roles (those of both windows are read), and a word becoming a saved rbp, or no longer one, has its arc go or come with its role; a frame's name longer than the spans' room shortens the chains beside it; `call` spans and the backtrace (`#n`, name, arguments at 384, file and line) from `zt.telescope.frames`, the frames two stops share sliding to their new depth; the backtrace as a lens's drawing with `Context.Options.backtrace` |
| | `source` | `src/source.zig` | the file the pc is on a line of, of the recording's sources (`Recording.sources`, `shown`: the program's own, or a library's the build gave; else the last such line, a frame up, where the pc waits), whole in a window, its middle third; its lines cut at 63 characters in a pane (67 on the map); the trail's bars (of that file's lines) crossfading with the advance; numbers as wide as the widest file's largest line (SQLite's six digits), the text moved right by as much; another file: the panel fades through (12 f out, 12 f in), its tag's title and note crossfading with it, its strip with it (`map.through`); a window going farther than its own height in one file: the advance is 48 f, the window gliding on the strip for the first 24 (the gold lit on its new row there), then the pane out and in |
| | `disasm` | `src/disasm.zig` | 17 rows (9 as subject), fewer above near a function's start; on the map 69 from the function's start where the pc is in its first three quarters (a strip's column stays still while the pc walks it), else round the pc; the line column as wide as the source's, a row's number where its line is of the file the source panel shows (libc's rows open64.c's while it shows open64.c, main's none then); two windows that overlap scroll, others fade out and in; its tag's function (a descent's tag too) crossfading with the advance; a 2-unit `rule` across over each block's first row (not its function's), and the block's visits by the moment shown ranged right, faint (`×3`), where the row's annotation leaves room, crossfading with the advance (`graph.Rules`, a descent's windows too); the rows clipped above the panel's padding (a row scrolling out takes its rule with it) |
| | `graph` | `src/graph.zig` (`read`, `fold`, `place`, `layout`, `Blocks`, `Map`, `Rules`) | the function's blocks from the recording (`zt.telescope.blocks`; a block of `nop` padding nothing goes to left out), their edges by how each ends, and the run over them by the moment shown: each block's visits, each edge's count, the last three edges taken, the pc's block; counted where one stop in the function follows another across an edge, and only for a recording that stops at every instruction (`exact`; by line, visits only, every edge `rule`). Laid out (`place`, pure, by the whole recording's counts, so it never moves as they grow): back edges by a walk from the entry in address order, layers by the longest forward path, the blocks that return last; in a layer a block under the predecessor that reached it most often, then under the one it falls from, a taken target never taken right of it, the more travelled first where two want one column; columns a pitch apart (the map's as wide as the pc's block with its annotation, 928; the lens's 300); a forward edge out of the bottom on its target's side (40 in, 16 in the lens; the middle when straight below), along the gap's middle, into the target's top (arrivals 48 apart), through the right channel (32 out) where it would cross a block; a back edge down 14, out to its loop's lane (16 apart from 24, the outermost farthest), up, into its header's head. Too tall for its place (`layout`), in the catalogue's order: each run of blocks the whole recording never reached (neighbours in address order joined by an edge; split where folding would make a loop the code does not have) one dashed box, `+5b to +b9 · 5 blocks not reached` (said of the run so far: a graph says only what has happened by the moment shown, never what will not; which blocks fold, and where each block is placed, are still chosen by the whole recording); then blocks over 16 rows to four, `more`, four (not the pc's); then it pans, whole layers, to the largest loop the pc's block is in that fits, else the pc's block in the middle. The static part kept per function and form (`memo`), the moment's counts counted again each frame. `Blocks`: the lens's drawing, boxes 24 high, 60 and 10 a row wide (132 at least), the offset, the visits (`dim`), reached `raised`, not yet on the page, a fold dashed, the pc's framed gold 3; the edges never taken `rule`, taken `dim`, the trail's golds (the newest 3), a loop's turns on its lane (Go 18). `Map`: on the map two columns wide beside the source, each block a head (its address, `lines a to b`, `×n` primary) over `insn`'s rows moved 52 left, the offset where the address was (ranged right at 72); the annotation only in the pc's block (and its rows that ran in the last three steps, with their trail bars), which widens to its column, its rows' annotations kept inside it; a conditional's counts by its ports; a direct call's hook out of the block's side and back a row down, the callee named (`swap`); under a return the way out (stub 14, bar 28), a tail call's stub and name, an indirect jump's `targets not known` |
| | `blocks` lens | `src/graph.zig` (`Blocks`), `theme.layout.split.blocks` | its drawing the graph as shapes over the program column (296 high), which then holds the source alone (twenty lines); its view the disassembly itself, seven rows over the state column; the registers over six words; no thread (the disassembly is not under the source: it fades with the distance between them) |
| | `hexdump` | `src/hexdump.zig` | malloc's words: a field read as `size` (`0x20 a m P`, the bits as rip's flags) or `protected` (`→ 405050 ^ 405`, `NULL ^ 405`, its arc to the pointer it protects), and a field's `note` (Go 18 faint: `key`, `top`, `slots left`); a lens's view (`hexdump.panel`): `bytes` rows and their reading, veiled at a sprint; a row whose bytes the step changed where the recording saw no write (memory nothing watches, read anew at a stop), or that became known, crossfading over 12 f (`rowPasses`); one reading for every dump (`hexdump.reading`), a list a character apart, a typed number as its type reads (`char` quoted, `bool` by name); the address room once a dump, by its widest; `Dump`, a view of a region by the fields a scene gives it (`Field`: where, how long, read as a number, big-endian or not, a pointer, text, or left to the eye), the rows that hold a field and a `more` row for each stretch left out, and where those rows outnumber the window, a window kept round the first row a mark or the step is on, the rest folded into `more` rows; marks the scene plays, and the step's only from the stop it came in at (`since`); the bytes a syscall was given as the kernel took them (`given`), and only what the debugger read at the stop (`seen`) |
| | `loupe` | `src/loupe.zig` (`canim.loupe`, `Loupe.open`, `.close`) | from a register, a loupe's field, or a dump's row read by the scene's fields (`.row`: malloc's tcache, `num_slots[0]` and `entries[0]`, the rest `more`); five rows round a pointer's target, lifted (`color.lift`, `lift_tag`, `shade` 12 and 16; 20 and 26 deeper), hanging from its pointer (its tag on the row's foot, 92 left of the digits, clamped to the stage), a 4-high bracket under the digits its stem, the target's fields framed bright; one opened from the band's view lies over the stack, never the registers, its stem down the gutter's right lane (x 962), its fields struck once it has opened (6 f after, 6 f apart: `Fields.struck`); a deeper one with no room to the right hangs under the one it opens from, its stem down to its tag; a note that does not fit is cut at a word with `…`; `open` 36 f (read 6, stem and rise 18 with the shadow, the frame 6 f after), `close` 12 f; it opens again after a close |
| | lenses: `nodes`, `array`, `calls`, `syscalls`, `backtrace` | `src/nodes.zig`, `src/array.zig`, `src/calls.zig` (`Tree`), `src/syscalls.zig` (`Crossing`), `src/context.zig` (`Backtrace`, `lens`) | the drawing in `band` (over the program column), its view in `view` (over the state column): `nodes` and `array` a dump (`hexdump.panel`), `calls` the backtrace with arguments, `syscalls` the calls so far as strace writes them (oldest on top, the newest coming in once it is back, held; the rows make room for it, a full log scrolling a row, 24 f, `glide`, the count above crossfading; out of room a row gives up its faint names first, then its arguments from the right, and keeps what it returned; a path by its string, the kernel's capture where the stop did not read it) over the bytes the call crossing in the step is given or fills (in with the argument framing, 12 f out and 12 f in; what a read fills landing a byte every 2 f, struck, the stack's words with them; a write's buffer framed as read while the kernel takes it; cleared with the log's new row: between crossings `no call crossing now`), `backtrace` (eleven rows as subject, five beside) a `Dump` the scene gives; an `under` pin's names in the order they came, the first left, faded out through the middle of a register's joining or leaving (`Pins.text`); a call node's look (gold, ringed, done) crossfading as the tree's moment changes (6 f), and at a sprint a new node coming in over its step; a left child's result on its left shoulder, off its parent; a view's row a register points into carries the register's `pin` at the row's end (`hexdump` `rowPin`; 48 to the left in a pane, its strip at the right), the reading ending before it; at a sprint the array's pins hold and move where a phrase ends |
| 4 tie | `thread`, `link` (and its `pin`), `projection`, `echo` | `src/ties.zig` | panels publish places (`anchor`); `Ties`, added last, draws in the channels: a link climbs to a node by the gutter's left lane and goes down to a slot by the right, its name riding its head, a target past the stack's window a stub and a row count; to a view's row (`dump_pin`) by the left lane, into the row's edge; on a beat the narration names (`Context.tiesWith`, `ties.Beat`): the register framed as read, then its link, held, drawn back with the frame; a projection from the view's bytes, or from a frame's return address to its call's node |
| 5 frame | `map`, `minimap`, `dive`, `surface` | `src/map.zig` (`Map`, `split`, `strip`, `Map.strips`), `Context.map` | the working frame's panels bound to a stage of 3840 by 2160 (`map.split`, packed by content: each box as long as the most rows its panel has wanted, `measure`, the backtrace's as long as the deepest call chain of the scene's way, so that it is packed once; the drawing, the source and under it the backtrace; the disassembly; the view (none where nothing draws one), the registers, and in the column's rest the stack going on, `stack, continued`; the stack from 16 words above rsp; and the first two columns' rest (`Split.spare`) given, in the catalogue's order, to `map.Spare`: a five-row dump round each place the registers (pwndbg's order, not rsp or rbp) and the 64 words up from rsp point at outside the stack and the code, none within another's rows, then the loupes open (`Map.loupes`, lifted, nine rows), then the key (the recording and the moment, the marks as drawn, the inks); only then page); its rows published while `ui.mapping` (the dumps' too); the working windows outlined (2 `dim`, 4 out), each window published with where its step took it from and how far its scroll has gone, so its outline glides; the thread across the gutter (x 1008), gold; a scene without a band can put a drawing on its map (`Map.drawing`); with `Context.Options.graph` the disassembly is the function's graph (`graph.Map`), two columns wide beside the source, the registers over the stack in the last column, no band (the lens's window on it is the graph whole, the disassembly's the box round the rows it shows), no thread line (the gold line number is the thread). Each pane's minimap (`map.strip`): a strip 40 wide inside its frame at its right, under the tag, on `well` (`theme.strip`), drawn from its column of the map (the source's boxes, the stack's with `stack, continued`, the view's dump; the disassembly's the linear rows round the pc, drawn for the strips alone where the map has a graph or a descent: `Map.In.strips`) at 4 units a row and 36 of 880 across, from what the map drawn for it collects (`ui.strokes`, `ui.collected`: each run of text a stroke 3 high in its ink 65% from the page, the marks 4 by 4 at a row's left in the catalogue's order, an arc with an end off the window a 2-unit line down the left edge, a block's first row ticked); a column longer than the strip the rows round its window, the window in the middle, clamped to the ends, three faint dots where it goes on (fading in over its first row's scroll); the window framed 2 in primary; a mark no working window shows (a word struck or read on the stack or in the view's dump) flashing on its row (a ring 8 to 14 in the mark's colour, 12 f). The strips are one image a frame (`Map.strips`): the map drawn for them six times, each from the cursor's mirror a frame later (6 to 11 f behind: `Cursor.lagInto`) with the panes' windows as long ago (`past`), every strip drawn as it shows (its rows, dots and window in place) and the six averaged, so that every change on a strip fades in over 6 f from 6 f after its onset and nothing on it moves a pixel in a frame; the panes blit their part (source, disassembly and its descent and the `blocks` lens's view, stack, a dump's view: not the registers, a drawing, a loupe, the backtrace, the `syscalls` lens's log). A pane with a strip has 48 less for its rows (`map.content`). `Map.show`, `.dive` (outlines bright 6 f, veil to 24, each panel from its window to its place 60 f, 6 f apart, a panel drawn over another setting off first (drawing, view, disassembly, stack, source, registers) so that none in its place is crossed by one on its way, opaque on the way, its rows on the window's rows, its tag and rules in from 84 f; with each, the rest of its column (the rows its strip shows) squeezing from its place on the map into the strip, its width and height each on its logarithm (to 36 of 880, 4 of 24 a row), its window's outline riding on it, gone into the strip's own drawing over the 12 f before its pane lands (`Map.squeeze`, `stripShows`); the map's other parts fading where they are, 24 to 72; 120 f and 30 f still), `.surface` (the dive back, 84 f, then 30 f still); per-panel transforms through `context.at` (`context.zoomed`); the clock's count ranged right at 1856 |
| | `stage` and `relayout` | `src/stage.zig` | splits `none`, `beside`, `subject` (`theme.layout.split`): the band is `band` (the drawing) and `view`; `relayout` fades the drawing round its move; `holdStack` holds the stack's window for the camera, with `free` slots |
| | `clock`, `caption`, `veil`, `card` | `src/words.zig`, `src/root.zig` (`Narrator`, `Camera`) | the clock still while a step plays, its piece fading in once the mark lands; a caption stays its reading time; the title card is `scenes/title.zig` |
| 6 verb | `fire`, `arm`, `strike`, `cool`, `read`, `extend`, `link`, `project`, `travel` (pins), `advance`, `cascade`, `continue` (`Cursor.continue`, `Plan.wave`), `run`, `sprint`, `establish` (`Context.establish`: a drawing's elements fade in rising, no lines), `scroll`, `relayout`, `visit`, `say`; `leave` and `turn` (`graph.leave`, from a block's last row, `graph.toEnd` to get there: fire 0–12; the compare's chips framed as read from 18 (the CPU's slot, the jump's echo), held while the edge draws gold, head first, 24–42; the mark (a gold plaque, half size in the lens) along the edge 42 to 42 + 12 f and 2 f a 100 units of the lens's edge (30 f at most), up the lane for a turn; landing, the advance; the target's count armed and struck 6 f after (a turn's lane count as it lands), cooled to nothing by the step's end; the trail recoloured over 18 f from the landing; a rest of 42 f from the landing); over a graph at a walk of several blocks, a run or a sprint the trail, the counts and the gold crossfade with the advance (8 f at a run, the step at a sprint), the pan gliding with it | `src/cursor.zig` (the timetable), `src/graph.zig` (`leave`, `instant`), the blocks (each draws its state at the instant) | tokens in `theme.time`; a level gives up its slot when nothing it touched is drawn (`Recording.drawn`); a label that changes in place with a step crossfades over the 12 f before the advance, or from the step's start where that is sooner (`Now.renaming`); at a run what marked a value goes with the run's ease (8 f) and a pin changes over it; at a sprint an ember and what grows come in over the step (4 f), never in a frame |

`Recording` (`src/Recording.zig`) is the index every block reads: lines,
calls, syscalls, allocations, which registers and bytes each moment changed
and read (a debugger's `touch` reads count), each moment's `touch` and
`branch`, and each instruction's line.

## The recordings

`build.zig` records six programs of `tools/` under `ztrace record` (the
debugger: registers, the stack, what they point at, the instructions round
the pc with their lines and callees' parameter counts, what each stack
word is (`zt.telescope.slots`), at every stop: `--stack 1024 --around 256
--disasm 69`, what the map needs, except where noted), each
by a bare name in a directory of its own with an empty environment, without
address randomisation, with the tools built `ReleaseFast` (a step through
the agent's or the runtime's code is a moment, and a slow tracer stretches
the clock's retry loops it steps through). The instrumented ones are built
`-no-pie -fno-stack-protector -Wl,-z,now`: short addresses, no resolver
and no canary stepped through that the source does not say.

A dynamic program's libraries (glibc, the loader) are named by their own
debug info where the debuginfod client's cache has the file of their build
id (`$DEBUGINFOD_CACHE_PATH`, else `$XDG_CACHE_HOME/debuginfod_client`,
else `~/.cache/debuginfod_client`): their frames carry names and lines.
The recorder finds it by `DEBUGINFOD_CACHE_PATH`, which the program
inherits and keeps in its environment, so it is `debuginfod`, a link
beside the program to the cache: the program's environment says
`DEBUGINFOD_CACHE_PATH=debuginfod` (rdx at main's start points at it),
nothing of the machine. A static musl program's are its own (Zig builds
musl from its sources with it).

**Sources.** A recording's lines name files other than the program's own
(libc's `open64.c`, musl's `open.c`). The build gives each scene those it
has (`tools/sources.zig embed`, every build, no network: the recording's
`<name>-sources` module, `Program.sources`, path and text): musl's from
Zig's lib directory (`zig env`), the rest from the debuginfod client's
cache, `<cache>/<build id>/source/<path as the debug info names it>` (a
directory of canim's own beside elfutils' entries there: elfutils' own
source layout is not documented on this machine, and gdb does not share
it). `zig build sources` fetches into it what it lacks, of the modules
named by a separate debug file (a distribution's library, never the
program's own), from the first server of `$DEBUGINFOD_URLS` or
`/etc/debuginfod/*.urls`: `curl <server>/buildid/<build id>/source<path>`,
which sends the build id and the path and curl's defaults. Without the
cache (or before the step) a scene shows a library without source, as
before. The source panel follows the pc into any file it has
(`Recording.shown`).

| Name | Program | Stops | Moments, bytes | Also |
| --- | --- | --- | --- | --- |
| `steps` | `fib.c`, static musl, `-O0` | every instruction | 1999, 601 KB | |
| `hello` | `hello.c`, the system's clang and glibc, dynamic: `-O0 -g -no-pie -fstack-protector-strong -Wl,-z,now` (a PLT bound at load, no resolver; the canary) | every instruction, `--from main`, `--steps 132` (to main's return) | 166 (30 of them the loader's syscalls before main), 110 KB (83 KB before libc was named) | reads `tools/note`; PLT stubs and GOT slots named (`open@plt`, `open@got`) |
| `heap` | `heap.c` (design/mock/heap.c), the system's clang and glibc, dynamic, as `hello` | every line, `--from main`, `--steps 46` (to main's return: libc's lines, named now, would take it on through `exit`), and pop's `call free@plt` (`break_call`: a breakpoint objdump finds, which a line-stepping recorder now stops at) | 78, 74 KB | `--heap` (`ztrace.heap.glibc`: chunks, the tcache, bins, the arena); `-w 0x405000,1024` (the chunks' bodies) and `-w head` (the global the list hangs from: unwatched, a recording keeps a global as last seen) |
| `sort` | `sort.c`, `ztrace cc --instr vars --only sort,a` | every instruction, `--from main` | 4446, 984 KB (4396, 751 KB before libc was named) | `--ring`: the variables' names and types; each `__zt_var` call is stepped (4 of them) |
| `list` | `list.c`, `ztrace cc --instr vars --only push,reverse,head` | every instruction, `--from reverse` | 2913, 1035 KB (2920, 743 KB before libc was named: the count differs by a few moments from one recording to the next, not looked into) | `--alloc --preload` the agent: allocator headers are read; the pushes (the agent's and the runtime's first calls) run through |
| `musl` | `hello.c` again, built by Zig for `x86_64-linux-musl`, static, `-O0 -g` (musl compiled from its sources with it: no PLT, its lines its own) | every instruction, `--from main`, `--steps 166` (to main's return) | 173, 55 KB | reads `tools/note` |
| `gallery` | the old `list` by line, kept in `test/gallery/list.ztrace`; for the graph pages `sort` and `hello` as recorded on 11 November (with blocks), kept in `test/gallery/sort.ztrace` and `hello.ztrace` (`gallery_sort`, `gallery_hello`) | | 134, 88 KB; 776 KB; 87 KB | the gallery's pictures depend on the drawing only |
| `sqlite` | `sqlite.c` (three rows into a table, committed) with SQLite 3.50.4's amalgamation, system clang `-O2 -g -fno-omit-frame-pointer -no-pie -fno-stack-protector -Wl,-z,now`, glibc | `--by break`: `sqlite3_step`, `sqlite3BtreeInsert`, `unixWrite`, and the instruction after its `pwrite64` (found by objdump); every syscall recorded, `-s 4096` | 181 (42 stops, 138 syscalls), 494 KB | made only with `-Dsqlite=DIR` (default `~/05-genizah/sqlite/sqlite-amalgamation-3500400`), in a new temporary directory each time; `sqlite3.c` is embedded as the source |

What builds each program: `fib.c` (`steps`) and `hello.c` for `musl`,
Zig's build (`addExecutable`, musl, static); `hello.c` for `hello`,
`heap.c` and `sqlite.c`, the system's clang against the system's glibc,
dynamically (`hello`'s PLT and GOT are the scene, as a C programmer's
build lays them; the heap scene is glibc's own allocator; `sqlite` is
built as the bench builds it, and its scene is glibc's `pwrite64`);
`list.c` and `sort.c`, `ztrace cc`, the system's clang with the
instrumentation pass, a plugin of that clang's LLVM.

Every recording the build makes carries each function's blocks
(`zt.telescope.blocks`, at the first stop in it) and a `branch` event at
each stop on a jump: the graph and the linear rows' block rules read them.
The old `list` of the gallery has none, and draws none.

A recording that begins inside a call (`--from`) has that call open from
its first stop (`Recording.index`, from the frame chain). Writes are the
bytes whose value changed, to the element the instruction stored (its
`touch`); a store of the same value is kept apart (`storedSame`) and
counts as assigning a local (and as a name coming to a node's pin). A register's change over a step is net: a
call's rsp put back is not struck. A call into the vDSO (the runtime's clock) is one moment, as the tracer
now records it: `list` and `sort` have `--stack 1024` like the rest. An address no symbol
holds is named from its module's first mapping (`list+2c89`).

## Motion, as measured

`tools/chart.py chart` on the 1080p exports (the designer's
`design/motion/motion.py`, its checks and its regions told where canim's
panels are (sort's the `blocks` split's: the drawing, the view that is
the disassembly, the source alone, the registers and the stack), each
pane's strip a region of its own (`source strip`, `disasm strip`,
`stack strip`, and `view strip` where the view is a dump: `motion.strips`,
the pane's region stopping 42 short of its right edge), secondary action
like the words (no CROWD), its one-frame changes POPs; the clock, its
count ranged right at 1856, its own region, whose count changing in a
frame is no POP; the caption's box from 940, under the clock's count and a
run's step counter). `design/motion/motion.py` itself has the strips'
regions by split too (`--regions none|beside|subject|blocks`, and the
default frame's columns less their strips). POP: any region still
for 12 f that changes in one frame and is still again. A one-frame change
that is right is counted apart by name (`POP exempt`), never dropped:
`keyframe`, x264's I frame (`-g 600`: 10, 20, 30 s) re-quantizing a still
region, under 200 pixels moved (motion.py reads the video's I frames with
ffprobe; the caption check skips such a frame and the one after it too);
`cut`, the gallery's pages, which are the catalogue's pictures cut one to
the next (chart.py names their times). The videos are x264 without
adaptive quantization (`aq-mode=0`, 18% larger): with it a still glyph's
edge was re-quantized as the rest of the frame moved, a one-pixel column
flickering in fib's caption band at 7.45 s that the instrument took for an
extra caption (the rendered frames there are identical; with `aq-mode=0`
fib's first 600 frames have no such column). CAPTION: up over 720 f, up under
90 f + 3.6 f a character (chart.py counts the characters of the scene's
`says.line` strings as shown; where the video's arrivals and the scene's
captions do not pair up it says so and checks no reading time), or the
picture moving within 60 f of its arrival; chart.py does not count the
list's dive (150 to 300 f) as a caption's change.

| | fib | list | sort | syscalls | musl | zoom | sqlite | heap | gallery | title |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| POP, before / after | 12 / 7 | 13 / 8 | 3 / 6 | 25 / 7 | – / 12 | 12 / 6 | 8 / 5 | 19 / 16 | 9 / 11 | – / 0 |
| of them the corner minimap's / the strips' | 5 / 1 | 6 / 1 | 2 / 5 | 17 / 1 | – / 1 | 6 / 1 | 3 / 0 | 10 / 6 | 4 / 4 | – / 0 |
| POP exempt, before / after | | | | | | | | | cut 5 / cut 5, keyframe 1 / keyframe 1 | |
| CROWD, before / after | 3 / 4 | 8 / 8 | 10 / 10 | 3 / 4 | – / 2 | 1 / 1 | 1 / 1 | 16 / 16 | 5 / 5 | – / 0 |
| METRONOME, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 |
| CAPTION up over 720 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | |
| CAPTION under its reading time, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 | 0 / 0 | 0 / 0 | 0 / 0 | | |
| CAPTION picture moving within 60 f, before / after | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | – / 0 | 0 / 0 | 0 / 0 | 0 / 0 | 0 / 0 | |
| AIR, before / after | 0 / 0 | 0 / 0 | 1 / 1 | 0 / 0 | – / 0 | 1 / 1 | 2 / 1 | 0 / 0 | 1 / 1 | – / 1 |
| seconds, before / after | 42.0 / 42.0 | 81.7 / 81.7 | 63.8 / 63.8 | 83.8 / 83.8 | – / 68.9 | 33.5 / 33.5 | 62.9 / 62.9 | 78.6 / 78.6 | 27.0 / 27.0 | – / 12.3 |

"Before" is the last pass's "after". The musl scene is new; the title's
export is the last pass's size to the byte (it was not in that table). The
corner minimap is gone and its fires with it (a repack landing in one
frame for all six drawings; its windows' outlines drawn from the frame's
own scroll): syscalls' 17 were most of its 25, in the run through `open`.
The strips that replace it are each the average of six drawings a frame
apart, their windows too (`past`), so a change on a strip fades over 6 f.
sqlite's AIR at 32.95 is gone. Sort's and heap's strips' counts are
mostly not the strips': see below.

What this pass built (design/README.md's "The map and the minimap",
mocks 10, 11, 20 and 39; the source following the pc):

- Each pane's strip (`map.strips`, `map.strip`, `map.through`): its
  column of the map at 4 units a row, the window framed, the gold, strikes
  and reads, an arc's end off the window down its edge, a flash where a
  word changes outside it; the corner minimap removed, the clock's count
  ranged right at 1856. `dive` squeezes each pane's column into its strip;
  `surface` the reverse. The strips' regions in `tools/chart.py` and
  `design/motion/motion.py`.
- The source panel follows the pc into any file the build has the source
  of (`Recording.sources`, `tools/sources.zig`, `zig build sources`); the
  `musl` scene; libraries' frames named by file and line in the backtrace.
- On the way: `rows.fitted` clamps an infinite width (a Debug panic,
  `integer part of floating point value out of bounds`, in musl); the
  sketchbook's text cache holds 4096 entries and 128 MB, not 512 and 16
  (the map's text drawn six times a frame thrashed it: the list's dive
  0.46 s a frame, about 47 ms after); the heap's recording stops at 46
  steps (libc's lines carried it on through `exit`: 519 moments); the
  graph's counts, ink, trail and lane counts are by the moment shown.

Right in one frame, and exempted by name: the encoder's keyframes and the
gallery's cuts (above).

What fires still, by kind (located on this pass's exports; those not
looked at this pass say so):

- The strips' regions: fib 30.37, list 3.87 (in the dive), syscalls
  5.10, musl 63.23, zoom 23.18, 12 to 24 pixels each. Sort's 31.63,
  32.18, 33.93 and 35.25 are the map's own panels under the source
  strip's region while the sprint plays on the map (as the view's 32.25);
  52.50 is 14 pixels. Heap's six (12 to 98 pixels) are in the stack
  strip's region: 65.07 is a loupe passing over it at a step's first
  frame, the rest not looked at. The gallery's 12.22, 18.15 and 20.82 are
  at a state's first frame, as its view's re-windowing.
- The stack: a few pixels in the arcs' lanes and the pins (fib 8.20,
  19.50, 24.90, 39.13; syscalls 29.13, 57.72, 70.17; sqlite 20.43,
  31.75); musl's five, list's 7.30, zoom's 19.25 and heap's 55.23 not
  looked at.
- Registers: a held corner, a few pixels at a value's top left (fib 21.10,
  syscalls 44.32, sqlite 38.67); zoom's 12.80 and 16.40, list's 59.45 and
  70.45, musl's 62.57, heap's 13.68 and the gallery's 22.38 not looked at.
- The source and the disassembly: syscalls 17.92, the line going
  `waiting` and back with the descent's rows; zoom 18.10 and 19.60, an
  annotation taking its value in place under the camera; musl's five in
  the disassembly (31.33 to 66.35), the descent's rows, a library
  address's leading digits changing in a frame; heap 13.50, a scroll's
  first whole-pixel step from rest.
- The view: syscalls 64.77, the read's first byte landing over the
  buffer's dots; the gallery's view re-windowing at a state's first frame;
  sqlite 55.83 (15 pixels) not looked at.
- The drawing: fib 33.63, the calls tree's badge corner; the heap's runs
  (its 16 CROWDs too: the calls and returns it does not narrate); sqlite
  42.47, the system calls' log scrolling a line up from rest by whole
  pixels (1 every other frame at first); list's 13.12, 40.82, 67.65 and
  68.85 (120 to 277 pixels) not looked at.
- AIR: sort's and zoom's last picture (the last caption read, then held);
  sqlite 46.02, where the chart misses the read frame on one byte (`0d`)
  at 47.5 s; the gallery's atoms page, 3 s by design; the title's card,
  held by design.
- CROWD: the advance (thread, plaques and rip as one mark, the source and
  the disassembly scrolling with it), the veil over three panels at a
  run's first step; sort's `surface` and `dive`, every panel at once by
  design.

## What is not done

- The graph's truth: what it shows is the run's by the moment shown (each
  block's visits and `seen` paper, each edge's count and ink, the trail,
  a loop's turns: `countBy` counts to the moment), and a fold of blocks no
  longer says `never reached` but `not reached`. What is still the whole
  recording's: where each block is placed (`place`, by the whole run's
  edge counts: the hot path straight down, so the picture does not move as
  the counts grow) and which blocks fold (the runs it never reached): both
  say something of the future to one who reads the layout. Left for the
  designer's revision of the graph.
- The graph (`graph`): the map draws the disassembly as its graph only
  where the scene asks (`Context.Options.graph`: sort); the catalogue has
  it whenever the recording has the function's blocks. Not built for the
  rest: the descent on the map (graphs stacked, the caller folded to its
  call), a list scene that opens on the map and dives out of a graph, a
  2 510-block `sqlite3VdbeExec`. `spread` and `gather` are not built: in a
  `surface` and a `dive` the working rows and the lens fade on their way
  (`context.Zoom.shows`) instead of gliding into their blocks. A finished
  loop is not folded; a fold is not named (`multi-threaded: a cancellable
  call`) since no scene names one; an indirect jump's taken targets do not
  become edges. The pan is by whole layers to the largest loop the pc's
  block is in that fits: sort's ten layers do not fit the lens (its outer
  loop is 284 of 270), so the lens pans three times a trip round the outer
  loop (24 f, `glide`). A function change (the pc going into another
  function with blocks) is not crossfaded: the graph changes in a frame,
  and sort ends at its `ret` for that. A count struck as the mark lands
  cools to nothing by the step's end (no held corner: the steps after do
  not keep it); at a walked step across several blocks the counts, the
  gold and the trail crossfade with the advance, nothing struck. On the
  map a `leave`'s plaque fades out of its row (6 f) as the mark sets off
  from the block's port, and in at the landing; it does not slide along
  the rows to the port. The pc's block widens no further than the right
  channel: a block in the last column has no annotation room. A
  `syscall`'s or call's arguments hang only as far as the block's last row.
- Sort's recording is the instrumented build: eleven blocks (`setg`, a
  `test`/`jne`, two blocks of a lone `jmp`), not mock 22's eight; its
  prologue (25 rows, the instrumentation's calls) folds on the map to four,
  `more`, four, and the map pans to the outer loop. Mock 22's exit sits in
  the second column; here it is under its fall-through's block, as the
  catalogue's rule has it, and its edge runs in the right channel.

- The descent: the kernel's three rows are kept at the floor from the
  `syscall` to the stop after it, so the rows under the call move up again
  a step later. The fold past three windows (`2 calls: fib fib`), a lazy
  PLT's resolver row and the vDSO's window are written but no recording
  shows them; on the map the descent's box is as long as the rows it has
  wanted (the map draws the descent only where it is shown: the strip's
  column is the linear rows round the pc). At a run the windows do not open and close in 8 f with no lane
  (the syscalls scene walks every step of the descent).
- `open("note", O_RDONLY) = 3` does not fit 832 from 540 (27
  characters): the arguments go from the right, `open("note", …) = 3`.
  A call's arguments come from as many as the source's call writes, typed
  by the system call of the function's name (`open`, `read`): a libc
  function with no system call of its name has its arguments in hex.
- The heap scene's drawing and view are the scene's own components
  (`Lists`, `Chunks` in `scenes/heap.zig`), not blocks of `src/`: no
  second scene needs them. It is 78 s against the storyboard's 79.4: the
  seconds over it went to steps the storyboard does not narrate, walked as
  cascades (the calls into push and pop, 3.1 s, and their prologues, 2.9 s,
  four times; the returns to main); those now run, and the return under
  the second free's caption is walked again (its reading time is longer
  than its steps, and the picture would stand still 3.5 s). Each `free`
  is now mock 18's: its line's instructions a cascade onto its call row
  (the recording stops there: `break_call` in build.zig, a breakpoint at
  pop's `call free@plt` found by objdump, which `--by line` now honours),
  then the call stepped over from that row (a continue's wave, the line
  not fired again). A `size` bit that changes is not struck on its chip.
  The heap's map has its drawing and view but no arena panel.
- The map: `continued` is built for the stack and the source (which
  goes on under the disassembly when its column cannot hold its 69 lines;
  in no scene now, since the disassembly fills its column wherever the
  source is that long). The stack continued shows the words past what the
  recording holds as unknown rows (`··`), not folded into one `more` row
  after the process's start. A dump round a pointer is the bytes, typed
  by the objects the recording knows, its target not framed. Loupes are
  map panels only where the scene names them (`Map.loupes`: list, heap),
  and on the minimap they are strokes, not lifted blocks. The disassembly's
  and the view's boxes are still as long as the most rows wanted so far
  (`map.measure`, a frame behind; the backtrace's is now packed once, by
  the scene's deepest chain, so its box can be taller than the frames of
  the moment). The sqlite map draws the backtrace lens, not the calls so
  far it changes to, and no view.
- The strips are the average of six drawings a frame apart (6 to 11 f
  behind), the panes' windows in them as long ago (`past`, kept by frame
  number: after a seek the first eleven frames draw the windows as they
  are): every change on a strip fades over 6 f, at the cost of drawing
  the map six times a frame while anything moves (once at rest), text
  collected but not shaped. Their images are a process-wide cache of the
  host's. Native shapes are not antialiased and images are sampled
  nearest, so a window gliding moves a pixel at a time: averaged, each
  pixel step fades over 6 f. The map's disassembly is the function from
  its start where it fits (so a strip's column stays still in a
  function); a jump to another function scrolls the map's rows, and on
  the strip that slide is averaged into a 6 f blur, under the pane's fade
  through (`map.through`). The drawing for the strips draws every part of
  the map but the registers, the backtrace and the spare dumps.
- A pane's content is 48 narrower in the working frame
  (`map.content`), the map's not: the gallery's rows and any panel drawn
  outside a context too. The `syscalls` lens's view (the log over the
  bytes crossing) has no strip but its reading is still cut 48 sooner. A
  conditional jump's annotation (`taken · reads zf sf`) is not cut by its
  room: with a library's 12-digit addresses it runs under the strip by a
  few characters (syscalls' hurried run through `open`, sort's view).
- A far jump in one file (the source's window farther than its own
  height) takes 48 f: the window glides on the strip for the first 24,
  then the pane fades out and in. A far jump of the disassembly alone (no
  source window far) fades through over the advance with its window
  gliding on the strip over the same frames. A file change (another
  source) fades the panel and its strip through over 24 f; at a run over
  the run's 8 f advance (syscalls' hurry through open64.c and
  sysdep-cancel.h flips the file several times, each a fade). The far
  jumps seen in the finals are sqlite's, in its 262 899-line sqlite3.c,
  whose strip (the map's source panel, round the line the pc goes to)
  cannot hold both places: at a continue the strip goes over to the new
  place as the continue sets off (a 6 f fade, the gold lit there at once)
  and shows no window until the pane's lands there, about 2 s later; the
  step back from `pwrite64` (43.3 s) plays on the crossing's plan, whose
  travel is shorter, so the pane fades through in about 6 f, before the
  strip (6 to 11 f behind) shows it. The tag's note names the new lines
  over the 12 f before the advance, before the pane shows them.
- The heap scene never stops inside malloc or free (they are run
  through, by the PLT, at a line a stop): there is no frame of theirs to
  name, and no line column of theirs to show. Their lines are in the
  recordings as names only where a frame is (sqlite's, list's and sort's
  `__libc_start_call_main`, `libc_start_call_main.h:59`).
- `dive`: every panel travels 60 f (the catalogue's 72 f), so that
  seven of them 6 f apart land by 120 f; each pane's column squeezes with
  it, its rows the strip will show (the column's rows past them fade with
  the map, where they are), and goes into the strip's own drawing over
  the 12 f before its pane lands (the catalogue: 84 to 96 for all), the
  text drawn real all the way (no strokes until the strip's); a graph's
  disassembly (sort) has no linear column on the map: its strip comes in
  as its pane lands, from nothing; the drawing does
  not crossfade between sizes (the list's are the same, subject on both).
  Only the list opens on the map; only sort surfaces (its sprint plays on
  the map), and no far continue plays on the map.
- A loupe hung from a register keeps to the stage but does not yet move
  past the current marks or a changed row; on the 1920 stage a deeper one
  hangs under the first, not 120 to its right. The catalogue's stem is 3
  in its strokes and 4 in the loupe's anatomy: it is 4 here.
- At a run a dump's values, a register's and a stack word's crossfade
  (8 f); a node's value in `nodes` and a cell's in `array` still change
  in a frame (the heap's drawing crossfades its own).
- The gallery keeps the old recording of the list
  (`test/gallery/list.ztrace`): on the build's list (by instruction) its
  loupe page has no second loupe, the nodes being 32 bytes apart and a
  loupe's five rows holding the next one's target already.

- Back pointers between nodes still run under the nodes: a page keyline
  round each pin's stub and head shows them passing behind it (there is
  no lane for them in `beside`).
- An `under` pin's names are in the order they came to the node (the
  recording read back from the stop shown), so a name that lands where
  another is stays on the right it travelled on; but one left alone
  where it was on the right keeps that side only for the step in which
  the other left, and takes the left at the next. A third name coming to
  a pin whose two sides are taken is counted (`+1`), unless it is a
  variable the scene names and a register holds the right, which it then
  takes; on its way it is drawn over the right-hand name (list, 7.5 s).
  A pin's count (`+1`) can run into the left-hand name of the next
  node's pin (list, 26 to 57 s).
  (In the stack's lane,
  rsp or rbp travelling alone keeps its place among the names it leaves
  and joins; both travelling to rows with other names is not handled.)
- Pins travel with `time.pin`'s times, but on `standard`, not the
  catalogue's `glide`, in the stack's lane and the array; a pin in a
  drawing sets off when the idea strikes (the projection's arrival),
  not 18 f after its word's strike.
- The disassembly scrolls or fades over the mark's advance: 24 f where
  the source's window moves too, 12 f where the mark only jumps.
- Whether the stack's window faded at a step is judged by the slots it
  shows now: after a relayout to fewer, a step that scrolled may lose
  its ticks.
- A frame's name on a `call` span is never cut (`metric.span.name_max`,
  300 units, is not built); the calls tree's small and folded sizes are
  not built.
- A link to a slot past the stack's window ends in its stub and row count:
  drawn in the sqlite scene only (rsi to the struct on the caller's
  stack, `23 rows`, 5.0 s; in a continue a link sets off with memory's
  strike, when the window is at its new place). One to a slot above the
  window would put its count over the panel's tag.
- A call's result badge is on its outer shoulder (a left child's left, off
  its parent's disc; it lay on the parent, fib 24 s on): in fib(5) none
  lies on a node, but two neighbours' badges between their nodes are 4
  units apart (`1][1`). Past about ten leaves nodes and badges collide
  (the catalogue's known case).
- A view's row a register points into carries its pin at the row's end,
  its head toward the row (`Ui.pinEnd`): the catalogue's `row` pin has no
  lane in a dump, whose bracket and address take its first 34 units. The
  reading gives way to it (the read buffer's text reads `"Hello, …` while
  rsi's pin is on its row; the top's `top` note goes while a register
  points into its row), and a link to the row ends at its left edge, not
  at the pin.
- The zoom scene's camera goes to x1.16, not the x1.5 decided: the stage
  (1792 wide) holds the instructions' mnemonics to the stack's roles at
  x1.16; at x1.5 the stack's chains (`fib+42`) and roles (`saved rbp`, `n`)
  the captions name fall off its right edge, or the mnemonics off its left;
  the stack's call spans are off its right edge at x1.16.
- Bytes the recorder merged into one written span (a free's link and key,
  stored by two instructions next to each other) strike as one.
- The `pages` lens is not in the band (`Timeline` is the old far view).
- The map's drawing flags (`ui.mapping`, `ui.strokes`, `ui.collected`,
  `ui.bound`, `ui.chrome`), a dive's per-panel transforms (`context.zoomed`), the
  map's measured rows (`map.held`), the strips' images and the windows
  they keep (`map.atlas`, `map.past`, `map.current`), the ties' table and the thread's
  waiting are still process-wide globals, set and read in one frame's
  drawing (the measured rows a frame behind); two players at once would
  want them on the frame. Only the strips' lag is passed down now: their
  drawings get the frame's values with the cursor's replaced by a lagging
  mirror's (`Cursor.lagInto`), and `Cursor.now` no longer reads
  `ui.strokes`. The rest is read by components the frame reaches only
  through `anim.Placed`, which carries no frame state; moving them means a
  `Ui` that carries them from every component's first `context.at`.
- A recording holds the bytes it has seen, each as last seen: it cannot
  tell a byte read again and unchanged from one not read since. Memory
  nothing watches (SQLite's page cache) is read at a stop only where a
  pointer leads (32 bytes), so a view of it says what the stop read
  (`hexdump.Fields.seen`); a syscall's buffer is shown as the kernel took
  it, from its capture. The recorder should say what it read at each stop.
- A backtrace row's `file:line` is its call's, where the recording has the
  instruction before its return address (the debugger records the
  instructions at a frame's return address, their lines with them): a
  library's too where its debug info was found (glibc's
  `libc_start_call_main.h:59` and `libc-start.c:372`, musl's
  `__libc_start_main.c:95`), else none.
- A program's frame arguments are in the backtrace only for calls the
  recording tells (an instrumented program's); at a breakpoint the
  callee's are in its registers, which the scene's captions name.
- The sqlite scene changes what is over the band (the backtrace lens,
  then the calls so far) and its view (the SQL at rbx, the row, the
  page) by fades scripted in the scene (12 f out, then 12 f in); the
  kernel's side does not bring its elements in as at `establish`.
- `zig build test` prints "failed command" for each scripted scene: that
  is the run echoing its stderr (the Vulkan headless warning), not a
  failure; the summary line is the verdict (none printed when it passes).