# makeover-tui

The terminal renderer for
[`makeover-layout`](https://makenot.work/git/max/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):

| | ANSI-16 | ANSI-256 | truecolor |
|---|---|---|---|
| a well collapses onto its face | 18/31 | 4/31 | 2/31 |
| at least one bevel edge vanishes into its face | 31/31 | 4/31 | 0 |

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.