Codewhale visual + interaction contract

A normal coding workbench.
One unmistakable whale.

Conversation stays primary. A pod, receipts, context, and settings are there when the work needs them. The surface inherits the terminal that brought it; Deepsea is an explicit atmosphere, not a default wallpaper.

Build target
Ratatui shell + CWC parity
Deepsea is opt-in.

screen

skin

view

Click any bordered surface to inspect its owner, typed state, action, and hitbox contract.

host terminal simulation · background is reset in Ratatui wide 140 × 40

USER14:41:02

Make release 0.9.12 ready.

CODEWHALE14:41:02

I’ll prepare release 0.9.12. Spawning a pod to run checks in parallel.
Plan: fix CI, audit contributor ancestry, draft release notes.

Caution: PR #1427 is marked do-not-merge and is in the integration ancestry.

POD LEDGER launch pod3/3 active

whale	assignment	state	elapsed	receipts	last update
▸ Scout	audit contributor PRs	● working	3m 02s	2	14:44:05
Builder	repair CI	○ waiting	2m 51s	1	14:43:54
Verifier	exact-head checks	✓ done	3m 18s	3	14:44:05

What are we working on?

Folder and tool access are asked when needed.

Quick actions · tab actions · enter choose · esc back

Appearance

Match Terminal is the default. Dark and Light keep a reset background; Deepsea is the only theme that paints water.

Notifications

History is inspectable. Banner, sound, and in-app delivery are separate choices.

What makes it Codewhale

It should feel as legible as Codex, Claude Code, or a sober native workbench before it feels branded. The terminal uses timing, language, a small current of cyan, and a restrained wordmark; surfaces that can render the canonical raster use that exact asset.

Host first

Match Terminal, Dark, and Light use Color::Reset for the background. Their foreground palette adapts; the user’s terminal remains the surface.

Conversation first

The transcript is the default lens. The rail and ledger can fold; receipts are quiet until a person asks for evidence.

One fact, one owner

Context lives in the header. Work lives in the top/rail. Receipts remain at their event. Route, cost, and phase live in the footer.

Deepsea is consent

Only Deepsea paints a deep blue field and underwater points. It stays still when low motion is selected, and it never becomes default wallpaper.

Glow means live

Cyan/gold bloom is a bounded working or completion transition. Settled output is still; color never invents a state without typed evidence.

Everything navigates

Any selectable row has visible focus, a recorded hitbox, keyboard and mouse parity, and an inspect action. No decorative glyph asks to be clicked.

Small whale grammar

The canonical raster mark has no approved terminal-glyph substitute. These glyphs are working notation rather than brand assets, and all retain an ASCII fallback.

⌁

Pod formation

Parallel work beginning. Never a generic button icon.

◌

Wake / live work

Active receipt or a running worker. Static in low-motion and ANSI.

◆

Spout / attention

A real user decision is needed. Gold and words; not an error.

✓ ! ×

Outcome

Passed, caution, failure. Failure red stays reserved for actual failure.

Brand asset rule: the graphic app consumes approved source assets through the brand manifest. Ratatui consumes a tested cell projection from the same manifest. This HTML intentionally does not invent an SVG substitute.

Ratatui wiring manifest

This maps the visual system to the current implementation owners and marks the necessary new projection types. It is deliberately a concrete migration path, not a second runtime or a new turn loop.

surface / fact	owner	typed state / contract	status
Header, context %, phase, route/cost footer	`crates/tui/src/tui/underwater.rs`	`ShellPhase`, `ContextBudgetSnapshot`, `OceanTreatment`; use `palette::grammar::ChromeInk`	existing owner; compose new layout
Foldable work rail, runs, workers	`tui/sidebar.rs` + `tui/work_surface/`	`SidebarAgentRow`, `SidebarSubagentSummary`, `WorkSurfaceState`	existing owner; promote pod hierarchy
Transcript, receipts, composer	`tui/ui.rs` + `tui/app/composer.rs`	`UiSnapshot` (proposed projection), existing transcript records and composer state	add projection only; preserve engine
Pod command + legacy fleet migration	`tui/views/fleet_setup.rs` + protocol/subagent owners	external `/pod`; `/fleet` alias; internal `FleetRole` migrates behind compatibility boundary	one-way product migration
Settings truth and live preview	`tui/views/mod.rs::ConfigView` + `tui/theme_picker.rs`	`SettingFact` proposed: current, effective, startup, saved, authority, apply semantics, editor, availability	replace ambiguous Saved/Session claims
Notifications + settings	`tui/notifications.rs`, `notification_payload.rs`, `sound_policy.rs`	`NotificationRecord` + `DeliveryPlan` proposed; existing `NotificationPayload`/`NotificationKind` retained	in-app, banner, sound independent
Click / keyboard / inspect	`tui/mouse_ui.rs` + each view	`InteractionTarget` proposed registry; every selectable target records `Rect`, focus, action, inspect detail	no visual-only controls
Theme + motion	`tui/theme_picker.rs`, `tui/ocean.rs`, `tui/motion/`	`ThemeId`, `OceanTreatment`, `MotionPolicy::from_settings(low_motion, fancy_animations,…)`	add Deepsea treatment; retain presets
Brand mark	`tui/glyphs.rs` + `tui/underwater.rs`	`BrandMark`/`CellProjection` proposed; approval-gated source asset manifest; ASCII projection	asset approval before full fan-out
Turn lifecycle	`core/engine/turn_loop.rs`	`Engine::run_turn` remains the sole turn loop; no new loop	guarded; do not change
Prompt	`crates/tui/src/prompts/text.rs`	`BASE_PROMPT` untouched	out of scope