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
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
|
# canim: the look
How a canim frame is laid out, coloured and set. How it moves is in
[`motion.md`](motion.md). The numbers are tokens in `anim/src/theme.zig`;
the changes this revision asks of them are [listed below](#token-changes).
Eleven frames drawn with these rules are in [`mock/`](mock).
**Revision 2.** The first pass put one idea on screen in a few sparse
panels. The premise now is a debugger's: *show the whole context, always*,
as pwndbg does, and put the scene's idea beside it as a lens on the same
state. Sections marked **(rev 2)** are new or changed; what was withdrawn is
in the table that follows.
The idea, in six rules:
1. **Lapis page, vellum ink.** 0x4200.cafe's own palette: a deep blue page,
cream text, gold for where execution is, vermilion for what just changed.
2. **Ink says what a thing is; paper says what happened to it.** **(rev 2)**
The colour of a value's digits is where it points (stack, heap, code,
data), a keyword, a string. A fill, a frame, a tick or a plaque behind or
beside it is an event: written, read, current. The two never share a
channel.
3. **Every mark has its own form.** Written is filled, read is framed,
changed is ticked, freed is hollow and dashed, unknown is two dots.
4. **Solid vellum is the kernel**, at every scale, and nothing else.
5. **Panels are acme windows.** A tag with a square box, a 2-unit rule, a
body. Square corners, no shadows, no gradients, no glow.
6. **The whole context, always, and the lens beside it.** **(rev 2)** Every
register followed as far as it points, the instructions at the pc, the
stack, the backtrace and the source are in the same place in every frame.
A list, a tree, an array is a lens on that state: never shown instead of
it, and visibly tied to the words it is made of. The machine is set in
JetBrains Mono; the narrator in Go.

## What changed
| | First pass | Revision 2 |
| --- | --- | --- |
| On screen | one to four panels chosen by the scene | the whole context in every frame, and one lens |
| Layouts | `solo`, `duo`, `trio`, `quad`, `trio_hero`, `far`, `crossing` | one frame with three splits; only title cards are anything else |
| Running head, level rail | a band at the top | gone: the rows went to the stage; the frame itself is the rail |
| Mono | Go Mono, 30 for anything read | JetBrains Mono NL, 20 in the context |
| Hard floor | mono 30, sans 28 | mono 20, sans 18; see [what a phone loses](#type) |
| Hue on digits | syntax only | region: where an address points |
| `pointer` role (orchid) | a frame and an arrow for every pointer | gone: a pointer is inked by its region; orchid is now `data` |
| Arrows to targets | always drawn | drawn in a lens, and for the one pointer a step follows |
| Changed a moment ago | ember fill and a bar | in the context, a tick at the value's left; ember and bar in a lens's cells |
| Registers | eight by default | all sixteen, rip, flags, each with its telescope |
| Stack | cards, or a byte grid | a telescope of eight words, and the backtrace under it |
| Source | the lines that fit a panel | the whole file, scrolling to keep the line in view |
| Levels | different layouts, a camera between them | places in one picture; the camera is for reading |
| Camera scales | 1, 2, 4 | 1, 1.5, 2, 4 |
## The frame (rev 2)
1920 by 1080 logical units; a 4K master is two pixels a unit. Master at
2160p60: at this density the extra resolution is not a nicety.
| Band | y | What |
| --- | --- | --- |
| margin | 0 to 48 | page |
| stage | 48 to 888 | the context and the lens: 35 rows of 24 |
| clock | 898 to 902 | a rule the width of the stage; gold along it as far as the recording has run; `moment 72 of 95` under its right end |
| caption | 912 to 1032 | one or two lines of narration |
| margin | 1032 to 1080 | page |
Side margins are 64. Two columns of 880 with 32 between them; panels in a
column are 12 apart. A panel is a tag of 24, 6 of padding, rows of 24, 6 of
padding: 36 + 24 a row.
**The state column** (right, x 976 to 1856) is the same in every frame of
every scene:
| Panel | Rows | Height | y |
| --- | --- | --- | --- |
| registers | 18: sixteen, rip, flags | 468 | 48 to 516 |
| stack | 8 words from rsp | 228 | 528 to 756 |
| backtrace | 3 frames, then a count | 108 | 768 to 876 |
**The program column** (left, x 64 to 944) holds the lens, the source and
the disassembly, top to bottom: the idea, its text, its instructions. It has
three splits, and the split is the only thing about the layout a scene
chooses:
| Split | Lens | Source | Disassembly | When |
| --- | --- | --- | --- | --- |
| no lens | | 21 lines, 540 | 10 rows, 276 | the machine alone |
| lens beside | 312 | 12 lines, 324 | 6 rows, 180 | the default: the machine is the subject ([mock 9](mock/09-context.png)) |
| lens as subject | 432 | 8 lines, 228 | 5 rows, 156 | the idea is the subject ([mock 11](mock/11-context-lens.png)) |
As the subject the lens is also a size up: mono 25 on rows of 30, values at
35. Moving between the last two is a layout change (0.8 s): the source gives
up four lines and the disassembly one row.
Of the frame's area:
| | No lens | Lens beside | Lens as subject |
| --- | --- | --- | --- |
| state column | 35% | 35% | 35% |
| source and disassembly | 35% | 21% | 16% |
| **context in all** | **70%** | **57%** | **51%** |
| **lens** | | **13%** | **18%** |
| caption band | 10% | 10% | 10% |
The lens never has more than a fifth of the frame, and that is the cost of
the premise. When an idea needs to be large it gets the camera (below), for
a few seconds, and the frame comes back.
**Place is meaning.** Down the program column abstraction falls: idea, C,
instructions. The state column is what they act on. The lens is top left,
where the eye starts, and next to the registers that point into it. The
kernel is still vellum and still underneath: its rows hang under the
`syscall` instruction in the disassembly, and a crossing is a lens.
**No data below y = 888.** The player's controls and subtitles cover the
caption band.
## Colour
| | Hex | On page | On `raised` | Use |
| --- | --- | --- | --- | --- |
| page | `0a1030` | | | the ground; panel bodies too |
| raised | `16245f` | 1.3 | | tags, cells, plaques, node bodies |
| rule | `3a4a8a` | 2.2 | 1.7 | rules, hollow cells, wedges; fill of bookkeeping |
| text, bright | `fff8e8` | 17.6 | 13.7 | titles, a value in flight, a landing frame |
| text, primary | `eee6d2` | 14.9 | 11.6 | numbers that are not addresses, names of code, plain code |
| text, dim | `9aa6d9` | 7.8 | 6.1 | register names, notes |
| text, faint | `6a7ab8` | 4.5 | 3.5 | arrows in a chain, offsets, line numbers, a decimal beside its hex |
| ink | `050a24` | | | letters on a solid accent |
### Regions: the ink of an address (rev 2)
As pwndbg colours them, and as its users read them without thinking:
| Points into | Ink | On page | Also |
| --- | --- | --- | --- |
| stack | yellow `f2d675` | 13.0 | |
| heap | blue `86b6ff` | 9.0 | |
| code | red `ff8f9a` | 8.5 | always followed by its name |
| data, writable | purple `d59cf5` | 8.8 | |
| writable and executable | its region's ink | | a 2-unit underline |
| read-only data | primary `eee6d2` | 14.9 | plain, as pwndbg leaves it |
| nothing: not a pointer | primary | | see [what a value shows as](#what-a-value-shows-as-rev-2) |
| a string | `b5e8c8` | 13.6 | in quotes |
The legend is always on screen, as pwndbg's is: the six words, each in its
ink, in the registers' tag.
These are tints, lighter and less saturated than the marks, so a frame of
them is quiet. Every one reads at 4.6 or better on every ground it can sit
on, the embers included.
### Marks: what happened
| Role | Solid | Ember | In the context (mono 20) | In a lens's cell |
| --- | --- | --- | --- | --- |
| current | gold `e8c46a` | `4a3d1c` | solid plaque on the label, ember across the row | the same |
| write | vermilion `ff6a4a` | `5a2218` | solid behind the value, digits bold in ink | solid fill, pulse |
| changed (held) | vermilion | | a tick, 4 wide, at the value's left, for three steps | ember and a 6-unit bar |
| read | `6fd6e6` | `1c4652` | a 2-unit frame, no fill | a 3-unit frame, ember inside |
| allocated | `7fdc9a` | `1f4a33` | | ember block in a solid frame |
| freed | no colour | | | hollow, dashed, hatched |
| fault | vermilion | | hazard bands round an ink plaque naming it | the same |
| attention, landing | bright | | a 2-unit bright frame | a 3-unit bright frame; a veil on the rest |
| link, flow | the target's region ink; primary | | a 3-unit arrow, for one step | a 3-unit arrow |
| unknown | faint | | two 6-unit squares | the same |
| kernel | vellum `eee6d2` | | the ground | the ground |
**How the two never fight.**
- A region is letters; a mark is never letters. During a strike the digits
are bold ink on solid vermilion: for 0.6 s "written now" is all that value
says. As the fill goes the digits come back in their region's ink.
- A held change does not sit under the digits it marks. It is a tick in the
gap to their left, the `*` pwndbg puts before a changed register. The
underline is left free to mean writable-and-executable.
- A read is a frame, outside the digits, and brings no fill.
- The current row is the one place region ink sits on a coloured ground:
code red on the gold ember, at 4.9.
- In a lens's cells (mono 25 and up, a box of their own) the ember stays:
there is room for it and the digits on it are measured (4.6 to 8.7).
**The `pointer` role is gone.** Being a pointer is not a colour any more:
every address is inked by where it points. Its orchid is `data`. Its forms
survive as the *link*: an arrow, and a frame round the bytes that make one
pointer, in the ink of the region pointed into, drawn in two places only:
inside a lens (a list's arrows), and for the single pointer a step follows
or rewrites.
**Pigments** still say *which object*, across views: ochre `8a5e0c`, teal
`17707c`, madder `a03060`, malachite `1c7450`, violet `6a3fb0`, azurite
`2f5fc4`; at most four, each with its name. In the context they are a
lens's way of naming an object and its rows, and never a ground under
region ink.
**Code** (pardes's four classes): plain `eee6d2`; keyword `c0dcff`, bold;
string and number `b5e8c8` (was `c8f0d8`: too close to plain at 20);
comment `9aa6d9`, italic. In the disassembly a mnemonic is a keyword.
**Colour vision.** Blue ground against gold and vermilion is the axis every
common deficiency keeps. Region ink *is* hue alone, as it is in pwndbg, and
heap, data and code have the same luminance; a deuteranope cannot tell heap
from data by colour. What is left for them: code always has its name after
it, a string its quotes, stack is far lighter than the rest, and an
address's own top digits say where it is. That is weaker than everything
else here and it is the price of the convention.
**After 4:2:0.** Mock 10 through x264: at 1080p (CRF 30) and at 720p
(CRF 28) every chain reads and every region keeps its colour. At 480p the
digits can no longer be trusted (`0` and `8` fall together); ticks, the
strike, the region colours, the gold rows and the caption survive.
## Type
**(rev 2)** One mono family for code, registers, hex and memory, so the
whole context sits on one grid; Go stays for everything said about it.
| Face | File | For |
| --- | --- | --- |
| JetBrains Mono NL Medium | `JetBrainsMonoNL-Medium.ttf` | everything mono at 20 and 25 |
| JetBrains Mono NL Regular | `JetBrainsMonoNL-Regular.ttf` | mono at 30 and larger |
| JetBrains Mono NL Bold | `JetBrainsMonoNL-Bold.ttf` | keywords, mnemonics, a struck value, plaque letters |
| JetBrains Mono NL Italic | `JetBrainsMonoNL-Italic.ttf` | comments |
| Go | `Go-Regular.ttf` | captions, notes |
| Go Medium | `Go-Medium.ttf` | tags, labels |
| Go Bold | `Go-Bold.ttf` | titles |
JetBrains Mono: OFL 1.1, `/usr/share/fonts/TTF/` (`ttf-jetbrains-mono`
2.304). Go: BSD-3-Clause, `/usr/share/fonts/go/`.
- **NL, not the plain family.** The plain one has ligatures: `->`, `!=` and
`>=` become single signs that are not in the source. NL is the same
design without them. (If the renderer can turn `calt` off, either will do.)
- **Medium at 20 and 25.** Light letters on a dark ground lose their thin
strokes first in a stream; at 720p Medium keeps its weight and Regular
does not.
- **Why not Go Mono too**: one family means a hex digit, a keyword and a
register name are the same width and weight, and the user asked for
JetBrains Mono where code is. Why Go stays: captions are the layer a
phone still reads, Go was the most legible of eight faces at 480 wide,
and the change of voice between machine and narrator is worth a second
family.
Its advance is 0.6 em, as Go Mono's was, so the rule holds: **mono sizes are
multiples of 5** and a character is a whole number of units, at 1080p and
at 4K.
| Mono | Advance | Rows of | For |
| --- | --- | --- | --- |
| **20** | 12 | 24 | the context: every panel of it |
| 25 | 15 | 30 | a lens that is the subject; a lens's values |
| 30 | 18 | 36 or 48 | what the camera at x1.5 makes of the context |
| 35 | 21 | | values in a lens that is the subject; code inside a caption |
| 45 | 27 | | a value in flight |
| 60 | 36 | | a title card's numbers |
| Sans | For |
| --- | --- |
| 18 | notes in a tag, a note at the end of a row |
| 20 | a panel's title |
| 24 | a note beside a lens |
| 40 on 54 | the caption |
| 44, 116 on 128 | a title card |
**The hard floor is mono 20 and sans 18.** Nothing is smaller, anywhere.
**What a phone loses.** Said plainly: at mono 20 the context is a picture
for a desk. On a phone held sideways an x-height is 0.8 mm, and at 480p no
hex digit can be trusted. A phone viewer keeps the caption (40), the
layout, the gold rows, the strike and its link, the region colours as
colour, a lens that is the subject, and whatever the camera brings to 30.
So one rule protects them: **nothing the narration depends on is only at
20.** The value it names is also in the caption, in mono 35, or the camera
goes to it.
**Hex.**
- Lower case, in groups of four from the right, half a character apart.
- An address is as long as it is: `28b4 1090`, `7ffe 970f 17b0`,
`100 1926`. No leading zeros, no `0x`: its ink says it is an address.
- A number that is not an address has `0x` once it has two digits, so that
`10` is never sixteen: see below.
- Decimal for what the source calls a number; both where a register may be
either.
## The context (rev 2)
Five panels, in the state they are in when `ztrace show FILE N` prints them.
Mocks [9](mock/09-context.png) and [10](mock/10-context-step.png) are
moments 71 and 72 of a recording of `targets/list`.
### Panel
A tag one row high on `raised`: a 12-unit box 8 in (gold where the narration
is, a faint hollow elsewhere); the title, Go Medium 20; a note, Go 18,
ranged right. A 2-unit rule round the body; the body is the page.
### Registers
Eighteen rows, in pwndbg's order: rax rbx rcx rdx rsi rdi rbp rsp, r8 to
r15, rip, flags. A name (dim) in a column of five characters; its value at
72 from the panel's edge; then its chain.
- rip: gold plaque on the name, gold ember across the row, the address in
code's ink and its name after it: `100 1926 reverse+22`. rip is never
"written".
- flags: the value, then the eight names. A set flag is upper case, bold,
bright, on a `raised` chip; a clear one lower case and faint
(pwndbg's `[ cf PF af zf sf IF df of ]`, without the brackets). One that
changed has the tick.
- Rows never reorder and none is hidden.
### The telescope
One row a chain, read left to right: *this, which points to that, which
holds this.*
- **An address**: its digits in its region's ink.
- **Points to**: an arrow 30 wide, a 2-unit shaft and a head 8 by 10, faint.
pwndbg's `—▸`.
- **Holds**: the same arrow pointing back. pwndbg's `◂—`. What follows it is
not an address.
- **The end**: a number, a string, or nothing after a code address but its
name, 10 units on, in primary: `100 18b0 main+80`. Where there is no
symbol, the module: `libc+27781`.
- **A string**: in quotes, in string ink, with C's escapes. Cut to the room
left with `…` and no closing quote; never to fewer than six characters.
- **Depth** is the recording's (three by default: four addresses from a
register, five in a stack row counting the row's own). A chain that was
still a pointer where the recording stopped ends in an arrow and three
dots. So does one that runs out of row: the string is cut first, then the
chain ends early. Nothing is taken from the middle.
- **A chain that changes.** Only the link that changed is struck. If it is
the first, the register was written, and the links after it are followed
again one at a time, 4 frames apart: the telescope extends. If it is a
later one, memory changed under a pointer that did not, and the tick sits
before that link alone.
- **Its target, when the target is on screen.** No standing lines: thirty
chains would be a net. Four things tie them instead:
1. the ink: blue is in the heap, yellow in the stack panel below;
2. the digits: the same address is the row's own in the stack, the node's
in the lens;
3. plaques: a register's name sits *at what it points to*, in the stack's
lane (`rsp`, `rbp`) and on a lens's nodes and rows (`rdi`, `rax`):
"who points here", up to three, then a count;
4. one link, for the step in hand: from the row of the register just
struck, through the gutter, to the row or node it now holds, in the
region's ink, 3 units wide. It draws after the strike and goes with
the advance. ([Mock 10](mock/10-context-step.png).)
### What a value shows as (rev 2)
The tracer classifies; this is how each class is set.
| It is | Because | Shown |
| --- | --- | --- |
| a pointer | it lies in a mapping | its address in the region's ink, and its chain |
| a code address | the mapping is executable | address, then `name+offset` in primary |
| a string | a pointer to printable bytes and a NUL | `"..."` in string ink |
| a digit | not a pointer, under 10 | `4` |
| a small number | not a pointer, 10 to 0xffff | `0x21` and its decimal after it, faint: `0x21 33` |
| a large number | not a pointer, larger | hex in fours with `0x`, primary |
| a small negative | within 4096 of 2^64 | `-1` |
| a file descriptor | a syscall's signature, or a variable's name and type, says so | the number, and faint what it was opened on: `3 "note"` |
| flags | eflags; an argument a signature calls flags | names: `O_RDONLY|O_CLOEXEC`; for eflags all eight, as above |
| a boolean | the debug info types it so | `true`, `false` |
| a character | the debug info types it so; a byte in a text view | its hex and the character: `0x41 'A'` |
| unknown | never observed | two dots |
Decimal goes beside hex when a value is a small number and nothing says
which it is (registers, stack words, heap words). When the type is known
the type decides: an `int` is decimal alone, a pointer hex alone. In a
system call's rows a size or a count is decimal first.
### Disassembly
A row an instruction: the address in code's ink, its offset in the function
faint (`+22`, to match rip and the backtrace), the mnemonic as a keyword,
the operands plain, a jump's target in code's ink. The function's name is
the tag's note.
- The pc's row: gold plaque with a marker, gold ember across.
- Two rows above it are the instructions just run, with trail bars; the pc
is never the top row.
- **Under the pc, a row that says what its operand is**: `rdi + 8 =` and a
telescope from the address computed. Before the step it is where to look;
during it, its first link is framed as read or struck as written.
- A `syscall`: under it, on vellum, the call decoded, a row an argument, by
the argument's own name (`fd`, `buf`, `count`).
### Stack
Eight words from rsp, low addresses on top. A lane for the plaques of the
registers that point at each row; the row's own address in stack's ink; its
chain. Where the frame pointer says so, a faint note at the row's end:
`return address`, `main's saved rbp`.
### Backtrace
A row a frame, newest on top: `#0` on a gold plaque, the name and offset,
the file and line. Three rows; a deeper stack ends in a count.
### Source
The whole file, in mono 20 on rows of 24, a window on it kept so that the
current line is in its middle third. It scrolls by whole lines (0.4 s) and
never cuts. Line numbers faint, ranged right in three characters. A line
longer than the 67 characters the panel holds is cut with a faint `…`.
- Current line: gold plaque on the number, gold ember across.
- Trail: the last three other lines run keep a 4-unit bar at the left edge,
gold cooling.
## The lens (rev 2)
Everything the first pass drew that is not one of the five panels is a
lens: a list's nodes and arrows, a call tree, an array's cells, the heap to
scale, a string's bytes, a system call's crossing, the page map and the
timeline of calls. One at a time, in the panel at the top of the program
column.
- It is drawn on the context's module (mono 20, rows of 24, values at 25)
and one size up when it is the subject. The first pass's sizes (cells of
48, mono 30) are what it comes to under the camera at x1.5.
- **It carries the words it is made of.** A list's lens is its nodes and,
under them, the heap words that are those nodes, an address, a value and
a `next` a row. A tree's nodes carry the frame they are; an array's cells
sit over their bytes.
- **It is tied to the context** the way a chain is tied to its target: the
same address under a node as in `rdi`'s row; the registers' plaques on
the node and on its row; the same mark at the same instant in the lens
and in the words (read, struck, landed); and the step's one link.
- What happens to a node happens to its words first: the words are the
cause (`motion.md`, the cascade).
- **With nothing to draw**, the panel still holds what a recording has
beyond the five: the live heap, a chunk a row (address, size, its first
words as a telescope), or the named variables, a row each (name, type,
value by its class). They are the plainest lenses, and the default one
whenever a recording has them.
The forms themselves are as the first pass drew them, in mocks 1 to 8:
| Lens | Mock | Its words |
| --- | --- | --- |
| list: nodes `[value | next]`, arrows in heap's ink, null a slash | [2](mock/02-list-insert.png), [9](mock/09-context.png) | the heap words, a node a row |
| call tree: circles, results on the shoulder | [1](mock/01-fib-recursion.png) | each node's frame in the stack telescope |
| array: cells, index tags, flights for a swap | [7](mock/07-sort-swap.png) | the bytes, where the array lives |
| heap to scale: chunks, bins, masks, a wedge into one chunk | [4](mock/04-malloc-glibc-musl.png) | the chunk's words |
| bytes: a grid of 8 with its text | [5](mock/05-memory-write.png) | themselves |
| a system call: vellum, the call decoded, the bytes crossing | [3](mock/03-syscall-write.png) | the registers that carried it |
| the far view: pages, system calls over time | [8](mock/08-far-view.png) | the mappings |
Those eight frames were drawn as whole frames; each is now what its lens
looks like with the camera on it. They have been redrawn in the new face
and with pointers in their regions' inks, and are otherwise the first
pass's.
A title card and the legend ([mock 6](mock/06-title-legend.png)) are the
only frames with no context: no program is running in them.
## Directing the eye in a full picture (rev 2)
Everything is on screen, so nothing is found by being alone. In order of
how often they are used:
1. **The cascade.** A step's effects arrive one place at a time, in the
order they were caused, 0.30 s apart (`motion.md`). Onset is the pointer.
2. **The gold thread.** One current mark a panel: the source line, the pc,
rip, frame #0, and the lens's current node. They move last, together.
3. **The strike**, the one solid warm thing in a frame of tints.
4. **The focus box.** The tag's box is gold in the panel the narration is
in, and only there. It is the old level rail, moved onto the frame.
5. **The step's link**: one arrow, for one step, from a cause to its effect
across panels.
6. **A veil** on the panels a named step does not touch (page at 50%, 0.3 s
in and out). For a beat, not a scene.
7. **The camera**, to read:
| Scale | Mono 20 becomes | Frames | For |
| --- | --- | --- | --- |
| x1.5 | 30 | 1195 by 560 | a column, or the lens with the registers' names and first links |
| x2 | 40 | 896 by 420 | up to sixteen rows of one panel |
| x4 | 80 | 448 by 210 | one chain, one node and its words |
The rules of `motion.md` hold: the target is framed first, everything else
fades, the move is 1.2 s, nothing else moves under it, and two seconds
without a change is the limit. The camera comes back to the whole frame
every time. It is a way of reading the context, not a place to be instead
of it.
**Levels** are no longer layouts. Going from a line of C to the register it
writes to the bytes it stores is the cascade crossing the frame: source
line (fire), disassembly note (where), registers (strike), stack or lens
words (strike), lens (the idea changes). The viewer is never moved; their
eye is.
## Motion
[`motion.md`](motion.md) is the direction. What density changes in it:
- A strike in the context: the arm is a 2-unit frame; the pulse goes out 3
units, not 4; the fill cools to nothing and leaves the tick.
- A telescope extends link by link, 4 frames apart, each fading in over 6.
- A register's plaque slides to the row or node the register now points at
(0.4 s, `glide`), after the register is struck.
- The step's link draws in 0.4 s (`standard`) after the strike, and fades
over 0.3 s as the marks advance.
- The pace counter and the progress line are on the clock rule over the
caption, not in a head.
- Camera frames are those in the table above; x1.5 is the usual one.
## Legibility rules (rev 2)
- Mono 20 and sans 18 are the floor. Medium weight under mono 30.
- Whatever the narration names is also at 35 in the caption or at 30 under
the camera.
- Lines: 2 units is the thinnest (rules, a read's frame, an arrow's shaft
in a chain); 3 for a link and a lens's frames; 4 for a tick.
- A region is told by ink; a mark never is. No mark sits under coloured
digits except a strike, for its 0.6 s, and the gold ember of a current row.
- No alpha tints but the veil, no gradients, no glow, no grain.
- Dashes 12 on, 8 off; the hatch 5 on a pitch of 20. Nothing finer.
- Solid vellum is the kernel and nothing else.
- One gold mark a panel. One step's writes in vermilion at a time.
- Nothing is hidden to make room. A row that cannot hold its chain ends in
dots at its far end; a panel that cannot hold its rows ends in a count.
## The mocks
`mock/gen.py` draws 1 to 8 and `mock/context.py` 9 to 11; resvg renders
them; each has a `-480.png` beside it.
| | Shows | After looking |
| --- | --- | --- |
| [9](mock/09-context.png) | **(rev 2)** the default frame at rest: moment 71, stopped in `reverse` at `mov rdi, [rdi + 8]` | the first draft's lens had plaques over its table's heads and a note over a column: nodes, addresses, plaques and words each got a row of their own |
| [10](mock/10-context-step.png) | **(rev 2)** the same, mid-step: `rdi` struck, its chain re-followed, the word it read framed in three places, its plaque moved, the link to its node | the link ran through the register's name like a strike-through, and ended in empty space: it now leaves from the panel's edge and lands on the row, which is framed whole. Chain arrows went from 24 to 30 wide: at 24 they touched the digits |
| [11](mock/11-context-lens.png) | **(rev 2)** the lens as subject: 432 tall, a size up | a note collided with a column head at the larger size and was dropped |
| [1](mock/01-fib-recursion.png) to [8](mock/08-far-view.png) | the first pass's frames: now the lenses, and the title card | redrawn in JetBrains Mono, with pointers in region ink and the legend remade: what happened in one row, what a thing is in the other |
The data in 9 to 11 is the recording's: every register and chain, the
instructions, the stack. The backtrace is read off the stack's return
addresses. The lens's heap words are what the chains and the program say
the heap holds; the recording, made under ptrace, has no allocations in it.
**At 480 wide** ([9](mock/09-context-480.png),
[10](mock/10-context-step-480.png)): no digit of the context can be read.
What is left is the two columns, four gold rows, the strike on `rdi` and
the link from it into the lens, yellow and blue as texture, and the caption
whole. In [11](mock/11-context-lens-480.png) the list's values can be read
as well. That is the phone's share, and the reason for the rule about the
caption.
## What this asks of the renderer (rev 2)
1. **Faces.** JetBrains Mono NL in four (Regular, Medium, Bold, Italic) and
Go in three. `sk.Face` has no medium mono today.
2. **A camera rest at 1.5**, with text shaped for its size there (mono 30,
an advance of 18), as it is at 1, 2 and 4.
3. **Many runs.** A context frame is about 700 separately inked runs of
text: every group of four hex digits is its own. Unsure whether `f.text`
at that count is comfortable in an export, or wants batching.
4. **From the recording**, which I have not checked beyond `ztrace show`:
- the instructions *before* the pc (from earlier moments, or decoded
backwards), for the two trail rows;
- an instruction's memory operand as data (base, index, displacement),
so the note under the pc can compute and follow its address;
- a backtrace: `show` names return addresses in the stack but prints no
frames for a ptrace recording;
- a lens's words when nothing recorded an allocation (`-w`, or the
agent).
5. Underlines, ticks and frames are rects; the scrolling source wants
`f.clip`; chain arrows are 8-pixel polygons and rely on the supersampling.
6. Still open from the first pass: dashed strokes from `sk.draw`.
## Token changes
For `anim/src/theme.zig`. Nothing in `time` changes but the two additions
at the end.
| Token | Was | Is |
| --- | --- | --- |
| `font.mono` | Go Mono, `Go-Mono.ttf` | JetBrains Mono NL, `JetBrainsMonoNL-Regular.ttf` |
| `font.mono_medium` | | `JetBrainsMonoNL-Medium.ttf`: mono under 30 |
| `font.mono_bold` | `Go-Mono-Bold.ttf` | `JetBrainsMonoNL-Bold.ttf` |
| `font.mono_italic` | `Go-Mono-Italic.ttf` | `JetBrainsMonoNL-Italic.ttf` |
| `size.mono.context` | | 20 |
| `size.mono.small` | 25: gutters | 25: a lens as subject, a lens's values |
| `size.mono.data` | 30: anything read | 30: the context under the camera |
| `size.sans.micro` | 22 | 18 |
| `size.sans.tag` | | 20 |
| `size.sans.label` | 28 | 28, in title cards only |
| `size.min_read` | 28 | 20 |
| `size.min_any` | 22 | 18 |
| `canvas.head`, `head_baseline`, `head_rule_y` | 48 to 96, 81, 104 | removed |
| `canvas.stage` | y 120, h 768 | y 48, h 840 |
| `canvas.clock_y` | | 900 |
| `canvas.row_gap` | 24 | 12 |
| `layout.solo`, `duo`, `duo_even`, `trio`, `trio_stack`, `trio_hero`, `quad`, `far`, `crossing` | | removed |
| `layout.program`, `layout.state` | | `cols(0, 6, 0, 840)`, `cols(6, 6, 0, 840)` |
| `layout.split.none` | | source 21 rows, disassembly 10 |
| `layout.split.beside` | | lens 312, source 12, disassembly 6 |
| `layout.split.subject` | | lens 432, source 8, disassembly 5 |
| `layout.state_rows` | | registers 18, stack 8, backtrace 3 |
| `color.region.stack` | | `f2d675` |
| `color.region.heap` | | `86b6ff` |
| `color.region.code` | | `ff8f9a` |
| `color.region.data` | | `d59cf5` |
| `color.string` | | `b5e8c8` |
| `color.code.literal` | `c8f0d8` | `b5e8c8` |
| `color.veil_alpha` | 0.65 | 0.50 for a beat's veil; 0.65 under the camera |
| `Role.pointer`, `Form.arrow` | orchid frame and arrow | removed; `Role.link`: region ink, `Form.thin_arrow` 3 wide |
| `mark(.write)` held, in the context | ember and bar | `metric.context.tick` |
| `metric.context.row` | | 24 |
| `metric.context.tag` | | 24 |
| `metric.context.pad` | | 6 above and below the rows, 12 at the sides (8 in the stack) |
| `metric.context.name_w` | | 60: five characters |
| `metric.context.chain_x` | | 72 |
| `metric.context.arrow_w` | | 30, for both arrows of a chain |
| `metric.context.group_gap` | | half an advance: 6 at mono 20 |
| `metric.context.tick` | | 4 wide, the row less 6 tall |
| `metric.context.plaque_h` | | the row less 4 |
| `metric.context.read_frame` | | 2 |
| `metric.context.pulse_outset` | | 3 |
| `metric.context.string_min` | | 6 characters |
| `metric.context.source_chars` | | 67 |
| `metric.lens.node` | 180 by 72 | 116 by 44 beside, 124 by 64 as subject |
| `metric.max_rows` | 10 | removed: nothing is hidden |
| `camera.scales` | 1, 2, 4 | 1, 1.5, 2, 4 |
| `time.unroll` | | 4 f (0.0667) between links re-followed |
| `time.link` | | 0.40 to draw, 0.30 to go |
## Implementation order (rev 2)
1. The faces and `size.mono.context`; the one-row panel.
2. **The telescope**: an address in its region's ink, the two arrows, the
end by class, the cut at the row's end. It is three of the five panels.
3. Registers, stack, backtrace: the state column, at rest.
4. Source (scrolling) and disassembly with its note: the program column.
5. Marks at density: strike, tick, read frame, the telescope extending.
The cascade of `motion.md` over these five panels.
6. Plaques at what registers point to, in the stack and then in a lens.
7. The lens panel and its three splits; the list first, with its words.
8. The step's link; the veil; the camera at x1.5.
9. The other lenses, from what exists: tree, array, heap, bytes, crossing.
Shader effects worth having: still none.
Export:
```sh
canim --export - --size 3840x2160 --fps 60 --frames N |
ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - \
-c:v libx264 -crf 14 -preset slow -pix_fmt yuv420p \
-colorspace bt709 -color_primaries bt709 -color_trc bt709 -color_range tv out.mp4
```
|