Crate saorsa_core 

saorsa-core: A retained-mode, CSS-styled terminal UI framework.

This crate provides the core rendering pipeline, layout engine, CSS styling system, and widget infrastructure for building rich terminal user interfaces.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  (Widget tree, CSS styles, reactive signals & bindings)     │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                  Layout Engine (Taffy)                      │
│  TCSS → ComputedStyle → taffy::Style → computed rects       │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│               Widget Rendering System                       │
│  Widget::render() → Vec<Segment> → Lines of styled text     │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│          Compositor (Layers, Z-ordering, Clipping)          │
│  Base layer + overlays → CompositorRegion → final buffer    │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│         Renderer (Differential, SGR optimization)           │
│  ScreenBuffer → DeltaBatch → optimized escape sequences     │
└─────────────────────────────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────┐
│               Terminal Backend (Crossterm)                  │
│  Raw mode, cursor control, alternate screen, events         │
└─────────────────────────────────────────────────────────────┘

Core Subsystems

• TCSS Parser: CSS-like styling with variables, pseudo-classes, and themes
• Layout Engine: Flexbox and grid layout via Taffy, scroll management
• Reactive System: Signal-based state with computed values, effects, and bindings
• Compositor: Layer-based rendering with z-ordering, clipping, and overlays
• Widget Library: Rich set of data, text, and UI widgets (tables, trees, markdown, etc.)
• Renderer: Double-buffered differential rendering with SGR optimization

Key Types

• Segment: Fundamental rendering unit (styled text + control flags)
• Cell: Single terminal cell (grapheme cluster + style + display width)
• ScreenBuffer: Double-buffered grid of cells with delta tracking
• Widget: Trait for renderable UI components
• Signal<T>: Reactive state container with automatic dependency tracking
• Compositor: Manages layers and composition into final screen buffer

Re-exports

pub use buffer::CellChange;

pub use buffer::ScreenBuffer;

pub use cell::Cell;

pub use color::Color;

pub use compositor::Compositor;

pub use compositor::CompositorError;

pub use compositor::CompositorRegion;

pub use compositor::Layer;

pub use cursor::CursorPosition;

pub use cursor::CursorState;

pub use cursor::Selection;

pub use error::Result;

pub use error::SaorsaCoreError;

pub use event::Event;

pub use event::KeyCode;

pub use event::KeyEvent;

pub use event::Modifiers;

pub use event::MouseEvent;

pub use focus::FocusManager;

pub use focus::FocusState;

pub use focus::WidgetId;

pub use geometry::Position;

pub use geometry::Rect;

pub use geometry::Size;

pub use highlight::HighlightSpan;

pub use highlight::Highlighter;

pub use highlight::NoHighlighter;

pub use highlight::SimpleKeywordHighlighter;

pub use layout::Constraint;

pub use layout::Direction;

pub use layout::Dock;

pub use layout::Layout;

pub use layout::LayoutEngine;

pub use layout::LayoutError;

pub use layout::LayoutRect;

pub use layout::OverflowBehavior;

pub use layout::ScrollManager;

pub use layout::ScrollState;

pub use overlay::OverlayConfig;

pub use overlay::OverlayId;

pub use overlay::OverlayPosition;

pub use overlay::Placement;

pub use overlay::ScreenStack;

pub use reactive::Binding;

pub use reactive::BindingDirection;

pub use reactive::BindingExpression;

pub use reactive::BindingId;

pub use reactive::BindingScope;

pub use reactive::Computed;

pub use reactive::Effect;

pub use reactive::OneWayBinding;

pub use reactive::PropertySink;

pub use reactive::ReactiveScope;

pub use reactive::Signal;

pub use reactive::TwoWayBinding;

pub use reactive::batch;

pub use reactive::batch;

pub use render_context::RenderContext;

pub use renderer::DeltaBatch;

pub use renderer::Renderer;

pub use renderer::batch_changes;

pub use renderer::build_sgr_sequence;

pub use segment::Segment;

pub use style::Style;

pub use terminal::CrosstermBackend;

pub use terminal::MultiplexerKind;

pub use terminal::Terminal;

pub use terminal::TerminalCapabilities;

pub use terminal::TerminalInfo;

pub use terminal::TerminalKind;

pub use terminal::TestBackend;

pub use terminal::detect;

pub use terminal::detect_multiplexer;

pub use terminal::detect_terminal;

pub use terminal::merge_multiplexer_limits;

pub use terminal::profile_for;

pub use text::TextConfig;

pub use text::expand_tabs;

pub use text::filter_control_chars;

pub use text::preprocess;

pub use text::string_display_width;

pub use text::truncate_to_char_boundary;

pub use text::truncate_to_display_width;

pub use text_buffer::TextBuffer;

pub use undo::EditOperation;

pub use undo::UndoStack;

pub use viewport::Viewport;

pub use widget::Alignment;

pub use widget::BorderStyle;

pub use widget::Checkbox;

pub use widget::Collapsible;

pub use widget::Column;

pub use widget::Container;

pub use widget::DataTable;

pub use widget::DiffMode;

pub use widget::DiffView;

pub use widget::DirectoryTree;

pub use widget::EventResult;

pub use widget::IndicatorStyle;

pub use widget::Label;

pub use widget::LoadingIndicator;

pub use widget::MarkdownRenderer;

pub use widget::Modal;

pub use widget::OptionList;

pub use widget::ProgressBar;

pub use widget::ProgressMode;

pub use widget::RadioButton;

pub use widget::RichLog;

pub use widget::SelectList;

pub use widget::Sparkline;

pub use widget::StaticWidget;

pub use widget::Switch;

pub use widget::Tab;

pub use widget::TabBarPosition;

pub use widget::Tabs;

pub use widget::TextArea;

pub use widget::Toast;

pub use widget::ToastPosition;

pub use widget::Tooltip;

pub use widget::Tree;

pub use widget::TreeNode;

pub use widget::Widget;

pub use wrap::WrapLine;

pub use wrap::WrapResult;

pub use wrap::line_number_width;

pub use wrap::wrap_line;

pub use wrap::wrap_lines;

Modules

buffer

Screen buffer — a 2D grid of terminal cells.

cell

Cell type — a single terminal cell.

color

Color types for terminal rendering.

compositor

Compositor — resolves overlapping widget layers into a flat cell grid.

cursor

Cursor position and selection types for text editing.

error

Error types for saorsa-core.

event

Event types for terminal input handling.

focus

Focus management for widget navigation.

geometry

Geometry primitives: Position, Size, Rect.

highlight

Pluggable syntax highlighting trait and default implementations.

layout

Layout system for splitting terminal areas.

overlay

Overlay management for modal dialogs, toasts, and tooltips.

reactive

Reactive primitives for automatic UI updates.

render_context

Render context — manages the frame lifecycle and rendering pipeline.

renderer

ANSI escape sequence renderer.

segment

Segment type — the fundamental rendering unit.

style

Text style type for terminal rendering.

tcss

Terminal CSS (TCSS) parser and stylesheet types.

terminal

Terminal abstraction for backend-agnostic rendering.

text

Text preprocessing — tab expansion and control character filtering.

text_buffer

Text buffer with rope-based storage for efficient text editing.

undo

Undo/redo stack for text editing operations.

viewport

Viewport — scrollable region with content clipping.

widget

Widget traits and built-in widgets.

wrap

Soft-wrap logic for splitting logical lines into visual lines.