summaryrefslogtreecommitdiff
path: root/design/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 22:50:34 -0300
committerGabriel Schneider <[email protected]>2026-11-10 22:51:17 -0300
commitfa5d150ac6977264f0704e9af664f8150bd25127 (patch)
treef18b56f22ef696208754097c9a13875b0a8b92e6 /design/README.md
parent7ebd23e8a5f4634981aa162905a3c4297b835d91 (diff)
downloadcomputeranim-fa5d150ac6977264f0704e9af664f8150bd25127.tar.gz
computeranim-fa5d150ac6977264f0704e9af664f8150bd25127.zip
design: arc, a pointer to a row of its own panel is drawn
From the user, on the loupe's mock: a pointer in memory named a row two above it and nothing showed it. In a dump, a loupe and the stack a pointer whose target is a row of the same panel is an arc in a lane at the panel's edge, as a jump is in the disassembly: quiet while it stands, full ink in the step that writes or reads it, a stub when the target is just off the window. A chain shares a lane. A loupe carries the arcs among its own rows; the stack's frame chain gets one only when touched. Co-Authored-By: Claude Fable 5.2 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa
Diffstat (limited to 'design/README.md')
-rw-r--r--design/README.md84
1 files changed, 72 insertions, 12 deletions
diff --git a/design/README.md b/design/README.md
index 02d5960..a6cc6dd 100644
--- a/design/README.md
+++ b/design/README.md
@@ -62,6 +62,7 @@ this table.
| | [`line`](#line) | a line of source | `current`, `trail`; wide numbers |
| | [`bytes`](#bytes) | sixteen bytes of a dump and what they read as | field runs, marks per run; wide address |
| | [`call`](#call) | one frame of the call chain | `row`, `span`; `newest` |
+| | [`arc`](#arc) | a pointer to a row of the same panel, drawn | standing, `touched`; a stub |
| 3 panel | [`registers`](#registers) | all seventeen | |
| | [`stack`](#stack) | a window on the newest frame's words, and the frames they belong to | 8 or 6 slots |
| | [`backtrace`](#backtrace) | the call chain as rows | in the `none` split; the view of `calls`; a lens's drawing |
@@ -387,7 +388,8 @@ A word of the stack, pwndbg's way and a little more.
| x | Column | |
| --- | --- | --- |
-| 10 | pins | the `row` pin's lane, to 112: every register whose value is this word's address |
+| 4, 10 | arcs | the [`arc`](#arc) lanes: a word holding the address of another slot in the window |
+| 16 | pins | the `row` pin's lane, to 112: every register whose value is this word's address |
| 172 | offset | from rsp, hex, `+18`, faint, ranged right in four characters (`-8` above rsp) |
| 184 | address | stack ink, `lead`; then the chain, its first hop the word's content |
| right | role | what the word is, where the recording knows it, ranged right where the chain's room ends: `saved rbp`, `saved rbx` (dim); a local's name (primary); at the process's start `argc`, `argv[0]`, `argv end`, `envp end`, `auxv` (dim) |
@@ -477,15 +479,16 @@ bytes and a pointer 8, never two fields and never a store's width.
| 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 |
+| 4, 10, 16 | arcs | the [`arc`](#arc) lanes: pointers to rows of the same dump |
+| 24 | bracket | `quiet`, on a row that holds a drawn thing; `tie` when a projection ends here |
+| 34 | 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, left to right, a character apart: a number in decimal (in its byte order); a pointer as `points` and its `address`, `NULL` dim; text in quotes, C's escapes, in a string's ink; a run left to the eye, or `loose`, as nothing; the chunk's size word before an allocation as a note in Go 18, faint (`malloc's: a chunk of 32`). Cut at the panel's edge with a faint `…` |
**Wide address.** The bytes begin 12 after the address ends, and at 132
-at least: an address of up to eight digits leaves them at 132; the stack's
-twelve put them at 174, and the reading at 682 (508 after the first
-byte, as always). A dump sets this once, by the widest address in its
+at least: an address of up to seven digits leaves them at 132; the stack's
+twelve put them at 190, and the reading at 698 (508 after the first byte,
+as always). A dump sets this once, by the widest address in its
window, so its rows keep one column.
The reading replaces a hexdump's text column: where bytes are text the
@@ -522,6 +525,55 @@ One frame of the call chain, in two forms.
(`n=4`, primary), file and line ranged right, dim. Arguments where the
debug info gives them.
+### arc
+
+A pointer whose target is a row of the same panel is drawn, not only read:
+an arc from the pointer's row to the row it names, in lanes at the
+panel's left edge. It is the disassembly's jump lane given to data, in
+every panel of rows that holds pointers: a dump (the band's view,
+`memory`), a [`loupe`](#loupe), the stack.
+
+| Part | Drawn |
+| --- | --- |
+| lanes | a dump and a loupe: three, at 4, 10 and 16 from the panel's left edge (the quiet bracket moves to 24, the address to 34, the bytes 12 after it, 132 at least). The stack: two, at 4 and 10 (the pins start at 16) |
+| arc | 2 units, corners of radius 4, in the ink of the region pointed into: out of the pointer's row at its left (x 21), along its lane, into the target's row at its left, head 7 by 8 at x 22, before the bracket and the address. Going up it leaves its row 9 down and arrives 15 down (going down, 15 and 9), so a chain of pointers (1004090 → 1004070 → 1004050) runs in one lane without touching |
+| ink | standing: 60% toward the page. Full: in the step that writes or reads the pointer, and always in a loupe, which was opened to show them |
+| a target mid-row | the head on its row; the `read` or strike on the target's own bytes says which |
+
+**Nesting.** Overlapping spans take separate lanes, the longest outermost;
+spans that do not overlap share one. Nested arcs never cross; interleaved
+ones cross once, as jump arrows do. Three lanes (two in the stack) is the
+most a panel holds before it is noise: past them the arcs of the step come
+first, then the shorter; the rest are only read, and nothing is hidden,
+since every pointer's reading names its target.
+
+**Out of the window.** A pointer whose target row is in the same region
+but not shown: in the step that writes or reads it, a stub along its lane
+to the panel's rule, head on the rule; otherwise nothing. No count, unlike
+a link's stub: the lane has no room for one, the reading names the
+address, and the minimap shows where.
+
+**Which form carries a pointer**, when more than one could:
+
+- **In a panel**, between its own rows: the arc. The stack's frame chain
+ (a saved rbp) is the exception: the `call` spans already draw the frames
+ it makes, so its arc is drawn only in a step that writes or reads it.
+- **A loupe** carries the arcs among its own rows; a dump showing the same
+ rows withholds them while it is open (one place, the one opened for it).
+ A loupe's stem already ties the pointer it opened from; a loupe never
+ opens for a target its own rows hold.
+- **The lens's drawing** draws the same pointer as its arrow (a node's
+ `next`); the view's arc is that pointer's bytes. Both stand: they are
+ the idea and the machine, tied by ink and digits, and a step that turns
+ the pointer turns the arc at the memory level and the arrow at the idea's.
+- **A flat chain** (a register's, a stack word's) whose hop lands on a row
+ of another panel: its `pin` where that panel has a pin lane (the stack,
+ a node); otherwise ink and digits. In the step that sets it, a `link`.
+ No standing line across panels: an echo of the target's row whenever the
+ pointer's row is current would flicker on every step.
+
+Its motion is under [`arc`'s verbs](#6-verbs). Mocks 9 to 11, 19, 21.
+
## 3. Panels
A panel is a tag and rows. Its rows never reorder and none is hidden to
@@ -1058,6 +1110,7 @@ Frames at 60 a second. `s` is the frame a strike lands. Curves:
| `dive` | from the map to the working frame | one continuous move in which the windows become the panels and the map becomes the minimap. 0 to 6: the windows' outlines go bright. 6 to 24: the rest of the map takes the veil (50%). 24 to 96, `glide`: each window goes from its place on the map to its panel's place, its scale on a logarithm from the map's (half, filling the frame) to the frame's (whole), so its rows grow from 10 units to 20 under the eye, the panels 6 f apart in the frame's reading order (drawing, view, source, registers, disassembly, stack), each drawn over those before; the map, veiled, goes the same 72 f to the minimap's place, its scale from a half to a twentieth, so the windows rise out of it as it falls away; their outlines stay on it and land as the minimap's windows. 72 to 96: the drawing, whose sizes differ between the two, crossfades from the map's to the frame's within its box. 84 to 96: the frame's tags, rules and lanes fade in; the veil on the map lifts as it lands. 96 to 132: still |
| `surface` | from the working frame to the map | the dive backwards, a little quicker: 0 to 12 the tags, rules and lanes fade out; 12 to 84, `glide`, the panels shrink into their windows as the minimap grows to fill the frame; 84 to 96 its veil lifts; then the map is still 36 f before anything plays on it |
| `flash` | the minimap, at a mark no window shows | a ring 8 across in the mark's colour draws out to 14 and is gone, 12 f, with the mark's own strike or read |
+| `arc` | a pointer to a row of its panel | written: with the arm (s−12) the old arc goes dashed; from s+6 it fades (12 f) while the new one draws from the pointer's row along its lane to the target, head first, 12 f, `standard`, at full ink; with the cool at the advance it quiets to standing (24 f). Read: to full ink with the read (6 f), back with the advance. Overwritten with a target off the panel or NULL: it fades from s+6 (12 f). A lane change glides 12 f. Scrolled: it rides its rows, fading as its target leaves. At a run 8 f, at a sprint none |
| `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. A level with nothing on screen to change gives up its slot |
| `continue` | a stop far from the last: a breakpoint, not a step. Where the windows' new places are farther than their own heights (another function, another file), it is told on the map: `surface`, the jump there, `dive` | `fire` on the line it leaves from; then the levels as in a `cascade`, but CPU is a wave: every register that changed is struck 2 f after the one above it, in pwndbg's order, the fill in over 6 f, no arm and no pulse (a dozen pulses at once are a flash, and a dozen arms a crowd); memory: the stack's window scrolls or fades to its new place, and the [backtrace](#backtrace)'s frames leave, slide and arrive; the idea; hold 36 f after the last strike; `advance`, the source and disassembly fading through if far; rest. Its marks are only on what was on screen to change |
@@ -1154,16 +1207,16 @@ python3 -B gen.py # 1 to 8, then resvg the same way
| Mock | Is | Blocks it shows |
| --- | --- | --- |
-| [9](mock/09-context.png) | `beside`, at rest: `targets/list` stopped at the load in `reverse` (`mock/list-dbg.txt`, moment 2) | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot` with offsets and roles, `pin` row; `call` spans; `insn` current, ahead, outside under a rule and its name; `line`; `bytes` by fields with number, pointer, loose; `nodes` with pins under, two names on one; `thread`; marks current, held; the minimap, its windows |
-| [10](mock/10-context-step.png) | the same, mid-step: the load done (moment 3) | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection`; the minimap |
+| [9](mock/09-context.png) | `beside`, at rest: `targets/list` stopped at the load in `reverse` (`mock/list-dbg.txt`, moment 2) | every panel; the band as two panels; `address` with `lead`; `chain` cut by `more`; `reg`, rip with flags; `slot` with offsets and roles, `pin` row; `call` spans; `insn` current, ahead, outside under a rule and its name; `line`; `bytes` by fields with number, pointer, loose; an `arc` standing in the view; `nodes` with pins under, two names on one; `thread`; marks current, held; the minimap, its windows |
+| [10](mock/10-context-step.png) | the same, mid-step: the load done (moment 3) | `struck` on rdi; `read` on the annotation, the run and the node's half (`echo`); `link` ending in rdi's pin; `projection`; the read pointer's `arc` at full ink; the minimap |
| [11](mock/11-context-lens.png) | `subject`, mid-step | the band at 296 and 200, the drawing a size up, a dump of seven, nine instructions, six slots; the minimap with the subject's windows |
| [12](mock/12-calls-subject.png) | `calls` as subject, mid-step: moments 752 to 753 of the fib scene, `fib(4)` calling `fib(2)` | `calls`: nodes current, waiting, done, the caller, results on the shoulder; the `backtrace` as its view, with arguments; `call` spans with arguments; the stack's row with offsets and a role; a `projection` from the return address to the new node; operands of 27 characters whole |
| [13](mock/13-sqlite-row.png) | the `backtrace` lens, at rest after a `continue`: stop 120 of the sqlite scene, at `sqlite3BtreeInsert+4` | the backtrace as the band's drawing; a `hexdump` by `fields` of a struct on the stack: twelve-digit addresses, pointer fields and `NULL`, `loose` padding and the bytes past the struct, `pad`, two fields framed as the caption names them, the reading as a list; wide line numbers in the source and the disassembly; frame names whole, shortening the chains beside them; `held` on every register the continue changed, none on the stack's window, which faded in |
| [14](mock/14-sqlite-page.png) | `syscalls` as subject, at rest after the crossing: stop 169, `pwrite64` back in `unixWrite` | the kernel's side in the band; a page by `fields` as the kernel took it (`given`): big-endian numbers, bytes left to the eye, text, a `more` row of 253; the stack's window scrolled into the frame (`rsp+20 to rsp+48`), its span open above; flags and registers the crossing changed |
| [15](mock/15-marks.png) | the marks sheet: `current`, `struck`, `held` as A (the first videos), B (the catalogue's) and C (a whiter reading), on rows of the list at the load and the store after it | the source's current line; the pc's row; rip; a struck and two held registers; a dump row struck on the one byte that changed and one held; a lens's cell held and struck; the same rows at 1.35 times |
-| [19](mock/19-map.png) | the map, mid-step with a loupe open: the same moment unfolded on 3840 by 2160 ([at 1080p](mock/19-map-1080.png)) | the file whole; 69 instructions; memory, the registers, the backtrace whole; the stack from 16 words above rsp, continued at the third column's foot and folded into `more` at the process's start; the loupe as a panel beside memory; the key; the thread across the gutter; the working frame's windows outlined |
+| [19](mock/19-map.png) | the map, mid-step with a loupe open: the same moment unfolded on 3840 by 2160 ([at 1080p](mock/19-map-1080.png)) | the file whole; 69 instructions; memory, the registers, the backtrace whole; the stack from 16 words above rsp, continued at the third column's foot and folded into `more` at the process's start; the loupe as a panel beside memory; `arc`s in memory, the loupe and the stack (the frame chain left to the spans); the key; the thread across the gutter; the working frame's windows outlined |
| [20](mock/20-dive.png) | `dive`, four instants on one sheet, each at the working frame's size | frame 0 the map; 24 the windows bright, the rest veiled; 60 halfway, the panels rising out of the map as it falls to the corner; 96 the working frame with its minimap |
-| [21](mock/21-loupe.png) | the working frame mid-step with a `loupe` open | the loupe hanging from rdi over the registers under it, its node framed; the minimap with the loupe at its place on the map, outlined bright |
+| [21](mock/21-loupe.png) | the working frame mid-step with a `loupe` open | the loupe hanging from rdi over the registers under it, its node framed, the chain 1004090 → 1004070 → 1004050 as `arc`s in one lane (the view withholds them while the loupe is open); the minimap with the loupe at its place on the map, outlined bright |
| [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` |
@@ -1250,11 +1303,15 @@ under [Token changes](#token-changes).
moves one transform for the whole stage and `relayout` lerps boxes at
one text size: neither does this. A sprint, a long run and a far
`continue` are played on the map between a `surface` and a `dive`.
-4. **The loupe** at the working frame's measures ([`loupe`](#loupe)):
+4. **`arc`** ([`arc`](#arc)): in a dump, a loupe and the stack, the lanes
+ at their left edge, the columns moved for them; standing and full ink;
+ the frame chain only when touched; a loupe's rows withheld from a dump
+ showing them.
+5. **The loupe** at the working frame's measures ([`loupe`](#loupe)):
five rows, hanging from its pointer, the lift and the shadow; nine rows
as a panel on the map; on the minimap a lift block, its target
outlined.
-5. **Still from before**: the calls tree's small size and folds,
+6. **Still from before**: the calls tree's small size and folds,
`metric.span.name_max` 300, `time.caption_max` 12 s and `time.first_step`
4 s (5 s when a scene opens on the map).
@@ -1290,6 +1347,9 @@ is in the file, "Is" what the documents say.
| `time.flash` | none | 0.20: a ring from 8 to 14 |
| `time.caption_max`, `first_step` | none | 12.00; 4.00, 5.00 when a scene opens on the map |
| `metric.span.name_max` | none | 300 |
+| `metric.arc` | none | lanes 4, 10, 16 (a dump, a loupe), 4 and 10 (the stack); out at 21, head 7 by 8 at 22; rows left at 9 and entered at 15 going up; stroke 2, radius 4; standing at 60% toward the page |
+| `metric.bytes.bracket`, `address`; `metric.slot.lane` | 7, 18; 10 | 24, 34 (the bytes 12 after the address, 132 at least); 16 |
+| `time.arc` | none | `draw` 0.20 from s+6; `fade` 0.20; `quiet` 0.40 with the cool; `lane` 0.20 |
| `metric.calls` small, folds | full only | disc 36, level 38, badge 24 at 6 and 32, mono 20; fold past 13 leaves or 6 levels |
Unchanged and already there: the 1920 stage and its splits, the palette