SuperLightTUI

SuperLightTUI (SLT) is a Rust-based TUI framework designed with an immediate-mode (closure-based) rendering model. It distinguishes itself from competitors like Ratatui or Textual through several specialized feature sets:

• AI-Native Widgets: Built-in support for AI workflows via widgets like StreamingText, ToolApproval, ContextBar, and StreamingMarkdown.
• Advanced Animation: A dedicated system supporting 5 types (Tween, Spring, Keyframes, Sequence, Stagger) with 9 easings.
• Responsive Layouts: Support for 5 responsive breakpoint tiers (xs, sm, md, lg, xl) applied to 35 properties, similar to CSS media queries.
• Rich Media & Protocols: Built-in support for image protocols (HalfBlock, Kitty, Sixel), syntax highlighting (15 languages via tree-sitter), and terminal protocols like OSC 8 links, OSC 52 clipboard, and OSC 11 color schemes.
• Developer Experience: Features a minimal "3-line start" API, error boundaries (error_boundary()) to catch panics without crashing the app, and a comprehensive testing suite (TestBackend, EventBuilder, proptest).

The documentation is organized by user intent rather than file name. Use the following paths to find what you need:

For rapid application development

If you want to build an app quickly, follow this sequence:

1. Quick Start: Installation, first app, layout, and input.
2. Widgets: A categorized map of available widgets.
3. Patterns: Common composition patterns for building complex UIs.
4. Examples: A collection of runnable example applications.

For backend and runtime development

If you are working on the runtime, backends, or testing infrastructure:

1. Backends: Custom backends, inline mode, static output, and the frame() method.
2. Testing: Using TestBackend, EventBuilder, and snapshots.
3. Debugging: Troubleshooting clipping, focus, and frame behavior.
4. Architecture: Understanding the module map and frame lifecycle.

For AI-assisted development

Use the AI Guide for the fastest path when using AI coding agents or builders.

For library contributors

If you intend to contribute to the SuperLightTUI core:

1. Design Principles: API rules and constraints.
2. Architecture: Module maps and lifecycle.
3. Testing: Contribution standards for testing.
4. Changelog: Reviewing recent changes.

The project is organized into several functional domains. When building custom widgets or extending the library, use this map to locate relevant logic:

• context/: The core engine. Contains core.rs (the Context struct), widget.rs (the Widget trait), container.rs (layout builders), and runtime.rs (hooks, focus, and notifications).
• widgets/: State management for various widget types (e.g., input.rs, collections.rs, selection.rs).
• layout/: The layout engine, including flexbox.rs for size/gap resolution and render.rs for clipping and viewport culling.
• style/: Visual configuration, including color.rs and theme.rs (which includes 10 presets via ThemeBuilder).
• terminal/: Backend implementations for Terminal (full-screen/alternate mode) and InlineTerminal (renders below cursor).
• anim/: Animation primitives like Tween, Spring, and Keyframes.
• chart/: Specialized logic for rendering charts and axes.

SuperLightTUI (SLT) operates on an immediate-mode paradigm. This means you do not manage a persistent tree of components or a message-passing system (like Elm's Model/Update/View). Instead, you provide a closure to slt::run that is executed every single frame.

Key Concepts:

• Frame-based Rendering: Your closure describes what the UI looks like right now. The library handles layout (flexbox), diffing, and writing only changed cells to the terminal.
• State Management:
  • Application State: Store your data in normal Rust variables or structs outside the run closure and mutate them within the closure.
  • Widget-local State: Use ui.use_state(|| ...) hooks for state that should persist specifically for a widget.
• Control Flow: Use standard Rust if and for statements to conditionally show or repeat UI elements.
• Interactivity: Interactive widgets return a Response object. You check properties like .clicked, .hovered, .changed, .focused, or .rect to react to user input.
• Hit-testing: Note that Response.rect uses the layout from the previous frame. Therefore, Response.rect is only reliable from the second frame onward.

To avoid passing read-only application data (like Theme, tick, or user info) through every single function signature, use the provide and use_context pattern. This implements a scoped dependency injection system.

Usage Rules

• ui.provide(value, |ui| ...): Publishes a value to the context stack. The value is only available to widgets rendered within the provided closure. Once the closure returns, the value is popped off the stack.
• ui.use_context::<T>(): Retrieves the nearest provided value of type T. Warning: This will panic if no provider for T is found on the current stack.
• ui.try_use_context::<T>(): Safely attempts to retrieve a value of type T. Returns Option<&T>. Use this in helper functions that might be called outside of a provider (e.g., in tests or isolated components).
• Best Practice: Use provide/use_context for read-only data. For data that requires mutation (like &mut MyState), pass the state explicitly as a parameter.
• Type Requirements: provide boxes the value as dyn Any, so the type T must satisfy the 'static lifetime.

#[derive(Clone, Copy)]
struct AppCtx { theme: Theme, tick: u64, user: &'static str }

fn main() -> std::io::Result<()> {
    slt::run(|ui: &mut Context| {
        let ctx = AppCtx { theme: *ui.theme(), tick: ui.tick(), user: "subin" };

        ui.provide(ctx, |ui| {
            render_header(ui);
        });
    })
}

fn render_header(ui: &mut Context) {
    // Retrieves the context provided in main
    let ctx = *ui.use_context::<AppCtx>();
    ui.text(format!("hi, {}", ctx.user));
}

SuperLightTUI provides several ways to make your UI adapt to light and dark terminal themes.

1. Container-level Overrides

On a ContainerBuilder, you can specify styles that only apply when dark mode is active using .dark_bg() and .dark_border_style().

2. Inline Adaptation with light_dark()

Use ui.light_dark(light_color, dark_color) to pick a color dynamically based on the current theme. This is useful for text colors that need to remain readable.

3. ContainerStyle with Dark Mode

Include .dark_bg() or .dark_border_style() directly in your const ContainerStyle definitions to ensure containers adapt automatically.

use slt::{Border, Color, Style};

// Container-level adaptation
slt::run(|ui| {
    ui.bordered(Border::Rounded)
        .bg(Color::Rgb(248, 250, 252))           // light mode bg
        .dark_bg(Color::Rgb(30, 30, 46))          // dark mode bg
        .dark_border_style(Style::new().fg(Color::Rgb(88, 91, 112)))
        .col(|ui| {
            ui.text("Adapts to dark/light mode");
        });

    // Inline adaptation
    let text_color = ui.light_dark(
        Color::Rgb(15, 23, 42),   // dark text for light mode
        Color::Rgb(205, 214, 244) // light text for dark mode
    );
    ui.text("Adaptive").fg(text_color);
});