TUIX Core v0.5 Overview
TUIX is a modular terminal UI engine inspired by web technologies. It provides a DOM-like component model, a nested layout system, a viewport-aware input and rendering pipeline, and a buffer-based renderer for structured terminal interfaces.
Version 0.5 keeps the low-level C + Cython core but focuses on composition and stability: safer pixel ownership, resize and teardown hardening, lower render-path lock contention, row/column/split/grid layout builders, viewport widgets, modal dialogs, scene transactions, richer snapshots, and mouse capture.
Architecture
The runtime is split into three layers: a native C engine for buffers, layout, hitmaps, compositing, diffing, and terminal output; a Cython bridge for fast binding calls; and Python modules for scene lifecycle, object creation, widget configuration, snapshots, and application control.
Each frame routes input, resolves geometry, lets builders update state and content, composites visible buffers, and writes only terminal-visible differences where possible.
Built-in Widget Types
| Widget | Builder Name | Description |
|---|---|---|
| Progressbar | ProgressBarBuilder | Horizontal fill bar with configurable value, fill/empty characters, colors, and optional percentage text. |
| Choice | ChoiceBuilder | Keyboard-navigable option list with confirmation state. |
| Input | InputBuilder | Single-line text input with placeholder, cursor movement, and submit state. |
| Canvas | CanvasBuilder | Free-draw surface for pixels, primitives, text, raw buffers, and cached sprites. |
| Text | TextBuilder | Inline text content with runtime foreground/background control. |
| Box | BoxBuilder | Framed container with title, border, and background colors. |
| Divider | DividerBuilder | Horizontal or vertical divider with custom symbol and color. |
| Badge | BadgeBuilder | Compact label with foreground/background palette. |
| Button | ButtonBuilder | Clickable and keyboard-activatable button with consumable press state. |
| Tag | TagBuilder | Chip-style label with configurable brackets and colors. |
| Status | StatusBuilder | IDLE/OK/WARN/ERROR status label with configurable palette. |
| Menu | MenuBuilder | Interactive menu with title, item selection, and activation state. |
| ScrollContainer | ScrollContainerBuilder | Viewport-backed container with virtual content size, offsets, and child attachment helpers. |
| Row | RowBuilder | Horizontal stack layout parent with gap, padding, justify, align, and child slot support. |
| Column | ColumnBuilder | Vertical stack layout parent using the same stack API as Row. |
| SplitPane | SplitPaneBuilder | Two-pane layout with orientation, ratio/pixel split, divider size, and minimum pane sizes. |
| Grid | GridBuilder | Grid layout with fixed and weighted row/column tracks, gaps, padding, and placement overrides. |
| Checkbox | CheckboxBuilder | Toggle with label, checked/disabled state, and consumable changed flag. |
| ListView | ListViewBuilder | Viewport-backed virtual list with selection and activation. |
| TextArea | TextAreaBuilder | Multiline viewport-backed editor with title, placeholder, text, and read-only mode. |
| Dialog | DialogBuilder | Modal dialog with backdrop, focus trapping, body sizing, padding, colors, and close handling. |
Module Map
| Module | Purpose |
|---|---|
| tuix.core.engine | Engine lifecycle, one-frame main loop, loop stats, and mouse capture. |
| tuix.core.scenes | Scene creation, selection, focus, modal state, transactions, stats, and compaction. |
| tuix.core.registry | Active scene pointer and mirrored low-level registry state. |
| tuix.core.builders | Builder constants, layout/grid constants, and standard registration. |
| tuix.core.objects | Object creation plus widget, layout, viewport, and modal runtime APIs. |
| tuix.core.buffers | Buffer hierarchy, z-index, layout slots, grid placement, snapshots, and free operations. |
| tuix.core.input | Input listener and consuming/non-consuming snapshots. |
What Is New In 0.5
- Nested layout contract with TuixLayoutSlot, TuixLayoutRect, parent-first subtree rebuilds, and per-child slot/grid overrides.
- New Row, Column, SplitPane, and Grid builders for native layout composition.
- New Checkbox, ListView, TextArea, and Dialog widgets.
- Scrollable containers now participate in viewport-aware geometry, hitmap, compositor, and input routing.
- Buffer ownership hardening with pixels_owned, safer temporary builder buffers, resize fixes, and teardown fixes.
- Lower render-path lock contention by running builder callbacks outside the global registry lock where snapshots and copies make it safe.
- Python bindings now cover scene selection, transactions, modal activation, mouse capture, layout/grid overrides, richer snapshots, and viewport/widget APIs.
Known Limitations
- TUIX Core remains a low-level engine rather than a high-level application framework.
- No built-in theme/style system beyond per-widget styling.
- The main loop is synchronous; async loop integration is not built in.