README.md — sigil-vt

1# sigil-vt

3The native VT/ANSI terminal core for the Sigil ecosystem — a VT100/xterm-subset

4terminal emulator in C: an incremental byte stream → a damage-tracked

5`int32[4]`-per-cell grid, with scrollback, cursor-report / device-attribute

6replies, an out-of-band event queue (title / bell / OSC-52 clipboard), mouse-mode

7flags, and native style-merged **row-run** extraction (the render seam).

9It is the shared native foundation for terminal handling across the ecosystem:

10slate's `(slate term)` rides it as a thin façade (byte-identical `take-frame`),

11and `(sigil tui grid)` will ride it in M3. See the design note

12`topics/sigil-terminal-handling-design`.

14This is the native reimplementation of slate's `(slate term)` emulator — **the

15Sigil emulator is the spec**; `native/vt.c` reproduces its semantics cell-for-cell,

16proven by `test/vt-test.sgl` (a faithful port of slate's `test/term-test.sgl`).

18## Layout

20- `native/vt.c` — the C core (parser state machine + grid + damage/scrollback/

21 replies/events + row-runs). Registered as `%vt-*` builtins in module `(sigil vt)`.

22- `src/sigil/vt.sgl` — the `(sigil vt)` Scheme surface (thin wrappers + the

23 public API, shaping damage into a dict etc.).

24- `test/vt-test.sgl` — the conformance suite.

26## Cell model

28Flat `int32_t` buffer, cell `(row,col)` at `((row*cols+col)*4)`:

29`[codepoint, attrs, fg, bg]`. Attr bits: bold 1, dim 2, italic 4, underline 8,

30blink 16, inverse 32, hidden 64, strike 128; high bits reserved for

31wide/continuation (wcwidth deferred). Colors: `-1` default, `0..255` indexed,

32`#x1000000 + #xRRGGBB` truecolor.

34## Trust boundary

36Terminal bytes are UNTRUSTED program output. The parser converts arbitrary bytes

37into a CLOSED vocabulary of grid operations — no escape sequence executes

38anything, reaches an eval, or emits markup. Params/sub-params/OSC accumulators

39are fixed-capacity; no allocation is sized by input params. The core never calls

40back into Scheme. Fuzzed + ASan/UBSan-clean on `vt-feed-bytes!` (see `spike/`).

42## Build / test (development, against a local monorepo checkout)

44```

45sigil deps install --redirects dev-redirects.sgl

46sigil build --redirects dev-redirects.sgl

47sigil test --redirects dev-redirects.sgl

48```

50## Not here

52No `vt-diff` (the grid-diff ANSI emitter) — deferred to M3 (the sigil-tui

53revival). The cell repr is designed to account for it.