|
| 1 | +# cTUI - AGENTS.md |
| 2 | + |
| 3 | +## OVERVIEW |
| 4 | + |
| 5 | +High-performance Rust TUI framework with React-style declarative components. Pure Rust, zero unsafe code. Async-first with Tokio runtime. |
| 6 | + |
| 7 | +## STRUCTURE |
| 8 | + |
| 9 | +``` |
| 10 | +cTUI/ |
| 11 | +├── ctui-core/ # Rendering primitives, Buffer, Cell, Component trait |
| 12 | +├── ctui-components/ # 27 pre-built widgets (Block, Input, List, Table...) |
| 13 | +├── ctui-layout/ # Flexbox-inspired layout engine |
| 14 | +├── ctui-animate/ # Easing, keyframes, spring physics |
| 15 | +├── ctui-theme/ # Built-in themes + theming system |
| 16 | +├── ctui-macros/ # #[component] proc-macro |
| 17 | +├── ctui-cli/ # Project scaffolding CLI |
| 18 | +├── ctui-tests/ # Integration test harness |
| 19 | +├── benches/ # Criterion benchmarks |
| 20 | +└── examples/ # counter, todo, dashboard, file_explorer, animation |
| 21 | +``` |
| 22 | + |
| 23 | +## WHERE TO LOOK |
| 24 | + |
| 25 | +| Need | Location | |
| 26 | +|------|----------| |
| 27 | +| Component trait / lifecycle | `ctui-core/src/component.rs` | |
| 28 | +| Buffer rendering | `ctui-core/src/buffer/` | |
| 29 | +| Input handling | `ctui-core/src/event.rs` | |
| 30 | +| Widget implementations | `ctui-components/src/{widget}.rs` | |
| 31 | +| Layout algorithms | `ctui-layout/src/flex.rs`, `grid.rs` | |
| 32 | +| Animation easing | `ctui-animate/src/easing.rs` | |
| 33 | +| Theme presets | `ctui-theme/src/theme.rs` | |
| 34 | +| Benchmarks | `benches/ratatui_baseline.rs` | |
| 35 | + |
| 36 | +## KEY ABSTRACTIONS |
| 37 | + |
| 38 | +### Component Trait (Elm Architecture) |
| 39 | +```rust |
| 40 | +trait Component { |
| 41 | + type Props; // Configuration (builder pattern) |
| 42 | + type State; // Internal state |
| 43 | + fn create(props: Self::Props) -> Self; |
| 44 | + fn render(&self, area: Rect, buf: &mut Buffer); |
| 45 | + fn update(&mut self, msg: Box<dyn Msg>) -> Cmd; |
| 46 | + fn on_mount(&mut self) {} |
| 47 | + fn on_unmount(&mut self) {} |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +### Widget Trait (Stateless) |
| 52 | +```rust |
| 53 | +trait Widget { |
| 54 | + fn render(&self, area: Rect, buf: &mut Buffer); |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +### Layout Snippet |
| 59 | +```rust |
| 60 | +Layout::flex() |
| 61 | + .direction(FlexDirection::Row) |
| 62 | + .justify_content(JustifyContent::SpaceBetween) |
| 63 | + .gap(1) |
| 64 | + .split(area, &constraints) |
| 65 | +``` |
| 66 | + |
| 67 | +### Animation Snippet |
| 68 | +```rust |
| 69 | +KeyframeAnimation::new() |
| 70 | + .keyframe(Keyframe::new(0.0, 0.0)) |
| 71 | + .keyframe(Keyframe::new(1.0, 100.0)) |
| 72 | + .duration_ms(1000) |
| 73 | + .playback_mode(PlaybackMode::Loop) |
| 74 | +``` |
| 75 | + |
| 76 | +## COMMANDS |
| 77 | + |
| 78 | +```bash |
| 79 | +cargo test --workspace --all-features # Run all 1079 tests |
| 80 | +cargo clippy --workspace -- -D warnings # Lint check |
| 81 | +cargo bench # Criterion benchmarks |
| 82 | +cargo run --example counter # Run example |
| 83 | +cargo doc --workspace --open # View docs |
| 84 | +ctui new my-app --template counter # Scaffold project |
| 85 | +``` |
| 86 | + |
| 87 | +## BENCHMARKS |
| 88 | + |
| 89 | +Target: >=10% faster than ratatui baseline |
| 90 | +- Buffer operations: 64-136% improvement |
| 91 | +- Buffer diff: 35% faster |
| 92 | +- Paragraph render: 20% faster |
| 93 | + |
| 94 | +## CRATE DEPENDENCY GRAPH |
| 95 | + |
| 96 | +``` |
| 97 | +ctui-core (foundation, no deps) |
| 98 | +├── ctui-components -> ctui-core |
| 99 | +├── ctui-layout -> ctui-core |
| 100 | +├── ctui-animate -> ctui-core |
| 101 | +├── ctui-theme -> ctui-core |
| 102 | +└── ctui-macros (proc-macro, standalone) |
| 103 | +``` |
| 104 | + |
| 105 | +## NOTES |
| 106 | + |
| 107 | +- ~43k lines Rust, 1079 tests across workspace |
| 108 | +- CI: blacksmith-4cpu-ubuntu-2204 runner |
| 109 | +- Lints: `#![deny(unsafe_code)]`, clippy pedantic + nursery |
| 110 | +- Release profile: LTO + opt-level 3 |
| 111 | +- Snapshot testing via insta crate |
0 commit comments