SugarCraft — CandyInput

🍬 CandyInput

Terminal escape sequence decoder

pioneering (no upstream) input foundation-package

The missing input layer for PHP TUI. EscapeDecoder consumes raw TTY bytes and emits typed Event objects — plain keys, Kitty keyboard protocol, SGR 1006 mouse, focus events, and bracketed paste. Reentrant and fuzz-friendly. Unblocks sugar-readline migration to real-TTY input (step-21).

Install

composer require sugarcraft/candy-input:@dev

Quickstart

use SugarCraft\Input\EscapeDecoder;
use SugarCraft\Input\Driver\StreamInputDriver;
use SugarCraft\Input\Event\KeyEvent;
use SugarCraft\Input\Event\MouseEvent;

$decoder = new EscapeDecoder();
$driver  = new StreamInputDriver(STDIN);

while (true) {
    $event = $driver->read();
    if ($event === null) continue; // non-blocking empty or EOF

    match (true) {
        $event instanceof KeyEvent  => handleKey($event),
        $event instanceof MouseEvent => handleMouse($event),
        default                      => handleOther($event),
    };
}

EscapeDecoder

decode(string $bytes): list<Event>Decode a byte buffer — emits 0+ Events; buffers partial sequences.

remainder(): stringGet unconsumed bytes that couldn't yet form a complete sequence.

reset(): voidClear the partial-sequence buffer.

InputDriver

read(): ?EventReturn the next Event, or null on EOF / non-blocking empty.

Event types

KeyEventkey, modifiers, raw — plain keys, F1-F12, arrows, Home/End/PgUp/PgDn, Insert, Delete, Backspace, Tab, Enter, Escape, Ctrl+letter

MouseEventx, y, button, action, modifiers — SGR 1006: press, release, drag, scroll

FocusEventgained — terminal window focus gained/lost (DECSET 1004)

PasteEventcontent — bracketed paste (CSI 200~ … CSI 201~), capped at 1 MiB

ResizeEventcols, rows — terminal resize

KeyModifier

Bitmask flags: Shift, Ctrl, Alt, Meta, Super, Hyper, CapsLock, NumLock. Combine with bitwise OR.

Use it for

Real-TTY input for sugar-readline — decode raw bytes instead of symbolic key names.
Interactive TUI programs — keyboard and mouse input without depending on a specific runtime.
Kitty keyboard protocol — disambiguation flags via CSI ?u, including key release events.
Safe paste handling — bracketed paste with 1 MiB cap prevents OOM from hostile input.
Foundation for any input-consuming lib — EscapeDecoder is leaf (no sugarcraft deps).

Source & demos

Try the quickstart →

API

Class	Method	Description
EscapeDecoder	decode(string $bytes): list<Event>	Decode byte buffer, buffer partials
EscapeDecoder	remainder(): string	Get unconsumed bytes
EscapeDecoder	reset(): void	Clear partial buffer
StreamInputDriver	read(): ?Event	Next event from stream, or null
KeyEvent	key: string	Symbolic key name
KeyEvent	modifiers: KeyModifier	Modifier bitmask
KeyEvent	raw: string	Raw bytes that produced this event
MouseEvent	x, y: int	Column and row (1-based)
MouseEvent	button: int	Button index (0=left, 1=middle, 2=right)
MouseEvent	action: string	press \| release \| drag \| scroll
FocusEvent	gained: bool	True if focus gained, false if lost
PasteEvent	content: string	Pasted content (max 1 MiB)
ResizeEvent	cols, rows: int	New terminal dimensions
KeyModifier	none(): self	No modifiers
KeyModifier	shift(): self	Shift modifier
KeyModifier	ctrl(): self	Ctrl modifier
KeyModifier	alt(): self	Alt modifier
KeyModifier	includes(int $flag): bool	Check if flag is set
KeyModifier	value(): int	Raw bitmask value