# 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`). ## Phase 1 as built (2026-11-17) What differs from the plan above, and why: - **The ops are a compile-time constant, not handed over at start.** `Term.ops` (src/Term.zig:18) is `&@import("term").ops` when the build's `term_options.terminal` says the core has a terminal, null otherwise. Every core module but core-test's is given `term`; core-test's (`core_lean` in build.zig) is not, and its `term_options` say so. A run-time `Pardes.Options.terminal` would have put the table in every test's options and every host's start for no gain: no build ever has two terminals, and a null known at compile time drops the dead code. - **The table**, `plain.term.Ops` (src/plain/term.zig): about 60 entries in the groups of Phase 0's table (lifecycle, output and view, input, prompt, text, the pager, draw, replicas), each taking and giving plain records or one of four opaque handles (`State`, `Encoder`, `Track`, `Replica`). The module fills it through a cast refused at compile time unless each entry's signature matches (src/term/term.zig). - **`Term.State` is a small struct around the handle** (src/Term.zig:55), not the handle itself: walk.zig allocates a pane's terminal on load and hooks its digest and dump, and needs a type of the core's to do it on. The dump keeps a terminal as before (its `Parts` by name, then ghostty's snapshot). The dump's type table names it `Term.State` where it said `term.terminal.State` (and `main`, `terminal.State`); walk discards the name on load, so dumps of either build load in the other (checked: test/daemon.py --upgrade from a build of main, fc38c73c5, and from the Phase 0 base into this one, and from this one back to main's). - **Predicted echo came back to the core** (src/echo.zig): it is the replica's presentation, and reads the emulator through five entries (`grid`, `modes`, `prompt`, `echoCell`, `markRead`). - **The draw group is plain data** (Phase 0 left it typed in the core's types): `Term.paint` fills a cell buffer in the theme's colours, the core lays it over the body (src/ansi.zig), and `Term.images` gives placements. The colour filter stays the terminal's, as it wraps ghostty's `generate256Color`. A finished command pane's diff colours (`DiffOutput`, `recolorDiffOutput`) moved beside it in src/ansi.zig. - **The no-terminal core** boots a scratch pane where a shell would be (Core.zig, `initSession`). `Term.open` refuses with `error.NoTerminal`, which a word says as "no terminal in this build" (`Term: …`, `exec: …` for a line no shell can take). `+Pager` pages the bytes as they are, escapes and all: nothing in the core parses an escape. There is no message at boot: only core-test builds this core, and a boot message made seven of its tests about messages and notices fail. - **The test fixture: neither the fake terminal nor a separate suite.** The count decided it. Of core-test's 946 tests, 535 booted a shell and skipped while the scratch boot was a skip; run on the scratch boot, 128 of them fail for want of a terminal (they open a shell or a command pane, read the emulator, or index the classic boot's three shells) and say so on their first line (`if (pardes.Term.ops == null) return error.SkipZigTest; // a shell`), and ninep/testing.zig's `withTerm` once for its 29. The rest run. core-test: 810 of 949 run, 139 skip; `shell-test` runs all of them with the terminal. The 28 tests that read terminal.zig's own state through a core are in test/terminal.zig (pane-test); the module's own tests are `term-test`. ## 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 - That `Kind.test_kind`'s pattern fits a terminal fake (none was built). - macOS: the Phase 1 tree was not built on a Mac. - 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.