SugarVterm
In-memory virtual terminal emulator
Feed an ANSI byte stream in, query a cell grid + cursor + mode state out — without ever spawning a real terminal. Built on a Paul Williams VT500 state machine.
Install
composer require sugarcraft/sugar-vterm
Quickstart
use SugarCraft\Vterm\Terminal\Terminal;
$term = Terminal::new(cols: 80, rows: 24);
$term->feed("\x1b[1;31mHello\x1b[0m world");
$screen = $term->screen();
$screen->cell(0, 0)->grapheme; // 'H'
$screen->cell(0, 0)->sgr()->bold; // true (sgr() never null; the $sgr property is ?Sgr — null on the renderer path)
$screen->cell(0, 0)->foreground(); // a Color (kind 1 = Indexed16, value 1 — 16-color red)
$term->feed("\x1b]2;Demo\x07");
$term->windowTitle(); // 'Demo'
$term->feed("\x1b[?1049h");
$term->mode()->altScreen; // true
What's in the box
VT500 parser15-state Paul Williams state machine, implemented upstream in sugar-ansi-parser and imported here — this lib's
src/Parser/ holds the handler bridges only. Handles partial input across feed() calls and CSI subparameters (: separator per VT500 spec).Full SGR16-color, bright, 256-color, and truecolor for fg + bg. The emulator pen tracks bold / italic / underline / strikethrough / blink / reverse / dim / hidden toggles and SGR underline styles 4:0–4:5 (single / double / curly / dotted / dashed); the renderer paints the five cell-attribute bits — bold, italic, underline (every style collapsed onto one bit), reverse, strikethrough — while blink, dim and hidden are tracked but not painted. BCE is always on — erase fills inherit the current background; there is no
?12 gate.Cursor + erase + scrollCUU/CUD/CUF/CUB/CUP/CHA/VPA, DECSC/DECRC, EL/ED/ECH/DCH/ICH, SU/SD, IND/RI/NEL.
DEC modes1049 alt screen + cursor save, 25 cursor visibility, 1000/1002/1003/1006 mouse, 2004 bracketed paste, 2026 synchronized output (batch queue + flush on disable), 7 auto-wrap (DECAWM).
OSC dispatch0/1/2 window title, 4 palette set, 8 hyperlinks (per-cell attribution), 52 clipboard write/read events. Every payload is attacker-supplied text kept VERBATIM — consumers sanitize before display or onward propagation.
Width-aware + combiningCJK + most emoji take 2 cells with a continuation marker. Zero-width runes — anything sugar-core
Width::string scores 0 (combining diacritics, variation selectors, joiners) — attach to the preceding cell via Cell::$combining so composed graphemes render correctly in a single column.Scrollback bufferRing buffer (default 1000 rows) captures scrolled-off content. Access via
Screen::scrollback(). Configure size with Terminal::withScrollbackSize(). Erased by CSI 3 J.Trust boundaryEngineered for hostile byte streams: stored strings cap at 64 KiB, event logs at 1024 entries (drop-oldest rings), the DEC 2026 queue replays past 16384 pending cells. Nothing leaves the grid's text unsanitised — stored side-channels (window titles, OSC 8 hyperlinks, OSC 52 payloads) are kept VERBATIM; consumers sanitize before display (
Sanitize::untrusted()). Full trust contract.Use it for
- Snapshot tests — drive any TUI's
view()through SugarVterm and assert on cell-grid state instead of raw byte strings. - Recording & replay — capture
feed()input and replay deterministically. - Headless SSH sessions —
sugar-ssh-serveris pairable: it can route session bytes intofeed()to run TUIs without a real PTY, but no integration ships in either package — the wiring is yours to write.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Originally inspired by charmbracelet/x/vt (Go); SugarCraft is developed as a native PHP project.
API
| Class | Method | Description |
|---|---|---|
| Terminal | new(cols, rows, scrollbackSize) | Create a virtual terminal (the Terminal::create() factory is deprecated: it accepts no scrollbackSize) |
| Terminal | feed(bytes) | Feed ANSI bytes to terminal |
| Terminal | screen() | Get current cell grid |
| Terminal | cursor() | Get cursor position |
| Terminal | mode() | Get terminal mode state (includes autoWrap) |
| Terminal | windowTitle() | Get window title from OSC — verbatim attacker text, sanitize before display |
| Terminal | withScrollbackSize(n) | New terminal with scrollback buffer size N |
| Screen | cell(row, col) | Get cell at position (out-of-bounds in either coordinate returns the empty cell) |
| Screen | scrollback() | Get scrollback buffer (ring buffer of scrolled-off rows) |
| Cell | grapheme, sgr(), combining, foreground(), background() | Cell content, style, and combining marks (sgr() always returns an Sgr; the raw $sgr property is ?Sgr) |
| Cell | withCombining(string) | New cell with additional combining marks appended |
| Mode | autoWrap, syncUpdate, withAutoWrap(bool) | DECAWM auto-wrap and synchronized-output (DEC 2026) state |
| Sgr | underlineStyle, withUnderlineStyle(UnderlineStyle) | SGR underline style (None/Single/Double/Curly/Dotted/Dashed) |
| UnderlineStyle | None / Single / Double / Curly / Dotted / Dashed | Enum — CSI 4:N map (4:0–4:5) |
Demos
VHS-recorded GIFs of every example shipped with the library. Regenerated automatically on every push that touches the source.
Feed and screenshot
An ANSI byte stream feeds into a Terminal; the cell grid prints back as a screenshot, with window title, cursor position, and hyperlink span. The GIF autoplays and cannot be paused by reduced-motion CSS — for a still, runphp examples/feed-and-screenshot.php.