summaryrefslogtreecommitdiff
path: root/design/README.md
blob: 8624017d097a43c7a0917cf2c7b12d13faa97f94 (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
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
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
# canim: the design language

This is the catalogue. Everything that can appear in a canim frame is a
**block** with a name, specified here once; everything larger is a
composition of blocks. The names are the ones the code uses. A gallery
scene that draws every block in every state is the test of this page.

- How blocks move is the [verbs](#6-verbs) below; the reasoning and the
  full timing charts behind them are in [`motion.md`](motion.md).
- The blocks drawn: [`mock/`](mock). [Which mock shows which block](#the-mocks).
- The numbers are tokens in `anim/src/theme.zig`:
  [what to change there](#token-changes).

![the frame, mid-step](mock/10-context-step.png)

## The rules

1. **Lapis page, vellum ink.** 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.** The colour
   of a value's digits is where it points, or that it is a keyword or a
   string. A fill, a frame, a tick beside it is an event. 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, unknown is two dots. Nothing is told
   by hue alone.
4. **Solid vellum is the kernel**, and nothing else.
5. **Panels are acme windows.** A tag, a 2-unit rule, a body. Square
   corners, no shadows, no gradients, no glow.
6. **The whole context, always.** Every register followed as far as it
   points, seventeen instructions round the pc, the source, the stack: in
   the same place in every frame, as pwndbg shows them. A lens (a list, a
   tree, an array) is drawn over that state and never instead of it.
7. **Panes are views of one machine, and the ties are drawn.** A source
   line and its instructions, a register and what it points at, a run of
   bytes and the node drawn from them: each relation has a form, a route
   and a moment.
8. **Low level first.** The bytes change, the tie carries it, the drawing
   reacts. A cause is always on screen before its effect.

## Vocabulary

Six layers. A block is made only of blocks from the layers above it in
this table.

| Layer | Block | Is | Options and states |
| --- | --- | --- | --- |
| 1 atom | [`address`](#address) | hex digits in the ink of where they point | `lead`, `name`, `rwx` |
| | [`value`](#value) | anything that is not an address | by class: digit, number, negative, string, fd, flags, bool, char, unknown |
| | [`arrow`](#arrow) | the sign between two things in a chain | `points`, `holds`, `more` |
| | [`hop`](#arrow) | a `points` arrow and the address it leads to | |
| | [`byte`](#byte) | two hex digits of a dump | `number`, `pointer`, `allocator`, `unread`; `pad` |
| | [`mark`](#mark) | what happened to a thing | `current`, `armed`, `struck`, `held`, `read`, `trail`, `allocated`, `freed`, `fault`, `attention`, `unknown`, `kernel` |
| | [`plaque`](#plaque) | a solid label under the current mark | `gold`, `chip` |
| | [`pin`](#pin) | a register's name at the thing it points to | `row`, `under` |
| | [`bracket`](#bracket) | a span marked at its edge | `quiet`, `tie` |
| | [`tag`](#tag) | a panel's title bar | `focus`; `note` or `legend` |
| 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop |
| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) |
| | [`slot`](#slot) | a word of the stack and its chain | pins |
| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` |
| | [`line`](#line) | a line of source | `current`, `trail` |
| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run |
| | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` |
| 3 panel | [`registers`](#registers) | all seventeen | |
| | [`stack`](#stack) | the words from rsp, and the frames they belong to | 8 or 4 slots |
| | [`backtrace`](#backtrace) | the call chain as rows | only in the `none` split |
| | [`source`](#source) | a window on the file | 14, 8 or 10 lines |
| | [`disasm`](#disasm) | the instructions round the pc | 17 or 11 rows |
| | [`lens`](#lenses) | a drawing of some state, and the bytes it is drawn from | `beside`, `subject` |
| | [`hexdump`](#hexdump) | memory, a `bytes` row a line | |
| | [`nodes`](#nodes) `array` `calls` `heap` `syscalls` `pages` | the drawings a lens can hold | |
| 4 tie | [`thread`](#4-ties) | the current line is these instructions | standing |
| | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin` |
| | [`projection`](#4-ties) | these bytes are that part of the drawing | for a step |
| | [`echo`](#4-ties) | the same mark in two panels at once | for a step |
| 5 frame | [`stage`](#5-the-frame) | the band and the two columns | split `none`, `beside`, `subject` |
| | [`clock`](#clock-and-caption) | where in the recording | |
| | [`caption`](#clock-and-caption) | the narrator | |
| | [`veil`](#clock-and-caption) | page over what a beat does not touch | |
| | [`card`](#clock-and-caption) | a title, the legend: no program running | |
| 6 verb | [`fire` `arm` `strike` `cool` `read` `extend` `link` `project` `travel` `advance`](#6-verbs) | what one block does | |
| | [`cascade` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | |

## 0. Tokens

### Grid

1920 by 1080 units; a 4K master is two pixels a unit, at 60 frames a second.

| Token | Value |
| --- | --- |
| context mono | 20: an advance of 12, rows of 24 |
| panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides |
| between panels | 12 |
| columns | two of 880, at x 64 and 976; the gutter between them, 944 to 976, belongs to the ties |
| strokes | 2: rules, frames, chain arrows, a projection. 3: a link, the thread, a lens's frames. 4: a tick |

### Colour

| | Hex | On page | Use |
| --- | --- | --- | --- |
| page | `0a1030` | | the ground; panel bodies |
| raised | `16245f` | 1.3 | tags, node bodies, the paper under a field's bytes, chips |
| well | `101a48` | | a node's pointer half |
| rule | `3a4a8a` | 2.2 | rules, quiet brackets |
| bright | `fff8e8` | 17.6 | titles, a set flag, the newest frame's name |
| primary | `eee6d2` | 14.9 | numbers, names of code, plain code |
| dim | `9aa6d9` | 7.8 | register names, an allocator's bytes, notes |
| faint | `6a7ab8` | 4.5 | chain arrows, line numbers, a decimal beside its hex |
| ink | `050a24` | | letters on a solid mark |

**Regions: the ink of an address**, as pwndbg colours them. The legend is
the registers' tag, always on screen.

| Points into | Ink | On page | Also told by |
| --- | --- | --- | --- |
| stack | `f2d675` | 13.0 | by far the lightest |
| heap | `86b6ff` | 9.0 | |
| code | `ff8f9a` | 8.5 | its name always follows |
| data, writable | `d59cf5` | 8.8 | |
| writable and executable | its region's | | a 2-unit underline |
| read-only data | primary | 14.9 | |
| a string | `b5e8c8` | 13.6 | its quotes |

Known weakness: heap, data and code have one luminance, so between those
three the ink is hue alone, as it is in pwndbg. A code address has its
name; heap and data have only their digits.

**Marks: the colour of an event.** Solid, and the ember it cools to.

| Role | Solid | Ember |
| --- | --- | --- |
| current | gold `e8c46a` | `4a3d1c`; trail `ae9350`, `746235`, `463b20` |
| write | vermilion `ff6a4a` | `5a2218` |
| read | `6fd6e6` | `1c4652` |
| allocated | `7fdc9a` | `1f4a33` |
| kernel | vellum `eee6d2` | |

**Code**: plain primary; keyword and mnemonic `c0dcff` bold; string and
number `b5e8c8`; comment dim italic. **Pigments** name an object across
views, at most four: ochre `8a5e0c`, teal `17707c`, madder `a03060`,
malachite `1c7450`, violet `6a3fb0`, azurite `2f5fc4`. Never a ground
under region ink.

### Type

| Face | For |
| --- | --- |
| JetBrains Mono NL Medium | all mono under 30 |
| JetBrains Mono NL Regular | mono at 30 and over |
| JetBrains Mono NL Bold | keywords, mnemonics, a struck value, plaques, pins |
| JetBrains Mono NL Italic | comments |
| Go, Go Medium, Go Bold | captions and notes; tags; titles |

NL because the plain family's ligatures turn `->` into a sign that is not
in the source. Medium because thin strokes on a dark ground die first in a
stream. OFL and BSD; `/usr/share/fonts/TTF/`, `/usr/share/fonts/go/`.

| Mono | Advance | For |
| --- | --- | --- |
| **20** | 12 | the context, the dump, a lens beside |
| 25 | 15 | a lens's values; its labels and pins as subject |
| 30 | 18 | the context under the camera at x1.5 |
| 35 | 21 | code inside a caption |
| 45 | 27 | a subject lens's values; a value in flight |
| 60 | 36 | a title card |

Sans: 18 notes and legends, 20 tags, 40 on 54 the caption, 44 and 116 a
card. **Floor: mono 20, sans 18.** At 480p no digit at 20 can be trusted,
so: **nothing the narration depends on is only at 20.** It is also in the
caption at 35, or the camera goes to it.

## 1. Atoms

### address

Lower-case hex, **unbroken**, as long as it is, no `0x`, no leading zeros:
`28b41090`, `7ffe970f17b0`, `1001926`. Its ink is its region.

| Option | Draws |
| --- | --- |
| `lead` n | the first n digits at 60% of the ink toward the page. Used in a column of addresses (disassembly, stack slots, a dump's gutter) with n = the digits every row shares, leaving at least two: the eye reads the part that changes |
| `name` | code only: `name+offset` in primary, 10 units on; the module when there is no symbol: `libc+27781` |
| `rwx` | a 2-unit underline |

States: plain; `struck` (bold, in ink, on solid vermilion 5 wider each
side); `read` (a 2-unit frame, 6 out); `held` (a tick at its left). Data:
a word and the mapping it lies in. Mocks 9 to 11, everywhere.

### value

What is not an address. The tracer classifies; the class decides.

| Class | Because | Shown |
| --- | --- | --- |
| digit | under 10 | `4` |
| small number | 10 to 0xffff | hex, and its decimal after it, faint: `0x21 33` |
| large number | larger, not in a mapping | `0x` and its hex, unbroken, primary |
| small negative | within 4096 of 2^64 | `-1` |
| string | a pointer to printable bytes and a NUL | `"..."` in string ink, C's escapes; cut with `…` and no closing quote, never under six characters |
| file descriptor | a signature or a type says so | the number, and faint what it is open on: `3 "note"` |
| flags | eflags; an argument a signature calls flags | names |
| boolean, character | the debug info types it so | `true`; `0x41 'A'` |
| unknown | never observed | two dots |

A typed value follows its type: an `int` is decimal alone, a pointer an
address alone. Mocks 9 to 11 show digit, small number, string; the rest
are not drawn.

### arrow

30 wide: a 2-unit shaft and a head 8 by 10, faint.

| Kind | Reads | pwndbg |
| --- | --- | --- |
| `points` | which points to | `—▸` |
| `holds` | which holds (what follows is not an address) | `◂—` |
| `more` | and goes on: `points` and three 3-unit dots | |

A **hop** is a `points` arrow and the address after it: the unit a chain
is counted, cut and re-followed in.

### byte

Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth.

| Kind | Ink | Paper |
| --- | --- | --- |
| `number`: a field that is not a pointer | primary | raised, one rect a field |
| `pointer`: a field that is one | the region it points into | raised, one rect a field |
| `allocator`: between allocations | dim | none |
| `unread`: never observed | two 4-unit squares, faint | none |

`pad`: in a little-endian word, the bytes above its highest non-zero byte
are at 45% toward the page: `70 10 b4 28` stands out of `00 00 00 00`,
and is the address `28b41070` read from the right. Marks are per run of
bytes, never per byte: see [`bytes`](#bytes). Mocks 9 to 11.

### mark

What happened, on paper and never in the letters.

| State | In the context (mono 20) | In a lens's cell |
| --- | --- | --- |
| `current` | a gold plaque on the label, gold ember across the row | the same |
| `armed` | a 2-unit vermilion frame, the old value still in it | 3 units |
| `struck` | solid vermilion behind the value; digits bold, in ink | solid fill |
| `held` | a vermilion tick, 4 wide, the row less 6 tall, at the value's left, for three steps | a vermilion bar, 4 high, along the cell's bottom edge |
| `read` | a 2-unit frame in read's colour, no fill | 2 units, 2 out |
| `trail` | a 4-unit bar at the row's left edge: three tones, newest first | |
| `allocated` | | ember block in a solid frame |
| `freed` | | hollow, dashed 12 on 8 off, hatched |
| `fault` | hazard bands round an ink plaque naming it | the same |
| `attention` | a 2-unit bright frame | 3 units; a veil on the rest |
| `unknown` | two dots | two dots |
| `kernel` | the ground is solid vellum | the same |

One gold mark a panel. One step's writes in vermilion at a time. Mocks 9
and 10 show current, struck, held, read, trail, unknown; 1 to 8 the rest.

### plaque

A solid label. `gold`: behind the label of a current row, letters bold in
ink (rip's name, 54 wide; a line number, 50; the pc's marker, 24, with an
ink triangle). `chip`: raised, 32 by 20, behind a set flag, letters bold
and bright. Nothing else is a plaque: a register's name at a target is a
[`pin`](#pin).

### pin

A register's name at the thing it points to: the names, bold, primary, and
a head in the target's region ink that touches the target. It answers "who
points here", and it is a [`link`](#4-ties) at rest.

| Form | Where | Anatomy |
| --- | --- | --- |
| `row` | a row's lane (the stack) | the names, then a head 9 by 12 pointing right at the row's address |
| `under` | under a drawn node | a stub 3 wide rising to the node's bottom edge, head 10 by 10; the first name left of the stub, the others right |

A pin for every register whose value is exactly the row's or node's
address; three names, then a count. No box, no fill: the boxed names of
the last revision read as buttons. Mocks 9 to 11.

### bracket

A span marked at its edge: a stroke down the span and a serif at each end,
toward the span. `quiet`: 2 units, serifs 5 (a node's row in a dump, at
60% of its region's ink; an older call frame, in rule). `tie`: 3 units,
serifs 6 or 7, in the ink of the tie it ends.

### tag

24 high, raised. A 12-unit box 8 in: solid gold where the narration is
(`focus`), a faint 2-unit outline elsewhere. The title, Go Medium 20,
primary under focus and dim otherwise. Ranged right, a `note` (Go 18,
faint) or a `legend` (words in Go Medium 18, each in its ink, 14 apart).

## 2. Rows

Every row is 24 high and one line. None wraps; what does not fit is cut at
its far end and says so.

### chain

`address (points address)* (holds value)?`

- A code address ends a chain with its name. A string ends it in quotes.
- **Depth** is the recording's. **Cut** where the row's `room` ends: a
  string is shortened first, then the chain ends early in `more`. Nothing
  is taken from the middle.
- **Marks** are per hop. If the first is struck the register was written
  and the rest are followed again ([`extend`](#6-verbs)); if a later one,
  memory changed under a pointer that did not, and the tick sits before
  that hop alone.
- No lines to targets. Thirty chains would be a net; a chain is tied to
  its target by ink, by digits, and by the target's pin.

### reg

A name (dim) 12 in; its chain from 72; room to 12 from the edge.

`rip`: gold plaque on the name, ember across, the address in code's ink
and its name. Never struck. Its row carries **flags** at the right end:
eight names on a pitch of 42. Set: upper case on a chip. Clear: lower
case, dim. Changed: a tick. (The value `0x206` is not drawn: the names are
the value.)

### slot

A lane 112 wide for a `row` pin; the chain from 122, beginning with the
slot's own address in stack ink with `lead`; room to 136 from the right
edge, which belongs to the [`call`](#call) spans.

### insn

An instruction, pwndbg's way: what it is, and what its operands are now.

| x | Column | |
| --- | --- | --- |
| 2 | mark | a gold plaque 24 wide (current) or a trail bar 4 wide (ran) |
| 31 | jump lane | a 2-unit line in trail gold from a jump that was taken to the row it landed on, head 7 by 8 |
| 40 | address | code ink, `lead` |
| 134 | line | the source line this run of instructions came from, ranged right in three characters, faint; on the first row of each run only; gold and bold for the current line |
| 180 | mnemonic | keyword, bold |
| 264 | operands | as the disassembler writes them, 24 characters; a jump's or call's target is an `address` in code ink |
| 564 | annotation | 25 characters; cut at its far end |

| State | Draws |
| --- | --- |
| `current` | plaque, ember across; annotation in full ink |
| `ran` | trail bar, newest of three brightest; keeps the annotation of what it did |
| `ahead` | plain; only static annotation (a callee's name) |
| `outside` | past the function's end: a rule above the row, everything faint, the next symbol's name in the annotation column |

**The annotation**, by what the instruction does:

| It | Annotation |
| --- | --- |
| reads memory | a chain from the address it computes: `28b41098 → 28b41070 ◂ 9`. Before the step, where it will look; in the step its first hop is `read` |
| writes memory | the same chain; the value after `holds` is `struck` |
| only sets a register | a small `reg`: `rax 28b41090 ◂ 4` |
| jumps on a condition | `taken` in primary, or `not taken` in dim; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37` |
| calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there |
| returns | `→ 10018b0 main+80` |
| makes a system call | its name and arguments by name, as a call; the kernel's rows hang under it on vellum |

Mocks 9 to 11 show the read, the register-setter, the taken jump and
`outside`. Call, return, write and syscall annotations are not drawn.

### line

The number ranged right in three characters, faint; the text from 64, in
the four code inks; 67 characters, then a faint `…`. `current`: gold
plaque on the number, ember across. `trail`: the bar, for the last three
other lines run.

### bytes

A hexdump row. Its runs come from the types of what the program's
pointers reach.

| x | Column | |
| --- | --- | --- |
| 7 | bracket | `quiet`, on a row that holds a drawn thing; `tie` when a projection ends here |
| 18 | address | region ink, `lead`; at 60% on a row that holds no drawn thing |
| 132 | sixteen `byte`s | on a pitch of 30, 12 more after the eighth |
| 640 | reading | what the runs read as, little-endian: a number ranged right in three characters; a pointer as `points` and its `address`; `NULL` dim; an allocator's run as a note in Go 18, faint |

The reading replaces a hexdump's text column: where bytes are text the
reading is the text, in quotes; where they are a pointer it is the address,
so a little-endian pointer is read without leaving the dump.

Marks are per run: `struck` (the paper solid vermilion, digits bold in
ink), `read` (a 2-unit frame 3 out), `held` (a tick in the gap at the
run's left). A struct wider than a row spans rows, and its bracket spans
them.

### call

One frame of the call chain, in two forms.

- `span`, on the stack: a bracket 14 in from the panel's right edge down
  the slots that are the frame, and the function's name left of it, Go
  Medium 18. `newest`: gold bracket, bright name. Older: rule and dim. A
  frame that runs past the panel's last slot has no bottom serif.
- `row`, in a backtrace panel: `#n` (a gold plaque on the newest), the
  name and offset in primary at 60, file and line in dim at 276.

## 3. Panels

A panel is a tag and rows. Its rows never reorder and none is hidden to
make room.

### registers

Seventeen `reg`s in pwndbg's order: rax rbx rcx rdx rsi rdi rbp rsp, r8
to r15, rip (with the flags). Tag: the region legend. 440 high. Reads the
moment's registers and mappings.

### stack

`slot`s from rsp, low addresses on top: eight; four when the lens is the
subject. `call` spans down its right edge: the backtrace, drawn on the
words that are each frame. rsp and rbp are pins in its lane. Reads the
stack words, and each frame's extent (the frame-pointer chain, or the
unwinder's CFA).

### backtrace

`call` rows, newest on top, four and then a count. A panel of its own only
in the `none` split, where there is room under the stack; in the others
the stack's spans carry it.

### source

A window on the whole file, scrolled by whole lines to keep the current
line in its middle third. Fourteen lines; eight beside a lens (the loop
in hand); ten when the lens is the subject. Tag: the file, and `lines 19
to 26 of 42`.

### disasm

Seventeen `insn`s in address order: the pc's, eight above, eight below.
Eleven (five, the pc, five) when the lens is the subject.

- Rows above the pc are the function's own instructions. Near its start
  there are fewer, and the pc's row sits higher; the window stays full
  from below.
- Past the function's end the rows are `outside`.
- The rows that ran in the last three steps are `ran`, above or below the
  pc: with the jump lane they show how control came here.
- Tag: the function's name.

### lenses

A lens is the band across the top of the stage: **a drawing, and beside
it the pane the drawing is a view of.**

| Lens | Drawing | Is a view of | Mock |
| --- | --- | --- | --- |
| `nodes` | boxes of a value and a pointer, arrows between them | a `hexdump` of the nodes' bytes, right half of the band | 9 to 11; 2 at camera scale |
| `array` | cells, index tags, flights for a swap | a `hexdump` of the array's bytes, an element a run | 7 at camera scale |
| `heap` | the heap to scale: chunks, bins | a `hexdump` of the chunk in hand | 4 at camera scale |
| `calls` | a call tree, results on the shoulder | the `stack` panel: each node is a `call` span. The drawing has the band's whole width | 1 at camera scale |
| `syscalls` | the crossing: vellum, the call decoded | the `registers` that carried it, by `echo`. Whole width | 3 at camera scale |
| `pages` | the far view: pages, system calls over time | the mappings. Whole width | 8 |
| `hexdump` alone | bytes and their text | itself | 5, in its first-pass form |

**What a new lens must provide** to fit the frame:

1. A drawing that fits 856 by 116 (`beside`) and by 212 (`subject`), or
   twice the width where it is a view of the stack or the registers.
2. The pane it is a view of, and for every element the bytes, slot or
   register it is drawn from.
3. A `place` for every element, so ties can land. A 12-unit lane clear at
   the top of the drawing and one at the bottom: **bytes arrive from
   above, pointers from below.**
4. Each mark on its cells: `current`, `armed`, `struck`, `held`, `read`.
5. Its `establish`: how its elements rise from what they are drawn from.

### nodes

Boxes of 116 by 44, 28 apart: six fit the band's half (124 by 72, 22
apart, as subject). The
value's half is raised, the number in mono 25 (45); the pointer's half,
48 wide, is the well, with a 10-unit square the arrow leaves from. Arrows
3 wide in the ink of the region pointed into, head 12 by 10; null is a
dim slash. **Above** each node its address, in its region's ink: the same
digits as its row in the dump. **Under** it, its pins. Marks on a half:
`read` frames it, `held` is the bar along its bottom edge.

### hexdump

`bytes` rows, sixteen a row, a window of the region kept round the rows
the step touches: five beside, nine as subject. Rows in address order; a gap in the
addresses is one row holding `more`'s three dots and the count of rows
left out. Tag (the band's
right half): `its bytes`, the range shown, and the legend of runs: each
field's name in its bytes' ink, `malloc's`, `never read`.

## 4. Ties

The panes are one machine at different levels. A tie says which thing in
one pane a thing in another is.

| Tie | Says | Between | When | Form |
| --- | --- | --- | --- | --- |
| `thread` | this line is these instructions, and the machine is here | the source's current line; every run of its instructions in the disassembly | standing; moves with the current mark | gold, 3 units: a `tie` bracket on the line, one on each run, a line in the left margin (x 54) between them |
| `link` | this register now points at that | the `reg` just struck; the row or node whose address it holds | for the step that set it | 3 units, in the ink of the region pointed into, head on the target; ends in the target's `pin` and leaves it behind |
| `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; the part of the drawing made of them | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket over the node's address; and the mark itself on the run and on the part |
| `echo` | these are one event | the same mark at the same instant in two panels: the annotation's address and the dump's run | for that step | no line |
| ink, digits | these are one thing | an address anywhere and its row, node or name | always | no line |

`call` spans and `pin`s are ties too, the kind that need no line because
they sit on their target.

**Budget.** One `thread`, always. For a step, one `link` and one
`projection`. Never more than three drawn lines in the frame; a second
pointer or a second run in the same step gets `echo` and pins.

**Routes.** A tie runs only in channels, with corners of radius 8 (6 for a
projection):

| Channel | Carries |
| --- | --- |
| the left margin, x 54 | the thread |
| the gutter's left lane, x 950 | a link, coming up from the registers |
| the gutter's right lane, x 962 | a projection, from the dump |
| a lens's bottom lane, 8 above its edge | a link, to the pin under its node |
| a lens's top lane, 4 under its tag | a projection, to the bracket over its node's address |

A link stays below a lens's nodes and a projection above them, and each
has its own lane in the gutter, so the two cannot cross. A tie may cross
a panel's rule; it never crosses a letter, a digit or another tie.

**Order.** A tie arrives before the thing it points to reacts: see
[`link` and `project`](#6-verbs). Mock 9 shows the standing ties; 10 and
11 all four.

## 5. The frame

| Band | y | |
| --- | --- | --- |
| margin | 0 to 48 | page |
| stage | 48 to 888 | 840: the lens band and the two columns |
| clock | 898 to 902 | |
| caption | 912 to 1032 | |
| margin | 1032 to 1080 | page |

No data below 888: a player's controls cover it.

**The program column** (left): source over disassembly: what was written,
what runs. **The state column** (right): registers over stack: what they
act on. **The lens band** (top, both columns): what it means, and the
bytes that mean it. The split is the one thing about the layout a scene
chooses.

| Split | Band | Source | Disassembly | Registers | Stack | Backtrace |
| --- | --- | --- | --- | --- | --- | --- |
| `none` | | 14 lines, 48 to 416 | 17, 428 to 868 | 48 to 488 | 8, 500 to 724 | 4, 736 to 864 |
| `beside` | 152, 48 to 200; dump of 5 | 8 lines, 212 to 436 | 17, 448 to 888 | 212 to 652 | 8, 664 to 888 | in the stack |
| `subject` | 248, 48 to 296; dump of 9 | 10 lines, 308 to 580 | 11, 592 to 888 | 308 to 748 | 4, 760 to 888 | in the stack |

**What gave** for seventeen instructions: a lens, the whole of a function
and seventeen instructions do not fit one column of 840. So the lens left
the program column for a band of its own; the backtrace became spans on
the stack; the flags moved into rip's row; a panel's padding went from 6
to 4; and beside a lens the source shows eight lines. As the subject the
lens takes six rows from the disassembly and four slots from the stack.

| Of the frame | `none` | `beside` | `subject` |
| --- | --- | --- | --- |
| context | 68% | 56% | 48% |
| lens band (drawing and bytes, half each) | | 13% | 21% |
| caption band | 10% | 10% | 10% |

### clock and caption

- **`clock`**: a 2-unit rule the width of the stage at y 900; gold, 4
  high, along it as far as the recording has run; `moment 72 of 95` in
  mono 20, faint, under its right end.
- **`caption`**: one or two lines, Go 40 on 54, ranged left on the
  margin; code in it is mono 35. Hex in it is unbroken too.
- **`veil`**: the page at 50% over the panels a named beat does not
  touch; at 65% under the camera.
- **`card`**: a title or the legend ([mock 6](mock/06-title-legend.png)).
  The only frames with no context.
- **Camera rests**: x1 (the frame), x1.5 (1195 by 560: a column, or the
  band), x2 (896 by 420: sixteen rows), x4 (448 by 210: one chain). It is
  for reading, and always comes back.

## 6. Verbs

Frames at 60 a second. `s` is the frame a strike lands. Curves:
`standard` (0.3, 0, 0.2, 1) for things arriving; `glide` (0.45, 0, 0.55,
1) for things travelling and cooling. Charts: [`motion.md`](motion.md).

| Verb | On | Chart |
| --- | --- | --- |
| `fire` | the current plaque | 0 to 12: it pulses once. Nothing else moves |
| `arm` | a value about to be written | s-12 to s: the `armed` frame, in over 2 f; the old value still in it |
| `strike` | a value written | s to s+6 the fill comes in, linear; the new digits at s+3; s to s+12 its edges go out 3 units (4 in a lens's cell) and back, sine; solid to s+36 |
| `cool` | a struck value | s+36 to s+60, `glide`: in the context to nothing, leaving `held` for three steps (then out over 36 f); in a lens's cell to its bar |
| `read` | a value read | in over 6 f; held to the advance; out over 18 f. No arm, no pulse |
| `extend` | a chain whose first hop was struck | each later hop is followed again, 4 f apart, fading in over 6 f |
| `link` | a `reg` just struck, and its target | s+6: the old pin fades (12 f) and the line draws from the register's row, head first, 24 f (36 f over 400 units), `standard`; the pin lands with the head and settles (12 f); held; at the advance the line draws back into the pin over 18 f |
| `project` | a run read or struck, and its part of the drawing | on the run's mark: the bracket on the row (6 f), the line draws from the bytes to the drawing (18 f, `standard`); only when it arrives does the part react (its own `read`, or `arm` and `strike`); out with the advance, 18 f |
| `travel` | a value or a tag going from one place to another | 30 f to 200 units, 36 f to 400, 48 f beyond; `glide` |
| `advance` | the current marks | last. The thread, the plaques and rip move together: 12 f to an adjacent row, 24 f up to eight rows, `standard`; farther, out and in over 6 f. A taken jump's line draws in the jump lane with it |
| `cascade` | a step | `fire` (12); then its effects a level at a time, 18 f apart: CPU (`reg`s, the pc's annotation), memory (`slot`s, `bytes`), the idea (the drawing, by `project`); each armed, then struck; hold 36 f after the last strike and 12 f a further value, 84 at most; `advance`; rest 24 f |
| `run` | steps that need not be read | 18 f a step, no arm, marks jump; 24 steps at most |
| `sprint` | steps to be got through | 4 f a step: only the current marks and the clock move. Each change of pace ramps at 0.6 of the step before |
| `establish` | a scene's opening | the state column, then the program column, then the band: 60 f and 30 f a panel. A lens's dump first; then each element rises from its row by `project`, 6 f apart in address order, and the lines go, leaving the quiet brackets |
| `scroll` | a `source` or `disasm` window | whole rows, 24 f, `glide`; marks ride with their rows |
| `relayout` | a change of split | 48 f, `glide`; nothing else moves under it |
| `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`; 120 f at most without a change; back |
| `say` | the caption | out 12 f, gap 6 f, in 18 f; it leads what it describes by 60 f, 120 f at a scene's first |

A step is as long as its content: 0.8 s when only the line moves, 1.5 s
for one register, 2.0 s for a register and memory, 2.5 s across three
levels.

## Composition

**What may contain what.**

- The stage holds the band and two columns. A column holds panels. A
  panel holds a tag and rows, or (a lens) a tag and a drawing. A row
  holds atoms. Nothing nests deeper.
- A mark sits on an atom or a row, never on a panel. A panel's only
  states are `focus` and veiled.
- A tie sits over panels, in channels. It joins `place`s that blocks
  publish (`reg`, `slot`, a word, a node, the line, the pc); it never
  reads a panel's layout.
- A panel is `32 + 24 n` high. Panels do not overlap and are 12 apart.

**Adding a block.**

1. Name it: one word, a noun, not in the vocabulary.
2. Compose it from the layers above. If it needs a new atom, add the atom
   first, on its own.
3. Give its states as `mark` states. A new state needs a new form, not a
   new colour.
4. Publish its `place`s.
5. Give its motion in the verbs. A new verb only when no sequence of the
   existing ones says it.
6. Draw it in the gallery in every state, at x1 and at 480 wide.
7. Add its row to the vocabulary and to the mocks table.

**Forbidden.**

- Information carried by hue alone. Every ink has a second sign (a name,
  quotes, a position, a paper) except heap against data, which is
  admitted above.
- A mark under coloured digits, except a strike for its 0.6 s and the
  gold ember of a current row.
- A tie across text, or across another tie. More than three drawn ties.
- Two strikes landing in the same frame. Two writes of one step are 6 f
  apart, in the order they happened.
- An effect before its cause: a drawing changing before its bytes, a
  current mark moving before the hold.
- A space inside a number. A row that wraps. Rows that reorder.
- Anything hidden to make room: a row that cannot hold its chain ends in
  `more`, a panel that cannot hold its rows ends in a count.
- Mono under 20, sans under 18. Lines under 2 units. Dashes finer than 12
  on 8 off.
- Alpha tints (but the veil), gradients, glow, grain, rounded panels.
- Solid vellum for anything but the kernel. Gold for anything but where
  execution is.

## The mocks

`mock/context.py` draws 9 to 11, one function a block under the block's
name; `mock/gen.py` draws 1 to 8. Each has a `-480.png` beside it.

```sh
cd design/mock
python3 context.py && for n in 09-context 10-context-step 11-context-lens; do
    resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done
python3 gen.py        # 1 to 8, then resvg the same way
```

| Mock | Is | Blocks it shows |
| --- | --- | --- |
| [9](mock/09-context.png) | `beside`, at rest: moment 71 of `targets/list`, stopped at `mov rdi, [rdi + 8]` | every panel; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot`, `pin` row; `call` spans; `insn` current, ran, ahead, outside, with the jump lane; `line`; `bytes` with number, pointer, allocator, unread and `pad`; `nodes` with pins under; `thread`; marks current, held, trail |
| [10](mock/10-context-step.png) | the same, mid-step | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection` |
| [11](mock/11-context-lens.png) | `subject` | the band at 248, the drawing a size up, a dump of nine, eleven instructions, four slots |
| [1](mock/01-fib-recursion.png) | first pass | `calls` at camera scale |
| [2](mock/02-list-insert.png) | first pass | `nodes` at camera scale; `allocated` |
| [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` |
| [4](mock/04-malloc-glibc-musl.png) | first pass | `heap`; `freed` |
| [5](mock/05-memory-write.png) | first pass | a byte grid: the old form of `hexdump`; `struck` and `held` in cells |
| [6](mock/06-title-legend.png) | | `card`, the legend |
| [7](mock/07-sort-swap.png) | first pass | `array`; `travel` |
| [8](mock/08-far-view.png) | first pass | `pages` |

Mocks 1 to 8 were drawn as whole frames before the context existed. Each
is now what its lens looks like under the camera; none shows its lens in
the band.

**Specified, not drawn.**

- The `none` split, and the `backtrace` panel with `call` rows.
- `insn` annotations for a call with its arguments, a return, a memory
  write, a system call, `not taken`, a jump out of the window.
- `value` classes other than digit, small number and string.
- `armed`, `fault`, `attention` and the veil in the context.
- A `projection` for a write (vermilion). A `link` to a `slot`.
- A struct wider than one `bytes` row; a gap in a dump; text in a dump.
- `array`, `heap`, `calls`, `syscalls`, `pages` in the band.
- `pin` with a count; `rwx`.
- Every verb: the mocks are stills. `establish`, `link` and `project`
  have no chart from a render yet.

**The data in 9 to 11** is the recording's: registers, chains, stack, the
instructions and their lines. The frames' extents are read off the
frame-pointer chain. The dump's node bytes are what the chains and the
program say the heap holds; its allocator rows are glibc's layout, with
the word nothing reads drawn as never read. A recording made under ptrace
has seen neither.

**At 480 wide** no digit of the context reads. What is left: the layout,
the gold rows and the thread, the strike on `rdi` and its link into the
band, yellow and blue as texture, the caption whole. Through x264 at 720p
(CRF 28) mock 10's dump, its faint padding bytes, its dots and the chains
still read.

## What this asks of the renderer

1. **Faces.** JetBrains Mono NL in four and Go in three; `theme.font.mono`
   is still Go Mono.
2. **Places.** `ties.Place` has register, word, node, source and pc. The
   thread needs every run of the current line's instructions, not the pc
   alone; a projection needs a run of bytes in the dump and a *part* of a
   node (its value, its pointer half); a link needs the pin's place.
3. **From the recording**:
   - the line of each instruction in the window, for the `line` column
     and the thread;
   - which instructions ran between two stops, for `ran` rows when
     stepping by line (or a recording by instruction);
   - each frame's extent on the stack, for `call` spans;
   - the bytes of a lens's region at each stop, so that allocator rows
     are read and not guessed; without it they are `unread`, honestly;
   - a callee's prototype, for the number of arguments under a call.
4. **Runs.** Mock 10 is 351 runs of text, 174 rects and 63 paths. An
   address is one run now (two with `lead`).
5. A camera rest at 1.5, with text shaped for mono 30 there.
6. Still open from the first pass: dashed strokes from `sk.draw`.

## Token changes

For `anim/src/theme.zig` as it stood when this was written. "Was" is what
is in the file.

| Token | Was | Is |
| --- | --- | --- |
| `font.mono`, `mono_bold`, `mono_italic` | Go Mono | JetBrains Mono NL Regular, Bold, Italic |
| `font.mono_medium` | | `JetBrainsMonoNL-Medium.ttf`: all mono under 30 |
| `metric.context.pad` | 6 | 4 |
| `metric.context.group_gap` | 6 | removed: hex is unbroken |
| `metric.context.lead_alpha` | | 0.6: the shared digits of a column of addresses |
| `metric.context.pad_alpha` | | 0.45: a word's padding bytes in a dump |
| `layout.registers` | 18 rows | 17: the flags are in rip's row |
| `layout.stack` | 8 | 8; 4 in `subject` |
| `layout.backtrace` | 3, always | 4, in `none` only |
| `layout.band` | | y 48, full width: 152 `beside`, 248 `subject` |
| `layout.split.none` | source 14, disasm 17 | the same; registers, stack 8, backtrace 4 beside them |
| `layout.split.beside` | lens 312 in the program column, source 8, disasm 10 | band 152; source 8, disasm 17; registers, stack 8 |
| `layout.split.subject` | lens 432, source 5, disasm 8 | band 248; source 10, disasm 11; registers, stack 4 |
| `layout.dump_rows` | | 5 `beside`, 9 `subject` |
| `metric.insn` | | columns at 2, 31, 40, 134, 180, 264, 564; operands 24 characters, annotation 25 |
| `metric.bytes` | | bracket 7, address 18, bytes from 132 on a pitch of 30 with 12 after the eighth, reading 640 |
| `metric.slot` | | pin lane 10 to 112, chain 122, room to 136 from the right |
| `metric.table.flag` | 60 by 36 | chip 32 by 20, pitch 42, ranged right in rip's row |
| `metric.pin` | | `row`: head 9 by 12, 5 after the names; `under`: stub 3 wide, the mono size and 10 long, head 10 by 10, names 9 either side |
| `metric.bracket` | | `quiet` 2 and 5; `tie` 3 and 6 (thread 7) |
| `metric.plaque` | 40 high, pad 12 | gold only: 54 (rip), 50 (a line number), 24 (the pc) wide, the row high |
| `metric.node` | 180 by 72, pointer 72 | 116 by 44, 28 apart; 124 by 72, 22 apart as subject; pointer half 48; origin 10 |
| `metric.lens.lane` | | 4 under the tag (projections); 8 above the bottom edge (links) |
| `metric.tie.thread_x` | | 54 |
| `metric.tie.lanes` | | 950 (link), 962 (projection) |
| `metric.tie.radius` | | 8; 6 for a projection |
| `stroke.tie` | | thread 3, link 3, projection 2 |
| `color.well` | | `101a48` |
| `Role.pointer` | orchid frame and arrow | removed. `Role.link`: region ink, 3 wide |
| `mark(.write)` held | ember and a 6-unit bar | in the context a tick, 4 wide; in a lens's cell a bar, 4 high |
| `color.veil_alpha` | 0.65 | 0.50 for a beat; 0.65 under the camera |
| `metric.max_rows` | 10 | removed: nothing is hidden |
| `time.link` | draw 0.40, go 0.30 | draw 0.40 (0.60 over 400 units), settle 0.20, back 0.30 |
| `time.project` | | bracket 0.10, draw 0.30, out 0.30 |
| `time.establish_rise` | | 0.10 between a lens's elements |
| `size.mono.value` | 35 | 35 in a caption; a subject lens's values are `flight`, 45 |

Unchanged and already there: the palette, region inks, `time.cascade`,
`strike`, `read`, `unroll`, `run`, `sprint`, `ramp`, the camera's scales.

## Building it

1. Atoms: `address` (unbroken, `lead`), `arrow`, `value`, `mark`, `pin`,
   `bracket`. The gallery starts here.
2. `chain`, then `reg` and `slot`: the state column at rest.
3. `insn` with its columns and annotations; `line`; `thread`.
4. `bytes` and `hexdump`; `nodes` in the band; quiet brackets.
5. `strike`, `cool`, `read`, `extend` at density; the `cascade`.
6. `link` and `pin`; `project`; `echo`.
7. `call` spans; the three splits and `relayout`; the camera at x1.5.
8. The other lenses in the band.

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
```