blockworx/panels/

overlay.rs

//! The selection overlay, and the icon helpers the menus and the smaller
//! chrome draw their buttons with.
//!
//! The frame took the rest — the tools are
//! [`crate::shell::tool_cluster`], undo and redo are
//! [`crate::shell::top_bar`] — so what is left here is the surface the
//! whole shell is built around: controls scoped to what the user has
//! already selected.
//!
//! One list feeds three surfaces — the row, the overflow menu it spills
//! into, and the right-click menu that duplicates it — because a second list
//! is a second answer to "what applies here", and there is only one.
//! [`Bar`] is where the one list is ordered and cut: the selected thing's own
//! verbs first, then the clerical ones, and the first
//! [`INLINE_CONTROLS`](blockworx_kernel::bar::INLINE_CONTROLS) of
//! that order in the row.
//!
//! The intersection is degenerate here, and this says so rather than
//! computing one: every command a multi-shape selection offers is a verb over
//! the whole set — copy, cut, delete, export the selection as one diagram —
//! so the intersection is never partial. The per-member verbs (flip, accent,
//! lock) are absent from a multi-selection because their actions carry one
//! target each, not because an intersection dropped them; giving them
//! multi-target actions is an emitter change, and not this frame's.

use crate::canvas::convert::{IntoEgui as _, IntoGeom as _};
use crate::{
    canvas::Camera,
    edit::naming::InterfaceLock,
    export::ExportScope,
    panels::chrome::Panel,
    shell::{SafeArea, glass},
    tools::commands::{Act, Command, CommandId, CommandSet},
};
use blockworx_doc::values::PinDir;
use blockworx_kernel::bar::{self, Bar};
use blockworx_tools::commands::in_overlay;

/// 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,
}

/// Whether this frame's input asked for the right-click menu. Where it
/// opens is the pointer's own position, which egui remembers for the popup, so
/// there is nothing here to carry.
#[derive(Clone, Copy, PartialEq, Eq)]
pub enum RightClick {
    Asked,
    No,
}

impl From<bool> for RightClick {
    fn from(asked: bool) -> Self {
        if asked {
            RightClick::Asked
        } else {
            RightClick::No
        }
    }
}

const EXPAND_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-expand.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 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 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");
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 overflow button. An ellipsis rather than the hamburger, which is
/// the document menu's glyph and would say the wrong thing here.
const MORE_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-more.svg");
const EYE_ICON: egui::ImageSource<'static> = egui::include_image!("../../icons/icon-eye.svg");
const EYE_OFF_ICON: egui::ImageSource<'static> =
    egui::include_image!("../../icons/icon-eye-off.svg");
/// The one glyph the I/O control wears, whatever the pins are doing: the
/// arrow meeting a wall the user drew for it. The three direction glyphs
/// themselves live with the picker that offers them.
const PIN_TYPE_ICON: egui::ImageSource<'static> = crate::io_pin_picker::INPUT_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 menus and the smaller chrome.
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)
}

/// The line a run of list rows sits under — the history panel's day, the
/// palette's source. Stated once so two lists cannot part company over what
/// a group heading looks like: quiet, small, with air above it so the run
/// below reads as one.
pub(crate) fn group_heading(ui: &mut egui::Ui, text: &str) {
    ui.add_space(6.0);
    ui.label(egui::RichText::new(text).small().weak());
}

/// The bar wears the shell's own selection-bar shape, so its height is the
/// pill tier's one constant rather than a second number beside it.
const BAR: glass::Shape = glass::Shape::Bar;

/// The gap between two cells in the row — the mockup's, which reads as one
/// cluster rather than as a line of separate buttons.
const CELL_GAP: f32 = 2.0;

/// The accent square inside its tap-sized cell, and its corner.
const SWATCH: f32 = 18.0;
const SWATCH_RADIUS: u8 = 3;

/// The icon beside a menu row's words.
const MENU_ICON: f32 = 18.0;

/// Everything one frame of the overlay resolves against: what the session
/// says the bar holds, and what the shell adds — which picker is up, the
/// room the chrome left, and the gestures over the canvas.
pub struct Overlay<'a> {
    pub commands: &'a mut CommandSet,
    /// The bar's contents, while something is selected.
    pub bar: Option<&'a crate::kernel::Overlay>,
    pub open_picker: Option<OpenPicker>,
    /// The room the floating chrome left, which the bar clamps into.
    pub safe: SafeArea,
    /// Whether the camera is being worked; the bar stands down while it is
    /// and re-places on release.
    pub camera: Camera,
    pub right_click: RightClick,
}

/// The egui id the right-click menu is held open under.
fn menu_id() -> egui::Id {
    egui::Id::from(Panel::SelectionMenu)
}

/// The overlay stands down: no bar, and the menu and the pickers the app
/// anchors to it go with it.
fn dismissed(ctx: &egui::Context) -> (Option<Act>, Option<egui::Pos2>) {
    egui::Popup::close_id(ctx, menu_id());
    (None, None)
}

/// Where this frame's bar goes, or why it goes nowhere.
enum Placed {
    /// Measured, and there is a spot for it.
    At(egui::Pos2),
    /// Measured, and there is nowhere lawful: both bands fall outside the
    /// region, and covering the selection is not an alternative.
    Nowhere,
    /// Not measured yet. This frame lays the bar out to find how wide it is
    /// and paints nothing, so the next one can place it.
    Measuring,
}

/// What the bar measured itself as, and what it was measuring. A selection
/// switch changes the row, and placing the new row with the old row's size
/// flashed it one frame in the wrong place — so the memory says what it is of,
/// and a frame it does not match is a sizing pass instead.
#[derive(Clone)]
struct Measured {
    controls: Vec<CommandId>,
    count: usize,
    rect: egui::Rect,
    /// The pass this was drawn on, so a bar that has since gone does not
    /// keep claiming the spot it stood at.
    pass: u64,
}

/// Where the bar stood last frame, if it was drawn: what a press there is
/// on, however egui's hit test — which sees the bar as part of the canvas's
/// own layer — attributes it.
pub(crate) fn bar_rect(ctx: &egui::Context) -> Option<egui::Rect> {
    let measured =
        ctx.data(|d| d.get_temp::<Measured>(Panel::SelectionButtons.measurement("rect")))?;
    (measured.pass + 1 == ctx.cumulative_pass_nr()).then_some(measured.rect)
}

/// 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())
}

/// The commands scoped to the current selection, drawn beside it as a
/// floating bar: the placement, the stand-down while the camera moves, the
/// overflow, the count, and the right-click duplicate.
///
/// Returns the triggered `Action` and the bar's top-right corner (which the
/// pickers anchor above; `None` when the bar is hidden, which dismisses them).
pub fn selection_overlay(
    ui: &mut egui::Ui,
    overlay: Overlay<'_>,
) -> (Option<Act>, Option<egui::Pos2>) {
    let Overlay {
        commands,
        bar: model,
        open_picker,
        safe,
        camera,
        right_click,
    } = overlay;
    let ctx = ui.ctx().clone();
    let ctx = &ctx;
    let Some(model) = model.filter(|bar| safe.viewport().intersects(bar.selection.screen.egui()))
    else {
        return dismissed(ctx);
    };
    let selection = model.selection;
    let screen = selection.screen.egui();
    // Tracking the object through a pan is a jittering distraction. The
    // measurement is left untouched, so the frame the gesture ends on places
    // the bar again without another sizing pass.
    if camera == Camera::Moving {
        return dismissed(ctx);
    }
    let offered: Vec<&Command> = overlay_controls(commands).collect();
    let drawn: Vec<CommandId> = offered.iter().map(|cmd| cmd.id).collect();
    let count = selection.count;
    let bar = Bar::of(offered, count, |cmd: &&Command| cmd.precedence);

    let size_key = Panel::SelectionButtons.measurement("rect");
    let remembered = ctx
        .data(|d| d.get_temp::<Measured>(size_key))
        .filter(|was| was.controls == drawn && was.count == count)
        .map(|was| was.rect.size());
    let placed = match remembered {
        Some(size) => match bar::place(screen.geom(), size.geom(), safe.region().geom()) {
            Some(bar) => Placed::At(bar.min.egui()),
            None => Placed::Nowhere,
        },
        None => Placed::Measuring,
    };
    let (at, builder) = match placed {
        Placed::At(at) => (at, Panel::SelectionButtons.ui_builder()),
        Placed::Nowhere => return dismissed(ctx),
        // 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.
        Placed::Measuring => {
            ctx.request_repaint();
            (
                screen.center(),
                Panel::SelectionButtons
                    .ui_builder()
                    .sizing_pass()
                    .invisible(),
            )
        }
    };
    let sizing = builder.sizing_pass;
    let controls = Controls { model, open_picker };
    let mut clicked: Option<CommandId> = None;
    let mut child =
        ui.new_child(builder.max_rect(egui::Rect::from_min_size(at, safe.viewport().size())));
    let rect = {
        let ui = &mut child;
        glass::shell(ui, BAR, glass::Elevation::Floating, glass::Tint::None)
            .show(ui, |ui| {
                glass::type_scale(ui, BAR);
                // The bar stands the pill tier's height whatever it holds, so
                // it reads as one of the chip's kin rather than as a taller
                // stranger over the drawing (the user: *"The selection
                // overlay pill should also be smaller in height (same as the
                // top-left pill)"*).
                if let Some(height) = BAR.content_height() {
                    ui.set_min_height(height);
                }
                clicked = draw_row(ui, &bar, count, controls);
            })
            .response
            .rect
    };
    tracing::debug!(
        target: "overlay",
        pass = ctx.cumulative_pass_nr(),
        sizing,
        drawn = drawn.len(),
        at = ?at,
        rect = ?rect,
        sel = ?screen,
        "overlay frame"
    );
    let pass = ctx.cumulative_pass_nr();
    ctx.data_mut(|d| {
        d.insert_temp(
            size_key,
            Measured {
                controls: drawn,
                count,
                rect,
                pass,
            },
        );
    });
    if sizing {
        return (None, None);
    }
    if let Some(id) = right_click_menu(ui, &bar, right_click, controls) {
        clicked = Some(id);
    }
    drop(bar);
    (
        clicked.and_then(|id| commands.take(id)),
        Some(rect.right_top()),
    )
}

/// The bar's contents: the count, the row, and the overflow button.
fn draw_row(
    ui: &mut egui::Ui,
    bar: &Bar<&Command>,
    count: usize,
    controls: Controls<'_>,
) -> Option<CommandId> {
    let mut clicked = None;
    ui.horizontal(|ui| {
        ui.spacing_mut().item_spacing.x = CELL_GAP;
        if count > 1 {
            ui.label(
                egui::RichText::new(format!("{count} selected"))
                    .small()
                    .weak(),
            );
            glass::group_gap(ui);
        }
        if !matches!(bar, Bar::Row(_)) {
            ui.label(
                egui::RichText::new(bar::nothing_to_say(count))
                    .small()
                    .weak(),
            );
            return;
        }
        for cmd in bar.row() {
            if let Some(id) = draw_command(ui, cmd, Shown::InTheBar, controls) {
                clicked = Some(id);
            }
        }
        let overflow = bar.overflow();
        if overflow.is_empty() {
            return;
        }
        let more = glass::tap_button(
            ui,
            MORE_ICON,
            glass::Live::Yes,
            format!("{} more", overflow.len()),
        );
        egui::Popup::menu(&more).show(|ui| {
            for cmd in overflow {
                if let Some(id) = draw_command(ui, cmd, Shown::InAMenu, controls) {
                    clicked = Some(id);
                }
            }
        });
    });
    clicked
}

/// On a pointer platform, right-click opens a menu with **exactly** the
/// overlay's commands. It is handed the same [`Bar`] the row was drawn from,
/// so it cannot carry one command more or one fewer.
fn right_click_menu(
    ui: &mut egui::Ui,
    bar: &Bar<&Command>,
    right_click: RightClick,
    controls: Controls<'_>,
) -> Option<CommandId> {
    let mut clicked = None;
    // Nothing to carry is no menu: a right-click that opened an empty box
    // would be a surface promising commands it does not have.
    let opened = match (right_click, bar.all().first()) {
        (RightClick::Asked, Some(_)) => Some(egui::SetOpenCommand::Bool(true)),
        (RightClick::Asked, None) => Some(egui::SetOpenCommand::Bool(false)),
        (RightClick::No, _) => None,
    };
    egui::Popup::new(
        menu_id(),
        ui.ctx().clone(),
        egui::PopupAnchor::PointerFixed,
        ui.layer_id(),
    )
    .kind(egui::PopupKind::Menu)
    .layout(egui::Layout::top_down_justified(egui::Align::Min))
    .open_memory(opened)
    .show(|ui| {
        for cmd in bar.all() {
            if let Some(id) = draw_command(ui, cmd, Shown::InAMenu, controls) {
                clicked = Some(id);
            }
        }
    });
    clicked
}

/// 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.
pub(crate) fn overlay_controls(commands: &CommandSet) -> impl Iterator<Item = &Command> {
    commands.iter_drawn().filter(|cmd| in_overlay(cmd.id))
}

/// The two ways one command is drawn: as a cell in the bar's row, and as a row
/// in a menu — the overflow's and the right-click's, which are the same menu.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Shown {
    InTheBar,
    InAMenu,
}

/// What a control needs beyond its own command to draw itself: what the
/// session says the bar holds, and which picker is currently up.
#[derive(Clone, Copy)]
struct Controls<'a> {
    model: &'a crate::kernel::Overlay,
    open_picker: Option<OpenPicker>,
}

/// Render `cmd` the way `shown` asks, returning the command a click fired.
/// Only what [`overlay_controls`] yields reaches here. A withheld command is
/// drawn dead rather than dropped, so the bar keeps its shape in a
/// read-only session.
fn draw_command(
    ui: &mut egui::Ui,
    cmd: &Command,
    shown: Shown,
    controls: Controls<'_>,
) -> Option<CommandId> {
    let Controls { model, open_picker } = controls;
    ui.add_enabled_ui(!cmd.withheld(), |ui| match cmd.id {
        CommandId::ExportSelection(_) => {
            let mut picked = None;
            match shown {
                Shown::InTheBar => {
                    let button =
                        glass::tap_button(ui, EXPORT_ICON, glass::Live::Yes, cmd.label.as_ref());
                    egui::Popup::menu(&button).show(|ui| {
                        picked = export_format_menu(ui, ExportScope::Selection);
                    });
                }
                Shown::InAMenu => {
                    ui.menu_button(cmd.label.as_ref(), |ui| {
                        picked = export_format_menu(ui, ExportScope::Selection);
                    });
                }
            }
            picked.map(CommandId::ExportSelection)
        }
        CommandId::Accent => {
            let accent = model.swatch?;
            let opened = glass::Opened::from(open_picker == Some(OpenPicker::Role));
            let response = match shown {
                Shown::InTheBar => accent_swatch(ui, accent.egui(), opened),
                Shown::InAMenu => menu_row(ui, None, &cmd.label, opened),
            };
            (response.clicked() && opened == glass::Opened::No).then_some(cmd.id)
        }
        CommandId::PinType => {
            let opened = glass::Opened::from(open_picker == Some(OpenPicker::PinType));
            let says = pin_dir_hover(model.pin_dir);
            let response = match shown {
                Shown::InTheBar => {
                    glass::tap_button(ui, PIN_TYPE_ICON, glass::Live::Yes, says.clone())
                }
                Shown::InAMenu => menu_row(ui, Some(PIN_TYPE_ICON), &cmd.label, opened),
            };
            (response.clicked() && opened == glass::Opened::No).then_some(cmd.id)
        }
        CommandId::HideTags | CommandId::ShowTags => {
            let icon = tag_icon(cmd.id);
            let response = match shown {
                Shown::InTheBar => {
                    glass::tap_button(ui, icon, glass::Live::Yes, cmd.label.as_ref())
                }
                Shown::InAMenu => menu_row(ui, Some(icon), &cmd.label, glass::Opened::No),
            };
            response.clicked().then_some(cmd.id)
        }
        id => {
            let icon = overlay_icon(id)?;
            let response = match shown {
                Shown::InTheBar => {
                    glass::tap_button(ui, icon, glass::Live::Yes, cmd.label.as_ref())
                }
                Shown::InAMenu => menu_row(ui, Some(icon), &cmd.label, glass::Opened::No),
            };
            response.clicked().then_some(id)
        }
    })
    .inner
}

/// The eye the tag toggle wears, which shows the *state* the way the lock
/// toggle beside it does — an open eye where the tags are showing, a struck
/// one where they are hidden — while the words name the action. The user
/// asked for the paradigm by name: *"Give me some kind of icon for the 'hide
/// tag' 'show tag'. Maybe just a show/hide icon (the usual eye-based
/// paradigm)."*
///
/// The registry offers `HideTags` exactly when the tags are visible, so the
/// command's identity is the state.
fn tag_icon(id: CommandId) -> egui::ImageSource<'static> {
    match id {
        CommandId::ShowTags => EYE_OFF_ICON,
        _ => EYE_ICON,
    }
}

/// The control names itself, and its words name the state.
///
/// The user's own rule: *"For the input/output configuration icon, do not
/// change it based on the current state of the pin. That is confusing. Pick
/// one icon (e.g., the |&lt;- icon) and use it always."* So the button wears
/// [`PIN_TYPE_ICON`] in every state — a control is a place, and a place that
/// changes its face is a new control every time you look — and the direction
/// the pins are facing is told in the tooltip, where a varying thing
/// belongs. A mixed selection has no one direction, and says so.
fn pin_dir_hover(dir: Option<PinDir>) -> String {
    let state = match dir {
        Some(PinDir::Input) => "currently Input",
        Some(PinDir::Output) => "currently Output",
        Some(PinDir::InOut) => "currently Input Output",
        None => "these pins face different ways",
    };
    format!("Direction \u{2014} {state}")
}

/// One row of a menu: the glyph the bar would have shown, and the words its
/// tooltip would have carried. Tap-height like everything else.
fn menu_row(
    ui: &mut egui::Ui,
    icon: Option<egui::ImageSource<'static>>,
    label: &str,
    opened: glass::Opened,
) -> egui::Response {
    let button = match icon {
        Some(icon) => egui::Button::image_and_text(glass::image(ui, icon, MENU_ICON), label),
        None => egui::Button::new(label),
    };
    ui.add(
        button
            .min_size(egui::vec2(0.0, glass::TAP))
            .selected(opened == glass::Opened::Yes),
    )
}

/// The accent control: the selection's current accent as a filled square in a
/// tap-sized cell, opening the role picker on click. While the picker is up the
/// swatch carries an active-indicator ring.
fn accent_swatch(ui: &mut egui::Ui, color: egui::Color32, opened: glass::Opened) -> egui::Response {
    let (cell, resp) = ui.allocate_exact_size(egui::Vec2::splat(glass::TAP), egui::Sense::click());
    let rect = egui::Rect::from_center_size(cell.center(), egui::Vec2::splat(SWATCH));
    let painter = ui.painter();
    painter.rect_filled(rect, SWATCH_RADIUS, color);
    let (width, stroke) = if opened == glass::Opened::Yes {
        (2.0, ui.visuals().selection.stroke.color)
    } else {
        (1.0, ui.visuals().widgets.inactive.fg_stroke.color)
    };
    painter.rect_stroke(
        rect,
        SWATCH_RADIUS,
        egui::Stroke::new(width, stroke),
        egui::StrokeKind::Inside,
    );
    resp.on_hover_text("Accent")
}

/// 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(test)]
mod tests {
    use super::*;
    use crate::kernel::Selection;
    use crate::kernel::chrome::accent_display_role;
    use crate::shape::ShapeId;
    use crate::theme::{Role, Theme};
    use crate::tools::tool::RoleTarget;
    use blockworx_kernel::bar::{CLEAR, INLINE_CONTROLS};
    use blockworx_tools::commands::Precedence;

    use blockworx_store::doc::Writability;

    use crate::{
        tools::{
            commands::{CommandContext, History},
            tool::Tool,
        },
        widget::test_fixtures::{Scene, two_blocks_with_a_routed_waypoint},
    };
    use egui::{Rect, Vec2, pos2, vec2};

    fn viewport() -> Rect {
        Rect::from_min_size(pos2(0.0, 0.0), vec2(1000.0, 800.0))
    }

    /// A bar of a size the placement tests can reason about without drawing it.
    const SIZE: Vec2 = Vec2::new(200.0, 40.0);

    /// The glyph egui puts on a menu row that opens a submenu.
    const SUBMENU_CHEVRON: &str = "\u{23f5}";

    // ---- what the bar shows --------------------------------------------

    /// The order is by what a command *is*: the user named the primaries —
    /// *"For sure the primary actions should be 'Accent, Expand, Icon, Lock,
    /// Rip, flip lr, and flip ud'. The 'copy/cut/delete' can all be put into
    /// the overflow menu, as can the 'export to svg'."* — and a block is the
    /// selection that offers all of them, more than the row holds.
    #[test]
    fn a_blocks_row_is_its_first_five_primaries_and_the_rest_go_behind_the_ellipsis() {
        let all: Vec<CommandId> = Harness::block().laid_out().iter().map(|c| c.0).collect();
        let bar = Bar::of(all.clone(), 1, |id: &CommandId| Precedence::of(*id));
        assert!(
            all.len() > INLINE_CONTROLS,
            "precondition: a block offers more controls than the row holds: {all:?}",
        );
        assert_eq!(
            bar.row().len(),
            INLINE_CONTROLS,
            "the row does not hold its fill: {:?}",
            bar.row(),
        );
        assert_eq!(bar.all().len(), all.len(), "the cut lost a control");
        let lock = if all.contains(&CommandId::Unlock) {
            CommandId::Unlock
        } else {
            CommandId::Lock
        };
        assert_eq!(
            bar.row(),
            [
                CommandId::Accent,
                CommandId::ExpandBlock,
                lock,
                CommandId::AddIcon,
                CommandId::RerouteBlock,
            ],
            "the row is not the user's primaries in the user's order",
        );
        for behind in [
            CommandId::FlipLr,
            CommandId::FlipUd,
            CommandId::Copy,
            CommandId::Cut,
            CommandId::Delete,
        ] {
            assert!(
                bar.overflow().contains(&behind),
                "{behind:?} is not behind the ellipsis: {:?}",
                bar.overflow(),
            );
        }
        assert!(
            bar.overflow()
                .iter()
                .any(|id| matches!(id, CommandId::ExportSelection(_))),
            "the selection export is not behind the ellipsis: {:?}",
            bar.overflow(),
        );

        // The order keeps the registry's within each rank.
        for rank in [Precedence::Own, Precedence::Clerical] {
            let in_registry_order: Vec<CommandId> = all
                .iter()
                .copied()
                .filter(|&id| Precedence::of(id) == rank)
                .collect();
            let in_bar_order: Vec<CommandId> = bar
                .all()
                .iter()
                .copied()
                .filter(|&id| Precedence::of(id) == rank)
                .collect();
            assert_eq!(
                in_bar_order, in_registry_order,
                "{rank:?} came out reordered"
            );
        }
    }

    /// Item 27, which is item 22 asked of one more type: *"The selection
    /// overlay for the port should also put the copy/cut/delete stuff behind
    /// the extension, and use the toolbar for the other controls."* A port's
    /// own verbs — its I/O direction, its tag, its accent, its flip — lead
    /// the row, and the clerical ones follow them, exactly as a block's do,
    /// because precedence lives on the command rather than on the type that
    /// offered it.
    #[test]
    fn a_ports_own_controls_lead_the_row_and_its_clerical_verbs_follow() {
        let mut port = Harness::port();
        let ids: Vec<CommandId> = port.laid_out().iter().map(|c| c.0).collect();
        let bar = Bar::of(ids.clone(), 1, |id: &CommandId| Precedence::of(*id));
        assert!(matches!(bar, Bar::Row(_)), "a port raises no row: {ids:?}");
        let own = [CommandId::PinType, CommandId::Accent, CommandId::FlipLr];
        for id in own {
            assert!(
                bar.row().contains(&id),
                "the port's own {id:?} is not in the row: {:?} / {:?}",
                bar.row(),
                bar.overflow(),
            );
        }
        assert!(
            bar.row()
                .iter()
                .any(|id| matches!(id, CommandId::HideTags | CommandId::ShowTags)),
            "the port's tag toggle is not in the row: {:?}",
            bar.row(),
        );
        assert!(
            bar.overflow().contains(&CommandId::Delete),
            "precondition: the port offers more than the row holds, so Delete is behind: {:?}",
            bar.all(),
        );
    }

    /// Item 26's glyphs, and which way round they read. The eye shows the
    /// *state* — the same way the padlock beside it does — so a control
    /// offering "Hide Tags" is one whose tags are currently open. The I/O
    /// control does the opposite, on the user's own second thoughts (item
    /// 14): one glyph always, and the state in words.
    #[test]
    fn the_tag_eye_shows_the_state_and_the_io_control_keeps_one_glyph() {
        let source = |icon: egui::ImageSource<'static>| match icon {
            egui::ImageSource::Bytes { uri, .. } => uri.to_string(),
            _ => panic!("the overlay's icons are embedded bytes"),
        };
        assert!(source(tag_icon(CommandId::HideTags)).contains("icon-eye.svg"));
        assert!(source(tag_icon(CommandId::ShowTags)).contains("icon-eye-off.svg"));
        assert_ne!(
            source(tag_icon(CommandId::HideTags)),
            source(tag_icon(CommandId::ShowTags)),
            "the two states share one glyph",
        );

        // Item 14 reverses item 26's other half: the I/O control keeps one
        // glyph in every state — *"do not change it based on the current
        // state of the pin. That is confusing."* — and says the state in
        // words instead.
        assert!(source(PIN_TYPE_ICON).contains("icon-pin-input.svg"));
        let said: Vec<String> = [
            Some(PinDir::Input),
            Some(PinDir::Output),
            Some(PinDir::InOut),
            None,
        ]
        .into_iter()
        .map(pin_dir_hover)
        .collect();
        assert_eq!(
            said.iter().collect::<std::collections::HashSet<_>>().len(),
            said.len(),
            "two states of the control say the same thing: {said:?}",
        );
        for word in &said {
            assert!(
                word.starts_with("Direction"),
                "the control does not name itself: {word}",
            );
        }
        assert!(
            said[1].contains("Output") && said[3].contains("different"),
            "the words do not name the state: {said:?}",
        );
    }

    /// The user's own sketch, checked against the paths: an arrow arriving at
    /// a wall on the left is an input, one leaving for a wall on the right is
    /// an output, and the two are mirror images rather than the same drawing
    /// twice.
    #[test]
    fn the_io_icons_put_the_wall_on_opposite_sides() {
        let input = include_str!("../../icons/icon-pin-input.svg");
        let output = include_str!("../../icons/icon-pin-output.svg");
        assert!(input.contains(r#"d="M5 4v16""#), "{input}");
        assert!(output.contains(r#"d="M19 4v16""#), "{output}");
        assert_ne!(input, output, "the two directions share one drawing");
        let eye = include_str!("../../icons/icon-eye.svg");
        let eye_off = include_str!("../../icons/icon-eye-off.svg");
        assert!(
            eye_off.contains(r#"d="M4 20L20 4""#) && !eye.contains(r#"d="M4 20L20 4""#),
            "only the hidden state carries the slash",
        );
    }

    /// Precedence is orthogonal to applicability: a route, a block and an
    /// area share the clerical verbs and put every one of them after their
    /// own verbs, though almost nothing else about their lists is the same.
    #[test]
    fn every_selection_type_puts_its_clerical_verbs_after_its_own() {
        for (what, harness) in [
            ("a block", Harness::block()),
            ("a wire", Harness::wire()),
            ("an area", Harness::area()),
        ] {
            let mut harness = harness;
            let ids: Vec<CommandId> = harness.laid_out().iter().map(|c| c.0).collect();
            let bar = Bar::of(ids.clone(), 1, |id: &CommandId| Precedence::of(*id));
            let ranks: Vec<Precedence> = bar.all().iter().map(|&id| Precedence::of(id)).collect();
            assert!(
                ranks.contains(&Precedence::Own) && ranks.contains(&Precedence::Clerical),
                "precondition: {what} offers verbs of both ranks: {ids:?}",
            );
            assert!(
                ranks.is_sorted(),
                "{what} puts a clerical verb before one of its own: {:?}",
                bar.all(),
            );
            assert!(
                bar.all().contains(&CommandId::Delete),
                "{what} lost Delete altogether: {ids:?}",
            );
        }
    }

    /// Selecting an area raises a bar. Areas answer to fewer verbs than
    /// blocks, but "fewer" is not "none" — the registry gives one an
    /// accent, a copy, a cut and a delete.
    #[test]
    fn an_area_selection_raises_a_bar_with_its_own_commands() {
        let mut area = Harness::area();
        let drawn: Vec<CommandId> = area.laid_out().into_iter().map(|(id, _)| id).collect();
        assert!(
            !drawn.is_empty(),
            "an area selection drew no controls at all",
        );
        for wanted in [
            CommandId::Accent,
            CommandId::Copy,
            CommandId::Cut,
            CommandId::Delete,
        ] {
            assert!(
                drawn.contains(&wanted),
                "the area's bar is missing {wanted:?}: {drawn:?}",
            );
        }
        assert!(
            area.corner.is_some(),
            "the area's bar laid out no controls on screen",
        );
        assert!(area.painted > 0, "the area's bar painted nothing");
    }

    /// An area is the one selection routinely *bigger* than the room around
    /// it: both outside candidates fall clear of the region, and the band
    /// just inside its own leading edge is what keeps a bar on screen.
    #[test]
    fn a_selection_taller_than_the_region_still_gets_a_bar() {
        let mut area = Harness::area();
        let region = area.safe.region();
        // An area drawn around the whole drawing: taller than the canvas has
        // room for a bar above or below it.
        area.selection.screen = Rect::from_min_max(
            pos2(region.center().x - 200.0, region.top() - 40.0),
            pos2(region.center().x + 200.0, region.bottom() + 40.0),
        )
        .geom();
        let screen = area.selection.screen.egui();
        assert!(
            screen.top() - CLEAR - SIZE.y < region.top()
                && screen.bottom() + CLEAR + SIZE.y > region.bottom(),
            "precondition: neither band outside the selection fits the region",
        );
        let placed = bar::place(screen.geom(), SIZE.geom(), region.geom())
            .expect("a selection bigger than its room still has somewhere lawful")
            .egui();
        assert!(
            region.contains_rect(placed),
            "the bar landed outside the region at {placed:?}",
        );

        let settled = settled(area);
        assert!(
            settled.corner.is_some() && settled.painted > 0,
            "the oversized area's bar never drew",
        );
    }

    /// The cut is by count: a list the row can hold is all row, and one
    /// control more puts exactly that one behind the ellipsis.
    #[test]
    fn the_row_holds_five_and_only_the_sixth_goes_behind_the_ellipsis() {
        let own = [
            CommandId::Accent,
            CommandId::ExpandBlock,
            CommandId::Lock,
            CommandId::AddIcon,
            CommandId::RerouteBlock,
        ];
        assert_eq!(
            own.len(),
            INLINE_CONTROLS,
            "precondition: the list is exactly the row's fill",
        );
        let full = Bar::of(own.to_vec(), 1, |id: &CommandId| Precedence::of(*id));
        assert_eq!(full.row(), own, "a full row lost a control");
        assert!(
            full.overflow().is_empty(),
            "five controls raised an ellipsis: {:?}",
            full.overflow(),
        );

        let six: Vec<CommandId> = own.iter().copied().chain([CommandId::Delete]).collect();
        assert_eq!(
            six.len(),
            INLINE_CONTROLS + 1,
            "precondition: one control more"
        );
        let spilled = Bar::of(six, 1, |id: &CommandId| Precedence::of(*id));
        assert_eq!(
            spilled.row(),
            own,
            "the sixth control took a place in the row"
        );
        assert_eq!(spilled.overflow(), [CommandId::Delete]);
    }

    #[test]
    fn a_multi_selection_sharing_nothing_says_so_rather_than_showing_an_empty_bar() {
        assert!(matches!(
            Bar::of(Vec::<CommandId>::new(), 3, |id: &CommandId| Precedence::of(
                *id
            )),
            Bar::NothingShared
        ));
        assert!(matches!(
            Bar::of(Vec::<CommandId>::new(), 1, |id: &CommandId| Precedence::of(
                *id
            )),
            Bar::Nothing
        ));
    }

    /// The count prefix, through a real frame. No blockworx multi-selection
    /// has an empty intersection today — every command it offers is a verb
    /// over the whole set — so the sentence above is proven at the split and
    /// the count is proven here.
    #[test]
    fn a_multi_selection_wears_its_count_and_a_single_one_does_not() {
        let mut chrome = crate::panels::painted::Chrome::new(viewport().geom());
        let mut many = Harness::two_blocks();
        chrome.settle(|ui| many.show(ui));
        assert!(
            many.corner.is_some(),
            "precondition: the bar drew for a two-block selection",
        );
        assert!(
            chrome.shows("2 selected"),
            "the multi-selection lost its count: {:?}",
            chrome.texts(),
        );
        let mut one = Harness::block();
        chrome.settle(|ui| one.show(ui));
        assert!(
            !chrome.texts().iter().any(|said| said.contains("selected")),
            "one block was counted: {:?}",
            chrome.texts(),
        );
    }

    // ---- right-click ---------------------------------------------------

    /// The right-click menu carries exactly the overlay's commands — the
    /// same list, so it can be neither longer (a command invisible on
    /// iPadOS) nor shorter. Read out of the menu's own area, so what the
    /// bar painted beside it cannot pad the answer.
    #[test]
    fn right_click_offers_exactly_the_overlays_commands() {
        let mut chrome = crate::panels::painted::Chrome::new(viewport().geom());
        let mut block = Harness::block();
        chrome.settle(|ui| block.show(ui));
        let laid = block.laid_out();
        let expected: Vec<&str> = laid.iter().map(|c| c.1.as_ref()).collect();
        assert!(
            expected.len() > 5,
            "precondition: some of these are only reachable through a menu",
        );
        chrome.hover_at(blockworx_geom::pos2(120.0, 700.0), |ui| block.show(ui));
        block.right_click = RightClick::Asked;
        chrome.frame(|ui| block.show(ui));
        block.right_click = RightClick::No;
        chrome.settle(|ui| block.show(ui));

        let menu = egui::AreaState::load(chrome.ctx(), menu_id())
            .map(|state| state.rect())
            .filter(|rect| rect.is_positive())
            .expect("the right-click menu never opened");
        // egui draws its own chevron beside a row that opens a submenu; it is
        // decoration, not a command.
        let mut rows: Vec<&str> = chrome
            .texts_inside(menu.geom())
            .into_iter()
            .filter(|run| *run != SUBMENU_CHEVRON)
            .collect();
        let mut wanted = expected.clone();
        rows.sort_unstable();
        wanted.sort_unstable();
        assert_eq!(
            rows, wanted,
            "the menu and the bar disagree about what applies here",
        );
    }

    // ---- camera ---------------------------------------------------------

    /// The bar stands down while the camera is worked and comes back where it
    /// was on release — without a sizing pass, because the measurement it
    /// left behind still describes the same controls.
    #[test]
    fn the_bar_stands_down_while_the_camera_moves() {
        let ctx = egui::Context::default();
        egui_extras::install_image_loaders(&ctx);
        let mut wire = Harness::wire();
        run(&mut wire, &ctx, 2);
        let placed = wire.corner.expect("the bar shows once it has measured");

        wire.camera = Camera::Moving;
        let painted = run(&mut wire, &ctx, 1);
        assert!(wire.corner.is_none(), "the bar tracked the pan");
        assert_eq!(painted, 0, "a hidden bar painted {painted} shape(s)");

        wire.camera = Camera::Settled;
        run(&mut wire, &ctx, 1);
        assert_eq!(
            wire.corner,
            Some(placed),
            "the bar took a sizing pass to come back, or came back elsewhere",
        );
    }

    // ---- the measuring pass and the bar's width -------------------------

    /// 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() {
        let ctx = egui::Context::default();
        egui_extras::install_image_loaders(&ctx);
        let mut wire = Harness::wire();
        let mut block = Harness::block();

        let painted = run(&mut wire, &ctx, 1);
        assert!(
            wire.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 painted = run(&mut wire, &ctx, 1);
        let wire_bar = wire.corner.expect("the wire's bar shows once measured");
        assert!(painted > 0, "a shown bar paints");
        run(&mut wire, &ctx, 1);
        assert!(
            wire.corner.is_some(),
            "an unchanged selection must not flicker"
        );

        let painted = run(&mut block, &ctx, 1);
        assert!(
            block.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)");
        run(&mut block, &ctx, 1);
        let block_bar = block.corner.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",
        );

        run(&mut wire, &ctx, 1);
        assert!(
            wire.corner.is_none(),
            "switching back re-measures too — the memory holds one bar, not a history",
        );
        run(&mut wire, &ctx, 1);
        assert_eq!(
            wire.corner,
            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". 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 writable = settled(Harness::wire());
        assert!(
            writable.invocable > 0 && writable.corner.is_some(),
            "a writable wire lost its overlay",
        );
        assert_eq!(writable.invocable, writable.drawn.len());
        let mut read_only = Harness::wire();
        read_only.writability = Writability::ReadOnly;
        let read_only = settled(read_only);
        assert!(
            read_only.corner.is_some(),
            "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 = settled(Harness::wire());
        let mut read_only = Harness::wire();
        read_only.writability = Writability::ReadOnly;
        let read_only = settled(read_only);
        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 action 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() {
        let quiet = settled(Harness::wire());
        let mut busy = Harness::wire();
        busy.history = History::doc();
        let busy = settled(busy);
        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",
        );
    }

    // ---- the artwork and the accent swatch ------------------------------

    #[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 status strip's breadcrumb (playbook R4), 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());
    }

    /// Entering a scope and rising out of one are a pair, after phosphor's
    /// arrow-square-in / arrow-square-out, which the user named: *"the
    /// 'arrow-square-in' and 'arrow-square-out' icons are better
    /// representatives."* One box with a gap at its corner, one arrow through
    /// the gap, arriving or leaving. Guards the artwork, not the file names.
    #[test]
    fn the_hierarchy_icons_share_a_box_and_oppose_their_arrows() {
        let enter = include_str!("../../icons/icon-expand.svg");
        let rise = include_str!("../../icons/icon-level-up.svg");
        let box_path = r#"d="M10 5H5v14h14v-5""#;
        let shaft = r#"d="M20 4l-9 9""#;
        for icon in [enter, rise] {
            assert!(icon.contains(box_path), "{icon}");
            assert!(icon.contains(shaft), "{icon}");
        }
        // The head sits at the inner end of the shaft coming in, and at the
        // outer end of the one going out.
        assert!(enter.contains(r#"d="M11 7v6h6""#), "{enter}");
        assert!(rise.contains(r#"d="M14 4h6v6""#), "{rise}");
    }

    #[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}");
    }

    /// The overflow glyph is not the document menu's. Two surfaces wearing
    /// one icon is two meanings for one mark.
    #[test]
    fn the_overflow_glyph_is_an_ellipsis_of_its_own() {
        let more = include_str!("../../icons/icon-more.svg");
        assert!(
            MORE_ICON
                .uri()
                .is_some_and(|uri| uri.ends_with("icon-more.svg")),
            "the overflow button borrowed another surface's glyph: {:?}",
            MORE_ICON.uri(),
        );
        assert_eq!(more.matches("<circle").count(), 3);
        assert!(more.contains(r#"viewBox="0 0 24 24""#), "{more}");
        assert!(more.contains(r#"stroke-width="2""#), "{more}");
    }

    // ---- the harness -----------------------------------------------------

    /// One selection under test, and the frame conditions that vary: what is
    /// selected, where it sits, whether the camera is moving, whether the
    /// session may write.
    struct Harness {
        scene: Scene,
        tool: Tool,
        selection: Selection,
        camera: Camera,
        right_click: RightClick,
        writability: Writability,
        history: History,
        safe: SafeArea,
        /// What the last [`Self::show`] laid out — every control, withheld
        /// ones included — and the words each carries.
        drawn: Vec<(CommandId, std::borrow::Cow<'static, str>)>,
        /// How many of them a click could actually fire.
        invocable: usize,
        /// Where the last [`Self::show`] put the bar's top-right corner, or
        /// `None` while it is hidden.
        corner: Option<egui::Pos2>,
        /// Shapes the last [`Self::show`] painted. The overlay is all this
        /// harness draws, so a hidden frame must paint none.
        painted: usize,
        /// The bar the overlay measured itself as, once it has.
        bar: Rect,
        /// Everything a click fired.
        fired: Vec<Act>,
    }

    impl Harness {
        fn over(scene: Scene, tool: Tool, count: usize) -> Self {
            Harness {
                scene,
                tool,
                selection: Selection {
                    screen: Rect::from_min_size(pos2(400.0, 400.0), vec2(120.0, 90.0)).geom(),
                    count,
                },
                camera: Camera::Settled,
                right_click: RightClick::No,
                writability: Writability::Writable,
                history: History::empty(),
                safe: SafeArea::over(viewport()),
                drawn: Vec::new(),
                invocable: 0,
                corner: None,
                painted: 0,
                bar: Rect::NOTHING,
                fired: Vec::new(),
            }
        }

        /// The fixture's one wire, selected.
        fn wire() -> Self {
            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::EditRoute::Selected {
                id: route,
                anchor: pos2(0.0, 0.0).geom(),
            }
            .into();
            Harness::over(scene, tool, 1)
        }

        /// One block, which is the selection with the most commands.
        fn block() -> Self {
            let mut scene = two_blocks_with_a_routed_waypoint();
            let shape = ShapeId::Rect(blockworx_doc::fixtures::block_id(1));
            assert!(
                scene.drawing().shape(shape).is_some(),
                "precondition: the fixture holds the block this selects",
            );
            let tool = crate::tools::resize_block::ResizeBlock::Selected { shape }.into();
            Harness::over(scene, tool, 1)
        }

        /// One area, selected the way a click on its border leaves it.
        fn area() -> Self {
            let mut scene = Scene::new(vec![crate::widget::test_fixtures::area(
                9,
                crate::path::Scope::Root,
                blockworx_geom::Rect::from_min_size(
                    blockworx_geom::pos2(0.0, 0.0),
                    blockworx_geom::vec2(200.0, 140.0),
                ),
            )]);
            let shape = ShapeId::Area(blockworx_doc::fixtures::area_id(9));
            assert!(
                scene.drawing().shape(shape).is_some(),
                "precondition: the fixture holds the area this selects",
            );
            let tool = crate::tools::resize_block::ResizeBlock::Selected { shape }.into();
            Harness::over(scene, tool, 1)
        }

        /// One port of the current level, selected — the case item 27 is
        /// about.
        fn port() -> Self {
            let body = Rect::from_min_size(pos2(0.0, 0.0), vec2(60.0, 60.0));
            let mut scene = Scene::new(vec![crate::widget::test_fixtures::pin_at(
                7,
                crate::path::Scope::Root,
                "clk",
                crate::widget::test_fixtures::slot(crate::shape::pin::PinSide::West, 0),
                body.geom(),
            )]);
            let shape = ShapeId::Port(blockworx_doc::fixtures::pin_id(7));
            assert!(
                scene.drawing().shape(shape).is_some(),
                "precondition: the fixture holds the port this selects",
            );
            let tool = crate::tools::resize_block::ResizeBlock::Selected { shape }.into();
            Harness::over(scene, tool, 1)
        }

        /// Both of the fixture's blocks, as a marquee leaves them.
        fn two_blocks() -> Self {
            let mut scene = two_blocks_with_a_routed_waypoint();
            let shapes: Vec<ShapeId> = [1, 2]
                .map(|n| ShapeId::Rect(blockworx_doc::fixtures::block_id(n)))
                .into();
            assert!(
                shapes.iter().all(|&id| scene.drawing().shape(id).is_some()),
                "precondition: the fixture holds both blocks",
            );
            let count = shapes.len();
            let tool = crate::tools::MultiSelect::Selected { shapes }.into();
            Harness::over(scene, tool, count)
        }

        /// One real frame of the overlay, and nothing else, into `ui`.
        fn show(&mut self, ui: &mut egui::Ui) {
            let drawing = self.scene.drawing();
            let mut commands = CommandSet::available(&CommandContext {
                tool: &self.tool,
                data: &drawing,
                history: self.history,
                current_lock: InterfaceLock::Unlocked,
                writability: self.writability,
                saving: blockworx_store::doc::Saving::Withheld,
                viewing: blockworx_store::doc::Viewing::Head,
            });
            self.drawn = overlay_controls(&commands)
                .map(|cmd| (cmd.id, cmd.label.clone()))
                .collect();
            self.invocable = commands.iter().filter(|cmd| in_overlay(cmd.id)).count();
            let theme = Theme::default();
            let model = crate::kernel::Overlay::of(&drawing, &theme, self.selection, &commands);
            let (action, corner) = selection_overlay(
                ui,
                Overlay {
                    commands: &mut commands,
                    bar: Some(&model),
                    open_picker: None,
                    safe: self.safe,
                    camera: self.camera,
                    right_click: self.right_click,
                },
            );
            if let Some(fired) = action {
                self.fired.push(fired);
            }
            self.corner = corner;
        }

        /// The controls this selection lays out, once one frame has resolved
        /// them.
        fn laid_out(&mut self) -> Vec<(CommandId, std::borrow::Cow<'static, str>)> {
            let ctx = egui::Context::default();
            egui_extras::install_image_loaders(&ctx);
            run(self, &ctx, 2);
            self.drawn.clone()
        }
    }

    /// `frames` real frames on `ctx`, leaving the harness holding what the
    /// last of them did. Returns how many shapes it painted.
    fn run(harness: &mut Harness, ctx: &egui::Context, frames: usize) -> usize {
        for _ in 0..frames {
            let mut out = ctx.clone().run_ui(
                egui::RawInput {
                    screen_rect: Some(harness.safe.viewport()),
                    ..Default::default()
                },
                |ui| harness.show(ui),
            );
            out.textures_delta.clear();
            harness.painted = painted(&out.shapes);
        }
        harness.bar = ctx
            .data(|d| d.get_temp::<Measured>(Panel::SelectionButtons.measurement("rect")))
            .map_or(Rect::NOTHING, |was| was.rect);
        harness.painted
    }

    /// A harness driven to rest on a context of its own — for the tests that
    /// ask what the bar came to rather than how it got there.
    fn settled(mut harness: Harness) -> Harness {
        let ctx = egui::Context::default();
        egui_extras::install_image_loaders(&ctx);
        run(&mut harness, &ctx, 2);
        harness
    }

    /// 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()
    }
}