SugarCraft

SugarCraft is a complete terminal-application stack for modern PHP: an MVC-style Model–Update–View runtime for terminal user interfaces (TUIs); styling, layout, and form engines; reusable components; charts; and terminal emulators and plumbing — plus a fleet of finished apps. Every package is composer-installable and requires PHP 8.3+; the interactive stack — runtime, components, and apps — runs async on a ReactPHP event loop.

🌐 Website: sugarcraft.github.io — library matrix, quickstart, comparison page. 📖 New here? Getting started — a finished binary, a first app, or a chart in five minutes. 📚 Vocabulary: Glossary — every term this README uses, defined with its source file.

composer require sugarcraft/sugarcraft        # umbrella metapackage — every library
composer require sugarcraft/sugar-style   # …or just the package you need

What's in the box

Every package installs independently with Composer. The libraries are grouped by layer:

	Library	Role
	SugarCraft	MVC-style Model–Update–View TUI runtime — Model / Msg / Cmd / Program, plus a frame-diff renderer with an opt-in cursed cell-diff mode.
	SugarAnsiParser	ECMA-48 VT500 state machine — ANSI byte-stream parser with abstract Handler interface. Extraction from sugar-vterm.
	SugarCellBuffer	Cell-grid value objects — immutable Buffer (2-D cell grid) and Cell (rune/style/link/width). Shared foundation for all rendering; Buffer::diff() included.
	SugarConstraints	Constraint-based layout solver — LayoutSolver interface with a deterministic GreedySolver engine (CassowarySolver kept only as a deprecated shim).
	SugarAsync	Shared async vocabulary for ReactPHP — CancellationToken, Subscriptions, AsyncOps helpers (withTimeout, retry, debounce, throttle).
	SugarInput	Terminal input decoder — raw TTY bytes to typed events: keyboard (Kitty progressive protocol, xterm modifyOtherKeys, legacy encodings) and mouse (SGR, urxvt, X10) via InputDriver / EscapeDecoder.
	SugarMouse

Apps built on the stack

	App	Role
	CandyStarter	composer create-project sugarcraft/candy-starter my-app — bootstrap skeleton with a working counter Model.
	CandyScriptui	Composer-installable CLI of 13 presentation subcommands (choose, confirm, file, filter, format, input, join, log, pager, spin, style, table, write) — scriptable terminal UI in one-liners.
	CandyCodeshot	Code → SVG (or PNG via ext-gd) screenshot generator.
	CandyMdview	Markdown CLI viewer / pager.
	CandyAnsiInspect	ANSI escape-sequence inspector.
	CandySshLauncher	TUI directory of SSH endpoints — YAML/JSON config + pcntl_exec into the chosen ssh.
	CandyKv	Personal key/value store — one SQLite database per store, @dbname namespaces, glob listing, TTL, binary values, JSON/YAML import/export.
	CandyMail	Email sending library — SMTP + Resend API transports, attachments, HTML + plain-text multipart, fluent interface.

Renamed packages (2026-10): every package moved to the two-prefix scheme above — candy- for runnable apps and CLI tools, sugar- for libraries (the honey- family was retired). The full old → new map, with redirect notes, lives in PROJECT_NAMES.md.

Each library has its own README.md with usage examples and a deep dive into its public API.

Quickstart — a counter app

Save as counter.php in a project with composer require sugarcraft/sugar-core, then run php counter.php:

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 $n = 0) {}
    public function init(): ?\Closure { return null; }

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

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

    public function subscriptions(): ?Subscriptions { return null; }
}

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

Architecture

• PHP 8.3+ — fibers, readonly props, enums, match, intersection types.
• Runtime: ReactPHP event loop — input, signals, render tick, and command execution all run concurrently on a single loop.
• Style: PSR-12 + readonly DTOs. Every Style, Model, etc. is immutable — with*() returns a new instance.
• Testing: PHPUnit 10. Snapshot ANSI tests for renderers; scripted-input event tests for the runtime.
• Layout: monorepo; every library also publishes as a standalone package and will later split into its own repo.

Status

Every library in the table above ships at v1, each with its own composer package and PHPUnit suite, and CI publishes per-library coverage to Codecov; the rendering libraries pin their output with snapshot-ANSI tests. The website library matrix carries live per-package status, and each library's README.md documents its full public API.

Adding a new library or app

The full package roster lives in MATCHUPS.md, and the contributor / agent playbook in AGENTS.md walks through the complete integration checklist: naming conventions, package skeleton, tests, examples, VHS demos (terminal sessions recorded as GIFs), website tiles, and the central docs to update. AI assistants should read AGENTS.md first.

Running the test suites

The umbrella package is a metapackage; each library has its own composer.json + vendor/. To test everything:

for d in candy-* sugar-*; do
    [ -f "$d/phpunit.xml" ] || continue
    (cd "$d" && composer install --quiet && vendor/bin/phpunit) || exit 1
done

Code style is enforced via php-cs-fixer (root .php-cs-fixer.dist.php). Run from the repo root:

PHP_CS_FIXER_IGNORE_ENV=1 php-cs-fixer fix --diff --allow-risky=yes

Contributing

See CONTRIBUTING.md. Bugs, feature requests, and new libraries — original tools, components, and terminal apps that fill gaps in the PHP stack — are all welcome. For security issues, see SECURITY.md. The fleet trust model — what counts as untrusted input and where the sanitize gates must sit — is docs/TRUST-BOUNDARY.md.

License

MIT.

Credits & inspiration

SugarCraft is a PHP-native project. Its original design inspiration came from the Go terminal ecosystem — notably Bubble Tea and the wider Charm family of libraries — reimagined here for PHP 8.3+.

---