From f25313ebb776aa4cca2dfbc49d3d3ff96dae161d Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Mon, 16 Nov 2026 23:36:47 -0300 Subject: docs/next-terminal.md: the terminal out of the core, the design record of 2026-11-16: Phase 1 is the destination (the terminal's files one module outside the core module, compiled into every binary, reached through a Zig interface the core declares), Phase 0 the narrow surface inside the tree that makes it a move, Phase 2 (the terminal on the addon C ABI) and Phase 3 (a terminal.so) written down and not built; prompt editing stays the core's, the back and forth across the interface with a worked example --- docs/next-terminal.md | 321 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 321 insertions(+) create mode 100644 docs/next-terminal.md diff --git a/docs/next-terminal.md b/docs/next-terminal.md new file mode 100644 index 00000000..d9c6d89d --- /dev/null +++ b/docs/next-terminal.md @@ -0,0 +1,321 @@ +# The terminal out of the core: one module, compiled in + +> investigate what it would take to remove the tty from the core and leave +> it as an addon as the rest, I'm wondering if we would take most of the +> dependencies (including transitive ones from libghostty) out of the core +> and make it much leaner for iterating (compile times and all) + +> Yes the goal was to make the core leaner for its own sake too … that's why +> I suggested adding it as an addon. + +> yes phase 1 is enough, you can document the phase 2 and the tradeoffs +> discussions, but we won't do then now. leave the prompt editing to the +> core (simple back and forth no? ) + +Decided 2026-11-16. The destination is **Phase 1**: + +- The terminal's files become one module outside the core module. +- That module is compiled into every pardes binary. +- It is reached through a Zig interface that the core declares. + +Phase 2 (the terminal on the addon C ABI) and Phase 3 (shipping it as a `.so`) are written down below and not built. Prompt editing stays the core's. + +## What "leaner" means + +"The core" is the `core_module` in build.zig: `src/pardes.zig` and everything it reaches. It is what `core-test`, hxdiff, perf, the benches and the test runners are compiled from, about 15 artifacts, each its own compilation. + +**Today `wireCore` (build.zig:835) gives it:** +- cloud9, uucode, mvzr, xitdb, zstd; +- tree-sitter and its 30 grammars; +- the generated themes, the translated `pardes_addon.h`; +- vaxis (for `gwidth` alone: surface.zig:428, File.zig:189-208); +- ghostty-vt, with what ghostty-vt brings: + - wuffs (PNG decode); + - simdutf and highway (C++); + - ghostty's four SIMD C++ files, and with them libc++ on the link; + - ghostty's `props-unigen`/`symbols-unigen` table generators and their own `uucode_generate`; + - zstbi (the terminal's PNG resize). +- Building ghostty-vt also copies ghostty's whole `src/` (603 files) into the cache to patch one file (build.zig:1938). + +**After Phase 1 the core module has:** +- cloud9, uucode, mvzr, xitdb, zstd; +- tree-sitter and its grammars; +- the themes and the addon header; +- vaxis, for `gwidth` (the user's ruling: a dependency kept beats one reimplemented in the core). + +No ghostty-vt, wuffs, zstbi, simdutf, highway or libc++. The executables still link all of them through the terminal module, as they link MuPDF through the pdf addon. + +**Compile time, measured 2026-11-16** (Debug, `core-test` with one filter, Zig 0.17.1): +- Any edit to a core file costs a full Zig recompile, 13.3 s, of which ghostty-vt is about 3 s. +- With a live incremental compiler (`--watch -fincremental`) the same edit takes 0.06–0.36 s. +- The comptime query filter in syntax.zig was a larger share (about 23%) than the terminal. +- So compile time alone did not justify this; leanness did. +- A cold build is 51 s wall, and ghostty's C++ and table generators are about 50 s of its (parallel) step time. + +## What the design stands on + +1. **The core already edits a copy of the terminal's text, never the emulator.** + - Editing shell rows with helix keys works on `EditBuffer`: "the owned text standing in for `rows` live terminal rows … the emulator grid remains untouched underneath" (terminal.zig:418-424). + - `editText` builds it from `shellRows` (terminal.zig:1695-1760). The pane says "a copy of the terminal's text: Tab or B2 runs it; what the program draws next replaces it". + - An exec types its line into an idle, empty prompt, or runs it in a new pane (exec.zig:663-674, 710-720). + - That is acme's `win` contract: text out of the terminal, edited by the editor, typed back. +2. **Replicas run an emulator fed with state, not pty bytes.** + - The authority sends ghostty's own snapshot records: one terminal-wide record, and one record per row, content-addressed, 8 bytes per unchanged row (screen_state.zig:1-33). + - A replica's replayed steps read the rows its authority's step read (replica.zig:284-310). A speculation that reads rows is marked (`tape.touchTerminal`, tape.zig:1066). + - Predicted echo reads the replica's emulator (echo.zig:237-320). + - The kinds design's painted Shadow was generalised from this path and shares its messages (`kind_shadow`, replica.zig:289, 308; architecture §10.4). +3. **Compiling an addon into the binary already exists.** The static build registers image and pdf from their modules with no `dlopen` (Addon.zig:180-188). This is the shape architecture §17.7 decided (`pub const pardes_addon = addon.ops(Kind)`, exported as a symbol only from a library). +4. **The default boot is a shell, and so are most tests.** + - `Boot.of` chooses `.shell`, `.classic` or `.tty_shell` unless a file, a missing path or stdin is named (Core.zig:2135-2143). + - `tty_only` appears 353 times in src/. About 380 of 1,067 tests in src/ touch a terminal (a grep, not a count of those that need one). + +## The options + +| | (A) run-time `.so` over `pardes_addon.h` | (B) a compiled-in module behind a Zig interface | (C) an external program, a client of the tree (acme's `win`) | (D) A's C ABI, compiled in as `static` does, also built as a `.so` | +|---|---|---|---|---| +| the core module's deps | without the terminal's | without the terminal's | without the terminal's | without the terminal's | +| the binary | the core; `terminal.so` beside it | everything | the core; `pardes-term` beside it | everything | +| no terminal when | the `.so` is not found (a moved binary, a zig-out build, the ~/.local trap) | never | the helper is missing or dies | never | +| interface | the versioned C ABI | a second, Zig-typed interface | 9P, plus a cells file | the versioned C ABI | +| replicas | §11.3's tiers | as today | painted only | §11.3's tiers | + +- **A** is "an addon like the rest" taken literally. A pardes whose `.so` went missing boots without a shell, which is no product. +- **B** costs a second interface beside pa_ops. It is the cheapest way to get the core module free of the terminal: the interface can be as Zig-typed as the code is today, and needs no versioning. +- **C** keeps the right contract but puts the process boundary in the wrong place. A real VT needs cells, cursor addressing, the alternate screen, colours and images, which cost about 240 KB of cells a frame (≈14 MB/s at 60 fps) and two IPC hops per echo. Replicas would get painted cells only. (What of `win` survives is under Deferred.) +- **D** is A done the way the static build already does image and pdf: one interface, no install trap. + +So the route is **B now, as Phase 1, with D as the way on (Phase 2) if it is ever wanted.** Phase 0 shapes B's interface like the future ABI entries (plain data in, plain data out), so that Phase 2 is a translation, not a redesign. + +## The cheap items (being done now, whatever follows) + +Items 1 and 3 were tried and reverted by the user's ruling (2026-11-16, "just keep the color palette then, the other choices were bad"): reimplementing a dependency in the core was judged worse than keeping it. Items 2 and 4 stand. + +1. **`gwidth` on uucode.** Tried and reverted: the core calls vaxis's `gwidth` again, and vaxis stays in the core module. + - vaxis's `gwidth` is about 100 lines over uucode (zig-pkg/vaxis-…/src/gwidth.zig:49-145). Its `.unicode` path, about 60 lines, moves beside `File.graphemeDisplayWidth`. + - The 5 call sites (surface.zig:428, File.zig:189-208, draw.zig:1333) use it, and vaxis leaves the core module (the tui, the gui and vaxis_input keep it). + - Gate: File.zig's "the ASCII arm of graphemeDisplayWidth matches the gwidth it skips" becomes an every-codepoint comparison against vaxis while both exist, plus the syntax and draw snapshots. +2. **The palette table.** + - `ghostty_vt.color.default` (Art.zig:490, gui.zig:5143) is the xterm 256: sixteen base colours, a 6×6×6 cube, a 24-step grey ramp. That is about 15 lines of comptime in colors.zig. + - Art.zig and gui.zig stop importing ghostty. + - Gate: equality with ghostty's table in a test, and the gui and tui snapshots. +3. **The pager's own SGR parser.** Tried and reverted: a +Pager's parse is an entry of the terminal interface instead (`Term.page`, bytes in, text and SGR spans out), ghostty's own stream behind it, so there is one parser. + - pager.zig keeps only printed text and SGR spans, but drives ghostty's `Stream` for it (pager.zig:1-10, 38, 64, 208). + - A CSI state machine that keeps `m` and drops every other sequence is about 150–200 lines. It stops pager.zig importing ghostty. + - Gate: today's `+Pager` outputs (spans and text) as goldens before the switch, and `pagercolor` byte-identical. +4. **`terminal.Snapshot` into Text.zig.** + - `Text.ed_undo/ed_redo` are typed `terminal.Snapshot` (Text.zig:83-85). + - The undo of the edit copy is the core's, so its type moves to its user. This also clears the way for `pardes-editor` (the text library, reports/editor-lib.md:313). + - Gate: core-test and hxdiff. + +After 2 and the pager's move behind the interface, ghostty-vt is imported by the terminal's own files alone (terminal.zig, screen_state.zig, TerminalImages.zig, and the pager's parse in src/term/). + +## Phase 0: the narrow module (no behaviour change, no ABI) + +`src/term/` takes: +- terminal.zig (3,422 lines); +- screen_state.zig (1,664); +- echo.zig (834); +- TerminalImages.zig (380). + +That is about 6,300 lines moved, not rewritten. + +The rest of the core calls only the functions of one interface file. Its records are plain data: rows, numbers, bytes to write, cells. `src/Term.zig` is the suggested name: the core declares the interface and the module implements it. + +**Today the core calls 62 terminal functions** (outside tests, by grep). They shrink as follows: + +| group | today | becomes | +|---|---|---| +| lifecycle (10) | create, createDoc, deinitEmulator, armShellSpawn, shellSpawned, reviveShell, emulatorGpa, terminalIo, deinitPendingCommand, animationDueMs | `open`, `close`, `tick` (the next deadline), `dump`, `load`, `revive` | +| output and view (13) | feedOutput, followOutput, atBottom, resizeGrid, resizeDeferred, scrollGrid, viewOf, viewTo, panFor, gridOffset, gridCursor, visibleCursor, scrollbar | `feed(bytes, track) → told`, `resize(cols, rows)`, `scroll(view, delta)` / `follow(view)`, and a `grid` record: offset, cursor, cursor visible, scrollbar, at bottom | +| input (10) | forwardKey, mouseBytes, wheelBytes, encodePaste, bracketedPaste, reportsMouse, reportsFocus, ownsWheel, tracksAllMotion, enterTty | `key(key) → bytes`, `mouse(event) → bytes`, `paste(text) → bytes`, and a `modes` record: mouse, all motion, wheel, focus, bracketed paste, alternate screen. `enterTty` is the core's own mode switch and stays. | +| prompt and commands (12) | promptInputEmpty, promptInputReady, onAlternateScreen, noteCommand, queuePendingCommand, releasePendingCommandIfReady, commandRunning, commandOutput, endOutputHere, padOutputBelowEdits, marksOf, takeMarks | a `prompt` record (phase, prompts, started, declined, last exit, input ready, input empty, cursor at prompt), `command_output(max_rows)`, `end_output_here`; the pending command queue becomes the core's, released by `prompt.ready`; the marks travel inside the term's replica state | +| text (11) | screenTextAlloc, screenTextLen, bodyText, shellRows, cursorLines, promptPrefixBytes, editText, setEditText, flatSurface, pushUndo, undoStep | `body`/`body_len` (the plaintext scrollback), `rows(lo, hi)` with each row's prompt-prefix length. editText, setEditText, cursorLines, flatSurface, pushUndo, undoStep and `EditBuffer` return to the core (edit.zig, Text.zig): about 400 lines of the core's own editing, misfiled in terminal.zig. | +| draw (6) | recolorAnsi, drawImages, hasImages, palColor, petscii, togglePetscii | `paint(window, palette)` writing cells with palette indices kept as indices, and `images(window) → placements`. The palette and the theme's contrast filter are the core's (colors.zig), and so are Petscii and glyph art (architecture §11.1). | + +So 62 functions become about 18 entries and three records (`grid`, `modes`, `prompt`). + +**The direct reaches into the emulator's state** (`.vt`, `.stream.handler`, `.terminal.?.` outside tests) number 33: +- replica.zig 15, echo.zig 12, ninep/pty.zig 5, Core.zig 1. +- echo.zig's go inside with it. +- replica.zig's terminal half (replica.zig:284-450: `Screens`, `Track`, the peers' state) calls `term` for `encode(peer_base) → bytes`, `ack(seq)`, `apply(bytes)` and `rows_request(lo, hi)`. +- ninep/pty.zig reads the `prompt` record. The pty files stay the core's: they are about processes, which the host owns. + +The ptys stay host resources: +- host_io.zig forkpty (:2119, :2854), the readers (:591), signals (:2705); +- upgrade.zig's records of their fds across the exec (:100-165); +- the `Effect` variants (`write`, `resize_pty`, `signal_pty`, `close_pty`, Effect.zig:42-47). + +**Gates:** +- core-test, pane-test, behaviour-test (with `--monkey` seeds); +- kitty-test, the kitty and image harnesses; +- every snapshot byte-identical; +- `hxdiff --parity` (a pty pane against a file pane), `zig build replicas` (digests, rollback rate), the process suite; +- `perf-gate` and `perf --terminal-mib` against the base on the same input; +- the replica soak, local and box, because replica.zig and echo move. + +## Phase 1: the module leaves the core module + +- **The module.** + - `term` is a Zig module of its own, rooted in `src/term/`. Its imports are `std`, ghostty-vt, wuffs, zstbi, uucode and the interface module. + - It does not import `pardes`. Zig refuses a file outside a module's root, so the build graph enforces the seam in both directions: the core cannot name ghostty, and the terminal cannot name the core. + - The records the terminal writes (cells, placements) live in the interface module, or in a leaf module surface.zig's types are moved into. surface.zig today imports `pardes.zig` (surface.zig:3), so its cell types have to be lifted out. +- **Registration.** + - main.zig hands the core `&term.ops` (`Pardes.Options.terminal`, or one global set at start beside `pardes.turn`). + - Every root that builds a product imports `term`: the exe, the static build, `run-isolated`, the gui. + - `core_module` does not. build.zig's `wireCore` stops giving it ghostty-vt, wuffs and zstbi, and core-test's link loses `-lc++`. +- **The no-terminal core.** A core with no terminal ops (only a test can build one) boots to a scratch pane and says once "no terminal in this build". Words that make terminals (`Term`, `Repl`, an exec with no idle shell) refuse in words. `takesCommandLine` is false. +- **The test fixtures.** This is decided at Phase 1 from the count of tests that need a real shell, as opposed to the ones that merely boot one: + - **A fake terminal for core-test** (`Kind.test_kind`'s pattern, Kind.zig:1153). A few hundred lines: `feed` appends text to rows, `prompt` says ready, `key` returns its UTF-8. The tests that boot `tty_only` for convenience boot a scratch pane or the fake. Terminal behaviour tests move to `term`'s own test step. + - **The shell tests leave core-test.** Every test that needs a shell moves to a suite that imports `term` (pane-test already imports the core and could import `term`). core-test keeps only what boots without one. + - Either way, about 350–700 lines of test boots change, most by one line. +- **Replication, dumps and Upgrade are unchanged.** + - Both sides of a replica are the same binary, so the screen-state path works as now, only called through `term`. + - Echo keeps working. + - The dump record keeps its format (walk parts plus ghostty's snapshot, terminal.zig:280-330) with no size cap, since this is not the addon record. + - Upgrade passes the pty fds as now. +- **Gates:** Phase 0's, plus: + - `zig build static` (musl), `-Dplatform=gui`, `macos-e2e` where a Mac is open; + - the replica soak at 30/80/207 ms, local and box; + - a check that core-test's compile command names no ghostty, wuffs, zstbi or `-lc++` (from `--verbose`). + +## Prompt editing: the back and forth + +The core owns the edit and the terminal owns the grid. Across the interface: + +**Terminal → core:** +- `rows(lo, hi)`: the logical rows from absolute row `lo` to `hi` as text, and each row's prompt-prefix length in bytes (from its OSC 133 marks, today `promptPrefixBytes`, terminal.zig:1563). +- The `grid` record: the absolute row the screen begins at, the cursor, the scrollbar. +- The `prompt` record: phase, input ready, input empty, cursor at prompt. +- From each `feed`, the `told` record (today `Told`, terminal.zig:1069): + - for every row the core asked to have tracked, its new absolute row; + - whether it was erased; + - whether the screen was cleared; + - whether the terminal is still alive. + +**Core → terminal:** +- `feed`'s `track`: the absolute rows the core holds positions on (the copy's rows, the cursor, selections, their undo, pointer rows). +- The line to run, as bytes to write to the pty: the line without its prompt prefix, then `\r`. Before it go as many `\r` as keep the program's output below the copy (today `padOutputBelowEdits`). + +**A worked example.** + +1. The shell is idle at absolute row 41, which shows `~/src $ ` (prefix 8 bytes, input empty). Row 12, in the scrollback, shows `~/src $ make test`. +2. In normal mode the cursor goes to row 12 and `i` starts an edit. The core asks `rows(12, 12)`, gets `~/src $ make test` with prefix 8, and makes its copy over row 12. The pane says "a copy of the terminal's text…". The user makes the line `~/src $ make test -j8`, with helix's keys, undo and registers, all the core's. +3. A background job prints three lines while the user types. The scrollback is at its limit, so the oldest three rows are dropped. The core calls `feed(bytes, track = [12, …])`, and `told` says row 12 is now row 9, not erased. The copy, the cursor and the undo snapshots move to row 9, and the program's output never touches the copy. + - Had the job run `clear` (ED 3), `told` would say row 12 erased and the screen cleared. The copy is dropped and the pane says so: "what the program draws next replaces it". +4. B2 on the line, or Tab, runs it. + - The core takes the copy's line and cuts the 8-byte prefix the row had: `make test -j8`. + - The `prompt` record says the shell is ready with empty input, so the core may type there (otherwise the line goes to a command pane, as exec.zig:663-674 decides today). + - The core writes `\r` padding as needed, then `make test -j8\r`. + - The program's echo and output replace the copy when they draw over its rows. + +Nothing in this crosses per keystroke of the edit itself: the edit is the core's text. The terminal is asked for rows when an edit starts or widens, and tells where rows went on each feed. + +## Deferred: Phase 2, the terminal on the addon C ABI + +This is not built now. It is written down so the discussion is not lost. + +### What it would buy over Phase 1 + +- **One interface.** The terminal would be a kind like image and pdf, on pa_ops. +- **Live reload while developing it** (`Addon reload terminal` in a session with a live shell). +- **A terminal someone else could replace.** + +The core module is already lean after Phase 1, so Phase 2 buys nothing more there. + +### What the C ABI would need (pardes_addon.h, today ABI 3.1, 19 function slots at :293-353) + +- **Bytes and the pty.** + - `feed(st, bytes, n, track, *told)`. + - `pa_api.spawn` (a child on a pty for this pane), `write`, `resize_pty`, `signal`. + - The ptys stay the host's, and Upgrade passes their fds as now: a kind never touches an fd, so the host-syscall yield rule (Turn.zig) is not involved. +- **Text for editing.** `rows(st, lo, hi, out)` with prefix lengths, and `told`. +- **Records.** + - `pa_grid`: cursor, shape, visibility, offset, scrollbar, dirty rows, coming out of `paint`. + - `pa_modes`: mouse, motion, wheel, focus, bracketed paste, alternate screen. + - `pa_prompt`: phase, counts, exit, ready, empty, at prompt. + - Plus `command_output` and `paste`. +- **Keys.** `pa_key` is {cp, ctrl, alt, shift, view} (pardes_addon.h:151-154). The kitty keyboard protocol needs composed text, key release, super, the unshifted codepoint, F1–F25, insert and the rest (terminal.zig:1384-1440). That is a new `pa_key2`. +- **Cells.** `pa_cell` (20 bytes, :63-69): + - strike, blink, invisible and the underline styles fit in `attrs`'s free bits; + - a wide/spacer flag fits in `flags`; + - underline colour and a hyperlink id do not fit. The record must grow, and records are passed as arrays with a fixed stride. That is a major bump. +- **Images.** `z` on `pa_placement` (80 bytes, no spare field, :100-109). Kitty's `z=-1` draws under the text. architecture.md:721 left it out because "the terminal is not a kind". +- **Replication, the fed tier.** + - `state_encode(st, peer_base, w)`, `state_ack(seq)`, `state_apply(st, bytes)`, `rows_request(lo, hi)`: screen_state.zig behind the ABI. + - The core carries opaque per-pane state messages beside today's `kind_shadow`/`kind_raster`. + - The hello pins the terminal's content hash (§11.3's `local` rule). A client whose terminal differs gets the painted Shadow (no echo, a round trip per key) and is told once, never refused. +- **Echo.** `predict(st, key, seq)` and `confirmed(st, seq)`. echo.zig moves with the terminal, which paints the provisional cells itself. +- **Dumps.** + - `PA_RECORD_MAX` is 1 MiB, and a scrollback is up to 16 MiB (terminal.zig:899). + - The record would hold the terminal-wide record plus each row's content hash, 8 bytes a row. The rows (screen_state's per-row records) go to the xitdb blob cache (architecture §14.4), written once across dumps and fetched by hash on a join. + - A version boundary at Upgrade or Restore: `load(rec, version)` refusing keeps the shell (its fd survived; `reviveShell`) and loses the history. +- **Paint.** `paint` is called once a frame in each view (pardes_addon.h:111-116). A terminal must say which rows changed, or the core redraws 12k cells per pane per frame. `pa_grid` carries a dirty-row bitmap. + +All told: about 20 new functions and 5 new or grown records. pa_ops goes from 19 slots to about 35, and Kind.zig grows by about 500–800 lines. Because of `pa_key2` and `pa_cell`, this is **ABI 4**: every addon rebuilds (there are six, all in the tree). + +### What it would risk + +- **Remote feel.** The fed tier and echo must land together, or a replica stops feeling local. Gate: the replica soak at 30/80/207 ms with echo on (echo hits, visible rollbacks), box and local. +- **The hot path.** + - Bytes in are one call per pty read (≤ 4 KiB, two in flight): nothing. + - Cells out add one pass of about 12k `pa_cell`s per pane per view per frame (architecture §10.2 estimates 10–20 µs), plus the dirty-row bookkeeping. + - Gates: `perf --terminal-mib`, `perf-gate`, and a new frame-time cell with four shell panes under `yes`. None of this is measured. +- **History at version boundaries** (above). + +### Phase 3: shipping `terminal.so` instead of compiling it in + +This is option A. It brings back the install trap: a binary without its `.so` has no shell. It buys nothing that a dev `.so` loaded over the compiled-in terminal does not. Not planned. + +### Option C, and what of acme's `win` survives + +`win` (plan9port src/cmd/9term/win.c) works like this: +- It opens a window's `ctl`, `event`, `addr` and `data` (:177-194). +- It starts the shell on a pty as a dumb terminal (:205). +- It strips CR, CRNL and NUL, and keeps a split rune for the next read. +- It parses one escape, the label (:626-647). +- It notices "password:" to stop echoing. +- It appends output at its output point by writing `#q.p` to `addr` and the bytes to `data` (:523-620). +- What is typed past the output point goes to the shell on newline. + +What survives: +- **The contract**: output is text the editor can edit, and a line goes back as input. pardes's prompt editing is that contract. +- **The process boundary, for one thing**: a helper would outlive an Upgrade of the editor by itself. + +What does not survive: everything a VT is for. Full-screen programs need cells, cursor addressing, the alternate screen, colours and images, and over a process boundary those cost a cells file per frame and two IPC hops per echo. A helper also sits outside the deterministic core, so replicas could only be painted. + +### The alternatives rejected for each hard part + +- **Prompt editing.** + - The terminal could embed `pardes-editor` and edit its own rows. Rejected: a second helix in the guest, possibly from another revision, with registers, macros, `.` and the selection's Look/exec/pipe needing round trips to the core. + - The core could edit the emulator's grid through pins. Rejected: it puts ghostty's pin model into the interface. +- **Replication.** + - Replaying pty bytes on every client is rejected: a gigabyte `cat` costs every client a gigabyte. + - Painted cells only is rejected as the default: no echo, no local scrollback, a round trip per key into a terminal pane. It stays as the fallback for a client without the same terminal. +- **Echo.** + - A per-cell read API back into the emulator is rejected: a reach the seam exists to remove. + - Dropping echo on replicas is rejected: it fails the soak. +- **Dumps.** + - A chunked record (`dump(off, buf, n)` until done) is rejected: every dump carries the whole scrollback again. + - A per-kind larger cap is rejected: it breaks the wire bound (§17.3) and "a dump always loads". +- **The 9P pty files.** Moving them into the addon, through kinds serving files of their own (§10.1 listed "the files it serves", which ABI 3 never got), is rejected for now: a 9P surface in C for one kind. The `prompt` record is enough. +- **The pager.** + - Making `+Pager` a terminal pane is rejected: it loses the file-like pane. + - Vendoring ghostty's parse table is rejected: it keeps a piece of what is leaving. + +### Questions for the day Phase 2 is taken up + +1. Is live reload of the terminal worth an ABI 4 that every addon rebuilds for? +2. A replica whose terminal build differs from the session's: painted with no echo, or refuse the build mismatch at the hello? +3. Should kinds get served files (the pty tree would be the first), or does the `prompt` record stay the whole story? +4. Dirty rows: a bitmap out of `paint`, or the terminal keeping cells across frames and the core asking only for changed rows? +5. Does a third-party terminal (another emulator than ghostty) need to be possible, or is "one interface" the only reason? + +## Not verified + +- How many tests need a real shell rather than a booted one. The 380 is a grep for terminal words in test bodies. +- That `Kind.test_kind`'s pattern fits a terminal fake. +- That nothing but ghostty's SIMD C++ brings `-lc++` into core-test's link. Round 1 read it off one command line. +- That surface.zig's cell types can move to a leaf module without dragging `pardes.zig` in. +- Everything quantitative about Phase 2: the extra cell pass, the dirty-row bookkeeping, a scrollback's size as row hashes (8 bytes a row is an estimate). +- The figure for option C (≈14 MB/s of cells) is arithmetic, not a measurement. +- The compile-time numbers above are from one day on a loaded 16-core machine, about ±1 s. -- cgit v1.3