summaryrefslogtreecommitdiff
path: root/design/README.md
blob: 826973eda53fd4e2e2e7af1e0c3e118710976359 (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
# canim: the look

How a canim frame is laid out, coloured, set and moved. The numbers are in
[`src/anim/theme.zig`](../src/anim/theme.zig) (`zig test` checks the contrast
figures quoted here); eight frames drawn with them are in [`mock/`](mock).

The idea, in six rules:

1. **Lapis page, vellum ink.** The palette is 0x4200.cafe's own (pardes's
   `lapis` theme), re-cut for video: a deep blue page, cream text, gold for
   where execution is, vermilion for what just changed.
2. **Paper, not letters.** Meaning is carried by what is behind and around a
   value (a fill, a frame, an arrow), never by the colour of its digits. Hue
   on letters is syntax, and quiet.
3. **Every mark has its own form.** Written is filled, read is framed, a
   pointer has an arrow, freed is hollow and dashed, unknown is two dots. No
   two roles are told apart by hue alone.
4. **Solid vellum is the kernel.** The other side of a system call is the
   page's negative: a cream ground with blue ink, at every scale, from the
   slab under a crossing to a 12-unit block on a timeline.
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. **Mono is the machine, sans is the narrator.** Anything recorded from the
   program is Go Mono; anything said about it is Go.

![fib](mock/01-fib-recursion.png)

## Canvas

1920 by 1080 logical units; a 4K master is the same layout at two pixels a
unit. Master at 2160p60 even for a 1080p audience: YouTube gives a 4K upload
a better 1080p stream.

| Band | y | What |
| --- | --- | --- |
| margin | 0 to 48 | page only |
| running head | 48 to 96, rule at 104 | title; where the program is; level rail |
| stage | 120 to 888 | panels |
| caption | 912 to 1032 | one or two lines of narration |
| margin | 1032 to 1080 | page only |

Side margins are 64. Between them, 12 columns of 120 with gutters of 32.
Panels stacked in a column are 24 apart and their heights are multiples of
24. The module is 12: a byte cell is 48, a memory row 60, a tag, a code line
and a register row 48.

**No data below y = 888.** The player's controls and subtitles cover the
caption band; only narration goes there.

**Order is meaning.** Source is leftmost, then the CPU, then memory. A lower
level is never left of, or above, a higher one; the kernel is always
underneath. Addresses increase downward in every grid, so the newest stack
frame is on top in the byte view as it is in the card view.

Layouts (`theme.layout`), by number of views:

| Views | Name | Columns | Mock |
| --- | --- | --- | --- |
| 1 | `solo` | 12 | |
| 2 | `duo` | 5, 7: context and subject | 5 (the 5 holds two) |
| 2 | `duo_even` | 6, 6: a comparison | 4 |
| 3 | `trio` | 4, 4, 4: source, CPU, memory | 3 (above the kernel) |
| 3 | `trio_stack` | 5; 7 over 7 (240, 504) | 2 |
| 3 | `trio_hero` | 12 (408) over 7, 5 (336) | 7 |
| 4 | `quad` | 5; 7 (336) over 3, 4 (408) | 1 |
| far | `far` | 8, 4 (480) over 12 (264) | 8 |

Four is the most. In a `quad` one panel is read and three are context; the
panel the narration is in has its tag's box filled gold. A panel shows at
most 10 rows of memory or of a table (14 lines of code); past that, elide
rows or go nearer.

## Colour

| | Hex | On page | On `raised` | Use |
| --- | --- | --- | --- | --- |
| page | `0a1030` | | | the ground; panel bodies too |
| raised | `16245f` | 1.3 | | tags, cells, cards, 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 |
| text, primary | `eee6d2` | 14.9 | 11.6 | anything to be read |
| text, dim | `9aa6d9` | 7.8 | 6.1 | names, notes |
| text, faint | `6a7ab8` | 4.5 | 3.5 | leading zeros, line numbers, column heads |
| ink | `050a24` | | | letters on a solid accent |

Marks (`theme.Role`, `theme.mark`). *Solid* is full strength; the *ember* is
the hold state, a colour of its own, not an alpha blend (gold blended over
lapis goes grey). Ratios: solid against the page, ink on solid, primary text
on ember.

| Role | Solid | Ember | Ratios | Form |
| --- | --- | --- | --- | --- |
| current | gold `e8c46a` | `4a3d1c` | 11.1, 11.7, 8.6 | solid plaque on the label, ember across the row |
| write | vermilion `ff6a4a` | `5a2218` | 6.6, 6.9, 10.1 | solid fill, bold ink digits; cools to ember and a 6-unit solid bar |
| read | `6fd6e6` | `1c4652` | 11.0, 11.6, 8.3 | 3-unit frame, ember inside |
| pointer | `d59cf5` | `45305a` | 8.8, 9.2, 9.3 | 4-unit frame round the bytes, and an arrow |
| allocated | `7fdc9a` | `1f4a33` | 11.2, 11.7, 8.1 | ember block in a 3-unit solid frame |
| freed | no colour | | | hollow; dashed dim frame; coarse hatch where there is room |
| fault | vermilion | | | hazard bands round an ink plaque naming it |
| attention | bright | | | bright frame; a veil (page at 65%) over the rest |
| flow | primary | | | thin arrow, gone a second after it lands |
| unknown | faint | | | two 6-unit squares where the digits would be |
| kernel | vellum `eee6d2` | | 14.9 | the ground itself |

- **Current** is one place a panel: the line, the instruction, rip, the newest
  frame, the node, the page. All gold, so the eye joins them across panels.
  rip is never "written"; it is current.
- **Write** is the only mark that fills a value and the only one that pulses.
  The changed thing is the brightest warm thing on a blue frame.
- **Fault** shares write's colour on purpose (something was done to the
  program) and is the only banded mark; it always carries the signal's name.
- **On the kernel's ground** ink is `0a1030`, dim text `4a5488` (5.8), rules
  `b9ad8e`; accents stay solid inside a 2-unit ink frame; a cooled change is
  `f3b9a0`. There are no embers there.

**Pigments** say *which* object, thread or variable, the same in every view:
dark bodies under primary text (4.5 or better), so marks still read on top.
In order: ochre `8a5e0c`, teal `17707c`, madder `a03060`, malachite `1c7450`,
violet `6a3fb0`, azurite `2f5fc4`. At most four in a scene. Ochre and teal
are apart for every viewer; from the third on the name carries it, so a
pigment is never without its name.

**Code** (pardes's four classes): plain `eee6d2`; keyword `c0dcff`, bold;
string and number `c8f0d8`; comment `9aa6d9`, italic; line numbers faint. As
a pardes theme: `bg` page, `fg` primary, `kw`, `str` = `num`, `comment`,
`lineno`. pardes's own `lapis` is not used for video: its vermilion keywords
and gold strings would spend the two colours that mean "changed" and "here".

**Colour vision.** Blue ground against gold and vermilion is the axis every
common deficiency keeps. Two pairs fall together by hue for a deuteranope:
allocated with current, pointer with read. Neither pair ever shares a form
or a place (a block against a plaque, an arrow against a frame).

**After 4:2:0.** Every accent is light (luminance 0.32 or more on a page of
0.007), so luma carries it; chroma only names it. Saturated colour is never
a line under 4 units or a fill under 12. Pigments, dark and saturated, are
fills only. Checked by encoding the mocks with x264 at CRF 34, and at 480p
CRF 30 scaled back up: 30-unit hex pairs, 25-unit address gutters, frames,
arrows and embers survive both; 2-unit rules, the hatch and 22-unit notes
fade at 480p, which is why none of them carries anything alone.

## Type

| Face | File | For |
| --- | --- | --- |
| Go Mono | `Go-Mono.ttf` | data, code (sketchbook's built-in face) |
| Go Mono Bold | `Go-Mono-Bold.ttf` | keywords, a struck value, plaque letters |
| Go Mono Italic | `Go-Mono-Italic.ttf` | comments |
| Go | `Go-Regular.ttf` | captions, notes |
| Go Medium | `Go-Medium.ttf` | tags, labels, the running head |
| Go Bold | `Go-Bold.ttf` | titles |

Bigelow & Holmes, BSD-3-Clause (the Go licence); installed here by `ttf-go`
in `/usr/share/fonts/go/`, upstream `golang.org/x/image/font/gofont/ttfs`.
They drew Lucida, acme's face; the two families share an x-height and have
tabular figures and a slashed zero, and neither has ligatures to turn `->`
into an arrow.

Sizes, in units:

| Mono | | Sans | |
| --- | --- | --- | --- |
| 25 | gutters, types, small tags | 22 | tag notes, glosses, the rail |
| **30** | bytes, words, registers, code | 24 | a sentence beside a row |
| 35 | values in nodes and chunks | **28** | tags, labels, legend names |
| 45 | a value in flight | 30 | kicker |
| 60 | hero cells, a system call's name | 40 on 54 | caption (code in it: mono 35) |
| | | 44 | subtitle |
| | | 116 on 128 | title |

- **Mono sizes are multiples of 5.** Go Mono advances 0.6 em, so a character
  is 15, 18, 21, 27 or 36 units, a hex pair is 36, and the grid is the same
  whole-number arithmetic at 1080p and at 4K (the renderer rounds advances
  to whole pixels).
- **Hard minimum: mono 30, sans 28** for anything the narration depends on.
  On a phone held sideways that is an x-height of about 1.1 mm. 22 to 25 is
  furniture: a viewer may lose it and still follow.
- **Hex**: lower case, groups of four, half a character apart, no `0x`
  (`0x` belongs to source code and to sentences). A register is 16 digits,
  an address 12, or its last 8 in a panel under 8 columns whose tag gives
  the rest. Leading zeros are faint. In an address gutter only the last
  group is primary: the end that changes from row to row.
- **Decimal** for what the source calls a number (locals, array values);
  hex for what the machine holds.
- Code for a video is written to fit: 34 characters a line in 5 columns, 42
  in 6, 51 in 7. The panel strips common indentation.

## Components

Every component draws the same states the same way: plain; **write** (solid,
this step); **held** (ember and bar, changed within 3 steps); **read**
(framed, this step); **current**. What the recording provides:

| Event (`trace.Kind`) | Drawn as |
| --- | --- |
| `step` and a `Regs` that differs | write on those registers; rip moves the current marks |
| `mem_write`, `mem_read` | write, read on those bytes (and on their page, from far) |
| `line` | the current line moves; the old one joins the trail |
| `call`, `ret` | a card on, or off, the call stack; a node in the call tree, then its result |
| `cmp` | a comparison plaque (`31 > 12`) |
| `variable` | a name beside its rows; a row in the locals table |
| `alloc`, `free` | a chunk becomes allocated, freed |
| `map`, `unmap`, `fault` | a row of the page map; a page becoming present |
| `syscall_enter`, `syscall_exit` | a block on the timeline; a crossing |
| `signal` | a fault band |
| `sched`, `thread_start` | a lane and a pigment for each thread |
| `mark` | a cue for a caption or a pause |

### Panel

Tag 48 tall on `raised`; a 20-unit box 14 in (gold in the panel the
narration is in, a faint hollow elsewhere); title sans medium 28 at x + 48;
a note, sans 22 faint, ranged right; rule 2 units round the body (dim when
in focus). The body is the page. Padding 20 and 16.

### Register table (mocks 1, 3, 5)

Rows of 48: name (mono 30, dim) 18 in; value, 16 digits in fours, ranged
right. Needs 3 columns; 4 with a role beside the name (`rdi` *1st*).

- Shown by default, in this order: rip, rax, rdi, rsi, rdx, rcx, rsp, rbp,
  then flags CF ZF SF OF. Any other register appears when a step touches it
  and leaves when its ember has gone. Rows never reorder.
- rip: gold plaque on the name, gold ember across the row.
- Flag chips 60 by 36: set is a 3-unit vellum frame and bold bright letters;
  clear is a rule frame and faint letters; just changed has a 6-unit
  vermilion bar under it.

The same table, with a type column and decimal values, is the **locals**
table (mock 7).

### Memory grid (mocks 2, 5, 8)

One 8-byte word a row, always: a row is a stack slot, a pointer, a field.
Three distances:

**Bytes.** Left to right: mark lane (88) for registers and pointer variables
that hold this row's address, as plaques pointing in; address gutter (mono
25); arrow lane (52, plus 22 for each further arrow nested in it); 8 cells of
46 on a 48 pitch; the same bytes as text (mono 30, non-printing as faint
dots); names. Rows are 60 apart.

- A zero byte has faint digits, so data stands out of padding.
- Never observed: two dots and no cell. Absence of fill is absence of
  knowledge.
- A pointer: a 4-unit frame 6 outside its 8 cells, and an arrow that leaves
  the frame's left edge, runs in the lane, and ends on the left edge of the
  byte it holds the address of. A target off-panel ends in a plaque at the
  panel's edge.
- Whose bytes: a divider row (a 12-unit square, gold for the frame that is
  running; the function's or object's name; a rule). Stack frames, heap
  chunks and globals are all dividers.
- A name spanning rows gets a 3-unit bracket. Variable names are mono;
  descriptions (`saved rbp`) are sans.
- Bytes not shown: an elision row, three dots and what they are.
- A string: text cells 84 tall, the character over its byte (mock 3).

**Words.** The 8 bytes as one number, on the footprint of the 8 cells (382
by 46), with the field's name and meaning to its right (`next`, `= NULL`).
Bytes turn into their word in place: the pairs reverse order as they close
up, which is little-endian shown rather than said.

**Pages** (the far form). A row a mapping: address, `r` `w` `x` chips, name,
size, then one 22-unit square a page on a 24 pitch. Hollow is mapped and
untouched, `rule`-filled is present, and the marks apply at this scale too:
the page holding rip is gold, a page read is framed cyan, written is
vermilion. The kernel's half is a vellum band underneath.

### Stack

As memory: the grid, with a divider per frame and `rsp`, `rbp` in the mark
lane. As an idea: **cards** (mock 1), newest on top, 56 tall and 12 apart,
with a 12-unit spine (gold on the newest), the function in bold, its
arguments, and the line it is at. A call slides a card in from above; a
return strikes its value on the card, the card leaves upward, the value
flies to the caller.

### System call (mock 3)

The kernel's ground rises from the bottom edge to y = 576, full bleed, under
three user panels. The three columns keep their meaning through it: under
the source, what the kernel runs (cards in ink frames); under the registers,
the call decoded (its name, mono bold 60; rows of register, argument, value,
meaning); under memory, the kernel's copy of the bytes.

- The registers that carry arguments are framed as read.
- A crossing is a 6-unit arrow, vellum above the line and ink below it.
- On return an arrow comes up and rax is written. An error return is a fault
  band on rax with the errno's name.

**Timeline strip** (mock 8): the same boundary from far away. A 3-unit
vellum line with user time above and each call hanging below it as a vellum
block 44 tall, as wide as its time in the kernel (12 at least, 16 apart).
Calls not yet made are hollow. Names (mono 25) go under blocks left to
right wherever one fits. The current call has a gold plaque and a gold line
through it; brackets above name the phases of user time. With several
threads, a lane each, with its pigment and name.

### Source panel (mocks 1, 2, 3, 5, 7)

Mono 30 on lines of 48. Gutter: three digits ranged right, then 16; code 20
after.

- Current line: gold plaque on the number (ink, bold), gold ember across.
- Trail: the last three lines executed keep a 6-unit bar at the left edge
  in gold cooling (`ae9350`, `746235`, `463b20`).
- Values: a hollow plaque at the end of the current line (`n = 1`).
- Lines left out: an elision row.
- **Unfold.** The current line opens into its instructions, indented 36
  behind a rule; the instruction at rip has an 8-unit gold bar and ember.
  This is the step from source to CPU, and it happens in place.
- **One expression.** A bright frame round it, the veil over the rest; a
  copy is set on a line below the code and its parts are replaced by their
  values one at a time, each replacement a write.

### Data structures (mocks 2, 7)

- **Array.** Cells 96 by 84 (mono 35), or 168 by 132 (mono 60) when the
  array is the subject. The index, mono 25 faint, is inside the cell at top
  left; index variables are dark tags inside it at top right, and slide from
  cell to cell. A comparison frames both cells as read and puts the `cmp`
  above them. A swap is two flights, one over and one under.
- **List node.** 180 by 72: the value (mono 35), then a 72-unit pointer
  compartment with a 14-unit square the arrow leaves from. Null is a slash.
  Arrows turn square corners with a 12-unit fillet and enter a node at its
  left edge.
- **Tree, graph.** Circles of radius 24 (36 alone on the stage), edges 3
  units. Not yet reached: absent in a call tree, which grows as it runs; a
  hollow ring in a graph. Waiting: page fill in a 4-unit vellum ring, on
  4-unit vellum edges. Current: solid gold. Done: `raised`, dim digits, its
  result in a 28-unit badge on its shoulder.
- **A value moving.** It lifts into a card (100 by 60, bright frame, bold
  45), flies an arc, lands as a write. Where it left keeps its digits,
  faint: a copy does not erase.

### Heap map (mock 4)

A strip to scale, 4 units a byte, 88 tall (56 when two are stacked). The
allocator's own bytes are `rule`-filled; allocated is a green ember in a
green frame with its variable's name; freed is hollow, dashed and hatched;
never used is a rule frame; three dots where it continues. Bytes a step
wrote are vermilion at scale, inside the chunk. A **wedge** (two rules from
a thing's corners to its enlargement's) opens a chunk into word rows.
Bookkeeping is drawn as what it is: a row of counts for bins, a row of bits
for a mask, an arrow for a list's head. Two allocators side by side use the
same three tiers at the same heights.

### Words on the frame

- **Label**: sans medium 28 beside its subject; an identifier is mono 30.
- **Note**: sans 24 dim; a gloss the narration also says.
- **Plaque**: 40 tall, 12 padding. Hollow for a value, `raised` for a place
  or a name, a pigment for a tracked object.
- **Callout**: there is no bubble. A note plus a bracket, a wedge or a flow.
- **Caption**: sans 40 on 54, ranged left on the margin, two lines of 64
  characters at most. On the kernel's ground it is ink.
- **Running head**: the title (sans medium 28, dim); then, mono 25 faint,
  where the program is, which is the current line itself whenever no source
  panel is on screen. At the right the **level rail**: source, cpu, memory,
  kernel, each a 16-unit square: gold where the narration is, solid when on
  screen, hollow when not.
- **Title card** (mock 6): a gold square and the series (sans medium 30);
  the title, Go Bold 116 on 128, bright; a subtitle, 44, dim.
- **Legend** (mock 6): a sample 94 by 46, a name (28), a gloss (22). The
  full card follows the title once; up to four entries may sit in the
  caption band while no caption is up.

## Levels, and moving between them

What keeps a viewer's place:

1. **Place.** Left is source, right is memory, down is the kernel. A level
   enters from its own side and leaves to it.
2. **Gold.** Each panel has one current mark. Going down a level, the upper
   level's gold is the last thing to dim and the first to return.
3. **The running head.** When the source panel is collapsed, its current
   line is written in the head. The rail says which levels are on screen.
4. **Pigment.** A tracked variable has one pigment in the locals table, on
   its list node and on its rows of memory (mock 2).
5. **Three lines, three meanings.** A pointer arrow (orchid, 4 units,
   filled head): this number is that address. A flow (vellum, 3 units, for
   a second): this value went there. A wedge (two rules): this, magnified.

Source to registers to bytes and back, as a sequence:

| | What happens | Seconds |
| --- | --- | --- |
| 1 | the current line holds | 0.5 |
| 2 | it unfolds; the lines below move down, instructions arrive 0.03 apart | 0.4 |
| 3 | if registers are not up: the source narrows, they enter from the right | 0.8 |
| 4 | the instruction mark steps; each step strikes the registers it writes | 0.25 a step, then hold |
| 5 | an instruction with a memory operand: the operand is framed | 0.4 |
| 6 | a flow draws from the register to the row; the value flies it; the bytes strike | 0.4, 0.6 |
| 7 | nearer: the rows are framed, the rest veiled, the camera goes to x2; the source is now the head's line | 0.4, 0.3, 1.2 |
| 8 | back: camera to x1, veil off, the line folds, the mark steps to the next line | 1.2, 0.3, 0.4, 0.25 |

From far to near (mock 8): a wedge draws from the page, or the block of
time, to a panel beside it (0.3). Both may stay, or the camera goes in (1.6
for x4) and the far view survives as the head's text.

## Motion

60 frames a second; every duration is a whole number of frames
(`theme.time`).

| Name | Seconds | For |
| --- | --- | --- |
| `snap` | 0.10 | a colour changing where nothing moves |
| `quick` | 0.20 | leaving; a small change of state |
| `step` | 0.25 | the current mark moving to a neighbour |
| `move` | 0.40 | moving within a panel, up to 400 units |
| `travel` | 0.60 | moving between panels, or further |
| `layout` | 0.80 | panels rearranging |
| `camera` | 1.20, 1.60 | to twice or half the scale; beyond |

| Curve | cubic-bezier | For |
| --- | --- | --- |
| `standard` | 0.2, 0, 0, 1 | whatever moves and stays: off promptly, a long settle |
| `enter` | 0, 0, 0.2, 1 | arriving |
| `exit` | 0.4, 0, 1, 1 | leaving |
| `camera` | 0.65, 0, 0.35, 1 | camera and layout |
| `linear` | | colour cooling, the playhead |

Nothing bounces. The one overshoot is a struck cell's scale,
`1 + 0.08 sin(pi t)` over 0.20.

**How a change is signalled.** A write: solid in 0.10 with a 0.20 pulse;
solid for 0.50; cools over 0.40 to its ember and bar; stays while the thing
has changed within 3 steps (4 s where time runs free); gone in 0.60. A
read: framed in 0.10, kept for the step (0.50 at least), gone in 0.30, no
pulse. The current mark slides (0.25); over more than 8 rows it goes out
and comes in (0.10 each) and the trail shows where it was. A pointer
changing target: the head travels the lane (0.40); the old path stays,
dashed and faint, for 0.80, then fades in 0.30.

**What moves and what fades.** A thing that is the same thing before and
after moves: a value, the current mark, an arrow's head, a card. A thing
that begins or ends fades: a frame, a caption, a panel's contents. A value
in flight lifts (0.10, to 1.12), flies an arc a quarter as high as it is
long (34 to 120 units), and lands as a write.

**How much at once.** One thing moves because the program did something;
at most two more move because of it (a value lands, a cell strikes, an
arrow turns). Things arriving together start 0.03 apart in reading order,
the last no more than 0.30 after the first. The camera and the layout move
alone, with no state changing under them.

**Pace.**

- *Walk*: 1.5 s a step, with everything above. The first three times a
  pattern is shown, and any step the narration names.
- *Run*: 0.25 s a step. No pulses, no flights; colour only.
- *Sprint*: under 0.05 s a step. Single changes are not drawn; embers and a
  counter are.
- Still for 0.8 after the stage is rearranged, for 1.0 before it is again.
- A caption stays 1.5 s plus 0.06 a character. It fades in over 0.25 rising
  8 units and is never typed out. Captions change while nothing moves.

**Camera.** Three scales only: x1 the frame, x2 a panel, x4 a few cells. It
never turns. The target is framed for 0.4 first; the camera holds 0.6 on
arrival; 1200 units a second at most. Whatever would end smaller than its
minimum size is faded out before the move, not shrunk.

## Legibility rules

- Text: mono 30 and sans 28 or larger for what must be read; nothing under 22.
- Lines: 2 units is the thinnest (rules, never meaning); 3 the thinnest
  that means something; 4 for arrows. Nothing is 1 pixel at 1080p.
- No hue alone: each role has its form (the table above; a test checks no
  two share one).
- No alpha tints, no gradients, no glow, no grain. Flat fills cannot band,
  and a codec spends its bits on edges, which are all axis-aligned here but
  for arrows and tree edges.
- Dashes are 12 on, 8 off; the hatch is 5 on a pitch of 20; a fault's bands
  are 12. Nothing finer: it turns to mush at 480p. Freed reads by being
  hollow and dashed; the hatch only helps at 720p and up.
- Solid vellum is the kernel and nothing else: no vellum chips, tags or
  buttons.
- One gold mark a panel. One step's writes in vermilion at a time.

## The mocks

Generated by [`mock/gen.py`](mock/gen.py) and rendered with resvg; each has
a `-480.png` beside it, the phone check.

| | Shows | Changed after looking |
| --- | --- | --- |
| [1](mock/01-fib-recursion.png) | `quad`: source, call tree, call stack, registers | gold tints were alpha blends and came out grey, so embers became colours of their own; the flags ran into the panel's edge, so the table shows five registers |
| [2](mock/02-list-insert.png) | list nodes over the heap words that hold them | the pigment spines sat at the far right, away from the rows they named: now plaques in the mark lane, pointing at their rows; column heads gave way to a note in the tag, to fit six rows |
| [3](mock/03-syscall-write.png) | `write` crossing into the kernel | the memory panel overflowed, hence the 8-digit gutter for narrow panels; U+2423 fell back to another font, so the visible space is drawn; `user` and `kernel` set larger |
| [4](mock/04-malloc-glibc-musl.png) | glibc and musl after `free(b)` | first pass was three tiers of collisions and an arrow touring the panel; rebuilt as the same three tiers both sides, a wedge into `b`, and a short arrow from the bin to the row |
| [5](mock/05-memory-write.png) | a pointer being stored, byte by byte | a line from `rax` ran under the row like an underline: now a flow that stops short of the gutter; `rsp` and `rbp` moved from the far right to the mark lane; frame dividers added |
| [6](mock/06-title-legend.png) | title card and the legend | six glosses collided at five-across widths: shortened, twelve entries in two rows |
| [7](mock/07-sort-swap.png) | insertion sort, a compare and a swap | cells were small in an empty panel, so the hero size; index variables moved from under the cells to tags inside them, freeing the space a swap needs |
| [8](mock/08-far-view.png) | page map, one page magnified, system calls | the kernel row was clipped and page counts ran out of the panel: sizes got a column, the kernel a band; the wedge went from three lines to two; two call names collided, so names are placed only where one fits |

Across all of them, after the first round: mono sizes went from 22, 24, 28
to 25, 30 (whole-unit advances, and larger on a phone); set flags and index
tags stopped being vellum chips once vellum meant the kernel; the hatch was
coarsened after the 480p encode.

Specified here and not yet drawn: a graph, a tree as the subject, ordinary
array cells, thread lanes, a fault in place, the bytes-to-word change, the
expression line.

## What this asks of the renderer

1. **More than one face in `f.text`**: Go Mono Bold (and Italic), and Go in
   three weights. The README describes one family set by an environment
   variable. Sans text is nearly all written by the author, so it can be
   Typst (which must be given `--font-path` for the Go fonts); bold mono is
   data and cannot. Without it the design still works: bold falls back to
   regular and the fills carry the state.
2. **Text under a moving camera.** Text is drawn at whole-pixel advances for
   its size, so at the in-between scales of a zoom the letters will shift
   against each other. Either a panel is drawn to an image for the move and
   scaled (that needs linear filtering; images sample nearest natively), or
   moving text is drawn as outlines.
3. **Dashed strokes** from `sk.draw` (the vector module has dashing).
4. **Hatch and hazard fills**: lines clipped to a rect; `f.clip` suffices.
5. **Whole-unit mono advances** at 60, 50, 70, 90, 120 pixels (the 4K sizes)
   as well as at 30, 25, 35, 45, 60: Go Mono's 0.6 em should round to them.
6. The veil is one translucent rect; nothing else needs alpha, additive
   blending or a shader.

## Implementation order

Most clarity for the least code first.

1. `theme.zig`, the panel, mono text in columns: the **register table** and
   the **source panel** with the current line and trail. Rects and text.
2. **The mark state machine**: plain, write, held, read, current, with the
   strike and cooling timings. Every later component is this on a
   different shape.
3. **Caption and running head** with the level rail.
4. **Memory grid**, bytes and words: gutter, dividers, elision, names.
5. **Arrows** with filleted elbows and heads: pointers, flows. Then list
   nodes and call stack cards, which are rects and arrows.
6. **The kernel's ground** and the crossing; the timeline strip.
7. **Flights**: a value on an arc. Hero array cells, compare, swap.
8. **Unfold**, the step from a line to its instructions.
9. Call tree (a tidy tree layout), heap strip, wedge, page map.
10. Veil and camera at x2 and x4; bytes to word; the expression line.

Shader effects worth having: none. A glow on a write would soften the one
edge that most needs to stay sharp, grain costs bitrate and there is no
gradient for it to protect, and a vignette darkens the corners where the
running head and rail live.

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