# tui-splitflap
Ratatui widget crate for retro split-flap display boards.
## Key Decisions
- Sequential: each step = `flip_speed_ms`, total = `distance * flip_speed_ms`
- Mechanical: total = `flip_speed_ms` regardless of distance
- Combined: same total as Sequential, first step is mechanical animation
- At `elapsed=0` display = settled; first char appears at `elapsed=flip_speed_ms`
- Mechanical animation: split char on center column only (borders preserved)
- `FlapCell` stores `mechanical_frames: Option<u8>` to derive phase/interrupt without FlipStyle
- Stagger by column index (`col_idx * stagger_ms`)
- `FlapBoard` accepts optional `Block` for outer container (ratatui idiom)
- Normal cells render with `┌─┐│ │└─┘` box-drawing borders within the 3×3 tile
- `FlapTheme` is `#[non_exhaustive]` with builder API (`fg`, `bg`, `tile_bg`, `split_fg`, `border_fg`)
- Default charset includes variant glyphs (Ð, Ɨ, Ᵽ, Ɍ, Ŧ, Ʉ, Ɏ, Ƶ) after their base letters for mid-rotation illusion
- `CharSet` uses `Arc<[char]>` — accepts `&'static [char]` or `Vec<char>` for runtime charsets
- No per-cell color — departures pane uses separate single-row boards per status for colored remarks
- `FlapBoardState::cell()` returns `Option<&FlapCell>` — bounds-safe access
- `FlapBoard::new()` and `FlapTheme::new()` kept alongside `Default` — Ratatui builder idiom; `Widget::new().prop(...)` reads correctly, `default().prop(...)` does not
- `FlapCell::{set_target, tick, reset}` and `CharSet::{sanitize, step_forward}` are `pub(crate)` — mutation/step APIs not intended for direct use; board state drives them
- `pub type Result<T>` and `CharSetError` re-exported at crate root — `CharSet::new` is the only fallible surface
## Crate Structure
```
src/
lib.rs char_set.rs cell.rs
state.rs widget.rs theme.rs
widget.ingredient.rs ← pantry ingredients (feature-gated)
tests/
integration.rs ← public API usage examples (9 tests)
examples/
demo.rs ← interactive demo with mode/speed/theme toggles
widget_preview/main.rs ← cargo pantry entry point
.github/workflows/
ci.yml ← fmt check, clippy, cargo test, cargo test --features pantry
```