makeover_tui/

lib.rs

//! The terminal renderer for [`makeover_layout`].
//!
//! <!-- wiki: makeover-tui -->
//!
//! Named for the target and not for ratatui, the same way
//! `makeover-immediate` is named for the mode and not for egui.
//!
//! # What a terminal actually costs you
//!
//! Not colour. That was the original assumption here 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, and the two failures that survive at
//! truecolor are not terminal failures at all: they are the themes whose
//! raised surface is already white, so the lightening clamps and the well
//! lands exactly on its face. Those render identically in a browser.
//! `makeover`'s own `well_is_distinct_from_its_face` test already names them.
//!
//! **What a terminal costs is geometry, and no amount of colour fixes it.**
//! An edge occupies a whole cell on each side. A cell is roughly 8x17 pixels,
//! so a one-pixel bevel becomes something an order of magnitude heavier, which
//! is why [`frame`] hands back a shrunk [`Rect`] instead of pretending the
//! region survived intact. There is nowhere to put a corner radius, so
//! `radius_control` and `radius_container` mean the same thing here. A fill
//! can only begin and end 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.
//!
//! What it does not mean is that the shape inside the cell stops mattering.
//! Half of a cell is still addressable, and a bevel drawn in half-blocks reads
//! as a lit edge where the same bevel in box-drawing reads as a line: `─` and
//! `│` are one stroke through the middle, identical on all four sides, saying
//! nothing about where the light is. Half-blocks also make the two corners
//! where light meets shadow expressible, since a glyph that fills half a cell
//! leaves the other half to the second tone.
//!
//! # Where fidelity does matter
//!
//! At [`Fidelity::Ansi16`] the depth vocabulary collapses outright: a well
//! cannot be filled distinctly on most themes *and* a bevel loses an edge on
//! every one of them, so a raised card and a well both read as a single-tone
//! box. Colour cannot carry the distinction, so [`frame`] carries it with the
//! glyphs instead.
//!
//! Above that, colour carries it and the glyph fallback never fires.
//!
//! [`Palette::shows`] is worth reading correctly in light of the numbers: it
//! 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 precisely when it should.
//!
//! # 0.13.0: a modal, and two cues four ports were about to each invent
//!
//! [`Depth::Overlay`](makeover_layout::Depth::Overlay) arrives in
//! makeover-layout 0.14.0 and needed nothing here: [`Palette::fill`] has
//! answered `Fill::Overlay` since this crate had a palette, so what was missing
//! was the route from a description rather than the drawing. A test asserts it,
//! because a route nothing exercises is one a refactor can quietly lose.
//!
//! [`Theme::selection_on`] and [`Theme::focus_ring`] are the other half, and
//! both are DERIVED rather than authored. Every consumer measured did selection
//! with `REVERSED`, for want of an on-accent foreground; every one that wanted
//! a focus ring either spent makeover's `border-strong` on it, which is a
//! divider at 1.63:1 on Akari Dawn, or derived its own the way `alloy_tui`
//! does. Four terminal ports were each about to answer that separately.
//!
//! Derived, not authored, because the direction is one-way. An authored key can
//! fall back to a derivation and break no theme on disk; a key this crate
//! started requiring would break every theme that lacks it. So the theme format
//! does not change and nothing on disk grows, and the promotion stays available
//! for a theme that ever needs to tune either.
//!
//! # 0.14.0: the first structural widget
//!
//! [`table`] is the first thing here that draws content rather than a surface,
//! and it exists because 14 call sites across `mnw-cli` and `viewer` were
//! already drawing one. `mnw-cli` had written the mapping layer by hand
//! (`src/tui/widgets.rs`: a muted bold header, a selected row carried by the
//! background alone) and `viewer` had written a smaller one, which is two
//! answers to a question this crate is supposed to answer once.
//!
//! It is a mapping layer over [`ratatui::widgets::Table`] rather than a table
//! implementation, because ratatui already lays tracks out, draws a header,
//! highlights a row and scrolls. What it has no answer for is content
//! measurement and narrowing, and those are what the module is.
//!
//! # 0.19.0: `widget` is [`piece`], because the word went to the description
//!
//! `makeover-layout` 0.20.0 added `Region::Widget`, the third tier between a
//! primitive and `Region::Bespoke`: a named assembly of primitives that each
//! renderer draws its own way. That is host-agnostic and sits *above* every
//! renderer.
//!
//! This crate's `widget` module is the opposite end of the same stack —
//! renderer-local, the answer to what a meter looks like in cells, taking a
//! description plus what only a terminal knows. Two different things wearing
//! one word, and the collision would have been worst exactly here, in a crate
//! that has to implement the tier.
//!
//! So this half moved and the description's half kept the word. That direction
//! is not arbitrary: a second or third party naming a widget is naming the
//! layout kind, and nothing outside this tree ever needed a word for a drawing
//! routine. `WidgetStyle` is `PieceStyle`.
//!
//! # 0.27.0: a bar for a bounded number, and an option that is not offered yet
//!
//! `makeover-layout` 0.28.0's form findings, at the renderer that has the bar
//! already. A [`makeover_layout::FieldKind::Range`] is drawn as [`piece::meter`]'s
//! cells with its two ends read out either side, because the ends are what the
//! question means and a terminal is where it would be easiest to quietly show a
//! figure instead. An unbounded range falls back to the text path rather than
//! to bounds this crate invented.
//!
//! `Choice::unavailable` is the one place the three-tone convention's muted is
//! the truth rather than the lie it warns about: that option will not answer,
//! and the reason it will not now sits on its row.
//!
//! `Choice::detail` (makeover-layout 0.39.0) takes a row of its own under the
//! option, inset by the width of the mark and muted for the same reason: the
//! line is not a thing to press. This is the host with the most room of the
//! three -- a browser's `<select>` has to run the line into its option's text
//! and a terminal does not, so it does not.
//!
//! `Field::placeholder` on a chooser, the third finding, is already answered
//! here and needed nothing: this renderer draws every option of a select at
//! once, so an unanswered one is a list with no mark against any row rather
//! than an empty box with nothing in it.
//!
//! # 0.33.0: an interval is one line
//!
//! `makeover-layout` 0.34.0's [`makeover_layout::FieldKind::Interval`], drawn
//! as the low end, the word `to`, and the high end. One line because it is one
//! question: two rows would read as two questions, which is exactly what the
//! kind exists to stop the description saying, and a terminal has no
//! side-by-side boxes to fall back on.
//!
//! - **An open end draws the bound it falls back to**, muted, because that is
//!   where the axis ends rather than a value anybody set. With no bound to fall
//!   back on the end stays blank, which is [`piece::field`]'s standing position
//!   on a value this crate would have to invent.
//! - **The word rather than a dash.** A dash between two numbers is a minus
//!   sign to anyone reading a signed axis, and half the measured axes are
//!   signed: audiofiles filters loudness in dBFS.
//! - The unit rides on each end, through the same `measured` the typed path
//!   uses, so `90 BPM to 130 BPM` reads without the label being consulted.
//!
//! [`piece::Held::Between`] is the second value, for the reason the description
//! states both names: a separator inside one string would make this crate own a
//! delimiter either end could contain.
//!
//! # 0.32.0: a number reads with its unit
//!
//! `makeover-layout` 0.33.0's `Field::unit`, drawn on the value rather than in
//! the label. A terminal has one line the eye is on -- the number -- and the
//! label is a line above it, so `0.05 s` is the reading and `Attack (s)` two
//! rows up is not. A range shows it after the readout beside the bar; a typed
//! number after the value. Every other kind ignores it, and which those are is
//! `FieldKind::measurable`'s answer rather than a `matches!` kept here.
//!
//! # 0.31.0: the bar fills along the curve
//!
//! `makeover-layout` 0.32.0's [`Curve`](makeover_layout::Curve). Where a value
//! sits on the bar is the curve's answer now, not its proportion of the extent.
//! Under `Curve::Linear` those are the same number, so every range drawn before
//! this is unchanged; under a constant ratio they are not, and a bar filled
//! linearly would put an envelope's whole useful half inside its first cell.
//!
//! The two ends beside the bar do not move: they are `f(0)` and `f(1)`, which
//! is what they always were and is now what the description calls them.
//!
//! # The correction this renderer forced
//!
//! [`makeover_layout::Fill`] briefly carried a `fallback` method, returning
//! `Page` for `Well` so a consumer without `surface-well` had something to
//! use. That is an answer for a renderer that can always paint a colour. Here
//! it is actively wrong: page *is* the surface a well is usually cut into, so
//! falling back to it produces the exact invisibility the fallback was meant
//! to avoid.
//!
//! Substituting one intent for another is renderer policy, not description.
//! The fallback moved out of the description and into
//! `makeover-immediate`, where it belongs, which is the first thing a second
//! renderer was built to find.

#![forbid(unsafe_code)]

use makeover_layout::{Bevel, Depth, Edge, Fill};
use ratatui::buffer::Buffer;
use ratatui::layout::Rect;
use ratatui::style::Color;

/// The description this crate renders, re-exported.
///
/// Every entry point here takes a type from it, so a consumer would otherwise
/// have to depend on the description separately and keep two version
/// requirements in step to name the argument it is already being handed.
pub use makeover_layout;

/// A loaded makeover theme, resolved to the colours ratatui draws with.
///
/// Behind the `theme` feature: it is the only thing here that needs `makeover`
/// itself, and that crate embeds the shipped theme files. A consumer that wants
/// [`frame`] and nothing else should not carry them.
#[cfg(feature = "theme")]
pub mod theme;

#[cfg(feature = "theme")]
pub use theme::{Mode, Quantize, Theme, ThemeError};

/// Columns, narrowing, cell parts and the sort caret, over ratatui's own
/// [`Table`](ratatui::widgets::Table).
///
/// Not feature-gated. It needs no theme: [`TableStyle`](table::TableStyle)
/// carries the tones, and a caller with a loaded theme gets them from
/// `TableStyle::from_theme` instead of supplying them.
pub mod table;

/// Word wrapping that answers a height and a drawing from the same measurement.
///
/// The half ratatui's `Paragraph` leaves out. A flow layout asks for rows at a
/// width and then draws into the rect it was given, and if the two disagree by
/// one row a node draws over the one under it.
pub mod text;

/// A meter, a badge, a control, a figure and a form field.
///
/// The pieces below the level [`table`] works at. Not feature-gated, on
/// [`table`]'s footing: [`PieceStyle`](piece::PieceStyle) carries the tones,
/// and a caller with a loaded theme reaches for `PieceStyle::from_theme`.
pub mod piece;

/// How many colours the terminal can actually show.
///
/// Only [`Fidelity::Ansi16`] changes what this crate draws. Above it, colour
/// separates a raised surface from a well on every shipped theme, and the
/// glyph fallback below never fires. Recorded rather than inferred, because a
/// caller that quantised its palette knows the answer and this crate cannot
/// recover it from the colours afterwards.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Fidelity {
    /// Sixteen colours. Depth cannot be carried by colour: a well collapses
    /// onto its face on 18 of 31 themes and a bevel loses an edge on all 31.
    Ansi16,
    /// The 6x6x6 cube and the grey ramp. Enough on 27 of 31 themes.
    Ansi256,
    /// 24-bit. The only failures left belong to the theme, not the terminal.
    #[default]
    TrueColor,
}

impl Fidelity {
    /// Read the terminal's own claim, from `COLORTERM` then `TERM`.
    ///
    /// Deliberately credulous, and the fall-through is where that is decided.
    /// An unrecognised `TERM` is assumed capable, because the two wrong answers
    /// do not cost the same: guessing [`TrueColor`](Self::TrueColor) on a
    /// limited terminal costs some fidelity, and guessing
    /// [`Ansi16`](Self::Ansi16) on a capable one throws away colour the user
    /// paid for — and, for a caller that quantises its palette off this answer,
    /// throws away the whole theme. `COLORTERM` is routinely stripped by ssh
    /// and by multiplexers, so an unrecognised name is the common case rather
    /// than the exotic one: `foot`, `xterm` and `screen` all land here.
    ///
    /// So sixteen colours is reached by naming the terminals that really have
    /// them. The list is short and it does not grow: these are the fixed
    /// consoles, and `TERM=linux` is the case this exists for — the Linux
    /// virtual console, which is what an installer and a machine with no
    /// desktop draw on.
    #[must_use]
    pub fn detect() -> Self {
        Self::from_env(
            &std::env::var("COLORTERM").unwrap_or_default(),
            &std::env::var("TERM").unwrap_or_default(),
        )
    }

    /// [`detect`](Self::detect) with the environment passed in, so the decision
    /// can be tested without mutating a process-wide variable from a parallel
    /// test.
    #[must_use]
    pub fn from_env(colorterm: &str, term: &str) -> Self {
        if colorterm.contains("truecolor") || colorterm.contains("24bit") {
            return Self::TrueColor;
        }
        match term {
            "linux" | "vt100" | "vt220" | "ansi" | "dumb" => Self::Ansi16,
            _ if term.contains("256color") || term.contains("direct") => Self::Ansi256,
            _ => Self::TrueColor,
        }
    }

    /// Whether colour alone can tell a raised surface from a well here.
    #[must_use]
    pub const fn separates_depth(self) -> bool {
        !matches!(self, Self::Ansi16)
    }
}

/// The resolved colours this renderer needs.
///
/// Supply them already quantised to whatever the terminal can show. That is
/// what makes [`Palette::shows`] a plain inequality rather than a colour-space
/// calculation: by the time a colour reaches here, the question of what the
/// terminal will actually paint has been answered.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Palette {
    /// `surface-page`.
    pub page: Color,
    /// `surface-raised`.
    pub raised: Color,
    /// `surface-overlay`.
    pub overlay: Color,
    /// `surface-well`, absent on makeover before 2.3.0.
    pub well: Option<Color>,
    /// `bevel-light`.
    pub bevel_light: Color,
    /// `bevel-dark`.
    pub bevel_dark: Color,
    /// What the terminal can show. Defaults to [`Fidelity::TrueColor`].
    pub fidelity: Fidelity,
}

impl Palette {
    /// Resolve a surface intent, or `None` where this renderer has no colour
    /// for it.
    ///
    /// No substitution happens here. A missing intent stays missing, and
    /// [`frame`] answers it with structure instead of with a different colour.
    /// That rule is what lets the wildcard below be a real answer rather than
    /// a hole: [`Fill`] is `#[non_exhaustive]` from `makeover-layout` 0.4.0
    /// onward, so the description can name a surface this renderer has not
    /// learned to paint, and saying so is better than failing to build.
    #[must_use]
    pub const fn fill(&self, fill: Fill) -> Option<Color> {
        match fill {
            Fill::Page => Some(self.page),
            Fill::Raised => Some(self.raised),
            Fill::Overlay => Some(self.overlay),
            Fill::Well => self.well,
            // Includes Fill::Sunken, which this renderer has no tone for: a
            // terminal cell has one background, so a surface set back by
            // colour alone is not a thing it can say. The chosen tab is drawn
            // forward instead.
            _ => None,
        }
    }

    /// Resolve a bevel edge intent.
    #[must_use]
    pub const fn edge(&self, edge: Edge) -> Color {
        match edge {
            Edge::Light => self.bevel_light,
            Edge::Dark => self.bevel_dark,
        }
    }

    /// Whether painting `fill` over `behind` would show anything.
    ///
    /// The whole of the terminal's problem in one predicate. On a truecolor
    /// terminal this is almost always true; in sixteen colours it is false
    /// often enough that a design relying on fills is a design that vanishes.
    #[must_use]
    pub fn shows(fill: Color, behind: Color) -> bool {
        fill != behind
    }

    /// Whether this palette can express a bevel as two distinct edges.
    ///
    /// Measured, this is the wrong thing to worry about: the two edge colours
    /// never quantise onto each other, at any depth, on any shipped theme.
    /// What does happen is an edge vanishing into the *face* it is drawn on,
    /// on every theme at sixteen colours. Kept because a hand-built palette
    /// can still collide, and cheap to ask.
    #[must_use]
    pub fn two_tone(&self) -> bool {
        self.bevel_light != self.bevel_dark
    }

    /// Whether depth has to be carried by glyphs rather than by colour.
    ///
    /// True when the terminal cannot separate the two surfaces, which is the
    /// sixteen-colour case and nothing else.
    #[must_use]
    pub const fn needs_glyph_depth(&self) -> bool {
        !self.fidelity.separates_depth()
    }
}

/// The characters a frame's edges and corners are drawn with.
///
/// Per side rather than per axis, because the set that reads best as a bevel
/// does not use the same glyph on opposite sides: a half-block edge is only
/// half a cell, and which half it occupies is what says where the edge is.
/// Box-drawing sets fill `top`/`bottom` and `left`/`right` with the same
/// character and lose nothing by it.
///
/// Three sets. [`BEVEL`] is what a terminal that can show two tones gets. The
/// other two exist because at sixteen colours the glyphs are the only thing
/// left to carry depth: a well cannot be filled distinctly and a bevel loses
/// an edge, so a raised card and a well would otherwise be the same
/// single-tone box. A doubled line reads as standing off the page and a light
/// one as cut into it, which is the same claim the fill and the bevel make in
/// colour.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct GlyphSet {
    pub(crate) top: &'static str,
    pub(crate) bottom: &'static str,
    pub(crate) left: &'static str,
    pub(crate) right: &'static str,
    pub(crate) top_left: &'static str,
    pub(crate) top_right: &'static str,
    pub(crate) bottom_left: &'static str,
    pub(crate) bottom_right: &'static str,
    /// Whether the two corners where light meets shadow carry both tones in
    /// one cell, foreground over background.
    ///
    /// Only a half-cell glyph can: it already divides the cell, so the split
    /// costs nothing and the corner reads as a transition rather than as one
    /// edge overrunning the other. A box-drawing corner is a single stroke
    /// with no such division, so those sets say `false` and both shared
    /// corners go to dark — see [`paint_bevel_with`] for why that particular
    /// fallback and not the other one.
    pub(crate) split_corners: bool,
}

/// Half-blocks, which is what a bevel actually wants.
///
/// A cell is roughly 8x17 device pixels, so a half-block along the top and a
/// half-cell column down the side are about the same number of pixels and the
/// edge reads as even thickness. Box-drawing cannot do that: `─` and `│` are
/// both a thin stroke through the middle of the cell, identical on all four
/// sides, which draws a *line* rather than a lit edge and gives up the light
/// model that makes a bevel legible.
///
/// Adopted from `alloy_tui`, which reached this independently and got there
/// first (2026-07-26, two days before this crate existed).
pub(crate) const BEVEL: GlyphSet = GlyphSet {
    top: "▀",
    bottom: "▄",
    left: "▌",
    right: "▐",
    top_left: "▛",
    // The two shared corners are the split ones: an upper half continues the
    // lit top edge while the lower half starts the shaded right edge, and the
    // mirror of that at bottom left.
    top_right: "▀",
    bottom_left: "▄",
    bottom_right: "▟",
    split_corners: true,
};

pub(crate) const LIGHT: GlyphSet = GlyphSet {
    top: "─",
    bottom: "─",
    left: "│",
    right: "│",
    top_left: "┌",
    top_right: "┐",
    bottom_left: "└",
    bottom_right: "┘",
    split_corners: false,
};

pub(crate) const DOUBLE: GlyphSet = GlyphSet {
    top: "═",
    bottom: "═",
    left: "║",
    right: "║",
    top_left: "╔",
    top_right: "╗",
    bottom_left: "╚",
    bottom_right: "╝",
    split_corners: false,
};

/// Paint a two-tone edge around the outside of `area`.
///
/// Light takes the top and left, dark the bottom and right. What happens at
/// the two corners where they meet depends on what the terminal can show.
/// Above sixteen colours the edge is drawn in half-blocks and those corners
/// carry both tones, one per half-cell. At sixteen it is box-drawing, whose
/// single stroke has no half to give, so both shared corners go to dark.
///
/// Costs a cell on each side, which a pixel renderer's bevel does not. Use the
/// [`Rect`] returned by [`frame`] rather than assuming the area is intact.
pub fn paint_bevel(buf: &mut Buffer, area: Rect, bevel: Bevel, palette: &Palette) {
    paint_bevel_with(buf, area, bevel, palette, set_for(palette, None));
}

/// Whether the activity mark is lit, this far into a wait.
///
/// The one place the blink's phase is worked out, so that `piece::activity` can
/// stay a pure drawing and this crate can still hold no clock: the caller says
/// how long the wait has run and gets back which of the two cells to draw.
///
/// The cadence is `makeover_timing::Cadence::Activity`, a half-period, and is
/// deliberately not a number chosen here. Three renderers draw this mark and
/// one of them is a browser running it off a CSS custom property; a terminal
/// that picked its own would be a second heartbeat for one wait.
///
/// **`reduced` returns a lit mark, always.** A reader asking for less motion has
/// asked for the movement to stop, not for the information to go away, which is
/// the whole argument on `makeover_timing::activity_blink`. A terminal has no
/// `prefers-reduced-motion` to read, so the preference arrives as a bool from
/// whatever the host asked its own platform.
///
/// ```
/// use makeover_tui::activity_lit;
/// use std::time::Duration;
///
/// assert!(activity_lit(Duration::from_millis(0), false));
/// assert!(!activity_lit(Duration::from_millis(600), false));
/// assert!(activity_lit(Duration::from_millis(1100), false));
/// // Motion off: lit, and it stays lit.
/// assert!(activity_lit(Duration::from_millis(600), true));
/// ```
#[must_use]
pub fn activity_lit(elapsed: std::time::Duration, reduced: bool) -> bool {
    let Some(half) = makeover_timing::activity_blink(reduced) else {
        return true;
    };
    let half = half.as_millis();
    // A cadence of zero would divide by nothing, which is the one value the
    // token cannot mean. Lit and still is the same answer reduced motion gets.
    if half == 0 {
        return true;
    }
    (elapsed.as_millis() / half).is_multiple_of(2)
}

/// Which glyphs to draw with, given what the terminal can show.
///
/// Above sixteen colours the two tones are available and [`BEVEL`] renders
/// them as light. At sixteen the tones collapse, so the box-drawing sets carry
/// the distinction in weight instead, and `depth` picks which: a doubled frame
/// for a raised card and a light one for everything else. `None` means the
/// caller is drawing a bevel with no depth behind it, which is never the
/// doubled case.
fn set_for(palette: &Palette, depth: Option<Depth>) -> GlyphSet {
    if !palette.needs_glyph_depth() {
        return BEVEL;
    }
    match depth {
        Some(Depth::Raised) => DOUBLE,
        _ => LIGHT,
    }
}

fn paint_bevel_with(buf: &mut Buffer, area: Rect, bevel: Bevel, palette: &Palette, set: GlyphSet) {
    if area.width < 2 || area.height < 2 {
        return;
    }
    let (top_left, bottom_right) = bevel.edges();
    let light = palette.edge(top_left);
    let dark = palette.edge(bottom_right);

    let (x0, y0) = (area.x, area.y);
    let (x1, y1) = (area.right() - 1, area.bottom() - 1);

    // Light first: top edge and left edge, corners included.
    for x in x0..=x1 {
        buf[(x, y0)].set_symbol(set.top).set_fg(light);
    }
    for y in y0..=y1 {
        buf[(x0, y)].set_symbol(set.left).set_fg(light);
    }
    // Dark second, so on a set without split corners the two shared ones land
    // on it by draw order alone.
    for x in x0..=x1 {
        buf[(x, y1)].set_symbol(set.bottom).set_fg(dark);
    }
    for y in y0..=y1 {
        buf[(x1, y)].set_symbol(set.right).set_fg(dark);
    }

    buf[(x0, y0)].set_symbol(set.top_left).set_fg(light);
    buf[(x1, y1)].set_symbol(set.bottom_right).set_fg(dark);

    if set.split_corners {
        // Where light meets shadow, both tones share the cell: the half the
        // glyph fills is the foreground and the half it leaves is the
        // background, so the corner is a transition rather than one edge
        // overrunning the other.
        buf[(x1, y0)]
            .set_symbol(set.top_right)
            .set_fg(light)
            .set_bg(dark);
        buf[(x0, y1)]
            .set_symbol(set.bottom_left)
            .set_fg(dark)
            .set_bg(light);
    } else {
        // Both shared corners to dark. Not arbitrary: it is the same rule
        // `makeover-immediate` produces by drawing its dark polyline second,
        // so a control does not change which corner is lit when it moves
        // between a terminal and a window. A single-stroke corner has no half
        // to give the other tone, so this is the only rule available to these
        // sets anyway.
        buf[(x1, y0)].set_symbol(set.top_right).set_fg(dark);
        buf[(x0, y1)].set_symbol(set.bottom_left).set_fg(dark);
    }
}

/// Draw a region at a given [`Depth`] and return the area left for content.
///
/// The fill is painted only when it would be visible against what is already
/// in the buffer. Everything else is the edge, which is why a well still reads
/// as a well on a terminal that cannot colour one.
pub fn frame(buf: &mut Buffer, area: Rect, depth: Depth, palette: &Palette) -> Rect {
    if area.is_empty() {
        return area;
    }
    let behind = buf[(area.x, area.y)].bg;

    if let Some(color) = depth.fill().and_then(|f| palette.fill(f))
        && Palette::shows(color, behind)
    {
        for y in area.top()..area.bottom() {
            for x in area.left()..area.right() {
                buf[(x, y)].set_bg(color);
            }
        }
    }

    match depth.bevel() {
        Some(bevel) if area.width >= 2 && area.height >= 2 => {
            // Colour separates raised from well wherever it can. Where it
            // cannot, the glyphs do, and only then: a doubled frame on every
            // terminal would be shouting.
            let set = set_for(palette, Some(depth));
            paint_bevel_with(buf, area, bevel, palette, set);
            Rect::new(area.x + 1, area.y + 1, area.width - 2, area.height - 2)
        }
        _ => area,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn palette(well: Option<Color>) -> Palette {
        Palette {
            page: Color::Indexed(7),
            raised: Color::Indexed(15),
            overlay: Color::Indexed(8),
            well,
            bevel_light: Color::Indexed(15),
            bevel_dark: Color::Indexed(0),
            fidelity: Fidelity::TrueColor,
        }
    }

    fn buffer() -> Buffer {
        Buffer::empty(Rect::new(0, 0, 6, 4))
    }

    #[test]
    fn a_well_that_cannot_be_coloured_is_still_drawn() {
        // The 18-of-31 case: no surface-well token at all.
        let p = palette(None);
        let mut buf = buffer();
        frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Well, &p);
        // No fill was available, but the region still reads as recessed.
        assert_eq!(buf[(0, 0)].symbol(), BEVEL.top_left);
        assert_eq!(buf[(0, 0)].bg, Color::Reset);
    }

    #[test]
    fn a_fill_that_matches_its_surroundings_is_not_painted() {
        let p = palette(Some(Color::Indexed(7)));
        let mut buf = buffer();
        // Everything behind is already page-coloured, and the well quantised
        // onto it. Painting it would be a no-op that hides the real problem.
        for y in 0..4 {
            for x in 0..6 {
                buf[(x, y)].set_bg(Color::Indexed(7));
            }
        }
        frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Well, &p);
        assert!(!Palette::shows(Color::Indexed(7), Color::Indexed(7)));
        // The edge is what carries the meaning here.
        assert_eq!(buf[(5, 3)].symbol(), BEVEL.bottom_right);
    }

    #[test]
    fn a_visible_fill_is_painted() {
        let p = palette(Some(Color::Indexed(4)));
        let mut buf = buffer();
        frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Well, &p);
        assert_eq!(buf[(2, 2)].bg, Color::Indexed(4));
    }

    #[test]
    fn an_overlay_is_painted_and_left_unedged() {
        // makeover-layout 0.14.0's Depth::Overlay, and the wiring under it was
        // already here: `Palette::fill` has answered `Fill::Overlay` since this
        // crate had a palette. So this asserts the route rather than building
        // one, and it is the assertion that would catch the route being lost.
        let p = palette(None);
        let mut buf = buffer();
        let inner = frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Overlay, &p);

        assert_eq!(buf[(2, 2)].bg, p.overlay);
        // A surface over the page is separated by the lift and by what sits
        // behind it, so it takes no edge -- and with no edge drawn, nothing is
        // given up to one: the content area is the whole region.
        assert_eq!(buf[(0, 0)].symbol(), " ");
        assert_eq!(inner, Rect::new(0, 0, 6, 4));
    }

    #[test]
    fn the_light_falls_from_the_top_left() {
        let p = palette(None);
        let mut buf = buffer();
        paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised, &p);
        assert_eq!(buf[(0, 0)].fg, p.bevel_light); // top-left
        assert_eq!(buf[(3, 0)].fg, p.bevel_light); // top edge
        assert_eq!(buf[(0, 2)].fg, p.bevel_light); // left edge
        assert_eq!(buf[(5, 3)].fg, p.bevel_dark); // bottom-right
        assert_eq!(buf[(3, 3)].fg, p.bevel_dark); // bottom edge
        assert_eq!(buf[(5, 2)].fg, p.bevel_dark); // right edge
    }

    // Half-cell glyphs divide the cell already, so the corner where light
    // meets shadow can hold both rather than picking one.
    #[test]
    fn the_shared_corners_carry_both_tones_when_the_glyph_can_split() {
        let p = palette(None);
        let mut buf = buffer();
        paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised, &p);
        let top_right = &buf[(5, 0)];
        assert_eq!(top_right.fg, p.bevel_light);
        assert_eq!(top_right.bg, p.bevel_dark);
        let bottom_left = &buf[(0, 3)];
        assert_eq!(bottom_left.fg, p.bevel_dark);
        assert_eq!(bottom_left.bg, p.bevel_light);
    }

    // A single-stroke corner has no half to give the second tone, so the
    // box-drawing sets keep the old rule: both shared corners to dark, which
    // is what makeover-immediate produces by drawing its dark polyline second.
    // Changing that would move the lit corner between a terminal and a window.
    #[test]
    fn box_drawing_corners_stay_dark_and_match_the_immediate_renderer() {
        let p = Palette {
            fidelity: Fidelity::Ansi16,
            ..palette(None)
        };
        let mut buf = buffer();
        paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised, &p);
        assert_eq!(buf[(5, 0)].symbol(), LIGHT.top_right);
        assert_eq!(buf[(5, 0)].fg, p.bevel_dark);
        assert_eq!(buf[(5, 0)].bg, Color::Reset, "a stroke has no second tone");
        assert_eq!(buf[(0, 3)].fg, p.bevel_dark);
    }

    // The whole outline, as a reader sees it. Asserted as glyphs because the
    // shape is the point: an even-weight edge on all four sides, which is what
    // box-drawing could not give.
    #[test]
    fn a_bevel_draws_an_even_outline_and_leaves_the_middle_alone() {
        let p = palette(None);
        let mut buf = Buffer::empty(Rect::new(0, 0, 5, 4));
        paint_bevel(&mut buf, Rect::new(0, 0, 5, 4), Bevel::Raised, &p);
        let rows: Vec<String> = (0..4)
            .map(|y| (0..5).map(|x| buf[(x, y)].symbol()).collect())
            .collect();
        assert_eq!(rows, vec!["▛▀▀▀▀", "▌   ▐", "▌   ▐", "▄▄▄▄▟"]);
    }

    #[test]
    fn pressing_swaps_the_lit_side() {
        let p = palette(None);
        let mut buf = buffer();
        paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised.pressed(), &p);
        assert_eq!(buf[(0, 0)].fg, p.bevel_dark);
    }

    #[test]
    fn a_sixteen_colour_terminal_can_lose_the_second_tone() {
        // Not a failure: one box is still a boundary. The palette says so
        // rather than the renderer pretending otherwise.
        let flat = Palette {
            bevel_dark: Color::Indexed(15),
            ..palette(None)
        };
        assert!(!flat.two_tone());
        assert!(palette(None).two_tone());
    }

    #[test]
    fn an_edge_costs_a_cell_on_every_side() {
        let p = palette(None);
        let mut buf = buffer();
        let inner = frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
        assert_eq!(inner, Rect::new(1, 1, 4, 2));
        // Flat takes no cells, because it draws no edge.
        let same = frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Flat, &p);
        assert_eq!(same, Rect::new(0, 0, 6, 4));
    }

    #[test]
    fn sixteen_colours_carries_depth_in_the_glyphs_instead() {
        // Colour cannot separate raised from well here: the fill collapses on
        // most themes and an edge vanishes on all of them. The frame has to
        // say it some other way or the two become the same box.
        let p = Palette {
            fidelity: Fidelity::Ansi16,
            ..palette(None)
        };
        assert!(p.needs_glyph_depth());
        let mut raised = buffer();
        frame(&mut raised, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
        let mut well = buffer();
        frame(&mut well, Rect::new(0, 0, 6, 4), Depth::Well, &p);
        assert_eq!(raised[(0, 0)].symbol(), DOUBLE.top_left);
        assert_eq!(well[(0, 0)].symbol(), LIGHT.top_left);
        assert_ne!(raised[(0, 0)].symbol(), well[(0, 0)].symbol());
    }

    #[test]
    fn above_sixteen_colours_the_glyphs_stay_out_of_it() {
        // The doubled fallback must not fire where colour already works, or
        // every modern terminal gets a heavier frame it did not need. What it
        // gets instead is the half-block bevel.
        for f in [Fidelity::Ansi256, Fidelity::TrueColor] {
            let p = Palette {
                fidelity: f,
                ..palette(Some(Color::Indexed(4)))
            };
            assert!(!p.needs_glyph_depth());
            let mut buf = buffer();
            frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
            assert_eq!(
                buf[(0, 0)].symbol(),
                BEVEL.top_left,
                "{f:?} got a heavier frame"
            );
            assert_ne!(buf[(0, 0)].symbol(), DOUBLE.top_left);
        }
    }

    // Raised and well are both bevels and differ only in which way they are
    // lit, so above sixteen colours they draw the same glyphs and the tones
    // carry the difference. That is exactly what stops holding at Ansi16, and
    // why the doubled set exists.
    #[test]
    fn colour_alone_separates_raised_from_well_where_it_can() {
        let p = palette(Some(Color::Indexed(4)));
        let mut raised = buffer();
        frame(&mut raised, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
        let mut well = buffer();
        frame(&mut well, Rect::new(0, 0, 6, 4), Depth::Well, &p);
        assert_eq!(raised[(0, 0)].symbol(), well[(0, 0)].symbol());
        assert_eq!(raised[(0, 0)].fg, p.bevel_light);
        assert_eq!(well[(0, 0)].fg, p.bevel_dark);
    }

    #[test]
    fn detection_defaults_generously_and_only_downgrades_on_evidence() {
        assert!(Fidelity::default().separates_depth());
        assert!(Fidelity::TrueColor.separates_depth());
        assert!(Fidelity::Ansi256.separates_depth());
        assert!(!Fidelity::Ansi16.separates_depth());
    }

    // Sixteen colours is reached by naming a console, never by failing to
    // recognise a terminal. `COLORTERM` is stripped by ssh and by every
    // multiplexer, so an unrecognised name carries no evidence at all, and a
    // caller quantising its palette off this answer would flatten a whole theme
    // on the strength of it.
    #[test]
    fn an_unrecognised_terminal_is_assumed_capable() {
        let f = Fidelity::from_env;
        assert_eq!(f("", "foot"), Fidelity::TrueColor);
        assert_eq!(f("", "xterm"), Fidelity::TrueColor);
        assert_eq!(f("", "screen"), Fidelity::TrueColor);
        assert_eq!(f("", ""), Fidelity::TrueColor);
    }

    #[test]
    fn a_console_that_really_has_sixteen_colours_is_named() {
        let f = Fidelity::from_env;
        assert_eq!(f("", "linux"), Fidelity::Ansi16);
        assert_eq!(f("", "vt100"), Fidelity::Ansi16);
        assert_eq!(f("", "dumb"), Fidelity::Ansi16);
    }

    #[test]
    fn a_terminal_naming_its_depth_is_taken_at_its_word() {
        let f = Fidelity::from_env;
        assert_eq!(f("", "xterm-256color"), Fidelity::Ansi256);
        assert_eq!(f("", "screen-256color"), Fidelity::Ansi256);
        assert_eq!(f("", "xterm-direct"), Fidelity::Ansi256);
        // And a claim of 24-bit beats the name, which is only ever a floor.
        assert_eq!(f("truecolor", "xterm-256color"), Fidelity::TrueColor);
        assert_eq!(f("24bit", "linux"), Fidelity::TrueColor);
    }

    #[test]
    fn a_region_too_small_for_an_edge_is_left_alone() {
        let p = palette(None);
        let mut buf = buffer();
        let inner = frame(&mut buf, Rect::new(0, 0, 1, 1), Depth::Raised, &p);
        assert_eq!(inner, Rect::new(0, 0, 1, 1));
    }
}