All 42 libraries

SugarVterm

In-memory virtual terminal emulator

vt500-parser cell-grid snapshot-tests no-pty

SugarVterm code coverage

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-server is pairable: it can route session bytes into feed() to run TUIs without a real PTY, but no integration ships in either package — the wiring is yours to write.

Source & demos

Try the quickstart →

API

ClassMethodDescription
Terminalnew(cols, rows, scrollbackSize)Create a virtual terminal (the Terminal::create() factory is deprecated: it accepts no scrollbackSize)
Terminalfeed(bytes)Feed ANSI bytes to terminal
Terminalscreen()Get current cell grid
Terminalcursor()Get cursor position
Terminalmode()Get terminal mode state (includes autoWrap)
TerminalwindowTitle()Get window title from OSC — verbatim attacker text, sanitize before display
TerminalwithScrollbackSize(n)New terminal with scrollback buffer size N
Screencell(row, col)Get cell at position (out-of-bounds in either coordinate returns the empty cell)
Screenscrollback()Get scrollback buffer (ring buffer of scrolled-off rows)
Cellgrapheme, sgr(), combining, foreground(), background()Cell content, style, and combining marks (sgr() always returns an Sgr; the raw $sgr property is ?Sgr)
CellwithCombining(string)New cell with additional combining marks appended
ModeautoWrap, syncUpdate, withAutoWrap(bool)DECAWM auto-wrap and synchronized-output (DEC 2026) state
SgrunderlineStyle, withUnderlineStyle(UnderlineStyle)SGR underline style (None/Single/Double/Curly/Dotted/Dashed)
UnderlineStyleNone / Single / Double / Curly / Dotted / DashedEnum — 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.

A scripted ANSI byte stream fed to a virtual terminal; the cell grid prints back showing colors, cursor position, and a hyperlink span

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, run php examples/feed-and-screenshot.php.