+ 
+ 
@@ -25,72 +27,27 @@ Details and the Unicode conformance numbers: Bidir
---
-## Four agents, four worktrees, four port blocks
+## Six things you will not find in another terminal
+
+1. **Bidirectional text that is actually correct**, at 91,707 of 91,707 Unicode conformance
+ cases, with Hebrew and Arabic drawn rather than reordered into blank cells. The logical
+ order stays in the core and the visual order lives in the renderer, so selecting the
+ character you see gives you the character you meant.
+2. **Correctness measured against another team's implementation**, not against itself. Every
+ build feeds 223 byte streams to this engine and to the real `libghostty-vt` and compares
+ the two grids cell by cell. Seventeen cases are pinned to *disagree*, so the harness can be
+ seen to detect difference at all.
+3. **A stable port block per workspace.** Four agents in four worktrees stop fighting over
+ port 3000, and the block is derived from the path so it never moves.
+4. **A dock that says which agent needs you**, from explicit signals only. Working, done,
+ error, and a fifth state that means *stopped and waiting*, raised by the bell.
+5. **No network path, and it is gated rather than promised.** One test reads the resolved
+ dependency graph, another proves the review panel's webview cannot leave its local
+ document.
+6. **Every gate here has been watched go red.** A test that has never failed is not evidence,
+ and the list of real defects that rule caught is further down this page.
-Git worktrees are the standard answer to running agents in parallel, and the number that
-keeps appearing is four to eight per developer. The isolation works for files and does
-nothing for anything that is not a file. Every dev server defaults to 3000. Agent A starts
-one, agent B dies on `EADDRINUSE`, and agent B reports a broken build that is not broken.
-
-The formula everyone hand-rolls is `PORT = BASE + INDEX * 10 + OFFSET`, plus a script that
-rewrites a `.env` per tree, and it does not survive being moved to CI.
-
-Termisu hands the base down. Every pane's child gets:
-
-```sh
-TERMISU_PORT_BASE # the first port of this workspace's block, 20000..39990
-TERMISU_PORT_SPAN # how many ports the block holds, 10
-```
-
-```jsonc
-// vite.config.js
-const base = Number(process.env.TERMISU_PORT_BASE ?? 3000)
-export default { server: { port: base }, preview: { port: base + 1 } }
-```
-
-**Derived from the workspace path, never handed out in sequence.** A base assigned in
-launch order moves whenever the panes open in a different order, and then a bookmark, a
-proxy rule and a database URL all rot. The same worktree is the same block forever and on
-every machine, with no state kept anywhere. A worktree reached through a symlink is the
-same workspace, which matters on macOS where `/tmp` is a symlink to `/private/tmp`.
-
-**`PORT` itself is deliberately not set.** Silently moving a dev server off the port its
-operator typed is a bigger surprise than a variable nothing reads yet.
-
-**It is a hash, so collisions are possible and the number is written down rather than
-implied.** With N workspaces the chance any two share a block is about
-`1 - exp(-N(N-1)/2/2000)`: 0.3% at four worktrees, 1.4% at eight. Removing that entirely
-would need a registry file, which is state on disk that has to be cleaned up and is wrong
-the moment a worktree moves.
-
-## No account, no telemetry, no network
-
-Termisu never talks to a server. Not to check a licence, not to phone an analytics
-endpoint, not to see whether there is an update. There is nothing to sign in to, there is
-no telemetry to turn off, and the whole thing runs with the wifi off.
-
-That is a fairly ordinary thing to claim and a fairly common thing to be wrong about, so
-it is gated rather than asserted:
-
-- **`crates/host/tests/no_network.rs`** reads the resolved dependency graph out of
- `Cargo.lock` and fails if anything in it can open a socket. This is the way the claim
- would actually break: nobody writes `TcpStream::connect` in a terminal on purpose, but a
- convenience crate arrives for an unrelated reason and drags an async runtime and a TLS
- stack in behind it. 241 crates resolve today and none of them are networked.
-- **`--smoke-offline`** covers the one part that could: the review panel is a `WKWebView`,
- so WebKit is linked into the process whether we like it or not. What makes the claim
- true anyway is `PanelNavigation`, which permits exactly one navigation - the local
- document the panel was handed - and refuses every other scheme, path and navigation
- type. A remote URL carrying that same path is refused too, which is a case a mutant
- found rather than a case anyone thought of.
-
-Two things that are honestly NOT covered by either gate. The shell you run inside Termisu
-is your shell and can do whatever you tell it to; the terminal does not police its child.
-And macOS itself may talk to Apple about a signed binary the first time it runs one, which
-is Gatekeeper, not us.
-
-**The licence is AGPL-3.0**, so this is checkable rather than a promise. The audit is
-`grep`, and the two gates above run on every build.
+---
## Why this exists
@@ -112,12 +69,7 @@ through with regular expressions. If you own the terminal, you do not guess: the
its working directory and its git branch are already sitting in cells, typed, because your own
parser put them there.
-So the terminal came first. **The workbench is the goal and it is not built** - there is no session
-map, no canvas, nothing that shows you what several agents are doing at once. What exists on top of
-the engine today is a window with panes, plus a module that can launch an agent CLI into one. The
-richer surface lives in the Swift host, which is a wrapper around the same engine and is where the
-tabs, palette, blocks and worktrees actually are. Read the feature list below as two hosts over one
-core, not as a product.
+So the terminal came first, and the surface on top of it is growing from the engine outward.
## Written from zero
@@ -126,12 +78,13 @@ where the seams were without teaching me why any of it worked. So I archived it
again from an empty directory on 2026-07-28.
The parser, the grid, scrollback, reflow, the pty, the renderer, bidi, shaping, the C ABI and
-the app are all written for this project. The one piece not written here is the escape-sequence
-tokenizer, a vendored fork of [vte](https://github.com/alacritty/vte), kept in-tree with its
-licences and one addition of our own.
+the app are all written for this project: 54,000 lines of Rust and 9,000 of Swift. The one piece
+not written here is the escape-sequence tokenizer, a vendored fork of
+[vte](https://github.com/alacritty/vte), kept in-tree with its licences and one addition of our
+own.
-**No Ghostty code ships here.** The app binary contains zero of its symbols and links zero of
-its libraries, which is checkable with `nm` and `otool`.
+**No Ghostty code ships here.** The app binary contains zero of its symbols and links zero of its
+libraries, which is checkable with `nm` and `otool`.
The history carries no personal data either, and that is checkable rather than asserted. Every
commit is authored by one GitHub noreply identity, no commit message names an account, and the
@@ -147,11 +100,6 @@ which exist because OSC 7 reports a `file://` URI and the corpus has to pin what
with one. Home-relative paths appear too, and they are this program's own: `~/.termisu/config.toml`
and the `~/.ruuah` fallback it still reads.
-The commits were rewritten once, on 2026-08-07, to remove an email address and two paths into a
-private machine before the repository was made public. Nothing else moved: the tree hash at HEAD
-is byte-identical either side of that rewrite, and all 305 commits and 28 tags survived with
-their messages, dates and ordering intact.
-
## How it is checked, and against what
Ghostty did not disappear from the project. It became the instrument.
@@ -189,14 +137,33 @@ version and watched go red. That is not a slogan; it is what found:
- a selection that outlived the pane it was made in and underflowed the renderer, found by splitting panes in the live window until it died
- every Arabic letter drawn in its isolated form, invisible to a suite whose other scripts have only one form per letter
- a pty shutdown that could deadlock forever, which had been hanging a test for at least a day without ever going red
+- every pane telling its child the terminal had no truecolor, which drew one agent's mascot in the wrong colour for fourteen days
+- two of the three spinner glyphs missing from the work-state table, so the dock announced *done* while an agent was still working
+
+### Vacuous passes are the enemy, not failures
+
+A gate that cannot fail is worse than no gate, because it is read as evidence. Four found and
+fixed in this repository, each one the same shape:
+
+- **A constant folded into both sides of a comparison.** A dock-width assertion compared a delta
+ against the very constant under test, so setting that constant to a wrong value passed. Absolute
+ bounds now, never deltas against the thing being measured.
+- **A shape signature that read only the root layer.** An invisible state dot with a live
+ sublayer still scored as a distinct shape. A shape gate counts geometry; only ink says whether
+ anything can be seen.
+- **A distinct-value count that an anti-aliased edge satisfied on its own.** Counting ink levels
+ could not tell a monochrome engraving from a filled silhouette, because an emoji bitmap's edge
+ supplies 123 levels by itself. The metric is where the ink piles up now: 0.023 against 0.251.
+- **A pty helper that matched the first marker on screen**, so a second question returned the
+ first answer. It failed loudly on one test and passed *silently* on another, where "the stale
+ value was not reported" was satisfied by re-reading the value being compared against.
### A hang is worse than a failure
-The last of those is worth its own note, because it is the shape of defect this project is
-least protected against. `Host::shutdown` stopped the pty pump before killing the child, and
-the pump is the only reader of the pty master; a child exiting with a controlling terminal
-blocks in the kernel until its output queue drains, so it could never finish exiting and the
-parent waited on it forever. **The reader has to outlive the child.**
+`Host::shutdown` stopped the pty pump before killing the child, and the pump is the only reader
+of the pty master; a child exiting with a controlling terminal blocks in the kernel until its
+output queue drains, so it could never finish exiting and the parent waited on it forever.
+**The reader has to outlive the child.**
Nothing went red. Cargo simply never returned. One instance was found still running seven and
a half hours after it started, holding its child processes, with two more beside it, while
@@ -205,7 +172,7 @@ every suite run that looked green ran alongside them.
What named it was a discriminating pair rather than a theory: 120 rounds of spawn-then-shutdown
with a **silent** child pass in 0.74s, and the same loop with a child that prints **one line**
first hangs within 40. A third attempt at a deterministic repro, using a large piped write,
-did **not** reproduce, and that was evidence too - the pipeline was slow to start, so the child
+did **not** reproduce, and that was evidence too: the pipeline was slow to start, so the child
was killed before writing anything.
Two consequences, and the second matters more. The kill happens first now, so the pump keeps
@@ -218,10 +185,9 @@ counts as a gate at all.
Two tests here were green locally and red on a shared CI runner, for reasons that had nothing
to do with the code. A synchronized-output test split its batch 60ms apart and was measured
-against a 150ms anti-stuck budget - a 2.5x margin, which is no margin at all on a machine
-somebody else is using, so the budget correctly published a half-drawn frame and a test about
-the gate failed for the wrong reason. A seqlock test required the reader to land at least one
-accepted read inside a fixed 400ms window, which a two-core runner cannot promise.
+against a 150ms anti-stuck budget, a 2.5x margin that is no margin at all on a machine somebody
+else is using. A seqlock test required the reader to land at least one accepted read inside a
+fixed 400ms window, which a two-core runner cannot promise.
Neither was a real defect and neither was harmless: a gate that reports on how loaded the
machine is teaches you to ignore it. The budget became a per-test setting so the gate test and
@@ -229,17 +195,41 @@ the budget test each set the value their own claim needs, and the liveness windo
while nothing has been accepted rather than failing. The workload, the race and the invariant
are untouched in both.
+### The gates
+
+Five exit-code gates run before anything merges.
+
| gate | what it proves |
|---|---|
-| `cargo test --workspace` | 713 tests: units, pixels, concurrency, C-surface round trips |
-| `termisu-vt-difftest` | 223 corpus cases, every verdict met, 17 of them pinned to disagree |
-| `esctest2` | 391 pinned passes of 568, both directions: a regression fails, so does an unpromoted pass |
-| `scripts/smoke-termisu.sh` | 26 host invariants about what AppKit, WebKit, the IPC and the child processes actually did, with no screen required |
-| export check | 28 + 56 C symbols present in the shipped archives: our own `termisu_vt_*` surface and the `ghostty_*` drop-in, each verified by name |
-| header parity | `include/termisu_vt.h` compiled against C static assertions generated from Rust's own `size_of` and `offset_of!`, with a control that proves a false assertion fails |
-
-The screenshots above were taken with `cargo run -p termisu-vt-render --example screenshot`, which
-runs a command in a real pty and renders the result with this terminal's own CPU backend. A
+| `cargo test --workspace` | **822 tests**: units, pixels, concurrency, C-surface round trips, live-pty contracts |
+| `cargo run -p termisu-vt-difftest` | **223 corpus cases**, every verdict met, 17 of them pinned to disagree |
+| `./scripts/build-lib.sh` | **28** `termisu_vt_*` C symbols present in `libtermisu-vt.a`, verified by name |
+| `./scripts/build-host.sh` | **61** symbols in `libtermisu-vt-host.a`: the ABI plus the embedder surface |
+| `./scripts/build-swift.sh` | **15 headless smokes**: what AppKit, WebKit, the bridge and the child processes actually did, with no screen required |
+
+Two more run by hand, because neither belongs in a loop:
+
+| suite | result |
+|---|---|
+| `esctest2`, through our own pty | **373 pinned passes of 568**, both directions: a regression fails, and so does an unpromoted pass |
+| `./scripts/agent-live-tap.sh` | starts a real authenticated agent, so no automated gate may run it |
+
+Where the 822 live:
+
+| crate | tests | what it covers |
+|---|---|---|
+| `core` | 190 | the parser and the grid: a pure state machine, no I/O and no clock |
+| `render` | 164 | glyphs, atlas, bidi drawing, shaping, both backends byte-equal |
+| `host` | 158 | the embedder surface, agent launching, and live-pty contracts |
+| `frame` | 79 | the seqlock frame channel and Unicode bidi conformance |
+| `ghostty` | 67 | differential encoders: keyboard and mouse, against the reference |
+| `pty` | 54 | the pty, and `esctest2` through it |
+| `snapshot` | 39 | the typed grid other layers read |
+| `vte` | 31 | the vendored tokenizer plus our APC addition |
+| `abi` | 16 | header parity, against C static assertions generated from Rust's own layout |
+
+The screenshots on this page were taken with `cargo run -p termisu-vt-render --example screenshot`,
+which runs a command in a real pty and renders the result with this terminal's own CPU backend. A
picture of some other terminal agreeing with our numbers would not be the claim being made.
## Bidirectional text
@@ -271,15 +261,10 @@ column right-to-left where it is Hebrew or Arabic, and note what does **not** mo
| Arabic | `مرحبا بالعالم` | joined, right-to-left, each letter in its contextual form |
| Persian | `سلام دنیا` | same, and `پ چ ژ گ` resolve through the same stack |
-Three of those are the cases a plausible implementation gets wrong. **`42` stays `42`** - reversing
-the run wholesale yields `24`, and it reads as perfectly normal until somebody types a port number
-backwards. **The code keeps its direction** while the string inside it reorders. **The box drawing
-stays in columns 0, 4 and 8**, because whole-line reordering across a table moves the frame
-relative to the text it encloses.
-
-Arabic and Persian go through the same reordering as Hebrew - the algorithm is script agnostic -
-and additionally through the shaper, because they are cursive: a contiguous run in one cursive
-script is shaped as a run so each letter takes its initial, medial, final or isolated form.
+Arabic and Persian go through the same reordering as Hebrew, because the algorithm is script
+agnostic, and additionally through the shaper, because they are cursive: a contiguous run in one
+cursive script is shaped as a run so each letter takes its initial, medial, final or isolated
+form.
Render any of them yourself. The example runs a command in a real pty and draws the result with
this terminal's own CPU backend, so it needs no window and no display:
@@ -312,17 +297,17 @@ a vendoring accident fails loudly instead of quietly measuring less.
reference-vs-property form it uses needs its own harness. Stated rather than counted, because a
number nothing computes is not evidence.
-The suite caught a genuine bug on its first run: the
-fast path that skipped the algorithm for plain text ignored the base direction, and under an RTL
-base even a row of neutrals resolves to level 1 and reverses.
+The suite caught a genuine bug on its first run: the fast path that skipped the algorithm for
+plain text ignored the base direction, and under an RTL base even a row of neutrals resolves to
+level 1 and reverses.
### Where it lives, and why that is the whole design
**Bidi is in the renderer and never in the core.** Reordering in the core would break cursor
addressing, because a cursor-addressed TUI has no mapping for where its cursor went after a
reorder. It would also make every RTL line diverge from the differential oracle by construction,
-deleting the only correctness signal this project has. Slice 5.5 landed reordering with the
-corpus untouched at 78/78, which is that separation demonstrated rather than asserted.
+deleting the only correctness signal this project has. Reordering landed with the corpus
+untouched, which is that separation demonstrated rather than asserted.
### Fonts, and what each script needs
@@ -334,7 +319,7 @@ stack rather than by the reordering.
| Latin, box drawing, powerline, Nerd icons | **JetBrains Mono NF** (SIL OFL 1.1) | ships inside the app; leads, so the cell box is its advance |
| geometric shapes | Menlo | ships with macOS; 96/96 where the lead is 43/96 |
| Hebrew | **Cousine** (SIL OFL 1.1) | ships inside the app; monospaced, GPOS attaches niqqud to its base, marks carry zero advance so a pointed cluster stays one cell |
-| Arabic, Persian | **Kawkab Mono** (SIL OFL 1.1) | ships inside the app; covers both blocks and joins correctly. It does **not** fix the grid - see below |
+| Arabic, Persian | **Kawkab Mono** (SIL OFL 1.1) | ships inside the app; covers both blocks and joins correctly |
| Arabic fallback | SF Arabic, Geeza Pro | ship with macOS, so Arabic and Persian render on a bare machine |
The three bundled faces ship inside `Termisu.app`; `assets/fonts/README.md` records why each one
@@ -343,20 +328,13 @@ is there and what it is licensed under. They were `~/Library/Fonts` lookups desc
step nobody performs on a fresh machine. A user-installed copy still wins, so an operator who
has their own build of a bundled family keeps it.
-Until 2026-08-07 the stack was `Menlo -> Miriam Mono CLM -> Arial Hebrew` - Menlo led and Miriam
-was the Hebrew face until 2026-08-25 - and none of the three carries
-the Arabic block, so every Arabic and Persian codepoint drew as a **blank cell** while the bidi
-algorithm reordered them perfectly. Correct algorithm, empty row, no error anywhere. It was found
-by rendering the sheet above across three scripts and looking at it, not by a test, and
-`arabic_and_persian_resolve_somewhere_in_the_stack` is that omission turned into one.
+Until 2026-08-07 the stack was `Menlo -> Miriam Mono CLM -> Arial Hebrew`, and none of the three
+carries the Arabic block, so every Arabic and Persian codepoint drew as a **blank cell** while the
+bidi algorithm reordered them perfectly. Correct algorithm, empty row, no error anywhere. It was
+found by rendering the sheet above across three scripts and looking at it, not by a test.
-Coverage alone was not the fix. Adding a face stopped the blank cells and left Arabic sitting off
-the grid, so `a_monospaced_arabic_face_outranks_the_proportional_ones` pins the ordering and
-checks that the monospaced face is the one which actually answers rather than merely the one
-listed first.
-
-**And a monospaced face is still not enough**, which this file claimed otherwise for a day.
-Installing one does not put Arabic on the grid. Measured at 32px against a 19px cell:
+**A monospaced face is not enough**, which this file claimed otherwise for a day. Measured at
+32px against a 19px cell:
| codepoint | face that answers | advance |
|---|---|---|
@@ -364,8 +342,8 @@ Installing one does not put Arabic on the grid. Measured at 32px against a 19px
| `א` | Miriam Mono CLM, the Hebrew face at the time; Cousine advances identically | 19.20px |
| `ب` | **Kawkab Mono** | **22.40px** |
-Monospaced is a property of a face on its own - uniform advance within itself. A terminal grid
-needs something else entirely: an advance equal to the **primary** face's, and no font ships
+Monospaced is a property of a face on its own: uniform advance within itself. A terminal grid
+needs something else entirely, an advance equal to the **primary** face's, and no font ships
promising that. Miriam Mono matching Menlo to 0.07px is luck rather than design, and it is the
whole reason Hebrew never showed this symptom and Arabic always did: a letter overhanging its
cell, and because a run paints in logical order, on a right-to-left row that spill lands on a cell
@@ -373,10 +351,10 @@ already painted and never cleared. An empty space beside an Arabic letter kept 5
its neighbour.
**Fixed 2026-08-08.** Each fallback face is rasterised and shaped at a size whose advance fits one
-cell - `32 * 19 / 22.46 = 27.07px` for Kawkab. Uniform scaling, so letter shapes are preserved,
-which is what separates it from the two alternatives that were rejected on measurement: scaling a
-run horizontally distorts the letters, and clipping each glyph to its cell cuts exactly the
-strokes that make cursive readable.
+cell: `32 * 19 / 22.46 = 27.07px` for Kawkab. Uniform scaling, so letter shapes are preserved,
+which is what separates it from the two alternatives rejected on measurement. Scaling a run
+horizontally distorts the letters; clipping each glyph to its cell cuts exactly the strokes that
+make cursive readable.
Before, three letters where each one's overhang pushes the next along and the last is clipped:
@@ -387,15 +365,7 @@ After, the same bytes through the same renderer:
Both are native-resolution crops of the same region, magnified with point sampling so no pixel is
-invented. Three exemptions keep the scaling where it belongs: the primary face defines the cell so
-it is never scaled; a face already inside the cell is left alone rather than nudged by fractions;
-and a full-em face is left alone because **an emoji spans two cells**, so its advance is correctly
-wider than one and fitting it to one would shrink every emoji in the terminal.
-
-The test that proves it was a characterisation pin asserting the defect, and was **promoted** to
-asserting zero - the promotion is the evidence, exactly as with a corpus case marked `diff`. Full
-record, including the four mutants killed and the two that survived, in
-[`docs/BACKLOG-2026.md`](docs/BACKLOG-2026.md).
+invented.
**Arabic letters take their contextual forms.** A contiguous run of cells in one cursive script
is shaped as a run, so each letter resolves to its initial, medial, final or isolated glyph, and
@@ -410,16 +380,13 @@ After, the same bytes through the same renderer, one variable changed:
-Both are this terminal's own CPU backend, which is byte-identical to the GPU one by
-specification, captured with `cargo run -p termisu-vt-render --example screenshot` and therefore
-needing no window and no display. The Hebrew and the Latin are unchanged between them, which is
-the control: a change that moved those would be a change to something other than joining.
+The Hebrew and the Latin are unchanged between them, which is the control: a change that moved
+those would be a change to something other than joining.
Until 2026-08-08 this rendered as isolated forms, and the note here blamed terminal grids. That
was wrong. Shaping was gated on a cluster having more than one codepoint, so a lone Arabic letter
-never reached the shaper at all and got the charmap's nominal glyph, which is the isolated form -
-a bug in this renderer, not a property every terminal shares. The diagnosis is kept in
-[`docs/plans/2026-08-07-arabic-joining.md`](docs/plans/2026-08-07-arabic-joining.md).
+never reached the shaper at all and got the charmap's nominal glyph, which is the isolated form:
+a bug in this renderer, not a property every terminal shares.
Hebrew coverage is pinned across the classes that appear in real text rather than one letter:
base letters, final forms, niqqud, the dagesh GSUB composes into its base, and punctuation.
@@ -432,14 +399,130 @@ fall back to the isolated forms drawn before. Wrong in a known way beats overlap
**Joining strokes do not always meet**, because each glyph is positioned in its own cell rather
than at the previous glyph's advance. The letters are in their correct joined forms, which is the
-part that makes Arabic readable. That is the real grid limit, and it is much smaller than the one
-this section used to claim.
+part that makes Arabic readable. That is the real grid limit.
+
+## Running agents in parallel
+
+The second reason this project exists. Everything here is built on explicit signals from the
+child, never on guessing at a byte stream.
+
+### A stable port block per workspace
+
+Git worktrees are the standard answer to running agents in parallel, and the number that keeps
+appearing is four to eight per developer. The isolation works for files and does nothing for
+anything that is not a file. Every dev server defaults to 3000: agent A starts one, agent B dies
+on `EADDRINUSE`, and agent B reports a broken build that is not broken.
+
+The formula everyone hand-rolls is `PORT = BASE + INDEX * 10 + OFFSET`, plus a script that
+rewrites a `.env` per tree, and it does not survive being moved to CI.
+
+Termisu hands the base down. Every pane's child gets:
+
+```sh
+TERMISU_PORT_BASE # the first port of this workspace's block, 20000..39990
+TERMISU_PORT_SPAN # how many ports the block holds, 10
+```
+
+```js
+// vite.config.js
+const base = Number(process.env.TERMISU_PORT_BASE ?? 3000)
+export default { server: { port: base }, preview: { port: base + 1 } }
+```
+
+**Derived from the workspace path, never handed out in sequence.** A base assigned in launch
+order moves whenever the panes open in a different order, and then a bookmark, a proxy rule and
+a database URL all rot. The same worktree is the same block forever and on every machine, with no
+state kept anywhere. A worktree reached through a symlink is the same workspace, which matters on
+macOS where `/tmp` is a symlink to `/private/tmp`.
+
+**`PORT` itself is deliberately not set.** Silently moving a dev server off the port its operator
+typed is a bigger surprise than a variable nothing reads yet.
+
+**It is a hash, so collisions are possible and the number is written down rather than implied.**
+With N workspaces the chance any two share a block is about `1 - exp(-N(N-1)/2/2000)`: 0.3% at
+four worktrees, 1.4% at eight. Removing that entirely would need a registry file, which is state
+on disk that has to be cleaned up and is wrong the moment a worktree moves.
+
+The hash took three measured attempts, and the spread gate is the only reason that was visible.
+Sibling worktrees differ in their **last** byte, which is the adversarial input for a cheap hash:
+
+| derivation | distinct blocks out of 64 |
+|---|---|
+| FNV-1a, `hash % BLOCKS` | 54 (a fair hash gives 63) |
+| FNV-1a, high half | 3 |
+| FNV-1a + `fmix64` + multiply-shift | **64** |
+
+Neither slice of the raw hash was good. The fix was an avalanche step, not a different set of
+bits.
+
+### The dock knows which agent needs you
+
+
+
+Rendered offscreen by --shot-sidebar: expanded, collapsed to its
+28pt rail, and parked mid-scroll at fourteen sessions.
Above quiet, below ringing. Measured rather than eyeballed, because a 140ms +fade cannot be caught by hand: 142.8 mean brightness against 134.1.
+ +## No account, no telemetry, no network + +Termisu never talks to a server. Not to check a licence, not to phone an analytics endpoint, not +to see whether there is an update. There is nothing to sign in to, there is no telemetry to turn +off, and the whole thing runs with the wifi off. + +That is a fairly ordinary thing to claim and a fairly common thing to be wrong about, so it is +gated rather than asserted: + +- **`crates/host/tests/no_network.rs`** reads the resolved dependency graph out of `Cargo.lock` + and fails if anything in it can open a socket. This is the way the claim would actually break: + nobody writes `TcpStream::connect` in a terminal on purpose, but a convenience crate arrives + for an unrelated reason and drags an async runtime and a TLS stack in behind it. 241 crates + resolve today and none of them are networked. +- **`--smoke-offline`** covers the one part that could: the review panel is a `WKWebView`, so + WebKit is linked into the process whether we like it or not. What makes the claim true anyway + is `PanelNavigation`, which permits exactly one navigation, the local document the panel was + handed, and refuses every other scheme, path and navigation type. A remote URL carrying that + same path is refused too, which is a case a mutant found rather than a case anyone thought of. + +Two things that are honestly **not** covered by either gate. The shell you run inside Termisu is +your shell and can do whatever you tell it to; the terminal does not police its child. And macOS +itself may talk to Apple about a signed binary the first time it runs one, which is Gatekeeper, +not us. + +**The licence is AGPL-3.0**, so this is checkable rather than a promise. The audit is `grep`, and +the two gates above run on every build. ## How it compares @@ -469,19 +552,44 @@ I have not audited the others, and I would rather leave a cell empty than fill i ## Architecture -Three rules, enforced by crate boundaries rather than by convention. +Four rules, enforced by crate boundaries rather than by convention. + +1. **The core is a pure, deterministic state machine.** Bytes in, grid mutations out. No pty, no + GPU, no clock, no I/O. That is what makes headless CI and differential testing possible at + all, and I/O lives in exactly one crate which is not the core. +2. **Bidi lives in the renderer, never in the core.** Reordering there would break cursor + addressing and delete the differential signal at the same time. +3. **No terminal bytes in a webview.** Not pixels, not keystrokes, not frames. Document-shaped + panels get a browser engine; the terminal surface never does. Renting `xterm.js` would mean + running a second VT parser in front of ours, which would make every test here measure code + nothing calls. +4. **A policy a gate cannot reach is a policy that has never been asserted.** Four have been + pulled out of live objects for exactly this reason, after one of them turned out to be wrong + in a way nothing could see: `LastPaneOutcome`, `WorkStateRule`, `ChromeTransition` and + `PanelNavigation`. -1. **The core is a pure, deterministic state machine.** Bytes in, grid mutations out. No pty, no GPU, no clock, no I/O. That is what makes headless CI and differential testing possible at all, and I/O lives in exactly one crate which is not the core. -2. **No terminal bytes in the webview.** Not pixels, not keystrokes, not frames. The chrome strip is a browser engine drawing documents. Renting `xterm.js` would mean running a second VT parser in front of ours, which would make every test here measure code nothing calls. -3. **One wgpu surface for all panes.** Pane count is a Rust-side fact. If the webview needs to know it, the design is wrong. +``` +crates/vte the vendored tokenizer, plus APC dispatch +crates/core the parser and the grid. No I/O, no clock +crates/snapshot the typed grid every other layer reads +crates/frame the seqlock frame channel, and bidi reordering +crates/render glyphs, atlas, shaping, CPU and wgpu backends +crates/pty the only crate that touches the operating system +crates/abi the C surface: libtermisu-vt.a, the libghostty-vt drop-in +crates/abi-types the C layouts, pinned byte for byte against the real library +crates/difftest the differential harness and its oracle +crates/host the embedder surface: panes, agents, worktrees, launch +crates/markdown pipe tables laid out as box drawing. Built, wired to nothing yet +swift/ the macOS app: window, chrome, panels, input +``` ## Features -**Terminal core** +### Terminal core -- Full VT parsing on a vendored [vte](https://github.com/alacritty/vte) fork (one addition: APC dispatch) +- Full VT parsing on a vendored [vte](https://github.com/alacritty/vte) fork, one addition: APC dispatch - True colour; styled underlines, single / double / curly / dotted / dashed, with SGR 58 underline colour -- OSC 8 hyperlinks whose stamps survive scroll and resize; OSC 52 clipboard write; OSC 9 and OSC 777 notifications; bell +- OSC 8 hyperlinks whose stamps survive scroll and resize; OSC 52 clipboard write; OSC 9 and OSC 777 notifications; `BEL` - OSC 7 working directory, stored exactly as reported, including two rules the reference implementation's own source gets wrong - OSC 133 semantic regions (prompt, input, output), the rails everything else rides - DSR / DA / DECRQM query replies through the pty, so programs that probe get real answers @@ -493,80 +601,127 @@ Three rules, enforced by crate boundaries rather than by convention. - Grapheme clusters from day one; wide glyphs and spacer tails; VS16 emoji presentation - Paged scrollback with an exact row budget -**Rendering** +### Rendering - Glyph atlas with damage-driven redraw; a CPU reference backend and a wgpu compute backend, byte-equal to each other by specification -- Colour emoji (sbix), synthesized block mosaics, per-glyph font fallback -- **Bidi in the renderer**: UBA reordering at 91,707 of 91,707 BidiCharacterTest cases, mirrored brackets in RTL runs, niqqud placed by GPOS shaping. In the renderer and never in the core, because reordering there would break cursor addressing +- **Bidi in the renderer**: UBA reordering at 91,707 of 91,707 `BidiCharacterTest` cases, mirrored brackets in RTL runs, niqqud placed by GPOS shaping +- Per-glyph font fallback, with each fallback face scaled so its advance fits the cell the primary face defines +- Synthesized block mosaics - Font ligatures behind a substitution guard, so a non-ligating font renders byte-identically with the feature on or off - Selection drawn as a tint blended over the finished row rather than as a cell background, which would be erased by the next cell's -**Input** +#### Emoji are glyphs, not stickers -- Kitty keyboard protocol: the full flag stack, CSI-u encoding, `modifyOtherKeys`, byte-compared against the reference encoder across 135,216 cases with zero divergent -- SGR mouse (1000 / 1002 / 1003 / 1006) plus alternate scroll, against a ~65k-case differential matrix; the wheel routes by mode to report, arrow keys, or viewport -- Chords match physical keys, so a Hebrew layout keeps every one of them + + +A coloured sticker is not a terminal glyph. The artwork's own colours are dropped and it is +painted in the cell's foreground, down the same blit path as a letter. Dropping the face instead +was rejected: the codepoint still occupies its cells, so a removed face leaves a hole the line +reflows around. -**The Tauri host** (`crates/termisu`) - a window with panes. Not a workbench yet: nothing here shows -you several agents at once, which is the whole point of the word and the reason it is not used. +- Alpha alone is a filled silhouette, so the artwork's **luminance** carves the interior. It is + stretched across the glyph's own range first, because emoji are authored against white and an + unstretched mask reads as mud. +- A floor on every opaque pixel, so a black heart does not vanish on a dark ground. +- Rec.709 in integers, so the CPU and GPU backends still receive byte-identical pixels. +- **Every emoji is one size**: a square of one cell advance, sitting on the text baseline. + Measured at 16px, cell 10x22: `M` inks 8x12, `x` inks 8x9, an emoji is 10x10, and all three + share a bottom edge. The grid never moves, because a `VS16` cluster stays one cell wide, which + the corpus pins against the reference. +- **Known limit**: the polarity assumes ink is lighter than ground, true of every scheme shipped + today. On a light theme an emoji reads as a negative. -- One window opening with one pane, split right with cmd+D, with a real gutter between panes and a rule drawn into it in the same render pass. Splitting stops before a pane becomes too narrow to use rather than continuing until something breaks -- A pane whose child has exited closes itself and gives its width back to the survivors; the last one closing closes the window -- Click-drag, double-click and triple-click selection, cmd+A, cmd+C. cmd+C is conditional on purpose: with nothing selected it falls through to the child as `^C` and can still interrupt a command. Shift takes the pointer back from a child that has captured the mouse -- cmd+V bracketed paste, cmd+= / cmd+- / cmd+0 live zoom across every pane, cmd+click hyperlinks +### Input + +- Kitty keyboard protocol: the full flag stack, CSI-u encoding, `modifyOtherKeys`, byte-compared against the reference encoder across **135,216 cases** with zero divergent +- SGR mouse (1000 / 1002 / 1003 / 1006) plus alternate scroll, against a ~65k-case differential matrix; the wheel routes by mode to report, arrow keys, or viewport +- **Chords match physical key codes, never characters**, so a Hebrew layout keeps every one of them. This is also why the pane cannot be SwiftUI: `KeyPress` carries a `KeyEquivalent`, which is a character + +### The app + +macOS, AppKit, one window. The reasoning is written down in +[`docs/decisions/2026-08-25-appkit-not-swiftui.md`](docs/decisions/2026-08-25-appkit-not-swiftui.md); +the short version is the keyCode line above, plus the geometry gates, which are assertable only +because the layout types exist apart from the views. + +- **One bar, and it starts shut.** A collapsible dock down the right-hand side of the window, listing every session with the directory and branch it is in. `cmd+B` toggles it, on the physical key, which is free in a terminal because readline and every TUI reach for `ctrl+B` +- **It collapses to a 28pt rail rather than to nothing.** A sidebar that collapses to zero has a state you can enter and not leave, and a chord is no way out for anyone who has not been told the chord exists. The non-idle state dots stack down the rail, so closing it does not hide which agent is working +- **The dock scrolls**, so no session is unreachable. It used to stop building rows past a capacity limit, silently, with no scrollbar and no ellipsis +- **The chrome takes the terminal's own background** and paints only white at an alpha over it. When themes land, one file is where they plug in +- **Closing the last tab opens a shell, it does not quit.** `cmd+W` says close this tab; answering it by quitting is the app deciding you meant `cmd+Q`. A child that exited on its own still terminates, because `exit` and `logout` are the universal "done with this terminal" gesture +- Splits with a real gutter, a pane whose child exited closing itself and giving its width back, and splitting that stops before a pane becomes too narrow to use +- Click-drag, double-click and triple-click selection, `cmd+A`, `cmd+C`. `cmd+C` is conditional on purpose: with nothing selected it falls through to the child as `^C` and can still interrupt a command +- `cmd+V` bracketed paste, `cmd+=` / `cmd+-` / `cmd+0` live zoom across every pane, `cmd+click` hyperlinks +- A `cmd+K` command palette, OSC 133 block navigation with a gutter, git worktree workspaces, and an SSH host list read from your own `ssh_config` - Agent launcher: ten agent CLIs with the fields that actually differ, a PATH probe that measures availability rather than trusting a table, spawn-observe-retry with counted backoff, and a guard that refuses an auto-approve bypass rather than stripping it - `~/.termisu/config.toml`: font size, family, ligatures, shell, themes, auto-direction, and `reports`, off by default because it lets a program read back what is on your screen -**There was a second host, in Swift, and it was deleted on 2026-08-08.** It carried tabs, a -cmd+K palette with TOML workflows, fish-style autosuggestions, OSC 133 blocks and git-worktree -workspaces, and it was kept for a long time as the parity target the Tauri port was measured -against - a port with no reference is a rewrite with extra steps. It went once the Tauri host -could produce an app on its own, because a reference nobody builds is a liability rather than a -reference. `git log -- swift/` still has all of it. - ## Status Working as a terminal, and in daily use on macOS, Apple Silicon. Pre-1.0, no stability promises. -**What it is not: a workbench.** There is no session map, no canvas, no way to see what several -agents are doing at once. The host is a window with panes and an agent launcher. The engine is -the part that is finished. The surface that would earn the word "workbench" is planned in -`docs/plans/` and not started. +**What is finished is the engine.** The core, the renderer, the pty, the C ABI and the +differential harness are the parts this project is about, and they are done to the standard the +gates describe. -Linux is compiled on every push (`cargo check -p termisu` on ubuntu-latest) and is otherwise -UNRUN: the GTK key and clipboard paths exist and no key has ever been pressed on a real Linux -machine. Windows is a separate slice and is not started - there is no POSIX pty there, so the pty -crate needs ConPTY. +**What is not built is a workbench.** There is no session map, no canvas, no way to see what +several agents are doing at once beyond the dock. The review panel renders documents and is +**read only**: editing from it needs a conflict model, undo, save semantics and an answer for the +agent editing the same file in the same second, and none of those is a diff viewer. Sessions do +not yet outlive the window, which is the one reason people stay on `tmux`. + +**The GUI layer is deliberately uncovered by the differential harness** and its debt is declared +per slice rather than hidden. Features landing there close as `untested - needs your eyes` unless +a picture was taken. + +Linux is compiled on every push (`cargo check`) and is otherwise **unrun**: the key and clipboard +paths exist and no key has ever been pressed on a real Linux machine. Windows is not started; +there is no POSIX pty there, so the pty crate needs ConPTY. ## Building -Requires Rust 1.93 or newer. +Requires Rust 1.93 or newer, and Xcode for the app. ```sh git clone https://github.com/Orellius/termisu.git cd termisu -cargo run -q -p termisu --bin termisu # run it +./scripts/build-app.sh # assemble, sign and install to ~/Applications +``` + +`build-app.sh` is the only supported install path. It takes the version from `git describe`, so +tag before you build. It also needs GNU `timeout` (`brew install coreutils`) and `librsvg` +(`brew install librsvg`) for the icon, and it fails loudly rather than shipping something wrong +if either is missing. + +The gates: + +```sh +cargo test --workspace # 822 tests +cargo run -p termisu-vt-difftest # 223 corpus cases, against libghostty-vt +./scripts/build-lib.sh # libtermisu-vt.a (the drop-in ABI, 28 exports) +./scripts/build-host.sh # libtermisu-vt-host.a (ABI plus embedder, 61 exports) +./scripts/build-swift.sh # the host, then 15 headless smokes ``` The rest: ```sh -cargo test --workspace # the gate: every test green -cargo run -p termisu-vt-difftest # the corpus, measured against libghostty-vt -./scripts/smoke-termisu.sh # host gate: no window, no synthesized input -./scripts/build-lib.sh # libtermisu-vt.a (the drop-in ABI) -./scripts/build-host.sh # libtermisu-vt-host.a (ABI plus embedder surface) -./scripts/build-app.sh # assemble, sign and install the app -sh scripts/demo-features.sh # the one-screen feature tour, inside the terminal +sh scripts/demo-features.sh # the one-screen feature tour, inside the terminal +./scripts/make-signing-identity.sh # a stable local signing identity, once per machine ``` Running the differential harness additionally needs a Ghostty checkout to build its oracle from, -pointed at by `TERMISU_VT_ORACLE_SRC`. See [CONTRIBUTING.md](CONTRIBUTING.md) for that and the rest -of the development setup. +pointed at by `TERMISU_VT_ORACLE_SRC`. See [CONTRIBUTING.md](CONTRIBUTING.md) for that and the +rest of the development setup. + +**On signing.** `codesign -s -` makes the designated requirement a bare hash of the code, so every +rebuild is a *different application* to macOS and it re-asks for every permission. +`make-signing-identity.sh` creates a stable local identity and fixes that. It is not Developer ID +and it is not notarization, which is what a public release would need. ## The names -- **Termisu** is the product: the app in `crates/termisu`. +- **Termisu** is the product: the macOS app, built from `swift/` over the engine. - **`termisu-vt`** is the engine, and it keeps its name. The VT core, pty, renderers and C ABI are the part somebody else could embed, so the crates carry the engine's name while the repository carries the product's. @@ -574,6 +729,8 @@ of the development setup. `libghostty-vt`, meant to sit behind somebody else's GUI, then grew its own window, renderer, panes and agent launcher. The ABI promise is still real and still tested: you can link `libtermisu-vt.a` where `libghostty-vt` was expected. +- The product was **Mind2t** until 2026-08-25 (terminal plus tiramisu) and the repository was + **ruuah-vt** until 2026-08-06. GitHub redirects the old URLs. ## Contributing @@ -599,5 +756,5 @@ derivation rather than transcription. - [Ghostty](https://ghostty.org) (MIT), the reference implementation this engine is measured against at test time, and the origin of the ABI. - [vte](https://github.com/alacritty/vte), the tokenizer this project vendors and extends. - [esctest2](https://github.com/ThomasDickey/esctest2) (GPL-2.0, test time only), the conformance suite run against our own pty. -- [Cousine](https://github.com/googlefonts/cousine), the Hebrew face, and [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) via [Nerd Fonts](https://github.com/ryanoasis/nerd-fonts), the lead. +- [Cousine](https://github.com/googlefonts/cousine), the Hebrew face, [Kawkab Mono](https://makkuk.com/kawkab-mono/), the Arabic face, and [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono) via [Nerd Fonts](https://github.com/ryanoasis/nerd-fonts), the lead. - [Culmus](https://culmus.sourceforge.io), for Miriam Mono CLM. It was the Hebrew face until 2026-08-25 and is still the GPOS control the mark-placement tests are measured against. diff --git a/docs/images/dock-states-20260826.png b/docs/images/dock-states-20260826.png new file mode 100644 index 0000000000000000000000000000000000000000..1bdbfc3cfd3b47111279c9a6d1c045b26a936423 GIT binary patch literal 26658 zcmcG0by!qg+b=Q5P%=mg(gG5Kfb`HHN_R*}2-1SY(9#_W2nZ4)DV@^Y0wO7$(%pU5 z_`HwrcjDi3IbP^yX3yHO*8Qt{hbSw`;9-+vqoAPRJ$ovpih_csj)H