TUIX v0.6Beta
TUIX Core v0.6 Overview
A modular terminal UI engine for Python powered by a compiled C + Cython core. v0.6 delivers 13 modular Python packages mirroring the native C directories (`core`, `scene`, `object`, `buffer`, `content_builder`, `command_buffer`, `compositor`, `event`, `input`, `renderer`, `sub_cycles`, `tuix`, `viewport`), removes flat legacy modules, introduces namespaced builder registration, expands Unicode and grapheme-cluster foundations, standardizes TUIX_RC_* return codes, and provides a thread-safe event and command-buffer bridge.
Version 0.6 standardizes native C API naming to the consistent `tuix_system_action` format, hardens buffer ownership and lifecycle tracking, improves rendering diff stability, and provides clean modular Python subpackages.
Core vs FrameworkTUIX Core intentionally provides low-level primitives, direct buffer management, and native rendering control. If using a high-level UI framework built on top of TUIX Core, you can utilize its abstractions directly; our official high-level framework is currently in active development.
Architecture
The runtime is split into three layers: a native C engine for buffers, nested layout, hitmaps, compositing, diffing, symbol interning, and terminal output; a Cython bridge for fast binding calls and frame execution; and modular Python packages for scene lifecycle, object creation, widget configuration, snapshots, and application control.
Each frame routes input, resolves geometry across parent/child trees, lets builders update state and content, composites visible buffers, and writes only terminal-visible differences to stdout.
Built-in Widget Types
| Widget | Builder Constant / Name | Description |
|---|---|---|
| Progressbar | PROGRESS_BAR (ProgressBarBuilder) | Horizontal fill bar with configurable value, fill/empty characters, colors, and optional percentage text. |
| Choice | CHOICE (ChoiceBuilder) | Keyboard-navigable option list with confirmation and selection state. |
| Input | INPUT (InputBuilder) | Single-line text input with placeholder, cursor movement, full UTF-8 codepoint support, and submit state. |
| Canvas | CANVAS (CanvasBuilder) | Free-draw surface for pixels, primitives (lines, rects, circles), grapheme-aware text, raw buffers, and cached sprites. |
| Text | TEXT (TextBuilder) | Inline text content with grapheme-cluster iteration and runtime foreground/background control. |
| ClickableText | CLICKABLE_TEXT (ClickableTextBuilder) | Clickable inline text label with foreground/background colors and consumable pressed state. |
| Box | BOX (BoxBuilder) | Framed container with title, border, and background colors. |
| Divider | DIVIDER (DividerBuilder) | Horizontal or vertical divider with custom symbol and color. |
| Badge | BADGE (BadgeBuilder) | Compact label with foreground/background palette. |
| Button | BUTTON (ButtonBuilder) | Clickable and keyboard-activatable button with consumable press state. |
| Tag | TAG (TagBuilder) | Chip-style label with configurable brackets and colors. |
| Status | STATUS (StatusBuilder) | IDLE/OK/WARN/ERROR status label with configurable palette and safe UTF-8 rendering. |
| Menu | MENU (MenuBuilder) | Interactive menu with title, item selection, and activation state. |
| ScrollContainer | SCROLL_CONTAINER (ScrollContainerBuilder) | Viewport-backed container with virtual content size, offsets, clipping, and child attachment helpers. |
| Row | ROW (RowBuilder) | Horizontal stack layout parent with gap, padding, justify, align, and child slot support. |
| Column | COLUMN (ColumnBuilder) | Vertical stack layout parent using the same stack API as Row. |
| SplitPane | SPLIT_PANE (SplitPaneBuilder) | Two-pane layout with orientation, ratio/pixel split, divider size, and minimum pane sizes. |
| Grid | GRID (GridBuilder) | Grid layout with fixed and weighted row/column tracks, gaps, padding, and placement overrides. |
| Checkbox | CHECKBOX (CheckboxBuilder) | Toggle with label, checked/disabled state, and consumable changed flag. |
| ListView | LIST_VIEW (ListViewBuilder) | Viewport-backed virtual list with selection, activation, and wheel scrolling. |
| TextArea | TEXT_AREA (TextAreaBuilder) | Multiline viewport-backed editor with title, placeholder, cursor navigation, grapheme editing, and read-only mode. |
| Dialog | DIALOG (DialogBuilder) | Modal dialog with backdrop, focus trapping, body sizing, padding, colors, and close handling. |
Module Map (13 Packages)
| Module | Purpose |
|---|---|
| tuix.core.core | Core system lifecycle (`init`, `shutdown`, `main_loop`, `lock`), frame stats, mouse capture, and registry proxy. |
| tuix.core.scene | Scene allocation, selection, focus routing, modal overlays, transactions, activity stats, and pixel compaction. |
| tuix.core.object | Object lifecycle allocation (`create_object`, `get_object_by_uid`), widget runtime APIs, and snapshot inspection. |
| tuix.core.buffer | Buffer hierarchy, z-index ordering, layout slots, grid placement, explicit layout rects, and screen metrics. |
| tuix.core.content_builder | Standard builder registry, builder constants, layout/grid constants, `register_standard()`, and `unregister_builder()`. |
| tuix.core.input | Native input listener thread (`listen`, `stop`), consuming (`get_snapshot`) and peeking (`peek_snapshot`) snapshots, and key injection. |
| tuix.core.command_buffer | Batched command execution opcodes and frame-boundary transaction commits. |
| tuix.core.compositor | Scene compositing, traversal caching, paint-mask-aware partial compositing, hit_map dirtiness, and geometry resolution. |
| tuix.core.event | Thread-safe event queue management and Python callback dispatch bridge. |
| tuix.core.renderer | Streaming ANSI renderer, native buffer allocation, patch rendering, row dirty tracking, and frame performance stats. |
| tuix.core.sub_cycles | Sub-cycle registry allocation, lifecycle management, and transactional OOM handling. |
| tuix.core.tuix | Terminal runtime configuration, probing policy, symbol interning, and pixel cell metadata. |
| tuix.core.viewport | Viewport capability querying, content offset calculation, and scroll insets. |
What Is New In 0.6
- Breaking native API cleanup: normalized C function names and headers to the consistent `tuix_system_action` format across all modules.
- 13 modular Python packages mirroring the native C tree (`core`, `scene`, `object`, `buffer`, `content_builder`, `command_buffer`, `compositor`, `event`, `input`, `renderer`, `sub_cycles`, `tuix`, `viewport`), removing flat legacy root modules.
- Namespaced builder registry: built-in builders live in the `tuix` namespace, descriptors declare ABI version metadata, struct sizes, and pixel ownership policies, and runtime entries track generation and live instances.
- Shared `TUIX_RC_*` return-code system replacing ambiguous status values across public core, scene, buffer, layout, and builder APIs.
- Thread-safe event shim and command-buffer bridge for frame-boundary execution commits and C-to-runtime event flushing.
- Unicode foundation: interned immutable UTF-8 pixel symbols, 128-byte keyboard payload, grapheme-cluster text measurement and rendering, and safe terminal probe-gated wide characters.
- New ClickableTextBuilder widget and updated canonical builder constants (`PROGRESS_BAR`, `SPLIT_PANE`, `LIST_VIEW`, `TEXT_AREA`, `CLICKABLE_TEXT`).
- Core robustness: paint-mask-aware partial compositing, redraw generation tracking, transactional sub-cycle registration on OOM, stale pointer invalidation on scene destruction, and NULL-name safety checks.
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.