Download the PHP package sugarcraft/candy-core without Composer

SugarCraft

PHP port of charmbracelet/bubbletea — the Elm-architecture TUI runtime at the heart of the Charmbracelet stack.

Requirements

• PHP 8.1+ (PHP 8.4+ recommended on Windows for FFI SetConsoleCtrlHandler support)
• mbstring, intl (for grapheme width)
• pcntl (signal handling — POSIX only; not available on Windows)
• FFI extension (required on Windows for raw TTY support)
• react/event-loop ^1.6 (Composer)
• Windows 10 version 1809+ (for ENABLE_VIRTUAL_TERMINAL_PROCESSING)

Architecture

• Model — your app implements init(), update(Msg), view(), subscriptions().
• Msg — marker interface for events. Built-ins: KeyMsg, WindowSizeMsg, QuitMsg.
• Cmd — Closure(): ?Msg. Async work whose result is dispatched as a Msg. Helpers in Cmd::quit(), Cmd::batch(), Cmd::send().
• Program — orchestrator. Sets up TTY, runs the ReactPHP event loop, dispatches Msgs, drives renders at the configured framerate.
• InputReader — stateful byte-stream parser; handles split escape sequences across reads.
• Renderer — minimal cursor-home + erase + write. Diff-based renderer is a follow-up.
• Util/ — Ansi, Color, ColorProfile, Width, Tty, Open foundation utilities, shared with CandySprinkles.
• Subscription — value object: id, Kind, params, produce closure.
• Subscriptions — immutable collection with withTick(), withKey(), withSignal(), withCustom(), all(), has().
• Kind — backed enum: Tick / Key / Signal / Custom.
• SubscriptionCapable — trait providing the default subscriptions(): null.
  • ScreenStack — immutable stack with push() / pop() / current() / breadcrumb() / isEmpty() / count().
  • Screen — value object: model, optional title, onEnter closure, onExit closure.
  • ScreenStackCapable — interface: screens(): ScreenStack. Implement to activate screen-stack routing.
  • RootModelWithScreenStack — concrete root model owning a ScreenStack; routes ScreenStackPushedMsg / ScreenStackPoppedMsg internally, delegates view() to the active screen.
  • PushScreenCmd / PopScreenCmd — Cmd factories that emit ScreenStackPushedMsg / ScreenStackPoppedMsg.
  • ScreenStackPushedMsg / ScreenStackPoppedMsg — infrastructure messages dispatched through Program::send().
  • Component — interface extending Model; adds onMount(): ?Closure (fired when mounted into a Composite) and onUnmount(): ?Closure (fired when removed). Return a Cmd to run immediately or null for no-op.
  • Composite — Model that manages a list of child Components. Tracks pendingCmds and drains them during reconcile, calling child onMount()/onUnmount() Cmds synchronously. Children are reconciled by ordinal position — reordering triggers lifecycle events on affected children.
  • WorkerPool — bounded-concurrency pool (default 4 workers) for offloading CPU-bound tasks to subprocesses via serialized callables.
  • WorkerCmd — Cmd factory: WorkerCmd::run($pool, $callable) dispatches a task to the pool and yields a WorkerResultMsg when complete.
  • WorkerResultMsg — result Msg carrying $result, $error, and $workerId from a pool worker.

Subscriptions

Elm-style subscription reconciliation lets a Model declare recurring events (ticks, key events, signals) without managing timers manually. After each update() cycle the runtime diffs the returned Subscriptions set against the active one — new subscriptions start, dropped ones cancel, stable ones keep running.

The SubscriptionCapable trait satisfies Model::subscriptions() with a null default — use it in Models that don't need subscriptions:

Screen / ScreenStack

Modal and sub-screen workflows use an immutable ScreenStack owned by a ScreenStackCapable root model. The Program routes init() / update() / view() to the active screen automatically, while infrastructure messages (ScreenStackPushedMsg / ScreenStackPoppedMsg) stay in the root model.

examples/screen-stack.php is a runnable demo showing 3-deep push / pop.

Demos

Counter Model

Timer

Status

• Phase 0 (foundation utilities): 🟢 complete.
• Phase 3 (runtime): 🟢 v1 — Program loop, mouse (cell-motion + all-motion + SGR 1006), focus / blur, bracketed paste, full function-key set including F13–F63 and the Kitty PUA range, the cell-diff "cursed" renderer (synchronized output 2026 + unicode mode 2027), inline-mode rendering, declarative View struct, plus the v2 Cmd surface (Suspend / Interrupt / Resume / Exec / Sequence / Every / Printf / Raw / wait / kill / releaseTerminal / restoreTerminal).

See ../CONVERSION.md for the full roadmap and the v2 parity sweep table tracking each Bubble Tea v2 / Lipgloss v2 / Bubbles v2 feature.

Companion libraries

SugarCraft is the foundation — the rest of the SugarCraft stack builds on it. From the same monorepo:

• CandySprinkles (← lipgloss) — declarative styling + layout.
• SugarBits (← bubbles) — 14 prebuilt components.
• SugarPrompt (← huh) — multi-page form library.
• SugarCharts (← ntcharts) — sparkline / bar / line / heatmap / OHLC.
• CandyShell (← gum) — composer-installable CLI of 13 subcommands.
• CandyShine (← glamour) — Markdown → ANSI renderer.
• CandyZone (← bubblezone) — mouse-zone tracker.
• HoneyBounce (← harmonica) — spring physics + Newtonian projectile sim.
• CandyKit (← fang) — opinionated CLI presentation helpers.
• CandyFreeze (← freeze) — code → SVG screenshot.
• CandyWish (← wish) — SSH server middleware framework.
• SugarSpark (← sequin) — ANSI escape-sequence inspector.

See the matchup table in ../MATCHUPS.md for status, package names, and namespace mappings.

Localization (i18n)

candy-core ships a tiny zero-dep translation registry that the rest of the SugarCraft monorepo plugs into. Every library owns a namespace (core, charts, prompt, …) and a lang/<locale>.php file per locale — call sites look strings up by fully-qualified key.

Each library exposes a thin Lang::t($key, $params) wrapper with its namespace baked in, so call sites stay short:

Adding a new locale

1. Copy candy-core/lang/en.php to candy-core/lang/<locale>.php (e.g. fr.php).
2. Translate the values, keeping keys and {placeholders} intact.
3. Set the locale at app startup with T::setLocale('fr') or T::setLocale(T::detect()).

Lookup chain: exact locale → base language → en → raw key. So a single fr.php automatically serves fr-fr, fr-ca, fr-be, etc. — only add a regional file (e.g. pt-br.php) when the wording genuinely diverges from the base language. A forgotten string is visible, never a fatal error.

See LOCALES.md in the SugarCraft monorepo for the recommended set of codes plus a list of every base language a contributor can target.

Application-level overrides

Apps can ship their own translations of any library's strings without patching upstream:

See the SugarCraft\Core\I18n\T docblock for the full API surface (register, translate, setLocale, locale, detect, overrideNamespace, reset).

Composing Cmds

The runtime ships several Cmd combinators. The cheat-sheet below maps Bubble Tea idioms to the PHP equivalents:

init() returns a Cmd (or null) to fire once at startup. update() returns [Model, ?Cmd] — the runtime applies the Cmd, dispatches its Msg, and feeds the result back into update().

The examples/ directory has runnable demos for each pattern: timer (tick scheduling), realtime (self-rescheduling tick), sequence (Cmd::sequence), send-msg (custom Msg + Cmd::tick), tabs (state-driven view selection), views (multi-view switcher), splash (animated splash → main view), suspend (Cmd::suspend + ResumeMsg), focus-blur, print-key, set-window-title, and prevent-quit.

Alt-screen vs inline mode

Pass useAltScreen: true (the default) to ProgramOptions and the runtime takes over the alt-screen — the user's previous content is preserved underneath, and Cmd::quit() restores it. Best for fullscreen TUIs.

Pass useAltScreen: false + inlineMode: true for a program that shares scrollback with the surrounding shell. The runtime saves the cursor on first frame and restores it after each repaint, so preceding shell output stays visible. Pair with Cmd::println() to emit lines that scroll above the program region.

A typical CandyShell prompt (gum input-style) uses inline mode; a fullscreen filter (gum filter-style) uses alt-screen.

Tutorial — building a shopping list

Every SugarCraft program is three things: a Model (the state), an update (state transitions), and a view (a string). Here's a shopping list that walks through all three.

Three rules carry through to every program:

1. Model is immutable. update() returns a new Model, never mutates the receiver. This buys you snapshot debugging, time travel, undo — all for free.
2. Cmds run async. update() decides what should happen; the runtime applies the resulting Cmd. A Cmd is a closure returning a Msg.
3. view() is pure. Same Model in → same string out. Side effects (writing to disk, hitting an HTTP endpoint, blinking the cursor) all live in Cmds, never in view().

Once you've internalised the loop, every other SugarCraft feature is just a richer Msg or a more interesting Cmd.

Debugging tips

The renderer owns stdout — printing to it from update() or view() will be overwritten on the next frame. The two ways to surface debug info from inside a running program:

1. Log to a file. Tail the file from another terminal:

2. Use Cmd::println(). Lines emitted via Cmd::println() print above the program region (alt-screen and inline mode both honour this) — perfect for "I got here" prints during development.

Other gotchas:

• Don't return null from Model::view(). The runtime expects a string. Return '' for an empty frame.
• Don't block the main thread in update() or view() — the runtime won't pump frames while you're sleeping. Long work goes in a Cmd that emits a Msg when it finishes.
• Test the Model in isolation. Drive update() with scripted Msgs in PHPUnit; the runtime is irrelevant for state-machine testing. (See candy-core/tests/Model/ for the pattern.)
• Profile with --bail. If a render is slow, the cell-diff renderer skips unchanged regions — make sure your view() is deterministic so the diff stays cheap.

Mouse support — cell-motion vs all-motion

Pass MouseMode::CellMotion (only emit motion events while a button is held) or MouseMode::AllMotion (emit every motion event including bare-cursor moves) to ProgramOptions. Pick:

• CellMotion when the model only cares about clicks + drags (most apps). Fewer Msgs flow through update(), lighter on the parser, plays nicely with terminal copy/paste because the user can hold Shift to bypass mouse capture.
• AllMotion when the model reacts to hover state (tooltips, fancy cursor effects, drag-preview overlays). Trade: every motion event lands in update(), so use a MouseMode::CellMotion stub for non-hover frames if perf bites.

MouseMsg carries a MouseAction enum (Press / Release / Motion / WheelUp / WheelDown) and 1-based col / row coordinates. The four MouseClickMsg / MouseReleaseMsg / MouseMotionMsg / MouseWheelMsg subclasses let you match by class when that's more convenient.

examples/mouse.php is a runnable demonstrator.

Test