teatui/AGENTS.md

TeaTui: Agent Context & Project Overview

Project Summary

TeaTui (Tea = The Elm Architecture) is an experimental Rust framework for building Terminal User Interfaces (TUIs) on top of Ratatui. It reproduces the Elm Architecture (Model-Update-View) to provide a pure functional development experience in Rust.

Tech Stack & Environment

• Language: Rust (Edition 2024).
• Workspace Structure: The project is organized as a workspace containing the core teatui library and an examples directory.
• Core Dependencies:
• ratatui: Used for terminal rendering.
• crossterm: Handles terminal backend and event polling.
• thiserror: Utilized for structured, descriptive error handling across the runtime.

Design Philosophy

• Functional Purity: The goal is to build TUI applications in a pure-functional style, completely removing the usage of &mut and procedural state management.
• Minimal Mutability: Mutability is discouraged in user-provided code; state transitions occur by returning new instances of the Model.
• Message Passing as Side Effects: Communication between internal processes is strictly handled via std::sync::mpsc channels. Message passing is considered the "highest form of side effect" in the design.

Core Architecture

The framework operates through four concurrent actors (threads) that manage the application lifecycle:

1. Model: A single type representing the entire application state.
2. View Actor: Renders the Model into the terminal. It takes a pure function &Model -> Widget and redraws only when the Model changes.
3. Update Actor: Manages state transitions. It takes the current Model and an incoming Message, returning an Update enum (either Update::Exit or Update::Next(NewModel, Option<Effect>)).
4. Effects Actor: Processes side effects (e.g., IO) returned by the Update actor. It can optionally return a Message to trigger further state updates.
5. Event Actor: Translates raw terminal events (via crossterm) into application-specific Messages.

Key Types & Signatures

• Update<M, E>: Enum signaling whether to exit or continue with a new state and optional effect.
• update(model: M, msg: Msg) -> Update<M, E>: The core logic for state changes.
• view(model: &M) -> Widget: The rendering logic.
• effects(model: &M, effect: E) -> Option<Msg>: The side-effect handler.

Development Guide

When extending the framework or building apps with it, ensure that update and view functions remain pure. Any operation involving the "outside world" (files, network, etc.) must be modeled as an Effect and handled within the effects actor.