summaryrefslogtreecommitdiff
path: root/docs/next-terminal.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 23:36:47 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitf25313ebb776aa4cca2dfbc49d3d3ff96dae161d (patch)
tree0e84cf2259400d7cdfc45392933e29924845c2fb /docs/next-terminal.md
parent639a2a7931394742af2a2e6f02006fdfd4dd6052 (diff)
downloadpardes-f25313ebb776aa4cca2dfbc49d3d3ff96dae161d.tar.gz
pardes-f25313ebb776aa4cca2dfbc49d3d3ff96dae161d.zip
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
Diffstat (limited to 'docs/next-terminal.md')
-rw-r--r--docs/next-terminal.md321
1 files changed, 321 insertions, 0 deletions
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.