summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/next-terminal.md61
-rw-r--r--docs/typ/building.typ16
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