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