sugarcraft/candy-vt

In-memory virtual terminal emulator — parses ANSI byte stream into a cell grid.

Maintainers

Package info

github.com/sugarcraft/candy-vt

Documentation

pkg:composer/sugarcraft/candy-vt

Statistics

Installs: 14

Dependents: 3

Suggesters: 1

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

dev-master 2026-05-18 02:36 UTC

Requires

Requires (Dev)

MIT 9e88e4a09d5bef2c2fc0a0ef271ac3f5ff31fdd3

  • Joe Huss <detain.woop@interserver.net>

terminalansivt100xtermtuisugarcraft

This package is auto-updated.

Last update: 2026-05-18 02:39:58 UTC

README

candy-vt

CandyVt

CI codecov Packagist Version License PHP

In-memory virtual terminal emulator — parses an ANSI byte stream into a cell grid with cursor, mode, SGR style, and hyperlink state.

Mirrors charmbracelet/x/vt.

Install

composer require sugarcraft/candy-vt

Quickstart

use SugarCraft\Vt\Terminal\Terminal;

$vt = Terminal::create(cols: 80, rows: 24);

// Feed raw ANSI bytes from a terminal program.
$vt->feed("\x1b[1;1H\x1b[31mmhello\x1b[0m");

// Inspect the rendered screen.
$screen = $vt->screen();
foreach ($screen->lines() as $row => $line) {
    echo "$row: $line\n";
}

// Current cursor position.
$cursor = $vt->cursor();
echo "cursor at {$cursor->row},{$cursor->col}\n";

Architecture

Layer Class Role
Facade Terminal\Terminal Owns a Parser + ScreenHandler; feed() drives bytes in
Parser Parser\Parser VT500 state machine — Paul-Williams algorithm, handles partial input
Handler Handler\ScreenHandler Dispatches parser actions to Buffer / Cursor / Sgr / Mode
Screen Screen\Screen Immutable snapshot — read current grid after feeding bytes
Buffer Buffer\Buffer Cell grid — rows × cols of styled grapheme cells
Cursor Cursor\Cursor Position + visibility + origin mode tracking
SGR Sgr\Sgr Current graphics rendition: foreground / background / attributes
Mode Mode\Mode Dec private mode (DECSET/DECRST) flags
Hyperlink Hyperlink\Hyperlink OSC 8 URL + id tracker

Parser handlers

Each handler translates parser actions into handler state mutations:

  • CursorHandler — CUP, HVP, CUU/CUD/CUF/CUB, CR, LF/VT/FF, BS, RI, HOME, DECSC/USC
  • SgrHandler — SGR sequences (colour + attributes)
  • EraseHandler — ED, EL, ECH, DECSCA
  • ScrollHandler — SU, SD, DECSTBM
  • ModeHandler — DECSET/DECRST/DECMODESET/DECMODERST
  • TabHandler — TBC, HTS
  • OscHandler — OSC window title, hyperlink, colour palette
  • ScreenHandler — orchestrates all of the above; owns the Buffer

Diff API

After feeding bytes, snapshot the screen and compare:

$before = $vt->screen();
$vt->feed($moreBytes);
$after  = $vt->screen();

foreach ($before->diff($after) as $change) {
    [$row, $col, $prev, $next] = $change;
    echo "{$row},{$col}: '{$prev->grapheme}' → '{$next->grapheme}'\n";
}

Test

cd candy-vt && composer install && vendor/bin/phpunit

Related