louie/lib.rs
1//! # Louie — An Agentic-First TUI Framework
2//!
3//! Louie is a terminal user interface framework built from the ground up for
4//! AI agent discoverability. Every widget, layout, and interaction carries
5//! structured metadata that agents can introspect at runtime, enabling
6//! programmatic discovery, inspection, and control of any TUI application.
7//!
8//! ## Architecture
9//!
10//! ```text
11//! ┌─────────────────────────────────────────────────────────┐
12//! │ Agent (AI) Human (keyboard/mouse) │
13//! │ │ │ │
14//! │ ▼ ▼ │
15//! │ ┌─────────┐ ┌───────────┐ │
16//! │ │ agent │ │ event │ │
17//! │ │ protocol │ │ system │ │
18//! │ └────┬─────┘ └─────┬─────┘ │
19//! │ └──────────┬─────────────┘ │
20//! │ ▼ │
21//! │ ┌──────────┐ │
22//! │ │ runtime │ Elm Architecture │
23//! │ │ (Model → │ update → Command → view) │
24//! │ └────┬─────┘ │
25//! │ ▼ │
26//! │ ┌──────────────────────────────┐ │
27//! │ │ widget layer + ontology │ │
28//! │ │ (every widget is │ │
29//! │ │ Discoverable + has schema) │ │
30//! │ └────────────┬─────────────────┘ │
31//! │ ▼ │
32//! │ ┌─────────────────────────┐ │
33//! │ │ terminal (double-buffer │ │
34//! │ │ differential render) │ │
35//! │ └──────────┬──────────────┘ │
36//! │ ▼ │
37//! │ ┌──────────┐ │
38//! │ │ backend │ crossterm / test │
39//! │ └──────────┘ │
40//! └─────────────────────────────────────────────────────────┘
41//! ```
42//!
43//! ## Module Guide
44//!
45//! | Module | Purpose |
46//! |--------|---------|
47//! | [`core`] | Primitives — [`Buffer`](core::buffer::Buffer), [`Cell`](core::cell::Cell), [`Rect`](core::rect::Rect), [`Style`](core::style::Style), [`Text`](core::text::Text) |
48//! | [`widget`] | Visual components — all implement [`Widget`](widget::Widget) and [`Discoverable`](ontology::Discoverable) |
49//! | [`layout`] | Constraint-based space allocation ([`Layout`](layout::Layout), [`Constraint`](layout::Constraint)) |
50//! | [`ontology`] | Agent discoverability — schemas, capabilities, actions, semantic roles |
51//! | [`agent`] | JSON Lines RPC protocol for AI agents to drive apps headlessly |
52//! | [`runtime`] | Elm architecture event loop — [`Model`](runtime::Model), [`Command`](runtime::Command), [`Program`](runtime::Program) |
53//! | [`event`] | Keyboard, mouse, resize, paste, focus, and tick events |
54//! | [`terminal`] | Double-buffered differential rendering via [`Frame`](terminal::Frame) |
55//! | [`backend`] | Backend trait + crossterm and test implementations |
56//! | [`animation`] | Tweens, springs, easing functions, and timelines |
57//! | [`focus`] | Focus ring for ordered widget navigation |
58//! | [`overlay`] | Modal overlay stack with focus capture |
59//!
60//! ## Agent Protocol
61//!
62//! Louie applications can be controlled entirely by AI agents via the
63//! [`agent`] module's JSON Lines protocol over stdin/stdout:
64//!
65//! ```text
66//! Agent → stdin: {"id":"1","request":{"type":"ping"}}
67//! App → stdout: {"success":true,"id":"1","data":{"status":"pong"}}
68//!
69//! Agent → stdin: {"request":{"type":"query_ontology"}}
70//! App → stdout: {"success":true,"data":{...widget catalog...}}
71//!
72//! Agent → stdin: {"request":{"type":"execute_action","agent_id":"editor-1","action":"insert_text","params":{"text":"hello"}}}
73//! App → stdout: {"success":true}
74//! ```
75//!
76//! See [`agent::protocol`] for the full message types and the
77//! [`agent::rpc`] module for the transport implementation.
78//!
79//! ## Feature Flags
80//!
81//! | Flag | Default | Description |
82//! |------|---------|-------------|
83//! | `crossterm` | **yes** | Crossterm terminal backend (disable for headless/agent-only) |
84//! | `bin` | no | Enables `louie-server` and `louie-demo` binaries (pulls in `tracing`) |
85//!
86//! ## Quick Start
87//!
88//! ```rust,no_run
89//! use louie::prelude::*;
90//!
91//! struct App { count: i32 }
92//!
93//! #[derive(Debug)]
94//! enum Msg { Increment, Decrement, Quit }
95//!
96//! impl Model for App {
97//! type Msg = Msg;
98//!
99//! fn update(&mut self, msg: Msg) -> Command<Msg> {
100//! match msg {
101//! Msg::Increment => self.count += 1,
102//! Msg::Decrement => self.count -= 1,
103//! Msg::Quit => return Command::Quit,
104//! }
105//! Command::None
106//! }
107//!
108//! fn view(&self, frame: &mut Frame) {
109//! let area = frame.area();
110//! let text = Text::from(format!("Count: {}", self.count));
111//! frame.render_widget(Paragraph::new(text), area);
112//! }
113//!
114//! fn handle_event(&self, event: Event) -> Option<Msg> {
115//! None
116//! }
117//! }
118//! ```
119
120pub mod agent;
121pub mod animation;
122pub mod backend;
123pub mod core;
124pub mod error;
125pub mod event;
126pub mod focus;
127pub mod layout;
128pub mod ontology;
129pub mod overlay;
130pub mod runtime;
131pub mod terminal;
132pub mod theme;
133#[doc(hidden)]
134pub mod util;
135pub mod widget;
136
137/// Prelude: import everything you need for a typical louie application.
138pub mod prelude {
139 pub use crate::animation::{Animation, Easing, Spring, Timeline, Tween};
140 #[cfg(feature = "crossterm")]
141 pub use crate::backend::crossterm_backend::CrosstermBackend;
142 pub use crate::backend::Backend;
143 pub use crate::core::buffer::Buffer;
144 pub use crate::core::cell::Cell;
145 pub use crate::core::rect::Rect;
146 pub use crate::core::style::{Color, Modifier, Style, Stylize};
147 pub use crate::core::text::{Line, Span, Text};
148 pub use crate::error::{Error, Result};
149 pub use crate::event::{Event, KeyCode, KeyEvent, KeyModifiers, MouseButton, MouseEvent};
150 pub use crate::layout::{Alignment, Constraint, Direction, Layout, Margin};
151 pub use crate::ontology::{
152 AgentAction, AgentCapability, Discoverable, OntologyRegistry, SemanticRole, WidgetSchema,
153 };
154 pub use crate::runtime::{Command, Model, Program};
155 pub use crate::terminal::Frame;
156 pub use crate::theme::{Theme, ThemeToken};
157 pub use crate::widget::block::{Block, BorderType, Borders};
158 pub use crate::widget::gauge::Gauge;
159 pub use crate::widget::list::{List, ListItem, ListState};
160 pub use crate::widget::paragraph::Paragraph;
161 pub use crate::widget::scrollbar::{Scrollbar, ScrollbarState};
162 pub use crate::widget::tabs::Tabs;
163 pub use crate::widget::{StatefulWidget, Widget};
164}