diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 15:17:21 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 15:20:24 -0300 |
| commit | 6fb92d5384ba944b2d6a9c5066a08b41a8ef555f (patch) | |
| tree | f8854c4272879c5fb54b7fd0e7c2f0e0b8ab904a /design/README.md | |
| parent | 2463e602f12f969fe085bc2114a3960411b79f87 (diff) | |
| download | computeranim-6fb92d5384ba944b2d6a9c5066a08b41a8ef555f.tar.gz computeranim-6fb92d5384ba944b2d6a9c5066a08b41a8ef555f.zip | |
design: a language of named blocks; the lens as a band over the whole context
The README is now the catalogue: atoms, rows, panels, ties, the frame and
the verbs, each block specified once under the name the code uses, with
rules of composition and what is forbidden. From the user's notes on the
context mocks: a lens is a band across the top, its drawing on the left
and the bytes it is drawn from on the right, a hexdump with each field's
bytes marked and read at the row's end; the disassembly is seventeen rows
in address order with a source-line column and an annotation for what
each row read, set or jumped to; a register is pinned to the node it
points at by name; hex is unbroken; and four kinds of tie say which pane
is a view of which (thread, link, projection, echo).
Diffstat (limited to 'design/README.md')
| -rw-r--r-- | design/README.md | 1224 |
1 files changed, 692 insertions, 532 deletions
diff --git a/design/README.md b/design/README.md index b108cf2..8624017 100644 --- a/design/README.md +++ b/design/README.md @@ -1,651 +1,811 @@ -# canim: the look +# canim: the design language -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). +This is the catalogue. Everything that can appear in a canim frame is a +**block** with a name, specified here once; everything larger is a +composition of blocks. The names are the ones the code uses. A gallery +scene that draws every block in every state is the test of this page. -**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. +- How blocks move is the [verbs](#6-verbs) below; the reasoning and the + full timing charts behind them are in [`motion.md`](motion.md). +- The blocks drawn: [`mock/`](mock). [Which mock shows which block](#the-mocks). +- The numbers are tokens in `anim/src/theme.zig`: + [what to change there](#token-changes). -The idea, in six rules: + -1. **Lapis page, vellum ink.** 0x4200.cafe's own palette: a deep blue page, - cream text, gold for where execution is, vermilion for what just changed. -2. **Ink says what a thing is; paper says what happened to it.** **(rev 2)** - The colour of a value's digits is where it points (stack, heap, code, - data), a keyword, a string. A fill, a frame, a tick or a plaque behind or - beside it is an event: written, read, current. The two never share a - channel. +## The rules + +1. **Lapis page, vellum ink.** A deep blue page, cream text, gold for where + execution is, vermilion for what just changed. +2. **Ink says what a thing is; paper says what happened to it.** The colour + of a value's digits is where it points, or that it is a keyword or a + string. A fill, a frame, a tick beside it is an event. The two never + share a channel. 3. **Every mark has its own form.** Written is filled, read is framed, - changed is ticked, freed is hollow and dashed, unknown is two dots. -4. **Solid vellum is the kernel**, at every scale, and nothing else. -5. **Panels are acme windows.** A tag with a square box, a 2-unit rule, a - body. Square corners, no shadows, no gradients, no glow. -6. **The whole context, always, and the lens beside it.** **(rev 2)** Every - register followed as far as it points, the instructions at the pc, the - stack, the backtrace and the source are in the same place in every frame. - A list, a tree, an array is a lens on that state: never shown instead of - it, and visibly tied to the words it is made of. The machine is set in - JetBrains Mono; the narrator in Go. + changed is ticked, freed is hollow, unknown is two dots. Nothing is told + by hue alone. +4. **Solid vellum is the kernel**, and nothing else. +5. **Panels are acme windows.** A tag, a 2-unit rule, a body. Square + corners, no shadows, no gradients, no glow. +6. **The whole context, always.** Every register followed as far as it + points, seventeen instructions round the pc, the source, the stack: in + the same place in every frame, as pwndbg shows them. A lens (a list, a + tree, an array) is drawn over that state and never instead of it. +7. **Panes are views of one machine, and the ties are drawn.** A source + line and its instructions, a register and what it points at, a run of + bytes and the node drawn from them: each relation has a form, a route + and a moment. +8. **Low level first.** The bytes change, the tie carries it, the drawing + reacts. A cause is always on screen before its effect. - +## Vocabulary -## What changed +Six layers. A block is made only of blocks from the layers above it in +this table. -| | 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 | +| Layer | Block | Is | Options and states | +| --- | --- | --- | --- | +| 1 atom | [`address`](#address) | hex digits in the ink of where they point | `lead`, `name`, `rwx` | +| | [`value`](#value) | anything that is not an address | by class: digit, number, negative, string, fd, flags, bool, char, unknown | +| | [`arrow`](#arrow) | the sign between two things in a chain | `points`, `holds`, `more` | +| | [`hop`](#arrow) | a `points` arrow and the address it leads to | | +| | [`byte`](#byte) | two hex digits of a dump | `number`, `pointer`, `allocator`, `unread`; `pad` | +| | [`mark`](#mark) | what happened to a thing | `current`, `armed`, `struck`, `held`, `read`, `trail`, `allocated`, `freed`, `fault`, `attention`, `unknown`, `kernel` | +| | [`plaque`](#plaque) | a solid label under the current mark | `gold`, `chip` | +| | [`pin`](#pin) | a register's name at the thing it points to | `row`, `under` | +| | [`bracket`](#bracket) | a span marked at its edge | `quiet`, `tie` | +| | [`tag`](#tag) | a panel's title bar | `focus`; `note` or `legend` | +| 2 row | [`chain`](#chain) | a telescope: this, which points to that, which holds this | `room`, marks per hop | +| | [`reg`](#reg) | a register and its chain | `rip` (with `flags`) | +| | [`slot`](#slot) | a word of the stack and its chain | pins | +| | [`insn`](#insn) | an instruction and its annotation | `current`, `ran`, `ahead`, `outside` | +| | [`line`](#line) | a line of source | `current`, `trail` | +| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run | +| | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` | +| 3 panel | [`registers`](#registers) | all seventeen | | +| | [`stack`](#stack) | the words from rsp, and the frames they belong to | 8 or 4 slots | +| | [`backtrace`](#backtrace) | the call chain as rows | only in the `none` split | +| | [`source`](#source) | a window on the file | 14, 8 or 10 lines | +| | [`disasm`](#disasm) | the instructions round the pc | 17 or 11 rows | +| | [`lens`](#lenses) | a drawing of some state, and the bytes it is drawn from | `beside`, `subject` | +| | [`hexdump`](#hexdump) | memory, a `bytes` row a line | | +| | [`nodes`](#nodes) `array` `calls` `heap` `syscalls` `pages` | the drawings a lens can hold | | +| 4 tie | [`thread`](#4-ties) | the current line is these instructions | standing | +| | [`link`](#4-ties) | this register points at that | for a step; rests as a `pin` | +| | [`projection`](#4-ties) | these bytes are that part of the drawing | for a step | +| | [`echo`](#4-ties) | the same mark in two panels at once | for a step | +| 5 frame | [`stage`](#5-the-frame) | the band and the two columns | split `none`, `beside`, `subject` | +| | [`clock`](#clock-and-caption) | where in the recording | | +| | [`caption`](#clock-and-caption) | the narrator | | +| | [`veil`](#clock-and-caption) | page over what a beat does not touch | | +| | [`card`](#clock-and-caption) | a title, the legend: no program running | | +| 6 verb | [`fire` `arm` `strike` `cool` `read` `extend` `link` `project` `travel` `advance`](#6-verbs) | what one block does | | +| | [`cascade` `run` `sprint` `establish` `scroll` `relayout` `visit` `say`](#6-verbs) | what a frame does | | -## The frame (rev 2) +## 0. Tokens -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. +### Grid -| Band | y | What | -| --- | --- | --- | -| margin | 0 to 48 | page | -| stage | 48 to 888 | the context and the lens: 35 rows of 24 | -| clock | 898 to 902 | a rule the width of the stage; gold along it as far as the recording has run; `moment 72 of 95` under its right end | -| caption | 912 to 1032 | one or two lines of narration | -| margin | 1032 to 1080 | page | +1920 by 1080 units; a 4K master is two pixels a unit, at 60 frames a second. -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. +| Token | Value | +| --- | --- | +| context mono | 20: an advance of 12, rows of 24 | +| panel | a tag of 24, 4 of padding, rows, 4 of padding: `32 + 24 n`; 12 at the sides | +| between panels | 12 | +| columns | two of 880, at x 64 and 976; the gutter between them, 944 to 976, belongs to the ties | +| strokes | 2: rules, frames, chain arrows, a projection. 3: a link, the thread, a lens's frames. 4: a tick | -**The state column** (right, x 976 to 1856) is the same in every frame of -every scene: +### Colour -| Panel | Rows | Height | y | +| | Hex | On page | Use | | --- | --- | --- | --- | -| 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 | +| page | `0a1030` | | the ground; panel bodies | +| raised | `16245f` | 1.3 | tags, node bodies, the paper under a field's bytes, chips | +| well | `101a48` | | a node's pointer half | +| rule | `3a4a8a` | 2.2 | rules, quiet brackets | +| bright | `fff8e8` | 17.6 | titles, a set flag, the newest frame's name | +| primary | `eee6d2` | 14.9 | numbers, names of code, plain code | +| dim | `9aa6d9` | 7.8 | register names, an allocator's bytes, notes | +| faint | `6a7ab8` | 4.5 | chain arrows, line numbers, a decimal beside its hex | +| ink | `050a24` | | letters on a solid mark | -**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: +**Regions: the ink of an address**, as pwndbg colours them. The legend is +the registers' tag, always on screen. -| 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)) | +| Points into | Ink | On page | Also told by | +| --- | --- | --- | --- | +| stack | `f2d675` | 13.0 | by far the lightest | +| heap | `86b6ff` | 9.0 | | +| code | `ff8f9a` | 8.5 | its name always follows | +| data, writable | `d59cf5` | 8.8 | | +| writable and executable | its region's | | a 2-unit underline | +| read-only data | primary | 14.9 | | +| a string | `b5e8c8` | 13.6 | its quotes | -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. +Known weakness: heap, data and code have one luminance, so between those +three the ink is hue alone, as it is in pwndbg. A code address has its +name; heap and data have only their digits. -Of the frame's area: +**Marks: the colour of an event.** Solid, and the ember it cools to. -| | No lens | Lens beside | Lens as subject | -| --- | --- | --- | --- | -| state column | 35% | 35% | 35% | -| source and disassembly | 35% | 21% | 16% | -| **context in all** | **70%** | **57%** | **51%** | -| **lens** | | **13%** | **18%** | -| caption band | 10% | 10% | 10% | +| Role | Solid | Ember | +| --- | --- | --- | +| current | gold `e8c46a` | `4a3d1c`; trail `ae9350`, `746235`, `463b20` | +| write | vermilion `ff6a4a` | `5a2218` | +| read | `6fd6e6` | `1c4652` | +| allocated | `7fdc9a` | `1f4a33` | +| kernel | vellum `eee6d2` | | -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. +**Code**: plain primary; keyword and mnemonic `c0dcff` bold; string and +number `b5e8c8`; comment dim italic. **Pigments** name an object across +views, at most four: ochre `8a5e0c`, teal `17707c`, madder `a03060`, +malachite `1c7450`, violet `6a3fb0`, azurite `2f5fc4`. Never a ground +under region ink. -**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. +### Type -**No data below y = 888.** The player's controls and subtitles cover the -caption band. +| Face | For | +| --- | --- | +| JetBrains Mono NL Medium | all mono under 30 | +| JetBrains Mono NL Regular | mono at 30 and over | +| JetBrains Mono NL Bold | keywords, mnemonics, a struck value, plaques, pins | +| JetBrains Mono NL Italic | comments | +| Go, Go Medium, Go Bold | captions and notes; tags; titles | -## Colour +NL because the plain family's ligatures turn `->` into a sign that is not +in the source. Medium because thin strokes on a dark ground die first in a +stream. OFL and BSD; `/usr/share/fonts/TTF/`, `/usr/share/fonts/go/`. -| | Hex | On page | On `raised` | Use | -| --- | --- | --- | --- | --- | -| page | `0a1030` | | | the ground; panel bodies too | -| raised | `16245f` | 1.3 | | tags, cells, plaques, node bodies | -| rule | `3a4a8a` | 2.2 | 1.7 | rules, hollow cells, wedges; fill of bookkeeping | -| text, bright | `fff8e8` | 17.6 | 13.7 | titles, a value in flight, a landing frame | -| text, primary | `eee6d2` | 14.9 | 11.6 | numbers that are not addresses, names of code, plain code | -| text, dim | `9aa6d9` | 7.8 | 6.1 | register names, notes | -| text, faint | `6a7ab8` | 4.5 | 3.5 | arrows in a chain, offsets, line numbers, a decimal beside its hex | -| ink | `050a24` | | | letters on a solid accent | +| Mono | Advance | For | +| --- | --- | --- | +| **20** | 12 | the context, the dump, a lens beside | +| 25 | 15 | a lens's values; its labels and pins as subject | +| 30 | 18 | the context under the camera at x1.5 | +| 35 | 21 | code inside a caption | +| 45 | 27 | a subject lens's values; a value in flight | +| 60 | 36 | a title card | -### Regions: the ink of an address (rev 2) +Sans: 18 notes and legends, 20 tags, 40 on 54 the caption, 44 and 116 a +card. **Floor: mono 20, sans 18.** At 480p no digit at 20 can be trusted, +so: **nothing the narration depends on is only at 20.** It is also in the +caption at 35, or the camera goes to it. -As pwndbg colours them, and as its users read them without thinking: +## 1. Atoms -| 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 | +### address -The legend is always on screen, as pwndbg's is: the six words, each in its -ink, in the registers' tag. +Lower-case hex, **unbroken**, as long as it is, no `0x`, no leading zeros: +`28b41090`, `7ffe970f17b0`, `1001926`. Its ink is its region. -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. +| Option | Draws | +| --- | --- | +| `lead` n | the first n digits at 60% of the ink toward the page. Used in a column of addresses (disassembly, stack slots, a dump's gutter) with n = the digits every row shares, leaving at least two: the eye reads the part that changes | +| `name` | code only: `name+offset` in primary, 10 units on; the module when there is no symbol: `libc+27781` | +| `rwx` | a 2-unit underline | -### Marks: what happened +States: plain; `struck` (bold, in ink, on solid vermilion 5 wider each +side); `read` (a 2-unit frame, 6 out); `held` (a tick at its left). Data: +a word and the mapping it lies in. Mocks 9 to 11, everywhere. -| Role | Solid | Ember | In the context (mono 20) | In a lens's cell | -| --- | --- | --- | --- | --- | -| current | gold `e8c46a` | `4a3d1c` | solid plaque on the label, ember across the row | the same | -| write | vermilion `ff6a4a` | `5a2218` | solid behind the value, digits bold in ink | solid fill, pulse | -| changed (held) | vermilion | | a tick, 4 wide, at the value's left, for three steps | ember and a 6-unit bar | -| read | `6fd6e6` | `1c4652` | a 2-unit frame, no fill | a 3-unit frame, ember inside | -| allocated | `7fdc9a` | `1f4a33` | | ember block in a solid frame | -| freed | no colour | | | hollow, dashed, hatched | -| fault | vermilion | | hazard bands round an ink plaque naming it | the same | -| attention, landing | bright | | a 2-unit bright frame | a 3-unit bright frame; a veil on the rest | -| link, flow | the target's region ink; primary | | a 3-unit arrow, for one step | a 3-unit arrow | -| unknown | faint | | two 6-unit squares | the same | -| kernel | vellum `eee6d2` | | the ground | the ground | +### value -**How the two never fight.** +What is not an address. The tracer classifies; the class decides. -- 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). +| Class | Because | Shown | +| --- | --- | --- | +| digit | under 10 | `4` | +| small number | 10 to 0xffff | hex, and its decimal after it, faint: `0x21 33` | +| large number | larger, not in a mapping | `0x` and its hex, unbroken, primary | +| small negative | within 4096 of 2^64 | `-1` | +| string | a pointer to printable bytes and a NUL | `"..."` in string ink, C's escapes; cut with `…` and no closing quote, never under six characters | +| file descriptor | a signature or a type says so | the number, and faint what it is open on: `3 "note"` | +| flags | eflags; an argument a signature calls flags | names | +| boolean, character | the debug info types it so | `true`; `0x41 'A'` | +| unknown | never observed | two dots | -**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. +A typed value follows its type: an `int` is decimal alone, a pointer an +address alone. Mocks 9 to 11 show digit, small number, string; the rest +are not drawn. -**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. +### arrow -**Code** (pardes's four classes): plain `eee6d2`; keyword `c0dcff`, bold; -string and number `b5e8c8` (was `c8f0d8`: too close to plain at 20); -comment `9aa6d9`, italic. In the disassembly a mnemonic is a keyword. +30 wide: a 2-unit shaft and a head 8 by 10, faint. -**Colour vision.** Blue ground against gold and vermilion is the axis every -common deficiency keeps. Region ink *is* hue alone, as it is in pwndbg, and -heap, data and code have the same luminance; a deuteranope cannot tell heap -from data by colour. What is left for them: code always has its name after -it, a string its quotes, stack is far lighter than the rest, and an -address's own top digits say where it is. That is weaker than everything -else here and it is the price of the convention. +| Kind | Reads | pwndbg | +| --- | --- | --- | +| `points` | which points to | `—▸` | +| `holds` | which holds (what follows is not an address) | `◂—` | +| `more` | and goes on: `points` and three 3-unit dots | | -**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. +A **hop** is a `points` arrow and the address after it: the unit a chain +is counted, cut and re-followed in. -## Type +### byte -**(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. +Two hex digits in 24 units, on a pitch of 30; 12 more after the eighth. -| Face | File | For | +| Kind | Ink | Paper | | --- | --- | --- | -| JetBrains Mono NL Medium | `JetBrainsMonoNL-Medium.ttf` | everything mono at 20 and 25 | -| JetBrains Mono NL Regular | `JetBrainsMonoNL-Regular.ttf` | mono at 30 and larger | -| JetBrains Mono NL Bold | `JetBrainsMonoNL-Bold.ttf` | keywords, mnemonics, a struck value, plaque letters | -| JetBrains Mono NL Italic | `JetBrainsMonoNL-Italic.ttf` | comments | -| Go | `Go-Regular.ttf` | captions, notes | -| Go Medium | `Go-Medium.ttf` | tags, labels | -| Go Bold | `Go-Bold.ttf` | titles | +| `number`: a field that is not a pointer | primary | raised, one rect a field | +| `pointer`: a field that is one | the region it points into | raised, one rect a field | +| `allocator`: between allocations | dim | none | +| `unread`: never observed | two 4-unit squares, faint | none | -JetBrains Mono: OFL 1.1, `/usr/share/fonts/TTF/` (`ttf-jetbrains-mono` -2.304). Go: BSD-3-Clause, `/usr/share/fonts/go/`. +`pad`: in a little-endian word, the bytes above its highest non-zero byte +are at 45% toward the page: `70 10 b4 28` stands out of `00 00 00 00`, +and is the address `28b41070` read from the right. Marks are per run of +bytes, never per byte: see [`bytes`](#bytes). Mocks 9 to 11. -- **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. +### mark -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. +What happened, on paper and never in the letters. -| 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 | +| State | In the context (mono 20) | In a lens's cell | +| --- | --- | --- | +| `current` | a gold plaque on the label, gold ember across the row | the same | +| `armed` | a 2-unit vermilion frame, the old value still in it | 3 units | +| `struck` | solid vermilion behind the value; digits bold, in ink | solid fill | +| `held` | a vermilion tick, 4 wide, the row less 6 tall, at the value's left, for three steps | a vermilion bar, 4 high, along the cell's bottom edge | +| `read` | a 2-unit frame in read's colour, no fill | 2 units, 2 out | +| `trail` | a 4-unit bar at the row's left edge: three tones, newest first | | +| `allocated` | | ember block in a solid frame | +| `freed` | | hollow, dashed 12 on 8 off, hatched | +| `fault` | hazard bands round an ink plaque naming it | the same | +| `attention` | a 2-unit bright frame | 3 units; a veil on the rest | +| `unknown` | two dots | two dots | +| `kernel` | the ground is solid vellum | the same | -| Sans | For | -| --- | --- | -| 18 | notes in a tag, a note at the end of a row | -| 20 | a panel's title | -| 24 | a note beside a lens | -| 40 on 54 | the caption | -| 44, 116 on 128 | a title card | +One gold mark a panel. One step's writes in vermilion at a time. Mocks 9 +and 10 show current, struck, held, read, trail, unknown; 1 to 8 the rest. + +### plaque -**The hard floor is mono 20 and sans 18.** Nothing is smaller, anywhere. +A solid label. `gold`: behind the label of a current row, letters bold in +ink (rip's name, 54 wide; a line number, 50; the pc's marker, 24, with an +ink triangle). `chip`: raised, 32 by 20, behind a set flag, letters bold +and bright. Nothing else is a plaque: a register's name at a target is a +[`pin`](#pin). -**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. +### pin + +A register's name at the thing it points to: the names, bold, primary, and +a head in the target's region ink that touches the target. It answers "who +points here", and it is a [`link`](#4-ties) at rest. + +| Form | Where | Anatomy | +| --- | --- | --- | +| `row` | a row's lane (the stack) | the names, then a head 9 by 12 pointing right at the row's address | +| `under` | under a drawn node | a stub 3 wide rising to the node's bottom edge, head 10 by 10; the first name left of the stub, the others right | -**Hex.** +A pin for every register whose value is exactly the row's or node's +address; three names, then a count. No box, no fill: the boxed names of +the last revision read as buttons. Mocks 9 to 11. -- 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. +### bracket -## The context (rev 2) +A span marked at its edge: a stroke down the span and a serif at each end, +toward the span. `quiet`: 2 units, serifs 5 (a node's row in a dump, at +60% of its region's ink; an older call frame, in rule). `tie`: 3 units, +serifs 6 or 7, in the ink of the tie it ends. -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`. +### tag -### Panel +24 high, raised. A 12-unit box 8 in: solid gold where the narration is +(`focus`), a faint 2-unit outline elsewhere. The title, Go Medium 20, +primary under focus and dim otherwise. Ranged right, a `note` (Go 18, +faint) or a `legend` (words in Go Medium 18, each in its ink, 14 apart). -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. +## 2. Rows -### Registers +Every row is 24 high and one line. None wraps; what does not fit is cut at +its far end and says so. -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. +### chain -- rip: gold plaque on the name, gold ember across the row, the address in - code's ink and its name after it: `100 1926 reverse+22`. rip is never - "written". -- flags: the value, then the eight names. A set flag is upper case, bold, - bright, on a `raised` chip; a clear one lower case and faint - (pwndbg's `[ cf PF af zf sf IF df of ]`, without the brackets). One that - changed has the tick. -- Rows never reorder and none is hidden. +`address (points address)* (holds value)?` -### The telescope +- A code address ends a chain with its name. A string ends it in quotes. +- **Depth** is the recording's. **Cut** where the row's `room` ends: a + string is shortened first, then the chain ends early in `more`. Nothing + is taken from the middle. +- **Marks** are per hop. If the first is struck the register was written + and the rest are followed again ([`extend`](#6-verbs)); if a later one, + memory changed under a pointer that did not, and the tick sits before + that hop alone. +- No lines to targets. Thirty chains would be a net; a chain is tied to + its target by ink, by digits, and by the target's pin. -One row a chain, read left to right: *this, which points to that, which -holds this.* +### reg -- **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).) +A name (dim) 12 in; its chain from 72; room to 12 from the edge. -### What a value shows as (rev 2) +`rip`: gold plaque on the name, ember across, the address in code's ink +and its name. Never struck. Its row carries **flags** at the right end: +eight names on a pitch of 42. Set: upper case on a chip. Clear: lower +case, dim. Changed: a tick. (The value `0x206` is not drawn: the names are +the value.) -The tracer classifies; this is how each class is set. +### slot -| It is | Because | Shown | +A lane 112 wide for a `row` pin; the chain from 122, beginning with the +slot's own address in stack ink with `lead`; room to 136 from the right +edge, which belongs to the [`call`](#call) spans. + +### insn + +An instruction, pwndbg's way: what it is, and what its operands are now. + +| x | Column | | | --- | --- | --- | -| 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 | +| 2 | mark | a gold plaque 24 wide (current) or a trail bar 4 wide (ran) | +| 31 | jump lane | a 2-unit line in trail gold from a jump that was taken to the row it landed on, head 7 by 8 | +| 40 | address | code ink, `lead` | +| 134 | line | the source line this run of instructions came from, ranged right in three characters, faint; on the first row of each run only; gold and bold for the current line | +| 180 | mnemonic | keyword, bold | +| 264 | operands | as the disassembler writes them, 24 characters; a jump's or call's target is an `address` in code ink | +| 564 | annotation | 25 characters; cut at its far end | -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. +| State | Draws | +| --- | --- | +| `current` | plaque, ember across; annotation in full ink | +| `ran` | trail bar, newest of three brightest; keeps the annotation of what it did | +| `ahead` | plain; only static annotation (a callee's name) | +| `outside` | past the function's end: a rule above the row, everything faint, the next symbol's name in the annotation column | -### Disassembly +**The annotation**, by what the instruction does: -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. +| It | Annotation | +| --- | --- | +| reads memory | a chain from the address it computes: `28b41098 → 28b41070 ◂ 9`. Before the step, where it will look; in the step its first hop is `read` | +| writes memory | the same chain; the value after `holds` is `struck` | +| only sets a register | a small `reg`: `rax 28b41090 ◂ 4` | +| jumps on a condition | `taken` in primary, or `not taken` in dim; taken, and its target is in the window: the line in the jump lane; outside it: `taken → 1001935 reverse+37` | +| calls | the callee's name, bright; its arguments hang under it in the annotation column, a small `reg` a row (`rdi …`, `rsi …`), as many as the prototype has, three when there is none. The rows they cover are ahead and have nothing there | +| returns | `→ 10018b0 main+80` | +| makes a system call | its name and arguments by name, as a call; the kernel's rows hang under it on vellum | -- 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`). +Mocks 9 to 11 show the read, the register-setter, the taken jump and +`outside`. Call, return, write and syscall annotations are not drawn. -### Stack +### line -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`. +The number ranged right in three characters, faint; the text from 64, in +the four code inks; 67 characters, then a faint `…`. `current`: gold +plaque on the number, ember across. `trail`: the bar, for the last three +other lines run. -### Backtrace +### bytes -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. +A hexdump row. Its runs come from the types of what the program's +pointers reach. -### Source +| x | Column | | +| --- | --- | --- | +| 7 | bracket | `quiet`, on a row that holds a drawn thing; `tie` when a projection ends here | +| 18 | address | region ink, `lead`; at 60% on a row that holds no drawn thing | +| 132 | sixteen `byte`s | on a pitch of 30, 12 more after the eighth | +| 640 | reading | what the runs read as, little-endian: a number ranged right in three characters; a pointer as `points` and its `address`; `NULL` dim; an allocator's run as a note in Go 18, faint | -The 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 `…`. +The reading replaces a hexdump's text column: where bytes are text the +reading is the text, in quotes; where they are a pointer it is the address, +so a little-endian pointer is read without leaving the dump. -- 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. +Marks are per run: `struck` (the paper solid vermilion, digits bold in +ink), `read` (a 2-unit frame 3 out), `held` (a tick in the gap at the +run's left). A struct wider than a row spans rows, and its bracket spans +them. -## The lens (rev 2) +### call -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. +One frame of the call chain, in two forms. -- 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. +- `span`, on the stack: a bracket 14 in from the panel's right edge down + the slots that are the frame, and the function's name left of it, Go + Medium 18. `newest`: gold bracket, bright name. Older: rule and dim. A + frame that runs past the panel's last slot has no bottom serif. +- `row`, in a backtrace panel: `#n` (a gold plaque on the newest), the + name and offset in primary at 60, file and line in dim at 276. -The forms themselves are as the first pass drew them, in mocks 1 to 8: +## 3. Panels -| 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 | +A panel is a tag and rows. Its rows never reorder and none is hidden to +make room. + +### registers + +Seventeen `reg`s in pwndbg's order: rax rbx rcx rdx rsi rdi rbp rsp, r8 +to r15, rip (with the flags). Tag: the region legend. 440 high. Reads the +moment's registers and mappings. + +### stack + +`slot`s from rsp, low addresses on top: eight; four when the lens is the +subject. `call` spans down its right edge: the backtrace, drawn on the +words that are each frame. rsp and rbp are pins in its lane. Reads the +stack words, and each frame's extent (the frame-pointer chain, or the +unwinder's CFA). + +### backtrace + +`call` rows, newest on top, four and then a count. A panel of its own only +in the `none` split, where there is room under the stack; in the others +the stack's spans carry it. + +### source -Those eight frames were drawn as whole frames; each is now what its lens -looks like with the camera on it. They have been redrawn in the new face -and with pointers in their regions' inks, and are otherwise the first -pass's. +A window on the whole file, scrolled by whole lines to keep the current +line in its middle third. Fourteen lines; eight beside a lens (the loop +in hand); ten when the lens is the subject. Tag: the file, and `lines 19 +to 26 of 42`. -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. +### disasm -## Directing the eye in a full picture (rev 2) +Seventeen `insn`s in address order: the pc's, eight above, eight below. +Eleven (five, the pc, five) when the lens is the subject. -Everything is on screen, so nothing is found by being alone. In order of -how often they are used: +- Rows above the pc are the function's own instructions. Near its start + there are fewer, and the pc's row sits higher; the window stays full + from below. +- Past the function's end the rows are `outside`. +- The rows that ran in the last three steps are `ran`, above or below the + pc: with the jump lane they show how control came here. +- Tag: the function's name. -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: +### lenses -| Scale | Mono 20 becomes | Frames | For | +A lens is the band across the top of the stage: **a drawing, and beside +it the pane the drawing is a view of.** + +| Lens | Drawing | Is a view of | Mock | | --- | --- | --- | --- | -| 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 | +| `nodes` | boxes of a value and a pointer, arrows between them | a `hexdump` of the nodes' bytes, right half of the band | 9 to 11; 2 at camera scale | +| `array` | cells, index tags, flights for a swap | a `hexdump` of the array's bytes, an element a run | 7 at camera scale | +| `heap` | the heap to scale: chunks, bins | a `hexdump` of the chunk in hand | 4 at camera scale | +| `calls` | a call tree, results on the shoulder | the `stack` panel: each node is a `call` span. The drawing has the band's whole width | 1 at camera scale | +| `syscalls` | the crossing: vellum, the call decoded | the `registers` that carried it, by `echo`. Whole width | 3 at camera scale | +| `pages` | the far view: pages, system calls over time | the mappings. Whole width | 8 | +| `hexdump` alone | bytes and their text | itself | 5, in its first-pass form | + +**What a new lens must provide** to fit the frame: + +1. A drawing that fits 856 by 116 (`beside`) and by 212 (`subject`), or + twice the width where it is a view of the stack or the registers. +2. The pane it is a view of, and for every element the bytes, slot or + register it is drawn from. +3. A `place` for every element, so ties can land. A 12-unit lane clear at + the top of the drawing and one at the bottom: **bytes arrive from + above, pointers from below.** +4. Each mark on its cells: `current`, `armed`, `struck`, `held`, `read`. +5. Its `establish`: how its elements rise from what they are drawn from. + +### nodes + +Boxes of 116 by 44, 28 apart: six fit the band's half (124 by 72, 22 +apart, as subject). The +value's half is raised, the number in mono 25 (45); the pointer's half, +48 wide, is the well, with a 10-unit square the arrow leaves from. Arrows +3 wide in the ink of the region pointed into, head 12 by 10; null is a +dim slash. **Above** each node its address, in its region's ink: the same +digits as its row in the dump. **Under** it, its pins. Marks on a half: +`read` frames it, `held` is the bar along its bottom edge. + +### hexdump + +`bytes` rows, sixteen a row, a window of the region kept round the rows +the step touches: five beside, nine as subject. Rows in address order; a gap in the +addresses is one row holding `more`'s three dots and the count of rows +left out. Tag (the band's +right half): `its bytes`, the range shown, and the legend of runs: each +field's name in its bytes' ink, `malloc's`, `never read`. + +## 4. Ties + +The panes are one machine at different levels. A tie says which thing in +one pane a thing in another is. + +| Tie | Says | Between | When | Form | +| --- | --- | --- | --- | --- | +| `thread` | this line is these instructions, and the machine is here | the source's current line; every run of its instructions in the disassembly | standing; moves with the current mark | gold, 3 units: a `tie` bracket on the line, one on each run, a line in the left margin (x 54) between them | +| `link` | this register now points at that | the `reg` just struck; the row or node whose address it holds | for the step that set it | 3 units, in the ink of the region pointed into, head on the target; ends in the target's `pin` and leaves it behind | +| `projection` | these bytes are that part of the drawing | a run a step read or wrote, in the dump; the part of the drawing made of them | for that step | 2 units in the mark's colour (read, write): a `tie` bracket on the row, a line, a bracket over the node's address; and the mark itself on the run and on the part | +| `echo` | these are one event | the same mark at the same instant in two panels: the annotation's address and the dump's run | for that step | no line | +| ink, digits | these are one thing | an address anywhere and its row, node or name | always | no line | -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. +`call` spans and `pin`s are ties too, the kind that need no line because +they sit on their target. -**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. +**Budget.** One `thread`, always. For a step, one `link` and one +`projection`. Never more than three drawn lines in the frame; a second +pointer or a second run in the same step gets `echo` and pins. -## Motion +**Routes.** A tie runs only in channels, with corners of radius 8 (6 for a +projection): -[`motion.md`](motion.md) is the direction. What density changes in it: +| Channel | Carries | +| --- | --- | +| the left margin, x 54 | the thread | +| the gutter's left lane, x 950 | a link, coming up from the registers | +| the gutter's right lane, x 962 | a projection, from the dump | +| a lens's bottom lane, 8 above its edge | a link, to the pin under its node | +| a lens's top lane, 4 under its tag | a projection, to the bracket over its node's address | + +A link stays below a lens's nodes and a projection above them, and each +has its own lane in the gutter, so the two cannot cross. A tie may cross +a panel's rule; it never crosses a letter, a digit or another tie. + +**Order.** A tie arrives before the thing it points to reacts: see +[`link` and `project`](#6-verbs). Mock 9 shows the standing ties; 10 and +11 all four. -- 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. +## 5. The frame -## Legibility rules (rev 2) +| Band | y | | +| --- | --- | --- | +| margin | 0 to 48 | page | +| stage | 48 to 888 | 840: the lens band and the two columns | +| clock | 898 to 902 | | +| caption | 912 to 1032 | | +| margin | 1032 to 1080 | page | -- 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. +No data below 888: a player's controls cover it. + +**The program column** (left): source over disassembly: what was written, +what runs. **The state column** (right): registers over stack: what they +act on. **The lens band** (top, both columns): what it means, and the +bytes that mean it. The split is the one thing about the layout a scene +chooses. + +| Split | Band | Source | Disassembly | Registers | Stack | Backtrace | +| --- | --- | --- | --- | --- | --- | --- | +| `none` | | 14 lines, 48 to 416 | 17, 428 to 868 | 48 to 488 | 8, 500 to 724 | 4, 736 to 864 | +| `beside` | 152, 48 to 200; dump of 5 | 8 lines, 212 to 436 | 17, 448 to 888 | 212 to 652 | 8, 664 to 888 | in the stack | +| `subject` | 248, 48 to 296; dump of 9 | 10 lines, 308 to 580 | 11, 592 to 888 | 308 to 748 | 4, 760 to 888 | in the stack | + +**What gave** for seventeen instructions: a lens, the whole of a function +and seventeen instructions do not fit one column of 840. So the lens left +the program column for a band of its own; the backtrace became spans on +the stack; the flags moved into rip's row; a panel's padding went from 6 +to 4; and beside a lens the source shows eight lines. As the subject the +lens takes six rows from the disassembly and four slots from the stack. + +| Of the frame | `none` | `beside` | `subject` | +| --- | --- | --- | --- | +| context | 68% | 56% | 48% | +| lens band (drawing and bytes, half each) | | 13% | 21% | +| caption band | 10% | 10% | 10% | + +### clock and caption + +- **`clock`**: a 2-unit rule the width of the stage at y 900; gold, 4 + high, along it as far as the recording has run; `moment 72 of 95` in + mono 20, faint, under its right end. +- **`caption`**: one or two lines, Go 40 on 54, ranged left on the + margin; code in it is mono 35. Hex in it is unbroken too. +- **`veil`**: the page at 50% over the panels a named beat does not + touch; at 65% under the camera. +- **`card`**: a title or the legend ([mock 6](mock/06-title-legend.png)). + The only frames with no context. +- **Camera rests**: x1 (the frame), x1.5 (1195 by 560: a column, or the + band), x2 (896 by 420: sixteen rows), x4 (448 by 210: one chain). It is + for reading, and always comes back. + +## 6. Verbs + +Frames at 60 a second. `s` is the frame a strike lands. Curves: +`standard` (0.3, 0, 0.2, 1) for things arriving; `glide` (0.45, 0, 0.55, +1) for things travelling and cooling. Charts: [`motion.md`](motion.md). + +| Verb | On | Chart | +| --- | --- | --- | +| `fire` | the current plaque | 0 to 12: it pulses once. Nothing else moves | +| `arm` | a value about to be written | s-12 to s: the `armed` frame, in over 2 f; the old value still in it | +| `strike` | a value written | s to s+6 the fill comes in, linear; the new digits at s+3; s to s+12 its edges go out 3 units (4 in a lens's cell) and back, sine; solid to s+36 | +| `cool` | a struck value | s+36 to s+60, `glide`: in the context to nothing, leaving `held` for three steps (then out over 36 f); in a lens's cell to its bar | +| `read` | a value read | in over 6 f; held to the advance; out over 18 f. No arm, no pulse | +| `extend` | a chain whose first hop was struck | each later hop is followed again, 4 f apart, fading in over 6 f | +| `link` | a `reg` just struck, and its target | s+6: the old pin fades (12 f) and the line draws from the register's row, head first, 24 f (36 f over 400 units), `standard`; the pin lands with the head and settles (12 f); held; at the advance the line draws back into the pin over 18 f | +| `project` | a run read or struck, and its part of the drawing | on the run's mark: the bracket on the row (6 f), the line draws from the bytes to the drawing (18 f, `standard`); only when it arrives does the part react (its own `read`, or `arm` and `strike`); out with the advance, 18 f | +| `travel` | a value or a tag going from one place to another | 30 f to 200 units, 36 f to 400, 48 f beyond; `glide` | +| `advance` | the current marks | last. The thread, the plaques and rip move together: 12 f to an adjacent row, 24 f up to eight rows, `standard`; farther, out and in over 6 f. A taken jump's line draws in the jump lane with it | +| `cascade` | a step | `fire` (12); then its effects a level at a time, 18 f apart: CPU (`reg`s, the pc's annotation), memory (`slot`s, `bytes`), the idea (the drawing, by `project`); each armed, then struck; hold 36 f after the last strike and 12 f a further value, 84 at most; `advance`; rest 24 f | +| `run` | steps that need not be read | 18 f a step, no arm, marks jump; 24 steps at most | +| `sprint` | steps to be got through | 4 f a step: only the current marks and the clock move. Each change of pace ramps at 0.6 of the step before | +| `establish` | a scene's opening | the state column, then the program column, then the band: 60 f and 30 f a panel. A lens's dump first; then each element rises from its row by `project`, 6 f apart in address order, and the lines go, leaving the quiet brackets | +| `scroll` | a `source` or `disasm` window | whole rows, 24 f, `glide`; marks ride with their rows | +| `relayout` | a change of split | 48 f, `glide`; nothing else moves under it | +| `visit` | the camera | the target framed first (24 f), the rest veiled (18 f); the move 72 f, `glide`; 120 f at most without a change; back | +| `say` | the caption | out 12 f, gap 6 f, in 18 f; it leads what it describes by 60 f, 120 f at a scene's first | + +A step is as long as its content: 0.8 s when only the line moves, 1.5 s +for one register, 2.0 s for a register and memory, 2.5 s across three +levels. + +## Composition + +**What may contain what.** + +- The stage holds the band and two columns. A column holds panels. A + panel holds a tag and rows, or (a lens) a tag and a drawing. A row + holds atoms. Nothing nests deeper. +- A mark sits on an atom or a row, never on a panel. A panel's only + states are `focus` and veiled. +- A tie sits over panels, in channels. It joins `place`s that blocks + publish (`reg`, `slot`, a word, a node, the line, the pc); it never + reads a panel's layout. +- A panel is `32 + 24 n` high. Panels do not overlap and are 12 apart. + +**Adding a block.** + +1. Name it: one word, a noun, not in the vocabulary. +2. Compose it from the layers above. If it needs a new atom, add the atom + first, on its own. +3. Give its states as `mark` states. A new state needs a new form, not a + new colour. +4. Publish its `place`s. +5. Give its motion in the verbs. A new verb only when no sequence of the + existing ones says it. +6. Draw it in the gallery in every state, at x1 and at 480 wide. +7. Add its row to the vocabulary and to the mocks table. + +**Forbidden.** + +- Information carried by hue alone. Every ink has a second sign (a name, + quotes, a position, a paper) except heap against data, which is + admitted above. +- A mark under coloured digits, except a strike for its 0.6 s and the + gold ember of a current row. +- A tie across text, or across another tie. More than three drawn ties. +- Two strikes landing in the same frame. Two writes of one step are 6 f + apart, in the order they happened. +- An effect before its cause: a drawing changing before its bytes, a + current mark moving before the hold. +- A space inside a number. A row that wraps. Rows that reorder. +- Anything hidden to make room: a row that cannot hold its chain ends in + `more`, a panel that cannot hold its rows ends in a count. +- Mono under 20, sans under 18. Lines under 2 units. Dashes finer than 12 + on 8 off. +- Alpha tints (but the veil), gradients, glow, grain, rounded panels. +- Solid vellum for anything but the kernel. Gold for anything but where + execution is. ## The mocks -`mock/gen.py` draws 1 to 8 and `mock/context.py` 9 to 11; resvg renders -them; each has a `-480.png` beside it. +`mock/context.py` draws 9 to 11, one function a block under the block's +name; `mock/gen.py` draws 1 to 8. Each has a `-480.png` beside it. + +```sh +cd design/mock +python3 context.py && for n in 09-context 10-context-step 11-context-lens; do + resvg $n.svg $n.png && resvg -w 480 $n.svg $n-480.png; done +python3 gen.py # 1 to 8, then resvg the same way +``` -| | Shows | After looking | +| Mock | Is | Blocks it shows | | --- | --- | --- | -| [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 | +| [9](mock/09-context.png) | `beside`, at rest: moment 71 of `targets/list`, stopped at `mov rdi, [rdi + 8]` | every panel; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot`, `pin` row; `call` spans; `insn` current, ran, ahead, outside, with the jump lane; `line`; `bytes` with number, pointer, allocator, unread and `pad`; `nodes` with pins under; `thread`; marks current, held, trail | +| [10](mock/10-context-step.png) | the same, mid-step | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection` | +| [11](mock/11-context-lens.png) | `subject` | the band at 248, the drawing a size up, a dump of nine, eleven instructions, four slots | +| [1](mock/01-fib-recursion.png) | first pass | `calls` at camera scale | +| [2](mock/02-list-insert.png) | first pass | `nodes` at camera scale; `allocated` | +| [3](mock/03-syscall-write.png) | first pass | `syscalls`; `kernel` | +| [4](mock/04-malloc-glibc-musl.png) | first pass | `heap`; `freed` | +| [5](mock/05-memory-write.png) | first pass | a byte grid: the old form of `hexdump`; `struck` and `held` in cells | +| [6](mock/06-title-legend.png) | | `card`, the legend | +| [7](mock/07-sort-swap.png) | first pass | `array`; `travel` | +| [8](mock/08-far-view.png) | first pass | `pages` | + +Mocks 1 to 8 were drawn as whole frames before the context existed. Each +is now what its lens looks like under the camera; none shows its lens in +the band. + +**Specified, not drawn.** + +- The `none` split, and the `backtrace` panel with `call` rows. +- `insn` annotations for a call with its arguments, a return, a memory + write, a system call, `not taken`, a jump out of the window. +- `value` classes other than digit, small number and string. +- `armed`, `fault`, `attention` and the veil in the context. +- A `projection` for a write (vermilion). A `link` to a `slot`. +- A struct wider than one `bytes` row; a gap in a dump; text in a dump. +- `array`, `heap`, `calls`, `syscalls`, `pages` in the band. +- `pin` with a count; `rwx`. +- Every verb: the mocks are stills. `establish`, `link` and `project` + have no chart from a render yet. -The data in 9 to 11 is the recording's: 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. +**The data in 9 to 11** is the recording's: registers, chains, stack, the +instructions and their lines. The frames' extents are read off the +frame-pointer chain. The dump's node bytes are what the chains and the +program say the heap holds; its allocator rows are glibc's layout, with +the word nothing reads drawn as never read. A recording made under ptrace +has seen neither. -**At 480 wide** ([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. +**At 480 wide** no digit of the context reads. What is left: the layout, +the gold rows and the thread, the strike on `rdi` and its link into the +band, yellow and blue as texture, the caption whole. Through x264 at 720p +(CRF 28) mock 10's dump, its faint padding bytes, its dots and the chains +still read. -## What this asks of the renderer (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. +1. **Faces.** JetBrains Mono NL in four and Go in three; `theme.font.mono` + is still Go Mono. +2. **Places.** `ties.Place` has register, word, node, source and pc. The + thread needs every run of the current line's instructions, not the pc + alone; a projection needs a run of bytes in the dump and a *part* of a + node (its value, its pointer half); a link needs the pin's place. +3. **From the recording**: + - the line of each instruction in the window, for the `line` column + and the thread; + - which instructions ran between two stops, for `ran` rows when + stepping by line (or a recording by instruction); + - each frame's extent on the stack, for `call` spans; + - the bytes of a lens's region at each stop, so that allocator rows + are read and not guessed; without it they are `unread`, honestly; + - a callee's prototype, for the number of arguments under a call. +4. **Runs.** Mock 10 is 351 runs of text, 174 rects and 63 paths. An + address is one run now (two with `lead`). +5. A camera rest at 1.5, with text shaped for mono 30 there. 6. Still open from the first pass: dashed strokes from `sk.draw`. ## Token changes -For `anim/src/theme.zig`. Nothing in `time` changes but the two additions -at the end. +For `anim/src/theme.zig` as it stood when this was written. "Was" is what +is in the file. | 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 | +| `font.mono`, `mono_bold`, `mono_italic` | Go Mono | JetBrains Mono NL Regular, Bold, Italic | +| `font.mono_medium` | | `JetBrainsMonoNL-Medium.ttf`: all mono under 30 | +| `metric.context.pad` | 6 | 4 | +| `metric.context.group_gap` | 6 | removed: hex is unbroken | +| `metric.context.lead_alpha` | | 0.6: the shared digits of a column of addresses | +| `metric.context.pad_alpha` | | 0.45: a word's padding bytes in a dump | +| `layout.registers` | 18 rows | 17: the flags are in rip's row | +| `layout.stack` | 8 | 8; 4 in `subject` | +| `layout.backtrace` | 3, always | 4, in `none` only | +| `layout.band` | | y 48, full width: 152 `beside`, 248 `subject` | +| `layout.split.none` | source 14, disasm 17 | the same; registers, stack 8, backtrace 4 beside them | +| `layout.split.beside` | lens 312 in the program column, source 8, disasm 10 | band 152; source 8, disasm 17; registers, stack 8 | +| `layout.split.subject` | lens 432, source 5, disasm 8 | band 248; source 10, disasm 11; registers, stack 4 | +| `layout.dump_rows` | | 5 `beside`, 9 `subject` | +| `metric.insn` | | columns at 2, 31, 40, 134, 180, 264, 564; operands 24 characters, annotation 25 | +| `metric.bytes` | | bracket 7, address 18, bytes from 132 on a pitch of 30 with 12 after the eighth, reading 640 | +| `metric.slot` | | pin lane 10 to 112, chain 122, room to 136 from the right | +| `metric.table.flag` | 60 by 36 | chip 32 by 20, pitch 42, ranged right in rip's row | +| `metric.pin` | | `row`: head 9 by 12, 5 after the names; `under`: stub 3 wide, the mono size and 10 long, head 10 by 10, names 9 either side | +| `metric.bracket` | | `quiet` 2 and 5; `tie` 3 and 6 (thread 7) | +| `metric.plaque` | 40 high, pad 12 | gold only: 54 (rip), 50 (a line number), 24 (the pc) wide, the row high | +| `metric.node` | 180 by 72, pointer 72 | 116 by 44, 28 apart; 124 by 72, 22 apart as subject; pointer half 48; origin 10 | +| `metric.lens.lane` | | 4 under the tag (projections); 8 above the bottom edge (links) | +| `metric.tie.thread_x` | | 54 | +| `metric.tie.lanes` | | 950 (link), 962 (projection) | +| `metric.tie.radius` | | 8; 6 for a projection | +| `stroke.tie` | | thread 3, link 3, projection 2 | +| `color.well` | | `101a48` | +| `Role.pointer` | orchid frame and arrow | removed. `Role.link`: region ink, 3 wide | +| `mark(.write)` held | ember and a 6-unit bar | in the context a tick, 4 wide; in a lens's cell a bar, 4 high | +| `color.veil_alpha` | 0.65 | 0.50 for a beat; 0.65 under the camera | | `metric.max_rows` | 10 | removed: nothing is hidden | -| `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 | +| `time.link` | draw 0.40, go 0.30 | draw 0.40 (0.60 over 400 units), settle 0.20, back 0.30 | +| `time.project` | | bracket 0.10, draw 0.30, out 0.30 | +| `time.establish_rise` | | 0.10 between a lens's elements | +| `size.mono.value` | 35 | 35 in a caption; a subject lens's values are `flight`, 45 | -## Implementation order (rev 2) +Unchanged and already there: the palette, region inks, `time.cascade`, +`strike`, `read`, `unroll`, `run`, `sprint`, `ramp`, the camera's scales. -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. +## Building it -Shader effects worth having: still none. +1. Atoms: `address` (unbroken, `lead`), `arrow`, `value`, `mark`, `pin`, + `bracket`. The gallery starts here. +2. `chain`, then `reg` and `slot`: the state column at rest. +3. `insn` with its columns and annotations; `line`; `thread`. +4. `bytes` and `hexdump`; `nodes` in the band; quiet brackets. +5. `strike`, `cool`, `read`, `extend` at density; the `cascade`. +6. `link` and `pin`; `project`; `echo`. +7. `call` spans; the three splits and `relayout`; the camera at x1.5. +8. The other lenses in the band. Export: |
