# AbstractTUI
> AbstractTUI is a reactive, compositor-grade terminal UI engine for Rust. State lives in
> fine-grained signals (in the SolidJS tradition — not immediate mode, not a virtual DOM):
> a write re-runs exactly the computations that depended on it, and those re-renders damage
> exactly the screen regions they own. Damage flows through a z-ordered compositor with
> alpha blending and per-cell shaders, a frame diff, and a byte-economical ANSI presenter,
> so an idle app emits zero bytes and allocates nothing. On top sit a 20+ widget library
> arranged by a flexbox-style solver and a track-based grid (rows and tables follow one
> convention: single click selects, Enter or engine-synthesized double-click activates),
> an app-shell vocabulary
> (a page-level tab host and edge-anchored drawer panels, both hosting full pages),
> 26 built-in themes over 36
> contrast-audited semantic design tokens, PNG/baseline-JPEG images drawn through the best
> channel the terminal proves (kitty graphics, iTerm2, sixel, or unicode mosaic),
> software-rasterized 3D from GLB files (textures, animation, skinning — no GPU),
> cell-shader animation with tweens, easings, and timelines, streaming transcripts
> (`Feed` + follow-tail scroll + a multiline composer with completion) speaking the full
> markdown doc vocabulary (GFM tables that render live while streaming, task lists, lazy
> in-flow images) with a document reader surface (heading outline and anchor jumps,
> find-in-document highlights), a live-data lane for background producers (bounded
> ingestion, honest drop counters, `TimeSeries` history rings with relative time axes on
> the charts) plus an engine-owned connection lifecycle with jittered-backoff reconnect,
> key press/release state with honest fidelity (push-to-talk, level meters, and a
> waveform scope for voice surfaces), text selection with OSC 52 clipboard copy, an
> optional boot splash, and a headless testing harness that drives the production
> pipeline without a pty — including screenshot capture with deterministic plain-text,
> replayable-ANSI and GitHub-renderable-SVG exporters. A public sub-cell vector canvas
> (braille/quadrant dot grids,
> lines, beziers, arcs, eighth-block fills) underlies the charts and an opt-in sibling
> extension family: `abstracttui-graph` (graph auto-layout + a GraphView widget) and
> `abstracttui-mermaid` (honest-subset mermaid rendering with atomic fallback). One core
> crate, five small dependencies (unicode-width, unicode-segmentation, miniz_oxide, plus
> libc on unix / windows-sys on Windows). MIT licensed.
## Core docs
- [README](README.md): Project overview — the pitch, highlights, a 16-line first app,
install, the flagship examples, the platform support table, and measured performance
numbers (idle costs zero; a 200×60 diff+present in ~0.5 ms).
- [Getting started](docs/getting-started.md): Install to first pixels, step by step — the
first app explained line by line, interactivity with `TextInput`, layout basics (flex
and grid), theming in 3 lines, showing an image, a 3D teaser, how capability degradation
works, and headless testing of your own app.
- [Architecture](docs/architecture.md): How the engine fits together — the layer map,
fine-grained reactivity, the compositor (layers, blending, shaders, diff/present), the
frame lifecycle, the zero-cost idle guarantee and the tests that pin it, the terminal
layer (capabilities, kitty keyboard, tmux, restore), the 3D pipeline, platform posture.
- [API guide](docs/api.md): The public surface, module by module — prelude, reactive
(plus the `reactive::connection` lifecycle with jittered-backoff reconnect), ui
(including double-click synthesis: `click_count()`, the ambient event-time rule, and
the single-click-selects / double-click-activates convention), layout (with the
small-terminals & content-pressure guarantees and recipes),
the widget catalog (`List` and `Table` selection-vs-activation, masked `TextInput`,
diff-aware `CodeView`,
`Feed` streaming/rich lines/sync/selection-by-key, chart history rings with time axes,
`Meter`/`AudioScope` levels, the `PageHost` page-level tab host), the widget
disposal-safety law, the `canvas` sub-cell vector layer (braille/quadrant dot grids,
Bresenham/bezier/arc strokes, eighth-block fills, the cell-color z-order rule), the
app runtime (overlays,
modal, toast, edge-anchored `Drawer` panels, the anchored-popup substrate and the
Select/Combobox/MultiSelect pickers,
completion, hooks, key press/release state and `PushToTalk`), theme, render
(Style-as-patch, shaders, the markdown doc vocabulary and the reader surface), gfx,
three, term/input, the testing harness, screenshots & captures (the `Screenshot`
value from the live driver, the `request_screenshot` verb, or the testing rig, with
text/replayable-ANSI/GitHub-renderable-SVG exporters and labeled protocol-image
regions), and plain statements of stability and limits.
- [Documentation index](docs/README.md): One-line map of every guide and the reference
material.
## Topics
- [Theming](docs/theming.md): The 36-token semantic model, the 26 built-in themes, runtime
switching through one signal, theme modes (`ThemeMode`, `themes_by_mode`, the
remembered-choice `toggle_mode()`) and the drop-in `ThemeSwitcher` chrome control
(grouped Dark/Light menu with live preview), WCAG-derived contrast floors and the
audit, registering custom themes (Strict/Labeled modes), token derivation helpers, and
styling rules for widget authors.
- [Graphics and 3D](docs/graphics-and-3d.md): Images end-to-end (decode → capability
ladder → mosaic modes → tmux passthrough), the GLB 3D pipeline (supported subset, scene/
camera/light, the Viewport3D widget, animation and skinning, textures and mips), the
boot splash, honest limits, and the measured performance envelope.
- [Graphs and diagrams](docs/graphs-and-diagrams.md): The extension family —
`abstracttui-graph` (the `GraphDesc -> Layout` contract; layered vs force vs grid pass
selection; `GraphView` cards/strokes/selection/pan/tooltips; honesty markers for broken
cycles and degradations) and `abstracttui-mermaid` (the exhaustive subset table as the
contract, flowcharts/flat-state compiled onto the graph crate, solverless sequence
diagrams, the atomic code-fence fallback with a named reason and a mermaid.live escape
link), plus install lines and measured layout numbers.
- [Live data](docs/live-data.md): Feeding the UI from background threads —
`channel_source`/`latest_source`/`bounded_source` (drop/coalesce policies, honest
`IngestStats`), the `interval` timer, waker dedup, the connection lifecycle
(`reactive::connection` + full-jitter `Backoff`, with a state diagram and a
worker-thread example), the Feed + follow-tail rendering pattern, and back-pressure
honesty.
- [FAQ](docs/faq.md): Real questions — design rationale, SSH, which terminals support
images, wide-character widths, headless testing, embedding in an existing event loop,
the near-zero dependency policy, theme readability, `NO_COLOR`/dumb terminals, Windows
status, crate size, shareable components, damage debugging, and the clipboard policy.
- [Troubleshooting](docs/troubleshooting.md): Symptom → cause → fix — nothing renders,
dead keyboard, images falling back to mosaic, washed-out colors, flicker/tearing,
Ctrl+Enter behaving like Enter, the splash not playing, slow frames, wide-character
misalignment, and tests that hang.
## Project
- [Changelog](CHANGELOG.md): Release history (Keep a Changelog, SemVer); 0.1.0
(2026-07-21) is the first public release, 0.2.21 (2026-07-25) the current one —
released alongside the first extension-family crates (`abstracttui-graph` 0.1.0,
`abstracttui-mermaid` 0.1.0, each with its own changelog under `extensions/`).
- [Contributing](CONTRIBUTING.md): Building, the test suite (~2,015 core tests; ~2,140
with the extension family via `--workspace`, the CI gate) and the explicitly-run suites
(live pty, two release-mode perf-budget suites with byte-emission ratchets, plus the
scheduled weekly `perf.yml` deep gate), golden snapshots, lint gates, the strict module
layering rule, code conventions, and how to add a widget or a theme.
- [Security policy](SECURITY.md): Private reporting (contact@abstractframework.ai); the
untrusted-input scope (terminal bytes, PNG/JPEG, GLB, markdown) — any panic, unbounded
allocation, or hang on crafted input is treated as a vulnerability-class bug.
- [Acknowledgements](ACKNOWLEDGEMENTS.md): The five dependencies with licenses, the public
specifications implemented, prior art (ratatui, notcurses, textual, SolidJS), and the
ported theme palettes.
- [License](LICENSE): MIT.
## Code entry points
- [src/prelude.rs](src/prelude.rs): The one-import app surface
(`use abstracttui::prelude::*;`) — widgets, layout vocabulary, signals, theme hooks, and
`App`; `render::Style` is deliberately excluded from the glob.
- [src/lib.rs](src/lib.rs): Crate root with the layer map — `base`, `term`, `input`,
`render`, `text`, `anim`, `reactive`, `layout`, `ui`, `canvas`, `widgets`, `gfx`,
`three`, `theme`, `app`, `boot`, `testing`.
- [examples/](examples/README.md): The catalog of the twenty-two runnable examples,
ordered as a learning path —
`hello`,
`widgets`, `components`, `gallery`, `themes`, `grid`, `activate`, `decide`, `feed`,
`transcript`, `reader`, `voice_mock`, `shell`, `drawers`, `dashboard`, `images`,
`effects`, `splash`, `viewer3d`,
`screenshot`, `caps`, `capture` — plus the extension-crate examples
(`workflow`/`network` in `extensions/graph`, `mermaid` in `extensions/mermaid`); each
documented with keys and requirements; every one exits cleanly without a tty, and
`dashboard`/`viewer3d`/`images` take `--caps`.
- [docs/captures/](docs/captures/): Deterministic text "screenshots" of the shipped
examples (plain, style-annotated, and rendered SVG via `Screenshot::to_svg`) and
clockless in-process stills of the app-layer
surfaces (streaming transcript with completion open, open Select popup, diff-tinted
code, scrolled feed, doc-vocabulary reader table), plus `themes-table.md` — every token
hex value of all 26 themes; regenerable with `cargo run --example capture`.
- [extensions/](extensions/README.md): The sibling-crate family workspace —
`extensions/graph/` (`abstracttui-graph`: layout passes + `GraphView`, examples
`workflow`/`network`) and `extensions/mermaid/` (`abstracttui-mermaid`: subset parser,
compiler, sequence renderer, a 30-fixture corpus, example `mermaid`); each crate
carries its own README and CHANGELOG.