eye-declare

A declarative inline TUI rendering library for Rust, built on Ratatui.

eye-declare provides a React-like component model for building terminal UIs that render inline — content grows into the terminal's native scrollback rather than taking over the full screen. Designed for CLI tools, AI assistants, and interactive prompts where output accumulates and earlier results should remain visible.

Status

eye-declare is in early development; expect breaking changes.

Coming changes:

• More ergonomic "leaf" API
• Improvements to height measurement and vertical layout

Installation

Add to your project with:

cargo add eye_declare

Quick Start

use eye_declare::{element, Application, ControlFlow, Elements, Spinner, TextBlock};

struct AppState {
    messages: Vec<String>,
    thinking: bool,
}

fn chat_view(state: &AppState) -> Elements {
    element! {
        #(for (i, msg) in state.messages.iter().enumerate() {
            TextBlock {
                Line {
                    Span(text: msg.clone())
                }
            }
        })
        #(if state.thinking {
            Spinner(key: "thinking", label: "Thinking...")
        })
    }
}

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let (mut app, handle) = Application::builder()
        .state(AppState { messages: vec![], thinking: false })
        .view(chat_view)
        .build()?;

    // Send updates from any thread or async task
    tokio::spawn(async move {
        handle.update(|s| s.messages.push("Hello from eye_declare!".into()));
    });

    app.run().await
}

The element! Macro

The element! macro is the primary way to build UIs. It provides JSX-like syntax for composing component trees:

fn dashboard(state: &DashboardState) -> Elements {
    element! {
        VStack {
            "Dashboard"

            #(for (i, item) in state.items.iter().enumerate() {
                Markdown(key: format!("item-{i}"), source: item.clone())
            })

            #(if state.loading {
                Spinner(label: "Refreshing...")
            })

            #(if let Some(ref err) = state.error {
                Markdown(source: err.clone())
            })

            #(footer_view(state))
        }
    }
}

Syntax reference

Syntax	Description
Component(prop: value)	Construct with props (struct field init)
Component { ... }	Component with children
Component(props) { children }	Both
"text"	String literal — auto-wrapped as TextBlock
key: expr	Special prop for stable identity across rebuilds
#(if cond { ... })	Conditional children
#(if let pat = expr { ... })	Pattern-matching conditional
#(for pat in iter { ... })	Loop children
#(expr)	Splice a pre-built Elements value inline

Components

Components are the building blocks. Props live on &self (immutable, set by parent). Internal state lives in the associated State type (mutable, framework-managed via automatic dirty tracking).

use eye_declare::Component;
use ratatui_core::{buffer::Buffer, layout::Rect, style::Style, widgets::Widget};
use ratatui_widgets::paragraph::Paragraph;

#[derive(Default)]
struct StatusBadge {
    pub label: String,
    pub color: Color,
}

impl Component for StatusBadge {
    type State = (); // no internal state needed

    fn render(&self, area: Rect, buf: &mut Buffer, _state: &()) {
        let line = Line::from(Span::styled(&self.label, Style::default().fg(self.color)));
        Paragraph::new(line).render(area, buf);
    }
}

Then use it in a view:

element! {
    StatusBadge(label: "Online", color: Color::Green)
}

Composite Components

Components can generate child trees via the children() method. The slot parameter carries externally-provided children (like React's props.children):

#[derive(Default)]
struct Card {
    pub title: String,
}

impl Component for Card {
    type State = ();

    fn children(&self, _state: &(), slot: Option<Elements>) -> Option<Elements> {
        let mut els = Elements::new();
        els.add(TextBlock::new().line(&self.title, heading_style));
        if let Some(children) = slot {
            els.group(children); // slot children rendered here
        }
        Some(els)
    }

    fn content_inset(&self, _state: &()) -> Insets {
        Insets::all(1) // 1-cell border chrome
    }

    fn render(&self, area: Rect, buf: &mut Buffer, _state: &()) {
        // draw border chrome; children render inside the inset area
    }
}

Usage with element!:

element! {
    Card(title: "My Card") {
        Spinner(label: "Loading...")
        "Some content"
    }
}

Three patterns:

• Pass through (default) — VStack, HStack accept external children as-is
• Generate own tree — a Spinner builds its own frame + label layout internally
• Wrap slot — a Card wraps external children in a header + border

Lifecycle Hooks

Components declare effects via lifecycle(). The framework manages registration and cleanup:

impl Component for Timer {
    type State = TimerState;

    fn lifecycle(&self, hooks: &mut Hooks<TimerState>, _state: &TimerState) {
        if self.running {
            hooks.use_interval(Duration::from_secs(1), |s| s.elapsed += 1);
        }
        hooks.use_mount(|s| s.started_at = Instant::now());
        hooks.use_unmount(|s| println!("Timer ran for {:?}", s.started_at.elapsed()));
    }

    // ...
}

Available hooks:

Hook	Fires when
use_interval(duration, handler)	Periodically, at the given duration
use_mount(handler)	Once, after the component is first built
use_unmount(handler)	Once, when the component is removed
use_autofocus()	Requests focus when the component mounts
provide_context(value)	Makes a value available to all descendants
use_context::<T>(handler)	Reads a value provided by an ancestor

Context

The context system lets ancestor components provide typed values to their descendants without prop-drilling. This is the primary mechanism for connecting components to app-level services.

Root-level context — register values on the application builder:

let (mut app, handle) = Application::builder()
    .state(MyState::default())
    .view(my_view)
    .with_context(event_sender)       // available to all components
    .with_context(AppConfig::new())   // multiple types supported
    .build()?;

Component-level context — provide and consume in lifecycle:

// Provider: makes a value available to descendants
fn lifecycle(&self, hooks: &mut Hooks<MyState>, _state: &MyState) {
    hooks.provide_context(self.theme.clone());
}

// Consumer: reads a value from an ancestor
fn lifecycle(&self, hooks: &mut Hooks<MyState>, _state: &MyState) {
    hooks.use_context::<Theme>(|theme, state| {
        state.current_theme = theme.cloned();
    });
}

The use_context handler always fires with Option<&T> — None if no ancestor provides the type. Inner providers shadow outer providers of the same type within their subtree.

Layout

Vertical stacking is the default. HStack provides horizontal layout with width constraints:

use eye_declare::{Elements, HStack, Column, TextBlock};
use eye_declare::WidthConstraint::Fixed;

fn two_column_view(state: &MyState) -> Elements {
    element! {
        HStack {
            Column(width: Fixed(20)) {
                TextBlock {
                    #(for line in state.lines {
                        Line {
                            Span(text: line)
                        }
                    })
                }
            }
            Column {
                // Fill: takes remaining space
                TextBlock {
                    #(for line in state.content_lines {
                        Line {
                            Span(text: line)
                        }
                    })
                }
            }
        }
    }
}

Components can declare content_inset() for borders and padding — children render inside the inset area while the component draws chrome in the full area.

Reconciliation

Elements are matched by key (stable identity) or position (implicit). State is preserved across rebuilds when nodes are reused:

element! {
    // Keyed: survives reordering, state preserved by key
    #(for msg in &state.messages {
        Markdown(key: format!("msg-{}", msg.id), source: msg.content.clone())
    })

    // Positional: matched by index + type
    "Footer"
}

Application

Application owns your state and manages the render loop. Handle sends updates from any thread or async task:

let (mut app, handle) = Application::builder()
    .state(MyState::new())
    .view(my_view)
    .build()?;

// Non-interactive: exits when handle is dropped and effects stop
app.run().await?;

// Component-driven interactive: raw mode with context-based event handling
// Components handle their own events and dispatch app-domain actions via channels
app.run_loop().await?;

// Raw interactive: direct access to terminal events (escape hatch)
app.run_interactive(|event, state| {
    // handle terminal events, mutate state
    ControlFlow::Continue
}).await?;

Multiple handle updates between frames are batched into a single rebuild.

Terminal Options

The builder supports configuring terminal protocols for interactive modes:

Application::builder()
    .state(state)
    .view(view)
    .ctrl_c(CtrlCBehavior::Deliver)         // route Ctrl+C to components (default: Exit)
    .keyboard_protocol(KeyboardProtocol::Enhanced)  // kitty protocol (default: Legacy)
    .bracketed_paste(true)                   // distinguish pastes from typing (default: false)
    .build()?;

Option	Default	Description
ctrl_c	Exit	Exit intercepts Ctrl+C; Deliver routes it to components
keyboard_protocol	Legacy	Enhanced enables kitty protocol for key disambiguation
bracketed_paste	false	Delivers pasted text as Event::Paste(String)

Committed Scrollback

For long-running apps, content that scrolls into terminal scrollback can be evicted from state via an on_commit callback:

Application::builder()
    .state(state)
    .view(view)
    .on_commit(|committed, state| {
        // `committed.key` identifies which element scrolled off
        state.messages.remove(0);
    })
    .build()?;

This is an opt-in performance optimization. Without it, the framework handles all content normally.

Imperative API

For direct control over the render loop, use InlineRenderer:

use eye_declare::{InlineRenderer, Spinner, VStack, TextBlock};

let mut renderer = InlineRenderer::new(width);
let spinner_id = renderer.push(Spinner::new("Loading..."));

// Mutate state, render, write to stdout
std::thread::sleep(Duration::from_millis(100));
renderer.tick();
let output = renderer.render();
stdout.write_all(&output)?;

// Declarative subtrees via rebuild
let container = renderer.push(VStack);
renderer.rebuild(container, element! {
    "Hello"
});

See the terminal_demo and lifecycle examples for complete sync event loop patterns.

Built-in Components

Component	Description
TextBlock	Styled text with display-time word wrapping. Supports Line/Span children for multi-styled lines.
Spinner	Animated Braille spinner with auto-tick. Shows a checkmark when .done().
Markdown	Headings, bold, italic, inline code, code blocks, and lists.
VStack	Vertical container — children stack top-to-bottom.
HStack	Horizontal container — children lay left-to-right with WidthConstraint-based layout.

Examples

cargo run --example chat            # Interactive chat with streaming
cargo run --example app             # Application wrapper with Handle updates
cargo run --example declarative     # View function pattern with element! macro
cargo run --example lifecycle       # Mount/unmount lifecycle hooks
cargo run --example interactive     # Focus, Tab cycling, text input
cargo run --example terminal_demo   # Sync imperative API with InlineRenderer
cargo run --example agent_sim       # Multi-component agent simulation
cargo run --example markdown_demo   # Markdown rendering showcase
cargo run --example growing         # Dynamically growing content
cargo run --example nested          # Nested component trees
cargo run --example wrapping        # Word wrapping and resize behavior

Architecture

Application        State + view function + async event loop
  InlineRenderer   Rendering, reconciliation, layout, diffing, scrollback
    ratatui-core   Buffer, Cell, Style, Widget primitives
    crossterm      Terminal I/O, event types

Inline rendering model

eye-declare uses an inline rendering model — content grows downward into the terminal's native scrollback, like standard CLI output. This is fundamentally different from full-screen TUI frameworks (ratatui's Terminal, tui-realm, cursive) that redraw a fixed viewport.

The tradeoff is deliberate. Inline rendering is the right model for AI assistants, build tools, and interactive prompts where output accumulates and earlier results should persist in scrollback for the user to review.

How it works:

1. Reconciliation matches new elements against existing nodes by key or position. State is preserved when nodes are reused, so animations continue seamlessly and internal component state survives rebuilds.

2. Layout measures each node's desired height (with word wrapping computed at render time) and allocates widths for horizontal containers. Content insets allow components to declare border/padding chrome while children render inside.

3. Rendering produces a Ratatui Buffer for each frame. The InlineRenderer diffs against the previous frame and emits only changed cells as ANSI escape sequences, wrapped in DEC synchronized output (?2026h/l) to prevent tearing.

4. Growth is handled by emitting newlines to claim new terminal rows before writing content. Old rows naturally scroll into terminal scrollback.

Scrollback handling: When content height exceeds the terminal height, the terminal scrolls rows into scrollback. The framework tracks terminal height and filters diff output to only address visible rows. The on_commit callback provides an additional optimization by evicting committed content from application state entirely.

Crate Structure

crates/
  eye_declare/         Main library
  eye_declare_macros/  element! proc macro

The macro is behind the macros feature flag (enabled by default).

License

MIT