summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 12:01:16 -0300
committerGabriel Schneider <[email protected]>2026-11-10 12:07:12 -0300
commitaf2d2cfdcdf5976f06fbcc4b1f8507f0b7d4af89 (patch)
treeeb455143013fa1b1278ae246676153205d9a3f17 /design/README.md
parenta0ca9a0bfa76cd2d04502b7f341cba5153f51899 (diff)
downloadcomputeranim-af2d2cfdcdf5976f06fbcc4b1f8507f0b7d4af89.tar.gz
computeranim-af2d2cfdcdf5976f06fbcc4b1f8507f0b7d4af89.zip
design: the visual system canim follows, with eight mock frames
Lapis page and vellum ink; a role is a form as well as a colour (current, write, read, pointer, allocated, freed, fault, kernel); panels as acme windows; Go Mono for the machine and Go for the narrator; motion as whole frames at 60 fps. design/mock/gen.py redraws the mocks from the tokens.
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md557
1 files changed, 557 insertions, 0 deletions
diff --git a/design/README.md b/design/README.md
new file mode 100644
index 0000000..826973e
--- /dev/null
+++ b/design/README.md
@@ -0,0 +1,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
+```