Crate bettertui_engine

Expand description

§bettertui_engine

High-performance terminal UI engine written in Rust. The native core of BetterTUI: layout, rendering, text editing, input, animation, terminal emulation, PTY management, font/glyph handling, and syntax highlighting - all in a single dependency.

§What it does

Flexbox layout - Taffy-powered layout engine (flexbox and grid semantics)
Rendering - ANSI output pipeline with framebuffer, painter, render passes, and dirty-region diffing so only changed cells are redrawn
Node tree - arena-allocated render tree with generational indices (no borrow-check fights, cheap inserts/removes)
Text editing - rope-backed buffer with undo/redo, search, wrapping, selection, cursor and viewport management
Input - keyboard parsing, mouse events, focus management and traversal, declarative keybindings
Terminal emulation - embedded VT state machine, terminal capability queries, scrollback buffers
PTY management - spawn and drive pseudo-terminals via portable-pty
Animation - timelines, tweens, easing functions
Fonts and glyphs - font loading/metrics plus built-in NerdFont icon registry generated at build time
Syntax highlighting - tree-sitter grammars for JavaScript, TypeScript, Rust, Python, JSON, HTML, CSS, Bash
Scheduling and events - frame scheduler, event bus, emitters, and a composable event pipeline
Theming - light/dark themes with spacing and border tokens

§Install

[dependencies]
bettertui_engine = "0.1"

§Quick start

Build a small node tree, lay it out, and render one ANSI frame to stdout:

use bettertui_engine::render::Renderer;
use bettertui_engine::taffy::Sizing;
use bettertui_engine::tree::{NodeArena, NodeKind, RenderNode};

fn main() {
    let mut arena = NodeArena::new();

    let root = arena.insert(RenderNode::box_node());
    let label = arena.insert(RenderNode::text("Hello from bettertui_engine"));
    arena.append_child(root, label).unwrap();

    {
        let root_node = arena.get_mut(root).unwrap();
        root_node.layout.width = Some(Sizing::Points(80.0));
        root_node.layout.height = Some(Sizing::Points(24.0));
    }

    let mut renderer = Renderer::new(80, 24);
    let frame = renderer.render(&mut arena);
    print!("{}", String::from_utf8_lossy(&frame.output_data));
}

§Feature flags

Feature	Default	Description
`diagnostics`	yes	Render/frame/cache diagnostic counters. Disable with `default-features = false` for zero-overhead release builds.
`napi`	no	Node.js bindings via napi-rs. Only needed when building the `bettertui_engine.node` addon; not used by pure-Rust consumers.
`production`	no	Convenience alias enabling `release-logs-warn`.
`release-logs-off` / `-error` / `-warn` / `-info` / `-debug`	no	Compile-time log gating; statically removes `tracing` events below the chosen level from release builds. Pick at most one.

§Modules

Module	Purpose
`tree`	Arena-allocated render tree: nodes, colors, styles, traversal
`taffy`	Layout engine integration, layout props/results, render-tree builder
`render`	Renderer, painter, render passes/pipeline, ANSI backend
`framebuffer`	Cell grid with per-cell attributes
`dirty_diff`	Region diffing between frames for partial redraws
`ansi`	Escape-sequence encoding, clipboard OSC sequences
`text`	Rope buffer, editing, undo, search, wrap, selection, cursor, viewport
`input`	Keys, mouse, focus manager, keybindings
`terminal`	VT state machine, capabilities, queries, screen, scrollback, process glue
`pty`	Pseudo-terminal spawning and IO
`animation`	Timelines, tweens, easing
`event_bus` / `event_emitter` / `event_pipeline`	Event distribution primitives
`font` / `glyph`	Font loading, metrics, glyph rasterization support
`graphics` / `graphics_protocol`	Terminal graphics protocol support
`hit_grid`	Hit testing from mouse coordinates to nodes
`logger`	Filtering, formatting, panic hooks, diagnostics
`plugin`	Plugin host, capabilities, slot registry
`protocol`	Command protocol types
`scheduler`	Frame scheduling and pacing
`span_feed`	Styled span streaming
`syntax`	Tree-sitter based syntax highlighting
`theme`	Theme definitions (light/dark), spacing/border tokens
`clock`	Monotonic time source

§Documentation

API reference: https://docs.rs/bettertui_engine
Project home: https://bettertui.dev
Source: https://github.com/localfirstai/bettertui

§Ecosystem

bettertui_engine powers BetterTUI. It works standalone in any pure-Rust project, and the same crate compiles into the Node.js addon used by the npm package @bettertui/core when the optional napi feature is enabled.

§Minimum supported Rust version

Rust 1.88 (edition 2024).

§License

MIT. See LICENSE.

Modules§

animation: Animation engine: easing functions, springs, tweens, keyframes, and animation state management.
ansi: ANSI escape sequence encoding and parsing (CSI, OSC, SGR).
clock
dirty_diff: Dirty region computation: diffs two framebuffers to find changed areas for incremental rendering.
engine: High-level engine API integrating the renderer, event system, and runtime.
event_bus: C-compatible event sink for FFI bindings.
event_emitter: Generic typed event emitter with listener registration and emission.
event_pipeline: Unified event pipeline: raw bytes → AnsiParser → VtMachine → EventQueue.
ffi: C ABI bindings for node:ffi. Every function is extern "C" with #[unsafe(no_mangle)]. Handles are opaque u64 values into global type-safe stores. String returns are *mut c_char (caller must free with ffi_free_string).
font
framebuffer: Frame buffer: cell-based pixel buffer with diff computation and dirty region tracking.
glyph: Glyph system: character classification, glyph caching, metrics, and lookup tables.
graphics: Graphics context for higher-level drawing operations.
graphics_protocol: Pixel-graphics protocol emitters: Kitty graphics, Sixel, and iTerm2 inline images.
hit_grid: Native hit grid for O(1) mouse event targeting.
input: Input system: event model, keyboard, mouse, clipboard, focus management, keybindings, and runtime state.
logger: Logging facade for BetterTUI engine with TypeScript integration.
plugin: Plugin host for lifecycle management and capability negotiation.
protocol: Command protocol layer for communicating with the rendering engine. Defines commands, buffers, processing, and error types.
pty: PTY abstraction: portable pseudo-terminal with process spawning, reading, and writing.
render: Rendering pipeline: objects, painter, renderer, backend, post-process effects.
scheduler: Frame scheduler with priority queue, frame budgeting, and idle/animation callbacks.
span_feed: Zero-copy output streaming via SpanFeed.
syntax
taffy: Layout engine: Taffy-based layout computation with tree synchronization and result mapping.
terminal: Terminal interaction: crossterm-based terminal event handling, queries, and VT emulation.
text: Text engine: buffer, cursor, selection, search, undo, unicode utilities, wrapping, viewport, and styled text.
theme
tree: Tree data structures: arena-backed node tree with layout, style, and visual properties.

Macros§

diag: Run a diagnostic-counter update against the global counters, but ONLY when the diagnostics feature is enabled. When the feature is off this expands to nothing, so counter maintenance imposes zero cost on the render/event hot paths in a maximally-optimized build.

Constants§

VERSION