blockworx/tools/

toolbar.rs

use crate::{
    doc::{At, TimeStep, Viewing},
    edit::{lower::accent_from_role, naming::InterfaceLock},
    export::ExportScope,
    grid::GRID_SIZE,
    shape::{ShapeId, ShapeRef},
    theme::{Role, Theme, accent_role},
    tools::{
        chrome::Panel,
        commands::{CommandId, CommandSet},
        names::{TOOLBAR_TOOLS, ToolName},
        tool::{Action, RoleTarget},
    },
    widget::drawing::Drawing,
};
use blockworx_doc::{register::Register, values::Role as AccentRole};

/// Whether the thing a toggle control opens — a picker, a window — is showing,
/// which is what draws the control pressed.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum PanelState {
    Open,
    Closed,
}

/// Which selection popup is open, if any. They are mutually exclusive: opening
/// one closes the other.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum OpenPicker {
    Role,
    PinType,
}

/// The egui temp-data key where the live toolbar stashes its frame rect each
/// frame (read by [`selection_overlay`] to keep out from under it).
pub fn toolbar_rect_id() -> egui::Id {
    Panel::ModeToolbar.measurement("rect")
}

/// Where the live toolbar drew last frame, for the chrome that must keep out
/// from under it. [`egui::Rect::NOTHING`] until it has drawn once, which
/// unions away.
pub fn drawn_rect(ctx: &egui::Context) -> egui::Rect {
    ctx.data(|d| d.get_temp(toolbar_rect_id()))
        .unwrap_or(egui::Rect::NOTHING)
}

/// The toolbar's view toggles, edited in place. Only the debug-marks checkbox
/// remains.
pub struct ViewToggles<'a> {
    pub debug_marks: &'a mut bool,
}

/// Everything [`toolbar_contents`] renders against.
pub struct ToolbarProps<'a> {
    /// The toolbar button shown selected (see
    /// [`displayed_tool`](crate::tools::names::displayed_tool)).
    pub selected: ToolName,
    pub toggles: ViewToggles<'a>,
    /// Where the user stands in the hierarchy, and how they move through it.
    pub nav: NavCluster<'a>,
}

/// What one toolbar frame reports: the action a button fired, the compass's
/// rect, which the navigator popup hangs from, and — for the tests that click
/// the real strip — each tool button's screen rect.
pub struct ToolbarFrame {
    pub action: Option<Action>,
    pub compass: egui::Rect,
    #[cfg(test)]
    pub tool_rects: Vec<(ToolName, egui::Rect)>,
}

/// The live toolbar: plain widgets in a child of the canvas `Ui`, centered in
/// a strip along the viewport top. Same layer as the canvas, painted after
/// it, so the buttons draw on top and win hit-testing.
pub fn toolbar(
    commands: &mut CommandSet,
    props: ToolbarProps<'_>,
    viewport: egui::Rect,
    ui: &mut egui::Ui,
) -> ToolbarFrame {
    let (frame, rect) = centered_strip(ui, Panel::ModeToolbar, viewport, |ui| {
        toolbar_contents(ui, commands, props)
    });
    // Stash the frame's rect so the selection overlay can avoid covering it.
    ui.ctx()
        .data_mut(|d| d.insert_temp(toolbar_rect_id(), rect));
    frame
}

/// Run `add` in a child `Ui` centered along `bounds`' top edge (below a
/// one-cell margin) — the toolbar's `Area` anchoring, without the `Area`.
/// Content-hugging widgets can't be centered before they're laid out, so the
/// x comes from last frame's measured width (stashed per host `Ui`); the
/// first frame draws once at the center-as-left-edge and snaps on the next.
/// Returns `add`'s result and the content's rect.
fn centered_strip<R>(
    ui: &mut egui::Ui,
    panel: Panel,
    bounds: egui::Rect,
    add: impl FnOnce(&mut egui::Ui) -> R,
) -> (R, egui::Rect) {
    let width_key = panel.measurement("width");
    let left = if let Some(width) = ui.ctx().data(|d| d.get_temp::<f32>(width_key)) {
        bounds.center().x - width / 2.0
    } else {
        ui.ctx().request_repaint();
        bounds.center().x
    };
    let strip = egui::Rect::from_min_max(
        egui::pos2(left, bounds.top() + GRID_SIZE),
        bounds.right_bottom(),
    );
    let mut child = ui.new_child(
        panel
            .ui_builder()
            .max_rect(strip)
            .layout(egui::Layout::top_down(egui::Align::Min)),
    );
    let result = add(&mut child);
    let rect = child.min_rect();
    ui.ctx()
        .data_mut(|d| d.insert_temp(width_key, rect.width()));
    (result, rect)
}

/// The toolbar's widgets, independent of where they sit: the live app centers
/// them over the canvas; the tutorial player embeds them in the video. Also
/// returns each tool button's rect (in the host `Ui`'s coordinates), which
/// the video feeds to the demo-cursor cues.
fn toolbar_contents(
    ui: &mut egui::Ui,
    commands: &mut CommandSet,
    props: ToolbarProps<'_>,
) -> ToolbarFrame {
    let ToolbarProps {
        selected,
        toggles: ViewToggles { debug_marks },
        nav: NavCluster { history, nav_open },
    } = props;
    let mut action: Option<Action> = None;
    let mut clicked: Option<CommandId> = None;
    #[cfg(test)]
    let mut rects = Vec::new();
    let mut compass_rect = egui::Rect::NOTHING;
    egui::Frame::popup(ui.style()).show(ui, |ui| {
        ui.horizontal(|ui| {
            debug_checkbox(ui, debug_marks);
            for mode in TOOLBAR_TOOLS {
                let button = egui::Button::image(icon_image(ui, tool_icon(*mode)))
                    .selected(selected == *mode);
                // The registry's own answer, so a button and the command it
                // fires cannot disagree: a locked block withholds Add Port,
                // and a read-only session withholds every authoring tool.
                // Disabled rather than absent — the toolbar keeps its shape.
                let id = CommandId::Arm(*mode);
                let hover = match crate::tools::commands::binding(id) {
                    Some(chord) => format!("{} ({})", mode, ui.ctx().format_shortcut(chord)),
                    None => mode.to_string(),
                };
                let response = ui
                    .add_enabled(commands.contains(id), button)
                    .on_hover_text(hover);
                #[cfg(test)]
                rects.push((*mode, response.rect));
                if response.clicked() {
                    clicked = Some(id);
                }
            }
            ui.separator();
            // Where you are in the hierarchy and how you move through it —
            // the navigator's compass, the path arrows, and enter/exit block.
            // They sit beside the tools rather than in a corner of their own,
            // in the space the file and preferences buttons left behind.
            let compass = egui::Button::image(icon_image(ui, COMPASS_ICON)).selected(*nav_open);
            let compass = ui.add(compass).on_hover_text("Navigator");
            compass_rect = compass.rect;
            if compass.clicked() {
                *nav_open = !*nav_open;
            }
            for (enabled, icon, hover, step) in [
                (history.can_back, BACK_ICON, "Back", Action::PathBack),
                (
                    history.can_forward,
                    FORWARD_ICON,
                    "Forward",
                    Action::PathForward,
                ),
            ] {
                if ui
                    .add_enabled(enabled, icon_button(ui, icon))
                    .on_hover_text(hover)
                    .clicked()
                {
                    action = Some(step);
                }
            }
            for (id, icon, hover) in [
                (CommandId::ExpandBlock, EXPAND_ICON, "Enter block"),
                (CommandId::GoUp, EXIT_ICON, "Go up a level"),
            ] {
                if ui
                    .add_enabled(commands.contains(id), icon_button(ui, icon))
                    .on_hover_text(hover)
                    .clicked()
                {
                    clicked = Some(id);
                }
            }
        });
    });
    ToolbarFrame {
        action: action.or_else(|| clicked.and_then(|id| commands.take(id))),
        compass: compass_rect,
        #[cfg(test)]
        tool_rects: rects,
    }
}

/// A lower-left overlay for the document history: Undo and Redo as icon
/// buttons with hover text, kept off the main toolbar so they sit near the
/// canvas. Each is enabled while its command is in the frame's
/// [`CommandSet`]. The hierarchy controls live elsewhere — on the toolbar's
/// navigation group, and in the palette. In-`Ui` widgets like the toolbar (see
/// [`toolbar`]): a bottom-up child of the canvas `Ui` hugs its content against
/// the viewport's lower-left corner with no measuring pass.
///
/// While a past rev is on the canvas the pair beside the clock *is* the
/// time machine: undo and redo do not apply to a document nobody is
/// editing, so they become a tape player — step back, step forward, and
/// seek to the latest rev. The clock never navigates; it only opens and
/// closes the panel, at head and in the past alike, so the one control
/// that toggles a window does not sometimes travel in time instead
/// (docs/ui-issues-2.md, items 4 and 7).
pub fn history_overlay(
    commands: &mut CommandSet,
    cluster: HistoryCluster<'_>,
    viewport: egui::Rect,
    ui: &mut egui::Ui,
) -> HistoryFrame {
    let HistoryCluster {
        panel_open,
        viewing,
        head,
        steps,
    } = cluster;
    let mut clicked: Option<CommandId> = None;
    let mut action: Option<Action> = None;
    let mut clock = egui::Rect::NOTHING;
    let past = viewing != Viewing::Head;
    let corner = egui::Rect::from_min_max(
        viewport.left_top() + egui::vec2(GRID_SIZE, 0.0),
        viewport.right_bottom() - egui::vec2(0.0, GRID_SIZE),
    );
    let mut child = ui.new_child(
        Panel::History
            .ui_builder()
            .max_rect(corner)
            .layout(egui::Layout::bottom_up(egui::Align::Min)),
    );
    egui::Frame::popup(child.style()).show(&mut child, |ui| {
        ui.horizontal(|ui| {
            // The trail toggle leads, so Undo and Redo keep the end of
            // the cluster they have always sat at.
            let toggle = egui::Button::image(icon_image(ui, TIMELINE_ICON)).selected(*panel_open);
            let toggle = ui.add(toggle).on_hover_text("History");
            clock = toggle.rect;
            if toggle.clicked() {
                *panel_open = !*panel_open;
            }
            ui.separator();
            let mut step = |ui: &mut egui::Ui, icon, hover: &str, to: Option<At>| {
                if ui
                    .add_enabled(to.is_some(), icon_button(ui, icon))
                    .on_hover_text(hover)
                    .clicked()
                {
                    action = Some(match to {
                        Some(At::Rev(rev)) => Action::ViewRev(rev),
                        _ => Action::ViewHead,
                    });
                }
            };
            let mut button = |ui: &mut egui::Ui, id, icon, verb: &str, of: Option<&str>| {
                let hover = match of {
                    Some(label) => format!("{verb} {label}"),
                    None => verb.to_owned(),
                };
                if ui
                    .add_enabled(commands.contains(id), icon_button(ui, icon))
                    .on_hover_text(hover)
                    .clicked()
                {
                    clicked = Some(id);
                }
            };
            if past {
                step(
                    ui,
                    STEP_BACK_ICON,
                    "Back one rev",
                    viewing.stepped(head, TimeStep::Back),
                );
                step(
                    ui,
                    STEP_FORWARD_ICON,
                    "Forward one rev",
                    viewing.stepped(head, TimeStep::Forward),
                );
                // Always live while a past rev is showing: that is what
                // there is to seek away from.
                step(ui, SEEK_LATEST_ICON, "Return to latest", Some(At::Current));
            } else {
                button(ui, CommandId::Undo, UNDO_ICON, "Undo", steps.undo);
                button(ui, CommandId::Redo, REDO_ICON, "Redo", steps.redo);
            }
        });
    });
    HistoryFrame {
        action: action.or_else(|| clicked.and_then(|id| commands.take(id))),
        clock,
    }
}

/// The history cluster's own state: whether the history panel its clock
/// button toggles is showing, and where in the log the canvas is standing.
pub struct HistoryCluster<'a> {
    pub panel_open: &'a mut bool,
    pub viewing: Viewing,
    /// The newest rev the log holds — the far end a step walks toward.
    pub head: blockworx_doc::rev::Rev,
    /// What the next undo and redo would take back or bring forward, by
    /// the commit's own label — so a reader hovering the button is told
    /// *which* edit, not merely that there is one.
    pub steps: UndoSteps<'a>,
}

/// The commits the undo and redo buttons stand over.
#[derive(Clone, Copy, Default)]
pub struct UndoSteps<'a> {
    pub undo: Option<&'a str>,
    pub redo: Option<&'a str>,
}

/// What one history-cluster frame reports.
pub struct HistoryFrame {
    pub action: Option<Action>,
    /// The clock button's rect, which the history panel hangs from.
    pub clock: egui::Rect,
}

/// What the toolbar's navigation group shows and edits: the path-history
/// arrows' availability and the navigator's open flag (which its compass
/// toggles). Enter is enabled only while a block is selected (it is in the
/// frame's [`CommandSet`] then); exit always is.
pub struct NavCluster<'a> {
    pub history: crate::tools::nav_tree::PathHistory,
    pub nav_open: &'a mut bool,
}

/// The concrete color the accent swatch shows for `target`: its current accent
/// role resolved against `theme`. Mirrors the role-picker's current-role lookup
/// in [`crate::app`] — an unset accent falls back to the target's own
/// un-accented stroke ([`Role::AreaStroke`], [`Role::TextBoxStroke`], or
/// [`Role::AccentDefault`]).
fn accent_swatch_color(data: &Drawing, target: RoleTarget, theme: &Theme) -> egui::Color32 {
    let accent = |role: &Register<AccentRole>| accent_from_role(*role.as_ref());
    let current = match target {
        RoleTarget::Block(rid) => data.block(rid).and_then(|b| accent(&b.role)),
        RoleTarget::Port(pid) => match data.shape(ShapeId::Port(pid)) {
            Some(ShapeRef::Port(port)) => accent(&port.pin.port_accent),
            _ => None,
        },
        RoleTarget::Route(rid) => data.auto_route(rid).and_then(|w| accent(&w.route.role)),
        RoleTarget::Area(cid) => match data.shape(ShapeId::Area(cid)) {
            Some(ShapeRef::Area(area)) => accent(&area.role),
            _ => None,
        },
        RoleTarget::Text(tid) => match data.shape(ShapeId::Text(tid)) {
            Some(ShapeRef::Text(text)) => accent(&text.text.role),
            _ => None,
        },
    };
    theme.resolve(accent_display_role(target, current))
}

/// The [`Role`] the accent swatch displays for `target` given its current accent
/// index `current`: the mapped accent role, or — when unset — the target's own
/// un-accented stroke, matching the role picker's "no accent" cell.
fn accent_display_role(target: RoleTarget, current: Option<u8>) -> Role {
    let default_role = match target {
        RoleTarget::Area(_) => Role::AreaStroke,
        RoleTarget::Text(_) => Role::TextBoxStroke,
        _ => Role::AccentDefault,
    };
    accent_role(current).unwrap_or(default_role)
}

const COMPASS_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-compass.svg");
const EXPAND_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-expand.svg");
const EXIT_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-exit.svg");
const LOCK_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-lock.svg");
const UNLOCK_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-unlock.svg");
const DELETE_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-trash.svg");
const IMAGE_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-image.svg");
const SELECT_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-select.svg");
const NEW_BLOCK_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-new-block.svg");
const AREA_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-area.svg");
const ADD_PORT_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-add-port.svg");
const ADD_TEXT_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-add-text.svg");
const ROUTE_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-route.svg");
const ADD_ICON_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-add-icon.svg");
const ROUTE_LABEL_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-route-label.svg");
const UNDO_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-undo.svg");
const REDO_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-redo.svg");
const TIMELINE_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-timeline.svg");
/// The tape-player trio the history cluster wears while a past rev is on
/// the canvas: `|<`, `>|`, `>>|`.
const STEP_BACK_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-step-back.svg");
const STEP_FORWARD_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-step-forward.svg");
pub(crate) const SEEK_LATEST_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-seek-latest.svg");
const COPY_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-copy.svg");
const CUT_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-cut.svg");
const FLIP_LR_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-flip-lr.svg");
const FLIP_UD_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-flip-ud.svg");
const BACK_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-arrow-left.svg");
const FORWARD_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-arrow-right.svg");
pub(crate) const EXPORT_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-export.svg");
const REROUTE_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-reroute.svg");

/// The router's debug-marks toggle, compiled in only under the `ui_debug`
/// feature: it is a developer overlay, not shipped chrome.
#[cfg(feature = "ui_debug")]
fn debug_checkbox(ui: &mut egui::Ui, debug_marks: &mut bool) {
    ui.checkbox(debug_marks, "Debug");
    ui.separator();
}

#[cfg(not(feature = "ui_debug"))]
fn debug_checkbox(_ui: &mut egui::Ui, _debug_marks: &mut bool) {}

/// The toolbar icon for a base tool. Only [`TOOLBAR_TOOLS`] reach this; any other
/// `ToolName` falls back to the select cursor (it is never shown on the toolbar).
fn tool_icon(tool: ToolName) -> egui::ImageSource<'static> {
    match tool {
        ToolName::NewBlock => NEW_BLOCK_ICON,
        ToolName::NewArea => AREA_ICON,
        ToolName::AddPort => ADD_PORT_ICON,
        ToolName::NewImage => IMAGE_ICON,
        ToolName::AddText => ADD_TEXT_ICON,
        ToolName::Route => ROUTE_ICON,
        _ => SELECT_ICON,
    }
}

/// The icon and hover text for the lock-toggle control. The padlock depicts the
/// block's current state — closed when locked, open shackle when unlocked, like a
/// physical padlock — while the hover text names the action a click performs.
fn lock_toggle_icon(lock: InterfaceLock) -> (egui::ImageSource<'static>, &'static str) {
    match lock {
        InterfaceLock::Locked => (LOCK_ICON, "Unlock pins"),
        InterfaceLock::Unlocked => (UNLOCK_ICON, "Lock pins"),
    }
}

/// A 14×14 icon image tinted to the current text color, the shared building block
/// for every icon button in the toolbar and overlays.
pub(crate) fn icon_image(
    ui: &egui::Ui,
    source: egui::ImageSource<'static>,
) -> egui::Image<'static> {
    egui::Image::new(source)
        .fit_to_exact_size(egui::vec2(14.0, 14.0))
        .tint(ui.visuals().widgets.inactive.fg_stroke.color)
}

/// A small square icon button tinted to the current text color, matching the
/// look of the navigation dialog's icon buttons.
pub(crate) fn icon_button(
    ui: &egui::Ui,
    source: egui::ImageSource<'static>,
) -> egui::Button<'static> {
    egui::Button::image(icon_image(ui, source))
}

/// The accent control: a small filled square of the selection's current accent
/// `color` that opens the role picker on click, sized to match [`icon_button`].
/// When the picker is `open` the swatch carries an active-indicator ring.
fn accent_swatch_button(
    ui: &mut egui::Ui,
    color: egui::Color32,
    picker: PanelState,
) -> egui::Response {
    let (rect, resp) = ui.allocate_exact_size(egui::vec2(14.0, 14.0), egui::Sense::click());
    let painter = ui.painter();
    painter.rect_filled(rect, 2.0, color);
    let (width, stroke) = if picker == PanelState::Open {
        (2.0, ui.visuals().selection.stroke.color)
    } else {
        (1.0, ui.visuals().widgets.inactive.fg_stroke.color)
    };
    painter.rect_stroke(
        rect,
        2.0,
        egui::Stroke::new(width, stroke),
        egui::StrokeKind::Inside,
    );
    resp.on_hover_text("Accent")
}

/// Gap (screen px) between the selection's edge and the overlay placed just
/// above or below it. Comfortably clears the selection frame, which is itself
/// drawn slightly outside the selection's bounding box. Expressed in grid cells
/// (world space) so the on-screen gap scales with zoom — a fixed pixel gap looks
/// cramped when zoomed in and detached when zoomed out.
const OVERLAY_BLOCK_GAP_CELLS: f32 = 1.5;
/// Minimum gap (screen px) between the viewport top and an above-placed overlay —
/// large enough to clear the mode toolbar. Tunable, since the toolbar may move or
/// resize; it's screen space because zoom doesn't affect it.
const OVERLAY_TOP_GAP: f32 = 96.0;
/// Minimum gap (screen px) from the viewport's left/right/bottom edges.
const OVERLAY_EDGE_GAP: f32 = 8.0;
/// Fallback distance (screen px) up from the viewport bottom when the overlay fits
/// neither above nor below the selection.
const OVERLAY_BOTTOM_GAP: f32 = 16.0;

/// The horizontal band an overlay of `size` can land in at vertical `y`, bounded
/// by `x_min..=x_max` (the on-screen clamp).
struct Strip {
    y: f32,
    size: egui::Vec2,
    x_min: f32,
    x_max: f32,
}

impl Strip {
    /// An x in the strip that is clear of every obstacle, by sliding sideways
    /// from `desired`: to the nearest landing past an obstacle's right edge
    /// (preferred — e.g. just past the navigation dialog), else just left of an
    /// obstacle. A small [`OVERLAY_EDGE_GAP`] is left between the overlay and the
    /// obstacle, since touching rects still count as intersecting. `None` when no
    /// clear x fits — e.g. a full-width obstacle. The caller has already tried
    /// `desired` itself, so this only returns a shifted x.
    fn shifted_clear_x(&self, desired: f32, obstacles: &[egui::Rect]) -> Option<f32> {
        let (y, size, x_min, x_max) = (self.y, self.size, self.x_min, self.x_max);
        let fits = |x: f32| {
            let rect = egui::Rect::from_min_size(egui::pos2(x, y), size);
            x >= x_min && x <= x_max && !obstacles.iter().any(|o| o.intersects(rect))
        };
        let right = obstacles
            .iter()
            .map(|o| o.right() + OVERLAY_EDGE_GAP)
            .filter(|&x| x >= desired && fits(x))
            .min_by(f32::total_cmp);
        let left = obstacles
            .iter()
            .map(|o| o.left() - size.x - OVERLAY_EDGE_GAP)
            .filter(|&x| x <= desired && fits(x))
            .max_by(f32::total_cmp);
        right.or(left)
    }
}

/// Top-left screen position for an overlay of `size`, placed relative to the
/// selection's screen-space bbox `sel` within `viewport`: prefer just above the
/// selection, else just below — both horizontally centered on the selection — and
/// only if neither centered placement clears the `obstacles` (the mode toolbar,
/// the navigation dialog), slide sideways (see [`Strip::shifted_clear_x`]) at the above
/// height then the below height as a last resort before hiding. Failing all that,
/// pin a fixed distance up from the bottom and center on the viewport. Always
/// clamped fully on screen. Returns `None` when nothing fits clear of the
/// obstacles (the caller hides it). Assumes `viewport.intersects(sel)` already.
fn place_overlay(
    sel: egui::Rect,
    viewport: egui::Rect,
    size: egui::Vec2,
    block_gap: f32,
    obstacles: &[egui::Rect],
) -> Option<egui::Pos2> {
    let x_min = viewport.left() + OVERLAY_EDGE_GAP;
    let x_max = viewport.right() - OVERLAY_EDGE_GAP - size.x;
    if x_max < x_min {
        return None; // wider than the viewport: can't fit on screen
    }
    let desired = (sel.center().x - size.x / 2.0).clamp(x_min, x_max);
    let clear = |pos: egui::Pos2| {
        let rect = egui::Rect::from_min_size(pos, size);
        !obstacles.iter().any(|o| o.intersects(rect))
    };

    // Above clears the toolbar gap; below clears it and fits the bottom margin.
    let above_y = sel.top() - block_gap - size.y;
    let above_ok = above_y >= viewport.top() + OVERLAY_TOP_GAP;
    let below_y = sel.bottom() + block_gap;
    let below_fits_bottom = below_y + size.y <= viewport.bottom() - OVERLAY_EDGE_GAP;
    let below_ok = below_y >= viewport.top() + OVERLAY_TOP_GAP && below_fits_bottom;

    // Centered, preferring above then below — keeps the overlay on the selection.
    if above_ok && clear(egui::pos2(desired, above_y)) {
        return Some(egui::pos2(desired, above_y));
    }
    if below_ok && clear(egui::pos2(desired, below_y)) {
        return Some(egui::pos2(desired, below_y));
    }
    // A centered placement is blocked: slide sideways to clear the obstacles,
    // above first then below, before giving up on the selection's neighborhood.
    let strip = |y: f32| Strip {
        y,
        size,
        x_min,
        x_max,
    };
    if above_ok && let Some(x) = strip(above_y).shifted_clear_x(desired, obstacles) {
        return Some(egui::pos2(x, above_y));
    }
    if below_ok && let Some(x) = strip(below_y).shifted_clear_x(desired, obstacles) {
        return Some(egui::pos2(x, below_y));
    }
    // There is room below the selection, but nothing there fit even shifted → hide
    // rather than overlap the obstacles. The bottom-of-screen fallback is only for
    // a selection that leaves no room below at all (e.g. it fills the viewport).
    if below_fits_bottom {
        return None;
    }
    let fallback_y = viewport.bottom() - OVERLAY_BOTTOM_GAP - size.y;
    if fallback_y < viewport.top() + OVERLAY_TOP_GAP {
        return None; // doesn't fit between the toolbar and the bottom
    }
    let fallback_desired = (viewport.center().x - size.x / 2.0).clamp(x_min, x_max);
    if clear(egui::pos2(fallback_desired, fallback_y)) {
        return Some(egui::pos2(fallback_desired, fallback_y));
    }
    strip(fallback_y)
        .shifted_clear_x(fallback_desired, obstacles)
        .map(|x| egui::pos2(x, fallback_y))
}

/// The export-format buttons, shared by the main menu's Export submenu and
/// the block overlay's "Export as top level" menu, each offering the formats
/// its `scope` carries. Returns the clicked format.
pub(crate) fn export_format_menu(
    ui: &mut egui::Ui,
    scope: crate::export::ExportScope,
) -> Option<crate::export::ExportFormat> {
    scope
        .formats()
        .iter()
        .copied()
        .find(|format| ui.button(format.label()).clicked())
}

/// Action buttons shown next to the current selection: a view of the frame's
/// [`CommandSet`], rendering each available selection command in registry
/// order — icon buttons for most, an export submenu, the tag-visibility text
/// toggle, the "I/O" picker button, and the accent swatch (a square of the
/// current accent color). `open_picker` tells the matching button to show
/// as active and to leave dismissal to the open popup. The overlay is placed in
/// screen space relative to `sel_screen` (the selection's on-screen bounds) within
/// `viewport` (see [`place_overlay`]); it is hidden when nothing is selected, the
/// selection isn't visible, or it can't fit on screen. Returns the triggered
/// `Action` and the overlay's top-right corner (used to anchor the popups above
/// it; `None` when hidden, which dismisses them).
#[allow(clippy::too_many_arguments)]
pub fn selection_overlay(
    commands: &mut CommandSet,
    data: &Drawing,
    theme: &Theme,
    open_picker: Option<OpenPicker>,
    sel_screen: Option<egui::Rect>,
    viewport: egui::Rect,
    zoom: crate::canvas::Zoom,
    ui: &mut egui::Ui,
) -> (Option<Action>, Option<egui::Pos2>) {
    let ctx = ui.ctx().clone();
    let ctx = &ctx;
    let Some(sel_screen) = sel_screen else {
        return (None, None);
    };
    if !viewport.intersects(sel_screen) {
        return (None, None);
    }
    // Nothing to render is nothing to show. Withheld commands still count —
    // a wire in a read-only session shows its controls disabled rather than
    // no bar at all (docs/ui-issues.md follow-up: disabled beats hidden).
    if overlay_controls(commands).next().is_none() {
        return (None, None);
    }
    // The overlay must not cover the mode toolbar or the navigation dialog;
    // read their last-frame rects so `place_overlay` can avoid them. The
    // toolbar (in-`Ui` widgets since the `Area` migration) stashes its rect
    // each frame; the navigator is still an `Area` — its rect persists in
    // egui memory after it stops being shown (it's toggleable), so only a
    // visible area counts as an obstacle.
    let visible_area_rect = |name: &str| {
        let id = egui::Id::new(name);
        ctx.memory(|m| {
            m.areas()
                .visible_last_frame(&egui::LayerId::new(egui::Order::Middle, id))
                .then(|| m.area_rect(id))
                .flatten()
        })
    };
    let obstacles: Vec<egui::Rect> = [
        ctx.data(|d| d.get_temp(toolbar_rect_id())),
        visible_area_rect("nav_tree"),
        visible_area_rect("history_panel"),
    ]
    .into_iter()
    .flatten()
    .collect();
    // World-space gap (grid cells → pixels) so the bar keeps a constant distance
    // from its object at any zoom.
    let block_gap = OVERLAY_BLOCK_GAP_CELLS * GRID_SIZE * zoom.get();
    // The overlay places itself from last frame's measured rect — but only
    // when that measurement is *of these controls*. A selection switch (a
    // block's bar giving way to a wire's) changes the control list, and
    // placing the new bar with the old bar's size flashed it one frame in
    // the wrong place. So the measurement remembers what it measured, and a
    // frame whose controls it does not match is an invisible sizing pass:
    // laid out, measured, never painted, correctly placed next frame.
    let drawn: Vec<CommandId> = overlay_controls(commands).map(|cmd| cmd.id).collect();
    let size_key = Panel::SelectionButtons.measurement("rect");
    let remembered = ctx
        .data(|d| d.get_temp::<(Vec<CommandId>, egui::Rect)>(size_key))
        .filter(|(of, _)| *of == drawn)
        .map(|(_, rect)| rect.size());
    let (builder, pos) = if let Some(size) = remembered {
        match place_overlay(sel_screen, viewport, size, block_gap, &obstacles) {
            Some(pos) => (Panel::SelectionButtons.ui_builder(), pos),
            None => return (None, None),
        }
    } else {
        ctx.request_repaint();
        // Both flags, deliberately: `sizing_pass` alone only tightens the
        // layout — egui's painter goes quiet on `invisible`, and its own
        // Area/Grid sizing passes chain exactly this pair. Without it the
        // measuring frame painted the bar at the provisional spot below.
        (
            Panel::SelectionButtons
                .ui_builder()
                .sizing_pass()
                .invisible(),
            sel_screen.center(),
        )
    };
    let sizing = builder.sizing_pass;
    let mut clicked: Option<CommandId> = None;
    let mut child = ui.new_child(builder.max_rect(egui::Rect::from_min_size(pos, viewport.size())));
    let rect = {
        let ui = &mut child;
        egui::Frame::popup(ui.style())
            .show(ui, |ui| {
                ui.horizontal(|ui| {
                    for cmd in overlay_controls(commands) {
                        let fired = ui
                            .add_enabled_ui(!cmd.withheld(), |ui| {
                                overlay_command(ui, cmd, data, theme, open_picker)
                            })
                            .inner;
                        if let Some(id) = fired {
                            clicked = Some(id);
                        }
                    }
                });
            })
            .response
            .rect
    };
    tracing::debug!(
        target: "overlay",
        pass = ctx.cumulative_pass_nr(),
        sizing,
        drawn = drawn.len(),
        pos = ?pos,
        rect = ?rect,
        sel = ?sel_screen,
        "overlay frame"
    );
    // Next frame's placement uses this frame's measurement of these controls.
    ctx.data_mut(|d| d.insert_temp(size_key, (drawn, rect)));
    if sizing {
        return (None, None);
    }
    (
        clicked.and_then(|id| commands.take(id)),
        Some(rect.right_top()),
    )
}

/// The controls this overlay lays out, in registry order, withheld ones
/// included (they draw disabled). The one gate: "is this overlay empty",
/// "what does it draw", and *how wide it is* all read this, so a command
/// that renders nothing takes no room either — each control sits in a
/// child `Ui` of its own, and an empty child still advances the row by
/// one item spacing.
fn overlay_controls(
    commands: &CommandSet,
) -> impl Iterator<Item = &crate::tools::commands::Command> {
    commands.iter_drawn().filter(|cmd| drawn_in_overlay(cmd.id))
}

/// Whether `id` draws a control in the selection overlay. The one list, so
/// that "is this overlay empty" and "what does this overlay draw" cannot
/// disagree — an overlay with nothing to draw is not shown at all.
fn drawn_in_overlay(id: CommandId) -> bool {
    match id {
        // One submenu covers every export format: the first format's command
        // renders it, the rest are reached inside the menu.
        CommandId::ExportSelection(format) => format == ExportScope::Selection.leading_format(),
        // These belong to other surfaces: toolbar arming, the history
        // cluster's undo/redo, whole-view export/import.
        CommandId::Arm(_)
        | CommandId::Undo
        | CommandId::Redo
        | CommandId::Export(_)
        | CommandId::Import => false,
        CommandId::HideTags | CommandId::ShowTags | CommandId::PinType | CommandId::Accent => true,
        id => overlay_icon(id).is_some(),
    }
}

/// Render `cmd`'s overlay control, returning the command a click fired.
/// Only what [`overlay_controls`] yields reaches here.
fn overlay_command(
    ui: &mut egui::Ui,
    cmd: &crate::tools::commands::Command,
    data: &Drawing,
    theme: &Theme,
    open_picker: Option<OpenPicker>,
) -> Option<CommandId> {
    match cmd.id {
        CommandId::ExportSelection(_) => {
            let mut picked = None;
            ui.menu_image_button(icon_image(ui, EXPORT_ICON), |ui| {
                picked = export_format_menu(ui, ExportScope::Selection);
            })
            .response
            .on_hover_text("Export");
            picked.map(CommandId::ExportSelection)
        }
        CommandId::HideTags | CommandId::ShowTags => {
            ui.button(cmd.label).clicked().then_some(cmd.id)
        }
        CommandId::PinType => {
            let selected = open_picker == Some(OpenPicker::PinType);
            (ui.add(egui::Button::new(cmd.label).selected(selected))
                .clicked()
                && !selected)
                .then_some(cmd.id)
        }
        CommandId::Accent => {
            let Action::OpenRolePicker { target } = &cmd.action else {
                return None;
            };
            let swatch = accent_swatch_color(data, *target, theme);
            let picker = if open_picker == Some(OpenPicker::Role) {
                PanelState::Open
            } else {
                PanelState::Closed
            };
            (accent_swatch_button(ui, swatch, picker).clicked() && picker == PanelState::Closed)
                .then_some(cmd.id)
        }
        id => {
            let icon = overlay_icon(id)?;
            ui.add(icon_button(ui, icon))
                .on_hover_text(cmd.label)
                .clicked()
                .then_some(id)
        }
    }
}

/// The icon-button artwork for the overlay's plain commands. The padlock pair
/// routes through [`lock_toggle_icon`] so the shackle depicts the block's
/// current state while the command names the action a click performs.
fn overlay_icon(id: CommandId) -> Option<egui::ImageSource<'static>> {
    match id {
        CommandId::Copy => Some(COPY_ICON),
        CommandId::Cut => Some(CUT_ICON),
        CommandId::FlipLr => Some(FLIP_LR_ICON),
        CommandId::FlipUd => Some(FLIP_UD_ICON),
        CommandId::Reroute | CommandId::RerouteBlock => Some(REROUTE_ICON),
        CommandId::AddRouteLabel => Some(ROUTE_LABEL_ICON),
        // Entering a block is a verb about the *selection*, so it is here as
        // well as in the toolbar's navigation group.
        CommandId::ExpandBlock => Some(EXPAND_ICON),
        CommandId::Lock => Some(lock_toggle_icon(InterfaceLock::Unlocked).0),
        CommandId::Unlock => Some(lock_toggle_icon(InterfaceLock::Locked).0),
        CommandId::AddIcon => Some(ADD_ICON_ICON),
        CommandId::Delete => Some(DELETE_ICON),
        _ => None,
    }
}

#[cfg(all(test, feature = "kittest"))]
mod kittest_visual {
    use super::*;
    use crate::canvas::palette::Luminance;
    use crate::font::build_fonts;
    use crate::preferences::{FontChoice, Theme};
    use egui::vec2;
    use egui_kittest::Harness;

    /// The toolbar as it now stands: the tools, then the navigation group the
    /// lower-right cluster gave up. Enter draws dead — a picture has no
    /// selection to enter — and so do the path arrows, which is the
    /// disabled-not-hidden paradigm in one image.
    #[test]
    fn toolbar_strip() {
        // Proportional[0] = Roboto (Basic), so the toolbar text renders in the
        // installed font; visuals come from a base16 scheme.
        let mut harness = Harness::builder()
            .with_size(vec2(1240.0, 120.0))
            .build_ui(move |ui| {
                let ctx = ui.ctx().clone();
                egui_extras::install_image_loaders(&ctx);
                ctx.set_fonts(build_fonts(FontChoice::Basic));
                ctx.set_visuals(Theme::Catppuccin.palette(Luminance::Dark).egui_visuals());

                // The real toolbar centers itself in a strip along the host
                // `Ui`'s top edge.
                let mut debug = false;
                let mut nav_open = false;
                let viewport = ui.max_rect();
                toolbar(
                    &mut CommandSet::writable_toolbar(),
                    ToolbarProps {
                        selected: ToolName::Select,
                        toggles: ViewToggles {
                            debug_marks: &mut debug,
                        },
                        nav: NavCluster {
                            history: crate::tools::nav_tree::PathHistory {
                                can_back: true,
                                can_forward: false,
                            },
                            nav_open: &mut nav_open,
                        },
                    },
                    viewport,
                    ui,
                );
            });
        harness.run();
        harness.snapshot("toolbar");
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::path::Scope;
    use crate::preferences::Preferences;
    use egui::{Rect, Vec2, pos2, vec2};

    fn viewport() -> Rect {
        Rect::from_min_size(pos2(0.0, 0.0), vec2(1000.0, 800.0))
    }
    const SIZE: Vec2 = Vec2::new(200.0, 40.0);
    // The world-space gap (in cells) at zoom 1, matching `selection_overlay`.
    const GAP: f32 = OVERLAY_BLOCK_GAP_CELLS * GRID_SIZE;

    /// The full chrome — main menu, toolbar, history cluster, title block,
    /// selection overlay over a selected block — must settle once icons load
    /// and each piece has measured itself (see [`crate::tools::settle`]).
    #[test]
    fn idle_chrome_settles() {
        use crate::path::BlockPath;
        use crate::tools::commands::{CommandContext, CommandSet, History};
        use crate::tools::resize_block::ResizeBlock;
        use crate::widget::test_fixtures::{self as fx, Scene};
        use blockworx_doc::fixtures::block_id;
        let b = block_id(1);
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(80.0, 80.0)),
            ),
            fx::titled(1, "core"),
        ]);
        let mut debug_marks = false;
        let mut nav = false;
        let mut prefs = Preferences::default();
        let mut rename_draft = String::new();
        let sel_screen = Some(Rect::from_min_size(pos2(400.0, 400.0), vec2(120.0, 90.0)));
        let settle = crate::tools::settle::probe(30, |ui| {
            let viewport = Rect::from_min_size(pos2(0.0, 0.0), vec2(1000.0, 800.0));
            let tool: crate::tools::tool::Tool = ResizeBlock::Selected {
                shape: ShapeId::Rect(b),
            }
            .into();
            // A path with names in it: the title block sizes itself to its
            // widest line, so an idle probe must include one.
            let mut path = BlockPath::empty();
            path.push(b);
            let mut commands = {
                let drawing = scene.drawing();
                CommandSet::available(&CommandContext {
                    tool: &tool,
                    data: &drawing,
                    history: History {
                        can_undo: true,
                        can_redo: false,
                    },
                    current_lock: InterfaceLock::Unlocked,
                    writability: crate::doc::Writability::Writable,
                    head: blockworx_doc::rev::Rev::ZERO,
                    saving: crate::doc::Saving::Withheld,
                    viewing: crate::doc::Viewing::Head,
                })
            };
            let (_, menu_rect) = crate::tools::main_menu::main_menu(
                &mut commands,
                crate::tools::main_menu::MainMenu {
                    prefs: &mut prefs,
                    recent: &[],
                    saving: crate::doc::Saving::Withheld,
                    document: crate::tools::file_menu::Document {
                        name: "engine",
                        draft: &mut rename_draft,
                        renaming: crate::doc::Renaming::Withheld,
                    },
                },
                viewport,
                ui,
            );
            let compass = toolbar(
                &mut commands,
                ToolbarProps {
                    selected: ToolName::Select,
                    toggles: ViewToggles {
                        debug_marks: &mut debug_marks,
                    },
                    nav: NavCluster {
                        history: crate::tools::nav_tree::PathHistory {
                            can_back: false,
                            can_forward: false,
                        },
                        nav_open: &mut nav,
                    },
                },
                viewport,
                ui,
            )
            .compass;
            assert!(
                compass.is_positive(),
                "the navigator popup needs the compass rect to hang from"
            );
            let mut panel_open = false;
            let _ = history_overlay(
                &mut commands,
                HistoryCluster {
                    panel_open: &mut panel_open,
                    viewing: Viewing::Head,
                    head: blockworx_doc::rev::Rev::ZERO,
                    steps: UndoSteps::default(),
                },
                viewport,
                ui,
            );
            {
                let indexed = scene.indexed();
                let block = crate::tools::title_block::TitleBlock {
                    name: "chrome".to_owned(),
                    author: "ada".to_owned(),
                    rev: blockworx_doc::rev::Rev::ZERO,
                    date: None,
                    from: None,
                };
                let theme = Theme::default();
                let _ = crate::tools::title_block::draw(
                    ui,
                    viewport,
                    &theme,
                    &block,
                    crate::doc::Writability::Writable,
                    &indexed,
                    &path,
                );
            }
            crate::tools::notices::draw(
                ui,
                viewport,
                menu_rect,
                &[crate::tools::notices::Notice::Standing(
                    "Read-only \u{2014} another blockworx has this container open".to_owned(),
                )],
            );
            let drawing = scene.drawing();
            let theme = Theme::default();
            let _ = selection_overlay(
                &mut commands,
                &drawing,
                &theme,
                None,
                sel_screen,
                viewport,
                crate::canvas::Zoom::unity(),
                ui,
            );
        });
        crate::tools::settle::assert_settles(&settle, 6);
    }

    /// What the selection overlay drew for a wire: every control it laid
    /// out, the subset a click could actually fire, and the bar it
    /// measured itself as.
    #[derive(Clone, Copy)]
    struct Controls {
        drawn: usize,
        invocable: usize,
        bar: Rect,
    }

    impl Default for Controls {
        fn default() -> Self {
            Controls {
                drawn: 0,
                invocable: 0,
                bar: Rect::NOTHING,
            }
        }
    }

    /// Whether the selection overlay shows for a selected wire in a session
    /// of this `writability`, and what it drew.
    fn route_overlay(writability: crate::doc::Writability) -> (bool, Controls) {
        route_overlay_with(
            writability,
            crate::tools::commands::History {
                can_undo: false,
                can_redo: false,
            },
        )
    }

    /// [`route_overlay`], with the frame's undo/redo availability spelled
    /// out — those commands draw controls elsewhere, so the overlay must
    /// be indifferent to them.
    fn route_overlay_with(
        writability: crate::doc::Writability,
        history: crate::tools::commands::History,
    ) -> (bool, Controls) {
        use crate::tools::commands::{CommandContext, CommandSet};
        use crate::widget::test_fixtures::two_blocks_with_a_routed_waypoint;
        let ctx = egui::Context::default();
        egui_extras::install_image_loaders(&ctx);
        let mut scene = two_blocks_with_a_routed_waypoint();
        let route = {
            let drawing = scene.drawing();
            let ids: Vec<_> = drawing.auto_routes().map(|(id, _)| id).collect();
            assert_eq!(ids.len(), 1, "the fixture carries exactly one wire");
            ids[0]
        };
        let tool: crate::tools::tool::Tool = crate::tools::EditRoute::Selected {
            id: route,
            anchor: pos2(0.0, 0.0),
        }
        .into();
        let screen = viewport();
        let mut shown = false;
        let mut controls = Controls::default();
        // Two frames: the overlay measures itself before it can place itself.
        for _ in 0..2 {
            ctx.clone()
                .run_ui(
                    egui::RawInput {
                        screen_rect: Some(screen),
                        ..Default::default()
                    },
                    |ui| {
                        let drawing = scene.drawing();
                        let mut commands = CommandSet::available(&CommandContext {
                            tool: &tool,
                            data: &drawing,
                            history,
                            current_lock: InterfaceLock::Unlocked,
                            writability,
                            head: blockworx_doc::rev::Rev::ZERO,
                            saving: crate::doc::Saving::Withheld,
                            viewing: crate::doc::Viewing::Head,
                        });
                        controls = Controls {
                            invocable: commands
                                .iter()
                                .filter(|cmd| drawn_in_overlay(cmd.id))
                                .count(),
                            drawn: overlay_controls(&commands).count(),
                            bar: Rect::NOTHING,
                        };
                        let theme = Theme::default();
                        let (_, corner) = selection_overlay(
                            &mut commands,
                            &drawing,
                            &theme,
                            None,
                            Some(Rect::from_min_size(pos2(400.0, 400.0), vec2(120.0, 90.0))),
                            screen,
                            crate::canvas::Zoom::unity(),
                            ui,
                        );
                        shown = corner.is_some();
                    },
                )
                .drop_without_applying_deltas();
        }
        controls.bar = ctx
            .data(|d| {
                d.get_temp::<(Vec<CommandId>, Rect)>(Panel::SelectionButtons.measurement("rect"))
            })
            .map_or(Rect::NOTHING, |(_, rect)| rect);
        (shown, controls)
    }

    /// One frame of the overlay for `tool` against `scene`, on a persistent
    /// context: where the bar's corner landed (`None` while it hides), and
    /// how many shapes the frame actually painted — the overlay is the only
    /// thing this harness draws, so a hidden frame must paint zero.
    fn overlay_frame(
        ctx: &egui::Context,
        tool: &crate::tools::tool::Tool,
        scene: &mut crate::widget::test_fixtures::Scene,
    ) -> (Option<egui::Pos2>, usize) {
        use crate::tools::commands::{CommandContext, CommandSet, History};
        let screen = viewport();
        let mut corner = None;
        let mut out = ctx.clone().run_ui(
            egui::RawInput {
                screen_rect: Some(screen),
                ..Default::default()
            },
            |ui| {
                let drawing = scene.drawing();
                let mut commands = CommandSet::available(&CommandContext {
                    tool,
                    data: &drawing,
                    history: History {
                        can_undo: false,
                        can_redo: false,
                    },
                    current_lock: InterfaceLock::Unlocked,
                    writability: crate::doc::Writability::Writable,
                    head: blockworx_doc::rev::Rev::ZERO,
                    saving: crate::doc::Saving::Withheld,
                    viewing: crate::doc::Viewing::Head,
                });
                let theme = Theme::default();
                let (_, at) = selection_overlay(
                    &mut commands,
                    &drawing,
                    &theme,
                    None,
                    Some(Rect::from_min_size(pos2(400.0, 400.0), vec2(120.0, 90.0))),
                    screen,
                    crate::canvas::Zoom::unity(),
                    ui,
                );
                corner = at;
            },
        );
        out.textures_delta.clear();
        (corner, painted(&out.shapes))
    }

    /// Leaf shapes in a frame's output, `Noop`s excluded.
    fn painted(shapes: &[egui::epaint::ClippedShape]) -> usize {
        fn leaves(shape: &egui::Shape) -> usize {
            match shape {
                egui::Shape::Noop => 0,
                egui::Shape::Vec(shapes) => shapes.iter().map(leaves).sum(),
                _ => 1,
            }
        }
        shapes.iter().map(|clipped| leaves(&clipped.shape)).sum()
    }

    /// Switching what is selected must never paint the new bar with the old
    /// bar's measurement: the frame after a switch is an invisible sizing
    /// pass, and the next frame shows the bar measured for its own controls.
    /// Steady-state frames stay visible — the pass runs only on change.
    #[test]
    fn switching_selections_takes_a_hidden_sizing_frame_instead_of_flashing() {
        use crate::tools::resize_block::ResizeBlock;
        use crate::widget::test_fixtures::two_blocks_with_a_routed_waypoint;
        let ctx = egui::Context::default();
        egui_extras::install_image_loaders(&ctx);
        let mut scene = two_blocks_with_a_routed_waypoint();
        let route = {
            let drawing = scene.drawing();
            let ids: Vec<_> = drawing.auto_routes().map(|(id, _)| id).collect();
            assert_eq!(ids.len(), 1, "the fixture carries exactly one wire");
            ids[0]
        };
        let wire: crate::tools::tool::Tool = crate::tools::EditRoute::Selected {
            id: route,
            anchor: pos2(0.0, 0.0),
        }
        .into();
        let block: crate::tools::tool::Tool = ResizeBlock::Selected {
            shape: crate::shape::ShapeId::Rect(blockworx_doc::fixtures::block_id(1)),
        }
        .into();

        let (corner, painted) = overlay_frame(&ctx, &wire, &mut scene);
        assert!(
            corner.is_none(),
            "the first frame ever should be a hidden sizing pass",
        );
        assert_eq!(
            painted, 0,
            "the sizing pass painted {painted} shape(s) — the flash the user \
             sees at the click point before the bar snaps into place",
        );
        let (corner, painted) = overlay_frame(&ctx, &wire, &mut scene);
        let wire_bar = corner.expect("the wire's bar shows once measured");
        assert!(painted > 0, "a shown bar paints");
        assert!(
            overlay_frame(&ctx, &wire, &mut scene).0.is_some(),
            "an unchanged selection must not flicker",
        );

        let (corner, painted) = overlay_frame(&ctx, &block, &mut scene);
        assert!(
            corner.is_none(),
            "the switch frame drew the block's bar with the wire's measurement",
        );
        assert_eq!(painted, 0, "the switch frame painted {painted} shape(s)");
        let block_bar = overlay_frame(&ctx, &block, &mut scene)
            .0
            .expect("the block's bar shows once measured");
        assert_ne!(
            wire_bar, block_bar,
            "precondition: the two bars measure apart, or a stale placement would be invisible",
        );

        assert!(
            overlay_frame(&ctx, &wire, &mut scene).0.is_none(),
            "switching back re-measures too — the memory holds one bar, not a history",
        );
        assert_eq!(
            overlay_frame(&ctx, &wire, &mut scene).0,
            Some(wire_bar),
            "the wire's bar returns exactly where it was",
        );
    }

    /// A selected wire in a read-only session shows the same overlay it
    /// shows writable — every control drawn, none invocable — because a
    /// bar that vanishes reads as a bug while a bar drawn disabled reads
    /// as "not now" (docs/ui-issues.md follow-up). The writable half is
    /// the precondition: the same selection carries live controls when it
    /// can be edited.
    #[test]
    fn the_selection_overlay_draws_its_withheld_controls_disabled() {
        let (shown, writable) = route_overlay(crate::doc::Writability::Writable);
        assert!(
            writable.invocable > 0 && shown,
            "a writable wire lost its overlay",
        );
        assert_eq!(writable.invocable, writable.drawn);
        let (shown, read_only) = route_overlay(crate::doc::Writability::ReadOnly);
        assert!(shown, "the read-only overlay vanished instead of disabling");
        assert_eq!(
            read_only.drawn, writable.drawn,
            "read-only dropped controls instead of disabling them",
        );
        assert_eq!(
            read_only.invocable, 0,
            "a read-only wire kept {} invocable verb(s)",
            read_only.invocable,
        );
    }

    /// A selection's control list is fixed — only enablement varies — so
    /// the bar it measures itself as is fixed too: a read-only wire's
    /// overlay is exactly the writable one's, to the pixel.
    #[test]
    fn a_read_only_overlay_measures_the_same_bar_as_a_writable_one() {
        let (_, writable) = route_overlay(crate::doc::Writability::Writable);
        let (_, read_only) = route_overlay(crate::doc::Writability::ReadOnly);
        assert!(
            writable.bar.is_positive(),
            "precondition: the overlay measured itself ({:?})",
            writable.bar,
        );
        assert_eq!(read_only.bar.size(), writable.bar.size());
    }

    /// The bar hugs its controls: a command that draws nothing here — undo
    /// and redo belong to the history cluster — must take no room either.
    /// Each control sits in a child `Ui` of its own, and a child laid out
    /// for a command that renders nothing still advances the row by one
    /// item spacing, which is how the bar came adrift from its buttons.
    #[test]
    fn commands_the_overlay_does_not_draw_do_not_widen_it() {
        use crate::tools::commands::History;
        let (_, quiet) = route_overlay_with(
            crate::doc::Writability::Writable,
            History {
                can_undo: false,
                can_redo: false,
            },
        );
        let (_, busy) = route_overlay_with(
            crate::doc::Writability::Writable,
            History {
                can_undo: true,
                can_redo: true,
            },
        );
        assert!(quiet.bar.is_positive(), "precondition: the bar measured");
        assert_eq!(
            busy.drawn, quiet.drawn,
            "precondition: undo and redo draw no control in the overlay",
        );
        assert_eq!(
            busy.bar.size(),
            quiet.bar.size(),
            "two commands the overlay never draws widened it anyway",
        );
    }

    /// Click the toolbar's `mode` button in a session of this `writability`
    /// and report what it dispatched. The toolbar is laid out for real and
    /// clicked through egui's own hit-testing against the frame's real
    /// [`CommandSet`], so a button that draws enabled when the registry
    /// withholds its command fails here.
    fn click_the_toolbar_tool(
        mode: ToolName,
        writability: crate::doc::Writability,
    ) -> Option<Action> {
        use crate::tools::commands::{CommandContext, CommandSet, History};
        use crate::widget::test_fixtures::Scene;
        const FRAMES: usize = 10;
        let ctx = egui::Context::default();
        egui_extras::install_image_loaders(&ctx);
        let mut scene = Scene::new(Vec::new());
        let tool: crate::tools::tool::Tool = crate::tools::SelectTool.into();
        let screen = viewport();
        let mut debug_marks = false;
        let mut nav_open = false;

        let mut button = Rect::NOTHING;
        let mut fired = None;
        for frame in 0..FRAMES {
            let clicking = frame == FRAMES - 1;
            let mut input = egui::RawInput {
                screen_rect: Some(screen),
                #[expect(
                    clippy::cast_precision_loss,
                    reason = "a frame count, not a measurement"
                )]
                time: Some(frame as f64 * 0.016),
                ..Default::default()
            };
            if clicking {
                assert!(
                    button.is_positive(),
                    "the {mode:?} button never laid out: {button:?}",
                );
                let pos = button.center();
                input.events = vec![
                    egui::Event::PointerMoved(pos),
                    egui::Event::PointerButton {
                        pos,
                        button: egui::PointerButton::Primary,
                        pressed: true,
                        modifiers: egui::Modifiers::NONE,
                    },
                    egui::Event::PointerButton {
                        pos,
                        button: egui::PointerButton::Primary,
                        pressed: false,
                        modifiers: egui::Modifiers::NONE,
                    },
                ];
            }
            ctx.clone()
                .run_ui(input, |ui| {
                    let mut commands = {
                        let drawing = scene.drawing();
                        CommandSet::available(&CommandContext {
                            tool: &tool,
                            data: &drawing,
                            history: History {
                                can_undo: false,
                                can_redo: false,
                            },
                            current_lock: InterfaceLock::Unlocked,
                            writability,
                            head: blockworx_doc::rev::Rev::ZERO,
                            saving: crate::doc::Saving::Withheld,
                            viewing: crate::doc::Viewing::Head,
                        })
                    };
                    let ToolbarFrame {
                        action, tool_rects, ..
                    } = toolbar(
                        &mut commands,
                        ToolbarProps {
                            selected: ToolName::Select,
                            toggles: ViewToggles {
                                debug_marks: &mut debug_marks,
                            },
                            nav: NavCluster {
                                history: crate::tools::nav_tree::PathHistory {
                                    can_back: false,
                                    can_forward: false,
                                },
                                nav_open: &mut nav_open,
                            },
                        },
                        screen,
                        ui,
                    );
                    button = tool_rects
                        .iter()
                        .find_map(|&(name, rect)| (name == mode).then_some(rect))
                        .expect("every toolbar tool reports its rect, enabled or not");
                    if clicking {
                        fired = action;
                    }
                })
                .drop_without_applying_deltas();
        }
        fired
    }

    /// A read-only session's toolbar still shows every tool — the strip keeps
    /// its shape — but the authoring ones are dead, and the neutral Select
    /// beside them is not. Clicked through the real layout, so a button that
    /// merely *looks* disabled would fail here.
    #[test]
    fn a_read_only_toolbar_arms_select_but_no_authoring_tool() {
        use crate::doc::Writability;
        assert!(matches!(
            click_the_toolbar_tool(ToolName::NewBlock, Writability::Writable),
            Some(Action::SwitchTool(_)),
            // Without this the refusal below could be a mis-aimed click.
        ));
        assert!(
            click_the_toolbar_tool(ToolName::NewBlock, Writability::ReadOnly).is_none(),
            "a read-only toolbar armed the New Block tool",
        );
        assert!(
            matches!(
                click_the_toolbar_tool(ToolName::Select, Writability::ReadOnly),
                Some(Action::SwitchTool(_)),
            ),
            "a read-only toolbar refused Select, which authors nothing",
        );
    }

    /// Every action a click along `row` dispatched, at [`STEP`] intervals
    /// across it. How a test asks which verbs a strip of identical icon
    /// buttons can reach, without hard-coding where in the strip each one
    /// landed: the strip is laid out for real and clicked through egui's own
    /// hit-testing, so a control that moved, shrank, went dead, or stopped
    /// taking clicks shows up as a missing verb. Clicks past the strip's end
    /// land on nothing and dispatch nothing.
    fn actions_along(
        row: egui::Rect,
        mut show: impl FnMut(&mut egui::Ui) -> Option<Action>,
    ) -> Vec<Action> {
        /// Comfortably finer than a 14px icon button, so no button is stepped
        /// over.
        const STEP: f32 = 6.0;
        let mut chrome = crate::tools::painted::Chrome::new(viewport());
        let mut fired = Vec::new();
        chrome.settle(|ui| {
            let _ = show(ui);
        });
        let mut x = row.left();
        while x <= row.right() {
            chrome.click_at(pos2(x, row.center().y), |ui| {
                if let Some(action) = show(ui) {
                    fired.push(action);
                }
            });
            x += STEP;
        }
        fired
    }

    /// One history cluster, laid out for real, with `drive` given the
    /// clock button's rect and a frame closure to click through. Reports
    /// what the clicks dispatched and where the panel toggle ended up.
    fn history_cluster<R>(
        history: crate::tools::commands::History,
        viewing: Viewing,
        head: blockworx_doc::rev::Rev,
        drive: impl FnOnce(Rect, &mut dyn FnMut(&mut egui::Ui) -> Option<Action>) -> R,
    ) -> (R, bool) {
        use crate::tools::commands::{CommandContext, CommandSet};
        use crate::widget::test_fixtures::Scene;
        let mut scene = Scene::new(Vec::new());
        let tool: crate::tools::tool::Tool = crate::tools::SelectTool.into();
        let screen = viewport();
        let mut panel_open = false;
        // Written by every frame and read after them, so the closure holds
        // only a shared borrow of it.
        let clock = std::cell::Cell::new(Rect::NOTHING);
        let mut frame = |ui: &mut egui::Ui| {
            let mut commands = {
                let drawing = scene.drawing();
                CommandSet::available(&CommandContext {
                    tool: &tool,
                    data: &drawing,
                    history,
                    current_lock: InterfaceLock::Unlocked,
                    writability: viewing.writability(),
                    head,
                    saving: crate::doc::Saving::Withheld,
                    viewing,
                })
            };
            let frame = history_overlay(
                &mut commands,
                HistoryCluster {
                    panel_open: &mut panel_open,
                    viewing,
                    head,
                    steps: UndoSteps::default(),
                },
                screen,
                ui,
            );
            clock.set(frame.clock);
            frame.action
        };
        let mut chrome = crate::tools::painted::Chrome::new(screen);
        chrome.settle(|ui| {
            let _ = frame(ui);
        });
        let clock = clock.get();
        assert!(clock.is_positive(), "the history cluster never laid out");
        let out = drive(clock, &mut frame);
        (out, panel_open)
    }

    /// Every verb a scan across the cluster *past the clock* dispatched.
    fn history_cluster_run(
        history: crate::tools::commands::History,
        viewing: Viewing,
        head: blockworx_doc::rev::Rev,
    ) -> (Vec<Action>, bool) {
        history_cluster(history, viewing, head, |clock, frame| {
            let row =
                Rect::from_min_max(clock.right_top(), clock.right_bottom() + vec2(200.0, 0.0));
            actions_along(row, frame)
        })
    }

    /// One click on the clock button itself.
    fn click_the_clock(viewing: Viewing, head: blockworx_doc::rev::Rev) -> (Option<Action>, bool) {
        history_cluster(no_undo(), viewing, head, |clock, frame| {
            let mut chrome = crate::tools::painted::Chrome::new(viewport());
            let mut fired = None;
            chrome.settle(|ui| {
                let _ = frame(ui);
            });
            chrome.click_at(clock.center(), |ui| {
                if let Some(action) = frame(ui) {
                    fired = Some(action);
                }
            });
            fired
        })
    }

    fn no_undo() -> crate::tools::commands::History {
        crate::tools::commands::History {
            can_undo: false,
            can_redo: false,
        }
    }

    /// The cluster's verbs past the clock, at head.
    fn history_cluster_verbs(history: crate::tools::commands::History) -> Vec<Action> {
        history_cluster_run(history, Viewing::Head, blockworx_doc::rev::Rev::ZERO).0
    }

    /// Undo and Redo are the history cluster's, and a click on each reaches
    /// the registry.
    #[test]
    fn the_history_cluster_undoes_and_redoes() {
        let verbs = history_cluster_verbs(crate::tools::commands::History {
            can_undo: true,
            can_redo: true,
        });
        assert!(
            verbs.iter().any(|a| matches!(a, Action::Undo)),
            "the history cluster dispatched no Undo ({} verbs in all)",
            verbs.len(),
        );
        assert!(
            verbs.iter().any(|a| matches!(a, Action::Redo)),
            "the history cluster dispatched no Redo ({} verbs in all)",
            verbs.len(),
        );
    }

    /// With nothing to redo the control is there to be seen — but dead. The
    /// sibling test above is what proves this one is not merely missing the
    /// button.
    #[test]
    fn the_redo_button_is_dead_with_nothing_to_redo() {
        let verbs = history_cluster_verbs(crate::tools::commands::History {
            can_undo: true,
            can_redo: false,
        });
        assert!(
            verbs.iter().any(|a| matches!(a, Action::Undo)),
            "precondition: the live half of the cluster still dispatches",
        );
        assert!(
            !verbs.iter().any(|a| matches!(a, Action::Redo)),
            "a dead Redo dispatched anyway",
        );
    }

    /// While a past rev is on the canvas the pair becomes a tape player:
    /// a step back, a step forward, and a seek to the latest rev. Driven
    /// through the cluster's own layout, so an icon that moved or went
    /// dead shows up as a missing verb.
    #[test]
    fn viewing_the_past_turns_the_cluster_into_a_tape_player() {
        use blockworx_doc::fixtures::rev;
        let (verbs, _) = history_cluster_run(no_undo(), Viewing::Past(rev(2)), rev(4));
        let dispatched = |wanted: fn(&Action) -> bool| verbs.iter().any(wanted);
        assert!(
            dispatched(|a| matches!(a, Action::ViewRev(r) if *r == rev(1))),
            "the tape player will not step back ({} verbs)",
            verbs.len(),
        );
        assert!(
            dispatched(|a| matches!(a, Action::ViewRev(r) if *r == rev(3))),
            "the tape player will not step forward ({} verbs)",
            verbs.len(),
        );
        assert!(
            dispatched(|a| matches!(a, Action::ViewHead)),
            "the tape player will not seek to latest ({} verbs)",
            verbs.len(),
        );
        assert!(
            !dispatched(|a| matches!(a, Action::Undo | Action::Redo)),
            "undo and redo act on a head nobody is looking at",
        );
    }

    /// A step back off the oldest rev has nowhere to go, so `|<` is drawn
    /// dead — the sibling above is what proves this is not merely a
    /// mis-aimed scan.
    #[test]
    fn the_step_back_button_is_dead_at_the_oldest_rev() {
        use blockworx_doc::fixtures::rev;
        let (verbs, _) = history_cluster_run(no_undo(), Viewing::Past(rev(1)), rev(4));
        assert!(
            verbs
                .iter()
                .any(|a| matches!(a, Action::ViewRev(r) if *r == rev(2))),
            "precondition: the live half of the tape still steps",
        );
        assert!(
            !verbs
                .iter()
                .any(|a| matches!(a, Action::ViewRev(r) if *r < rev(1))),
            "a dead step-back dispatched anyway",
        );
    }

    /// The clock opens and closes the panel, and does nothing else — at
    /// head and in the past alike. It used to double as "return to
    /// current" while a rev was showing, so one control did two unrelated
    /// things depending on state, and the panel could not be opened from
    /// the past at all (docs/ui-issues-2.md, item 4).
    #[test]
    fn the_clock_only_ever_toggles_the_panel() {
        use blockworx_doc::fixtures::rev;
        for viewing in [Viewing::Head, Viewing::Past(rev(2))] {
            let (fired, open) = click_the_clock(viewing, rev(4));
            assert!(
                fired.is_none(),
                "{viewing:?}: the clock dispatched a verb instead of opening the panel",
            );
            assert!(open, "{viewing:?}: the clock did not open the panel");
        }
    }

    /// The navigation group's verbs, clicked out of the toolbar itself: the
    /// row runs from the compass to the toolbar's right edge.
    fn toolbar_nav_verbs(history: crate::tools::nav_tree::PathHistory) -> Vec<Action> {
        use crate::tools::commands::{CommandContext, CommandSet};
        use crate::tools::resize_block::ResizeBlock;
        use crate::widget::test_fixtures::{self as fx, Scene};
        use blockworx_doc::fixtures::block_id;
        // A child inside a parent, viewed from inside the parent: Enter
        // wants a block selected and Up wants a level above the one on
        // the canvas, which the document root does not have.
        let mut scene = Scene::new(vec![
            fx::block_in(
                1,
                Scope::Root,
                Rect::from_min_max(pos2(0.0, 0.0), pos2(200.0, 200.0)),
            ),
            fx::titled(1, "core"),
            fx::block_in(
                2,
                Scope::Block(block_id(1)),
                Rect::from_min_max(pos2(20.0, 20.0), pos2(80.0, 80.0)),
            ),
            fx::titled(2, "inner"),
        ])
        .inside(block_id(1));
        // Entering a block is a verb about the selection, so one is selected.
        let tool: crate::tools::tool::Tool = ResizeBlock::Selected {
            shape: ShapeId::Rect(block_id(2)),
        }
        .into();
        let screen = viewport();
        let mut debug_marks = false;
        let mut nav_open = false;
        let compass = std::cell::Cell::new(Rect::NOTHING);
        let mut frame = |ui: &mut egui::Ui| {
            let mut commands = {
                let drawing = scene.drawing();
                CommandSet::available(&CommandContext {
                    tool: &tool,
                    data: &drawing,
                    history: crate::tools::commands::History {
                        can_undo: false,
                        can_redo: false,
                    },
                    current_lock: InterfaceLock::Unlocked,
                    writability: crate::doc::Writability::Writable,
                    head: blockworx_doc::rev::Rev::ZERO,
                    saving: crate::doc::Saving::Withheld,
                    viewing: crate::doc::Viewing::Head,
                })
            };
            let frame = toolbar(
                &mut commands,
                ToolbarProps {
                    selected: ToolName::Select,
                    toggles: ViewToggles {
                        debug_marks: &mut debug_marks,
                    },
                    nav: NavCluster {
                        history,
                        nav_open: &mut nav_open,
                    },
                },
                screen,
                ui,
            );
            compass.set(frame.compass);
            frame.action
        };
        let mut chrome = crate::tools::painted::Chrome::new(screen);
        chrome.settle(|ui| {
            let _ = frame(ui);
        });
        let compass = compass.get();
        assert!(
            compass.is_positive(),
            "the toolbar drew no compass to scan from",
        );
        let row = Rect::from_min_max(
            compass.right_top(),
            compass.right_bottom() + vec2(200.0, 0.0),
        );
        actions_along(row, frame)
    }

    /// The navigation functions moved onto the toolbar, and they are the same
    /// four: back and forward through the path history, into a block and up a
    /// level. Driven through the toolbar's own layout and the frame's real
    /// [`CommandSet`], so a button that draws but dispatches nothing fails.
    #[test]
    fn the_toolbar_navigates_the_hierarchy_and_the_path_history() {
        let verbs = toolbar_nav_verbs(crate::tools::nav_tree::PathHistory {
            can_back: true,
            can_forward: true,
        });
        for wanted in ["back", "forward", "into the block", "up a level"] {
            let found = verbs.iter().any(|action| {
                matches!(
                    (wanted, action),
                    ("back", Action::PathBack)
                        | ("forward", Action::PathForward)
                        | ("into the block", Action::ExpandBlock(_))
                        | ("up a level", Action::GoUp)
                )
            });
            assert!(
                found,
                "the toolbar will not go {wanted} ({} verbs in all)",
                verbs.len(),
            );
        }
    }

    /// With nowhere to go back to, the arrow is drawn and dead — the paradigm
    /// the whole toolbar keeps.
    #[test]
    fn the_path_arrows_are_dead_with_no_history_to_walk() {
        let verbs = toolbar_nav_verbs(crate::tools::nav_tree::PathHistory {
            can_back: false,
            can_forward: false,
        });
        assert!(
            verbs.iter().any(|a| matches!(a, Action::GoUp)),
            "precondition: the live half of the group still dispatches",
        );
        assert!(
            !verbs
                .iter()
                .any(|a| matches!(a, Action::PathBack | Action::PathForward)),
            "a dead path arrow dispatched anyway",
        );
    }

    #[test]
    fn accent_swatch_maps_index_to_its_accent_role() {
        use blockworx_doc::id::BlockId;
        let block = RoleTarget::Block(BlockId::NULL);
        assert_eq!(accent_display_role(block, Some(0)), Role::Accent0);
        assert_eq!(accent_display_role(block, Some(7)), Role::Accent7);
        // An unset (or out-of-range) accent falls back to the plain default.
        assert_eq!(accent_display_role(block, None), Role::AccentDefault);
        assert_eq!(accent_display_role(block, Some(9)), Role::AccentDefault);
    }

    #[test]
    fn accent_swatch_uses_each_targets_own_unaccented_stroke() {
        use blockworx_doc::id::{AreaId, TextId};
        // With no accent set, areas/text boxes preview their own stroke role
        // rather than the generic `AccentDefault`, matching the picker's cell.
        let area = RoleTarget::Area(AreaId::NULL);
        let text = RoleTarget::Text(TextId::NULL);
        assert_eq!(accent_display_role(area, None), Role::AreaStroke);
        assert_eq!(accent_display_role(text, None), Role::TextBoxStroke);
        // A set accent still wins over the target-specific default.
        assert_eq!(accent_display_role(area, Some(2)), Role::Accent2);
    }

    #[test]
    fn lock_toggle_icon_depicts_the_blocks_current_state() {
        let (locked_icon, locked_hover) = lock_toggle_icon(InterfaceLock::Locked);
        let (unlocked_icon, unlocked_hover) = lock_toggle_icon(InterfaceLock::Unlocked);
        // Like a physical padlock: closed shackle when locked, open when not
        // (icons compare by URI, since `ImageSource` is not `PartialEq`).
        assert_eq!(locked_icon.uri(), LOCK_ICON.uri());
        assert_eq!(unlocked_icon.uri(), UNLOCK_ICON.uri());
        assert_ne!(locked_icon.uri(), unlocked_icon.uri());
        // The hover text names the action a click performs, not the state.
        assert_eq!(locked_hover, "Unlock pins");
        assert_eq!(unlocked_hover, "Lock pins");
    }

    /// Guards the padlock artwork itself: `lock_toggle_icon` picking the right
    /// *file* only helps if that file actually draws the right shackle. Both
    /// padlocks share a body rect; only the shackle path differs, and the closed
    /// one returns to the body on both sides (`V4` down the right leg).
    #[test]
    fn padlock_svgs_draw_a_closed_and_an_open_shackle() {
        let closed = include_str!("../../icons/icon-lock.svg");
        let open = include_str!("../../icons/icon-unlock.svg");
        assert!(
            closed.contains(r#"d="M8 11V7a4 4 0 0 1 8 0v4""#),
            "{closed}"
        );
        assert!(open.contains(r#"d="M8 11V7a4 4 0 0 1 7.5-2""#), "{open}");
    }

    /// Rising a level is the toolbar's job now, so the selection overlay draws
    /// no control for it; entering a block — a verb about the selection — keeps
    /// its button.
    #[test]
    fn the_selection_overlay_offers_enter_but_not_go_up() {
        assert!(overlay_icon(CommandId::GoUp).is_none());
        assert!(overlay_icon(CommandId::ExpandBlock).is_some());
    }

    /// The import icon is the export icon's conjugate: the same tray, with the
    /// arrow coming *into* it. Guards the artwork, not just the file names.
    /// Enter and exit are a pair, after Bootstrap's box-arrow-in-down /
    /// box-arrow-up: one box, one arrow, pointing opposite ways.
    #[test]
    fn the_hierarchy_icons_share_a_box_and_oppose_their_arrows() {
        let enter = include_str!("../../icons/icon-expand.svg");
        let exit = include_str!("../../icons/icon-exit.svg");
        let box_path =
            r#"d="M9 9H5a2 2 0 0 0-2 2v8a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-8a2 2 0 0 0-2-2h-4""#;
        assert!(enter.contains(box_path), "{enter}");
        assert!(exit.contains(box_path), "{exit}");
        // Into the box, and out of it.
        assert!(enter.contains(r#"points="8 11 12 15 16 11""#), "{enter}");
        assert!(exit.contains(r#"points="8 6 12 2 16 6""#), "{exit}");
    }

    /// The tape trio, after a transport panel: a stop bar on the side the
    /// tape runs *to*, and one chevron per step — two for the seek, which
    /// runs past every rev between here and the latest. Guards the
    /// artwork, not just the file names.
    #[test]
    fn the_tape_icons_bar_the_end_they_travel_to() {
        let back = include_str!("../../icons/icon-step-back.svg");
        let forward = include_str!("../../icons/icon-step-forward.svg");
        let latest = include_str!("../../icons/icon-seek-latest.svg");
        assert!(
            back.contains(r#"<line x1="7" y1="5" x2="7" y2="19"/>"#),
            "{back}",
        );
        assert!(
            forward.contains(r#"<line x1="17" y1="5" x2="17" y2="19"/>"#),
            "{forward}",
        );
        assert!(
            latest.contains(r#"<line x1="21" y1="5" x2="21" y2="19"/>"#),
            "{latest}",
        );
        assert_eq!(back.matches("<polyline").count(), 1);
        assert_eq!(forward.matches("<polyline").count(), 1);
        assert_eq!(
            latest.matches("<polyline").count(),
            2,
            "the seek icon is the double chevron",
        );
        // The house style: 24×24, stroke-2, no fill.
        for icon in [back, forward, latest] {
            assert!(icon.contains(r#"viewBox="0 0 24 24""#), "{icon}");
            assert!(icon.contains(r#"stroke-width="2""#), "{icon}");
            assert!(icon.contains(r#"fill="none""#), "{icon}");
        }
    }

    #[test]
    fn the_import_icon_reverses_the_export_arrow_over_the_same_tray() {
        let export = include_str!("../../icons/icon-export.svg");
        let import = include_str!("../../icons/icon-import.svg");
        let tray = r#"d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4""#;
        assert!(export.contains(tray), "{export}");
        assert!(import.contains(tray), "{import}");
        // Export's chevron points up and away; import's points down and in.
        assert!(export.contains(r#"points="17 8 12 3 7 8""#), "{export}");
        assert!(import.contains(r#"points="7 10 12 15 17 10""#), "{import}");
    }

    #[test]
    fn places_above_a_mid_canvas_selection() {
        let sel = Rect::from_min_size(pos2(400.0, 400.0), vec2(100.0, 100.0));
        let p = place_overlay(sel, viewport(), SIZE, GAP, &[]).unwrap();
        // Just above the top edge, centered on the selection.
        assert_eq!(p.y, 400.0 - GAP - SIZE.y);
        assert_eq!(p.x, 450.0 - SIZE.x / 2.0);
    }

    #[test]
    fn flips_below_when_the_selection_is_too_near_the_top() {
        let sel = Rect::from_min_size(pos2(400.0, 100.0), vec2(100.0, 100.0));
        let p = place_overlay(sel, viewport(), SIZE, GAP, &[]).unwrap();
        // Above would breach the top gap, so it lands just below the bottom edge.
        assert_eq!(p.y, 200.0 + GAP);
    }

    #[test]
    fn pins_to_bottom_center_when_the_selection_fills_the_screen() {
        let sel = Rect::from_min_size(pos2(-100.0, -100.0), vec2(1200.0, 1000.0));
        let vp = viewport();
        let p = place_overlay(sel, vp, SIZE, GAP, &[]).unwrap();
        assert_eq!(p.y, vp.bottom() - OVERLAY_BOTTOM_GAP - SIZE.y);
        assert_eq!(p.x, vp.center().x - SIZE.x / 2.0); // centered on the viewport
    }

    #[test]
    fn clamps_horizontally_within_the_viewport() {
        let sel = Rect::from_min_size(pos2(950.0, 400.0), vec2(40.0, 40.0));
        let vp = viewport();
        let p = place_overlay(sel, vp, SIZE, GAP, &[]).unwrap();
        assert_eq!(p.x, vp.right() - OVERLAY_EDGE_GAP - SIZE.x);
    }

    #[test]
    fn hides_when_the_overlay_is_wider_than_the_viewport() {
        let sel = Rect::from_min_size(pos2(400.0, 400.0), vec2(100.0, 100.0));
        assert!(place_overlay(sel, viewport(), vec2(1100.0, 40.0), GAP, &[]).is_none());
    }

    #[test]
    fn hides_when_below_would_sit_over_the_toolbar() {
        // Selection mostly scrolled off the top, only its bottom sliver visible
        // near the viewport top: above doesn't fit, and below — though there's
        // room beneath it — would land in the toolbar zone, so hide.
        let sel = Rect::from_min_size(pos2(400.0, -40.0), vec2(100.0, 80.0));
        assert!(place_overlay(sel, viewport(), SIZE, GAP, &[]).is_none());
    }

    #[test]
    fn flips_below_when_above_would_overlap_an_obstacle() {
        // A mid-canvas selection would normally place above, but a toolbar-shaped
        // obstacle covers that spot, so it lands below instead.
        let sel = Rect::from_min_size(pos2(400.0, 400.0), vec2(100.0, 100.0));
        let above = Rect::from_min_size(pos2(300.0, 300.0), vec2(400.0, 80.0));
        let p = place_overlay(sel, viewport(), SIZE, GAP, &[above]).unwrap();
        assert_eq!(p.y, 500.0 + GAP);
    }

    #[test]
    fn shifts_right_past_the_nav_dialog_instead_of_hiding() {
        // A tall left-edge nav dialog spanning the full height: a left-side
        // selection's centered overlay overlaps it both above and below, so rather
        // than hide, slide right to just past the dialog (at the above height).
        let sel = Rect::from_min_size(pos2(20.0, 400.0), vec2(60.0, 60.0));
        let nav = Rect::from_min_size(pos2(0.0, 0.0), vec2(260.0, 800.0));
        let p = place_overlay(sel, viewport(), SIZE, GAP, &[nav]).unwrap();
        assert_eq!(p.x, 260.0 + OVERLAY_EDGE_GAP); // just past the nav's right edge
        assert_eq!(p.y, 400.0 - GAP - SIZE.y); // still at the above height
    }

    #[test]
    fn hides_when_a_full_width_obstacle_blocks_every_landing() {
        // An obstacle covering the whole viewport leaves no clear x at any height,
        // so even with sideways sliding the overlay hides.
        let sel = Rect::from_min_size(pos2(400.0, 400.0), vec2(100.0, 100.0));
        let everything = Rect::from_min_size(pos2(0.0, 0.0), vec2(1000.0, 800.0));
        assert!(place_overlay(sel, viewport(), SIZE, GAP, &[everything]).is_none());
    }
}