Expand description
ttui — a terminal UI framework built around layered buffers,
Transition-driven animation, and dumb (no-internal-state) widgets.
Modules§
- app
- Terminal event loop and the
Apptrait apps implement. Terminal event loop: polls input, dispatches to anApp, and redraws only the cells that changed since the last frame. - audio
AudioSinktrait for optional sound-effect playback. Optional sound-effect playback hook — apps depend onAudioSinkrather than a concrete audio backend so they stay testable/silent by default.- blend
- Alpha-blending prototype — spike prototype, not a committed API.
Alpha-blending prototype for the rendering-fidelity spike
(docs/design/specs/core/2026-08-08-rendering-fidelity-spike-design.md).
Spike-only, and now historical: the spike’s recommendation was
adopted, so
LayerStack::compositedoes real Porter-Duff “over” compositing onCell::alpharather than the hard-cutout rule this spike was measured against. These two functions are kept as the spike’s record and are not on the render path. - buffer
- Cell/
Buffer/LayerStack— the framework’s core render target.Cell/Buffer/LayerStack— the framework’s core render target. Widgets writeCells into aBuffer; apps composite multiple layers into one viaLayerStackbefore the terminal diff-flush. - camera
- Deterministic camera viewport and brightness scaling. Deterministic camera viewport and brightness scaling — used for panning/zooming a rendered buffer and for boot-sequence fades.
- canvas
- Sub-cell rendering primitive (half-block + braille) — graduated,
committed API; see the module docs for
HalfBlockvsBrailledetails. Sub-cell rendering primitive:HalfBlockmode gives 2x vertical resolution with full 2-color fidelity per cell;Braillemode gives 4x resolution with one fg color per cell. Graduated from the rendering-fidelity spike (docs/design/specs/core/2026-08-08-rendering-fidelity-spike-design.md) per docs/design/specs/core/2026-08-08-rendering-primitives-graduation-design.md. - easing
- Linear/eased interpolation and progress helpers.
Linear/eased interpolation and progress helpers — the building
blocks every
Transition-driven animation in this codebase uses. - effects
- Screen-shake and other whole-buffer visual effects. Screen-shake and other whole-buffer visual effects.
- glitch
- Decaying noise overlay for glitch/corruption effects. Decaying noise overlay for glitch/corruption effects — shared across screens that render mutually-exclusive glitch states.
- input
- Key-binding resolver: single keys and multi-key chords resolving
to an app-defined action type.
Framework-level key-binding resolver: single keys and multi-key
chords resolve to an app-defined action type. Apps compose an
InputBinderinto their own state (likeGlitchBuffer/ParticleSystem) rather than theApptrait changing shape. - layout
Rect/Constraint-based area splitting.Rect/Constraint-based area splitting, in the same spirit as ratatui’sLayout— divides one area into ordered sub-areas.- noise
- Deterministic seed-driven jitter for scattering and placement. Deterministic seed-driven jitter — one integer hash, no RNG state and no allocation, so the same seed gives the same offset on every frame and every run. Not a general-purpose PRNG and not cryptographic: it exists to place stars and nudge glyphs.
- particles
- A simple particle system for bursts and impacts. A simple particle system for bursts and impacts — one straight-line velocity per particle, no gravity or collision.
- perspective
- Fixed-forward pinhole-camera projection: points, lines, polygons. Fixed-forward pinhole-camera projection — points, lines, and polygons in camera-relative 3D space project to 2D screen coordinates plus a depth-derived scale. Graduated from the depth & perspective projection spike (docs/design/specs/core/2026-08-10-depth-perspective-projection-spike-design.md) per docs/design/specs/core/2026-08-11-perspective-projection-graduation-design.md. No camera position/orientation — see that spec’s Non-goals.
- terminal
- Raw-mode terminal setup/teardown. Raw-mode terminal setup/teardown: entering the alternate screen, diff-based redraws, input polling, and panic-safe cleanup.
- theme
- App color palette and border glyph set.
App color palette and border glyph set — passed explicitly to
Block/SmashBorder; other widgets take plain color params instead of a wholeTheme. - transition
- Time-driven progress tracking for animations, and the
Phasessubdivision of a progress range. Time-driven progress tracking for animations — apps own aTransitionper animated value,tickit each frame, and readprogress()/is_complete()to drive rendering.Phaseslives beside it because the two are read together —PHASES.at(t.progress())turns one overall progress into a phase index and progress within that phase — not because this module owns animation staging. - widgets
- Ready-to-render widgets — see
widgetsmodule docs. Ready-to-render TUI widgets — each takes an explicit value/theme and a target area, no internal animation state; the owning app computes any tweened value and passes a snapshot per frame.