| 1 | # Library quality |
| 2 | |
| 3 | Codewhale supplies the visual system; Ratatui supplies the rendering contracts. |
| 4 | The goal is a library you can adopt one component at a time, with predictable |
| 5 | state, readable fallbacks and a small amount of host code. |
| 6 | |
| 7 | ## What we learned from the ecosystem |
| 8 | |
| 9 | | Reference | Useful standard | Applied here | |
| 10 | | --- | --- | --- | |
| 11 | | [Ratatui widget guidance](https://docs.rs/ratatui/latest/ratatui/widgets/) | Widgets render by reference; application state persists independently | Reusable borrowed `Themed` widgets, `dyn Paint` collections and standard stateful list/picker rendering | |
| 12 | | [Ratatui 0.30](https://ratatui.rs/highlights/v030/) and [tui-widgets](https://github.com/ratatui/tui-widgets) | Libraries avoid selecting a consumer's backend and unused features | Ratatui defaults disabled; the examples select Crossterm separately | |
| 13 | | [rat-widget](https://github.com/thscharler/rat-salsa/tree/master/rat-widget) | Focus, selection and scrolling need explicit state and usable input outcomes | Caller-owned states; repeated navigation, deliberate activation and host-shortcut regression checks | |
| 14 | | [ratatui-textarea](https://github.com/ratatui/ratatui-textarea) | Editing deserves dedicated Unicode, paste and boundary handling | Grapheme-safe incremental editing, bounded paste and safe secret-field behavior | |
| 15 | | [tachyonfx](https://github.com/ratatui/tachyonfx) | Effects compose with a host's clock and target rendered cells | Existing host-clock motion, quiet policies and post-paint native ocean treatments | |
| 16 | | [Cargo packaging](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) | Consumers receive source and required assets, rather than a repository dump | Explicit package contents and an independent package-build gate | |
| 17 | |
| 18 | These are engineering references. Native Codewhale components retain their |
| 19 | source appearance; additional compositions remain optional. This comparison |
| 20 | does not establish a market ranking or a performance advantage over those |
| 21 | libraries. |
| 22 | |
| 23 | ## Checks that protect adoption |
| 24 | |
| 25 | - A standalone consumer uses `TestBackend`, borrows widgets, and chooses no |
| 26 | terminal backend. Run `cargo run --locked --manifest-path tests/consumer/Cargo.toml`. |
| 27 | - Public documentation compiles and resolves links: `RUSTDOCFLAGS=-Dwarnings |
| 28 | cargo doc --locked --no-deps`, plus the doctests in the normal test suite. |
| 29 | - Source packages build independently: `cargo package --locked`. Preview |
| 30 | images and local sessions stay in the repository rather than the package. |
| 31 | CI also runs the packaged library's tests, so native assets remain complete. |
| 32 | - CI covers Linux, macOS, Windows and the declared Rust minimum, and rejects |
| 33 | duplicate Ratatui/Crossterm versions. |
| 34 | - Rendering tests cover nonzero origins, partial and empty rectangles, narrow |
| 35 | terminals, Unicode text, all nine capability profiles and all native themes. |
| 36 | - [Rendering benchmarks](BENCHMARKS.md) separate prepared-widget paint cost |
| 37 | from full gallery construction and rendering. Timings are measurements on |
| 38 | your machine, with no flaky wall-clock threshold in CI. |
| 39 | |
| 40 | ## Integration boundaries |
| 41 | |
| 42 | The application owns terminal setup, events, focus, persistence, actions and |
| 43 | time. The kit does not install an event loop or select an async runtime. |
| 44 | `examples/starter.rs` is a small complete app; `examples/showcase.rs` demonstrates |
| 45 | larger compositions and scheduling. Both use the same public components. |
| 46 | |
| 47 | The current API is pre-1.0. The root exports remain available; this quality |
| 48 | pass adds reusable adapters without requiring a rewrite of existing callers. |
| 49 | Use the [component guide](COMPONENTS.md) and [view guide](VIEWS.md) to find the |
| 50 | native source and the corresponding public API. |
| 51 |