SugarCraft glossary

Every term the root README and the library docs assume you already know, defined in two or three lines each with a pointer to the code that makes it true. This page is fleet-wide; candy-code's own glossary covers the agent-app vocabulary (ACP, refusal kinds, presets) separately.

How a terminal app draws

Term Meaning
TUI Terminal User Interface — an interactive app that runs in a text terminal, redrawing the whole screen (or parts of it) instead of scrolling output.
ANSI The family of escape-sequence conventions a terminal understands — bytes starting ESC [ / ESC ] that move the cursor, set colors, toggle modes. Everything a TUI "draws" is ANSI text.
ECMA-48 The 1976 ISO-parented standard that defines the control sequences ANSI terminals follow (C0/C1 controls, CSI structure). SugarCraft's parser models it in sugar-ansi-parser.
VT500 Digital Equipment's late terminal-model spec — the de-facto reference register of CSI/DEC Private modes that modern terminals emulate. sugar-ansi-parser's state machine targets it.
CSI Control Sequence Introducer — ESC [ — the prefix of most commands (cursor movement, SGR, mode set/reset).
SGR Select Graphic Rendition — the CSI m command: ESC[1m bold, ESC[38;2;R;G;Bm truecolor. Style rendering is a stream of SGR parameters; defined and emitted by sugar-style/src/Style.php.
OSC Operating System Command — ESC ] … ESC \ (or BEL) — out-of-band messages: window titles, hyperlinks, iTerm2 image chunks.
OSC 8 The hyperlink extension: ESC]8;;URL ESC\ text ESC]8;; ESC\. A click target without a mouse protocol; emitted by SugarCraft\Core\Util\Ansi::hyperlink() and consumed by sugar-markdown.
alternate screen The second full-screen buffer many terminals keep (ESC[?1049h) — enter it and the user's scrollback survives you. sugar-core's Program owns this lifecycle.
raw mode TTY setting that turns off line buffering and echo, so the app reads each keystroke immediately. Set up by sugar-core's input stack; required for arrow keys to arrive as bytes at all.
PTY Pseudo-Terminal — the kernel master/slave pair that gives a child process a fake tty. Used to run programs under a terminal (sugar-pty, candy-code's PtyRun tool).
ConPTY Windows Pseudo Console — Microsoft's CreatePseudoConsole API, the Windows equivalent of a PTY (Convert-IO, no signals/controlling terminal). Implemented by sugar-pty's Windows backend (sugar-pty/src/Windows/).
cell-diff The renderer keeps the previous frame as a grid of cells and writes only the characters that changed. sugar-cellbuffer's Buffer::diff() is the shared engine.
"cursed" cell-diff mode sugar-core's opt-in raw-line diffing mode — the historic lipgloss term for byte-level (not cell-level) frame differencing: cheaper, but only correct when every row is rewritten exactly. See the sugar-core README row ("opt-in cursed cell-diff mode").
rune One user-perceived character in one grid cell (may be several bytes / codepoints: an emoji, a combining sequence). sugar-cellbuffer/src/Cell.php stores rune/style/link/width.
braille chart An 8-dot Braille cell (⣀-shaped glyphs, U+2800 block) used as a 2×4-pixel plotting cell — line graphs in text. Produced by the charts Canvas/BrailleGrid and sugar-dashboard's Plot/Braille/; candy-top's CPU graphs are these, hence "braille graphs, btop-compatible". (Sparklines are the block-element family ▁▂▃▄▅▆▇█, not braille.)
luminance ramp Grayscale block glyphs (░▒▓█) chosen by pixel brightness — the fallback way to show an image or GIF where truecolor or graphics protocols are unavailable (sugar-animation, candy-gifview, sugar-image's ANSI tier).
half block The ▄/▀ glyphs; sugar-image's always-available ANSI tier paints one image row per two such half-cells.
Sixel DEC's bitmap-in-escape-stream image format (ESC P … q … ESC \); one of the three image protocols sugar-image negotiates alongside Kitty and iTerm2 (SixelRenderer).
OHLC Open–High–Low–Close — the four-price sample behind candlestick/bar financial charts; the data shape sugar-charts/src/OHLC/ renders as terminal candlesticks.

Keyboard and mouse protocols

Term Meaning
Kitty progressive keyboard protocol A graphics-protocol-era keyboard extension (CSI >1u flags) that reports every key + modifier combination unambiguously, and lets apps "disambiguate" chords. Decoded by sugar-input; negotiated on startup by apps such as candy-code and candy-files.
xterm modifyOtherKeys xterm's older alternative for reporting chords as CSI 27;modifier;keysym ~. Also decoded by sugar-input.
X10 mouse The 1984 DEC VT52-era mouse report (ESC [ M + 3 bytes) — button press only, coordinates capped to 223 columns. sugar-input's mouse decoders read it.
urxvt mouse The rxvt-unicode extension adding drag/motion reports to the X10 encoding.
SGR mouse The modern encoding (CSI < button;x;y M/m) — arbitrary coordinates, press and release distinguishable; what candy-top enables (?1002h + ?1006h).
marker / zone / sentinel The click plumbing trio: a marker is the pair of invisible codepoints wrapped around rendered content, a zone is the rectangle the renderer discovers from those markers when a frame is scanned, and the sentinels are the codepoints themselves — U+E000 (open) and U+E001 (close), constants Sanitize::ZONE_SENTINEL_OPEN/CLOSE in sugar-core/src/Util/Sanitize.php. The marker builder is SugarCraft\Mouse\Mark::zone().
PUA Private Use Areas — Unicode blocks reserved for app-defined glyphs. SugarCraft reserves U+E000–U+F8FF: the two zone sentinels plus image-overlay markers live there, which is why untrusted text is swept of them (see untrusted below and docs/TRUST-BOUNDARY.md).

Runtime vocabulary

SugarCraft's interactive stack is an MVC-style Model–Update–View runtime (the architecture pioneered by The Elm Architecture and ported to Go as Bubble Tea). The words, per sugar-core:

Term Meaning
Model An immutable value object holding your app's whole state, implementing SugarCraft\Core\Model — init(), update(), view(), subscriptions().
Msg Anything that happened: a key press, a tick, an async result. A SugarCraft\Core\Msg value handed to update().
Update Model::update(Msg): [Model, ?Cmd] — the single place state changes; returns the next model plus an optional effect.
View `Model::view(): string
Cmd A deferred effect — a Closure returned by update() that the runtime runs and feeds its resulting Msg back in (sugar-core/src/Cmd.php).
Subscriptions The model's declared live sources (timers, streams, key-repeat…) that update() never touches; the runtime reconciles them after each cycle (sugar-core/src/Subscriptions.php).
Program The harness that owns the event loop, raw mode, alt-screen, and the Update→View tick (sugar-core/src/Program.php). Your app is just a Model.
tick One loop iteration's repaint decision; frame-rate is a ProgramOptions setting.
frame Two senses — (1) TEA: one complete view() output painted to screen; (2) candy-vcr/VHS: one recorded (or rendered) image in a session tape/GIF. Each lib names its sense locally.

Styling and color

Term Meaning
Style An immutable set-and-render description — bold, colors, underline — as a SugarCraft\Style\Style value object (sugar-style/src/Style.php); its setters keep lipgloss's bare names (bold(), fg()) and still return a new instance via a private with() — sugar-style is the documented naming exception, so the with*() spelling belongs to the other value-object families. Never "the Sprinkles Style" — Sprinkles was sugar-style's pre-rename codename in the original confectionery naming family (PROJECT_NAMES.md); the package has shipped as sugar-style since the 2026-10 rename.
theme A named, loadable collection of style choices — a file on disk you select (candy-top ships btop-compatible theme files; sugar-style's Theme.php is the programmatic kind: Theme::ansi()).
palette The in-memory set of colors resolved for one render — sugar-style/src/Palette.php (and sugar-colorprofile's tiered palettes). A theme selects a palette; the palette is what styles index into.
ColorProfile The terminal's color depth — the five enum cases NoTty/Ascii/Ansi/Ansi256/TrueColor (sugar-core/src/Util/ColorProfile.php:12-16) — detected once at startup from TERM/COLORTERM/NO_COLOR/CI env by Util\ColorProfile::detect() and dispatched as a ColorProfileMsg; apps may then pick different palettes per tier. sugar-colorprofile resolves colors down the longer eight-rung degradation ladder (TrueColor→Ansi256→Ansi240→Ansi→Ansi8→Fgbg→Ascii→NoTTY; see its row in docs/MATCHUPS.md).
NO_COLOR The community convention: set NO_COLOR to any non-empty value and programs drop color. Honored fleet-wide via core detection plus per-app config; see KEYMAPS.md for the app-by-app caveat.

Layout words: pane vs panel vs box

Term Meaning
pane A dockable, switchable region of a multi-view app window — candy-code's are the Pane enum cases (chat, files, agents…) in candy-code/src/Tui/Pane.php; one active pane at a time, draggable dividers.
panel A self-contained bordered widget rendered inside a screen — sugar-panels' box-drawing tree (sugar-panels/src/SugarPanels.php): each panel has a border and title, they tile, you never "switch to" them.
box The bordered rectangle a panel draws; also the unit of candy-top's screen (CPU box, mem box).

Recording words: cassette vs tape

Term Meaning
cassette A recorded interactive session — the JSONL event tape candy-vcr writes and replays to drive tests and demos deterministically (candy-vcr/src/Cassette.php).
tape (VHS) A declarative GIF script — the .vhs/*.tape file that says "type this command, sleep, screenshot" so CI renders the demo GIF (AGENTS.md convention, workflow vhs.yml). Named after the charmbracelet/vhs tool it mirrors.

Trust words

Term Meaning
trusted Data your program authored — your Model's own strings, config you wrote. It may contain markers and SGR freely.
untrusted Anything from outside: tool output, file contents, network, prompt injections possible. Must pass through Sanitize::untrusted() / untrustedForMarkedFrames() before reaching a presentation sink, which strips forged sentinels and escape payloads. The full fleet contract is docs/TRUST-BOUNDARY.md.

Port and package vocabulary

Term Meaning
upstream / antecedent The original project a SugarCraft package models. "Port of charmbracelet/x" or "Design antecedent: treilik/bubbleboxer" means the API and semantics follow that project deliberately (see the Mirrors … docblock law in AGENTS.md); a bare "inspired by" makes little promise either way — the docs therefore use port/antecedent consistently, and README phrases like "bubblezone-style" name a specific antecedent project the same way.
façade A package that re-exports another's classes via class_alias (e.g. sugar-widgets → sugar-forms symbols). Ships only an alias smoke-test, never a copied suite (AGENTS.md façade law).
path repository A composer repositories[] entry pointing at a sibling checkout. Never committed to a published lib manifest (it is a fatal for split-repo clones); CI injects the closure at build time — tools/check-path-repos.php.
phar PHP Archive — a single self-contained executable file (php candy-top.phar), built and signed for candy-code/v* and candy-top/v* tags (SECURITY.md).
umbrella The sugarcraft/sugarcraft metapackage — installs every library in one composer require (root composer.json). A dependency convenience, not a namespace: packages never require it.
LFS Git Large File Storage — the git extension that replaces big binaries with pointer files and fetches them from a separate store; candy-git-server implements optional LFS on its push/pull surface.
ReactPHP The PHP event-loop library (react/event-loop) SugarCraft builds its async + runtime on: the shared Loop::get() drives input, signals and repaint ticks; sugar-async layers the cancellables/timeouts vocabulary on top of it.

Legacy campaign IDs

You will occasionally see labels like F-18 (the namespace-collision ruling in PROJECT_NAMES.md — candy-image), E-nnn, ISS-nnn, wave-N, or tranche-N inside prose. These are internal audit/campaign finding IDs — each was the handle for one line of a dated review ledger (F-nn: the chafa study findings; E-nnn: the candy-code hardening backlog; ISS-nnn: the tracked issue list). They are history, not product vocabulary: nothing in the API depends on them, and the ledgers that resolve them are not shipped with the packages. Read the sentence around one and ignore the ID. New docs and code are written without them.