Crate envision 

Envision

A ratatui framework for building TUI applications with first-class support for both interactive terminal use and programmatic control (AI agents, automation, testing).

Two Runtime Modes

Envision provides two distinct ways to run your application:

Terminal Mode - For Interactive Use

// Run in a real terminal with keyboard/mouse input
Runtime::<MyApp>::terminal()?.run()

Virtual Terminal Mode - For Programmatic Control

// Create a virtual terminal
let mut vt = Runtime::<MyApp>::virtual_terminal(80, 24)?;

// Inject events programmatically
vt.send(Event::key(KeyCode::Char('j')));
vt.step()?;

// Inspect the display
println!("{}", vt.display());

The same application code works in both modes - your App implementation doesn’t need to know which mode it’s running in.

The Elm Architecture (TEA)

Envision uses The Elm Architecture pattern:

• State: Your application’s data model
• Message: Events that can update state
• Update: Pure function that produces new state from old state + message
• View: Pure function that renders state to the UI

struct MyApp;

impl App for MyApp {
    type State = MyState;
    type Message = MyMsg;

    fn init() -> (Self::State, Command<Self::Message>) { /* ... */ }
    fn update(state: &mut Self::State, msg: Self::Message) -> Command<Self::Message> { /* ... */ }
    fn view(state: &Self::State, frame: &mut Frame) { /* ... */ }
}

Features

• Capture rendered frames as inspectable text or structured data
• Track frame history and compute diffs between renders
• Annotate widgets with semantic information for accessibility and testing
• Inject events programmatically for automation and AI agents
• Async support with tokio integration for subscriptions and commands
• Component library with common UI elements (buttons, inputs, lists, etc.)
• Theming support for consistent styling

Re-exports

pub use adapter::DualBackend;

pub use annotation::Annotate;

pub use annotation::Annotation;

pub use annotation::AnnotationRegistry;

pub use annotation::WidgetType;

pub use app::App;

pub use app::AsyncCommandHandler;

pub use app::AsyncRuntime;

pub use app::AsyncRuntimeConfig;

pub use app::Command;

pub use app::DebounceSubscription;

pub use app::FilterSubscription;

pub use app::IntervalImmediateSubscription;

pub use app::Runtime;

pub use app::RuntimeConfig;

pub use app::Subscription;

pub use app::SubscriptionExt;

pub use app::TakeSubscription;

pub use app::TerminalEventSubscription;

pub use app::ThrottleSubscription;

pub use app::TickSubscription;

pub use app::TimerSubscription;

pub use backend::CaptureBackend;

pub use backend::EnhancedCell;

pub use backend::FrameSnapshot;

pub use component::Accordion;

pub use component::AccordionMessage;

pub use component::AccordionOutput;

pub use component::AccordionPanel;

pub use component::AccordionState;

pub use component::Breadcrumb;

pub use component::BreadcrumbMessage;

pub use component::BreadcrumbOutput;

pub use component::BreadcrumbSegment;

pub use component::BreadcrumbState;

pub use component::Button;

pub use component::ButtonMessage;

pub use component::ButtonOutput;

pub use component::ButtonState;

pub use component::Checkbox;

pub use component::CheckboxMessage;

pub use component::CheckboxOutput;

pub use component::CheckboxState;

pub use component::Column;

pub use component::Component;

pub use component::Dialog;

pub use component::DialogButton;

pub use component::DialogMessage;

pub use component::DialogOutput;

pub use component::DialogState;

pub use component::Dropdown;

pub use component::DropdownMessage;

pub use component::DropdownOutput;

pub use component::DropdownState;

pub use component::FocusManager;

pub use component::Focusable;

pub use component::InputField;

pub use component::InputFieldState;

pub use component::InputMessage;

pub use component::InputOutput;

pub use component::ListMessage;

pub use component::ListOutput;

pub use component::Menu;

pub use component::MenuItem;

pub use component::MenuMessage;

pub use component::MenuOutput;

pub use component::MenuState;

pub use component::ProgressBar;

pub use component::ProgressBarState;

pub use component::ProgressMessage;

pub use component::ProgressOutput;

pub use component::RadioGroup;

pub use component::RadioGroupState;

pub use component::RadioMessage;

pub use component::RadioOutput;

pub use component::Select;

pub use component::SelectMessage;

pub use component::SelectOutput;

pub use component::SelectState;

pub use component::SelectableList;

pub use component::SelectableListState;

pub use component::SortDirection;

pub use component::Spinner;

pub use component::SpinnerMessage;

pub use component::SpinnerState;

pub use component::SpinnerStyle;

pub use component::StatusBar;

pub use component::StatusBarItem;

pub use component::StatusBarMessage;

pub use component::StatusBarOutput;

pub use component::StatusBarState;

pub use component::StatusBarStyle;

pub use component::TabMessage;

pub use component::TabOutput;

pub use component::Table;

pub use component::TableMessage;

pub use component::TableOutput;

pub use component::TableRow;

pub use component::TableState;

pub use component::Tabs;

pub use component::TabsState;

pub use component::TextArea;

pub use component::TextAreaMessage;

pub use component::TextAreaOutput;

pub use component::TextAreaState;

pub use component::Toast;

pub use component::ToastItem;

pub use component::ToastLevel;

pub use component::ToastMessage;

pub use component::ToastOutput;

pub use component::ToastState;

pub use component::Toggleable;

pub use component::Tooltip;

pub use component::TooltipMessage;

pub use component::TooltipOutput;

pub use component::TooltipPosition;

pub use component::TooltipState;

pub use component::Tree;

pub use component::TreeMessage;

pub use component::TreeNode;

pub use component::TreeOutput;

pub use component::TreeState;

pub use harness::Assertion;

pub use harness::AsyncTestHarness;

pub use harness::Snapshot;

pub use harness::TestHarness;

pub use input::Event;

pub use input::EventQueue;

pub use theme::Theme;

Modules

adapter

Dual adapter for simultaneous real and capture backends.

annotation

Widget annotation system for semantic UI understanding.

app

TEA (The Elm Architecture) application framework.

backend

Backend module providing the CaptureBackend implementation.

component

Composable UI components for TUI applications.

harness

Test harness for headless TUI testing.

input

Input module for terminal events.

prelude

Prelude module for convenient imports

theme

Theming support for Envision components.