makeover-tui

The terminal renderer for makeover-layout, on ratatui.

Named for the target and not for the library, the same way makeover-immediate is named for the mode and not for egui.

What a terminal actually costs you

Not colour. That was this crate's original assumption and it is wrong on any terminal built this decade. Measured across the 31 shipped themes (makeover's well_fidelity example):

The threshold is 256, not 24-bit. The two failures surviving at truecolor are not terminal failures: they are the themes whose raised surface is already white, so the lightening clamps and the well lands on its face. Those render identically in a browser, and makeover already asserts them.

What a terminal costs is geometry. An edge occupies a whole cell per side, and a cell is roughly 8x17 pixels, so a one-pixel bevel becomes an order of magnitude heavier. frame returns a shrunk Rect rather than pretending the region survived. There is nowhere to put a corner radius, so radius_control and radius_container mean the same thing here. A fill begins and ends on a cell boundary.

That is the constraint worth designing against. It does not improve, it is not detectable, and it applies equally to the best terminal ever written.

Where fidelity matters

At Fidelity::Ansi16 the depth vocabulary collapses: a well cannot be filled distinctly on most themes and a bevel loses an edge on all of them, so a raised card and a well both read as one single-tone box. Colour cannot carry the distinction, so frame carries it with the glyphs, doubling the frame for a raised surface and leaving a well light. Above sixteen colours that fallback never fires, which is tested, because a doubled frame on every modern terminal would be shouting.

Fidelity::detect() reads COLORTERM then TERM and is deliberately credulous. A terminal that understates itself costs a slightly heavier frame; a terminal that overstates itself was going to render wrongly whatever this crate assumed.

Palette::shows is not a low-colour workaround. It is a correctness check that a fill will be visible against what is behind it, and at truecolor it fires on exactly the two clamping themes, which is when it should.

The correction it forced

makeover-layout::Fill briefly carried a fallback, returning Page for Well so a consumer without surface-well had something to paint. That is an answer for a renderer that can always paint an exact colour. Here it is actively wrong: the page is usually the surface a well is cut into, so falling back to it produces precisely the invisibility the fallback existed to prevent.

Substituting one intent for another turned out to be renderer policy rather than description. It moved out of makeover-layout and into makeover-immediate, which does want it. That is the first thing a second renderer was built to find, and it took a day rather than the API-window's usual 48 hours after adoption.

Status

On crates.io at 0.1.0. No consumer yet: alloy_tui and shop are the intended first ones, both of which already take makeover and makeover-geometry from the registry.

Design lives in the wiki note makeover-tui; the backlog is in GoingsOn under the project of the same name.

Licence

MIT.