| 1 | # Codewhale terminal components |
| 2 | |
| 3 | The current Codewhale TUI is the source for native components, layout, |
| 4 | backgrounds and ombré. Extract the existing presentation into public Ratatui |
| 5 | APIs; keep application data, actions and persistence in the host. Optional |
| 6 | compositions can explore useful alternatives without changing the native |
| 7 | baseline. [VIEWS.md](VIEWS.md) inventories the terminal screens. |
| 8 | |
| 9 | ## The water |
| 10 | |
| 11 | `OceanColumn` adapts the existing Underwater treatment from |
| 12 | `CodeWhale/crates/tui/src/tui/ocean.rs` at |
| 13 | `a79ce5c4d5ed1a5f7032185710c27343a900351c`: |
| 14 | |
| 15 | | Position | Ground | |
| 16 | |---|---| |
| 17 | | Surface | `#102A45` | |
| 18 | | Middle | `#0A1E33` | |
| 19 | | Deep | `#061320` | |
| 20 | |
| 21 | One absolute vertical column connects the workspace, transcript and composer. |
| 22 | It does not restart inside each widget. Caller-reported waiting and approval |
| 23 | add the native warm cast; failure stays steady; completion breathes and settles. |
| 24 | Selections, elevated panels, diffs and code retain their own backgrounds. |
| 25 | The caller supplies phase, context percentage, motion policy and elapsed time. |
| 26 | Use `OceanColumn::viewport` for the shell bounds and `apply_matching` for each |
| 27 | native chrome band's base ground. Keep elevated and semantic surfaces outside |
| 28 | those bands; the finishing pass preserves their fills. |
| 29 | The field only paints measured dark truecolor Ocean; other profiles retain |
| 30 | their selected native or token grounds. The native light palettes keep their own grounds. |
| 31 | |
| 32 | `Ombre` offers additional artistic treatments over completed component buffers: |
| 33 | Ocean uses the logo's blue pair, Lagoon uses Live into Primary, Dusk uses Primary |
| 34 | into Attention, Coral uses Danger into Attention, and Graphite maps the actual |
| 35 | desktop graphite grounds. These are spatial materials, never alternative state |
| 36 | colors. Paper uses pale washes. The finishing pass preserves glyphs, foregrounds, |
| 37 | content fills and caller colors, and keeps a text cell's original background |
| 38 | whenever a replacement cannot preserve its contrast floor. All fallback |
| 39 | profiles pass through unchanged. |
| 40 | |
| 41 | ## Work has priority |
| 42 | |
| 43 | The default native layout has no permanent top header or right sidebar. |
| 44 | Conversation, pending input, the rounded composer, posture, workflow progress, |
| 45 | metrics and workbar form one vertical layout. The workbar has Tasks, Fleet, |
| 46 | Jobs, Files, Notes, Context, Git and Cost, with optional top and side placement. |
| 47 | Its row facts and keyboard outcomes belong to the caller. |
| 48 | |
| 49 | Native palette slots retain their separate Working, Success, Warning, |
| 50 | permission and mode colors. Marks and words preserve meaning under no color |
| 51 | or ASCII. Narrow surfaces shed secondary information before essential input, |
| 52 | permission and model/context information. |
| 53 | |
| 54 | `WorkspaceFrame`, `ContextRibbon`, author-heading messages, desktop-style |
| 55 | cards and the extra `Ombre` palettes are optional compositions. They are not |
| 56 | substitutes for the TUI baseline. |
| 57 | |
| 58 | ## Life and motion |
| 59 | |
| 60 | The C-shaped Codewhale is the same character as the native client. The |
| 61 | `whale_motion` core adapts its existing pure Rust springs, authored clips, |
| 62 | props, particles, scene and cove, rather than adding another performance model. |
| 63 | Provenance and selected conformance fixtures live in |
| 64 | [assets/whale-motion](assets/whale-motion/PROVENANCE.md). |
| 65 | |
| 66 | One session-scoped `Stage` receives explicit owner inputs and advances on the |
| 67 | host's clock. Changing session resets the performance. Hiding a surface stops |
| 68 | painting; resuming discards missed motion. Terminal cadence is capped at six |
| 69 | paints per second in action and two at rest. Reduced motion uses the authored |
| 70 | poster. The compact view always keeps readable state words. |
| 71 | |
| 72 | Braille has one foreground per cell. The colored adapter samples native ink at |
| 73 | visible dots, chooses the majority shape, and resolves ties by paint order. |
| 74 | The monochrome packed geometry remains an independent conformance oracle. |
| 75 | The studio paints the character after the water, using the optional |
| 76 | `paint_with_contrast` floor of 3:1 for decorative ink. It mixes only insufficient |
| 77 | inks toward the theme foreground; ordinary `paint` retains native ink exactly. |
| 78 | Fish, rare jellyfish and bubbles occupy open water around text; their bounded |
| 79 | populations and caller-clock motion settle under reduced or still policies. |
| 80 | |
| 81 | ## Host boundaries and verification |
| 82 | |
| 83 | Components own paint and local presentation geometry. The host owns Engine |
| 84 | events, permission decisions, queue mutation, Markdown parsing, clipboard, |
| 85 | link navigation, persistence and the event loop. `Transcript` accepts typed |
| 86 | authored blocks; `CodeBlock` keeps original source separate from safe display. |
| 87 | |
| 88 | The live showcase and captured previews use the same renderer. Every catalog |
| 89 | entry is exported in nine terminal profiles and included in the generated |
| 90 | README's dark and light boards. Tests cover clipping, Unicode, safe display, |
| 91 | color fallbacks, motion lifecycle and canonical native geometry. Hosted CI |
| 92 | checks source, snapshots and media hashes. These checks establish library |
| 93 | behavior. Engine adoption is separate work. |
| 94 |