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`.

14The parser supports VT100 G0/G1 ASCII and DEC Special Graphics designation,

15SI/SO selection, and saved-cursor restoration of those character sets. This

16renders tmux/ncurses line drawing as Unicode in the grid, scrollback and row

17runs. Ordinary Unicode output is preserved.

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

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

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

23## Layout

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

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

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

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

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

31## Cell model

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

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

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

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

37`#x1000000 + #xRRGGBB` truecolor.

39## Trust boundary

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

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

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

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

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

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

49```

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

51sigil build --redirects dev-redirects.sgl

52sigil test --redirects dev-redirects.sgl

53```

55## Not here

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

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