# 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.
This file aggregates the full AbstractTUI documentation verbatim: the README followed by
every guide under docs/, each introduced by a `===== FILE: <path> =====` separator, with
package facts at the end.
===== FILE: README.md =====
# AbstractTUI
**The terminal, composed.** A reactive, compositor-grade terminal UI engine for Rust.
AbstractTUI is built on fine-grained reactive signals — not immediate mode, not a
virtual DOM. Reading a signal inside a view tracks it; writing one re-runs exactly
the computations that depended on it, and those re-renders damage exactly the
screen regions they own. Damaged regions flow through a real compositor
(z-ordered layers, alpha blending, per-layer offset/opacity), a frame diff, and a
byte emitter that plays the terminal like an instrument — cursor-motion economy,
minimal SGR runs, synchronized output where the terminal supports it. The result:
an idle app emits zero bytes and allocates nothing, and a blinking cursor repaints
one cell, not the screen.
*The `dashboard` example — live line charts, sub-cell progress bars, a
software-rendered 3D mark, a scrolling event log, a sortable table, toasts and a
modal, all animating while the rest of the screen stays still.*
### 3D in the terminal — a real GLB, rasterized to cells
*`cargo run --example viewer3d` turning [the standard damaged-helmet glTF
model](https://github.com/KhronosGroup/glTF-Sample-Models) (15,452 triangles) —
a hand-written perspective rasterizer with a z-buffer, textures and lighting,
presented through half-block, quadrant, sextant and braille mosaics. No GPU, no
external renderer.*
### The design system on one screen — restyled under one keypress
*The `gallery` example — every token, widget state, chart, and text style on one
board. Pressing a key swaps the theme signal and the whole screen re-renders
through ordinary reactivity.*
## Highlights
- **Widgets + layout** — buttons, text inputs, a multiline composer
(`TextArea` with history and completion dropdowns), selects (`Select` /
`Combobox` / `MultiSelect` over anchored popups that layer above modals),
lists and sortable tables with distinct selection and activation events
(single click selects; Enter or double-click activates),
tabs, checkboxes, radio groups, scroll regions, panels, badges, progress
bars, spinners, modals, toasts, tooltips — plus the app-shell pair:
`PageHost` (full pages behind one themed tab bar — container-reserved
chords, reactive tab badges, overflow windowing) and `Drawer`
(edge-anchored overlay panels, modal or glanceable, sliding from any
edge) — arranged by a flexbox-style solver
(row/column, `grow`, `gap`, padding) and a track-based grid
(`fr`/cells/percent, spans).
- **Transcripts and documents** — `Feed` renders append-only conversations
and logs with keyed rich blocks (markdown, code with syntax and diff
tinting, multi-ink rich lines, custom draw); streaming markdown items
re-typeset only the open block per token and speak the full doc
vocabulary — GFM tables (a streamed table renders as a table live), task
lists, strikethrough, and lazy in-flow images. `MarkdownView` adds the
reading surface: heading outline with anchor jumps, and find-in-document
with highlighted matches. `Scroll::follow_tail` pins to the bottom until
the user scrolls and re-pins at the edge.
- **Live data** — feed the UI from background threads through
`channel_source` / `latest_source` / `bounded_source` (drop or coalesce
policies with honest drop counters), a cancellable `interval` timer, and
waker deduplication; `TimeSeries` history rings put relative time axes
under the charts (a sampling pause draws as a hole, never a compressed
x-axis), and `reactive::connection` owns the reconnect lifecycle with
jittered exponential backoff. An idle app still costs zero — offline
included.
- **Selection + clipboard** — drag to select rendered text (wide-glyph safe,
pane-clamped), copy via OSC 52; or suspend mouse capture for native
terminal selection.
- **26 built-in themes** — catppuccin, rose-pine, tokyo-night, nord, one-dark,
dracula, monokai, gruvbox, solarized, everforest and the Abstract originals —
over 36 semantic design tokens, contrast-audited against WCAG floors, and
hot-swappable at runtime through one signal.
- **Input everywhere** — keyboard and mouse (click, hover, drag, wheel), the
kitty keyboard protocol and xterm modifyOtherKeys decoded automatically when
present, bracketed paste hardened against multi-megabyte and hostile input,
focus events, key chords with modifiers.
- **Voice and AV plumbing** — key press/release state with honest fidelity
(true hold detection where the terminal reports releases; never a
fabricated "held" on legacy wires), a `PushToTalk` gesture built on it
(hold-to-talk, labeled latch fallback, capture stops on focus loss), and
`Meter` / `AudioScope` widgets that render live levels with real
ballistics and go fully idle when the signal does.
- **Images** — PNG and baseline JPEG decoding built in, drawn through the best
channel your terminal offers: kitty graphics, iTerm2, sixel, or unicode mosaic
(half-block / quadrant / sextant / braille). Capability detection is automatic
and every degradation is labeled, never silent.
- **Software-rasterized 3D** — load GLB files (node hierarchies, textures,
vertex colors, animation, skinning) and render them into the same cell
pipeline. No GPU, no native dependencies.
- **Motion** — cell shaders (shimmer, dissolve, hue-drift, and more) that cost
work only where damage exists, plus tweens, easings, and timelines.
- **A boot identity** — a 2-second animated splash (3D mark with a pure-cell 2D
fallback), skippable with any key, auto-disabled on non-TTY, `NO_COLOR`, and
`TERM=dumb`.
- **Headless testing** — drive the production pipeline against a captured
terminal and assert on the rendered screen. No pty required.
- **Screenshots** — capture any screen as a plain value (`Driver::screenshot()`,
the `app::request_screenshot` key-bindable verb, or the VT model in headless
tests) and export it as plain text, replayable ANSI, or a GitHub-renderable
SVG — deterministic artifacts for docs, bug reports, and test evidence, with
protocol-image regions honestly labeled.
- **Vector strokes + an extension family** — a public sub-cell canvas
(braille/quadrant dot grids, lines, beziers, arcs, eighth-block
fills) in core, and diagram-class capability as opt-in sibling
crates: `abstracttui-graph` (auto-layout + graph widget) and
`abstracttui-mermaid` (honest-subset mermaid). See
[docs/graphs-and-diagrams.md](docs/graphs-and-diagrams.md).
## Your first app
Fifteen lines, one import:
```rust
use abstracttui::prelude::*;
fn main() -> abstracttui::base::Result<()> {
App::simple(|cx| {
let count = cx.signal(0);
Element::new()
.style(LayoutStyle::column())
.child(dyn_view(LayoutStyle::line(1), move || {
text(format!("count: {}", count.get()))
}))
.child(Button::new("+1").on_click(move || count.update(|c| *c += 1)).view(cx))
.child(text("Tab focuses · Enter clicks · Ctrl+C quits"))
.build()
})
}
```
Tab focus, Enter/Space activation, and Ctrl+C quit are all defaults. The count
line re-renders fine-grained through `dyn_view` — nothing else repaints. The
walkthrough lives in [docs/getting-started.md](docs/getting-started.md).
## Install
```sh
cargo add abstracttui
```
Rust 2021 edition. The dependency policy is deliberately austere — `unicode-width`,
`unicode-segmentation`, `miniz_oxide`, plus `libc` on unix / `windows-sys` on
Windows, and nothing else. ANSI emission, input parsing, the layout solver, the
signals runtime, PNG/JPEG decoding, glTF parsing, and the 3D rasterizer are all
implemented in-crate.
The extension family installs only when you need it (same MIT license,
same dependency discipline, public core API only —
[ADR-0004](docs/adr/0004-extension-packaging.md)):
```sh
cargo add abstracttui-graph # 0.1 — graph auto-layout + GraphView
cargo add abstracttui-mermaid # 0.1 — mermaid subset renderer
```
## Run the examples
```sh
git clone https://github.com/lpalbou/abstracttui
cd abstracttui
cargo run --example dashboard
```
Twenty-two runnable examples live in [examples/](examples/README.md) — ordered
there as a learning path — plus three more in the extension crates, and every
one exits cleanly with a notice when no interactive terminal is present, so they
are safe to run anywhere. Start with these six:
- `dashboard` — the flagship ops screen: charts, log tail, sortable table,
toasts, modal help, spatial pane navigation.
- `shell` — the app shell: three full pages behind a global `PageHost` tab
bar (live tab badge, Ctrl+PgUp/PgDn, digit jumps) plus `Drawer` panels
from both edges (`i` inspector, `g` nav).
- `gallery` — the whole design system on one screen; one keypress restyles it.
- `themes` — every theme as a live card grid with a preview pane and measured
contrast ratios.
- `viewer3d` — orbit a GLB model with measured fps
(`cargo run --example viewer3d -- path/to/model.glb`).
- `images` — four mosaic families side by side, dithering, and pixel-protocol
placement with the chosen channel named.
`ABSTRACTTUI_THEME=rose-pine cargo run --example hello` themes any example from
the environment; `--caps` on `dashboard`, `viewer3d`, and `images` prints the
detected capability report and exits.
The animations above are recorded straight from these examples with
[`vhs`](https://github.com/charmbracelet/vhs); the tapes live in
[`docs/media/`](docs/media/) and regenerate with `vhs docs/media/<name>.tape`.
## Platform support
| Platform | Status |
| --- | --- |
| macOS | Verified — the full test suite includes live pty tests (real controlling terminal, signal-driven resize, suspend/resume). |
| Linux | Verified — same unix code paths; the full default suite runs in CI on ubuntu, and the live pty suite runs in a dedicated CI job (`live pty (ubuntu)`, real pseudo-terminal, examples prebuilt). |
| Windows | Best-effort — compiles clean and lint-free against the MSVC target, the library suite runs in CI on a real Windows runner, but it has not yet been run on a live Windows console. Treat the first Windows run as a beta event. |
Minimum supported Rust version: **1.87** (declared as `rust-version` in
Cargo.toml and checked by a pinned-toolchain CI job; raising it is a
minor-version event, declared in the CHANGELOG).
The terminal is always restored — on quit, on panic, and on Ctrl+Z suspend —
including cursor style, mouse modes, and kitty keyboard flags.
## Performance
Measured (release build, M-class laptop): a full 200×60 diff+present costs
~0.5 ms, a keystroke reaches the painted frame in ~50 µs through the real event
loop, and an idle app costs zero — zero bytes written, zero heap allocations,
zero wakeups. The allocation budgets gate every CI run; the release-mode
timing budgets and byte-emission ratchets gate on a weekly scheduled job
(`perf.yml`, also runnable by hand — see CONTRIBUTING) — budgets, not
aspirations, with the honest split stated.
## Documentation
- [Getting started](docs/getting-started.md) — install to first pixels, step by step.
- [Architecture](docs/architecture.md) — signals, damage, the compositor, the render pipeline.
- [API guide](docs/api.md) — the public surface, module by module.
- [Graphs and diagrams](docs/graphs-and-diagrams.md) — the extension family: graph layout, `GraphView`, the mermaid subset.
- [Live data](docs/live-data.md) — background threads into the UI, bounded and honest.
- [FAQ](docs/faq.md) and [Troubleshooting](docs/troubleshooting.md).
- [Examples catalog](examples/README.md) — what each demo proves and the keys it answers to.
- API reference on [docs.rs](https://docs.rs/abstracttui) (family crates: [abstracttui-graph](https://docs.rs/abstracttui-graph), [abstracttui-mermaid](https://docs.rs/abstracttui-mermaid)).
## License
MIT — see [LICENSE](LICENSE).
===== FILE: docs/getting-started.md =====
# Getting started
From install to first pixels, step by step. Every snippet here compiles against
the current release; the longer ones are lifted from the crate's own doctests,
which run in CI.
## Install
```sh
cargo add abstracttui
```
AbstractTUI targets the Rust 2021 edition and builds on macOS, Linux, and
Windows with a deliberately small dependency set (`unicode-width`,
`unicode-segmentation`, `miniz_oxide`, plus the platform FFI crate). There is no
native library to install and no GPU requirement.
## Your first app
```rust
use abstracttui::prelude::*;
fn main() -> abstracttui::base::Result<()> {
App::simple(|cx| {
let count = cx.signal(0);
Element::new()
.style(LayoutStyle::column())
.child(dyn_view(LayoutStyle::line(1), move || {
text(format!("count: {}", count.get()))
}))
.child(Button::new("+1").on_click(move || count.update(|c| *c += 1)).view(cx))
.child(text("Tab focuses · Enter clicks · Ctrl+C quits"))
.build()
})
}
```
Line by line:
- **`use abstracttui::prelude::*;`** — one import covers the common path:
widgets (`Button` included), layout vocabulary, signals, hooks, and `App`
itself.
- **`App::simple(|cx| ...)`** — builds the app, mounts your root component,
enters the raw terminal, and runs the event loop until quit. The `cx`
parameter is your `Scope`: the handle you create reactive state with. A panic
hook is installed first, so the terminal is restored even if your code panics.
- **`let count = cx.signal(0);`** — a `Signal`. Signals are small `Copy`
handles, so you can move them into as many closures as you like. `.get()` is
a tracked read; `.set(v)` and `.update(|v| ...)` write and notify exactly the
computations that read it.
- **`Element::new().style(LayoutStyle::column())`** — the element tree. Styles
describe layout (direction, size, grow, gap, padding); children stack top to
bottom in a column.
- **`dyn_view(LayoutStyle::line(1), move || ...)`** — a reactive region. The
closure re-runs whenever a signal it reads changes, and only this region's
cells are redrawn. `LayoutStyle::line(1)` is a full-width, one-row slot.
- **`Button::new("+1").on_click(...).view(cx)`** — a widget builder. `.view(cx)`
resolves the active theme from context and returns a finished `View`, ready
for `.child(..)`. Every themed widget in the prelude supports this shape.
- **`text(...)`** — a static text leaf. It never re-renders because it reads no
signals.
- **Defaults you did not write** — Tab/Shift+Tab move focus, Enter and Space
activate the focused widget, Ctrl+C quits. Override any of them by consuming
the event in a handler or shortcut.
## Adding interactivity
`TextInput` binds to a `Signal<String>` and reports edits through `on_change`
(after every edit) and `on_submit` (on Enter). Combined with `dyn_view`, state
flows from keystroke to screen with no wiring in between:
```rust
use abstracttui::prelude::*;
fn form(cx: Scope) -> View {
let name = cx.signal(String::new());
let saved = cx.signal(false);
Element::new()
.style(LayoutStyle::column().gap(1).padding(Edges::all(1)))
.child(
TextInput::new()
.placeholder("your name")
.value(name) // bind an external signal
.on_change(move |_| saved.set(false)) // any edit invalidates
.view(cx),
)
.child(Button::new("Save").on_click(move || saved.set(true)).view(cx))
.child(dyn_view(LayoutStyle::line(1), move || {
let status = if saved.get() { "saved" } else { "unsaved" };
text(format!("{} — {}", name.get(), status))
}))
.build()
}
```
Run it with `App::simple(form)`. Tab moves between the input and the button;
the input handles cursor movement, selection (Shift+arrows), word jumps
(Alt+arrows), and paste for you. Mouse clicks focus and activate the same
widgets — no extra code.
The same one-import surface covers the rest of a form or chat screen:
`Select`/`Combobox`/`MultiSelect` for choices (a one-row trigger opening an
anchored popup), `TextArea` + `TextAreaState` for a multiline composer that
grows with its content, and `Feed` (`abstracttui::widgets`) with
`Scroll::follow_tail` for streaming transcripts — markdown items speak the
full doc vocabulary, GFM tables and task lists included. The
[API guide](api.md#widgets--the-built-in-library) walks each one;
`cargo run --example transcript` and `--example components` show them
composed, and `--example reader` is the document side: tables, in-flow
images, a TOC panel, and find-in-document.
## Layout basics
Layout is a flexbox-style solver. The vocabulary: `LayoutStyle::column()` /
`LayoutStyle::row()` set direction, `gap(n)` spaces children, `padding(Edges)`
insets content, and sizes come from `Dimension::Cells(n)`, `Dimension::Percent(f)`,
or `grow`:
```rust
// A fixed sidebar and a growing main pane.
Element::new()
.style(LayoutStyle::row().gap(1).padding(Edges::all(1)))
.child(
Element::new()
.style(LayoutStyle::column().width(Dimension::Cells(20)))
.child(text("sidebar"))
.build(),
)
.child(
Element::new()
.style(LayoutStyle::column().grow(1.0)) // takes the remaining width
.child(text("main"))
.build(),
)
.build()
```
The rule for multi-pane layouts: give every pane that should share leftover
space a `grow`, and fixed panes an explicit size. A pane with neither takes
only its content size. `LayoutStyle::fill()` (fill the parent on both axes) and
`LayoutStyle::line(n)` (full width, `n` rows) cover the two most common shapes.
For two-dimensional layouts there is a track-based `Grid` — columns and rows
declared as `Track::Cells(n)`, `Track::Percent(f)`, `Track::Fr(f)`, or
`Track::Auto`, with row-major auto-placement and spans:
```rust
// A label column and a growing field column; children fill row by row.
Grid::new(vec![Track::Cells(12), Track::Fr(1.0)], vec![])
.gap(1)
.child(text("Name:"))
.child(TextInput::new().view(cx))
.child(text("Notes:"))
.child(TextInput::new().view(cx))
.view()
```
The `grid` example (`cargo run --example grid`) cycles three track recipes over
the same children — the fastest way to build intuition.
## Theming in 3 lines
```rust
set_theme_by_id("nord"); // switch — every themed region repaints
let theme = use_theme(cx); // reactive handle to the active theme
let tokens = theme.get().tokens; // 36 semantic color tokens (bg, text, accent, …)
```
Widgets never name colors; they consume semantic tokens (`bg`, `surface`,
`text`, `accent`, `ok`/`warn`/`error`, chart slots, syntax inks, …), so one
`set_theme_by_id` restyles the entire app. 26 themes ship built in — try
`cargo run --example themes` for a live picker with measured contrast ratios,
or set `ABSTRACTTUI_THEME=<id>` in the environment (the convention every
example honors). Custom themes register at runtime through `theme::register`,
which audits contrast floors and either refuses or labels violations,
depending on the mode you choose.
## Showing an image
Decode once, wrap in an `Arc`, hand it to the `Image` widget:
```rust
use std::sync::Arc;
use abstracttui::gfx;
let bytes = std::fs::read("photo.jpg")?;
let bitmap = Arc::new(gfx::decode_image(&bytes)?);
```
```rust
use abstracttui::widgets::ImageFit;
// In your component:
Image::from_bitmap(bitmap.clone())
.fit(ImageFit::Contain) // largest size that fits, aspect preserved
.view(cx)
```
`gfx::decode_image` sniffs the actual bytes (containers lie, bytes don't) and
decodes PNG or baseline JPEG; unknown formats are rejected by name, never with
a panic. The widget renders unicode mosaic — colored sub-cell glyphs that work
in any terminal — and picks the best mosaic mode for the terminal's detected
glyph and color support. For pixel-perfect output over the kitty, iTerm2, or sixel
protocols, `gfx::ImageSession` manages placement at the app level; the
`images` example (`cargo run --example images`) shows both paths side by side,
naming the channel it chose.
## A 3D teaser
```rust
use std::sync::Arc;
use abstracttui::three;
let view = three::quick_view("model.glb")?; // load + framed camera + light
let model = Arc::new(view.model);
```
```rust
// In your component:
Viewport3D::new(model.clone())
.orbit(0.6, 0.35, 1.0) // yaw, pitch, zoom — drive these from signals
.view(cx)
```
`three::quick_view` loads a GLB file with a camera framed on the model's bounds
and a default light. `Viewport3D` software-rasterizes the scene into cells:
drag orbits, the wheel zooms, and the widget reports deltas through
`.on_orbit`/`.on_zoom` so camera state lives in your signals. Animated,
skinned models play through `.animate(clip, t)`. The loader supports binary
GLB with triangle meshes, embedded PNG/baseline-JPEG textures, LINEAR/STEP
animation, and 4-joint skinning; unsupported features are rejected by name or
degraded with a label, never guessed at. `cargo run --example viewer3d --
path/to/model.glb` is the full viewer, with measured fps in the status row.
## Plain terminals vs feature-rich terminals
You write one app; the engine adapts it to the terminal it finds. Capabilities
(color depth, kitty keyboard/graphics, sixel, synchronized output, pixel
geometry) are detected in two passes — an instant environment pass for the
first frame, then an active probe that can both raise and lower the answer
based on what the terminal actually replies. Everything degrades in the open:
- Truecolor styling steps down to 256 or 16 colors; `NO_COLOR` and `TERM=dumb`
are honored.
- Images step down the protocol ladder to unicode mosaic, which works
everywhere. Inside tmux, pixel protocols are enabled only after a live
passthrough probe proves they arrive.
- Key combos like Ctrl+Enter or Shift+Enter exist only on terminals with the
kitty protocol or modifyOtherKeys (legacy terminals send bytes identical to
plain Enter) — treat them as enhancements, and keep baseline bindings on
keys that work everywhere: arrows, Home/End, PgUp/PgDn, F1–F12.
Every degradation is recorded as a labeled startup notice. Read them
reactively with the `use_startup_notices(cx)` hook and render them in a status
line or toast — the `dashboard` example does exactly that, and its `--caps`
flag prints the full capability report without needing a tty.
## Testing your app headlessly
No pty needed: drive the same pipeline production uses against a captured
terminal, feed input as bytes, and assert on the rendered screen. This is the
crate's own doctest on `App`:
```rust
use abstracttui::prelude::*;
use abstracttui::app::Driver;
use abstracttui::testing::CaptureTerm;
let size = Size::new(20, 4);
let mut app = App::new(size);
app.mount(|cx| {
let n = cx.signal(0);
Element::new()
.shortcut(KeyChord::plain(Key::Char('+')), move |_| n.update(|v| *v += 1))
.child(dyn_view(LayoutStyle::line(1), move || text(format!("n = {}", n.get()))))
.build()
}).unwrap();
let mut term = CaptureTerm::new(size);
let cfg = RunConfig { probe: false, ..RunConfig::default() };
let mut driver = Driver::new(&mut app, &mut term, cfg).unwrap();
driver.turn(&mut app, &mut term).unwrap(); // first frame
assert!(term.screen().to_text().contains("n = 0"));
term.push_input(b"+"); // a keypress
driver.turn(&mut app, &mut term).unwrap(); // dispatch + repaint
assert!(term.screen().to_text().contains("n = 1"));
```
`CaptureTerm` records every byte and models the screen; `Driver::turn` runs one
full frame cycle — input dispatch, effects, layout, damage-driven redraw, diff,
present. Every focus and damage path is the real one. For pure component tests
you can skip the driver entirely: mount into a `ui::UiTree`, dispatch events,
and draw into a `ui::BufferCanvas` — every widget suite in the crate is written
that way.
When a test (or a bug report) needs to show what the screen looked like,
capture it as a value and export plain text, replayable ANSI, or an SVG —
see [the API guide's "Screenshots & captures"](api.md#screenshots--captures)
and `cargo run --example screenshot`, which demos both the key-binding and
the headless-test recipe.
## Where next
- [Architecture](architecture.md) — signals, the damage contract, the
compositor, and the render pipeline.
- [API guide](api.md) — the public surface, module by module.
- [Theming](theming.md) — the token model, custom themes, contrast floors.
- [Graphics and 3D](graphics-and-3d.md) — images end-to-end, the GLB
pipeline, the boot splash.
- [Live data](live-data.md) — background threads into the UI, bounded and
honest.
- [Graphs and diagrams](graphs-and-diagrams.md) — the extension
family: graph auto-layout + `GraphView` (`abstracttui-graph`) and
the honest mermaid subset (`abstracttui-mermaid`), installed only
when you need them.
- [FAQ](faq.md) and [Troubleshooting](troubleshooting.md).
- [Examples catalog](../examples/README.md) — twenty-five runnable programs
(three of them in the extension crates) ordered as a learning path, from
the 53-line `hello` to the full `dashboard`, with the keys each answers to. For content-heavy apps start
with `transcript` (streaming markdown chat), `reader` (tables, images,
TOC, search), and `voice_mock` (push-to-talk and live meters, no audio
required); for app chrome start with `shell` (full pages behind a
`PageHost` tab bar plus `Drawer` panels from both edges).
===== FILE: docs/architecture.md =====
# AbstractTUI Architecture
AbstractTUI is a standalone Rust engine that treats the terminal as a real
display device. A layered compositor with damage tracking sits under a
fine-grained reactive component model; pixel graphics and software-rasterized
3D are first-class citizens of the same scene, themed by a shared design-token
system.
Most terminal UI stacks pick one of two camps: immediate mode, which rebuilds
the whole frame every tick and diffs it, or retained widget trees with coarse
invalidation. AbstractTUI takes a third architecture. State lives in signals;
a write re-runs exactly the computations that depended on it, and those
computations damage exactly the screen regions they own. There is no virtual
DOM to diff and no full-frame rebuild to pay for. An idle application burns
zero CPU; a blinking status cell damages one cell.
## Layer map
Every module sits at a fixed layer and depends only on layers below it. The
`testing` module cuts across the whole stack: an in-memory terminal double
and a VT100/xterm interpreter let any layer be exercised headlessly against
ground truth.
```mermaid
graph BT
base["base<br/>geometry, color, errors, shared vocabulary"]
subgraph terminal["terminal layer"]
term["term<br/>raw mode, capabilities, restore"]
input["input<br/>byte stream to events"]
end
subgraph drawing["drawing layer"]
render["render<br/>surfaces, compositor, diff, presenter"]
text["text<br/>measurement, wrapping"]
anim["anim<br/>clock, tweens, cell shaders"]
end
reactive["reactive<br/>signals, memos, effects, scheduler"]
layout["layout<br/>flex and grid solver"]
ui["ui<br/>element tree, event routing, focus"]
subgraph content["content layer"]
canvas["canvas<br/>sub-cell dot grids, vector strokes"]
widgets["widgets<br/>built-in library"]
gfx["gfx<br/>bitmaps, mosaic, pixel protocols"]
three["three<br/>GLB loading, 3D rasterizer"]
end
theme["theme<br/>design tokens, theme registry"]
app["app<br/>frame loop, overlays, runtime"]
boot["boot<br/>splash identity"]
testing["testing<br/>capture terminal, VT model, harnesses"]
base --> terminal
terminal --> drawing
drawing --> reactive
reactive --> layout
layout --> ui
ui --> content
content --> theme
theme --> app
app --> boot
testing -. exercises every layer .-> terminal
testing -.-> drawing
testing -.-> app
```
The engine is deliberately standalone. Runtime dependencies are limited to
`libc` (unix), `windows-sys` (windows), `unicode-width`,
`unicode-segmentation`, and `miniz_oxide` (PNG inflate). ANSI emission, input
parsing, the flexbox solver, the signals runtime, JSON parsing (for glTF),
PNG chunking and defiltering, base64, sixel encoding, and the 3D math and
rasterizer are all implemented in-crate.
Above the crate sits one more deliberate layer: the **sibling-crate
extension family** ([ADR-0004](adr/0004-extension-packaging.md)).
Genuinely new domains — graph layout + rendering
(`abstracttui-graph`), mermaid diagrams (`abstracttui-mermaid`) —
ship as separate crates in an in-repo cargo workspace
(`extensions/*`), built and tested against core HEAD in CI but
installed by downstreams only when needed. Extensions consume the
PUBLIC API exclusively (the same "no private engine privileges" rule
the built-in widgets live under); a capability an extension needs and
cannot reach is, by definition, a core backlog item. They inherit the
dependency posture (hand-rolled parsers, std + the family), the token
discipline, and the honest-degradation principle; publish order is
core first, family the same day. The family guide is
[graphs-and-diagrams.md](graphs-and-diagrams.md).
## Pillar 1: fine-grained reactivity
The `reactive` module implements signals, memos, and effects with ownership
scopes, in the SolidJS tradition rather than the React one. Reads are tracked:
while a computation runs, every `Signal` it reads records an edge to it. A
write marks direct observers dirty and transitive observers for re-check,
then flushes queued effects — immediately after the write, or once at the end
of a `batch`. Each effect pulls its sources up to date before running, so it
observes a single consistent world (diamond dependencies cannot glitch).
Memos recompute lazily and stop propagation when the new value compares equal.
Ownership scopes tie state to component lifetime: signals, memos, effects,
and cleanups created on a `Scope` die when that scope is disposed, which is
what happens when a dynamic view region unmounts. The UI consequence is the
important one: components are plain functions that run **once** to build a
view blueprint. Reactivity lives in `dyn_view` regions that re-run when the
signals they read change — a parent never re-renders a child, and there is no
tree diff. A changed region marks damage for exactly the cells it owns.
Draw closures are pure over data captured at view-build time; reading a
tracked signal inside a draw closure is a debug-mode panic. This is what
keeps the frame model (below) airtight: painting cannot create new damage.
Background threads reach this world through the live-data lane
(`channel_source`, `latest_source`, `bounded_source`, `interval`): producers
post values, a waker coalesces any burst into one wakeup, and the bound
signal is written on the UI thread at the next frame's update phase — the
single-writer rule is preserved by construction. Overflow policies and drop
counters keep back-pressure honest. Reconnect rides the same lanes:
`reactive::connection` owns the connection state machine and its jittered
retry schedule (`Backoff`), with worker reports crossing on the posted-jobs
lane and retries armed on the timer heap — offline costs zero wakeups until
the retry is due. See [Live data](live-data.md).
## Pillar 2: the compositor
The `render` module owns everything between "widgets wrote cells" and "bytes
reached the terminal":
- **Z-ordered layers.** Each layer is a cell surface with an offset, opacity,
a blend mode, an optional color transform, and an optional per-cell shader.
Animations translate or fade whole layers without re-rendering their
content.
- **Blending.** Colors are RGBA. `Blend::Normal` is source-over;
`Blend::Additive` accumulates light (for glows, particles, scanline
highlights). Alpha means transparency while compositing, and "terminal
default color" once a frame reaches the presenter.
- **Per-cell shaders** transform cells as a pure function of `(x, y, t, cell)`.
Shaders are billed by damage: a shader runs only where damage exists, so a
static shader is paid once at install and never again. An animated shader
is an animation — advancing its clock damages what the shader's
`changed_region` hint declares (default: the whole layer) and requests the
next frame like any tween. The hint contract is stability outside the
declared rect, property-tested for every built-in shader.
- **Damage tracking.** Every draw records its own damage automatically.
Damage may honestly over-approximate: the diff re-checks equality, so stale
damage costs microseconds, never wrong pixels.
- **Frame diff and presentation.** The flattened frame is diffed against what
the terminal currently shows, producing minimal runs. The presenter turns
runs into byte-economical ANSI: cursor-motion economy, SGR run
minimization, truecolor with 256/16-color downlevel, DEC 2026 synchronized
output so frames land atomically, and a scroll-region optimization that
detects full-width band shifts (log append, list scroll) and replays them
as DECSTBM scroll commands instead of repainted rows. All bytes are
buffered and flushed to the terminal exactly once per frame.
All output flows through the presenter — including foreign payloads. Image
protocols emit through `Presenter::external_write`, which flushes pending
runs, positions the real cursor, emits the payload, and invalidates cursor
and SGR assumptions afterward. Nothing writes to the terminal behind the
presenter's back.
## Pillar 3: capability-driven graphics
The `gfx` module serves bitmaps through the best channel the terminal
actually offers, on an explicit quality ladder:
1. **kitty graphics** — upload once by id, place and move by escape, true
deletion;
2. **iTerm2** (OSC 1337) — full base64-PNG re-emit at the cursor;
3. **sixel** — paletted raster at the cursor;
4. **unicode mosaic** — colored half-block, quadrant, sextant, or braille
glyphs, with optional dithering. This is plain cells, so it works on any
terminal and composites like any other content.
Which channel applies is decided by detected capabilities, never by
assumption, and every degradation is labeled with a reason rather than
applied silently — `MosaicMode::auto` returns both the chosen mode and why.
The `three` module renders into the same pipeline, so a 3D viewport and a
PNG follow identical presentation rules.
## The frame lifecycle
The application runtime drives one strictly-sequenced pass per frame on the
UI thread:
```mermaid
flowchart LR
U["USER<br/>drain posted jobs,<br/>dispatch events in one<br/>reactive batch,<br/>flush effects"]
L["LAYOUT<br/>re-solve dirty<br/>subtrees"]
D["DRAW<br/>run draw closures for<br/>damaged regions only"]
C["COMPOSE<br/>flatten layers,<br/>shaders, blending"]
P["PRESENT<br/>diff to minimal ANSI,<br/>one flush"]
S["SWAP<br/>frame becomes<br/>previous"]
U --> L --> D --> C --> P --> S
S -->|sleep until input, timer,<br/>or a requested frame| U
```
User code runs only in the USER phase. Input dispatch is wrapped in one
reactive batch; effect flush is where dynamic views remount and layout
re-solves are requested. From LAYOUT onward no user code runs, therefore no
signal writes, therefore no re-entrant damage: the frame's damage set is
sealed when LAYOUT begins. Signal writes from other threads arrive only as
posted jobs, and posted jobs run only in the USER phase — a write landing
mid-frame wakes the loop and is drained by the next frame. Late damage is
never lost and never double-painted, by construction rather than by
discipline. One engine-owned addition happens inside DRAW itself: an image
pre-pass folds the rects vacated by moved or removed image placements into
the frame's damage (and, where a byte protocol left pixels the cell model
cannot see, poisons the previous-frame model so the diff re-emits them) —
deterministic driver bookkeeping, not user code, so the seal against
re-entrant damage stands.
The cursor follows the same economy. The default is the terminal's native
cursor, parked by the presenter, so a focused-but-idle text field costs
nothing. A composited or animated cursor is an animation: it requests frames
and is billed as one.
## The damage promise
The frame model rolls up into one product guarantee:
> **An idle AbstractTUI app costs zero: zero bytes written, zero heap
> allocations, zero shader work.**
This is enforced by tests, not stated as an aspiration. In-tree tests pin
each clause: an idle frame emits zero bytes
(`render::present::tests::zero_runs_zero_bytes`, and the third frame of
`render::pipeline_tests::full_pipeline_small_damage_small_bytes`), a
no-change frame allocates nothing
(`alloc_budget::presenter_no_change_frame_emits_and_allocates_nothing`),
steady-state diff and present allocate nothing
(`alloc_budget::diff_present_steady_state_allocates_nothing`), a static
shader on an idle layer performs zero shade calls
(`render::compositor::tests::shader_runs_only_for_damaged_cells_and_never_when_static`),
and the guarantee holds through the whole app layer with the modern
mounts in play — a streaming `Feed`, an armed `interval`, a parked
`Select` popup, a parked protocol image — where sixteen idle turns
through the real driver allocate nothing and write nothing
(`alloc_budget::idle_turns_with_feed_interval_parked_popup_and_parked_image_allocate_nothing`),
and again with the AV surfaces mounted — a settled `Meter`, a quiet
`AudioScope`, armed key state, and a bound push-to-talk
(`alloc_budget::idle_turns_with_parked_meter_scope_and_key_state_allocate_nothing`).
Idle really means idle: the event loop blocks in a terminal read with zero
wakeups until input, a resize, a cross-thread wake, or a timer deadline
arrives. Animations never poll — an active animation requests one more frame
through the scheduler and simply stops asking when it settles, and each
animated layer is billed for exactly the damage it declares.
The active path is budgeted too: diff plus present of a full-change 200x60
frame runs in roughly 450 microseconds median on an M-class laptop, and the
steady-state hot path performs no heap allocation. The irreducible byte cost
of truecolor styling is the SGR payload itself; 256-color caps are the lever
for byte-constrained links.
## The terminal layer
The `term` and `input` modules are the platform boundary, kept small enough
to audit line by line. The posture:
- **Raw mode and session lifecycle.** `enter` switches to raw mode, the
alternate screen, and the requested modes; `leave` undoes everything in
exact reverse order. Restore is layered three deep: explicit `leave`,
`Drop` if you forget, and a process-global `term::emergency_restore` for
panic hooks. Cursor style, window title, pixel-mouse mode, and kitty
keyboard flags are all tracked and reset — including from a panic.
`App::run` installs the panic hook before anything else, so a panic in any
draw closure or handler still restores the screen.
- **Capability detection is evidence, not folklore.** Detection runs in two
passes: an instant, conservative environment pass for the first frame,
then an active query probe that runs concurrently and can both raise and
lower the answer — a terminal that replies "mode not recognized" is
believed. Color depth, kitty keyboard and graphics, sixel, synchronized
output, cell pixel geometry, and pixel-mouse support are all probed with
safe timeouts. `NO_COLOR` and `TERM=dumb` are honored.
- **Kitty keyboard protocol.** Progressive enhancement flags are pushed on
enter and popped on leave. Under the kitty protocol (or xterm's
modifyOtherKeys) the engine decodes press/repeat/release and chords such
as Ctrl+Enter or Shift+Enter that are byte-identical to plain Enter on the
classic wire. Applications should treat those chords as enhancements;
arrows, Home/End, PgUp/PgDn, and F1-F12 with any modifier combination are
reliable everywhere.
- **Mouse, including pixel coordinates.** SGR mouse tracking delivers cell
coordinates always; raw pixel coordinates ride alongside only when pixel
reporting is verifiably active. Pixel reporting is a mid-session toggle
(applications flip it while a pointer hovers an image), with the same
latch-and-restore machinery as the cursor style.
- **Bracketed paste is the only paste path.** Paste is fuzz-hardened:
multi-megabyte pastes stream in bounded chunks, byte-exactly, with
embedded escape sequences neutralized as content. Copy-to-clipboard uses
OSC 52, gated on detection; the read form of OSC 52 is deliberately never
emitted — it would let any application read the user's clipboard.
- **Keyboard input is never silently dead.** If the platform refuses to poll
the terminal descriptor (a real macOS quirk with `/dev/tty` that the
engine detects and avoids), the reader falls back to a working descriptor
with a labeled degradation surfaced through startup notices, or fails with
an actionable error. An app that starts is an app that receives keys.
- **One event stream that never lies.** Keys, mouse, paste, focus, resize,
and terminal query replies arrive ordered through one reader. Unknown or
hostile escape sequences are swallowed and surfaced as `Unknown` events —
foreign bytes cannot forge keystrokes; the parser never panics on any
input and is continuously fuzzed. Resize comes from platform ground truth
(never parsed from bytes), is deduplicated, and is re-checked on every
wake so a missed signal cannot leave a stale layout.
- **tmux, honestly.** Inside tmux, pixel graphics are off by default because
tmux swallows the protocols unless passthrough is enabled — which is
invisible from the environment. The engine verifies passthrough per
session with a wrapped round-trip probe and only then enables the kitty
and iTerm2 paths, wrapped automatically. tmux cannot reflow passthrough
images across scrolling or pane splits; that limit is cosmetic and stated.
- **Suspend/resume is a first-class verb** on unix: full restore, stop the
process group, re-enter on resume. On Windows it returns an explicit
`Unsupported` error.
## The 3D pipeline
The `three` module loads binary glTF (GLB) with a validation-first posture:
typed accessors are checked against the buffers they index, unsupported
features are rejected by name (sparse accessors, Draco and meshopt
compression, non-triangle primitive modes), and recoverable gaps degrade
with labels (external URIs, normal/metallic-roughness/occlusion maps, morph
weights). A two-million-triangle budget is enforced from metadata before any
allocation happens.
Rendering is a software perspective rasterizer: near-plane and guard-band
clipping, top-left fill rule, z-buffer, perspective-correct depth and UVs,
lambert-plus-ambient shading, base-color textures with a box-filter mip
chain. Node TRS and matrix hierarchies animate via LINEAR and STEP keyframe
tracks; skinned meshes blend up to four joints per vertex. Pose sampling is
pure in `t` and allocation-free at steady state, so playback costs are
predictable. Output lands in an RGBA framebuffer that flows through the same
image ladder as any bitmap — mosaic cells universally, pixel protocols where
the terminal proves them. A model of 20k triangles or fewer renders in under
2 ms at typical viewport sizes; ~120k triangles holds 30 fps with headroom
on one core (reproduce with
`cargo test --release -- --ignored perf_three_envelope --nocapture`).
## Platform posture
macOS and Linux are the verified platforms. Every unix code path is exercised
by a live pseudo-terminal test suite — signal-driven resize, job-control
suspend, and keystroke flow under a real controlling terminal — and tmux
passthrough has been proven live against tmux 3.7b.
Windows support is best-effort and honestly labeled: the backend compiles
cleanly and is lint-clean against the MSVC target, its platform-independent
logic (UTF-16 surrogate pairing, wake latching, resize deduplication) is
unit-tested on every host, and its console usage was written against
Microsoft's documented semantics — but it has not yet executed on a live
Windows machine. Treat the first Windows run as a beta event, not a
certified path. The rendering path itself is identical ANSI everywhere
(Windows 10+ VT processing), so the platform delta is confined to the
terminal layer.
Diff/present correctness is property-tested against the in-crate VT
interpreter: the bytes the presenter emits, applied to the previous screen,
must reproduce the intended screen — including wide-glyph pairs at scroll
boundaries. The input parser is fuzzed with hostile corpora on every build.
===== FILE: docs/api.md =====
# AbstractTUI API Guide
A guided tour of the public API, module by module. This is not a reference —
the item-by-item rustdoc is the reference (`cargo doc --open`, or browse
[docs.rs](https://docs.rs/abstracttui)). The goal here is orientation: what
each module is for, the types you will actually touch, and the idioms the
engine expects. Snippets are lifted from the crate's compiled doctests
wherever possible, so they match the shipped code.
## The prelude
`use abstracttui::prelude::*;` is all an application needs for the common
path. The prelude is curated to the app-code surface only: engine and test
types (`UiTree`, `Driver`, `create_root`, canvases) stay behind explicit
imports. One deliberate absence: `render::Style` is not exported, because two
`Style` types one glob apart is a trap. Layout style is exported as
`LayoutStyle` (box geometry — direction, size, gap); paint style is spelled
`render::Style` in full, inside draw closures, where it belongs.
## reactive — signals, memos, effects
`Signal<T>` is tracked state, `Memo<T>` is derived state, and an effect is a
computation that re-runs when anything it read changes. Handles are `Copy`;
state is owned by the `Scope` that created it and dies when that scope is
disposed. `batch` coalesces writes so effects observe one consistent world;
`untrack` reads without subscribing. The model in one compiled example:
```rust
use abstracttui::reactive::{batch, create_root};
use std::{cell::RefCell, rc::Rc};
let log = Rc::new(RefCell::new(Vec::new()));
let (root, ()) = create_root(|cx| {
let count = cx.signal(0);
let doubled = cx.memo(move || count.get() * 2);
let log2 = log.clone();
cx.effect(move || log2.borrow_mut().push(doubled.get()));
count.set(3);
batch(|| {
count.set(4);
count.set(5); // coalesced: the effect sees only 10
});
});
assert_eq!(*log.borrow(), vec![0, 6, 10]);
root.dispose();
```
(`create_root` is the standalone entry point; inside an app, `App::mount`
hands your component a ready `Scope`.) Two time-aware helpers round out the
module: `animate(cx, source, easing, duration)` returns a signal following
`source` through eased transitions (settled values cost zero frames), and
`after(delay, f)` runs a one-shot closure on the UI thread, costing zero
wakeups until due.
Timers arm AND fire against the loop's clock, never a stray wall-clock
read: inside a driven turn the driver publishes its (injectable) clock,
so one injected test clock scripts `after`/`interval` deadlines end to
end (an `after(0)` armed under an injected timeline comes due on that
timeline, even when real time has raced ahead). Custom loop authors
driving `run_due_timers(now)` publish the same value around their
user-code phases with `reactive::set_loop_clock(Some(now))` — the
driver does this automatically — and `None` restores real-time arming
for bare rigs.
## reactive::connection — lifecycle + jittered reconnect
`connection(cx, backoff, dial)` owns what every networked app
hand-rolls around its transport: the state vocabulary, the retry
schedule, the armed retry timer, and cancellation. The engine does NO
network I/O — `dial` runs on the UI thread once per attempt, spawns
the app's transport work (`spawn_worker` plus the HTTP client, socket,
or subprocess of your choice — the transport stays the app's call),
and reports through the `Clone + Send` `ConnectionEvents` reporter:
`connected()`, `degraded(reason)`, `failed(reason)`, `closed()`
(clean, terminal). Reports apply on the UI thread in the next phase U;
reports from a SUPERSEDED attempt (a zombie worker racing the retry
that replaced it) or after close are inert and counted
(`stale_reports`, the `dead_sends` convention). Workers poll
`is_closed()`/`is_current()` as their stop conditions.
`conn.state()` is a `Signal<ConnState>` the UI renders like any other:
`Connecting`, `Connected`, `Degraded(reason)`, `Reconnecting {
attempt, next_in }` (render "retry #2 in 1.4s" from the fields),
`Closed` — a closed vocabulary by design (transport semantics must not
grow into it). `conn.close()` is the UI-side terminal close;
`conn.retry_now()` skips a pending wait; scope disposal closes, cancels
the armed timer, and drops the dial fn.
`Backoff` is the pure schedule: FULL jitter — uniform in `[0,
min(cap, base × 2^attempt)]` — with defaults base 500 ms, ×2, cap
30 s, `reset()` on success (the machine calls it on connect), and
`seeded(n)` for deterministic tests. Jitter is not optional
politeness: un-jittered fleets retry in lockstep after a server
restart (the thundering herd). While reconnecting the loop stays
parked — the one armed one-shot costs zero wakeups until due, and a
`Closed` connection costs nothing forever (test-pinned). See
[live-data.md § "Connection lifecycle"](live-data.md#connection-lifecycle)
for the state diagram and a worker-thread example.
## ui — elements, views, composition
`Element` is the view-tree builder: layout style, children, focusability,
event handlers, keyboard shortcuts, an optional draw closure, and an
optional intrinsic measure (`.measure(fn(Size) -> Size)`) so a draw
widget can answer `Auto` sizing like a text leaf instead of defaulting
to zero.
Components are plain functions `fn(Scope, Props) -> View` — no trait, no
registry. They run **once**; reactivity comes from `dyn_view(style, f)`,
which re-runs `f` when the signals it reads change and re-renders only that
region. Props structs carry data fields, `Callback<T>` fields for typed
events out, and `View` fields as slots for children:
```rust
use abstracttui::prelude::*;
use abstracttui::widgets::Button;
struct CardProps {
title: String,
on_close: Callback<()>, // typed event out
children: View, // slot
}
fn card(cx: Scope, props: CardProps) -> View {
let close = props.on_close.clone();
Element::new()
.style(LayoutStyle::column())
.child(
Element::new()
.style(LayoutStyle::row())
.child(text(props.title))
.child(Button::new("x").on_click(move || close.call(())).view(cx))
.build(),
)
.child(props.children) // the slot mounts where the component says
.build()
}
```
Events route capture → target → bubble with hit testing and focus
management; `KeyChord` shortcuts attach to any element. For app-scale state,
the endorsed pattern is a store struct of signals provided as context —
`cx.provide_context(store)` at the root, `cx.use_context()` anywhere below.
Signals are `Copy` handles, so cloning the store shares state: no prop
drilling, no reducer framework.
### Double-click
Terminals report only raw press/release — the engine synthesizes
multi-click counts (same button, within 400 ms, within 1 cell; wheel,
drags, and a different button reset the chain; modifiers don't break
it). Every mouse-Down handler can read the press's chain position via
`ctx.click_count()`: 1 = isolated press, 2 = a double-click's second
press, 3 = a triple's third. Both presses deliver normally — nothing is
delayed waiting for a second click — so the convention is one `if` in a
press handler: **single-click selects, double-click activates** (click 1
did the selecting; click 2 additionally commits).
[`Table::on_activate`](#table--selection-vs-activation) ships exactly
that; [`List`](#list--selection-vs-activation)'s click-on-selected
picker gesture subsumes it without a timer (`examples/activate.rs`
shows both side by side). The recipe for hand-rolled rows (custom
cards, graph nodes):
```rust
use abstracttui::ui::{MouseButton, MouseKind, UiEvent};
// inside .on(Phase::Bubble, |ctx, ev| { ... })
if let UiEvent::Mouse(m) = ev {
if matches!(m.kind, MouseKind::Down(MouseButton::Left)) {
// select the row under m.pos here (every press), then:
if ctx.click_count() >= 2 {
// open/commit the row — guard that BOTH presses hit the
// same logical row (Table gates on already-selected), or a
// fast click-walk down adjacent rows would spuriously open.
}
}
}
```
Counts flow only where time flows: the driver publishes its
(`set_clock`-injectable) clock as the ambient event time each turn, so
apps under `App::run` get counts for free and tests script double-click
timing through the same injected clock animations use — and, since the
wave-11 timer fix, the same clock timer deadlines ARM against
(`reactive::set_loop_clock` is the custom-loop half of that one-clock
story; see the reactive section). A bare `UiTree`
driven directly has no time source and every press deterministically
counts 1 — harnesses opt in with `ui::set_event_time(Some(t))`. Custom
input paths outside tree dispatch can embed their own `ui::ClickChain`
(the pure state machine: `observe(now, &event) -> count`, configurable
`window`/`tolerance`) and read `ui::event_time()` for the engine's
clock.
## layout — flex and grid
The layout solver is a flexbox subset over integer cells: `Direction`
row/column, `grow`/`shrink`/`basis`, `gap`, padding, margin, min/max,
percent and absolute positioning, plus wrapping (`wrap()`, `cross_gap`).
Rounding is largest-remainder, so children tile their container exactly.
`Display::Grid` adds track grids: columns and rows are `Track::Cells(n)`,
`Track::Percent(f)`, `Track::Auto` (content-sized), or `Track::Fr(w)`
(weighted leftover); children auto-place row-major and can span via
`col_span`/`row_span`. `Overflow` (`Visible`/`Clip`/`Scroll`) is the
clipping and wheel-routing vocabulary.
```rust
use abstracttui::prelude::*;
// Sidebar + growing content in a row.
let sidebar = LayoutStyle::default().width(Dimension::Cells(24));
let content = LayoutStyle::default().grow(1.0);
// A label/field form as a track grid.
let form = LayoutStyle::default().grid(
vec![Track::Cells(12), Track::Fr(1.0)], // columns
vec![Track::Auto, Track::Auto], // rows
);
```
### Small terminals & content pressure
The engine guarantees, at any viewport size and any content volume: a
child flex crushes to zero area is CLEAN ABSENCE — its draw closure
does not run (so a hand-rolled bar can never smear onto a sibling's
row), the collapse is named by a startup notice in debug builds, and
the row repaints correctly when the child returns. `Modal` and `Drawer`
clamp inside the viewport at open AND re-clamp on every resize; tab
strips window with overflow indicators; wide glyphs never tear at a
truncation or clip edge. Two recipes remain the app's job: give chrome
you want incompressible `shrink(0.0)` (or wrap the oversized middle in
a `Scroll`, whose default `basis(0)` exerts no pressure), and render
`use_startup_notices` somewhere visible — the engine names every
zero-collapse into that lane, and a notice nobody renders is a
debugging session someone else pays for.
## widgets — the built-in library
Every widget is built from the same public `ui` + `layout` + `theme` surface
user code has — widgets hold no engine privileges. They consume design
tokens only, never raw colors; the canonical build is `.view(cx)` (theme
from context), with an `element` form for explicit tokens — stateless
widgets take just `&TokenSet`, no `Scope`. One honest exception:
`Meter` and `AudioScope` are `view(cx)`-only (signal-driven — their
tokens resolve TRACKED inside their own reactive region, so a
fixed-token `element` form would need a wrapper node just to change the
token source; the deliberate absence is documented in their rustdoc).
Controlled-mode bindings are named after the STATE they bind: `value`
(`Select`/`Combobox`), `selection` (`List`/`Table`), `active`
(`PageHost`), `folded` (`Disclosure`), `offset_x`/`offset_y`
(`Scroll`) — new widgets follow the state-name rule; the one historical
outlier is `Drawer::bind(Signal<bool>)`. The catalog:
- **Block** — the bordered panel primitive: title, fill, focus ring, `BorderKind`.
- **Button** — clickable label; hover/pressed/focused/disabled visuals; Enter/Space or mouse fires `on_click`.
- **TextInput** — single-line editor: grapheme-cluster-atomic cursoring, selection, word jumps, `on_change`/`on_submit`; `.masked(true)` for secret fields (bullets on screen AND in the accessibility export).
- **TextArea** — multiline composer: soft wrap, vertical caret with goal column, grow-to-content between `rows(min, max)`, submit-vs-newline policy, history recall, block paste, and a caret-cell anchor for completion dropdowns (`TextAreaState` is the app wire).
- **List** — virtualized selectable list; variable-height items, sticky selection by key, `scroll_to`. Vocabulary: `on_select` = selection changed (fires on movement); `on_activate` = the user committed this row (Enter/Space/click-on-selected).
- **Feed** — virtualized, append-only, keyed rich items (markdown in the full doc vocabulary — tables, lazy in-flow images, task lists — plus plain text, code fences, custom draws): the chat/log/transcript surface. Appends are O(1); a streaming tail item re-typesets only its open region (a streamed table renders as a table live); 10k items draw one screenful.
- **Table** — fixed/percent/flex columns, styled header, virtualized rows, selection, sort-indicator hook (the app sorts). Vocabulary: `on_select` = selection changed (fires on movement); `on_activate` = the user committed this row (Enter/Space/double-click — a single click only selects; see the Table section below).
- **Tabs** — tab bar over lazily mounted panels; only the active panel is mounted.
- **PageHost** — the page-level tab host: N FULL pages behind one themed tab bar, exactly one mounted (see [its own section](#widgetspagehost--the-page-level-tab-host) below).
- **Disclosure** — the fold/unfold card: a one-row title header (glyph + truncating title + muted detail slot) that expands a body in place. Click or Enter/Space toggles; `max_body_rows` caps the body behind a scrollbar; state is widget-internal (`initially_folded`) or app-owned (`folded(Signal<bool>)`).
- **Scroll** — clipped viewport over oversized content, mounted once so state, focus, and hit testing survive scrolling. The content extent is measured by the layout solver (`content_size` is an optional override) and can be read back through `extent_signal`; `follow_tail` binds the pinned-to-bottom idiom; `scrollbar_auto_hide` hides the bar while content fits.
- **Checkbox** — `[x] label` bound to a `Signal<bool>`.
- **RadioGroup** — one-of-N bound to a `Signal<usize>`; one tab stop, Up/Down move the selection.
- **Progress** — bar with sub-cell precision; optional ok→warn→error ramp.
- **Spinner** — indeterminate activity glyph, pure over a caller-owned frame index.
- **Badge** — small tinted label for status chips, counts, tags (`Tone`).
- **Separator** — horizontal or vertical rule, optionally labeled.
- **Charts** — `Sparkline`, `LineChart`, `BarChart` on sub-cell grids, with
optional relative time axes fed from a `TimeSeries` history ring (see the
history-rings section below).
- **Grid** — container widget over `Display::Grid`; spans ride each child's own style.
- **Image** — bitmap display through the mosaic pipeline (`ImageFit`; `Bitmap` re-exported beside it). Measures as its native cell footprint, so it holds real space in `Auto`-sized rows/panels.
- **Viewport3D** — orbiting 3D view of a `three::Model`: `.orbit(yaw, pitch, zoom)`, `.animate(clip, t)`, `.on_orbit`/`.on_zoom` deltas; camera state lives app-side in signals. Grows into its region by default (a draw widget has no intrinsic size — the old zero-height default rendered nothing without an explicit `.layout`).
- **MarkdownView / RichTextView / CodeView** — typeset markdown (doc vocabulary: GFM tables, lazy in-flow images, task lists, plus outline/anchor rows and find-with-highlights — see the reader-surface section below), wrapped styled spans, read-only highlighted code.
- **Meter / AudioScope** — live level rendering: dB meter with real ballistics (instant attack, timed decay, peak hold) and a rolling braille waveform — see the live-levels section below.
- **Logo** — the AbstractTUI wordmark for headers, about screens, empty states.
### Code and diffs — lexers and their theme mappings
`CodeView` tints through the pluggable `text::Highlighter` seam (byte
ranges + `TokenKind`; the built-in `CLikeLexer` is honest demo-grade),
and `widgets::code_token_color` is the ONE place token kinds become
theme inks. Diffs are line-oriented, not token-oriented, so they ride a
dedicated additive vocabulary: `text::DiffLexer` classifies each line
(`DiffKind`: added, removed, hunk header, file header, meta chrome,
context — `#[non_exhaustive]`, so downstream matches carry a `_` arm
rendering unknown kinds as body text), and `widgets::diff_token_color`
maps it onto the SEMANTIC inks — added `ok`, removed `error`, hunk
headers `info`, chrome `text_muted` — readable on the `surface_raised`
code ground in every built-in theme (measured, test-pinned).
Routing is by language label, best effort: `CodeView::lang("diff")`
(also `"patch"`/`"udiff"`; `"rust"`/`"c"` pick C-like presets; unknown
labels change nothing), and markdown/Feed code fences labeled
` ```diff ` route automatically — one shared recipe, so a fence and a
`CodeView` can never tint the same patch differently:
```rust
use abstracttui::widgets::CodeView;
fn patch_pane(patch: &str, t: &abstracttui::theme::TokenSet) -> abstracttui::ui::Element {
CodeView::new(patch).lang("diff").element(t)
}
```
Classification is stateless per line (scroll-position-invariant by
design) and approximate by contract: a removed line whose content
begins `-- ` reads as a file header (the classic highlighter
resolution), and prose between hunks stays untinted.
### List — selection vs activation
Selection FOLLOWS MOVEMENT: arrows/Home/End/Page keys and clicks move
the highlight, and `on_select` is the selection-changed notification —
never wire commitment, navigation, or destruction to it. Activation is
the EXPLICIT "user chose this row" event: `on_activate` fires on Enter
(always), on Space (a List has no toggle meaning), and on a click on
the already-selected row; a click on an unselected row only selects.
Double-clicks work by subsumption — click 1 selects, click 2 lands on
the now-selected row and activates, with no timing requirement (the
picker gesture is deliberately broader than `Table`'s timed
double-click). Both callbacks run after the List's own bookkeeping
(selection write, ensure-visible), so an `on_activate` may close the
surrounding modal — disposing the List's scope synchronously is safe.
When `on_activate` is unbound, Enter and Space pass through to your
shortcuts unchanged:
```rust
use abstracttui::prelude::*;
fn theme_picker(cx: Scope, apply_and_close: impl FnMut(usize) + 'static) -> View {
List::of(["dark", "light", "solarized"])
.on_activate(apply_and_close) // Enter / Space / click-on-selected
.view(cx) // browsing with arrows only moves the highlight
}
```
### Table — selection vs activation
Same split, browsing-surface edition: `on_select` notifies selection
movement (arrows/Page/Home/End/click); `on_activate` is "open this row"
— it fires on Enter (always), on Space (a single-select table has no
toggle meaning; a future multi-select mode will claim Space as toggle
within that mode), and on **double-click**: the second press of a click
chain landing on the already-selected row. Deliberately unlike `List`,
a slow second click on the selected row does NOT activate — re-clicking
a row to focus the pane must never open its editor. Both presses of a
double-click deliver normally (click 1 selects, click 2 activates;
selection is never suppressed), a chained press that drifted onto a
NEIGHBOR row only re-selects (fast click-walking down rows is browsing,
not commitment), and a wheel between clicks resets the chain (the
content under the cell moved). When `on_activate` is unbound, Enter and
Space pass through to your shortcuts — same contract as List (and the
gateway-console rule: a screen-level key must never be claimed by a
widget with no consumer):
```rust
use abstracttui::prelude::*;
use abstracttui::widgets::{ColWidth, Column};
fn providers(cx: Scope, open_editor: impl FnMut(usize) + 'static) -> View {
Table::new(vec![
Column::new("provider", ColWidth::Flex(1.0)),
Column::new("status", ColWidth::Cells(12)),
])
.rows(vec![/* ... */])
.on_activate(open_editor) // Enter / Space / double-click
.view(cx) // single-click only selects
}
```
### TextInput — masked (secret) fields
`.masked(true)` renders one `•` per grapheme cluster (a ZWJ emoji
family is one bullet; each bullet occupies its cluster's width, so
scroll and cursor geometry match the unmasked field) and exports the
same bullets through `access_value` — the accessibility snapshot is
shipped off-process by automation consumers, so a masked field never
leaks plaintext through the semantic tree either. Editing, selection,
cursor math, and paste are untouched; the bound value signal holds the
real text. One deliberate exception: Alt+arrow word jumps treat the
whole masked value as a single word (start/end, like Home/End,
Shift-extension included) — true word boundaries would reveal the
secret's word count and word lengths through caret motion. For a
reveal toggle, rebuild the field with `masked(false)`
inside a `dyn_view_scoped` over your reveal signal.
### Feed — streaming transcripts
An app owns a cloneable `FeedState` handle and mutates it; the `Feed`
widget windows over it. Items are keyed identities (`push` with a known
key replaces); a streaming item rides `md::DocStreamSession`, so a
token append costs one open region, never the document. Markdown items
speak the full DOC vocabulary: an agent answer streaming a GFM table
renders as a TABLE live (the whole in-flight table is the open region
until its first non-pipe line seals it), task lists wear checkboxes,
`~~strikethrough~~` strikes, and `` images typeset from a
header-only probe (decode happens lazily when an image row first
draws — items measure and window without decoding). `total_rows()` is
the reactive content extent, and `clear()` rebuilds bounded windows:
```rust
use abstracttui::prelude::*;
use abstracttui::widgets::{Feed, FeedItem, FeedState};
fn transcript(cx: Scope) -> View {
let feed = FeedState::new(cx);
feed.push("q1", FeedItem::markdown("**you** — hello"));
feed.push_stream("a1"); // a live answer…
feed.stream_append("a1", "# Str"); // …fed token by token
feed.stream_append("a1", "eaming");
let follow = cx.signal(true); // render it: "following / scrolled"
Scroll::new(Feed::new(&feed).view(cx))
.follow_tail(follow)
.view(cx)
}
```
### Feed — rich lines (multi-ink without a custom block)
`FeedItem::rich` / `rich_lines` / `.rich_block` carry the engine's
span model (`render::RichText`) into feed items: a severity-tinted log
line or a chat header is spans, not a `FeedBlock::Custom` draw closure
with hand-rolled wrapping. Rich blocks typeset through the same
span-preserving wrap and row walk as every other block (cell-exact
parity with `RichTextView`, test-pinned), so wrapping, windowing and
damage behave exactly like `Text`. Span styles are patches: `fg: None`
spans inherit the item's theme ink; explicit inks are resolved `Rgba`
and render verbatim (rebuild items to retint on theme switch). Rich
items are replace-on-update; token streaming stays `push_stream`:
```rust
use abstracttui::render::rich::{RichLine, Span};
use abstracttui::render::Style;
use abstracttui::widgets::FeedItem;
fn log_line(t: &abstracttui::theme::TokenSet, ts: &str, body: &str) -> FeedItem {
FeedItem::rich_lines(vec![RichLine::from_spans(vec![
Span::new("ERROR ", Style::new().fg(t.error)),
Span::new(format!("{ts} "), Style::new().fg(t.text_muted)),
Span::plain(body), // fg-less: wears the item ink per theme
])])
}
```
(The public `FeedBlock` enum stays exhaustive through 0.2.x, so the
rich kind rides `FeedItem` constructors; `FeedBlock::Rich` proper is
budgeted for 0.3.)
### Feed — syncing from a `Signal<Vec<T>>`
When the transcript's source of truth is a FOLD (a vector recomputed
by events) rather than an append-only stream, `FeedState::sync` owns
the diff: keys are identities, fingerprints detect change, and the
optional visibility closure is the one truth for filtering. Appends at
the tail take the O(1) push path, changed fingerprints update in
place, and anything violating push order — shrink, reorder, mid-list
insert or visibility flip — takes the rebuild path inside the engine.
A rebuild re-renders every visible item, so a source that reorders on
every drain rebuilds on every drain — for feeds ordered by mutable
rank, sync a stable order and sort at render time, or accept
O(visible) per change. Float fingerprints must compare by bits
(`f32::to_bits`) — NaN never equals itself and re-renders the item
every drain.
A synced feed has ONE writer (the bridge); foreign writes are not
silent, though: the bridge detects them (a mutation counter) and
self-heals at the next drain with a full rebuild — stray items
evicted, order restored to source order. Render/key closures run on
change, never per frame:
```rust
use abstracttui::widgets::{FeedItem, FeedState, SyncSpec};
struct Msg { id: String, rev: u64, hidden: bool, text: String }
fn wire(cx: abstracttui::reactive::Scope, feed: &FeedState,
items: abstracttui::reactive::Signal<Vec<Msg>>) {
feed.sync(cx, items, SyncSpec::new(
|m: &Msg| m.id.clone(), // identity
|m| m.rev, // cheap change fingerprint
|m| FeedItem::markdown(&m.text), // pixels, built on change
).visible(|m| !m.hidden));
}
```
When the items live INSIDE a larger reactive shape — one field of a `Signal<Fold>` whose stats mutate under the same signal, or a focus-selected convo's nested vec — `FeedState::sync_with(cx, move |read| fold.with(|f| read(&f.items)), spec)` is the same bridge behind a borrow-based source (first-app/0282): the closure hands the current items over in place (zero copies), every signal it reads becomes a dependency of the sync effect, and a stats-only write re-runs the drain but the fingerprint walk renders nothing; `sync` itself delegates here.
### Feed — selection by key
`Feed::selected_key(sig)` binds a `Signal<Option<String>>`: the
selected item's row band grounds in the theme's `selection_bg` while
item inks stay (a transcript keeps its severity/syntax colors).
Selection is app-driven state — the app writes the signal and can pair
it with `FeedState::row_of(key)` (the item's first content row) to
drive a wrapping `Scroll`'s offset to the selected item. Unknown keys
highlight nothing.
### Feed — capped preview blocks (`max_rows`)
Transcript previews cap their bodies: `FeedItem::max_rows(n)` bounds
the most recently appended Text/Rich block at `n` typeset rows TOTAL,
applied post-wrap at the width the engine typesets at (the row count
only exists after the wrap — a consumer cannot precompute it). Content
that wraps to at most `n` rows renders unchanged; overflow shows the
first `n - 1` wrapped rows and spends the last row on an honest marker
— "… (+K more lines)" in `text_muted`, where K is the hidden
wrapped-row count at the current width (it changes on resize).
`FeedItem::overflow_marker(|k| ...)` overrides the wording. Extent and
windowing count the marker row, so a capped block is never taller than
`n`; chain per block (`.block(a).max_rows(3).block(b).max_rows(8)`);
streaming items are unaffected (caps live on static Text/Rich blocks):
```rust
use abstracttui::widgets::FeedItem;
fn tool_result(body: &str) -> FeedItem {
FeedItem::text(body)
.max_rows(6)
.overflow_marker(|k| format!("… (+{k} more lines — full text in the run ledger)"))
}
```
### Feed — item press (click hit info)
`Feed::on_item_press(|key, row_within_item| ...)` fires on a left
press over an item's rows — row 0 is the item's first typeset row, so
"the user clicked this card's title row" is `row_within_item == 0`.
Presses on the gap between items or past the tail fire nothing (honest
geometry, never rounded to a neighbor), and an unbound feed attaches
no handler at all. The row math is public as
`FeedState::item_at_row(row) -> Option<(key, row_within_item)>` (the
inverse of `row_of`) for apps with their own pointer logic. The
callback runs after the feed releases its state borrow, so it may
mutate the `FeedState` (re-push the pressed item) or dispose the
feed's scope.
### Disclosure — the fold/unfold card
Progressive disclosure for transcripts, message boards and settings
panes: a one-row header — fold glyph (`▸`/`▾`), truncating title,
optional right-aligned muted `detail` slot — over a body that mounts
on expand and UNMOUNTS on fold (a folded card costs zero idle work).
Click the title row, or Enter/Space while it is focused (one tab
stop; focus wears the selection pair). The card is borderless
two-tone chrome (header `surface_raised`, body `surface`) — wrap it
in a `Block` when you want a frame.
`max_body_rows(n)` (default 8) limits the unfolded body: shorter
content takes its natural height, taller content scrolls inside the
capped region with a scrollbar that auto-hides when it fits;
`max_body_rows(0)` removes the cap. Bodies: `Disclosure::text` /
`Disclosure::markdown` (typeset once through the shared Feed recipe,
kept across folds) or `.body(|scope| view)` for any `View` — the
closure runs once per EXPANSION on a generation scope, so durable
state belongs in signals outside it.
State is uncontrolled by default (`initially_folded`, default folded);
`folded(Signal<bool>)` hands the policy to the app — the signal's
current value is the state, toggling writes it back, and a
"collapse all" is a loop of writes. `on_toggle(|folded_now| ...)`
fires after the state write (disposal-safe):
```rust
use abstracttui::prelude::*;
fn cycle_card(cx: Scope, n: usize, reasoning_md: &str) -> View {
Disclosure::markdown(format!("cycle {n}"), reasoning_md)
.detail("12 lines")
.max_body_rows(6)
.view(cx) // folded by default: the header is the summary
}
```
#### The message-card recipe (Feed + Disclosure semantics)
A hub/chat transcript wants Feed virtualization AND per-card fold —
today that composes from parts (both validator apps hand-rolled
exactly this; it is now the packaged pattern). Keep fold state in a
`Signal<HashMap<key, bool>>`, include it in the `FeedState::sync`
fingerprint `(rev, folded)` so a toggle re-typesets exactly the
changed item, render folded items as one rich header line (+ an
optional `max_rows` preview) and unfolded items as header + body
blocks, then wire both toggle surfaces: Enter on the selected key
(`Feed::selected_key`), and click via `on_item_press` gated on
`row_within_item == 0` — flip the key's entry, bump the fingerprint,
and the feed re-renders that card in place (extent and follow-tail
stay exact because item heights are re-typeset, never guessed). A
Feed-NATIVE card item kind (engine-owned title row inside the feed's
own block vocabulary) remains future work: feed blocks are draw-only
regions today (the 0280 block-boundary honesty), so the packaged
per-item WIDGET is `Disclosure`, and inside a `Feed` the pattern
above is the supported shape.
Monitors stop hand-rolling sample rings: `TimeSeriesState` (reactive)
or `TimeSeries` (plain) take `push(t, value)` — `t` is a `Duration` on
the app's clock, never a wall-clock read — quantize time into cadence
slots, and retain a bounded window (drop-by-age `new(cadence, window)`
or drop-by-count `with_slots`). Missed slots pad with `NAN`, so a
sampling pause draws as a HOLE through the charts' existing gap
contract instead of compressing the x-axis. `LineChart::time_axis(span)`
embeds relative labels in the axis rule row — "now" anchored at the
plot's right edge, nice ticks leftward, density adapting to width —
and `Sparkline::time_axis(span)` adds an optional label row. Feed the
span from the ring so warmup labels the REAL covered time:
```rust
use std::time::Duration;
use abstracttui::prelude::*;
use abstracttui::widgets::{LineChart, TimeSeriesState};
const TICK: Duration = Duration::from_millis(250);
fn traffic(cx: Scope, t: &TokenSet, sample: impl Fn() -> f32 + 'static) -> View {
let rx = TimeSeriesState::new(cx, TICK, TICK * 72); // 18s window
{
let rx = rx.clone();
let mut n = 0u32;
interval(cx, TICK, move || {
n += 1;
rx.push(TICK * n, sample());
});
}
let tokens = *t;
dyn_view(LayoutStyle::default().grow(1.0), move || {
LineChart::new(vec![rx.samples()]) // tracked: re-renders per push
.range(0.0, 100.0)
.time_axis(rx.span())
.element(&tokens)
.build()
})
}
```
### Meter and AudioScope — live levels
`Meter` renders level data with real ballistics: instant attack, timed
decay (default 20 dB/s over the meter span, frame-clocked and
frame-rate-independent — a stalled stream shows a falling bar, not a
frozen one), and a peak-hold marker (~1.5 s, then it falls to the
level). One channel or N bands, eighth-block sub-cell fill, zone colors
from the `ok`/`warn`/`error` theme tokens:
```rust,ignore
let level = cx.signal(0.0f32); // fed by the recorder lane
Meter::new(level).db_floor(-60.0).view(cx); // horizontal dB channel
Meter::bands(band_frames).bar(3, 1).view(cx); // vertical spectrum bars
```
**The idle law (pinned by tests):** a silent meter decays to its
fixpoint and STOPS requesting frames — unchanged input over any number
of turns costs zero frames and zero allocations. Only real motion bills
the frame loop.
`AudioScope` draws a rolling waveform from a `Signal<Vec<f32>>` window
on the braille chart substrate. Pair it with `bounded_source` and
`OverflowPolicy::DropOldest`: the source's retained window IS the
scope's ring (with honest drop accounting riding along). The scope owns
no clock — when the data stops, the last frame stays and nothing
re-renders.
Both are `view(cx)`-only — the catalog's one exception to the
`element(&tokens)` form. They are signal-driven by construction, and
their theme tokens resolve tracked inside the same reactive region
that follows the level data; a fixed-token `element` build would need
a wrapper node just to change where tokens come from, so it is a
deliberate absence, not an oversight.
`examples/voice_mock.rs` composes all of it — push-to-talk, meters,
scope, a fake transcription feed — with no audio and no network (the
capture gesture itself is `app::PushToTalk`, described with the app
runtime below).
### Scroll follow-tail
`follow_tail(Signal<bool>)` packages the log/transcript idiom: while
true the offset tracks the content bottom across appends and resizes;
any user scroll above the bottom sets it false; reaching the bottom
edge re-arms it. The signal is app-visible both ways — set it true for
a "jump to latest" key. Without `content_size` the extent comes from
the layout solver's measurement of the mounted content:
```rust
use abstracttui::prelude::*;
fn log_pane(cx: Scope, content: View) -> View {
let pinned = cx.signal(true);
Scroll::new(content) // extent measured — no height bookkeeping
.follow_tail(pinned) // pinned until the user scrolls up
.view(cx)
}
```
### Modal content that can overflow
Put the overflow inside a `Scroll` and keep the fixed rows fixed — the
defaults now do the bookkeeping: `Scroll`'s default layout is
`grow(1.0).basis(Cells(0))` (it absorbs overflow instead of demanding
its content size), one-row controls default `shrink(0.0)` (an
overflowing sibling can never crush them to zero rows), and
`Modal::open` floors declared fixed sizes. Opt out per row with an
explicit `min_h(0)`; debug builds log any fixed-size child that still
collapses:
```rust
use abstracttui::prelude::*;
use abstracttui::widgets::Button;
fn approval(cx: Scope, details: View) -> View {
Element::new()
.style(LayoutStyle::column().gap(1))
.child(text("Approve this tool call?")) // fixed row: stays
.child(Scroll::new(details).view(cx)) // absorbs the overflow
.child(Button::new("Approve").view(cx)) // never crushed to 0
.build()
}
```
### TextArea — the multiline composer
The chat/console input surface. `TextAreaState` (the FeedState pattern)
owns the durable wire: the value signal, the caret byte, focus, the
history store, programmatic edits, and `caret_cell()` — the caret's
solved screen cell, which anchors completion dropdowns. The widget soft
wraps at its width, grows with content inside `rows(min, max)` and then
scrolls internally; Enter submits while Alt+Enter, Ctrl+J (the universal
chord — `0x0a` IS Ctrl+J on the legacy wire, so it works on every
terminal) and Shift+Enter where the kitty protocol reports it insert a
newline — flip it with `SubmitPolicy::EnterInserts`. Up/Down navigate the buffer first and
reach for history only at the edges; the in-progress draft survives a
recall round trip. Pastes insert whole, newlines included — never a
submit:
```rust
use abstracttui::prelude::*;
fn composer(cx: Scope) -> View {
let state = TextAreaState::new(cx);
let st = state.clone();
TextArea::new()
.state(&state)
.placeholder("Message — Enter sends, Alt+Enter newline")
.rows(1, 4)
.on_submit(move |msg| {
st.push_history(msg); // Up recalls it later
st.clear();
})
.view(cx)
}
```
**Placeholder while focused** (first-app/0291): by default the
placeholder paints only while the field is empty AND unfocused — the
classic yield-to-the-caret rule — which means an `.autofocus()`ed
composer (focused from boot) never shows its hint at all. Opt in with
`.placeholder_while_focused(true)`: the hint then also paints while
focused-and-empty, one cell past the caret in the same `text_faint`
ink, so the caret block stays visible beside it — the convention
modern editors ship. The default stays off so existing apps render
byte-identically; `TextInput` has the same option.
### Completion dropdown (anchored panel)
`app::anchored` ships the passive half of the anchored-popup substrate
(backlog 0500) and the completion controller riding it (backlog 0120):
`place_panel` places below-preferred, flips above when cramped, and
clamps into the viewport; `AnchoredPanel` mounts the result as a
NON-modal overlay above everything live (`Overlays::top_z() + 1`) that
never takes focus — keys stay with the composer — and closes with its
opener's scope. `Completion` registers trigger-character providers and
wraps the composer view; while the dropdown is open, Down/Up move the
highlight, Enter/Tab accept (the candidate's `insert` replaces the
whole token), Esc dismisses, further typing refilters, and clicking a
row accepts it:
```rust
use abstracttui::app::anchored::{Completion, CompletionCandidate};
use abstracttui::prelude::*;
fn composer_with_commands(cx: Scope, app: &App) -> View {
let state = TextAreaState::new(cx);
let composer = TextArea::new().state(&state).rows(1, 4).view(cx);
Completion::new()
.trigger('/', |query| {
["help", "quit"]
.iter()
.filter(|c| c.starts_with(query))
.map(|c| CompletionCandidate::new(format!("/{c}"), format!("/{c} ")))
.collect()
})
.attach(cx, &app.overlays(), &state, composer)
}
```
Triggers fire for whitespace-delimited tokens; `Completion::trigger_at(char, TriggerPosition, provider)` additionally scopes WHERE the token may sit (first-app/0292) — `StartOfInput` (the draft's first token, leading whitespace tolerated: slash commands), `StartOfLine` (a line's first token), or the `Anywhere` default that plain `trigger` registers — and a token outside its policy never opens the dropdown nor consults the provider.
`place_panel` prefers below and flips above only when below cannot fit the content; the opener can state the mirror bias (first-app/0294) — `Completion::placement(PanelPlacement::AbovePreferred)` / `AnchoredPanel::open_passive_biased` / the pure `place_panel_biased` — so a bottom composer's short candidate list sits above the caret instead of on the chrome row below; the default stays `BelowPreferred` everywhere.
Providers run synchronously with the query typed after the trigger;
an empty Vec closes the dropdown. The OWNED mode (`Popup`, a modal
tree above the whole live stack with `DismissReason`-labeled endings:
commit, Escape, outside press, anchor scope death, and viewport
resize — a resize stales both the solved placement and the captured
anchor, so an open popup closes rather than float at stale
coordinates) and the TOOLTIP mode (`Tooltip::attach`, a hover-timed
passive label) ship beside it on the same placement engine — the
select family below rides the owned mode.
### Select / Combobox / MultiSelect — the choice controls
One family over one popup substrate, three faces (`app::select`,
re-exported in the prelude). All three render as a one-row focusable
trigger (side strokes carry focus, `▾` affordance, `text_faint`
placeholder); Enter/Space or a click opens an anchored popup that
layers above EVERYTHING live — a select inside stacked modals works —
and is placed below the trigger, flipped above when cramped. Inside,
Up/Down/PageUp/PageDown move a HIGHLIGHT (never the bound value),
Enter commits, Esc abandons, and an outside press dismisses without
acting on what is below. `on_change` fires on COMMIT only, and only
when the value actually changed; `Select::commit_on_move(true)` is the
opt-in live-preview exception (Escape then restores the pre-open
value). Options carry a stable `key`, a `label`, an optional muted
right-aligned `hint`, and `disabled` (skipped by movement, out of the
focus order). The closed control reports `Role::Button` (a select
trigger is a button that opens a menu; a dedicated `Select` role is
parked in the 0.3 breaking budget) with the current choice as its
access value; popups report `Menu`/`MenuItem`.
- **`Select`** — closed one-of-N bound to a `Signal<usize>`;
type-ahead inside the popup jumps by label prefix, a repeated char
cycles.
- **`Combobox`** — the popup includes the trigger row and mounts a
real `TextInput` there (zero visual jump); typing filters
(case-insensitive substring), the filter text is never the value, a
non-matching buffer commits nothing, and a count/"no matches" line
is part of the popup.
- **`MultiSelect`** — checkbox-marked rows; Space (or click) toggles
a working copy without closing, Enter commits the whole set into a
`Signal<Vec<String>>` of keys (canonical option order), Esc abandons
it. The collapsed row joins the chosen labels and degrades to
"N selected" when they overflow.
```rust
use abstracttui::prelude::*;
use abstracttui::theme::themes;
fn theme_picker(cx: Scope) -> View {
let picked = cx.signal(usize::MAX); // nothing chosen yet
Combobox::new(
themes().iter().map(|t| SelectOption::new(t.label)).collect(),
)
.value(picked)
.placeholder("type to search themes…")
.on_change(|i| {
set_theme_by_id(themes()[i].id);
})
.view(cx)
}
```
Inside an `App` the popup finds the overlay store through reactive
context automatically; outside one (bare-tree tests), pass
`.overlays(&overlays)` explicitly. The faces live app-side (they need
the overlay store; `widgets` sits below `app` in the layer map), but
they are plain token-consuming components with the standard
`.view(cx)` / `.element(cx, &tokens)` builds.
**Programmatic open — `SelectHandle`.** Command-summoned pickers
(`/theme`, `/model` typed into a composer) open a face without a
trigger gesture: build a cloneable `SelectHandle`, attach it with
`.handle(&h)` on any of the three faces, and call `h.open()` from a
command handler or shortcut — it returns `true` when the popup is open
after the call. The popup anchors at the trigger's LAST-PAINTED rect,
so a face that has never rendered refuses (`false`) — open on the
frame after mounting (the documented one-frame caveat). Disabled
faces, empty option lists, and unmounted faces (the wire dies with the
face's scope; dyn_view regenerations rewire automatically) also return
`false`, never panic:
```rust
use abstracttui::prelude::*;
fn command_picker(cx: Scope) -> (View, SelectHandle) {
let picker = SelectHandle::new();
let view = Combobox::new(vec![
SelectOption::new("nord"),
SelectOption::new("aurora"),
])
.handle(&picker)
.placeholder("theme…")
.view(cx);
(view, picker) // `/theme` handler calls picker.open()
}
```
## widgets::PageHost — the page-level tab host
Full complex pages behind one themed tab bar (app-kits 0545 — "a
global tab system... higher-level containers able to contain full
complex pages"). `Tabs` remains the small in-content strip; the
navigation-kit `FilterTabs` (0550, proposed) filters one surface
without panels. A `PageHost` is the app-shell container: N pages
addressed by id, exactly one mounted.
```rust
use abstracttui::prelude::*;
fn shell(cx: Scope, alerts: Signal<u32>) -> View {
PageHost::new()
.page("overview", "Overview", move |gcx| overview(gcx))
.page("reader", "Reader", move |gcx| reader(gcx))
.page("settings", "Settings", move |gcx| settings(gcx))
.badge("overview", move || {
let n = alerts.get();
(n > 0).then(|| n.to_string())
})
.number_jump(true) // opt-in: plain digits 1-9 jump
.view(cx)
}
```
- **Pages are builders** (`FnMut(Scope) -> View`) receiving a
per-activation GENERATION scope: only the active page is mounted;
switching disposes the outgoing page's scope (signals, effects,
timers, focus) and builds the incoming one fresh.
- **No keep-alive, by design**: a hidden-but-mounted page's timers
would keep ticking — the zero-idle law forbids it. Durable page
state lives in app-owned signals created OUTSIDE the builders (the
compose store pattern); builders re-read them on remount. Demo:
`examples/shell.rs` (type into Settings, leave, return).
- **Controlled or uncontrolled**: `.active(Signal<String>)` hands the
app the navigation signal (the cycle-7 router ruling: navigation
state IS a signal — external writes switch pages, `on_change` does
not fire for them); otherwise the host owns an internal signal and
`.initial(id)` picks the start page. Unknown ids fold to the first
page. `on_change(|id|)` fires after the active write on host-driven
switches (disposal-safe, the 0297 law). It hands you the page ID
where `Tabs::on_change` hands an index — deliberate, not drift: a
`Tabs` strip is positional (its panels are an ordered list), while
`PageHost` pages are id-addressed identities that navigation state
(`active(Signal<String>)`) names directly.
- **Tab bar**: two rows (titles + the `border_focus` cell strip);
active `text`+BOLD, idle `text_muted`, badges `info`, ground
`surface`. Badges are reactive getters — a count change repaints
the bar only. Overflow WINDOWS the strip around the active tab
(sticky window start; `‹`/`›` indicators are prev/next click
targets); oversized titles truncate with an ellipsis. Clicks
hit-test the bar plan AS DRAWN — the pixels on screen — so a model
change landing between a draw and a press (a badge widening) can
never shift a tab under the pointer; nothing to configure. One tab
stop, `Role::Tabs`, access value `"Title (i/N) [badge]"`.
- **Chords** (default Ctrl+PgUp/PgDn; `.chords(prev, next)` replaces,
and EMPTY sets disarm the interceptor entirely — the reserved keys
return to the content) are CONTAINER-RESERVED: intercepted at
Capture phase on the host root, because scrollable widgets match
PageUp/PageDown modifier-blind and would eat a bubble-layer chord;
plain PgUp/PgDn always stay with the content. Matching is
normalized — both wire spellings of a shifted letter fire. Chords
are live while focus is anywhere inside the host; with nothing
focused, keys target the tree root, so a host mounted AS the root
element answers from frame one (otherwise establish focus:
click/Tab/`focus_first` — inside a MODAL overlay, a `Modal` or a
modal `Drawer`, `focus_init` lands on the bar and chords answer
with no ritual). A chord/digit switch re-anchors focus on the host
root so the next chord is never dead after the focused node died
with its page.
- **Digit jumps** ride the shortcut table (never capture): a focused
text input keeps its digits; declared labels surface in
keymap-help.
## The widget disposal-safety law
**Every widget completes its own bookkeeping — every write to its
scope-owned signals — BEFORE user callbacks run, so a callback may
dispose the widget's scope synchronously.** Closing a modal from the
button that confirmed it, from the list row that picked, from the
composer that submitted, is the NORMAL shape, not a hazard; no
one-tick "retire" deferral is needed anywhere. `EventCtx` calls
(`stop_propagation`, focus/capture requests) are dispatch-owned flags
and exempt — they are safe on either side of a callback.
Covered and pinned by a disposal test per site: `Button::on_click`
(both mouse and keyboard arms), `Checkbox`/`RadioGroup`/`Tabs`
`on_change`, `TextInput` and `TextArea` `on_change`/`on_submit`,
`List::on_select`/`on_activate`, `Table::on_select`/`on_activate`/
`on_sort_requested`, and the select faces' commit `on_change` (the
popup follows its owner's scope down — the anchor-unmount cascade).
`Popup::on_dismiss` fires after the popup's own teardown for the same
reason. One knowable consequence: bookkeeping uses the state as the
widget left it — a callback that mutates the widget's state (a
submit-and-clear composer) sees that mutation rendered by the NEXT
event, not retroactively applied to the one that fired it.
The same law covers REENTRANCY, not just disposal: a callback may
open a modal, write the widget's own controlled signal, or flush
effects synchronously — no widget holds a borrow across a user
callback (the invariant is documented on `widgets::SharedCallback`
and pinned by reentrancy tests on List and Select).
One deliberate refinement for the paste INTERCEPT (`on_paste` below):
an interceptor decides whether widget writes happen at all, so it runs
FIRST — the law's guarantee is preserved from both arms (on `Consume`
no widget write follows the hook; on `Insert` the widget re-checks its
signals' liveness and treats a hook that disposed the scope as
consumed, never a dead-signal panic).
## File attachments — paste intercept, drop classifier, FilePicker
Terminals have no drop protocol: **dropping a file onto every major
terminal PASTES its path**, and the spelling varies per terminal. The
engine owns the three surfaces a file-attaching app needs
(`examples/attachments.rs` is the wired recipe; backlog
first-app/0273):
**1. The paste intercept.** `TextInput::on_paste` and
`TextArea::on_paste` (uniform semantics) run when `UiEvent::Paste`
reaches the focused editor, BEFORE insertion, with the RAW paste text:
```rust,ignore
TextArea::new()
.on_paste(|pasted| match abstracttui::input::paste::classify(pasted) {
Some(paths) => { attach(paths); PasteAction::Consume } // no text lands
None => PasteAction::Insert, // byte-identical to an unhooked editor
})
```
`PasteAction::Insert` = today's behavior exactly (TextInput folds line
breaks to spaces, TextArea normalizes newlines); `Consume` = the
editor inserts NOTHING, fires no `on_change`, touches neither caret
nor history. The hook fires in `masked` fields too — return `Consume`
unconditionally to block pasting into a password field. The enum is
`#[non_exhaustive]` (ADR-0003 §3): foreign `match`es carry a `_` arm.
**2. The drop classifier.** `input::paste::classify(&str) ->
Option<Vec<String>>` — pure string parsing, zero I/O — answers "is
this paste a file drop?" against the researched spellings of the real
terminals (the corpus, with sources, lives in the `input::paste`
module docs):
| terminal | drop spelling |
| --- | --- |
| Terminal.app | backslash-escaped specials, space-joined multi-drop |
| iTerm2 ≥ 3.4 | backslash-escaped (advanced pref: single-quoted) |
| Ghostty | backslash-escaped; GTK multi-drop is NEWLINE-joined |
| WezTerm | `SpacesOnly` default; `Posix`/`Windows*` = double-quoted; `None` = raw |
| kitty | raw path as-is (no escaping, by policy) |
| Windows Terminal | double-quoted when spaces; WSL tabs single-quote |
| GNOME Terminal (VTE) | `file://` URIs converted to single-quoted paths |
| MATE Terminal (bug class) | raw `file://` uri-list reaches the app |
Accepted shapes per token: POSIX absolute, `~/` home-relative
(returned as-is — expansion is YOURS), Windows drive/UNC, `file://`
URLs (percent-decoded, empty/`localhost` host only). **The asymmetry
policy**: a false positive EATS user text, a false negative just
pastes — so every ambiguous case returns `None`: raw unescaped spaces
(`/a/My File.txt` from kitty), unterminated quotes, interior blank
lines, control characters, relative paths, non-`file:` URLs, and
prose ("see /usr/bin for details"). Existence-checking stays app-side
(the engine never touches the filesystem in the input path): fs-check
the returned paths and offer a visible undo before silently attaching.
**3. The picker.** `FilePicker` — breadcrumb header (left-truncated),
live type-to-filter input (the single focus stop), entry rows with
kind glyphs + an optional size column, keyboard nav, opt-in
multi-select, `on_pick(Vec<String>)`:
```rust,ignore
FilePicker::new(StdFileSource::default()) // std::fs, dirs-first,
.start_in("/Users/me/Documents") // hidden files skipped
.multi_select(true) // Space marks, badge counts
.on_pick(|paths| attach(paths)) // may close the modal (law)
.view(cx)
```
Keys: Enter descends a directory or picks a file (marked set when
non-empty, else the current file); Backspace/Left go to the PARENT
when the filter is empty (otherwise they edit the filter); Up/Down/
Page move the selection; **Esc is never consumed** — the host modal
owns dismissal (wire it like every modal: a `shortcut` that closes).
The widget is PURE: entries come from the `FileSource` seam
(`read_dir(path) -> Result<Vec<FileEntry>, String>`), so tests stay
hermetic and archives/remote listings slot in; `StdFileSource` reads
synchronously once per navigation (local fs is fine; a stalling
network mount is the app's risk — the seam is the escape hatch).
Errors render honestly in the list area ("cannot read: …"), and a
parked picker costs zero idle bytes.
## app — the runtime
`App::simple` is the whole happy path: mount a component, enter the
terminal, run until quit. This compiled example is the canonical first app —
Tab focuses, Enter/Space clicks, Ctrl+C quits, all by default:
```rust
use abstracttui::prelude::*;
use abstracttui::widgets::Button;
fn main() -> abstracttui::base::Result<()> {
App::simple(|cx| {
let count = cx.signal(0);
Element::new()
.style(LayoutStyle::column())
.child(dyn_view(LayoutStyle::line(1), move || {
text(format!("count: {}", count.get()))
}))
.child(Button::new("+1").on_click(move || count.update(|c| *c += 1)).view(cx))
.child(text("Tab focuses · Enter clicks · Ctrl+C quits"))
.build()
})
}
```
For more control, `App::new(size)` + `mount` + `run` splits the steps, and
`App::quitter()` hands out a cloneable programmatic-quit handle. Ctrl+C
arrives as an ordinary key (raw mode); the quit-by-default policy is
overridden by any handler that consumes the event.
Around the core loop the module provides:
- **Overlays** — z-ordered layers above the main tree (`LayerHandle`,
`ImageHandle`) for popups, menus, and pixel images.
- **Modal** — a centered, focus-trapped overlay panel: input is fully owned
while open, Tab cycles inside, state created in the modal's scope dies on
close. **Toast** — top-right chips that slide in, park for their duration
at zero frame cost, then slide out and remove their layer.
- **AnchoredPanel / Popup / Tooltip** (`app::anchored`) — the three
routing modes of the anchored-popup substrate, one placement engine
(below-preferred, flip-above, viewport clamp): `AnchoredPanel` is the
PASSIVE layer (never focused — keys stay with the anchor's owner;
`Completion` builds the caret-anchored dropdown on it), `Popup` is the
OWNED modal tree above the whole live stack with `DismissReason`-named
endings (the Select family rides it), and `Tooltip` is the hover-timed
passive label. All three close with their opener's scope (see the
widgets section for the completion and select details).
- **Hooks** — `use_theme(cx)` (the app-level theme signal), `use_viewport(cx)`
(terminal size as a signal), `use_startup_notices(cx)` (labeled startup
degradations as a reactive list), and `use_caps(cx)` — the driver's LIVE
`Capabilities` (env pass at enter, upgraded as active-probe replies fold
in). Read it in a `dyn_view` for capability-honest UI: key hints that say
"Shift+Enter newline" only where the kitty protocol is actually live,
graphics-channel labels that flip when the probe proves a better channel.
Read-only by contract (writing capabilities stays the driver's job);
`current_caps()` is the untracked snapshot for plumbing.
- **KeymapHelp** — a ready-made `?` help modal listing the shortcuts
reachable from the current focus plus every registered global action.
Global actions resolve LAST in the driver's key path: a key that
nothing in the UI consumed — including one a MODAL overlay owned but
did not consume — falls through to the action registry, which is
what lets an action-bound toggle (the shell example's `i` inspector)
close the very modal drawer it opened.
## app::ChoicePrompt — the modal decision gate
Block a flow on a structured question — agent approvals, setup choices,
destructive confirmations with alternatives — and continue in the
callback:
```rust,ignore
ChoicePrompt::new("Overwrite 3 modified files?")
.option_detail("overwrite", "Overwrite them", "the local edits are lost")
.option("keep", "Keep my copies")
.allow_other("Something else…")
.on_resolve(|outcome| match outcome {
ChoiceOutcome::Answered(a) => apply(a), // a.selected: ids, a.other: text
ChoiceOutcome::Cancelled => (), // explicit — never silent
})
.open(cx);
```
The question is plain data (`ChoiceQuestion` + `ChoiceOption { id, label,
detail }` — approval questions arrive from elsewhere; `ChoicePrompt::of`
accepts one). The gate opens a focus-trapped `Modal` over everything and
resolves EXACTLY ONCE through `on_resolve` — Enter-commit, click-commit,
the Confirm/Cancel buttons, Escape, and the returned handle's `cancel()`
all funnel into the same path; the modal is already closed when the
callback runs, so it may dispose anything (including its opener) or open
the next prompt. An outside click is swallowed, never a dismissal: a
decision gate has explicit endings only. The one deliberate exception is
the handle's `retire()`: the HOST closes the gate with NO outcome —
`on_resolve` never fires, and the consumed exactly-once flag guarantees
no later ending (Esc, buttons, `cancel()`) ever will. Retiring says the
host owns the outcome (it is replacing the prompt with another surface,
or resolving the gated question through another lane), so "host retired,
reopen later" stays distinguishable from the user's Esc (`Cancelled` —
"user dismissed, stay away"). Idempotent; a retire after resolution is a
no-op.
Selection follows the engine-wide vocabulary (movement is not
activation): single mode — the highlight IS the candidate (`●`), arrows/
Home/End/wheel move it, `1-9` jump (move only — a deliberate asymmetry),
Enter or a click on the already-selected row commits `{ selected: [id] }`;
multiple mode (`allow_multiple`) — Space or a click toggles `☑`/`☐`
marks, `1-9` jump-toggle (the mark is the selection act), Enter or
Confirm commits the whole set canonicalized to option order (an empty
set is a legal answer — the gate reports, the caller judges).
Per-option SHORTCUT LETTERS (`option_key(id, label, 'a')` /
`ChoiceOption::key`) are the explicit activation vocabulary:
case-sensitive (`a` ≠ `A`), rendered as a dim `(a)` in the row, named
in the hint, commit in single mode and jump-toggle in multiple; a
declared key outranks the digit-jump lane. **The key-spelling
guarantee**: a shifted letter has two wire spellings — the legacy wire
bakes the shift into the char (Shift+A → `Char('A')`) while the kitty
keyboard protocol reports the base key plus the modifier (Shift+A →
`Char('a')` + SHIFT) — and a declared `'A'` fires on BOTH; a declared
`'a'` never fires on Shift+A (case stays meaningful, only the spelling
folds). The same fold covers every chord-match surface (`Element::
shortcut`, `Actions`, `KeyState::pressed_chord`) via
`KeyChord::normalized()` — `plain(Char('A'))` and
`Mods::SHIFT + Char('a')` are one chord, so a single registration
works on every terminal; `KeyEvent::means_char(c)` is the same
predicate for hand-rolled letter matchers. (Shifted non-letter
symbols — `?`, `~` — keep a wire split on kitty terminals: the shifted
symbol is layout-dependent and the engine does not guess.)
`allow_other(label)` appends
an "Other" row; engaging it (highlight in single mode, checked in
multiple) reveals an inline `TextInput` — autofocused, and its own key
handling shields the list (digits and letters type, they never jump or
activate) — whose trimmed text rides `ChoiceAnswer::other`; committing
a hollow Other is refused with a visible note. Esc is LAYERED while the
editor is focused: the first Esc retreats to the list (draft kept), the
second cancels — the hint tells the truth per state.
`dismissable(false)` is the must-choose mode for destructive gates: no
Cancel button, no advertised Esc; Esc REFUSES visibly ("an answer is
required") while `handle.cancel()` keeps the programmatic lever.
`dismiss_label("Defer")` renames the dismiss affordance everywhere it
renders — the button, the hint's Esc segment (`Esc Defer`; the unset
default keeps the built-in "Esc cancels" — the engine never conjugates
a caller label) and the advertised shortcut — for surfaces whose Esc is
not a cancel (the approval consumer's Esc DEFERS: the gated run keeps
waiting). The OUTCOME stays `ChoiceOutcome::Cancelled`; the label names
what the caller's wiring does with it. Irrelevant under
`dismissable(false)`.
`ChoiceOption::danger(true)` / `.danger(id)` tints a destructive
option's glyph+label with the `Error` token (the audited selection pair
still wins while that row is highlighted with the list focused).
`option_with(ChoiceOption)` is the escape hatch for detail+key+danger
combinations. Option `detail` lines render muted under their label;
long lists window around the highlight with an `i/N` position note; the
panel sizes itself from the question and clamps into the viewport. The
a11y tree carries the question (`Heading`), the options
(`MenuItem`+"selected" / `Checkbox`+on/off per mode) and the revealed
editor (`Input`) — the frozen-Role vocabulary, honestly mapped.
**The body slot** (`.body(|mcx| view)` + `.body_rows(n)`, default 8):
a structured region between the prompt heading and the options — the
approval surface's per-call cards, an alternate JSON view behind a
caller-owned signal, a live tier line. The closure runs in the MODAL
scope when the gate mounts (state created there dies on close), so a
scrollable body is `.body(|mcx| Scroll::new(cards).view(mcx))` and a
reactive one is a `dyn_view` reading the caller's signals — it
re-renders live while the gate is up. Contract (v1): the body is a
DISPLAY region — clipped to its solved row budget, panel-width, and
the gate autofocuses the options so every key stays the options'
vocabulary (letters/digits/Space/Enter/Esc; a body `Scroll` never
sees keys unless the user explicitly clicks it, and even then
letters/Enter bubble past it to the gate). The WHEEL scrolls a
`Scroll`-wrapped body while the pointer is over it and moves the
highlight elsewhere. Height honesty: the options are allocated FIRST
(never crushed by a tall body — the 0240 law); the body absorbs what
remains up to `body_rows`, floors at one row under pressure, and
clips instead of painting over the rows below. Width: the panel is
content-derived (options, prompt, hint, buttons) and the body closure
is opaque to that measure, so a body wider than the question would
size the panel declares its need with `body_width(cols)` — a minimum
content width that participates in the same measure (the prompt then
wraps at the widened width; options and hint gain the room), still
clamped into the viewport with the existing margins: on a narrow
terminal the body clips inside its region as before, never the
options. Like `body_rows`, it participates only when a body is set.
The prompt string still wraps/ellipsizes as before — structure
belongs in the body, not in a mile-long prompt. The body adds only
its own honest display entries to the a11y tree; the question/options
contract is untouched.
`ChoiceSequence::new(vec![q1, q2]).on_resolve(..).open(cx)` chains
several questions (each opens as the previous resolves);
`ChoiceSequenceOutcome` is `Completed(answers)` or `Cancelled { index,
answers }`. An empty question list completes synchronously. See
`examples/decide.rs` for all three flavors.
## app::Drawer — edge-anchored overlay panels
A drawer summons a FULL page (a Feed, a form, a reader) from a viewport
edge, over the app, without touching its layout — the entity-app
chat/inspector panel, translated to cells. Install once, then drive it
through the handle or a bound signal:
```rust
use std::time::Duration;
use abstracttui::prelude::*;
fn wire_inspector(cx: Scope, page: impl Fn(Scope) -> View + 'static) -> DrawerHandle {
let inspector = Drawer::new(DrawerEdge::Right)
.size(DrawerSize::Percent(0.4)) // or Cells(n); cross axis fills
.title("Inspector") // themed header + esc hint + ✕
.motion(Duration::from_millis(160)) // Duration::ZERO = instant mode
// (ZERO is also the deterministic-test mode: in a wall-time-less
// headless harness a timed slide never advances, so the panel
// renders nothing until real frames elapse — console-tui field note)
.on_close(|why| { /* DrawerCloseReason::{Api, Escape, ..} */ })
.install(cx, move |mount| page(mount));
inspector.toggle(); // open / close / is_open too
inspector
}
```
Focus modes: `DrawerFocus::Modal` (default) is a focus-trapped tree —
all input routes to the panel, Esc closes, a press outside closes when
`close_on_outside(true)` (default), and a `scrim(true)` (default) veils
the page with the theme's `overlay` token. The titled header's ✕ is a
MOUSE-ONLY affordance (deliberately not focusable — chrome must never
steal a modal's initial focus from the content it frames, so
`focus_init` lands on the page and a hosted `PageHost`'s chords answer
from frame one); Esc is the keyboard close. Closing releases the
keyboard the INSTANT it begins: keys pressed during the closing slide
route to the app (the departing panel is display-only — Esc-then-
shortcut works at any typing speed), and a reopen that reverses the
flight re-arms the trap and re-establishes initial focus.
`DrawerFocus::Passive` is
glanceable: keys stay with the main surface until the user clicks into
the panel (the focused-overlay key rule); no scrim ever — dimming
content that stays interactive would lie. The default diverges from the
web `AfDrawer` (non-modal) deliberately: in a keyboard-first terminal
an unfocused panel cannot even scroll.
Lifecycle honesty: a CLOSED drawer removes its layers and disposes its
mount scope — `build` runs per open, and state that must survive close
lives OUTSIDE the builder (the Tabs rule: create signals in the
installing scope, capture them in `build`). A hidden-but-mounted tree
would accumulate undrained damage and spin the frame loop; removal is
the zero-idle-lawful shape. The slide bills exactly its band
(`Layer::set_origin` damages old ∪ new bounds) and the flight requests
frames only while easing — settled, parked or closed drawers cost zero
bytes (wave-pinned).
Stacking laws: drawers occupy fixed per-edge z slots in a band below
`MODAL_Z` (Left < Right < Top < Bottom at corners), so a `Modal` opened
from a drawer layers above it, owned popups (`top_z() + 1`) layer above
everything live, and toasts stay on top. ONE drawer per edge: opening
on an occupied edge finishes the incumbent instantly with
`DrawerCloseReason::Replaced`. A terminal resize RE-CLAMPS (geometry
re-solves, surfaces resize, an in-flight slide continues toward the
fresh resting place) — unlike `Popup`, which dismisses, a drawer's
anchor is the edge itself and never goes stale. `bind(Signal<bool>)` is
the controlled mode: external writes open/close, handle verbs write
back — one truth. (Naming note: `bind` is the one departure from the
state-name binding convention in the widgets intro — its state word
would be "open", which reads like a verb; renaming would be breaking
and is not planned.) See `examples/shell.rs` (the 'i'/'g' drawers) and
`examples/drawers.rs`.
## app::ThemeSwitcher — the theme menu button
One cell of chrome that gives any app runtime theming — mount it in a
header, tab bar or footer row:
```rust,ignore
use abstracttui::prelude::*;
// The menu face: ☾/☼ icon button (the glyph shows the CURRENT mode);
// Enter/Space/click opens an anchored popup of every visible theme
// grouped Dark / Light, current theme marked ●, house palettes first.
ThemeSwitcher::new()
.on_change(|t| save_preference(t.id)) // fires when a switch STICKS
.view(cx)
// The one-click face: no popup — each activation flips dark ↔ light
// via app::toggle_mode(), restoring your last theme of the target mode.
ThemeSwitcher::toggle().view(cx)
```
The popup rides the select-family machinery: arrows/Home/End/PageUp/
PageDown move (group headers are skipped), type-ahead jumps by label
prefix and a repeated letter cycles its matches, Enter or a click
commits, Escape restores the pre-open theme, a press outside keeps the
preview. Movement previews LIVE — the `Select::commit_on_move`
semantic — and the menu re-resolves its own tokens per step, so the
list renders in the theme you are previewing. It is an owned anchored
popup: modal above the whole live stack, SCREEN-space anchored (a
switcher inside a `Modal` or `Drawer` opens its menu adjacent to the
button, never displaced), flipping above the anchor when the space
below is short — a footer placement opens upward automatically.
`on_change` fires once per switch that sticks (commit, or an
outside-press that keeps a changed preview; every toggle flip) and
never for preview steps, Escape-restores, or mechanical dismissals
(resize, opener unmount). Live restyling needs no callback — the theme
signal already drives it. Closed, the switcher is zero-idle. A11y: the
trigger is `button "theme"` (toggle face: `"toggle theme mode"`) whose
value is the active theme's label; the popup is a `menu` of
`menuitem` rows.
Mode vocabulary underneath: `ThemeMode`, `theme.mode()`,
`theme::themes_by_mode(mode)`, `app::toggle_mode()` — see
[docs/theming.md](theming.md#theme-modes--the-switcher). Demos:
`examples/themes.rs` (both faces in the browser's toolbar),
`examples/shell.rs` (footer placement).
## app::keys — key press/release state (held keys)
Real-time surfaces (games' move-while-held, voice push-to-talk) need key
STATE over time, not key events. `use_key_state(cx)` arms a driver-fed
service that taps the input stream BEFORE the routing seam drops
releases:
```rust,ignore
use abstracttui::prelude::*; // use_key_state, KeyFidelity
let keys = use_key_state(cx);
// per frame / per tick:
let diagonal = keys.is_down(Key::Up) && keys.is_down(Key::Right);
// per turn edges (sealed by the driver's phase U):
let fired = keys.pressed_chord(KeyChord::plain(Key::Char(' ')));
```
**Fidelity is the contract.** `keys.fidelity()` answers what this
session can honestly report:
- `KeyFidelity::Full` — kitty release events are live (the terminal
speaks the protocol AND the event-type flags are pushed; on
probe-proven terminals this flips on within the first frames when the
driver pushes the flags mid-session). `is_down`/`keys_down`/`released`
carry true key state.
- `KeyFidelity::Degraded` — a legacy wire only ever reports presses.
Press edges (`pressed`, `pressed_chord`) stay honest; the down-set
stays EMPTY and releases never fire. There is deliberately no
repeat-timeout approximation: auto-repeat cadence cannot distinguish
"held" from "tapping fast", and a dropped repeat would fabricate a
release mid-hold. Apps fall back to latch/tap semantics and label the
gesture truthfully — `hold_gesture_label(fidelity, chord)` gives the
wording ("hold Space" vs "press Space to start/stop").
Hygiene: the terminal losing focus clears the down-set and synthesizes
release edges for held keys (`keys.focus_cleared()` tells them apart
from wire releases) — a key released while unfocused never sticks down.
Reads are tracked signals: `dyn_view`s and effects re-run on edges.
Zero cost until the first `use_key_state` call arms the service, and
zero per-turn cost while no keys move.
## app::PushToTalk — the capture gesture
The voice capture contract over the key-state service (one binding,
three decisions owned):
```rust,ignore
let ptt = PushToTalk::bind(cx, KeyChord::plain(Key::Char(' ')))
.on_start(|| recorder.start())
.on_stop(|reason| recorder.stop(reason)); // Released | FocusLost | Cancelled
let state = ptt.state(); // Signal<CaptureState>: Idle | Held | Latched
let hint = ptt.gesture_label(); // truthful per fidelity, updates live
```
On `Full` fidelity the chord is hold-to-talk (press starts, release
stops; a same-turn tap fires start then stop, in order). On `Degraded`
wires the same chord becomes toggle-to-talk (`PttMode::Latch`) — never
a fake hold. The terminal losing focus stops capture in EVERY mode
(`StopReason::FocusLost`), and capture never auto-restarts when focus
returns mid-hold: a fresh press is required. `ptt.cancel()` is the
programmatic stop. Terminals cannot see unfocused keys — there are no
global hotkeys here; audio capture itself is app-side.
## app::selection — screen-text selection and clipboard copy
Terminals in mouse-capture mode route drags to the application, so native
text selection stops working in every mouse-enabled TUI. The engine ships
the whole answer stack (see the
[troubleshooting matrix](troubleshooting.md#i-cant-select-text-with-the-mouse)
for the zero-code terminal bypasses). Three cloneable, thread-local
handles, all in `app::selection` (functions re-exported in the prelude):
```rust
use abstracttui::prelude::*; // selection(), mouse_capture(), copy_to_clipboard()
// Tier 3 — engine drag-select. Opt in once (or bind a key to toggle):
selection().set_enabled(true); // left-drag now paints a selection
selection().is_active(); // a region is visible
selection().clear(); // Esc and click do this too
// Tier 2 — native selection mode: hand the pointer back to the terminal.
mouse_capture().suspend(); // native drag-select works; no mouse events arrive
mouse_capture().resume(); // re-arm the entered mouse mode (e.g. on next key)
// The app-reachable clipboard verb (OSC 52 through presenter custody):
copy_to_clipboard("exact source text");
```
While selection is enabled, the engine claims **left drags only — plain
clicks pass through to the widgets** (click-through, 0285). The click
rules, stated plainly:
- **Left Down with no visible region**: the drag anchor arms silently
and the Down PASSES — the widget under the pointer arms its own
pressed state in parallel, so a Button stays clickable with select
mode on (the layer used to consume every Down/Up, which made every
Button in the app dead by mouse).
- **First Drag that leaves the anchor cell**: the layer CLAIMS the
gesture — dragging paints the theme's `selection_fg`/`selection_bg`
inks over the composed frame (damage-contract honest — only changed
cells repaint), and releasing copies. At the claim, the press the
tree already saw is resolved WITHOUT a click: the pressed widget
receives a release outside every rect (release-inside-decides, so a
Button un-presses without firing) and the pointer capture drops.
Drags that never leave the anchor cell stay potential clicks
(terminal cell quantization is the drag slop — a wiggly click still
clicks).
- **Up with no drag** (a plain click): passes — the widget fires.
- **Left Down while a region is VISIBLE**: the click DISMISSES the
selection — clear + consume, both halves of the click (Esc parity:
the user was clearing a highlight, not aiming at the widget beneath).
**Every copy ends the gesture** (0290): the region clears with the copy,
so the app's next keystrokes — including Enter and `c` — route normally
at once (a retained region used to silently eat them in composer-shaped
apps). The key table while a region is visible (i.e. mid-drag):
| Key | Effect |
|----------------|------------------------------------------|
| Enter | copy the region, then clear (one-shot) |
| `c` / Ctrl+C | copy the region, then clear (one-shot) |
| Esc | cancel — clear without copying |
| anything else | routes to the app normally |
Ctrl+C only quits when no region is visible. Wheel scrolling, hover, and
every other key route normally the whole time. Copies travel as OSC 52
through the presenter's byte custody;
terminals that did not advertise the capability still get the bytes
(harmless) plus a one-time labeled startup notice, and under tmux the
sequence is deliberately not passthrough-wrapped (tmux consumes OSC 52
natively — `set -g set-clipboard on`).
Selection semantics, stated plainly:
- **Screen text, not widget content.** What you copy is what the flattened
frame shows: wide glyphs (CJK, emoji) are never split, blank cells read
as spaces, trailing whitespace trims per row, rows join with `\n`.
Soft-wrapped lines copy as separate rows; scrolled-away content cannot
be selected. The logical text↔cells mapping is future work (backlog
0160), not this feature.
- **Linear row flow, clamped to a pane.** The selection flows like a
terminal's own: anchor to right edge, full middle rows, left edge to
head. Both ends clamp to the pane under the drag *anchor* — the content
box of the nearest clipping or padded ancestor (a `Scroll` viewport, a
bordered `Block`), else the whole tree — so sibling panes and border
glyphs never leak into a copy.
- **Zero idle cost.** With no active selection the render hook is two
empty checks; a parked selection renders no frames until something
changes.
`Terminal::set_mouse_reporting(bool)` is the tier-2 verb underneath
(implemented by both platform backends and `testing::CaptureTerm`;
`Driver::set_mouse_reporting` is the immediate form for embedders). One
platform note: job-control suspend (`Ctrl+Z`) re-enters with the original
options, re-arming reporting — suspend again after resume if you keep it
off.
## app — the full-redraw verb (Ctrl+L class)
The damage contract trusts the terminal to keep every cell the engine
painted. When that breaks EXTERNALLY — Cmd+K in Terminal.app,
`printf '\033c'` from a stray process, an emulator glitch — model-side
repaints cannot heal it: cells whose bytes did not change emit
nothing, so the loss is permanent. Two verbs (first-app/0299, exported
at `app::` and re-exported in the prelude) reach the driver's "screen
is unknown" resync — the same pair resize and suspend-resume run
(previous-frame model poisoned, presenter re-anchored, every layer
damaged, protocol images re-placed):
```rust
use abstracttui::prelude::*;
// The Ctrl+L binding every terminal app owes its users:
Element::new().shortcut(KeyChord::new(Mods::CTRL, Key::Char('l')), |_| {
request_full_redraw() // next frame re-emits EVERY cell + re-places images
});
// Opt-in auto-heal: full redraw whenever the terminal reports
// focus-in (an external clear is nearly always followed by a focus
// round-trip, so the damage fixes itself before anyone looks):
set_redraw_on_focus_gained(true);
```
`request_full_redraw()` is callable from any component handler or
posted job on the app thread; the driver drains it at its next turn
(a call from a key handler is honored within the same turn). Cost is
bounded and honest: one full-frame emission, then idle returns to
zero bytes. The focus-regain opt-in defaults OFF — a full frame per
focus-in is real byte cost under tmux pane-switching cadence, so
existing sessions stay byte-identical unless the app asks
(`app::redraw_on_focus_gained()` reads the policy back). Use these for
terminal-side damage only; for ordinary content changes, signals and
tree damage already repaint exactly what changed.
## theme — design tokens
Widgets consume `TokenId`s resolved against the active theme's `TokenSet`;
they never hold raw colors. Twenty-six built-in themes ship in the registry:
the abstract family (`abstract-dark` — the default — plus light, aurora,
paper, ember, midnight, dawn), `observer-night`, catppuccin (mocha,
macchiato, frappe, latte), rose-pine (plus moon, dawn), `tokyo-night`,
`nord`, `one-dark`/`one-light`, `dracula`, `monokai`, `gruvbox`,
`solarized-dark`/`-light`, and `everforest-dark`/`-light`.
Switching is one signal write: widgets that read the theme signal re-render
fine-grained, and the app damages the whole tree so even static text
repaints in the new palette:
```rust
use abstracttui::prelude::*;
set_theme_by_id("catppuccin-mocha"); // false for unknown ids, nothing changes
```
`theme::list()` enumerates `(id, label, dark)` for a picker. Applications
can add their own themes at runtime with `theme::register(candidate, mode)`:
every registration runs the full contrast audit, and the mode decides
whether violations refuse the theme or register it with labeled findings.
Polarity is first-class: `ThemeMode::{Dark, Light}` (closed — the
decisive-ground invariant admits no third value), `theme.mode()` derived
from the audited flag, and `theme::themes_by_mode(mode)` listing one
mode's themes in the curated order (house palette first, registrations
trailing). `app::toggle_mode()` flips dark ↔ light restoring the
last-used theme of the target mode (house palette on a cold start) —
`set_theme` records every switch, so the round trip keeps your choices.
The drop-in chrome control over all of this is
[`app::ThemeSwitcher`](#appthemeswitcher--the-theme-menu-button).
## render — surfaces and paint (advanced)
Most applications never touch `render` directly — widgets and draw closures
do. The two concepts worth knowing:
**`Surface`** is the cell buffer draw closures write into. Damage is
recorded automatically by every write; the diff re-checks equality, so
over-approximate damage costs microseconds, never wrong pixels.
**`render::Style` is a patch, not an appearance.** `fg`/`bg` at `None` keep
what the target cell already has — text drawn over a filled panel keeps the
panel's background. Attributes are add/remove sets, so bold layers onto
existing content. `Style::absolute()` opts out (remove everything first),
and `merge` is sequential application — the later opinion wins:
```rust
use abstracttui::base::Rgba;
use abstracttui::render::{Attrs, Style};
// The common one-liner: ink + emphasis.
let err = Style::new().fg(Rgba::rgb(255, 80, 80)).bold();
assert_eq!(err.add, Attrs::BOLD);
assert_eq!(err.bg, None); // bg unset: keeps the panel underneath
// Patches compose; the later opinion wins where both have one.
let quoted = err.merge(Style::new().dim().fg(Rgba::rgb(150, 150, 150)));
assert_eq!(quoted.fg, Some(Rgba::rgb(150, 150, 150)));
assert_eq!(quoted.add, Attrs::BOLD | Attrs::DIM);
```
The one non-patch field is the hyperlink id: it always overwrites, because
inheriting a stale link under a fresh label would be a correctness hazard.
For effects, layers accept per-cell shaders (`CellShader`; built-ins in
`anim::shaders`). Shaders are billed by damage: static shaders cost nothing
after installation; animated shaders damage only what their `changed_region`
hint declares. For debugging: `render::snapshot(&surface)` prints a bordered
character grid, `snapshot_styles` adds per-row style annotations, and
`Compositor::set_debug_damage(true)` outlines every repaint region live.
**`md::StreamSession`** is the incremental entry into the markdown
pipeline (text arriving over time: model output, a growing log). Closed
blocks freeze — parsed once, never revisited — and only the open tail
re-parses per append, with any chunking of the same bytes yielding
blocks identical to `md::parse` of the whole source. An unclosed fence
reports as code from the moment its opening line arrives. It is
widget-agnostic; `Feed`'s streaming items ride its doc-vocabulary twin,
`md::DocStreamSession` (next section):
```rust
use abstracttui::render::md::{self, MdStyles, StreamSession};
let styles = MdStyles::default();
let mut s = StreamSession::new(styles.clone());
s.append("# Title\n\nStreaming **bo");
s.append("ld** text.");
assert_eq!(s.closed_blocks().len(), 1); // the heading sealed and froze
assert_eq!(
s.finish(),
md::parse("# Title\n\nStreaming **bold** text.", &styles)
);
```
## render::md — the doc vocabulary and the markdown reader surface
The core `md::Block` enum shipped exhaustive, so the extended block
kinds live in `md::DocBlock` (`#[non_exhaustive]`, wrapping the core
set verbatim in `DocBlock::Core`): `Table(TableBlock)` — GFM header +
alignment delimiter + body rows, inline styles inside cells, `\|`
escapes; `Image(ImageBlock)` — a whole-line ``; and
`Task(TaskBlock)` — `- [ ]` / `- [x]` items. `md::parse_doc` is the
entry; for sources containing none of the extended constructs it is
exactly `md::parse` wrapped in `Core` (test-pinned). Inline
`~~strikethrough~~` joined the core span vocabulary (attribute-only:
`Attrs::STRIKE`). `md::DocStreamSession` is the streaming twin of
`StreamSession` for the doc vocabulary — same freeze/equivalence
contract; a table OPENS once its header + delimiter lines are complete,
grows a row per pipe line, and CLOSES (seals) at the first non-pipe
line.
`md::outline(source)` extracts headings as `Heading { level, text,
anchor_id }` with GitHub-compatible, deduplicated slugs
(`md::slugify`). Width-resolved positions live on the widget:
`MarkdownView::outline_rows(source, &tokens, width)` pairs each heading
with the typeset ROW its text starts at (the TOC jump target), and
`MarkdownView::resolve_anchor(...)` answers `[text](#anchor)` links.
`MarkdownView` AND `Feed` markdown items render the full doc
vocabulary (one shared typeset recipe — a feed item and a reader pane
can never typeset the same source differently): tables typeset
through the Table widget's own column solver (one width policy —
natural widths when they fit, proportional flex + per-cell ellipsis
when they don't); images render as MOSAIC rows in the flow — sized from
a header-only probe (`gfx::probe_dimensions`) at typeset, DECODED
LAZILY on first draw and cached by (path, size), with alt-text captions
and labeled decode-failure states (pixel-protocol images in scrollable
flow are deliberately out of scope; mosaic cells are cell-safe in any
scroll context). Streaming feed items ride `md::DocStreamSession`
(see "Feed — streaming transcripts" above).
Find-in-document: `MarkdownView::find(source, &tokens, width, query,
case_insensitive)` returns `MdSearchMatch { row, bytes, cells }` over
the TYPESET text (matches live in what the eye sees; offsets snap to
grapheme clusters), and `.highlights(matches, current)` paints them
non-destructively at draw in selection tones, the current match
distinguished with BOLD+UNDERLINE. An empty query costs nothing. The
underlying text↔cells mapping (byte offset ↔ column, both directions)
is the shared substrate content selection (backlog 0160) will consume.
`examples/reader.rs` composes all of it into an mdpad-class reader.
## canvas — Canvas & vector strokes
The sub-cell vector layer (extensions 0420): the dot-grid math the
charts always used privately, promoted to public API so diagram
extensions (`abstracttui-graph`, mermaid) and app draw closures stop
re-deriving it. `Sparkline`/`LineChart` lines, `BarChart` bars and
`Progress` fills all draw through this layer today — the promotion
kept their rendered cells byte-identical (test-pinned).
```rust
use abstracttui::base::Point;
use abstracttui::canvas::DotCanvas;
use abstracttui::prelude::*;
fn trace(cx: Scope, samples: Signal<Vec<(f32, f32)>>) -> View {
let t = use_theme(cx).get().tokens;
let ink = t.chart(0); // resolve tokens at build time, as always
dyn_view(LayoutStyle::default().grow(1.0), move || {
let pts = samples.get();
Element::new()
.style(LayoutStyle::fill())
.draw(move |canvas, rect| {
let mut dots = DotCanvas::braille(rect.w, rect.h);
for w in pts.windows(2) {
let c = (0.5 * (w[0].0 + w[1].0), 0.5 * (w[0].1 + w[1].1));
dots.bezier_quad(w[0], c, w[1], 0.25);
}
dots.blit(canvas, Point::new(rect.x, rect.y), ink);
})
.build()
})
}
```
- **The dot-space model**: a `DotCanvas` covers a cell rect with a
finer grid — `DotMode::Braille` is 2x4 dots per cell (a WxH panel =
a 2Wx4H dot canvas), `DotMode::Quadrant` 2x2 (universal glyph
coverage where braille fonts are unreliable — the same degradation
rationale as the image mosaic; the mode enum is `#[non_exhaustive]`,
sextant is a known candidate). Dot (0,0) is top-left; strokes clip
at the grid edge, never panic.
- **Primitives**: `set`/`clear`/`get`, `line` (Bresenham — far
off-grid endpoints are pre-clipped so a panned diagram edge costs
O(grid), never O(length)), `polyline`, `bezier_quad`/`bezier_cubic`
(adaptive flattening to a flatness tolerance in dot units, depth-
bounded at 4096 segments per curve), `ellipse_arc`
(parameter-stepped, ≤ 2048 segments). All deterministic — same
inputs, same dots, on every platform (arcs use an in-crate
polynomial sin/cos instead of the platform libm) — and non-finite
inputs draw nothing, the chart sample-skip contract.
- **The cell-color rule (documented z-order)**: a terminal cell
carries ONE fg and ONE glyph, so `blit(canvas, origin, color)`
paints every non-empty cell in one stroke color and SKIPS empty
cells. Overlapping grids therefore compose at cell granularity:
later blits win overlapping cells — glyph and color both, dots
never merge across grids. Multi-color pictures = one grid per
color, blitted back-to-front (exactly how `LineChart` layers its
series). `blit_styled` takes a full `render::Style` patch instead
of a bare color, so a stroke can carry attributes and a link id.
- **Composition is free**: blits go through `ui::Canvas`/
`ui::StyledCanvas`, so `ClippedCanvas` clipping and damage tracking
apply — a blit into a damaged region repaints only that region.
`clear_all()` keeps the allocation; the whole stroke + blit steady
state allocates nothing (pinned in `tests/alloc_budget.rs`).
- **Eighth-block fills**: `fill_v`/`fill_h` draw partial gauge/bar
fills at 8 steps per cell (the `BarChart`/`Progress` vocabulary);
the glyph ramps `V_EIGHTHS`/`H_EIGHTHS`, the quadrant table and
`braille_bit` are exported for callers building their own cell
vocabularies.
- **Colors are caller-resolved** `Rgba` (the widget token rule):
resolve theme tokens — `t.chart(i)`, `t.accent` — at view-build
time and pass the values; the canvas layer invents no colors.
This layer is what the extension family draws its diagram edges with —
for node-and-edge graphs and mermaid sources, use the sibling crates
instead of hand-stroking (see
[the extensions section](#extensions-family--sibling-crates-on-this-api)
and [graphs-and-diagrams.md](graphs-and-diagrams.md)).
## gfx — images
`gfx::decode_image(bytes)` sniffs the magic bytes (containers lie, bytes do
not) and decodes PNG or baseline JPEG into a `Bitmap` — owned RGBA8 with
get/set, nearest and bilinear resize, cropping, and a box-filter mip chain.
Unknown formats are rejected by name, telling the caller what does decode;
truncated or hostile bytes are named errors, never panics.
Three presentation entry points, smallest first:
```rust
use abstracttui::base::{Rect, Rgba};
use abstracttui::gfx::{render_to_cells, Bitmap};
use abstracttui::term::Capabilities;
let img = Bitmap::new(16, 8, Rgba::rgb(180, 90, 30));
let cells = render_to_cells(&img, Rect::new(2, 1, 8, 4), &Capabilities::default());
assert_eq!(cells.len(), 8 * 4);
```
- `render_to_cells` picks the best mosaic mode for the probed terminal and
returns ready-to-blit cell patches; `MosaicMode::auto(&caps)` returns both
the mode and the reason it was chosen (half-block, quadrant, sextant, or
braille; optional Floyd–Steinberg dithering).
- `widgets::Image` is the widget form — always mosaic, because a draw
closure owns cells, not escape bytes.
- `gfx::ImageSession` manages the pixel protocols (kitty, iTerm2, sixel):
slots keyed by the caller, content versions, minimal traffic per channel —
kitty transmits once and re-places on move; iTerm2 and sixel honestly
re-emit. Bytes reach the terminal through the presenter, and tmux
passthrough wrapping applies automatically when capabilities prove it.
## three — 3D models
`three::quick_view(path)` is the five-line hello: load a GLB, get a camera
framed on the model's bounds and a default light, render:
```rust
use abstracttui::three::{self, Framebuffer, SceneRenderer};
let view = three::quick_view("model.glb")?;
let mut fb = Framebuffer::new(160, 96);
SceneRenderer::new().render(&view.scene(), &mut fb);
// fb -> mosaic cells via gfx, or hand the model to widgets::Viewport3D.
```
Underneath: `Model::load(bytes)` / `load_glb(path)` parse and validate the
GLB (unsupported features reject by name; recoverable gaps degrade with
labels into `model.warnings`), `Scene`/`Camera`/`Light` describe the view,
and `SceneRenderer` rasterizes with z-buffer, texturing, and mips.
`model.animations()` lists clips; `sample_pose_full(clip, t, &mut pose)`
produces node worlds and skin joint matrices, pure in `t` and allocation-free
at steady state — loop with `t % clip.duration()`. One culling note: bare
`Scene::new` culls back faces (procedural meshes are consistently wound);
`QuickView::scene()` and `Viewport3D` render double-sided, because
real-world exports are not.
## term and input — the terminal, when you need it
Applications under `App` rarely touch these; embedders and diagnostics do.
`Capabilities::detect_env()` is the free, instant, conservative environment
pass; the active probe refines it concurrently at startup. `caps.summary()`
is the multi-line human report (`summary_line()` the one-liner); scripts
should read fields, not parse prose. `EnterOptions` declares the session
posture — the default is the full-screen stance (alternate screen, hidden
cursor, button-drag mouse, bracketed paste, focus events), with kitty
keyboard flags as an explicit opt-in:
```rust
use abstracttui::term::{Capabilities, EnterOptions, TermRead, Terminal, UnixTerminal};
use std::time::{Duration, Instant};
let caps = Capabilities::detect_env(); // free, instant, conservative
let mut term = UnixTerminal::new()?; // real device fd acquisition
term.enter(&EnterOptions::default())?; // raw mode + altscreen + modes
match term.read(Some(Instant::now() + Duration::from_secs(5)))? {
TermRead::Input(bytes) => { /* feed input::Parser */ }
TermRead::Resize(size) => { /* re-layout */ }
TermRead::Wake => { /* another thread wants the loop */ }
TermRead::Idle => { /* deadline expired */ }
}
term.leave()?; // also runs on Drop — the terminal always restores
```
`input::Parser` turns raw bytes into structured events — resumable across
arbitrary chunk splits (mid-UTF-8, mid-escape), never panicking on any
input. `input::EventReader` glues a terminal to the parser and owns the
ESC-disambiguation deadlines.
Kitty keyboard flags follow the PROBE, not just the environment: the env
pass claims the protocol only for terminals that speak it out of the box
(kitty, ghostty, foot — WezTerm ships it config-off, so its claim waits
for probe evidence), and when the active probe proves the protocol on a
terminal env could not claim (iTerm2 ≥ 3.5, VS Code/Cursor, Warp), the
driver pushes the standard flags mid-session via
`Terminal::set_kitty_keyboard` — Shift+Enter-class chords start working
without a restart. The verb updates the terminal's session accounting,
so `leave` pops exactly what was pushed and job-control suspend/resume
stays symmetric (pop on suspend, re-push on resume). Embedders that
enter with explicit `RunConfig::enter` options own their posture: the
driver never upgrades it.
## testing — the headless harness
The `testing` module ships in the library so applications can test against
the same machinery the engine tests itself with: `CaptureTerm` is an
in-memory terminal that records emitted bytes and models the screen,
`VtScreen` is the VT100/xterm interpreter that serves as ground truth
("the bytes we emitted produce the frame we intended"), and `app::Driver`
pumps real frames — the same pipeline production uses — without a tty:
```rust
use abstracttui::prelude::*;
use abstracttui::app::Driver;
use abstracttui::testing::CaptureTerm;
let size = Size::new(20, 4);
let mut app = App::new(size);
app.mount(|cx| {
let n = cx.signal(0);
Element::new()
.shortcut(KeyChord::plain(Key::Char('+')), move |_| n.update(|v| *v += 1))
.child(dyn_view(LayoutStyle::line(1), move || text(format!("n = {}", n.get()))))
.build()
}).unwrap();
let mut term = CaptureTerm::new(size);
let cfg = RunConfig { probe: false, ..RunConfig::default() };
let mut driver = Driver::new(&mut app, &mut term, cfg).unwrap();
driver.turn(&mut app, &mut term).unwrap(); // first frame
assert!(term.screen().to_text().contains("n = 0"));
term.push_input(b"+"); // a keypress
driver.turn(&mut app, &mut term).unwrap(); // dispatch + repaint
assert!(term.screen().to_text().contains("n = 1"));
```
Input is fed as the terminal would send it, so every dispatch, focus, and
damage path is the real one. For pure component tests, skip the driver: mount
into a `ui::UiTree`, dispatch events, draw into a `ui::BufferCanvas`.
Golden-snapshot assertions and deterministic fuzz helpers round out the
module. When a test needs to EXPORT what the screen looked like — as
evidence in a failure report or a docs artifact — capture it as a value
and write text/ANSI/SVG: that is the
[Screenshots & captures](#screenshots--captures) section, and both of
its capture surfaces work headlessly.
## Screenshots & captures
`render::Screenshot` is a captured screen as a plain value — a grid of
`{glyph, fg, bg, underline color, attrs}` cells (`ShotCell`) — with three
deterministic exporters. It answers "what does the app actually show?"
for debugging, documentation, and test evidence.
**Two capture surfaces, one truth.** In a running app, capture the frame
as **last presented** (a pure read of the composed frame — no re-render,
no damage side effects):
```rust,ignore
// Embedders/tests driving their own turns:
let shot = driver.screenshot();
// Component code (App::run consumed the App): the request verb — the
// same thread-local drain shape as `request_full_redraw`. The callback
// runs on the app thread with the screen as the user saw it when the
// request landed. No default hotkey exists; this binding IS the recipe:
Element::new().shortcut(KeyChord::plain(Key::F(12)), |_| {
abstracttui::app::request_screenshot(|shot| {
let _ = shot.write_svg("/tmp/screen.svg");
});
})
```
In headless tests, capture from the byte side — the testing rig's VT
model, i.e. what the emitted bytes actually produced:
```rust
use abstracttui::prelude::*;
use abstracttui::app::Driver;
use abstracttui::testing::CaptureTerm;
let size = Size::new(24, 3);
let mut app = App::new(size);
app.mount(|_cx| Element::new().child(text("proof of pixels")).build()).unwrap();
let mut term = CaptureTerm::new(size);
let cfg = RunConfig { probe: false, ..RunConfig::default() };
let mut driver = Driver::new(&mut app, &mut term, cfg).unwrap();
driver.turn(&mut app, &mut term).unwrap();
let shot = term.screen().screenshot(); // bytes -> VT model -> value
assert!(shot.to_text().contains("proof of pixels"));
let svg = shot.to_svg(); // attach to a test report
assert!(svg.contains("proof of pixels"));
```
Both surfaces produce the same value for the same screen (test-pinned),
and `Screenshot::from_surface(&Surface)` captures any surface directly.
**The exporters** (pure functions, byte-deterministic; `write_text` /
`write_ansi` / `write_svg` are the one-call file forms):
- `to_text()` — plain UTF-8 lines, trailing blanks trimmed. Identical to
`VtScreen::to_text` for the same screen.
- `to_ansi()` — SGR-styled text you can `cat` into any truecolor
terminal. Minimal escapes: one SGR transition per style change (the
presenter's own builders), rows separated by `SGR 0` + CRLF, no
trailing newline. Fidelity is test-pinned by a roundtrip law: replaying
the export through the testing rig's VT interpreter reproduces the
capture exactly, including the cluster-fusion hazards (after
ZWJ/VS16/ambiguous-width clusters and trailing regional indicators the
export re-anchors the column with `CHA` — the presenter's risky-cluster
defense, in the row-relative form that keeps the bytes replayable from
any scrollback position).
- `to_svg()` — the docs/report artifact; GitHub renders it in READMEs.
Backgrounds merge into per-run rects, text runs pin to their columns
with `textLength` (font drift cannot shear the grid; wide glyphs run
alone), decorations draw as explicit rects, exact RGB from the capture.
Cells carrying "terminal default" colors render with a built-in
neutral ink/paper; pass your own via `to_svg_with(fg, bg)`.
A generated sample lives at
[`docs/captures/transcript-stream.svg`](captures/transcript-stream.svg)
(the capture pipeline now emits `.svg` beside every `.txt` still).
**Honesty notes.** Cells under a kitty/iTerm2/sixel image are not the
picture — the terminal shows pixels the cell plane cannot see.
`Driver::screenshot()` stamps those placements from the live session
bookkeeping into `Screenshot::pixel_regions()`; `to_svg` renders them as
labeled placeholder veils, text/ANSI exports stay cell-plane-verbatim.
Unicode-mosaic images ARE cells and capture as themselves. VT-model
captures carry no regions (the rig consumes protocol payloads as
counted, unmodeled frames). Hyperlink targets are not captured (a visual
capture has no click surface — the styled debug dumps show them);
`blink` exports as static; `undercurl` draws as a straight underline in
SVG. Capture is on-demand only: nothing here runs per-frame, and an
idle app still costs zero.
The future control-server "observe" verb (backlog control-plane
0310/0320) is a serialization of this same value — the bus exposes
`Screenshot` exports over the wire; nothing new to invent there.
## Stability and limits
Plain statements of current behavior:
- **JPEG** decoding is baseline sequential only; progressive and arithmetic
variants reject by name. **PNG** supports 8-bit depths without interlacing
(Adam7 rejects by name).
- **Sixel** uses one palette per emission: multiple live sixel images
recolor each other — prefer one per screen. iTerm2 and sixel have no
placement model (moves re-emit the payload); only kitty gets placement
escapes and true deletes.
- **Pixel protocols** are verified byte-for-byte against protocol models,
not live terminals; unicode mosaic is the universal, always-safe path.
- **3D animation** supports LINEAR and STEP interpolation; CUBICSPLINE and
morph weights skip with labels; rotations nlerp (shortest path), not
slerp. Skinning reads `JOINTS_0`/`WEIGHTS_0` (four joints per vertex,
linear blend). Textures: base color only, REPEAT wrap, per-triangle mips.
- **Mosaic** color resolution is two colors per cell (the glyph split
carries the rest); braille conveys structure, not color; sextant glyphs
need a recent font and are an explicit opt-in.
- **Ambiguous-width characters** follow `unicode-width` narrow semantics. A
terminal configured ambiguous-wide breaks cell layout for every terminal
application; the presenter's cursor discipline bounds the drift but
cannot erase it.
- **Capacity ceilings** degrade with labels, never unbounded growth: 4096
distinct long grapheme clusters per surface (then U+FFFD), 65535
hyperlinks per surface (then plain text), with counters exposed.
- **Scroll optimization** requires DECSTBM/SU/SD compliance — present in
every VT100 descendant — and can be forced off via `PresenterOpts`.
- **Windows** compiles clean and its extracted logic is unit-tested on every
host, but it has not yet run on a live Windows machine; treat a first
Windows deployment as a beta event. macOS and Linux are the live-verified
platforms.
## Extensions family — sibling crates on this API
Diagram-class capability ships OUTSIDE the core crate as sibling
crates built on the public API above (ADR-0004: install only when
needed, no cargo features, no private hooks). Each crate carries its
own rustdoc — this guide does not duplicate it; the family guide with
selection advice and worked examples is
[graphs-and-diagrams.md](graphs-and-diagrams.md).
- [`abstracttui-graph`](https://docs.rs/abstracttui-graph) — graph
auto-layout (`GraphDesc -> Layout`: `layered` sugiyama-lite,
`force` bounded seeded placement, `grid` labeled fallback; honesty
markers for broken cycles and degradations) and `GraphView` (cards,
canvas-stroke edges, selection/pan/tooltips, zero idle).
- [`abstracttui-mermaid`](https://docs.rs/abstracttui-mermaid) —
honest-subset mermaid: an exhaustive spelling table (the contract,
shipped verbatim in the crate docs), flowcharts/flat-state compiled
onto `abstracttui-graph`, solverless sequence diagrams, atomic
fallback to the verbatim code fence with a named reason and a
mermaid.live escape link.
===== FILE: docs/theming.md =====
# Theming
AbstractTUI widgets never name colors — they name **roles**. Every drawable
surface resolves a semantic token against the active theme, so an entire
application restyles from a single switch, and every built-in palette is
held to measured, test-enforced contrast floors.
This page covers the token model, the 26 built-in themes, runtime
switching, the contrast guarantees, registering your own themes, and the
styling conventions widget authors should follow. The complete hex value
of every token in every theme lives in the generated reference:
[`captures/themes-table.md`](captures/themes-table.md).
## The 36-token semantic model
A theme's palette is a `TokenSet`: 36 resolved `Rgba` values, one per
`TokenId`. The tokens are grouped by the job they do, not by hue:
**Grounds** — the layered backgrounds an app is built on.
- `bg` — the application field; the deepest layer, fills the terminal.
- `surface` — panel and card ground.
- `surface_raised` — raised chrome: popovers, menus, active tabs, chips,
and the declared ground for code blocks.
- `overlay` — the modal scrim; deliberately carries alpha for the
compositor to blend over whatever it covers.
**Text tiers** — three levels of copy, each with its own contrast floor.
- `text` — body copy.
- `text_muted` — secondary copy: labels, descriptions, timestamps.
- `text_faint` — the decoration tier: placeholders, disabled glyphs,
watermark art. Deliberately below the accessible-text grade; never used
for information-carrying text.
**Strokes**
- `border` — hairline strokes: pane separators, boxes, rules.
- `border_focus` — the focus-ring ink; must read stronger than `border`.
**Voice** — where the theme's personality lives.
- `accent` — the theme's identity color: primary actions, active states,
brand marks. One accent per screen region works best.
- `accent_alt` — a curated companion accent (gradients, secondary
emphasis).
- `link` — hyperlink ink (the underline comes from the style attribute,
not the color).
**Semantic states**
- `ok`, `warn`, `error`, `info` — success, caution, failure, and
informational marks.
**Selection pair**
- `selection_bg` / `selection_fg` — always used together, never mixed with
other grounds. The pair means "this is the thing keys act on".
**Cursor and shadow**
- `cursor` — the caret/block-cursor ink when the engine draws its own.
- `shadow` — a dim multiplier for cell-space drop shadows (carries alpha).
- `shadow_ground` — `shadow` pre-composited over `bg` at theme build, so
it is opaque. This is what `Block::shadow` paints: widgets never do
color math themselves.
**Chart ramp**
- `chart[0..8]` — eight hue-separated series colors, all legible on `bg`.
Chart series pick a **slot**, never a color: slots 0–4 follow the
accent/info/ok/warn/error family and slots 5–7 are curated companions,
with a separation pass that keeps every series tellable-apart even in
palettes where two source colors coincide. `TokenSet::chart(i)` clamps
out-of-range indexes to the last slot, so indexing from arbitrary data
can never panic.
**Syntax family**
- `syntax_keyword`, `syntax_string`, `syntax_number`, `syntax_type`,
`syntax_func`, `syntax_punct`, `syntax_comment` — code inks derived per
theme from the audited accent/semantic family and contrast-guarded
against `surface_raised` (the code ground). Comments deliberately recede
at the 3:1 class; the other inks target 4.5:1.
By-id access exists for tooling (theme editors, debug overlays, config
files): `TokenId::ALL` (all 36, stable order), `tokens.get(id)`,
`tokens.set(id, rgba)`, `TokenId::from_name("accent")`, and
`tokens.iter()` for `(id, color)` pairs.
## The 26 built-in themes
`theme::themes()` returns the built-in registry; `theme::get(id)` looks a
theme up by id (also honoring the `"dark"`/`"light"` aliases for the house
pair); `theme::resolve(id)` falls back to the default for unknown ids and
returns a labeled warning string alongside; `theme::default_theme()` is
`abstract-dark`. `theme::list()` yields `(id, label, dark)` for every
visible theme, built-ins first, then runtime registrations — the picker
surface.
The family:
| family | themes |
| --- | --- |
| Abstract originals | `abstract-dark`, `abstract-light`, `abstract-aurora`, `abstract-paper`, `abstract-ember`, `abstract-midnight`, `abstract-dawn` |
| Observer | `observer-night` |
| Catppuccin | `catppuccin-mocha`, `catppuccin-macchiato`, `catppuccin-frappe`, `catppuccin-latte` |
| Rosé Pine | `rose-pine`, `rose-pine-moon`, `rose-pine-dawn` |
| Tokyo Night | `tokyo-night` |
| Nord | `nord` |
| One | `one-dark`, `one-light` |
| Dracula | `dracula` |
| Monokai | `monokai` |
| Gruvbox | `gruvbox` |
| Solarized | `solarized-dark`, `solarized-light` |
| Everforest | `everforest-dark`, `everforest-light` |
The ported families keep every hex value their upstream palette defines,
verbatim. Tokens the upstream source does not define (borders, selection
tints, focus rings, the chart ramp, the syntax family) are derived by
documented, contrast-guarded rules — for example, borders composite the
theme's own text ink over the ground so gruvbox gets warm cream strokes
rather than clinical gray.
Every token value of every theme, generated straight from the registry:
[`captures/themes-table.md`](captures/themes-table.md).
## Switching themes at runtime
There is exactly one app-level theme signal. Reads are reactive, writes
restyle the whole application:
```rust
use abstracttui::prelude::*;
// Inside a component: read reactively. Any dyn_view that reads the
// signal rebuilds with fresh tokens when the theme changes.
fn header(cx: Scope) -> View {
let theme = use_theme(cx);
dyn_view(LayoutStyle::line(1), move || {
let t = theme.get(); // &'static Theme: t.tokens, t.is_dark()
text(format!("{} ({})", t.label, if t.is_dark() { "dark" } else { "light" }))
})
}
// Anywhere: switch. Returns false (and changes nothing) for unknown ids.
set_theme_by_id("nord");
// Or with a handle from the registry / a runtime registration:
set_theme(abstracttui::theme::get("catppuccin-mocha").unwrap());
```
Mounting an app installs a watcher on the signal that damages the whole
tree on switch, so even static text repaints, while regions that read the
signal inside `dyn_view` re-render fine-grained. `Theme::is_dark()` is the
supported way to make polarity-conditional choices (shadow strength, image
dithering, artwork variants).
The shipped examples honor `ABSTRACTTUI_THEME=<id>` as a startup
convention — `set_theme_by_id` at boot is all it takes to adopt the same
convention in your app.
## Theme modes & the switcher
Polarity is a first-class vocabulary: `ThemeMode::{Dark, Light}` is a
closed enum (the decisive-ground invariant leaves no room for a third
value), `theme.mode()` derives it from the audited `dark` flag — one
source, never a second luminance threshold — and
`theme::themes_by_mode(mode)` lists every visible theme of one mode in
the same curated order `list()` presents: built-ins in registry order
(the house palette of each mode first), runtime registrations trailing.
That "first of mode is the house theme" fact is documented and pinned;
pickers and the toggle default rely on it.
`app::toggle_mode()` flips dark ↔ light while keeping the user's theme
*choice* per mode: `set_theme` (the one signal-write choke point)
records every switch as its mode's last-used theme, so
`nord → toggle → abstract-light → toggle → nord` round-trips. A mode
never visited on this thread falls back to its house palette.
`ThemeSwitcher` is the drop-in control — one line in any app's chrome:
```rust
use abstracttui::prelude::*;
// In your header / tab bar / footer row:
let menu = ThemeSwitcher::new().view(cx); // ☾/☼ button; opens the grouped menu
let flip = ThemeSwitcher::toggle().view(cx); // same cell; one click flips the mode
```
The menu face opens an owned anchored popup (modal, above the whole
live stack — it layers and anchors correctly inside a `Modal` or
`Drawer`) listing every visible theme grouped **Dark** then **Light**,
group headers as skipped rows, the active theme marked `●`. It rides
the select-family machinery: Up/Down/Home/End/PageUp/PageDown move,
type-ahead jumps by label prefix (a repeated letter cycles its
matches), Enter or a click commits, Escape restores the pre-open theme,
and a press outside keeps what you previewed. Movement previews the
theme **live** — the `Select::commit_on_move` semantic, which exists
for exactly this control — and the menu re-resolves its own tokens per
step, so the list you are browsing is rendered in the theme it names.
`on_change(|theme| ...)` fires once per switch that *sticks* (commit or
outside-press with a changed theme; never on preview steps, never on
Escape) — the hook for persisting a theme preference.
The glyph: the button shows the **current** mode — `☾` on dark themes,
`☼` on light ones. A static `◐` would spend the cell on decoration; a
mode-reflecting glyph makes the one cell double as the app's polarity
indicator, while hover/focus affordances and the a11y label ("theme",
value = the active theme's label) carry the button-ness and the action.
`☾` U+263E and `☼` U+263C are East-Asian-neutral (single-width in every
convention) and absent from Unicode emoji-data — unlike `☀` U+2600,
which some terminal stacks promote to a double-width emoji glyph.
Closed, the switcher is zero-idle: no layers, no timers — it re-renders
only when the theme signal or its own hover/focus state is written. The
popup's subscriptions live on a per-open scope and die at dismissal.
## Contrast guarantees
Every registered theme must pass `theme::audit(id, &tokens)` — a WCAG
contrast audit that measures each documented pair with
`theme::contrast_ratio(a, b)` and returns structured `Violation`s (theme,
rule, token, measured value, required floor). The built-in family passes
with zero violations as a test invariant; the floors are public in
`theme::contrast::floors` so your tooling audits against the same numbers:
| pair | floor |
| --- | --- |
| `text` / grounds | 4.5:1 (7:1 is the target, reported not enforced) |
| `text_muted` / `bg` | 3.0:1 |
| `text_faint` / `bg` | 2.5:1 (the deliberate decoration tier) |
| `accent`, `accent_alt`, semantics, `link` / `bg` | 3.0:1 |
| `selection_fg` / `selection_bg` | 4.5:1 |
| `border` / `bg` | 1.5:1 |
| `border_focus` / `bg` | 2.0:1 |
| `cursor` / `bg` | 3.0:1 |
| syntax inks / `surface_raised` | 4.5:1 (comments 3.0:1) |
Syntax floors are additionally capped at what the theme's own body text
achieves on the code ground — code can never be more readable than text,
which matters for deliberately soft palettes.
Beyond the pairs, grounds must be **decisive**: a theme's measured ground
luminance must agree with its declared `dark` flag by a margin
(`|L(bg) − 0.5| ≥ 0.15`). A mid-gray ground makes both text polarities
marginal and breaks everything downstream that groups by polarity.
Audit exceptions are named per `(theme, rule)` pair, never blanket, and a
stale exception fails the test suite. Exactly one exists:
`everforest-light`'s text on raised chrome measures ~4.25:1 — both values
are verbatim upstream colors, the rule is stricter than the mandated
text/ground floor, and 4.25:1 still clears WCAG AA-large.
## Registering a custom theme
`theme::register(candidate, mode)` is the runtime door:
```rust
use abstracttui::theme::{register, RegisterMode, ThemeCandidate, TokenSet};
let candidate = ThemeCandidate {
id: "my-theme".into(), // kebab-case: [a-z0-9-_], non-empty
label: "My Theme".into(),
dark: true, // audited against measured luminance
tokens: my_tokens, // a full TokenSet
};
match register(candidate, RegisterMode::Strict) {
Ok(reg) => set_theme(reg.theme),
Err(e) => eprintln!("{e}"), // structured violations, not a boolean
}
```
The audit always runs; the mode declares what happens to findings:
- **`RegisterMode::Strict`** — findings refuse the registration. The
error carries the structured violation list plus role-hygiene findings
(`RegisterError::Rejected { violations, hygiene }`), so a theme file can
be treated as code: fix what the audit names.
- **`RegisterMode::Labeled`** — the theme registers anyway, and every
finding comes back on `Registration::warnings` as a `#FALLBACK:`-prefixed
line. Use this for user-supplied themes where refusing would strand the
user — and surface the warnings, never swallow them.
Identity problems refuse in **both** modes: an empty or malformed id is
`RegisterError::InvalidId`, and shadowing a built-in id or one of its
aliases is `RegisterError::ReservedId` — a user theme silently replacing
`nord` would be spoofing, not customization.
Accepted registrations are `&'static` (leaked once, stable for the app's
life, ~300 bytes each), visible to `theme::get`, `theme::list`, and theme
cycling. Re-registering an id replaces it for future lookups while old
handles stay valid; re-registering a byte-identical candidate returns the
existing handle without allocating.
### Deriving tokens
You rarely design 36 colors by hand. `theme::derive` provides the same
helpers the built-in registry uses:
- `mix(a, b, t)`, `lighten(c, t)`, `darken(c, t)` — sRGB-space mixes
(the perceptual limits are documented at the definitions; these are for
small nudges within one theme, not long decorative gradients).
- `mix_until_contrast(base, ink, anchor, t0, step, floor)` — walk a mix
upward until it clears a contrast floor against its ground (how borders
are derived).
- `tint_until_readable(base, tint, fg, t0, step, t_min, floor)` — walk a
tint downward until the foreground stays readable on it (how selection
backgrounds are derived).
The intended recipe: start from your four anchor colors (ground, text,
accent, one semantic), derive surfaces with `lighten`/`darken` steps, fill
the rest with the walks, then run `theme::audit` and fix what it names.
## Design guidance for widget authors
Widgets built on AbstractTUI should speak tokens and nothing else — the
engine's own widget sources are lint-checked for raw hex. The conventions
that keep a screen coherent:
**Three focus/selection mechanisms, in priority order.**
1. The **selection pair** says "this is the thing keys act on"
(list rows, table rows, selected text).
2. A **`border_focus` stroke** says "this pane owns the keyboard"
(bordered widgets and panes).
3. **`accent` ink** is hover garnish.
Never render two selection pairs at different strengths — one pair, one
meaning.
**The state table.**
- *Normal*: content inks on their ground.
- *Hover*: recolors the actionable ink to `accent` — decoration only; a
hover state must never carry information focus does not.
- *Focus*: `border_focus` stroke on bordered widgets; the selection pair
on borderless ones.
- *Disabled*: `text_faint`, and out of the focus order entirely — a
focused-disabled widget cannot exist.
- *Selected*: persists when the pane is unfocused; the owning pane's
stroke says where keys go.
**Hard rules.**
- Tokens only; no color arithmetic in widgets — pre-composited tokens like
`shadow_ground` exist precisely so widgets never blend.
- Placeholders (`text_faint`) disappear on first input.
- Underline-as-affordance is drawn as cells, never as a text attribute
alone, so it survives 16-color terminals.
- Every widget draws inside its rect; long spans clip rather than leak.
For a live rendering of all of this, run the `widgets` and `gallery`
examples (`cargo run --example gallery`), and see
[`../examples/README.md`](../examples/README.md).
===== FILE: docs/graphics-and-3d.md =====
# Graphics and 3D
AbstractTUI renders real pixels in the terminal: PNG/JPEG images through
the best channel the terminal offers, and software-rasterized 3D models
(GLB) with textures, lighting, and animation — all with hand-rolled
decoders and no GPU requirement. Degradation is always labeled, never
silent: when the engine falls back to a lesser channel, the result says so.
## Images end-to-end
### Bytes to picture
`gfx::decode_image(bytes)` sniffs the magic bytes (containers lie, bytes
don't) and decodes **PNG** or **baseline JPEG** into a `gfx::Bitmap` — an
owned RGBA8 image with pixel `get`/`set`, nearest and bilinear resize,
cropping, and a box-filter mip chain. Unknown formats reject by name,
telling the caller what does decode ("PNG and baseline JPEG decode,
GIF/WebP/AVIF/TIFF do not" — a message you can show verbatim). Truncated
or hostile bytes produce named errors, never panics; the decoders are
fuzz-hardened.
### Picture to terminal: the capability ladder
The engine picks the best channel the terminal proves it supports —
`gfx::choose_channel(&caps.graphics())` (the ladder reads the
graphics view of the capability report) — best first:
| channel | how it draws | moves / resizes | removal | requires |
| --- | --- | --- | --- | --- |
| kitty graphics | upload once by id, place by escape | cheap re-place, no retransmit | true delete | kitty graphics protocol |
| iTerm2 | full base64-PNG re-emit at the cursor | full re-emit | cells overdraw | OSC 1337 support |
| sixel | paletted raster at the cursor | full re-emit | cells overdraw | sixel + known cell pixel geometry; one shared palette |
| unicode mosaic | colored glyphs (it *is* cells) | free | free | any terminal |
Capabilities come from detection, not folklore: an instant environment
pass, then an active query probe that can raise *and* lower the answer.
Run any of the `dashboard`, `viewer3d`, or `images` examples with `--caps`
to print the report for your terminal.
### Three entry points, smallest first
- **`gfx::render_to_cells(bitmap, rect, &caps)`** — one call. Picks the
best mosaic mode for the probed terminal and returns ready-to-blit
`CellPatch`es.
- **`widgets::Image`** — the widget: `Image::from_path("logo.png")` or
`Image::from_bitmap(Arc<Bitmap>)` (the `Bitmap` type is re-exported
beside the widget and in the prelude), with `fit`
(`Contain`/`Cover`/`Fill`/`None`), alignment, and a mosaic-mode
override. The widget **always renders mosaic cells**: a widget draw
closure owns cells, not escape bytes, so pixel-protocol placement lives
one level up.
- **`gfx::ImageSession`** — pixel protocols with a lifecycle. Slots are
keyed by the caller (`SlotKey`), content changes are declared by version
bump, and each sync emits the minimum traffic the channel allows: kitty
transmits once, re-places on move, and deletes on drop; iTerm2 and sixel
honestly re-emit their full payload on any change. Bytes flow through an
`ExternalSink` (the presenter adapts), and tmux passthrough wrapping is
applied automatically when capabilities call for it. `SyncOutcome` tells
you whether cells need repainting, bytes were written, or nothing
changed.
`gfx::present_image` / `ImageRenderer` sit under all three: capability
ladder on top, `RenderConfig` for the knobs (kitty wire format, placement
z-index, sixel register budget and dithering).
### Mosaic modes
Mosaic renders pixels as colored glyphs with a two-colors-per-cell best
fit (weighted least squares):
- **HalfBlock** — 1×2 pixels per cell using `▀`. Exact and universal.
- **Quadrant** — 2×2, the 16-glyph quadrant set. Universal glyph coverage.
- **Sextant** — 2×3, the 64-pattern sextant set. Denser, but its U+1FB00
glyphs need a recent font — explicit opt-in, since no font probe exists
and missing glyphs render as tofu.
- **Braille** — 2×4, dots by luminance threshold. Structure rather than
color; the strongest choice on monochrome-class terminals.
`MosaicMode::auto(&caps)` picks for you and returns the reason as a label:
non-UTF-8 locales get HalfBlock (U+2580 survives most legacy codepages),
monochrome terminals get Braille, color terminals get Quadrant.
Optional **Floyd–Steinberg dithering** (serpentine error diffusion) can
pre-quantize the source to a palette before cell fitting — worth it when
the *output* terminal is 256- or 16-color, where straight quantization
would band gradients. Sixel emission has its own configurable dithering.
### Images under tmux
Inside tmux, graphics protocols are off by default because tmux swallows
them unless the user set `allow-passthrough on` — a setting invisible from
the environment. The engine verifies passthrough per session with a
wrapped round-trip probe and only then enables the kitty/iTerm2 paths,
wrapping every payload automatically. Known cosmetic limit: tmux cannot
reflow passthrough images across scrolling or pane splits. Mosaic works
everywhere regardless.
### Verifying image support on your terminal
Two commands answer "what does my terminal actually support?":
```bash
cargo run --example caps # the capability report
cargo run --example images # see it: mosaic families + protocol placement
```
`caps` renders the live capability set — the probe's upgrades appear on
screen moments after launch, and the `images via` line names the channel
the ladder picked (`kitty graphics protocol`, `iterm2 inline images`,
`sixel`, or `unicode mosaic`). Apps can read the same facts through
`use_caps(cx)` / `current_caps()`. `images` then shows the result: the
four mosaic glyph families side by side, and `p` places the same picture
through the chosen pixel protocol, labeled with the channel in the
footer.
What to expect per terminal: kitty, WezTerm, and Ghostty take the kitty
graphics path; iTerm2 and VS Code's terminal take OSC 1337 inline
images; foot and mlterm take sixel; Terminal.app and most others render
unicode mosaic — which is not a failure but the universal fallback, at
character-cell resolution. Under tmux, protocols engage only when the
passthrough probe proves `allow-passthrough on` (see above). If a
protocol row reads `yes` but you see mosaic, check `cell pixel size` —
without pixel geometry the ladder stays conservative.
### Not an image: hand-drawn vector strokes
Charts, gauges, and hand-rolled traces do not go through the image
pipeline at all. The public sub-cell canvas (`DotCanvas`, in the
prelude) draws braille/quadrant dot grids with line/bezier/arc strokes
and eighth-block fills — the same layer the shipped charts render
through, and what the diagram extensions stroke their edges with.
The full surface (dot-space model, primitives, the cell-color rule) is
[api.md § canvas](api.md#canvas--canvas--vector-strokes); for
node-and-edge diagrams, prefer the `abstracttui-graph` /
`abstracttui-mermaid` crates over hand-stroking
([graphs-and-diagrams.md](graphs-and-diagrams.md)).
## 3D end-to-end
### The five-line hello
```rust
use abstracttui::three::{self, Framebuffer, SceneRenderer};
let view = three::quick_view("model.glb")?; // load + framed camera + light
let mut fb = Framebuffer::new(160, 96);
SceneRenderer::new().render(&view.scene(), &mut fb);
// fb -> mosaic cells via MosaicRenderer, or use Viewport3D below.
```
`quick_view` (and `quick_view_bytes` for in-memory GLB data) returns a
`QuickView` with public `model`, `camera`, `light`, and `stats` fields —
adjust the camera and light freely between frames, then call `.scene()`.
`stats` reports decode cost (texture decode dominates on textured models;
a 2048² JPEG-textured asset loads in the ~100 ms class — show a loading
state around it). `look_from(yaw, pitch)` re-frames the camera on the
model's bounds: the "reset camera" a viewer needs.
### What loads (the GLB subset)
Binary GLB containers with embedded buffers; TRIANGLES primitives;
positions, normals, UVs, and vertex colors; u8/u16/u32 indices or
non-indexed geometry; node TRS and matrix hierarchies; multiple scenes
(the default scene wins); `baseColorFactor` and `baseColorTexture`
(embedded PNG or baseline JPEG); `emissiveFactor`; smooth-normal
generation on request; and a 2-million-triangle budget enforced from
metadata before decode.
Rejected **by name**: sparse accessors, Draco/meshopt compression,
non-triangle primitive modes, and out-of-range anything. Labeled
degradations (the model loads, with a warning): external URIs, unsupported
texture maps (normal/metallic-roughness/occlusion), morph weights, and
CUBICSPLINE animation channels (skipped).
### Scene, camera, light
`Scene<'_>` borrows a `Model` and carries a `Camera` (orbit-style: target,
yaw, pitch, distance, vertical FOV, near/far), a `Light` (directional:
direction vector or spherical `from_angles`, ambient + diffuse terms), a
background color, and a `double_sided` flag.
Culling defaults differ by entry, deliberately: bare `Scene::new` culls
back faces (procedural meshes are consistently wound), while `Viewport3D`
and `QuickView::scene()` render double-sided (real-world GLB exports are
not, and holes read as bugs). Flip `double_sided` explicitly when the
other trade-off fits.
### The Viewport3D widget
```rust
let vp = Viewport3D::new(Arc::new(model))
.orbit(yaw, pitch, zoom) // plain floats each build; signals live app-side
.mode(MosaicMode::HalfBlock)
.animate(0, t) // play clip 0 at time t (loops; static = rest pose)
.light_angles(azimuth, elevation)
.fog(0.15)
.on_orbit(move |dyaw, dpitch| { /* write yaw/pitch signals */ })
.on_zoom(move |steps| { /* write zoom signal */ })
.element(&tokens);
```
The widget is pure over its props: same props, same pixels. Left-drag
orbits (the pointer is captured for the drag, so fast drags keep steering
outside the rect), the wheel zooms — but the widget only *reports* deltas
through `on_orbit`/`on_zoom`; the app owns camera state and clamping.
`element(&TokenSet)` takes no scope because the widget holds no reactive
state. The default layout grows into whatever region the parent hands it
(a viewport has no intrinsic size to measure), so an un-`layout()`ed
viewport is visible by construction; pass `.layout(...)` to size it
explicitly. Buffers persist inside the draw closure, so a steady-state
repaint allocates nothing. `light`, `background`, `spin` (caller-driven
auto-rotation), and `cull_backfaces` round out the builder.
For a complete interactive viewer, run
`cargo run --example viewer3d -- model.glb`.
### Animation playback
`Model::animations()` lists the clips; `sample_pose_full(clip, t, &mut
Pose)` produces per-instance world matrices plus per-skin joint matrices —
pure in `t`, clamped to the clip's keyframe range (loop with
`t % clip.duration()`), and allocation-free in steady state (the `Pose`
scratch is reused across frames).
Supported interpolation: **LINEAR** and **STEP**; rotations use
shortest-path nlerp. **Skinning**: up to 4 joints per vertex
(`JOINTS_0`/`WEIGHTS_0`), linear blend, sanitized at load — out-of-range
weighted joints reject, drifted weight sums renormalize with a label. An
animated, skinned test asset ships in the repository
(`src/three/fixtures/animated_bar.glb`).
### Textures and mip-mapping
Base-color textures decode through the same image pipeline (embedded PNG /
baseline JPEG) and build a box-filter mip chain. The rasterizer picks a
mip level **per triangle** from the texels-per-pixel ratio, with bilinear
sampling within the level; wrap mode is REPEAT.
## The boot splash
An optional two-second identity animation for app startup, played before
your first frame. `boot::should_splash(&caps)` is the production gate: it
returns the reason to skip when the render handle is not a tty, when
`ABSTRACTTUI_NO_SPLASH` is set (any value except `0`, so wrapper scripts
can force-enable), when `NO_COLOR` is set, when `TERM=dumb`, or when the
capability report itself says the terminal is dumb. Respect the reason —
it is ready-made for a log line.
The sequence runs 2.0 s in four beats: **arrival** (three planes fly in,
staggered, on an ease-out curve), **alignment** (at 0.9 s the planes lock
into the mark and a 12-spark burst fires), **reveal** (at 1.4 s the
wordmark tracks open from 4 cells of letter-spacing to 1), **hold**
(settle, then done). Any key skips with a fast 120 ms fade, and a hard
2.5 s wall cutoff bounds the whole thing.
Two render paths read the same identity constants: a 3D path (the mark
rendered by the `three` rasterizer, chosen on truecolor terminals) and a
pure-cell 2D path with its own particle field (everywhere else). Try both:
`cargo run --example splash` (`--3d` / `--2d` to force one).
## Honest limits
- **JPEG**: baseline sequential only; progressive and arithmetic coding
reject by name. Scan component selectors are validated against the
frame header; malformed scans reject rather than decode wrong.
- **PNG**: 8-bit depths, no interlacing (Adam7 rejects by name).
- **Sixel**: one palette per emission — multiple live sixel images recolor
each other. Prefer one sixel image per screen.
- **iTerm2/sixel** have no placement model: any move or resize re-emits
the full payload; only kitty gets placement escapes and true deletes.
- **Pixel protocols** are verified byte-for-byte against the protocol
specifications and a protocol state model, not against every live
terminal emulator; mosaic is the universal, always-correct path.
- **Screenshots**: cells under a kitty/iTerm2/sixel placement are not
the picture — captures export those regions as labeled veils rather
than fake cells, while mosaic images capture as themselves (they ARE
cells). See [api.md § "Screenshots & captures"](api.md#screenshots--captures).
- **Animation**: LINEAR/STEP only; CUBICSPLINE channels and morph weights
skip with labels; rotation interpolation is nlerp, not slerp.
- **Skinning**: `JOINTS_0`/`WEIGHTS_0` only (4 joints per vertex), linear
blend, no inverse-transpose normal handling (an approximation under
non-uniform scale).
- **Textures**: base color only; other maps are labeled and ignored; wrap
is REPEAT (per-sampler modes are not read). Mip LOD is per-triangle,
not per-pixel.
- **Mosaic**: two colors per cell, by construction; braille carries
structure, not color.
- **Rasterizer**: near-plane and guard-band clipping, top-left fill rule,
perspective-correct depth and UVs; vertex-color interpolation is
screen-linear (invisible at cell scale).
- **Performance numbers are load-sensitive**: the envelope below is from
an idle machine; medians inflate several-fold under host contention.
## Performance envelope
Measured medians, release build, on a quiet machine (ms/frame):
| asset | triangles | 160×96 | 320×192 |
| --- | --- | --- | --- |
| synthetic sphere (untextured, gouraud) | 16,128 | 0.76 | 0.97 |
| helmet (JPEG textured + mips) | 15,452 | 1.31 | 1.82 |
| helmet (untextured) | 15,452 | 1.18 | 1.59 |
| x-wing (PNG textured + mips) | 119,999 | 7.53 | 8.21 |
| skinned sphere (animated, all vertices blended) | 65,024 | 2.90 | 3.26 |
The renderer is vertex-bound at cell scale: 4× the pixels costs +9–39%,
while 7.4× the triangles costs ~5.7×. Rule of thumb: assets up to ~20k
triangles render in well under 2 ms anywhere; a 120k-triangle asset fits a
30 fps budget with 3–4× headroom on one core.
Mosaic conversion adds, for a 200×60-cell target (worst case): half-block
~50 µs, braille ~0.5 ms, quadrant ~1 ms, sextant ~3.7 ms.
Reproduce on your machine:
```bash
cargo test --release -- --ignored perf_three_envelope --nocapture
cargo test --release -- --ignored perf_mosaic_200x60 --nocapture
```
===== FILE: docs/graphs-and-diagrams.md =====
# Graphs and diagrams — the extension family
Core stays lean; diagram-class capability ships as sibling crates you
install only when needed ([ADR-0004](adr/0004-extension-packaging.md)):
- **`abstracttui-graph`** — graph auto-layout (`GraphDesc -> Layout`:
layered, force and grid passes) plus `GraphView`, a read-only graph
widget with selection, pan, tooltips and canvas-stroke edges.
- **`abstracttui-mermaid`** — honest-subset mermaid rendering:
flowcharts and flat state diagrams compile onto `abstracttui-graph`,
sequence diagrams render through a deterministic solverless plan,
and everything outside the subset falls back atomically.
Both are ordinary crates on the public core API — no private hooks, no
cargo features, the same dependency posture as core (std + the family;
the mermaid parser is hand-rolled).
## Installing
```toml
[dependencies]
abstracttui = "0.2"
abstracttui-graph = "0.1" # graph layout + GraphView
abstracttui-mermaid = "0.1" # mermaid subset (depends on -graph)
```
## The one data contract: `GraphDesc -> Layout`
You describe the graph; a layout pass returns positions. Every pass
shares the same input and output types — consumers select the
ALGORITHM, never a different contract:
```rust
use abstracttui_graph::{layered, GraphDesc, LayeredOpts};
let desc = GraphDesc::new()
.node("fetch", 9, 3) // id, card width/height in cells
.node("build", 9, 3)
.edge("fetch", "build");
let layout = layered(&desc, &LayeredOpts::default());
// layout.nodes: Rect + rank per node; layout.edges: waypoint
// polylines; layout.bounds: the content size a Scroll advertises.
```
Honesty markers ride the output: cycle-broken edges are MARKED
(`EdgeLayout::broken`, `Layout::broken_edges()`), and
`Layout::fallback` names every degradation (node cap exceeded,
duplicate ids dropped, unresolvable edges skipped, grid placement) —
`None` means the requested algorithm ran cleanly. Every pass is
deterministic (same input, identical `Layout`, golden-pinned; float
arithmetic avoids transcendentals so goldens hold across platforms)
and bounded (sweep counts, node caps, iteration budgets — documented
on the option types).
## Picking a pass
| Pass | Use for | Shape |
| --- | --- | --- |
| `layered(&desc, &LayeredOpts)` | workflows, dependency/build graphs, pipelines, state machines — DAG-shaped data (cycles get broken and marked) | sugiyama-lite: longest-path ranks, bounded median crossing-reduction sweeps, aligned-median coordinates, waypoints through rank gaps; directions TD/LR/BT/RL |
| `force(&desc, &ForceOpts)` | knowledge graphs, networks — cyclic, dense, non-hierarchical data that defeats layering | seeded, alpha-cooled repulsion + edge springs + optional `rank_bias`; a bounded ACT that freezes on settle (never an idle animation — cache the `Layout`, re-render from the cache) |
| `grid(&desc)` | the honest fallback | near-square row-major placement, always labeled |
The grid is also what `layered` degrades TO: past the node cap
(default 512) it returns the grid placement with the cap named in
`Layout::fallback` — a labeled grid beats a hung solver at terminal
scale. Measured on a dev machine (unoptimized profile): 500 nodes /
718 edges lay out in ~14 ms (`layered`) and ~30 ms (`force`, budget
64).
## GraphView
`GraphView` renders a `Layout`: node cards (title on the border, an
optional kind-tinted left accent, a reactive badge slot), edges as
sub-cell canvas strokes (smoothed beziers through the waypoints,
arrowheads, dotted/thick styles from `EdgeDesc::style`, cycle-broken
edges dotted in their own ink — drawn through core's public
[canvas layer](api.md#canvas--canvas--vector-strokes)), the fallback
label as a non-scrolling notice line, and pan via `Scroll`.
```rust
use abstracttui::prelude::*;
use abstracttui_graph::{GraphDesc, GraphStyle, GraphView, NodeDesc};
// Inside a view builder (cx: Scope), colors caller-resolved from the
// active theme per the widget token rule:
let t = use_theme(cx).get().tokens;
let style = GraphStyle::from_tokens(&t)
.kind_accent("ok", t.ok)
.kind_accent("error", t.error);
let view = GraphView::new(
GraphDesc::new()
.with_node(NodeDesc::new("a", 12, 3).label("Fetch").kind("ok"))
.with_node(NodeDesc::new("b", 12, 3).label("Parse").kind("error"))
.edge("a", "b"),
)
.style(style)
.badges(|id| (id == "a").then(|| "3".to_string()))
.tooltips(std::time::Duration::from_millis(300))
.on_node_press(|id| eprintln!("pressed {id}"))
.view(cx);
```
Interaction is ONE focus stop: arrows pan until a node is selected;
Enter selects the first node, then arrows move the selection
spatially (aligned-first, deterministic tiebreaks), Enter presses it
(`on_node_press`), Escape deselects. Clicking a card selects and
presses; hovering shows a tooltip when enabled. Layout runs at
view-build time (an act): rebuild the view (`dyn_view` over your data
signal) to relayout — a parked `GraphView` costs zero idle,
test-pinned. Algorithm selection: `.algo(GraphAlgo::Force(opts))`, or
`.with_layout(layout)` to render positions you computed (or dragged)
yourself.
Run the crate examples: `cargo run -p abstracttui-graph --example
workflow` (layered pipeline with a marked retry cycle) and `--example
network` (force-directed).
## Mermaid: the honest subset
Mermaid has no spec grammar, and "faithful" is the wrong bar for a
terminal. `abstracttui-mermaid` renders an exhaustive, tested subset
natively and falls back ATOMICALLY on everything else. The table
below is the contract, verbatim from the crate docs
([docs.rs/abstracttui-mermaid](https://docs.rs/abstracttui-mermaid));
the YES rows enumerate accepted SPELLINGS, and any spelling outside
them triggers the fallback naming the first unrecognized line —
unknown syntax is safe by construction:
| Mermaid | v1 | Accepted spellings (exhaustive) | Behavior |
| --- | --- | --- | --- |
| `flowchart` / `graph` TD/TB/LR/BT/RL | YES | header keyword + direction token only | layered layout (BT/RL as transposes) |
| Node shapes | YES | `id`, `id[text]`, `id(text)`, `id{text}`, `id([text])`; quoted `"text"` inside brackets | cards; shape = accent + badge sigil (see below) |
| Edges | YES | `-->`, `---`, `-.->`, `==>`; label as postfix `\|label\|` only | strokes; dotted/thick as stroke styles |
| `subgraph` | NO (v2) | — | atomic fallback |
| `sequenceDiagram` | YES | `participant id [as alias]`; messages `->>`, `-->>`, `->`, `-->` with `: text`; `Note left of/right of/over` | deterministic columns/rows — no solver |
| sequence `loop`/`alt`/`par`/activations | NO (v2) | — | atomic fallback |
| `stateDiagram-v2` (flat) | YES (stretch) | `[*]`, `id`, `id : label`, `-->` with `: label` | compiles to the flowchart engine |
| `classDiagram`, `erDiagram`, `gantt`, `pie`, `journey`, `mindmap`, `timeline`, `gitGraph` | NO | — | atomic fallback |
| `classDef`, `style`, `%%{init}` directives | IGNORED | recognized-and-dropped WITH a notice; `%%` comments drop silently | render proceeds |
The stretch row shipped: flat `stateDiagram-v2` parses as a third
front end to the flowchart IR (`[*]` becomes synthetic start/end
nodes). Cell-honest shape mapping: terminal cards do not rotate into
diamonds — a shape arrives as the card's accent kind plus a badge
sigil (`id{..}` → `decision` + ◆, `id(..)` → `rounded` + ○,
`id([..])` → `stadium` + ◎). Lexical notes (normalization, not new
constructs): `;` is a statement terminator, `%%` comments strip to
end of line (quote-aware); the infix label form (`--label-->`),
`&`-chaining, and edge chaining (`A --> B --> C`) are named v2
fallbacks.
### The atomic fallback
If a diagram contains ANY construct outside the table (styling
directives excepted), the WHOLE diagram renders as the code fence it
already is — verbatim source, monospace — plus one notice naming the
first unsupported construct and line, plus an optional
[mermaid.live](https://mermaid.live) link (`live_link_url`): the
diagram travels in the URL FRAGMENT, never to a server; nothing is
shared until the user opens the link. Partial rendering of a
half-understood diagram misleads; the code block never lies.
### Usage
```rust
use abstracttui_mermaid::MermaidView;
// In a view builder:
let view = MermaidView::new(
"graph TD\n A[Start] --> B{Ship?}\n B -->|yes| C(Done)",
)
.view(cx);
// Pure-data entry points for other consumers:
// parse(&str) -> Result<Diagram, Unsupported> (IR or named reason)
// to_graph(&FlowchartIr) -> (GraphDesc, LayeredOpts)
// live_link_url(&str) -> String (the escape hatch)
```
Run the demo: `cargo run -p abstracttui-mermaid --example mermaid`
(four embedded samples including an honest fallback; or pass a `.mmd`
path).
## Honest limits (v1)
- Open links (`---`) carry the `open` style hint and render as
arrowless strokes in `GraphView` (mermaid's undirected reading).
- Sequence gaps size to ADJACENT-pair message labels; long labels
between distant columns truncate with an ellipsis.
- Edge chaining (`A --> B --> C`), infix labels, `&`-chaining and
`subgraph` are named fallbacks, not silent acceptance — growth is
new table rows with tests.
- Force layouts report `rank` 0 for every node (no hierarchy is
computed — honest, not missing data).
===== FILE: docs/live-data.md =====
# Live data: background sources into the UI
How a networked, long-lived app gets data from a background thread into
signals — the ownership rule, the named bindings, bounded back-pressure,
and the recurring time source. The runnable companion is
[`examples/feed.rs`](../examples/feed.rs).
## The ownership rule (one sentence)
The reactive graph is single-threaded: background threads never touch
signals — the only sanctioned crossing is a closure posted to the UI
thread, and writing a signal from the wrong thread is a **named panic**
(it tells you to use this page's pattern), never silent aliasing.
Under the hood that crossing is `reactive::WakeHandle::post(f)`: the
closure crosses the thread boundary, wakes the event loop, and runs in
the next frame's phase U with full runtime access. Two guarantees come
with it:
- **Ordered delivery** — one producer's posts apply in emit order
(FIFO; cross-producer order is lock-acquisition order).
- **One frame per burst** — any number of posts between two frames
coalesce into one wake and one repaint; a post landing mid-frame
applies in the next frame, exactly once.
And one cost rule: while a source is quiet, the app is byte-for-byte
idle — no polling, no timers, the loop parks in a blocking read.
## The bindings
You rarely post by hand. Three named helpers in `reactive::` cover the
shapes (all senders are `Clone + Send`; all signals die with the scope
that created them, after which senders turn **inert** — sends apply
nothing, count on `dead_sends()`, and are never unsafe):
| helper | signal shape | delivery | use for |
| --- | --- | --- | --- |
| `channel_source(cx)` | `Signal<Vec<T>>` | every value, in order, unbounded | low-rate event streams |
| `latest_source(cx, initial)` | `Signal<T>` | newest value; intermediates coalesce at the source | progress, telemetry, presence |
| `bounded_source(cx, capacity, policy)` | `Signal<Vec<T>>` window + `Signal<IngestStats>` | at most `capacity` retained; overflow per policy, counted | anything that can flood |
## Bounded ingestion and back-pressure honesty
`WakeHandle::post` is the **control lane**: unbounded by contract,
correct for low-rate messages. A flooding producer (chat hub, tool
output, tail -f) needs the **data lane**:
```rust
let (tx, events, stats) = bounded_source::<String>(
cx,
400, // the retained window, and the bound
OverflowPolicy::DropOldest, // what overflow MEANS is the app's call
);
```
- `DropOldest` — ring: the newest tail survives (feeds, logs).
- `DropNewest` — the head survives (capture the first N).
- `OverflowPolicy::coalesce(fold)` — overflow merges into the newest
survivor (progress updates that supersede each other). A fold that
PANICS degrades labeled instead of poisoning the lane: the panic is
caught, the value it consumed counts as `dropped`, the event counts
as `fold_panics`, and later sends keep working.
- **There is no `Block`.** Blocking a producer against the UI thread
inverts liveness: the producer inherits every UI stall (a held
scrollbar, a suspended terminal, a modal) as unbounded latency on its
own sockets and locks, and can no longer answer the cancellation the
UI is about to send it. Producers that must not lose data pause their
*reads* upstream (the transport pushes back); they never park on the
UI.
Honesty is part of the contract: every value lands in exactly one
bucket of `stats` (`IngestStats { delivered, dropped, coalesced,
fold_panics }` — the last counts events, its values are inside
`dropped`), updated atomically with the window. **Render `dropped`
(and `fold_panics`) when nonzero** — "1.2k shown · 34 dropped" is the
labeled-degradation convention; silent loss is the failure mode this
lane exists to prevent. `delivered + dropped + coalesced` always equals
values sent; a `DropOldest` window aging out an already-shown item is
retention churn, deliberately not re-counted as a drop. Memory is
bounded by construction (≤ 2×capacity across the transit buffer and
the window) and a burst costs one wake, one posted drain, one frame —
no matter how many values arrive.
Producer-side guidance: drain everything available per read and send
per item into the bounded lane (it batches internally), or batch into
few `post` closures on the raw lane. One closure per burst is the
intended cadence for high-rate sources.
## The recurring time source
Time is the zeroth data source. `reactive::interval` is the engine-owned
version of the self-rescheduling `after(..)` recursion, with the
cancellation story the recursion never has:
```rust
let handle = interval(cx, Duration::from_secs(1), move || {
now.set(clock_text()); // runs on the UI thread, phase U
});
// handle.cancel() stops it early; scope disposal cancels it anyway —
// a closed pane's poller cannot keep ticking by accident.
```
Fixed-delay drift policy: the next deadline is *fire time + period*.
After a suspend of N periods it fires **once** and resumes cadence —
missed ticks coalesce, there are no catch-up storms. Between fires an
armed interval costs zero wakeups (the loop sleeps until the deadline);
timers never frame-pace.
## Connection lifecycle
Reconnect is the half of networking with no transport dependence at
all, so the engine owns it: `reactive::connection` is the state
machine, `reactive::Backoff` the retry schedule. The engine still does
**no network I/O** — you supply the dial function; the transport stays
your call. What you stop hand-rolling: the state enum, the backoff
math, the retry timer, the cancellation story, and the answer to "what
does the frame loop do while offline" (nothing — the one armed
one-shot costs zero wakeups until due).
```mermaid
stateDiagram-v2
[*] --> Connecting : connection(cx, backoff, dial)
Connecting --> Connected : events.connected()
Connecting --> Degraded : events.degraded(reason)
Connecting --> Reconnecting : events.failed(reason)
Connected --> Degraded : events.degraded(reason)
Degraded --> Connected : events.connected()
Connected --> Reconnecting : events.failed(reason)
Degraded --> Reconnecting : events.failed(reason)
Reconnecting --> Connecting : retry timer fires / retry_now()
Connecting --> Closed : close() / events.closed()
Connected --> Closed : close() / events.closed()
Degraded --> Closed : close() / events.closed()
Reconnecting --> Closed : close() (armed retry cancelled)
Closed --> [*]
```
Every transition is a signal write — the UI renders the state like any
other signal, and each state carries what honest rendering needs
(`Degraded(reason)`; `Reconnecting { attempt, next_in }` for
"reconnecting (attempt 2) in 1.4s"). Success resets the schedule;
`Closed` is terminal from either side (UI `close()`, transport
`closed()`, or scope disposal) and costs nothing forever.
```rust
use abstracttui::prelude::*;
use abstracttui::reactive::spawn_worker;
let conn = connection(cx, Backoff::default(), move |events| {
// Runs on the UI thread once per attempt: spawn the blocking
// transport work and return immediately.
let events = events.clone();
spawn_worker("hub-stream", move || {
match dial_hub() { // your transport
Ok(stream) => {
events.connected();
while let Ok(msg) = stream.read() {
if events.is_closed() { return; } // stop condition
tx.send(msg); // the 0010/0020 lanes
}
events.failed("stream ended"); // drop -> reconnect
}
Err(e) => events.failed(e.to_string()),
}
});
});
// Render it honestly — a badge, a status line, dimmed panes:
let state = conn.state();
dyn_view(LayoutStyle::line(1), move || match state.get() {
ConnState::Connected => text("● online"),
ConnState::Degraded(r) => text(format!("◐ degraded: {r}")),
ConnState::Reconnecting { attempt, next_in } =>
text(format!("○ retry #{attempt} in {next_in:.1?}")),
ConnState::Connecting => text("… connecting"),
ConnState::Closed => text("· closed"),
});
```
**Why full jitter.** A fleet of clients backing off `base × 2^n`
with no jitter retries in lockstep after a server restart — every
retry wave lands together and the herd re-kills the thing it is
waiting for. The common hand-roll (linear `500ms × errors`, capped,
no jitter) has exactly that failure mode. `Backoff` draws uniformly
from `[0, min(cap, base × 2^n)]` (defaults: base 500 ms, cap 30 s),
so retries decorrelate while pressure on a dead endpoint still decays
exponentially. `Backoff::seeded(n)` makes tests deterministic.
Three rules the machine enforces so you don't have to:
- **Stale attempts can't lie.** Each dial gets a generation-stamped
reporter; once a failure is accepted, later reports from that
attempt (a zombie worker racing its replacement) are inert and
counted (`stale_reports`) — attempt N can never flip attempt N+1's
state. Workers poll `events.is_closed()`/`is_current()` to stop
early.
- **Cancellation is scope death.** The connection dies with `cx` like
everything else: armed retry removed, dial fn dropped, workers see
`is_closed()`. `conn.close()` does the same on demand;
`conn.retry_now()` skips a pending wait (the "retry now" button).
- **Offline is idle.** Between transitions the loop stays parked; the
only clock is the one armed one-shot. A visible countdown is an
ordinary `interval`, billed as such — never a poll loop.
Catch-up after reconnect (cursors, replay, resubscription) is
deliberately NOT here — it is transport/protocol policy (the app's
dial fn re-subscribes; per-channel cursors in the reference domain),
and the state enum must never grow transport-specific fields.
## Worker lifecycle
Spawn producers with `reactive::spawn_worker(label, f)`: a worker
**panic** is posted back and surfaces as a labeled app error (`Driver`
turns it into `Err`), instead of a thread dying silently while the feed
just... stops. A clean return is not an error. Give workers a stop flag
and join them after `App::run` returns (the feed example's teardown),
so no thread outlives the terminal session.
## Copy-paste starting point
The rendering side pairs the bounded window with the `Feed` widget
(keyed rich items, windowed paint) inside `Scroll` with the engine's
follow-tail: the content extent is measured (no size hint), the offset
sticks to the bottom until the user scrolls up, and setting the follow
signal true jumps back to the latest. The window syncs into slot keys,
so the Feed holds at most `capacity` items — bounded end to end.
(`FeedState::clear` enables a simpler clear-and-repush sync; the
slot-key recipe shown here re-typesets only the slots whose content
actually changed.)
```rust
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use abstracttui::prelude::*;
use abstracttui::reactive::{bounded_source, spawn_worker, OverflowPolicy};
use abstracttui::widgets::{Feed, FeedItem, FeedState};
fn main() -> abstracttui::base::Result<()> {
if !abstracttui::term::have_tty() {
return Ok(());
}
let stop = Arc::new(AtomicBool::new(false));
let mut app = App::new(Size::new(80, 24));
let mut sender = None;
app.mount(|cx| {
let (tx, events, stats) =
bounded_source::<String>(cx, 400, OverflowPolicy::DropOldest);
sender = Some(tx);
let feed = FeedState::new(cx);
let feed_sync = feed.clone();
cx.effect_labeled("window-sync", move || {
events.with(|rows| {
for (i, line) in rows.iter().enumerate() {
feed_sync.push(format!("slot-{i}"), FeedItem::text(line.clone()));
}
});
});
let follow = cx.signal(true); // read it for chrome; set true to jump
Element::new()
.style(LayoutStyle::column())
.child(
Scroll::new(Feed::new(&feed).gap(0).view(cx))
.follow_tail(follow)
.view(cx),
)
.child(dyn_view(LayoutStyle::line(1), move || {
let s = stats.get();
text(match s.dropped {
0 => format!("{} events", s.delivered),
d => format!("{} events · {d} dropped", s.delivered),
})
}))
.build()
})?;
let tx = sender.take().expect("mounted");
let stop_w = stop.clone();
let worker = spawn_worker("my-source", move || {
while !stop_w.load(Ordering::Relaxed) {
// read your socket/process/channel here, then:
tx.send("hello from the background".to_string());
std::thread::sleep(std::time::Duration::from_millis(500));
}
});
let result = app.run();
stop.store(true, Ordering::Relaxed);
worker.join().ok();
result
}
```
Swap the sleep for a real read loop and this is a networked app: the
transport (HTTP poll, WebSocket, subprocess pipe) is your choice — the
engine's job ends at the thread boundary, and this page is that
boundary's contract. The runnable version with bursty timing, pause,
and an events/sec `interval` is [`examples/feed.rs`](../examples/feed.rs).
## Message cards that fold (per-item disclosure)
Hub watchers and chat transcripts render each message as a card with a
one-row title that folds/unfolds. Standalone cards (settings panes,
tool results outside a feed) are the `Disclosure` widget directly —
capped scrolling body, click/Enter toggling, app-owned fold signals.
INSIDE a `Feed`, keep the feed's virtualization and compose the same
semantics: fold state in a `Signal<HashMap<key, bool>>`, the fold bit
folded into each item's `SyncSpec` fingerprint (`(rev, folded)` — a
toggle re-typesets exactly that item), folded items rendered as one
rich header line, unfolded as header + body blocks, Enter on the
selected key plus click-to-toggle via `Feed::on_item_press` gated on
`row_within_item == 0`. The full recipe (and why the in-feed card is a
pattern rather than an engine block kind today) lives in
[api.md → "The message-card recipe"](api.md#the-message-card-recipe-feed--disclosure-semantics).
## Testing live-data apps
The headless harness works unchanged: drive `Driver::turn` against
`testing::CaptureTerm`, send from a joined thread between turns, and
assert on the rendered screen — one frame per burst, zero bytes while
quiet. `tests/wave_livedata.rs` pins exactly those claims and is a
gallery of the shapes.
Time is scriptable too: timers arm **and** fire against the loop's
clock, so an injected test clock drives `interval` cadence and
`Backoff` retry deadlines deterministically — the driver publishes its
clock around each turn automatically, and a custom loop calling
`run_due_timers(now)` publishes the same value with
`reactive::set_loop_clock(Some(now))` (`None` restores real-time
arming). See [api.md § reactive](api.md#reactive--signals-memos-effects)
for the one-clock story.
===== FILE: docs/faq.md =====
# FAQ
## Why another TUI library?
Most terminal UI libraries make one of two bets: immediate-mode (redraw
everything every frame, diff at the end) or a retained widget tree with
coarse invalidation. AbstractTUI makes a different one: **fine-grained
reactive signals driving a layered compositor with damage tracking**.
State lives in signals; only the regions that read a changed signal
re-render; the compositor diffs only damaged cells; an idle app sits in a
blocking read at zero CPU. On top of that sits capability-driven graphics
(real images and software-rasterized 3D with labeled fallbacks) and a
36-token theme system with enforced contrast floors. If your app is a
short-lived form, simpler designs are fine; AbstractTUI is built for
long-running, composed, animated applications that should still cost
nothing when nothing happens.
## Does it work over SSH?
Yes. Everything the engine does travels as bytes over the pty, which is
exactly what SSH carries. Capabilities are detected from the terminal that
is actually attached — your local emulator — via an environment pass plus
an active query probe, so color depth, image protocols, and keyboard
enhancements reflect what your end of the connection supports. Expect the
same feature set you would get locally in the same emulator; only latency
changes.
## Which terminals support images?
Anything, at some rung of the ladder. Kitty-protocol terminals get the
best channel (upload once, cheap moves, true deletes); iTerm2-protocol
terminals get inline images with full re-emits; sixel terminals get
paletted rasters; **every** terminal gets unicode mosaic, which is plain
colored glyphs and needs nothing. The engine probes and picks; run
`cargo run --example caps` for the live capability report (the
`images via` line names your channel), and `cargo run --example images`
to see the result. See [graphics-and-3d.md](graphics-and-3d.md) for the
full ladder and the per-terminal expectations.
## Why is my emoji/wide-character layout off in one terminal?
Because terminals genuinely disagree about the width of some characters.
Emoji presentation sequences (VS16), ZWJ families, and East-Asian-Ambiguous
symbols render at different widths across emulators and configurations —
there is no protocol to ask. The engine measures with a consistent width
policy and defends its cursor after emitting a risky cluster, so a
disagreement stays confined to that cluster instead of smearing everything
after it on the line. If your terminal is configured ambiguous-wide, cell
layout of every TUI breaks regardless; prefer the terminal's default width
configuration, and prefer unambiguous glyphs in structural chrome.
## How do I test my app headlessly?
Drive the same pipeline production uses against a captured terminal — no
tty needed:
```rust
use abstracttui::app::Driver;
use abstracttui::testing::CaptureTerm;
let mut term = CaptureTerm::new(size);
let mut driver = Driver::new(&mut app, &mut term, cfg)?;
driver.turn(&mut app, &mut term)?; // one full frame cycle
assert!(term.screen().to_text().contains("n = 0"));
term.push_input(b"+"); // bytes, as a terminal would send
driver.turn(&mut app, &mut term)?;
```
`CaptureTerm` records the emitted bytes and models the screen, so you
assert on rendered text (or raw bytes) with every dispatch, focus, and
damage path being the real one. For pure component tests, skip the driver:
mount into a `ui::UiTree`, dispatch events, draw into a buffer canvas.
## How do I capture a screenshot of my app?
Capture the screen as a plain value and export it: `Screenshot` (in the
prelude) exports deterministic plain text (`to_text`), replayable ANSI you
can `cat` back into a terminal (`to_ansi`), and a GitHub-renderable SVG
(`to_svg`). Three capture surfaces: `driver.screenshot()` for embedders
and tests (the frame as last presented), `app::request_screenshot(cb)`
from any key handler (bind your own key — there is deliberately no engine
default), and `term.screen().screenshot()` in headless tests (what the
emitted bytes actually produced). One honesty rule: pixel-protocol image
regions export as labeled veils, never as fake cells. See
[api.md § "Screenshots & captures"](api.md#screenshots--captures) and
`cargo run --example screenshot`.
## Can I draw custom vector graphics — or render graphs and diagrams?
For hand-rolled traces, the public sub-cell canvas (`DotCanvas`, in the
prelude) gives you braille/quadrant dot grids with line/bezier/arc strokes
and eighth-block fills — the same layer the shipped charts draw through
([api.md § canvas](api.md#canvas--canvas--vector-strokes)). For
node-and-edge diagrams, don't hand-stroke: the sibling crates
`abstracttui-graph` (auto-layout + `GraphView`) and `abstracttui-mermaid`
(honest mermaid subset) install only when you need them — see
[graphs-and-diagrams.md](graphs-and-diagrams.md).
## Can I embed AbstractTUI in an existing event loop?
Yes. `App::run` is a convenience, not a requirement. `Driver::turn` runs
exactly one frame cycle and never blocks — the blocking edge is a separate
wait call, so your own loop decides when to pump. Headless surfaces
(`pump`, `draw`) drive the reactive and layout pipeline without a terminal
at all, and the unix terminal can be constructed over explicit file
descriptors for embedders.
## Why the near-zero dependency policy?
The dependency policy is a hard rule: `std` plus a minimal, low-level,
permissively-licensed set — `unicode-width`, `unicode-segmentation`,
`miniz_oxide` (inflate for PNG), and the platform bindings (`libc` on
unix, `windows-sys` on Windows). Everything else is hand-rolled: ANSI
emission, the input parser, the flexbox solver, the signals runtime, JSON
parsing for glTF, PNG chunking and defiltering, JPEG decode, base64, sixel
encoding, and the 3D math and rasterizer. The payoff is a dependency graph
you can audit in one sitting, fast clean builds, no feature-flag matrix,
and behavior that changes only when this crate changes.
## How do themes stay readable?
Every theme — built-in or registered at runtime — is audited against
WCAG-derived contrast floors: body text at 4.5:1, muted text at 3:1,
accents and semantic marks at 3:1, selection text at 4.5:1, and so on down
to hairline borders at 1.5:1. The built-in family passes with zero
violations as a test invariant, and `theme::register` runs the same audit
on your themes — refusing in strict mode or labeling every finding in
labeled mode. See [theming.md](theming.md#contrast-guarantees) for the
full table.
## What happens on a dumb terminal, or with NO_COLOR?
Both are honored. `TERM=dumb` (or an empty `TERM`) marks the terminal as
not worth escaping at: the active capability probe is skipped entirely and
the splash refuses to play. `NO_COLOR` forces color depth down regardless
of what the terminal supports, and the raw fact is surfaced so themes can
react. On limited-color terminals, the presenter quantizes to the 256- or
16-color palette pairwise — foreground and background are re-picked
together so text never vanishes into its own background.
## Is Windows supported?
Best-effort, honestly labeled. macOS and Linux are the verified platforms:
every unix code path is exercised by live pty tests, including
signal-driven resize, job-control suspend, and keystroke flow under a real
controlling terminal. The Windows backend compiles cleanly against the
MSVC target, its platform-independent logic (UTF-16 pairing, wake
latching, resize dedupe) is unit-tested on every host, and its console
usage follows Microsoft's documented semantics — but it has not been
exercised on live Windows hardware. Treat a first Windows
deployment as a beta event. (One concrete difference: `suspend()` returns
an explicit Unsupported error on Windows — hide the Ctrl+Z binding there.)
## How big is the crate?
One crate, no feature flags, no build script, three small library
dependencies plus the platform bindings. The source is roughly 105k lines
of Rust including its extensive inline test suites — decoders, rasterizer,
layout solver, and signals runtime included, since none of that is pulled
in from elsewhere.
## Can widgets be shared as libraries?
Yes — a component is a plain function, so it ships like any Rust code. The
convention: a props struct (with `Callback<T>` fields for typed events out
and `View` fields for slots), a function that takes `Scope` and props and
returns a `View`. `Callback::default()` is a no-op, so optional events
cost nothing to leave unbound. The `components` example is the heavily
commented reference: three reusable components composed repeatedly with
different props into a settings screen.
## How do I see what is actually repainting?
The compositor has a damage visualizer
(`render::Compositor::set_debug_damage(true)`) that outlines exactly the
regions each frame repaints. The switch lives on the compositor itself, so
today it is for embedders driving the render pipeline directly
([api.md § render](api.md#render--surfaces-and-paint-advanced)) — under
`App::run` the driver owns the compositor and exposes no toggle yet. The
signal-side diagnosis needs no visualizer: if a "static" screen keeps
repainting, something is writing a signal it shouldn't (every `dyn_view`
that reads it re-renders) — audit the writes before reaching for a
profiler. Perf numbers only mean anything in `--release` builds.
## Why can my app write the clipboard but not read it?
By design. Copy uses OSC 52 (gated on detection, since some terminals
silently ignore it, and success is only reported when the capability
holds). The **read** form of OSC 52 is deliberately never emitted: it
would let any full-screen application silently read the user's clipboard —
a data-exfiltration vector. Paste reaches your app exclusively through
bracketed paste, which is fuzz-hardened: multi-megabyte pastes stream in
bounded chunks, byte-exactly, with embedded escape sequences neutralized
as content.
Writing is easy to reach: `copy_to_clipboard(text)` from any handler, or
enable the engine's drag-select (`selection()`) so users copy what they
see — both in the
[api.md selection section](api.md#appselection--screen-text-selection-and-clipboard-copy).
If a copy never arrives, see
[troubleshooting](troubleshooting.md#the-engines-copy-doesnt-reach-my-clipboard).
## Why doesn't Ctrl+Enter (or Shift+Enter) do anything?
On the classic terminal wire, Ctrl+Enter, Shift+Enter, and Ctrl+Backspace
are byte-identical to plain Enter / Ctrl+H — no parser can recover what
the terminal never sent. They become distinct under the kitty keyboard
protocol or xterm's modifyOtherKeys, both of which the engine detects and
decodes automatically. Treat these chords as enhancements, not baseline
bindings; everything on arrows, Home/End, PgUp/PgDn, and F1–F12 with any
modifier combination is reliable everywhere.
## Does it support the mouse?
Yes: SGR-encoded mouse events (clicks, drags, wheel) in cell coordinates
on every supported terminal, hover/click affordances in the built-in
widgets, pointer capture for drags (the 3D viewport uses it for orbiting),
and pixel-precision reporting where the terminal verifiably supports it —
raw pixel coordinates ride alongside cell coordinates only when pixel
reporting is actually active, never posing as cells.
## How do I let users pick a theme?
`set_theme_by_id(id)` switches at runtime and the whole app restyles
through the one theme signal; `theme::list()` gives you `(id, label,
dark)` for every visible theme, including ones your app registered. The
shipped examples honor `ABSTRACTTUI_THEME=<id>` as a startup convention,
and `cargo run --example themes` is a complete picker UI — card grid, live
preview, measured contrast ratios — you can crib from.
===== FILE: docs/troubleshooting.md =====
# Troubleshooting
Symptom → cause → fix, for the problems terminal reality actually
produces. Two diagnostic surfaces recur below:
- **The capability report**: `cargo run --example dashboard -- --caps`
(also `viewer3d`, `images`) prints what the engine detected — color
depth, image protocols, keyboard enhancements, tmux state. In code:
`caps.summary()` (multi-line) or `caps.summary_line()` (one line).
- **Startup notices**: labeled degradations are collected at startup and
exposed reactively (`use_startup_notices`); render them in a footer or
toast and problems name themselves.
## Nothing renders at all
**Cause**: there is no terminal to render to. Either the process is not
attached to a tty (output redirected, running under CI), or `TERM=dumb`
(or empty) told the engine not to emit escapes at this terminal.
**Fix**: run inside a terminal emulator. If stdin/stdout/stderr are all
redirected and `/dev/tty` is unavailable, terminal construction fails with
an actionable error rather than emitting bytes into the void. For CI and
tests, don't fight it — drive the app headlessly with
`testing::CaptureTerm` (see [faq.md](faq.md#how-do-i-test-my-app-headlessly)).
Note the shipped examples deliberately exit 0 with a one-line notice when
there is no interactive terminal.
## Keyboard is dead under an unusual shell or launcher
**Cause**: some environments hand the process a terminal descriptor that
cannot be polled (a real macOS quirk with `/dev/tty`). The engine detects
this and falls back to a working descriptor instead of blocking forever.
**Fix**: usually none needed — an app that starts is an app that receives
keys. The fallback is a *labeled* degradation: `Terminal::degraded()`
returns the reason, and it lands in the startup notices. If keys are
genuinely dead, check the notices first; if the engine could not find any
workable descriptor it fails with an actionable error rather than starting
deaf.
## Images don't show (or fall back to blocky glyphs)
**Cause**: the terminal didn't prove a pixel protocol. Image channels are
enabled by detection — kitty graphics, iTerm2, or sixel (sixel also needs
the cell pixel geometry) — and anything unproven falls back to unicode
mosaic, with the degradation labeled, never silent.
**Fix**: check `--caps` to see which channel was chosen and why. Under
tmux, graphics are off by default: tmux swallows the protocols unless
`allow-passthrough on` is set, and that setting is invisible from the
environment, so the engine verifies it per session with a wrapped
round-trip probe and only then enables the pixel paths. Set
`set -g allow-passthrough on` in `~/.tmux.conf`, restart the session, and
re-check `--caps`. Mosaic output is not a bug — on terminals with no pixel
protocol it *is* the correct answer, and the quadrant/sextant/braille
modes are a deliberate quality ladder within it.
## Colors look wrong or washed out
**Cause**: the terminal did not advertise truecolor, so every 24-bit color
is being quantized to the 256- (or 16-) color palette. Detection reads
`COLORTERM` and `TERM` in the environment pass, and the active probe can
both raise and lower the verdict. `NO_COLOR`, if set, forces color off
deliberately.
**Fix**: use a truecolor terminal, or export `COLORTERM=truecolor` if your
terminal genuinely supports it but doesn't say so (common over some SSH
hops that strip the variable). Check what was detected with `--caps`. One
guarantee under quantization: foreground/background pairs are re-picked
together, so text may band but never vanishes into its own background.
## The screen flickers or tears during animation
**Cause**: the terminal doesn't support synchronized output (DEC private
mode 2026), so partially-painted frames can be displayed mid-write. Where
the capability is detected, the engine brackets frames and the terminal
displays each one atomically.
**Fix**: use a terminal that supports synchronized output (check
`--caps` — `sync` appears in the summary line when detected). Everything
still works without it; the engine's damage tracking keeps writes small,
which minimizes the visible window, but true tear-free animation needs the
terminal's cooperation.
## Ctrl+Enter behaves exactly like Enter
**Cause**: on the legacy wire they are the same bytes. Ctrl+Enter,
Shift+Enter, and Ctrl+Backspace are byte-identical to Enter / Ctrl+H — the
information does not exist in the stream, so no parser can recover it.
**Fix**: use a terminal with the kitty keyboard protocol or xterm's
modifyOtherKeys — both are detected and decoded automatically, and these
chords become distinct. In your own app, treat such chords as
enhancements with a baseline alternative; arrows, Home/End, PgUp/PgDn, and
F1–F12 with any modifier are reliable everywhere.
## The boot splash doesn't play
**Cause**: one of the deliberate gates fired. `boot::should_splash` skips
when the render handle is not a tty, when `ABSTRACTTUI_NO_SPLASH` is set
(to anything except `0`), when `NO_COLOR` is set, when `TERM=dumb`, or
when the capability report classifies the terminal as dumb.
**Fix**: if you *want* the splash, clear those variables and run on a real
tty (`cargo run --example splash` to verify; `ABSTRACTTUI_NO_SPLASH=0`
explicitly opts back in under wrapper scripts that set it). The gate
function returns the skip reason as a string — log it and the answer reads
itself. Also remember any keypress skips the splash with a fast fade; a
buffered keystroke at launch can end it almost immediately.
## Frames are slow
**Cause**: usually one of three, in this order: a debug build (the
rasterizer and mosaic fit are numeric code — `--release` is several times
faster); a busy machine (the published envelope is from an idle box, and
medians inflate several-fold under host contention); or your app damaging
more than it thinks (a signal written every tick re-renders every region
that reads it).
**Fix**: measure in `--release` first. Then audit what repaints: a
supposedly idle screen that keeps painting means some signal is being
written needlessly (every `dyn_view` that reads it re-renders). Embedders
driving the render pipeline directly can also flip the compositor's damage
visualizer (`render::Compositor::set_debug_damage(true)`) to outline each
frame's repaint regions — under `App::run` the driver owns the compositor,
so there is no app-level toggle yet. For 3D scenes,
the perf envelope and its reproduction commands are in
[graphics-and-3d.md](graphics-and-3d.md#performance-envelope) — the
renderer is vertex-bound at cell scale, so triangle count matters far more
than viewport size.
## Wide characters are misaligned in some terminals
**Cause**: East-Asian-Ambiguous characters, emoji presentation sequences
(VS16), and ZWJ families genuinely render at different widths across
terminals — some split emoji families into components, some render
ambiguous symbols double-wide under CJK configurations or emoji-font
fallback. There is no protocol to query the terminal's opinion.
**Fix**: the engine already confines the damage — after emitting a risky
cluster it re-anchors the cursor, so a width disagreement stays inside
that cluster instead of shifting the whole line (the classic smear). What
it cannot fix: a terminal configured ambiguous-*wide* breaks the cell
grid of every TUI. Keep the terminal's default width configuration, and
prefer unambiguous glyphs (plain ASCII, box drawing, block elements) in
structural chrome.
## A row vanishes (or content overlaps) on a small terminal
**Cause**: flex overflow pressure crushed a node to zero area — content
demanded more rows/columns than the viewport has, and something had to
give. The engine's guarantees at any size (0.2.15): a zero-area node is
CLEAN ABSENCE — its draw closure never runs, so it can never smear onto a
sibling's row; `Modal` and `Drawer` clamp into the viewport at open and
re-clamp on every resize; tab strips window with overflow indicators; wide
glyphs never tear at a clip edge. In debug builds every zero-collapse is
named by a startup notice.
**Fix**: two app-side recipes. Give incompressible chrome (title bars,
button rows, status lines) an explicit `shrink(0.0)` so the oversized
MIDDLE gives instead — or wrap that middle in a `Scroll`, whose default
`basis(0)` exerts no pressure. And render `use_startup_notices` somewhere
visible: the engine names every collapsed node into that lane, and a
notice nobody renders is a debugging session someone else pays for. The
full contract: [api.md § "Small terminals & content pressure"](api.md#small-terminals--content-pressure).
## Double-click doesn't activate (in the app, or in a test)
**Cause**: several honest ones, in likelihood order. In a `Table`, a SLOW
second click is deliberate: activation needs a true double-click (second
press within 400 ms, within 1 cell, on the already-selected row) —
re-clicking a row to focus its pane must never open its editor. A second
press that drifted onto a NEIGHBOR row only re-selects (fast click-walking
is browsing, not commitment), and a wheel between clicks resets the chain
(the content under the cell moved). In a HEADLESS TEST, a bare `ui::UiTree`
has no time source, so every press deterministically counts 1 —
double-click needs time to flow.
**Fix**: in the app, none — Enter and Space always activate, and `List`'s
click-on-selected gesture is timing-free. In tests, drive through the real
`Driver` (it publishes its `set_clock`-injectable clock as the ambient
event time each turn, so one injected clock scripts animations AND
double-click timing), or opt a bare tree in with
`ui::set_event_time(Some(t))`. Custom input paths outside tree dispatch
embed their own `ui::ClickChain`. The full convention:
[api.md § "Double-click"](api.md#double-click).
## My screenshot shows a labeled veil where an image should be
**Cause**: honesty, not loss. Cells under a kitty/iTerm2/sixel placement
are not the picture — the terminal shows pixels the cell plane cannot see,
so `Driver::screenshot()` stamps those placements into
`Screenshot::pixel_regions()` and the SVG exporter draws a labeled
placeholder veil instead of pretending. Text and ANSI exports stay
cell-plane-verbatim; VT-model captures (headless tests) carry no regions
at all — the rig counts protocol payloads without modeling their pixels.
**Fix**: if the still must contain the picture, render the image through
the unicode-mosaic path for the capture — mosaic images ARE cells and
capture as themselves. Otherwise accept the veil: it marks exactly the
region the terminal owned. See
[api.md § "Screenshots & captures"](api.md#screenshots--captures).
## I can't select text with the mouse
**Cause**: mouse capture. The engine enables SGR mouse reporting for
wheel scrolling and click routing, and a terminal in mouse-capture mode
sends drags to the *application* instead of performing its own text
selection. Every mouse-capturing TUI behaves this way — it is the
protocol, not a bug.
**Fix**: three answers, cheapest first.
1. **Hold the bypass modifier your terminal already ships.** Every major
emulator can bypass mouse capture for one drag:
| Terminal | Bypass gesture |
|---------------------|-------------------------------------------------|
| iTerm2 | Option+drag (also Cmd if configured) |
| macOS Terminal.app | Fn+drag (Option+drag selects rectangles) |
| kitty | Shift+drag |
| WezTerm | Shift+drag |
| GNOME Terminal/VTE (incl. Tilix, xfce4-terminal) | Shift+drag |
| Alacritty | Shift+drag |
| Windows Terminal | Shift+drag |
| tmux (inside any of the above) | the same modifier, per the OUTER terminal |
This selects raw screen cells — borders, gutters, and pane seams
included — which is why the engine also offers the next two.
2. **A "native selection mode" keybinding** (engine tier 2): the app
calls `app::selection::mouse_capture().suspend()` — mouse reporting
turns off, the terminal's own selection (and clipboard) works at full
native quality, and the app resumes with `.resume()` on its next
keypress. See the [api.md selection section](api.md#appselection--screen-text-selection-and-clipboard-copy).
3. **Engine drag-select with OSC 52 copy** (tier 3): the app enables
`app::selection::selection()`, and dragging paints a real selection
highlight clamped to the pane under the anchor; releasing (or
`c`/Enter/Ctrl+C) copies the selected screen text to the system
clipboard through OSC 52. `cargo run --example feed` demonstrates it.
## The engine's copy doesn't reach my clipboard
**Cause**: OSC 52 is a write-only, fire-and-forget escape — the terminal
either applies it or silently ignores it, and there is no reply to check.
Common blockers: the terminal does not support OSC 52 (the engine emits
anyway — harmless — and pushes a one-time labeled startup notice when the
capability was not advertised); tmux is in the middle (it consumes OSC 52
itself — `set -g set-clipboard on` in `~/.tmux.conf` lets it forward the
copy; the engine follows its verb policy and does not passthrough-wrap
OSC 52, because tmux handles the sequence natively); or a security
setting (some terminals gate clipboard writes behind a prompt or a
setting, e.g. `clipboard_control` in kitty).
**Fix**: check the startup notices first, then your multiplexer's
`set-clipboard`, then the terminal's clipboard permission setting. Size
is rarely the issue: screen selections are a few kilobytes and every
known OSC 52 cap (tmux's historical ~74KB, kitty's default 8MB) sits far
above them. As a last resort the modifier-bypass matrix above always
works — it never involves the application.
## Tests hang forever
**Cause**: the app was spawned in a harness with piped stdin that never
reaches EOF. An idle app deliberately sits in a blocking read (zero CPU),
so with a pipe that never sends bytes and never closes, it waits forever —
that is correct behavior pointed at the wrong harness design.
**Fix**: don't drive the real binary through pipes in tests. Use the
canonical headless harness — `testing::CaptureTerm` plus `Driver::turn` —
which runs the full production pipeline synchronously: push input bytes,
turn one frame, assert on the rendered screen. Every test in this crate
that exercises the app loop is written that way, and it needs no tty, no
timeouts, and no sleeps.
===== PACKAGE FACTS =====
- Crate: `abstracttui` 0.2.18 (Rust, edition 2021). First public release: 2026-07-21
(0.1.0); current release 0.2.21 (2026-07-25).
- Extension family (sibling crates in the repo workspace, installed only when needed;
ADR-0004 — public core API only, same MIT license and dependency discipline):
- `abstracttui-graph` 0.1.0 — graph auto-layout (`GraphDesc -> Layout`: layered /
force / grid passes) + the `GraphView` widget. Depends on `abstracttui` 0.2.
- `abstracttui-mermaid` 0.1.0 — honest-subset mermaid rendering (atomic fallback).
Depends on `abstracttui` 0.2 and `abstracttui-graph` 0.1.
- Description: a reactive, compositor-grade terminal UI engine — fine-grained signals,
layered rendering with damage tracking, streaming transcripts and live-data ingestion,
text selection with OSC 52 copy, images (kitty/iTerm2/sixel/mosaic),
software-rasterized 3D (GLB), a sub-cell vector canvas, themes and animation.
- License: MIT.
- Repository / homepage: https://github.com/lpalbou/abstracttui
- API reference: https://docs.rs/abstracttui (family: https://docs.rs/abstracttui-graph,
https://docs.rs/abstracttui-mermaid)
- Dependencies (std plus this minimal set; everything else is implemented in-crate):
- `unicode-width` 0.2 — cell-width measurement
- `unicode-segmentation` 1 — grapheme segmentation
- `miniz_oxide` 0.9 — DEFLATE (PNG decoding)
- `libc` 0.2 — Unix terminal FFI (unix targets only)
- `windows-sys` 0.61 — Windows console FFI (windows targets only)
- Test invocation (from CONTRIBUTING.md):
- `cargo test` — the core suite (~2,015 tests: unit tests, integration suites under
`tests/`, and doctests).
- `cargo test --workspace` — core plus the extension family (~2,140 tests; the CI
gate).
- `cargo test --test live_smoke -- --ignored --test-threads=1` — live pty smoke tests
(spawn a real terminal session; run serially).
- `cargo test --test perf_budgets --release -- --ignored --test-threads=1` —
engine-primitive performance budgets (meaningful only in release builds; run
serially).
- `cargo test --test perf_app_surfaces --release -- --ignored --test-threads=1` —
app-layer performance budgets: feed streaming, select popup, selection drag,
composer keystroke, diff scroll, startup time-to-first-frame (release, serial).
- `UPDATE_GOLDENS=1 cargo test` — deliberately (re)mint golden snapshots under
`tests/goldens/`.
- Lint gates before submitting: `cargo fmt --all` and
`cargo clippy --workspace --all-targets` (zero warnings expected).
- Windows cross-check: `cargo check --target x86_64-pc-windows-msvc`.