summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md1224
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:
+![the frame, mid-step](mock/10-context-step.png)
-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.
-![the context](mock/09-context.png)
+## 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: