summaryrefslogtreecommitdiff
path: root/docs/next-terminal.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 04:20:55 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitb65048ac19f9f47b6faa21d1a9f3d06ba3ff1a95 (patch)
treeb748e066d9a01690e8e20259db06746b2a5ad969 /docs/next-terminal.md
parentbb3d189676a9681542a61b453f0eb55208cc1311 (diff)
downloadpardes-b65048ac19f9f47b6faa21d1a9f3d06ba3ff1a95.tar.gz
pardes-b65048ac19f9f47b6faa21d1a9f3d06ba3ff1a95.zip
docs: the terminal out of the core, as built: docs/next-terminal.md gains Phase 1 as built (the ops a compile-time constant and why, the table, Term.State a struct around the handle and the dump's type name, echo back in the core, the draw group as plain data with the diff colours beside it, the no-terminal core with no boot message and why, the test split by its counts), its not-verified list loses what is now known; building.typ says what core-test, shell-test and term-test build and run, and the term and plain modules; the changelog's entry says the terminal is a module of its own and what core-test and shell-test are
Diffstat (limited to 'docs/next-terminal.md')
-rw-r--r--docs/next-terminal.md61
1 files changed, 57 insertions, 4 deletions
diff --git a/docs/next-terminal.md b/docs/next-terminal.md
index d9c6d89d..1229df6f 100644
--- a/docs/next-terminal.md
+++ b/docs/next-terminal.md
@@ -178,6 +178,61 @@ The ptys stay host resources:
- 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:
@@ -312,10 +367,8 @@ What does not survive: everything a VT is for. Full-screen programs need cells,
## 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.
+- 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.