All 42 libraries

SugarCraft Core

MVC-style Model–Update–View TUI runtime

inspired by charmbracelet/bubbletea runtime model-update-view react-php event-loop bandwidth-sparing

SugarCraft Core code coverage

Model / Msg / Cmd / Program. The runtime everything else builds on. Includes the "cursed" cell-diff renderer (the Bubble Tea v2 name for it) — meaningful SSH bandwidth savings for slow-changing UIs.

Install

composer require sugarcraft/sugar-core

Quickstart

use SugarCraft\Core\{Cmd, KeyType, Model, Msg, Program, Subscriptions};
use SugarCraft\Core\Msg\KeyMsg;

final class Counter implements Model {
    public function __construct(public readonly int $count = 0) {}
    public function init(): ?\Closure { return null; }
    public function subscriptions(): ?Subscriptions { return null; }

    public function update(Msg $msg): array {
        if ($msg instanceof KeyMsg) {
            return match (true) {
                $msg->type === KeyType::Char && $msg->rune === 'q' => [$this, Cmd::quit()],
                $msg->type === KeyType::Up      => [new self($this->count + 1), null],
                $msg->type === KeyType::Down    => [new self($this->count - 1), null],
                default                         => [$this, null],
            };
        }
        return [$this, null];
    }

    public function view(): string {
        return "count: $this->count\n(↑/↓ to change, q to quit)";
    }
}

(new Program(new Counter()))->run();

What's in the box

Model interfaceFour methods: init(), update(Msg), view(), subscriptions() — the SubscriptionCapable trait supplies a default for the last one.
Cmd helpersCmd::quit(), Cmd::batch(), Cmd::send() — async work scheduled, never inlined.
InputReaderStateful escape-sequence parser. Bracketed paste, mouse, function keys, OSC, DEC private modes. Paste is bounded: an end marker split across reads still closes the envelope, a paste larger than MAX_PASTE_BYTES (1 MiB) surfaces in chunks, and an envelope whose end marker never arrives is closed after PASTE_IDLE_TIMEOUT (1 s) of silence so the keyboard comes back. Pasted content is sanitized by default: escapes are stripped and the U+E000–U+F8FF marker arena is swept before the payload reaches update(); opt out with ProgramOptions::$sanitizePaste only when you supply your own containment. Process launches from user data use proc_open()'s argv form — never shell interpolation.
"Cursed" rendererBubble Tea v2's term for the cell-diff default — here, cell-diff rendering with ≥15% bandwidth savings on a 50-tick test.
ReactPHP loopEvent-loop concurrency for input, signals, render tick, command execution.
Signal handlingSIGWINCH (resize), SIGTSTP and SIGCONT surface as Msgs in your update(); SIGINT, SIGTERM and SIGHUP instead unwind the loop cleanly and record the 128+N exit convention for the entry point to propagate. While raw mode is active Ctrl+C is an ordinary keystroke, not a signal. On exit the runtime cancels its pending one-shot timers and restores the previous signal handlers and async-signal mode.
ColorProfile::detect()Detection order: unless CLICOLOR_FORCE / FORCE_COLOR is set, a non-tty output is NoTty first (so NO_COLOR on a pipe emits no escapes at all), then TERM=dumb → NoTty; next NO_COLOR → Ascii (color off, bold/faint kept — it outranks the force variables), then CLICOLOR=0 → Ascii (the BSD opt-out, unless a force variable already won), then force → TrueColor (so a forced pipe still gets color), then COLORTERM, TERM_PROGRAM, WT_SESSION and TERM patterns; a truthy CI variable → Ansi, and the fallback → Ascii.
Screen / ScreenStackImmutable stack for modal / drill-down flows. RootModelWithScreenStack + ScreenStackCapable delegate init/update/view to the active screen automatically.
Component / CompositeParent-child lifecycle model. Component interface adds onMount()/onUnmount(); Composite owns children and drains lifecycle Cmds during reconcile.
WorkerPoolBounded-concurrency pool (default 4 workers) for CPU-bound tasks. WorkerCmd::run($pool, $task) dispatches a global function name or serializable callable and yields a WorkerResultMsg on completion. A Closure cannot cross the process boundary, so dispatching one returns an already-rejected promise.

Source & demos

Try the quickstart →

Demos.

Two VHS-recorded GIFs — the counter and timer demos — regenerated by CI on every push that touches the source. The other examples the library ships run straight from examples/ with php examples/<name>.php.

Counter Model

Counter Model

↑ / ↓ to count, q to quit. Demonstrates the full Model / Msg / Cmd loop.
Timer

Timer

Ticking timer driven by a Cmd-scheduled tick message.