Architecture
Module Overview
leaf is written in Rust (Edition 2021) and organized into these modules:
| Module | Responsibility |
|---|---|
main.rs | Entrypoint, CLI options, initial document or picker |
cli.rs | Command-line argument definitions |
config.rs | Configuration file loading and defaults |
app/ | Application state (document, TOC, search, pickers, code blocks, links, goto line) |
markdown/ | Parsing, rendering, LaTeX, Mermaid, tables, TOC extraction, frontmatter |
render/ | TUI layout with ratatui (content, popups, status bar, TOC) |
runtime/ | Event loop with mode-aware keyboard.rs and mouse.rs handlers |
theme/ | Theme types, presets, resolution, and TOML deserialization |
editor.rs | Editor detection, classification (terminal vs GUI), and launch |
completions.rs | Shell completion installation for Bash, Zsh, Fish, PowerShell |
clipboard.rs | Cross-platform URL opening and OSC 52 clipboard copy |
inline.rs | Non-interactive stdout rendering (--inline) |
terminal.rs | Raw mode / alternate screen lifecycle |
update.rs | Self-update with SHA256 verification |
Key Dependencies
- ratatui : terminal UI framework
- crossterm : cross-platform terminal handling
- pulldown-cmark : Markdown parsing
- syntect : syntax highlighting
- mmdflux : Mermaid diagram rendering
- unicodeit : LaTeX-to-Unicode conversion
Event Loop
The main event loop in runtime/ runs at ~20 FPS (50ms ticks):
- Process pending picker queue and spawn loading threads
- Poll async file picker loading (non-blocking
try_recv) - Check file changes (watch mode)
- Handle keyboard/mouse input via mode-aware branching (help → pickers → goto line → search → normal)
- Redraw the TUI
- Handle terminal resize (recompute width, reparse Markdown)
Building
cargo build --release
cargo test