SugarCraft

PHP ports of the Charmbracelet TUI ecosystem (plus bubblezone, ntcharts, and a small SugarCraft-flavoured sweetshop of original libraries) — composer-installable, PHP 8.1+, async on ReactPHP.

🌐 Website: sugarcraft.github.io — library matrix, quickstart, comparison page.

composer require sugarcraft/sugarcraft

What's in the box

Forty-five libraries grouped by layer:

	Library	Role
	SugarCraft	Elm-architecture TUI runtime — Model / Msg / Cmd / Program (incl. cursed cell-diff renderer). Port of bubbletea.
	CandySprinkles	Declarative styling + layout — Style, Border, Table, List, Tree, Layout::join, Place, Canvas (multi-layer compositor). Port of lipgloss.
	HoneyBounce	Damped spring physics + Newtonian projectile sim. Port of harmonica.
	CandyZone	Mouse-zone tracker — wrap rendered chunks, get back bounding boxes. Port of bubblezone.
	SugarBits	14 components: TextInput, TextArea, ItemList, Table, Viewport, FilePicker, Progress, Spinner, Cursor, Help, Key, Paginator, Stopwatch, Timer. Port of bubbles.
	CandyVt	Virtual terminal emulator — ANSI byte stream → cell grid + cursor + mode state. Port of charmbracelet/x/vt.
	CandyVcr	Record + replay candy-core sessions — JSONL/YAML cassettes, Program::withRecorder(), Player with byte + cell-grid assertions, CLI. Port of charmbracelet/x/vcr.
	CandyPty	Pseudo-terminal primitive — Pty::open() master/slave round-trip via FFI to libc; spawn/resize/non-blocking I/O land in PR2-PR5. Linux + macOS only. Port of charmbracelet/x/xpty.
	SugarCharts	Canvas + Sparkline, Bar, Line, Heatmap, Scatter, TimeSeries, Streamline, Waveline, OHLC, Picture (Sixel/Kitty/iTerm2). Port of ntcharts.
	SugarPrompt	Form library — Note, Input, Confirm, Select, MultiSelect, Text, FilePicker; multi-page Groups; 6 themes. Port of huh.
	CandyShine	Markdown → ANSI renderer with word-wrap, OSC 8 hyperlinks, 8 themes. Port of glamour.
	CandyKit	CLI presentation helpers — StatusLine, Banner, Section, Stage, HelpText. Port of fang.
	CandyWish	SSH server middleware — Logger, Auth, RateLimit, BubbleTea (mount a SugarCraft Program over ForceCommand). Port of wish.
	CandyMetrics	Telemetry primitives — counters, gauges, histograms with InMemory / JSON / StatsD / Prometheus textfile / Multi backends, plus a CandyWish session middleware. Port of promwish.
	CandyLog	Colorful leveled logger — Debug / Info / Warn / Error / Fatal with structured context, Text / JSON / Logfmt formatters, sub-loggers, and StandardLogAdapter. Port of log
	CandyPalette	Terminal color profile detection + ANSI / ANSI256 / TrueColor conversion. StandardColors and ProfileWriter. Port of colorprofile
	CandyLister	Tree/list view with box-drawing prefixes, cursor navigation, word-wrap, and filter-as-you-type. Port of bubblelister
	SugarBoxer	Box-drawing layout engine — H/V panel composition with weighted sizing, borders, and nested grids. Port of bubbleboxer
	SugarVeil	Terminal overlay compositor — push/pop overlay views with z-ordering, positioning, and per-overlay teardown. Port of bubbletea-overlay
	SugarCrumbs	Navigation breadcrumbs — immutable NavStack with push/pop, shell-change detection, and type-ahead filter. Port of bubbleo
	SugarDash	Dashboard TUI library — column grid layout, framed panels, status bar, tabs, and more. Port of bubble-grid.
	CandyHermit	Fuzzy finder overlay — type to filter a list, arrow keys to select, Enter to confirm. Bubbletea Model wrapper. Port of theHermit
	SugarStickers	FlexBox layout engine + simple sort/filter table. Ratio-based sizing, gap, justify, align, per-column styling. Port of stickers
	SugarToast	Floating notification overlays — Info / Success / Warning / Error types, configurable position and auto-dismiss. Port of bubbleup
	SugarCalendar	Interactive month-grid date picker — keyboard navigation, min/max date constraints, locale day names, ANSI rendering. Port of bubble-datepicker
	SugarReadline	Interactive prompts — Text, Confirm, Selection, MultiSelect, Textarea. State-machine model, no external readline dependency. Port of promptkit
	SugarTable	Full-featured interactive data table — column definitions, StyledCell ANSI formatting, pagination, frozen rows/cols. Port of bubble-table

Apps built on the stack

	App	Role
	CandyMold	composer create-project sugarcraft/candy-mold my-app — bootstrap skeleton with a working counter Model. Port of bubbletea-app-template.
	CandyShell	Composer-installable CLI of all 13 subcommands (choose, confirm, file, filter, format, input, join, log, pager, spin, style, table, write). Port of gum.
	CandyFreeze	Code → SVG screenshot generator (no ext-gd required). Port of freeze.
	SugarGlow	Markdown CLI viewer / pager. Port of glow.
	SugarSpark	ANSI escape-sequence inspector. Port of sequin.
	SugarWishlist	TUI directory of SSH endpoints — YAML/JSON config + pcntl_exec into the chosen ssh. Port of wishlist.
	SugarSkate	In-memory key/value store with plugin backends — Memory, SQLite, Badger. Glob listing, TTL, batch operations. Port of skate
	SugarPost	Email sending library — SMTP + Resend API transports, attachments, HTML + plain-text multipart, fluent interface. Port of skate
	CandyServe	Self-hostable Git server over SSH (authorized keys), Git daemon, and HTTP. Users, repos, access control, optional LFS. Port of soft-serve
	CandyTetris	Tetris clone — SRS rules, 7-bag, ghost piece, NES scoring, level-driven gravity. Port of tetrigo.
	SuperCandy	Dual-pane file manager — Midnight Commander style, multi-select, sort, delete-with-confirm. Port of superfile.
	SugarCrush	AI coding-assistant chat shell — pluggable backend (EchoBackend offline; CommandBackend for Anthropic / OpenAI / Ollama via a wrapper script). Port of crush.
	SugarStash	Three-pane git TUI — status / branches / log, single-key stage / unstage; shells out to git for every mutation. Port of lazygit.
	CandyQuery	Terminal SQLite browser — list tables, browse rows, run ad-hoc queries (PDO + :memory: test fixtures). Port of lazysql.
	SugarTick	Privacy-first coding-time tracker — JSONL on disk, SugarCharts-driven dashboard, no cloud / no MongoDB. Port of TakaTime.
	CandyMines	Minesweeper — first-click safety, recursive flood-fill, flag toggle, win/lose detection, deterministic-RNG injectable. Port of go-sweep.
	CandyFlip	ASCII GIF viewer — ext-gd decode, downsample to a cell grid, render as ANSI 24-bit blocks or a luminance-ramp. Port of gifterm.
	HoneyFlap	Flappy-Bird-style game — bird motion is a HoneyBounce projectile, pipes scroll left at a fixed cell rate. Port of flapioca.

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

Quickstart — a counter app

use SugarCraft\Core\{Cmd, KeyType, Model, Msg, Program};
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"; }
}

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

Architecture

• PHP 8.1+ — fibers, readonly props, enums, match, intersection types.
• Runtime: ReactPHP event loop. Mirrors goroutine semantics for input, signals, render tick, command execution.
• 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 during the porting phase. Each library will split into its own repo at v1.0.

Status

Every library in the table above is at v1. The full surface of every Go counterpart that PHP can reasonably express (modulo the niche items called out in CONVERSION.md § Phase audit) has been ported. See CONVERSION.md for the full roadmap, per-library status, and the v2-parity sweep against Bubble Tea v2 / Lipgloss v2 / Bubbles v2.

Adding a new library or app

The matchup of upstream → SugarCraft port is the source-of-truth in MATCHUPS.md, and the contributor / agent playbook in AGENTS.md walks through the full integration: naming conventions, package skeleton, tests, examples, VHS demos, 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-core candy-sprinkles honey-bounce candy-zone sugar-bits \
         sugar-charts sugar-dash sugar-prompt candy-shell candy-shine candy-kit \
         candy-freeze sugar-glow sugar-spark \
         candy-wish sugar-wishlist candy-metrics \
         candy-mold candy-tetris super-candy sugar-crush \
         sugar-stash candy-query sugar-tick candy-mines candy-flip honey-flap; do
    (cd "$d" && composer install --quiet && vendor/bin/phpunit) || exit 1
done

Contributing

See CONTRIBUTING.md. Bugs, feature requests, and ports of additional Charmbracelet (or compatible) libraries welcome. For security issues, see SECURITY.md.

License

MIT.

---

made with sugar · sweet to build · fun to use