blockworx/shell/

flex.rs

//! Flexbox for the shell: the vocabulary every surface lays its contents out
//! with, and the inspector that says where the boxes actually went.
//!
//! `docs/taffy-layout-playbook.md` §6 and §8. [`glass`](super::glass) places a
//! box against the frame; this lays out what is inside it. The vocabulary is
//! shared so no two surfaces can disagree about what "the growing middle"
//! means — the whole reason the engine is worth having beyond fidelity.
//!
//! Every node is created through [`Named`] and carries a `&'static str` name.
//! The names are what the overlay and [`dump`] print; without them a layout
//! bug is a wall of anonymous rectangles.
#![allow(
    dead_code,
    reason = "P1 delivers the vocabulary before P2-P4 consume it; the allow \
              goes when the first surface migrates"
)]

use egui_taffy::taffy;
use egui_taffy::taffy::prelude::{auto, length, percent};
use egui_taffy::{TuiBuilderLogic, TuiWidget, tui};

use crate::bounded::{Bounded, Bounds};

pub use egui_taffy::Tui;

/// Passes egui must be allowed per frame for the engine to work.
///
/// `egui_taffy` sizes a node from the *previous* pass and calls
/// `request_discard` while the tree is dirty (playbook §4.1), so a
/// single-pass frame would paint the layout it was about to correct.
pub const MAX_PASSES: core::num::NonZeroUsize = core::num::NonZeroUsize::MIN.saturating_add(2);

pub struct PointBounds;

impl Bounds for PointBounds {
    const MIN: f32 = 0.0;
    const MAX: f32 = f32::INFINITY;
}

/// A length in egui points — a gap, a padding, a fixed side. Non-negative:
/// flexbox has no such thing as a gap below zero, so the type refuses one
/// rather than every constructor guarding against it.
pub type Points = Bounded<PointBounds>;

impl Points {
    pub const ZERO: Self = Self::new(0.0);
}

/// How much of the [`egui::Ui`] a [`surface`] root claims. `egui_taffy`
/// defaults to min-content on both axes, so a root that fills has to say so —
/// and the same answer decides whether the root is `width: 100%`.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Room {
    Width,
    Height,
    Both,
}

impl Room {
    fn spans_width(self) -> bool {
        matches!(self, Room::Width | Room::Both)
    }

    fn spans_height(self) -> bool {
        matches!(self, Room::Height | Room::Both)
    }
}

/// One box's flex specification, named for what it means in the shell rather
/// than for the CSS it compiles to. Built by the constructors below and
/// narrowed with the combinators, so the two sides of every split are named
/// rather than measured.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Flex(taffy::Style);

/// `display:flex; align-items:center; gap:<gap>` — the prototype's `.row`, and
/// the default for anything laid out left to right.
pub fn row(gap: Points) -> Flex {
    line(taffy::FlexDirection::Row, taffy::AlignItems::Center, gap)
}

/// `.row.rev`: the same row, aligned to the top, for a body that is taller
/// than the glyph beside it.
pub fn row_start(gap: Points) -> Flex {
    line(taffy::FlexDirection::Row, taffy::AlignItems::FlexStart, gap)
}

/// `flex-direction:column` with a gap.
pub fn stack(gap: Points) -> Flex {
    line(
        taffy::FlexDirection::Column,
        taffy::AlignItems::Stretch,
        gap,
    )
}

/// `.tags`: a row that flows onto the next line rather than shrinking its
/// chips.
pub fn wrap(gap: Points) -> Flex {
    let mut flex = line(taffy::FlexDirection::Row, taffy::AlignItems::FlexStart, gap);
    flex.0.flex_wrap = taffy::FlexWrap::Wrap;
    flex
}

/// `flex:1; min-width:0` — the middle that takes what the sides leave, and
/// shrinks below its content rather than pushing them off the end.
pub fn grow() -> Flex {
    Flex::default().grow()
}

/// `flex:none` — a lead glyph, a trailing readout, a cluster of controls.
pub fn fixed() -> Flex {
    Flex::default().fixed()
}

/// `.topbar .center`: a growing middle whose contents stay centred in it
/// however much room the sides leave. `egui::containers::Sides` cannot say
/// this, and it is the clearest single case for the engine.
pub fn centre(gap: Points) -> Flex {
    row(gap).grow().centred()
}

/// `.tool`, `.av`: a fixed square with one thing centred in it.
pub fn cell(side: Points) -> Flex {
    row(Points::ZERO).fixed().square(side).centred()
}

/// `.meta`: a fixed column whose lines are flush right.
pub fn trailing(gap: Points) -> Flex {
    let mut flex = stack(gap).fixed();
    flex.0.align_items = Some(taffy::AlignItems::FlexEnd);
    flex
}

/// `.sheetbody`: the growing column that scrolls its own overflow. Scrolling
/// is a node property here, never an `egui::ScrollArea` wrapped round the
/// tree (playbook §4.4).
pub fn scrolling() -> Flex {
    stack(Points::ZERO).grow().scrolls()
}

fn line(direction: taffy::FlexDirection, align: taffy::AlignItems, gap: Points) -> Flex {
    Flex(taffy::Style {
        display: taffy::Display::Flex,
        flex_direction: direction,
        align_items: Some(align),
        gap: length(f32::from(gap)),
        ..Default::default()
    })
}

impl Flex {
    /// `flex:1; min-width:0`.
    pub fn grow(mut self) -> Self {
        self.0.flex_grow = 1.0;
        self.0.flex_shrink = 1.0;
        self.0.flex_basis = length(0.0);
        self.0.min_size.width = length(0.0);
        self
    }

    /// `flex:none`.
    pub fn fixed(mut self) -> Self {
        self.0.flex_grow = 0.0;
        self.0.flex_shrink = 0.0;
        self.0.flex_basis = auto();
        self
    }

    /// `justify-content:center; align-items:center` — the prototype's
    /// `place-items:center`, which for a single child is the same box.
    pub fn centred(mut self) -> Self {
        self.0.justify_content = Some(taffy::JustifyContent::Center);
        self.0.align_items = Some(taffy::AlignItems::Center);
        self
    }

    pub fn min_height(mut self, points: Points) -> Self {
        self.0.min_size.height = length(f32::from(points));
        self
    }

    pub fn width(mut self, points: Points) -> Self {
        self.0.size.width = length(f32::from(points));
        self
    }

    pub fn height(mut self, points: Points) -> Self {
        self.0.size.height = length(f32::from(points));
        self
    }

    pub fn square(self, side: Points) -> Self {
        self.width(side).height(side)
    }

    pub fn pad(mut self, points: Points) -> Self {
        self.0.padding = length(f32::from(points));
        self
    }

    /// `overflow-y:auto`, which `egui_taffy` builds the scroll area for. The
    /// cross axis clips: a column that scrolls sideways as well is a layout
    /// bug wearing a scrollbar.
    pub fn scrolls(mut self) -> Self {
        self.0.overflow = taffy::Point {
            x: taffy::Overflow::Clip,
            y: taffy::Overflow::Scroll,
        };
        self
    }

    fn spanning(mut self, room: Room) -> Self {
        if room.spans_width() {
            self.0.size.width = percent(1.0);
        }
        if room.spans_height() {
            self.0.size.height = percent(1.0);
        }
        self
    }

    pub fn style(&self) -> &taffy::Style {
        &self.0
    }
}

impl From<Flex> for taffy::Style {
    fn from(flex: Flex) -> taffy::Style {
        flex.0
    }
}

/// A flexbox root over `ui`, filling as much of it as `room` says.
///
/// `name` is both the inspector's label and the root's `egui::Id`, so two live
/// roots in one frame must not share one — duplicate root ids *panic*
/// (playbook §4). Every chrome piece is its own `egui::Area`, so one name per
/// piece is enough.
pub fn surface<T>(
    ui: &mut egui::Ui,
    name: &'static str,
    room: Room,
    style: Flex,
    add: impl FnOnce(&mut Tui) -> T,
) -> T {
    let _span = tracing::info_span!("taffy_layout", surface = name).entered();
    let root = tui(ui, egui::Id::new(name));
    let root = match room {
        Room::Width => root.reserve_available_width(),
        Room::Height => root.reserve_available_height(),
        Room::Both => root.reserve_available_space(),
    };
    root.style(style.spanning(room).into())
        .show(|tui| recorded(name, tui, add))
}

/// The shell's node constructors: everything laid out through this module is
/// named, so the inspector has something to say.
pub trait Named<'r>: TuiBuilderLogic<'r> {
    /// A box that holds other boxes.
    fn node<T>(self, name: &'static str, style: Flex, add: impl FnOnce(&mut Tui) -> T) -> T {
        self.style(style.into()).add(|tui| recorded(name, tui, add))
    }

    /// A box that answers a click as a whole — a list row, where the target is
    /// the row and not the words in it.
    fn pressable<T>(
        self,
        name: &'static str,
        style: Flex,
        add: impl FnOnce(&mut Tui) -> T,
    ) -> egui_taffy::TuiInnerResponse<T> {
        self.style(style.into())
            .clickable(|tui| recorded(name, tui, add))
    }

    /// A leaf drawn with an ordinary egui closure. Its size is what the
    /// closure allocated, so this is the wrong door for text that wraps —
    /// [`Named::text`] is that one.
    ///
    /// The rect the inspector gets is the box inside the node's padding and
    /// border, where a container's is the box outside them.
    fn leaf<T>(self, name: &'static str, style: Flex, draw: impl FnOnce(&mut egui::Ui) -> T) -> T {
        self.style(style.into()).ui(|ui| {
            record(ui.ctx(), name, ui.max_rect());
            draw(ui)
        })
    }

    /// A widget the crate measures itself. The recorded rect is the widget's
    /// own, not the node's box: a leaf gives no closure to read the box from,
    /// and reaching into the layout tree deadlocks it.
    fn widget<W>(self, name: &'static str, style: Flex, widget: W) -> egui::Response
    where
        W: TuiWidget<Response = egui::Response>,
    {
        let response = self.style(style.into()).ui_add(widget);
        record(&response.ctx, name, response.rect);
        response
    }

    /// Text that wraps at the width its node was given.
    ///
    /// The only correct door for it: a hand-rolled `ui` closure reports
    /// `ui.min_size()`, which for wrapping text is the narrowest it can
    /// possibly be — one letter per line — while the crate's own `Label`
    /// measurement asks the galley (playbook §12, 2026-09-08).
    fn text(
        self,
        name: &'static str,
        style: Flex,
        text: impl Into<egui::WidgetText>,
    ) -> egui::Response {
        self.widget(name, style, egui::Label::new(text).wrap())
    }
}

impl<'r, B: TuiBuilderLogic<'r>> Named<'r> for B {}

/// Enter `name` at this node's box, run its contents, leave again. One place,
/// so a root, a container and a click target cannot disagree about what the
/// inspector is told.
fn recorded<T>(name: &'static str, tui: &mut Tui, add: impl FnOnce(&mut Tui) -> T) -> T {
    let ctx = tui.egui_ctx().clone();
    enter(&ctx, name, tui.taffy_container().full_container());
    note_overflow(
        &ctx,
        name,
        tui.taffy_container(),
        tui.current_style().overflow,
    );
    let inner = add(tui);
    leave(&ctx);
    inner
}

/// One node as this pass laid it out.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Node {
    pub name: &'static str,
    /// Nesting under the [`surface`] root, which is zero.
    pub depth: usize,
    pub rect: egui::Rect,
}

/// What the last pass laid out, in the order the tree was walked.
pub fn nodes(ctx: &egui::Context) -> Vec<Node> {
    read(ctx, |recording| recording.nodes.clone())
}

/// The computed tree as indented text: name, where it landed, how big it is.
/// The console half of §8 — an edit-and-re-run loop, and what makes a layout
/// bug reportable.
pub fn dump(ctx: &egui::Context) -> String {
    use std::fmt::Write as _;

    let (nodes, overflowing) = read(ctx, |recording| {
        (recording.nodes.clone(), recording.overflowing.clone())
    });
    let mut out = String::new();
    for node in nodes {
        let rect = node.rect;
        let flag = if overflowing.contains(node.name) {
            "  OVERFLOWS"
        } else {
            ""
        };
        let _ = writeln!(
            out,
            "{:indent$}{} at ({:.0}, {:.0}) {:.0}x{:.0}{flag}",
            "",
            node.name,
            rect.left(),
            rect.top(),
            rect.width(),
            rect.height(),
            indent = node.depth * 2,
        );
    }
    out
}

/// Every node whose content has outgrown its box since the app started.
pub fn overflowing(ctx: &egui::Context) -> Vec<&'static str> {
    read(ctx, |recording| {
        recording.overflowing.iter().copied().collect()
    })
}

/// The layout overlay and its console chord (§8.1, §8.4): each node's computed
/// rect as a one-pixel outline tinted by depth, with the node's name over it.
#[cfg(feature = "ui_debug")]
pub fn inspect(ctx: &egui::Context, theme: &crate::theme::Theme) {
    use crate::theme::Role;

    const BY_DEPTH: [Role; 3] = [Role::LayoutBox0, Role::LayoutBox1, Role::LayoutBox2];
    let dump_chord = egui::KeyboardShortcut::new(
        egui::Modifiers::COMMAND | egui::Modifiers::SHIFT,
        egui::Key::L,
    );
    if ctx.input_mut(|input| input.consume_shortcut(&dump_chord)) {
        println!("{}", dump(ctx));
    }

    let painter = ctx.layer_painter(egui::LayerId::new(
        egui::Order::Debug,
        egui::Id::new("flex_inspector"),
    ));
    for node in nodes(ctx) {
        if !node.rect.is_positive() {
            continue;
        }
        let tint = theme.resolve(BY_DEPTH[node.depth % BY_DEPTH.len()]);
        painter.rect_stroke(
            node.rect,
            egui::CornerRadius::ZERO,
            egui::Stroke::new(1.0, tint),
            egui::StrokeKind::Inside,
        );
        painter.text(
            node.rect.left_top(),
            egui::Align2::LEFT_TOP,
            node.name,
            egui::FontId::monospace(7.0),
            theme.resolve(Role::LayoutName),
        );
    }
}

/// Where the frame's nodes are collected. One buffer per `egui::Context`.
fn buffer() -> egui::Id {
    egui::Id::new("blockworx::shell::flex")
}

#[derive(Clone, Default)]
struct Recording {
    /// Cleared whenever this changes, so the buffer holds one pass rather than
    /// every pass since the app started. Discards perturb the counter, which
    /// is a hazard for arithmetic on it (playbook §4.2) but not for asking
    /// whether it moved.
    pass: u64,
    depth: usize,
    nodes: Vec<Node>,
    /// Named once and remembered, so a node that overflows every frame says so
    /// once. Survives the per-pass clear for that reason.
    overflowing: std::collections::BTreeSet<&'static str>,
}

/// Read what has been recorded. Never rolls the pass: the tree is read back
/// after the frame that drew it has ended, by which time the counter has
/// already moved on.
fn read<T>(ctx: &egui::Context, act: impl FnOnce(&Recording) -> T) -> T {
    ctx.data_mut(|data| act(data.get_temp_mut_or_default::<Recording>(buffer())))
}

/// Record into this pass's buffer, emptying it first if the pass has turned
/// over since the last node was written.
fn write<T>(ctx: &egui::Context, act: impl FnOnce(&mut Recording) -> T) -> T {
    let pass = ctx.cumulative_pass_nr();
    ctx.data_mut(|data| {
        let recording = data.get_temp_mut_or_default::<Recording>(buffer());
        if recording.pass != pass {
            recording.pass = pass;
            recording.depth = 0;
            recording.nodes.clear();
        }
        act(recording)
    })
}

/// A rect a node has not been laid out into yet is NaN, which paints nowhere
/// and sorts nowhere.
fn placed(rect: egui::Rect) -> egui::Rect {
    if rect.any_nan() {
        egui::Rect::ZERO
    } else {
        rect
    }
}

fn record(ctx: &egui::Context, name: &'static str, rect: egui::Rect) {
    write(ctx, |recording| {
        recording.nodes.push(Node {
            name,
            depth: recording.depth,
            rect: placed(rect),
        });
    });
}

fn enter(ctx: &egui::Context, name: &'static str, rect: egui::Rect) {
    record(ctx, name, rect);
    write(ctx, |recording| recording.depth += 1);
}

fn leave(ctx: &egui::Context) {
    write(ctx, |recording| {
        recording.depth = recording.depth.saturating_sub(1);
    });
}

/// §8.5: silent overflow is the failure mode hand-rolled layout had, and the
/// one most likely to survive the migration unnoticed. A node that clips or
/// scrolls is *meant* to overflow and is not reported.
#[cfg(debug_assertions)]
fn note_overflow(
    ctx: &egui::Context,
    name: &'static str,
    container: &egui_taffy::TaffyContainerUi,
    overflow: taffy::Point<taffy::Overflow>,
) {
    /// Sub-pixel content rounding is not an overflow.
    const SLACK: f32 = 1.0;

    let layout = container.layout();
    let (box_size, content) = (layout.size, layout.content_size);
    if box_size.width <= 0.0 || box_size.height <= 0.0 {
        return;
    }
    let over_x = overflow.x == taffy::Overflow::Visible && content.width > box_size.width + SLACK;
    let over_y = overflow.y == taffy::Overflow::Visible && content.height > box_size.height + SLACK;
    if !(over_x || over_y) {
        return;
    }
    let first = write(ctx, |recording| recording.overflowing.insert(name));
    if first {
        tracing::warn!(
            node = name,
            box_width = box_size.width,
            box_height = box_size.height,
            content_width = content.width,
            content_height = content.height,
            "layout overflow: the content does not fit the box it was given",
        );
    }
}

#[cfg(not(debug_assertions))]
fn note_overflow(
    _ctx: &egui::Context,
    _name: &'static str,
    _container: &egui_taffy::TaffyContainerUi,
    _overflow: taffy::Point<taffy::Overflow>,
) {
}

#[cfg(test)]
mod tests {
    use super::{
        Flex, MAX_PASSES, Named as _, Node, Points, Room, Tui, cell, centre, dump, fixed, grow,
        nodes, overflowing, row, row_start, scrolling, stack, surface, trailing, wrap,
    };
    use egui_taffy::taffy;

    /// The width every test lays out into, so a reported rect is readable
    /// against a number rather than against the screen.
    const ROOM: f32 = 300.0;

    fn points(value: f32) -> Points {
        Points::new(value)
    }

    /// Real frames, so the layout under test is the one the app would paint —
    /// sizes come from the previous pass, so a single frame proves nothing.
    fn laid_out(mut show: impl FnMut(&mut egui::Ui)) -> crate::tools::painted::Chrome {
        let mut chrome = crate::tools::painted::Chrome::new(egui::Rect::from_min_size(
            egui::pos2(0.0, 0.0),
            egui::vec2(ROOM + 40.0, 600.0),
        ));
        chrome.ctx().options_mut(|options| {
            options.max_passes = MAX_PASSES;
        });
        chrome.settle(|ui| {
            let mut room = ui.new_child(
                egui::UiBuilder::new()
                    .id(egui::Id::new("flex_room"))
                    .max_rect(egui::Rect::from_min_size(
                        egui::pos2(10.0, 10.0),
                        egui::vec2(ROOM, 560.0),
                    ))
                    .layout(egui::Layout::top_down(egui::Align::Min)),
            );
            show(&mut room);
        });
        chrome
    }

    fn named(chrome: &crate::tools::painted::Chrome, name: &str) -> Node {
        nodes(chrome.ctx())
            .into_iter()
            .find(|node| node.name == name)
            .unwrap_or_else(|| {
                panic!(
                    "no node named {name:?}: {:?}",
                    nodes(chrome.ctx())
                        .iter()
                        .map(|node| node.name)
                        .collect::<Vec<_>>()
                )
            })
    }

    /// The `.row` / `.row .lead` / `.row .body` / `.row .t3` split of §3's
    /// table, spelled in the vocabulary rather than in taffy.
    fn a_row(ui: &mut egui::Ui) {
        surface(
            ui,
            "row",
            Room::Width,
            row(points(10.0)),
            |tui: &mut Tui| {
                tui.leaf("lead", fixed(), |ui| {
                    ui.label("LEAD");
                });
                tui.node("body", grow(), |tui: &mut Tui| {
                    tui.leaf("body_text", fixed(), |ui| {
                        ui.label("BODY");
                    });
                });
                tui.leaf("trail", fixed(), |ui| {
                    ui.label("TRAIL");
                });
            },
        );
    }

    #[test]
    fn the_growing_middle_takes_the_room_the_fixed_sides_leave() {
        let chrome = laid_out(a_row);
        let (lead, body, trail) = (
            named(&chrome, "lead"),
            named(&chrome, "body"),
            named(&chrome, "trail"),
        );
        assert!(
            lead.rect.is_positive() && trail.rect.is_positive(),
            "the sides did not lay out at all: {lead:?} {trail:?}",
        );
        assert!(
            body.rect.left() >= lead.rect.right(),
            "the middle overlaps the lead: {body:?} vs {lead:?}",
        );
        assert!(
            trail.rect.left() >= body.rect.right(),
            "the trailing cluster did not go to the end: {trail:?} vs {body:?}",
        );
        assert!(
            body.rect.width() > lead.rect.width() + trail.rect.width(),
            "the middle did not grow: {body:?}",
        );
        assert!(
            trail.rect.right() <= 10.0 + ROOM + 1.0,
            "the row overran its room: {trail:?}",
        );
    }

    #[test]
    fn every_node_carries_its_name_and_its_nesting_depth() {
        let chrome = laid_out(a_row);
        let seen: Vec<(&str, usize)> = nodes(chrome.ctx())
            .iter()
            .map(|node| (node.name, node.depth))
            .collect();
        assert_eq!(
            seen,
            vec![
                ("row", 0),
                ("lead", 1),
                ("body", 1),
                ("body_text", 2),
                ("trail", 1),
            ],
        );
    }

    /// The buffer is cleared when the pass moves, so it holds the frame on
    /// screen rather than every frame since the app started.
    #[test]
    fn the_buffer_holds_one_pass_and_not_every_pass() {
        let chrome = laid_out(a_row);
        assert_eq!(nodes(chrome.ctx()).len(), 5);
    }

    /// The one hard rule P0 found: wrapping text has to go through the
    /// crate's own measurement, which [`Named::text`] is.
    #[test]
    fn wrapping_text_uses_the_width_its_node_was_given() {
        let long = "Base plate seventy eight to eighty four millimetres and then some more";
        let chrome = laid_out(|ui| {
            surface(
                ui,
                "wrapping",
                Room::Width,
                row_start(points(10.0)),
                |tui: &mut Tui| {
                    tui.leaf("av", cell(points(26.0)), |ui| {
                        ui.label("AV");
                    });
                    tui.text("description", grow(), long);
                },
            );
        });
        let text = named(&chrome, "description");
        assert!(
            text.rect.width() > ROOM / 2.0,
            "the label collapsed instead of using its node: {text:?} of {ROOM}",
        );
    }

    /// A fixed square is exactly that, however small the thing inside it is.
    #[test]
    fn a_cell_keeps_its_side_whatever_it_holds() {
        let chrome = laid_out(|ui| {
            surface(
                ui,
                "cells",
                Room::Width,
                row(points(4.0)),
                |tui: &mut Tui| {
                    tui.node("tool", cell(points(52.0)), |tui: &mut Tui| {
                        tui.leaf("glyph", fixed(), |ui| {
                            ui.label("T");
                        });
                    });
                },
            );
        });
        let tool = named(&chrome, "tool");
        assert_eq!((tool.rect.width(), tool.rect.height()), (52.0, 52.0));
        let glyph = named(&chrome, "glyph");
        assert!(
            tool.rect.contains_rect(glyph.rect),
            "the glyph left its cell: {glyph:?} in {tool:?}",
        );
    }

    /// §8.5. A fixed box holding something wider than itself is reported,
    /// with its name, rather than silently clipping.
    #[test]
    fn a_node_whose_content_outgrows_its_box_is_named() {
        let chrome = laid_out(|ui| {
            surface(
                ui,
                "cramped",
                Room::Width,
                stack(points(0.0)),
                |tui: &mut Tui| {
                    tui.node("too_small", fixed().width(points(20.0)), |tui: &mut Tui| {
                        tui.widget(
                            "wide",
                            fixed(),
                            egui::Label::new("a great deal wider than twenty points").extend(),
                        );
                    });
                },
            );
        });
        assert!(
            named(&chrome, "wide").rect.width() > 20.0,
            "the test's own premise failed: the content fits the box",
        );
        assert!(
            overflowing(chrome.ctx()).contains(&"too_small"),
            "the overflow went unreported: {:?}",
            overflowing(chrome.ctx()),
        );
    }

    /// A scrolling node is *meant* to overflow, and must not be reported.
    #[test]
    fn a_scrolling_node_is_not_an_overflow() {
        let chrome = laid_out(|ui| {
            surface(
                ui,
                "sheet",
                Room::Both,
                stack(points(0.0)).height(points(120.0)),
                |tui: &mut Tui| {
                    tui.node("body", scrolling(), |tui: &mut Tui| {
                        for _ in 0..20 {
                            tui.leaf("line", fixed(), |ui| {
                                ui.label("a row of the list");
                            });
                        }
                    });
                },
            );
        });
        assert!(
            !overflowing(chrome.ctx()).contains(&"body"),
            "a scroll container was reported as overflowing",
        );
    }

    /// The whole-row click target of §8.1's history list: the box answers the
    /// press, not the words inside it, and it is named like any other node.
    #[test]
    fn a_pressable_row_answers_a_click_anywhere_in_its_box() {
        let mut chrome = crate::tools::painted::Chrome::new(egui::Rect::from_min_size(
            egui::pos2(0.0, 0.0),
            egui::vec2(ROOM + 40.0, 600.0),
        ));
        chrome.ctx().options_mut(|options| {
            options.max_passes = MAX_PASSES;
        });
        let clicked = std::cell::Cell::new(false);
        let show = |ui: &mut egui::Ui| {
            surface(
                ui,
                "list",
                Room::Width,
                stack(points(0.0)),
                |tui: &mut Tui| {
                    let pressed = tui.pressable("rev", row(points(11.0)), |tui: &mut Tui| {
                        tui.leaf("lead", cell(points(28.0)), |ui| {
                            ui.label("SB");
                        });
                        tui.text("what_changed", grow(), "Moved the base plate");
                    });
                    if pressed.clicked() {
                        clicked.set(true);
                    }
                },
            );
        };
        chrome.settle(show);
        let row_rect = named(&chrome, "rev").rect;
        assert!(
            row_rect.is_positive(),
            "the row did not lay out: {row_rect:?}"
        );
        let empty = egui::pos2(row_rect.right() - 4.0, row_rect.center().y);
        assert!(
            chrome
                .texts_inside(egui::Rect::from_center_size(empty, egui::vec2(6.0, 6.0)))
                .is_empty(),
            "the point pressed is not empty, so the row is not what answered",
        );
        chrome.click_at(empty, show);
        assert!(clicked.get(), "the row ignored a press inside its own box");
    }

    #[test]
    fn the_dump_indents_by_depth() {
        let chrome = laid_out(a_row);
        let dumped = dump(chrome.ctx());
        let lines: Vec<&str> = dumped.lines().collect();
        assert!(lines[0].starts_with("row at "), "{dumped}");
        assert!(lines[1].starts_with("  lead at "), "{dumped}");
        assert!(lines[3].starts_with("    body_text at "), "{dumped}");
    }

    #[test]
    fn the_dump_says_which_node_overflowed() {
        let chrome = laid_out(|ui| {
            surface(
                ui,
                "cramped",
                Room::Width,
                stack(points(0.0)),
                |tui: &mut Tui| {
                    tui.node("too_small", fixed().width(points(20.0)), |tui: &mut Tui| {
                        tui.widget(
                            "wide",
                            fixed(),
                            egui::Label::new("a great deal wider than twenty points").extend(),
                        );
                    });
                },
            );
        });
        assert!(dump(chrome.ctx()).contains("too_small at "));
        assert!(dump(chrome.ctx()).contains("OVERFLOWS"));
    }

    #[test]
    fn the_growing_middle_may_shrink_below_its_content() {
        let style: taffy::Style = grow().into();
        assert_eq!(style.flex_grow, 1.0);
        assert_eq!(style.flex_shrink, 1.0);
        assert_eq!(style.min_size.width, taffy::prelude::length(0.0));
    }

    #[test]
    fn a_fixed_box_neither_grows_nor_shrinks() {
        let style: taffy::Style = fixed().into();
        assert_eq!(style.flex_grow, 0.0);
        assert_eq!(style.flex_shrink, 0.0);
    }

    /// §3's table distinguishes `.row` from `.row.rev` by one property, and
    /// the vocabulary must not blur them.
    #[test]
    fn a_reversion_row_starts_where_an_ordinary_row_centres() {
        let centred: taffy::Style = row(points(11.0)).into();
        let started: taffy::Style = row_start(points(10.0)).into();
        assert_eq!(centred.align_items, Some(taffy::AlignItems::Center));
        assert_eq!(started.align_items, Some(taffy::AlignItems::FlexStart));
        assert_eq!(centred.gap.width, taffy::prelude::length(11.0));
    }

    #[test]
    fn the_centred_middle_grows_and_centres() {
        let style: taffy::Style = centre(points(8.0)).into();
        assert_eq!(style.flex_grow, 1.0);
        assert_eq!(style.justify_content, Some(taffy::JustifyContent::Center));
        assert_eq!(style.min_size.width, taffy::prelude::length(0.0));
    }

    #[test]
    fn chip_flows_wrap_and_meta_columns_do_not() {
        let chips: taffy::Style = wrap(points(4.0)).into();
        let meta: taffy::Style = trailing(points(3.0)).into();
        assert_eq!(chips.flex_wrap, taffy::FlexWrap::Wrap);
        assert_eq!(meta.flex_direction, taffy::FlexDirection::Column);
        assert_eq!(meta.align_items, Some(taffy::AlignItems::FlexEnd));
        assert_eq!(meta.flex_grow, 0.0);
    }

    #[test]
    fn a_scrolling_body_scrolls_one_way_and_clips_the_other() {
        let style: taffy::Style = scrolling().into();
        assert_eq!(style.overflow.y, taffy::Overflow::Scroll);
        assert_eq!(style.overflow.x, taffy::Overflow::Clip);
        assert_eq!(style.flex_grow, 1.0);
    }

    #[test]
    fn a_gap_below_zero_is_not_a_gap() {
        assert_eq!(f32::from(points(-4.0)), 0.0);
        assert_eq!(f32::from(Points::new(f32::NAN)), 0.0);
    }

    #[test]
    fn the_engine_needs_more_than_one_pass() {
        assert_eq!(MAX_PASSES.get(), 3);
    }

    /// §8.1: one outline per node, and the names beside them, so "where did
    /// this box actually go" has an answer on screen.
    #[cfg(feature = "ui_debug")]
    #[test]
    fn the_overlay_draws_one_outline_per_node_with_its_name() {
        let theme = crate::theme::Theme::from_embedded();
        let mut chrome = crate::tools::painted::Chrome::new(egui::Rect::from_min_size(
            egui::pos2(0.0, 0.0),
            egui::vec2(ROOM + 40.0, 600.0),
        ));
        chrome.ctx().options_mut(|options| {
            options.max_passes = MAX_PASSES;
        });
        chrome.settle(|ui| {
            a_row(ui);
            super::inspect(ui.ctx(), &theme);
        });
        assert_eq!(nodes(chrome.ctx()).len(), 5, "the tree did not lay out");
        for name in ["row", "lead", "body", "body_text", "trail"] {
            assert!(chrome.shows(name), "the overlay did not name {name}");
        }
        assert!(
            chrome.outlines().len() >= 5,
            "fewer outlines than nodes: {:?}",
            chrome.outlines(),
        );
    }

    #[test]
    fn a_root_that_fills_says_so_in_its_style() {
        let both: taffy::Style = Flex::default().spanning(Room::Both).into();
        let wide: taffy::Style = Flex::default().spanning(Room::Width).into();
        assert_eq!(both.size.width, taffy::prelude::percent(1.0));
        assert_eq!(both.size.height, taffy::prelude::percent(1.0));
        assert_eq!(wide.size.height, taffy::prelude::auto());
    }
}