diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 04:20:55 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | b65048ac19f9f47b6faa21d1a9f3d06ba3ff1a95 (patch) | |
| tree | b748e066d9a01690e8e20259db06746b2a5ad969 /docs | |
| parent | bb3d189676a9681542a61b453f0eb55208cc1311 (diff) | |
| download | pardes-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')
| -rw-r--r-- | docs/next-terminal.md | 61 | ||||
| -rw-r--r-- | docs/typ/building.typ | 16 |
2 files changed, 71 insertions, 6 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. diff --git a/docs/typ/building.typ b/docs/typ/building.typ index 6bf7dfce..543acfa5 100644 --- a/docs/typ/building.typ +++ b/docs/typ/building.typ @@ -121,8 +121,12 @@ package, and `zig build lib-test` builds and runs it. ``` zig build unit-test module and shell unit tests (the perf gate runs with it) zig build test-build compile the unit-test programs without running them -zig build core-test core tests without native shell tests -zig build shell-test the native shell's own unit tests, without the perf gate +zig build core-test core tests on the core without a terminal (no ghostty, + no C++): a shell boot is a scratch pane, and a test + that needs a terminal skips; the one to iterate on +zig build shell-test the same tests and the native shell's, with the terminal, + without the perf gate +zig build term-test the terminal module's own tests (src/term/) zig build pane-test pane, output and namespace integration tests zig build kitty-test kitty graphics conformance of terminal panes, at the core zig build kitty-harness kitty graphics through a pane end to end (a fake kitty @@ -238,6 +242,14 @@ effects such as spawning processes. decides who serves it. - The root module is chosen by platform: `main.zig` (tui, gui), `macos.zig`. The macOS shell is a library whose host owns `main()`. +- The terminal is a module of its own, `term` (`src/term/`): the + emulator (ghostty-vt), kitty images (wuffs, zstbi), the pager's parse + and the replicas' screen state. It never imports the core; the core + reaches it through one table of plain-data entries (`src/plain/term.zig`, + through `src/Term.zig`), chosen at compile time. The records both name + (cells, colours, keys) are `plain` (`src/plain/plain.zig`, std only). + Every product is built with the terminal; core-test's core is built + without it, so its compile names no ghostty, wuffs, zstbi or C++. - `memory.limits` is the one home for the core's capacities (selections, the tag's bytes, undo, the arenas' regions). Each core allocator is a DebugAllocator over its arena's reserved region, thread |
