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 candycore/candycore

What's in the box

Sixteen libraries grouped by layer:

	Library	Role
	CandyCore	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.
	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.
	CandyShell	Composer-installable CLI of all 13 subcommands (choose, confirm, file, filter, format, input, join, log, pager, spin, style, table, write). Port of gum.
	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.
	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.
	CandyWish	SSH server middleware — Logger, Auth, RateLimit, BubbleTea (mount a CandyCore Program over ForceCommand). Port of wish.
	SugarWishlist	TUI directory of SSH endpoints — YAML/JSON config + pcntl_exec into the chosen ssh. Port of wishlist.
	CandyMetrics	Telemetry primitives — counters, gauges, histograms with InMemory / JSON / StatsD / Prometheus textfile / Multi backends, plus a CandyWish session middleware. Port of promwish.

Apps built on the stack

	App	Role
	CandyMold	composer create-project candycore/candy-mold my-app — bootstrap skeleton with a working counter Model. Port of bubbletea-app-template.
	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 CandyCore\Core\{Cmd, KeyType, Model, Msg, Program};
use CandyCore\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.

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-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